Version.h

[詳解]

/// @file
/// @brief バージョン値構造体 Version のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_VERSION_H
#define AMDAEMON_VERSION_H

#include "amdaemon/env.h"

#include <string>
#include <cstdint>

namespace amdaemon
{
    //--------------------
    // Version 構造体定義
    //--------------------

    /// @brief バージョン値構造体。
    /// @note memcpy 可能。
    /// @ingroup g_appimage g_netdelivery
    /// @internal ライブラリ実装メモ: この型を直接共有メモリに配置する。
    struct Version
    {
        /// 内部値の表現型。
        typedef std::uint32_t value_type;

        /// パッチバージョン値の最大許容値。
        static const value_type PatchLimit = (1 << 8) - 1;

        /// マイナーバージョン値の最大許容値。
        static const value_type MinorLimit = PatchLimit;

        /// メジャーバージョン値の最大許容値。
        static const value_type MajorLimit =
            UINT32_MAX / ((MinorLimit + 1) * (PatchLimit + 1));

        /// 内部値。 libam のアプリバージョン値と同等のフォーマット。
        value_type value;

        /// @brief バージョン値を作成可能な各バージョン値であるか否かを調べる。
        /// @param[in] major メジャーバージョン値。 MajorLimit 以下。
        /// @param[in] minor マイナーバージョン値。 MinorLimit 以下。
        /// @param[in] patch パッチバージョン値。 PatchLimit 以下。
        /// @retval true  作成可能である場合。
        /// @retval false 作成不可能である場合。
        /// @see make(value_type, value_type, value_type)
        ///
        /// この関数が true を返す場合、同じ引数を静的メンバ関数 make に渡すことで
        /// 例外を発生させることなくバージョン値を作成可能であることが保証される。
        static bool canMake(value_type major, value_type minor, value_type patch = 0);

        /// @brief 各バージョン値からバージョン値を作成する。
        /// @param[in] major メジャーバージョン値。 MajorLimit 以下。
        /// @param[in] minor マイナーバージョン値。 MinorLimit 以下。
        /// @param[in] patch パッチバージョン値。 PatchLimit 以下。
        /// @return バージョン値。
        /// @see canMake(value_type, value_type, value_type)
        ///
        /// @exception Exception
        /// - 引数 major に MajorLimit より大きい値を指定した場合。
        /// - 引数 minor に MinorLimit より大きい値を指定した場合。
        /// - 引数 patch に PatchLimit より大きい値を指定した場合。
        static Version make(value_type major, value_type minor, value_type patch = 0);

        /// @brief バージョン値を作成可能なバージョン文字列であるか否かを調べる。
        /// @param[in] src バージョン文字列。 "1.23.45", "6.78" 等。
        /// @retval true  作成可能である場合。
        /// @retval false 作成不可能である場合。
        /// @see make(const wchar_t*)
        ///
        /// この関数が true を返す場合、同じ引数を静的メンバ関数 make に渡すことで
        /// 例外を発生させることなくバージョン値を作成可能であることが保証される。
        static bool canMake(const wchar_t* src);

        /// @brief バージョン文字列からバージョン値を作成する。
        /// @param[in] src バージョン文字列。 "1.23.45", "6.78" 等。
        /// @return バージョン値。
        /// @see canMake(const wchar_t*)
        ///
        /// @exception Exception
        /// - 引数 src に nullptr を指定した場合。
        /// - 引数 src のフォーマットが不正である場合。
        /// - 引数 src の構成数値が許容範囲外である場合。
        ///
        /// - メジャーバージョン値、マイナーバージョン値、パッチバージョン値を表す
        ///   10進数文字列を文字 '.' で連結した文字列からバージョン値を作成する。
        /// - パッチバージョン値は省略可能であり、その場合は 0 が指定されたものとみなす。
        static Version make(const wchar_t* src);

        /// @brief "0.00.00" のバージョン値を作成する。
        /// @return "0.00.00" のバージョン値。
        static Version zero()
        {
            Version result = { };
            return result;
        }

        /// @brief メジャーバージョン値を取得する。
        /// @return メジャーバージョン値。
        value_type major() const
        {
            return (value / ((MinorLimit + 1) * (PatchLimit + 1)));
        }

        /// @brief マイナーバージョン値を取得する。
        /// @return マイナーバージョン値。
        value_type minor() const
        {
            return (value / (PatchLimit + 1) % (MinorLimit + 1));
        }

        /// @brief パッチバージョン値を取得する。
        /// @return パッチバージョン値。
        value_type patch() const
        {
            return (value % (PatchLimit + 1));
        }

        /// @brief バージョン値を文字列化する。
        /// @param[in] withoutPatch パッチバージョンを含めないならば true 。
        /// @return バージョン文字列。 "1.02.03" 等。
        std::wstring toString(bool withoutPatch = false) const;
    };

    //--------------------
    // インライン関数定義
    //--------------------

    /// @brief 等価比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso Version
    inline bool operator==(const Version& l, const Version& r)
    {
        return (l.value == r.value);
    }

    /// @brief 非等価比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso Version
    inline bool operator!=(const Version& l, const Version& r)
    {
        return !(l == r);
    }

    /// @brief 小なり比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso Version
    inline bool operator<(const Version& l, const Version& r)
    {
        return (l.value < r.value);
    }

    /// @brief 大なり比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso Version
    inline bool operator>(const Version& l, const Version& r)
    {
        return (r < l);
    }

    /// @brief 小なり等価比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso Version
    inline bool operator<=(const Version& l, const Version& r)
    {
        return !(r < l);
    }

    /// @brief 大なり等価比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso Version
    inline bool operator>=(const Version& l, const Version& r)
    {
        return !(l < r);
    }
} // namespace amdaemon

namespace std
{
    // 前方宣言
    template<class T> struct hash;

    /// @brief ハッシュ値を求めるファンクタ構造体。
    ///
    /// std::hash クラステンプレートの amdaemon::Version 構造体に対する特殊化。
    template<>
    struct hash< ::amdaemon::Version >
    {
        /// 戻り値の型。
        typedef size_t result_type;

        /// 引数の型。
        typedef ::amdaemon::Version argument_type;

        /// @brief 引数のハッシュ値を取得する。
        /// @param[in] version 引数。
        /// @return ハッシュ値。
        result_type operator()(argument_type version) const
        {
            return static_cast<result_type>(version.value);
        }
    };
} // namespace std

#endif // AMDAEMON_VERSION_H