AccessCode.h

[詳解]

/// @file
/// @brief アクセスコード値構造体 AccessCode のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_ACCESSCODE_H
#define AMDAEMON_ACCESSCODE_H

#include "amdaemon/env.h"
#include "amdaemon/util/StaticAssert.h"

#include <string>
#include <cstdint>
#include <cstddef>
#include <cstring>

namespace amdaemon
{
/// @addtogroup g_aime
/// @{

    //--------------------
    // AccessCode 構造体定義
    //--------------------

    /// @brief アクセスコード値構造体。
    /// @note memcpy 可能。
    ///
    /// AiMeLibの AiMeDef::AccessCode 構造体とバイナリ互換である。
    ///
    /// @internal ライブラリ実装メモ: この型を直接共有メモリに配置する。
    struct AccessCode
    {
        /// 桁数。
        static const std::size_t DigitCount = 20;

        /// BCD形式データサイズ。
        static const std::size_t Size = (DigitCount + 1) / 2;

        /// 内部値。4ビットごとに1桁を表すBCD形式データ。AiMeLib互換。
        std::uint8_t values[Size];

        /// @brief すべての桁が 0 であるアクセスコード値を取得する。
        /// @return すべての桁が 0 であるアクセスコード値。
        static const AccessCode& zero();

        /// @brief アクセスコード値を作成可能なBCD形式データであるか否かを調べる。
        /// @param[in] values BCD形式データ。AiMeLib互換。
        /// @retval true  作成可能である場合。
        /// @retval false 作成不可能である場合。
        /// @see make(const std::uint8_t (&)[Size])
        ///
        /// この関数が true を返す場合、同じ引数を静的メンバ関数
        /// make(const std::uint8_t (&)[Size]) に渡すことで、
        /// 例外を発生させることなくアクセスコード値を作成可能であることが保証される。
        static bool canMake(const std::uint8_t (&values)[Size]);

        /// @brief BCD形式データからアクセスコード値を作成する。
        /// @param[in] values BCD形式データ。AiMeLib互換。
        /// @return 作成されたアクセスコード値。
        /// @see canMake(const std::uint8_t (&)[Size])
        ///
        /// @exception Exception
        /// 引数 values に不正な値を指定した場合。
        static AccessCode make(const std::uint8_t (&values)[Size]);

        /// @brief アクセスコード値を作成可能なアクセスコード文字列であるか否かを調べる。
        /// @param[in] src アクセスコード文字列。 "01031234567812345678" 等。
        /// @param[in] separator
        ///     セパレータとして認識する文字列。既定の処理を行わせるならば nullptr 。
        /// @retval true  作成可能である場合。
        /// @retval false 作成不可能である場合。
        /// @see make(const wchar_t*, const wchar_t*)
        ///
        /// この関数が true を返す場合、同じ引数を静的メンバ関数
        /// make(const wchar_t*, const wchar_t*) に渡すことで、
        /// 例外を発生させることなくアクセスコード値を作成可能であることが保証される。
        static bool canMake(const wchar_t* src, const wchar_t* separator = nullptr);

        /// @brief アクセスコード文字列からアクセスコード値を作成する。
        /// @param[in] src アクセスコード文字列。 "01031234567812345678" 等。
        /// @param[in] separator
        ///     セパレータとして認識する文字列。既定の処理を行わせるならば nullptr 。
        /// @return 作成されたアクセスコード値。
        ///
        /// @exception Exception
        /// - 引数 src に nullptr を指定した場合。
        /// - 引数 src に無効な文字が含まれる場合。
        /// - 引数 src 内の数字個数が #DigitCount と等しくない場合。
        ///
        /// 引数 src 内の文字 '0' 〜 '9' を用いてアクセスコード値を作成する。
        ///
        /// 引数 separator の扱いは次の通り。
        ///
        /// - separator が既定値 nullptr である場合、半角スペースおよびタブ文字を無視する。
        ///   先頭および末尾にある場合や、連続している場合も無視される。
        /// - separator が空文字列である場合、数字以外のあらゆる文字は無効となる。
        /// - separator が nullptr 以外かつ空文字列以外である場合、
        ///   指定された文字列をセパレータとして認識する。
        ///   - 先頭および末尾に現れてはならない。
        ///   - 連続していてはならない。
        ///   - 上記要件を満たしていればセパレータの位置および個数は任意。
        ///   - セパレータ文字列に数字が含まれていてもセパレータの判定が優先される。
        static AccessCode make(const wchar_t* src, const wchar_t* separator = nullptr);

        /// @brief 無効なアクセスコード値を作成する。
        /// @return 無効なアクセスコード値。
        static AccessCode makeInvalid();

        /// @brief 有効なアクセスコードであるか否かを取得する。
        /// @retval true  有効なアクセスコードである場合。
        /// @retval false 無効なアクセスコードである場合。
        bool valid() const;

        /// @brief 指定した桁位置の数値を取得する。
        /// @param[in] digitIndex 桁位置。先頭が 0 。 0 以上 #DigitCount 未満。
        /// @return 数値。有効なアクセスコードならば 0 以上 9 以下。
        ///
        /// @exception
        /// 引数 digitIndex に #DigitCount 以上の値を指定した場合。
        ///
        /// 無効なアクセスコードであっても構わず算出する。
        /// そのため無効なアクセスコードでは範囲外の値が返る場合がある。
        int getDigit(std::size_t digitIndex) const;

        /// @brief 文字列表現値を作成する。
        /// @param[in] separator 4桁ごとのセパレータ文字列。区切らないならば nullptr 。
        /// @return 文字列表現値。
        ///
        /// 無効なアクセスコードであっても構わず文字列を作成する。
        /// その際、無効な桁は16進数文字('A' 〜 'F')となる。
        std::wstring toString(const wchar_t* separator = nullptr) const;
    };

/// @}

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

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

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

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

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

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

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

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

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

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

        /// @brief 引数のハッシュ値を取得する。
        /// @param[in] accessCode 引数。
        /// @return ハッシュ値。
        result_type operator()(const argument_type& accessCode) const
        {
            // 先頭から sizeof(result_type) バイトを用いる
            AMDAEMON_STATIC_ASSERT(sizeof(accessCode.values) >= sizeof(result_type));
            return *reinterpret_cast<const result_type*>(accessCode.values);
        }
    };
} // namespace std

#endif // AMDAEMON_ACCESSCODE_H