Encoding.h

[詳解]

/// @file
/// @brief 文字コード変換処理を提供する静的クラス Encoding のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_UTIL_ENCODING_H
#define AMDAEMON_UTIL_ENCODING_H

#include "amdaemon/env.h"

#include <string>
#include <locale>

namespace amdaemon
{
namespace util
{
/// @addtogroup g_util
/// @{

    /// @brief 文字コード変換処理を提供する静的クラス。
    /// @see WinEncoding
    ///
    /// @note
    /// - Windows環境に特化しても問題ない場合は WinEncoding クラスの利用を推奨する。
    /// - 各メンバ関数の引数 loc を省略しているのであれば、メンバ参照におけるクラス名を
    ///   "Encoding" から "WinEncoding" に単純置換するだけで動作するようになっている。
    ///
    /// C++標準ライブラリを用いた文字コード変換処理を提供する。
    ///
    /// 静的メンバ関数 convert は、第1引数に変換種別タグ、第2引数に変換元文字列を渡すことで、
    /// C++標準ライブラリ codecvt 等を用いて文字コード変換を行う。
    /// マルチバイト文字列とワイド文字列との間の変換については、
    /// 変換種別タグの指定が不要なオーバロードも定義される。
    ///
    /// @code
    /// // マルチバイト文字列の "あいうえお" をUTF-8化する
    /// std::string u8aiueo = Encoding::convert(Encoding::MbcsToUtf8, "あいうえお");
    /// 
    /// // マルチバイト文字列の "あいうえお" をワイド文字列化する
    /// // 変換種別タグ指定不要なオーバロード
    /// std::wstring w_aiueo = Encoding::convert("あいうえお");
    /// @endcode
    ///
    /// また、変換種別タグの指定が不要なラップ関数も用意されている。
    ///
    /// @code
    /// // マルチバイト文字列の "あいうえお" をUTF-8化する
    /// std::string u8aiueo = Encoding::convertMbcsToUtf8("あいうえお");
    /// @endcode
    ///
    /// 日本語等を扱う場合、各メンバ関数を用いる前に、 std::locale::global 関数を用いて
    /// 文字分類(std::locale::ctype)のグローバルロケールを設定しておくこと。
    ///
    /// 例えば main 関数の冒頭などで下記の関数呼び出しを行うとよい。
    ///
    /// @code
    /// // #include <locale> が必要
    /// 
    /// // グローバルロケールを日本語に設定する
    /// std::locale::global(std::locale(std::locale(), "japanese", std::locale::ctype));
    /// 
    /// // 既に作成済みの std::wcout はロケールが変更されないので
    /// // メンバ関数 imbue を用いて個別に設定する必要がある
    /// std::wcout.imbue(std::locale());
    /// @endcode
    ///
    /// グローバルロケールを変更することが好ましくない場合、各関数の末尾の引数に
    /// std::locale 値を渡すことで直接ロケール指定することもできる。
    ///
    /// @code
    /// // #include <locale> が必要
    /// 
    /// // 日本語ロケールでワイド文字列の L"わをん" をマルチバイト文字列化する
    /// std::string wawon =
    ///     Encoding::convert(
    ///         L"わをん",
    ///         std::locale(std::locale(), "japanese", std::locale::ctype));
    /// @endcode
    ///
    /// ロケールが影響するのはマルチバイト文字列との間の変換のみである。
    /// ワイド文字列とUTF-8文字列との間の変換ではロケールは無視される。
    ///
    /// 変換できない文字が含まれている場合は変換処理を打ち切って空文字列を返す。
    /// 主な失敗理由は次の通り。
    ///
    /// - テキストとして不正な文字列を変換しようとした。
    /// - Unicodeにしかない文字(&hearts; 等)をマルチバイト文字列に変換しようとした。
    class Encoding
    {
    public:
        /// マルチバイト文字列からワイド文字列への変換を示すタグ構造体。
        struct MbcsToWideTag { };
        /// マルチバイト文字列からワイド文字列への変換を示すタグ。
        static const MbcsToWideTag MbcsToWide;

        /// ワイド文字列からマルチバイト文字列への変換を示すタグ構造体。
        struct WideToMbcsTag { };
        /// ワイド文字列からマルチバイト文字列への変換を示すタグ。
        static const WideToMbcsTag WideToMbcs;

        /// UTF-8文字列からワイド文字列への変換を示すタグ構造体。
        struct Utf8ToWideTag { };
        /// UTF-8文字列からワイド文字列への変換を示すタグ。
        static const Utf8ToWideTag Utf8ToWide;

        /// ワイド文字列からUTF-8文字列への変換を示すタグ構造体。
        struct WideToUtf8Tag { };
        /// ワイド文字列からUTF-8文字列への変換を示すタグ。
        static const WideToUtf8Tag WideToUtf8;

        /// マルチバイト文字列からUTF-8文字列への変換を示すタグ構造体。
        struct MbcsToUtf8Tag { };
        /// マルチバイト文字列からUTF-8文字列への変換を示すタグ。
        static const MbcsToUtf8Tag MbcsToUtf8;

        /// UTF-8文字列からマルチバイト文字列への変換を示すタグ構造体。
        struct Utf8ToMbcsTag { };
        /// UTF-8文字列からマルチバイト文字列への変換を示すタグ。
        static const Utf8ToMbcsTag Utf8ToMbcs;

        /// @brief マルチバイト文字列をワイド文字列に変換する。
        /// @param[in] src マルチバイト文字列。
        /// @param[in] loc ロケール設定。
        /// @return ワイド文字列。変換できなかった場合は空文字列。
        /// @note 変換種別タグ指定不要。
        static std::wstring convert(
            const std::string& src,
            const std::locale& loc = std::locale())
        {
            return convert(MbcsToWide, src, loc);
        }

        /// @brief ワイド文字列をマルチバイト文字列に変換する。
        /// @param[in] src ワイド文字列。
        /// @param[in] loc ロケール設定。
        /// @return マルチバイト文字列。変換できなかった場合は空文字列。
        /// @note 変換種別タグ指定不要。
        static std::string convert(
            const std::wstring& src,
            const std::locale& loc = std::locale())
        {
            return convert(WideToMbcs, src, loc);
        }

        /// @brief マルチバイト文字列をワイド文字列に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src マルチバイト文字列。
        /// @param[in] loc ロケール設定。
        /// @return ワイド文字列。変換できなかった場合は空文字列。
        static std::wstring convert(
            MbcsToWideTag tag,
            const std::string& src,
            const std::locale& loc = std::locale());

        /// @brief マルチバイト文字列をワイド文字列に変換する。
        /// @param[in] src マルチバイト文字列。
        /// @param[in] loc ロケール設定。
        /// @return ワイド文字列。変換できなかった場合は空文字列。
        static std::wstring convertMbcsToWide(
            const std::string& src,
            const std::locale& loc = std::locale())
        {
            return convert(MbcsToWide, src, loc);
        }

        /// @brief ワイド文字列をマルチバイト文字列に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src ワイド文字列。
        /// @param[in] loc ロケール設定。
        /// @return マルチバイト文字列。変換できなかった場合は空文字列。
        static std::string convert(
            WideToMbcsTag tag,
            const std::wstring& src,
            const std::locale& loc = std::locale());

        /// @brief ワイド文字列をマルチバイト文字列に変換する。
        /// @param[in] src ワイド文字列。
        /// @param[in] loc ロケール設定。
        /// @return マルチバイト文字列。変換できなかった場合は空文字列。
        static std::string convertWideToMbcs(
            const std::wstring& src,
            const std::locale& loc = std::locale())
        {
            return convert(WideToMbcs, src, loc);
        }

        /// @brief UTF-8文字列をワイド文字列に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src UTF-8文字列。
        /// @param[in] loc ロケール設定。無視される。
        /// @return ワイド文字列。変換できなかった場合は空文字列。
        static std::wstring convert(
            Utf8ToWideTag tag,
            const std::string& src,
            const std::locale& loc = std::locale());

        /// @brief UTF-8文字列をワイド文字列に変換する。
        /// @param[in] src UTF-8文字列。
        /// @param[in] loc ロケール設定。無視される。
        /// @return ワイド文字列。変換できなかった場合は空文字列。
        static std::wstring convertUtf8ToWide(
            const std::string& src,
            const std::locale& loc = std::locale())
        {
            return convert(Utf8ToWide, src, loc);
        }

        /// @brief ワイド文字列をUTF-8文字列に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src ワイド文字列。
        /// @param[in] loc ロケール設定。無視される。
        /// @return UTF-8文字列。変換できなかった場合は空文字列。
        static std::string convert(
            WideToUtf8Tag tag,
            const std::wstring& src,
            const std::locale& loc = std::locale());

        /// @brief ワイド文字列をUTF-8文字列に変換する。
        /// @param[in] src ワイド文字列。
        /// @param[in] loc ロケール設定。無視される。
        /// @return UTF-8文字列。変換できなかった場合は空文字列。
        static std::string convertWideToUtf8(
            const std::wstring& src,
            const std::locale& loc = std::locale())
        {
            return convert(WideToUtf8, src, loc);
        }

        /// @brief マルチバイト文字列をUTF-8文字列に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src マルチバイト文字列。
        /// @param[in] loc ロケール設定。
        /// @return UTF-8文字列。変換できなかった場合は空文字列。
        static std::string convert(
            MbcsToUtf8Tag tag,
            const std::string& src,
            const std::locale& loc = std::locale());

        /// @brief マルチバイト文字列をUTF-8文字列に変換する。
        /// @param[in] src マルチバイト文字列。
        /// @param[in] loc ロケール設定。
        /// @return UTF-8文字列。変換できなかった場合は空文字列。
        static std::string convertMbcsToUtf8(
            const std::string& src,
            const std::locale& loc = std::locale())
        {
            return convert(MbcsToUtf8, src, loc);
        }

        /// @brief UTF-8文字列をマルチバイト文字列に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src UTF-8文字列。
        /// @param[in] loc ロケール設定。
        /// @return マルチバイト文字列。変換できなかった場合は空文字列。
        static std::string convert(
            Utf8ToMbcsTag tag,
            const std::string& src,
            const std::locale& loc = std::locale());

        /// @brief UTF-8文字列をマルチバイト文字列に変換する。
        /// @param[in] src UTF-8文字列。
        /// @param[in] loc ロケール設定。
        /// @return マルチバイト文字列。変換できなかった場合は空文字列。
        static std::string convertUtf8ToMbcs(
            const std::string& src,
            const std::locale& loc = std::locale())
        {
            return convert(Utf8ToMbcs, src, loc);
        }

    private:
        // インスタンス化禁止
        Encoding();                             // 宣言のみ
        Encoding(Encoding&);                    // 宣言のみ
        Encoding& operator=(const Encoding&);   // 宣言のみ
    };

/// @}
} // namespace util
} // namespace amdaemon

#endif // AMDAEMON_UTIL_ENCODING_H