WinEncoding.h

[詳解]

/// @file
/// @brief Windows環境に特化した文字コード変換処理を提供する静的クラス WinEncoding のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_UTIL_WINENCODING_H
#define AMDAEMON_UTIL_WINENCODING_H

#include "amdaemon/env.h"

#include <string>
#include <cstdint>
#include <cstdlib>

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

    //--------------------
    // WinEncoding クラス定義
    //--------------------

    /// @brief Windows環境に特化した文字コード変換処理を提供する静的クラス。
    /// @see Encoding
    ///
    /// 下記の Windows API 関数を用いた、
    /// ANSI文字列とワイド文字列との間の文字コード変換処理を提供する。
    ///
    /// - MultiByteToWideChar
    /// - WideCharToMultiByte
    ///
    /// ANSI文字列とは、ここでは char の配列で表す文字列全般を指す。
    /// ワイド文字列とは、 wchar_t の配列で表す文字列を指す。
    /// Windows環境においてワイド文字列の文字コードはUTF-16LEである。
    ///
    /// 静的メンバ関数 convert は、第1引数にコードページ値または変換種別タグ、
    /// 第2引数に変換元文字列を渡すことで文字コード変換を行う。
    /// マルチバイト文字列(CP932)とワイド文字列との間の変換については、
    /// コードページ値や変換種別タグの指定が不要なオーバロードも定義される。
    ///
    /// @code
    /// // ワイド文字列の L"あいうえお" をマルチバイト文字列化する
    /// std::string aiueo = WinEncoding::convert(WinEncoding::CodePageMbcs, L"あいうえお");
    /// 
    /// // マルチバイト文字列(CP932)の "あいうえお" をUTF-8化する
    /// std::string u8aiueo = WinEncoding::convert(WinEncoding::MbcsToUtf8, "あいうえお");
    /// 
    /// // マルチバイト文字列(CP932)の "あいうえお" をワイド文字列化する
    /// // コードページ値や変換種別タグを指定不要なオーバロード
    /// std::wstring w_aiueo = Encoding::convert("あいうえお");
    /// @endcode
    ///
    /// また、主要な文字コード用にラップ関数が用意されている。
    ///
    /// @code
    /// // マルチバイト文字列(CP932)の "あいうえお" をUTF-8化する
    /// std::string u8aiueo = WinEncoding::convertMbcsToUtf8("あいうえお");
    /// @endcode
    ///
    /// 文字コード変換における挙動は先述の Windows API に依存する。
    /// 変換できない文字が含まれていてもその文字を '?' 等に置換するのみであり、
    /// 変換処理を打ち切ることはない。
    ///
    /// @par マルチバイト文字列(CP932)へ変換する場合の特殊処理
    /// このクラスの特殊な動作として、文字コード変換先がマルチバイト文字列(CP932)である場合、
    /// 文字コード変換処理を行う前に、いくつかの文字について置換処理を行う。
    /// 処理の内容は静的メンバ関数 #remapSjisToMbcs に準ずる。
    /// @par
    /// 各メンバ関数の引数 remappingSjisToMbcs に false を指定するとこの処理を無効化できる。
    /// 引数指定を省略した場合は true を指定したものとして扱われる。
    /// @par
    /// この文字置換処理は、変換元の文字列がシフトJISから変換されていた場合であっても
    /// 極力マルチバイト文字列(CP932)へ変換できるようにするためのものであり、
    /// 変換先がマルチバイト文字列(CP932)でなければ行われない。
    /// 変換先がマルチバイト文字列(CP932)ではない関数についても引数
    /// remappingSjisToMbcs が存在するが、その場合の引数値は単に無視される。
    class WinEncoding
    {
    public:
        /// @brief マルチバイト文字列(CP932)のコードページ値 932 。
        ///
        /// CP932は、日本語WindowsではシフトJISと呼ばれることも多い文字コードである。
        /// 本来のシフトJISより文字数が多く、一部文字の定義が異なる。
        static const std::uint32_t CodePageMbcs = 932;

        /// UTF-8のコードページ値 65001 。
        static const std::uint32_t CodePageUtf8 = 65001;

        /// ASCIIのコードページ値 1252 。
        static const std::uint32_t CodePageAscii = 1252;

        /// マルチバイト文字列(CP932)からワイド文字列(UTF-16LE)への変換を示すタグ構造体。
        struct MbcsToWideTag { };
        /// マルチバイト文字列(CP932)からワイド文字列への変換を示すタグ。
        static const MbcsToWideTag MbcsToWide;

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

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

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

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

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

        /// @brief ANSI文字列をワイド文字列に変換する。
        /// @param[in] codePage 変換元のコードページ値。
        /// @param[in] src ANSI文字列。
        /// @param[in] remappingSjisToMbcs このオーバロードでは無視される。
        /// @return ワイド文字列。
        ///
        /// 対象のコードページから変換できない文字は代替文字に置き換えられる。
        static std::wstring convert(
            std::uint32_t codePage,
            const std::string& src,
            bool remappingSjisToMbcs = true);

        /// @brief ワイド文字列をANSI文字列に変換する。
        /// @param[in] codePage 変換先のコードページ値。
        /// @param[in] src ワイド文字列。
        /// @param[in] remappingSjisToMbcs
        ///     引数 codePage の値が #CodePageMbcs である場合に、
        ///     静的メンバ関数 #remapSjisToMbcs 相当の文字置換処理を事前に行うならば true 。
        /// @return ANSI文字列。
        ///
        /// 対象のコードページに変換できない文字は代替文字 '?' に置き換えられる。
        static std::string convert(
            std::uint32_t codePage,
            const std::wstring& src,
            bool remappingSjisToMbcs = true);

        /// @brief マルチバイト文字列(CP932)をワイド文字列に変換する。
        /// @param[in] src マルチバイト文字列(CP932)。
        /// @param[in] remappingSjisToMbcs このオーバロードでは無視される。
        /// @return ワイド文字列。
        ///
        /// 変換できない文字は代替文字に置き換えられる。
        static std::wstring convert(const std::string& src, bool remappingSjisToMbcs = true)
        {
            return convert(CodePageMbcs, src, remappingSjisToMbcs);
        }

        /// @brief ワイド文字列をマルチバイト文字列(CP932)に変換する。
        /// @param[in] src ワイド文字列。
        /// @param[in] remappingSjisToMbcs
        ///     静的メンバ関数 #remapSjisToMbcs 相当の文字置換処理を事前に行うならば true 。
        /// @return マルチバイト文字列(CP932)。
        ///
        /// 変換できない文字は代替文字 '?' に置き換えられる。
        static std::string convert(const std::wstring& src, bool remappingSjisToMbcs = true)
        {
            return convert(CodePageMbcs, src, remappingSjisToMbcs);
        }

        /// @brief マルチバイト文字列(CP932)をワイド文字列に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src マルチバイト文字列(CP932)。
        /// @param[in] remappingSjisToMbcs このオーバロードでは無視される。
        /// @return ワイド文字列。
        ///
        /// 変換できない文字は代替文字に置き換えられる。
        inline static std::wstring convert(
            MbcsToWideTag tag,
            const std::string& src,
            bool remappingSjisToMbcs = true);

        /// @brief マルチバイト文字列(CP932)をワイド文字列に変換する。
        /// @param[in] src マルチバイト文字列(CP932)。
        /// @return ワイド文字列。
        ///
        /// 変換できない文字は代替文字に置き換えられる。
        static std::wstring convertMbcsToWide(const std::string& src)
        {
            return convert(MbcsToWide, src);
        }

        /// @brief ワイド文字列をマルチバイト文字列(CP932)に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src ワイド文字列。
        /// @param[in] remappingSjisToMbcs
        ///     静的メンバ関数 #remapSjisToMbcs 相当の文字置換処理を事前に行うならば true 。
        /// @return マルチバイト文字列(CP932)。
        ///
        /// 変換できない文字は代替文字 '?' に置き換えられる。
        inline static std::string convert(
            WideToMbcsTag tag,
            const std::wstring& src,
            bool remappingSjisToMbcs = true);

        /// @brief ワイド文字列をマルチバイト文字列(CP932)に変換する。
        /// @param[in] src ワイド文字列。
        /// @param[in] remappingSjisToMbcs
        ///     静的メンバ関数 #remapSjisToMbcs 相当の文字置換処理を事前に行うならば true 。
        /// @return マルチバイト文字列(CP932)。
        ///
        /// 変換できない文字は代替文字 '?' に置き換えられる。
        static std::string convertWideToMbcs(
            const std::wstring& src,
            bool remappingSjisToMbcs = true)
        {
            return convert(WideToMbcs, src, remappingSjisToMbcs);
        }

        /// @brief UTF-8文字列をワイド文字列に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src UTF-8文字列。
        /// @param[in] remappingSjisToMbcs このオーバロードでは無視される。
        /// @return ワイド文字列。
        ///
        /// 変換できない文字は代替文字に置き換えられる。
        inline static std::wstring convert(
            Utf8ToWideTag tag,
            const std::string& src,
            bool remappingSjisToMbcs = true);

        /// @brief UTF-8文字列をワイド文字列に変換する。
        /// @param[in] src UTF-8文字列。
        /// @return ワイド文字列。
        ///
        /// 変換できない文字は代替文字に置き換えられる。
        static std::wstring convertUtf8ToWide(const std::string& src)
        {
            return convert(Utf8ToWide, src);
        }

        /// @brief ワイド文字列をUTF-8文字列に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src ワイド文字列。
        /// @param[in] remappingSjisToMbcs このオーバロードでは無視される。
        /// @return UTF-8文字列。
        ///
        /// 変換できない文字は代替文字 '?' に置き換えられる。
        inline static std::string convert(
            WideToUtf8Tag tag,
            const std::wstring& src,
            bool remappingSjisToMbcs = true);

        /// @brief ワイド文字列をUTF-8文字列に変換する。
        /// @param[in] src ワイド文字列。
        /// @return UTF-8文字列。
        ///
        /// 変換できない文字は代替文字 '?' に置き換えられる。
        static std::string convertWideToUtf8(const std::wstring& src)
        {
            return convert(WideToUtf8, src);
        }

        /// @brief マルチバイト文字列(CP932)をUTF-8文字列に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src マルチバイト文字列(CP932)。
        /// @param[in] remappingSjisToMbcs このオーバロードでは無視される。
        /// @return UTF-8文字列。
        ///
        /// 変換できない文字は代替文字 '?' に置き換えられる。
        inline static std::string convert(
            MbcsToUtf8Tag tag,
            const std::string& src,
            bool remappingSjisToMbcs = true);

        /// @brief マルチバイト文字列(CP932)をUTF-8文字列に変換する。
        /// @param[in] src マルチバイト文字列(CP932)。
        /// @return UTF-8文字列。
        ///
        /// 変換できない文字は代替文字 '?' に置き換えられる。
        static std::string convertMbcsToUtf8(const std::string& src)
        {
            return convert(MbcsToUtf8, src);
        }

        /// @brief UTF-8文字列をマルチバイト文字列(CP932)に変換する。
        /// @param[in] tag 変換種別タグ。
        /// @param[in] src UTF-8文字列。
        /// @param[in] remappingSjisToMbcs
        ///     静的メンバ関数 #remapSjisToMbcs 相当の文字置換処理を事前に行うならば true 。
        /// @return マルチバイト文字列(CP932)。
        ///
        /// 変換できない文字は代替文字 '?' に置き換えられる。
        inline static std::string convert(
            Utf8ToMbcsTag tag,
            const std::string& src,
            bool remappingSjisToMbcs = true);

        /// @brief UTF-8文字列をマルチバイト文字列(CP932)に変換する。
        /// @param[in] src UTF-8文字列。
        /// @param[in] remappingSjisToMbcs
        ///     静的メンバ関数 #remapSjisToMbcs 相当の文字置換処理を事前に行うならば true 。
        /// @return マルチバイト文字列(CP932)。
        ///
        /// 変換できない文字は代替文字 '?' に置き換えられる。
        static std::string convertUtf8ToMbcs(
            const std::string& src,
            bool remappingSjisToMbcs = true)
        {
            return convert(Utf8ToMbcs, src, remappingSjisToMbcs);
        }

        /// @brief
        ///     本来のシフトJISとCP932との間でマッピングの異なるワイド文字について、
        ///     CP932への文字コード変換用に再マッピングする。
        /// @param[in,out] target 再マッピング対象のワイド文字列。
        /// @param[in] length
        ///     再マッピング対象文字数。
        ///     既定値 SIZE_MAX の場合は文字 '¥0' の直前までを対象とする。
        /// @return target 自身。
        /// @see remapSjisToMbcs(std::wstring&, std::size_t)
        ///
        /// 各文字に対して下記の置換処理を行う。
        ///
        /// - 文字 0x2014 ならば文字 0x2015 (―)に置換する。
        /// - 文字 0x301C ならば文字 0xFF5E (〜)に置換する。
        /// - 文字 0x2016 ならば文字 0x2225 (‖)に置換する。
        /// - 文字 0x2212 ならば文字 0xFF0D (−)に置換する。
        /// - 文字 0x00A2 ならば文字 0xFFE0 (¢)に置換する。
        /// - 文字 0x00A3 ならば文字 0xFFE1 (£)に置換する。
        /// - 文字 0x00AC ならば文字 0xFFE2 (¬)に置換する。
        ///
        /// ただし引数 target が nullptr である場合は何もせず nullptr を返す。
        static wchar_t* remapSjisToMbcs(wchar_t* target, std::size_t length = SIZE_MAX);

        /// @brief
        ///     本来のシフトJISとCP932との間でマッピングの異なるワイド文字について、
        ///     CP932への文字コード変換用に再マッピングする。
        /// @param[in,out] target 再マッピング対象のワイド文字列。
        /// @param[in] length
        ///     再マッピング対象文字数。
        ///     この値と target.size() のうち小さい方の値を用いる。
        /// @return target 自身の参照。
        /// @see remapSjisToMbcs(wchar_t*, std::size_t)
        ///
        /// 各文字に対して下記の置換処理を行う。
        ///
        /// - 文字 0x2014 ならば文字 0x2015 (―)に置換する。
        /// - 文字 0x301C ならば文字 0xFF5E (〜)に置換する。
        /// - 文字 0x2016 ならば文字 0x2225 (‖)に置換する。
        /// - 文字 0x2212 ならば文字 0xFF0D (−)に置換する。
        /// - 文字 0x00A2 ならば文字 0xFFE0 (¢)に置換する。
        /// - 文字 0x00A3 ならば文字 0xFFE1 (£)に置換する。
        /// - 文字 0x00AC ならば文字 0xFFE2 (¬)に置換する。
        static std::wstring& remapSjisToMbcs(
            std::wstring& target,
            std::size_t length = SIZE_MAX)
        {
            // std::min のためだけに algorithm ヘッダをインクルードしたくないので自前判定
            remapSjisToMbcs(
                &target.front(),
                (length < target.size()) ? length : target.size());
            return target;
        }

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

/// @}

    //--------------------
    // インラインメンバ関数実装
    //--------------------

    // [static] マルチバイト文字列(CP932)をワイド文字列に変換する。
    inline std::wstring WinEncoding::convert(
        MbcsToWideTag /*tag*/,
        const std::string& src,
        bool remappingSjisToMbcs)
    {
        return convert(CodePageMbcs, src, remappingSjisToMbcs);
    }

    // [static] ワイド文字列をマルチバイト文字列(CP932)に変換する。
    inline std::string WinEncoding::convert(
        WideToMbcsTag /*tag*/,
        const std::wstring& src,
        bool remappingSjisToMbcs)
    {
        return convert(CodePageMbcs, src, remappingSjisToMbcs);
    }

    // [static] UTF-8文字列をワイド文字列に変換する。
    inline std::wstring WinEncoding::convert(
        Utf8ToWideTag /*tag*/,
        const std::string& src,
        bool remappingSjisToMbcs)
    {
        return convert(CodePageUtf8, src, remappingSjisToMbcs);
    }

    // [static] ワイド文字列をUTF-8文字列に変換する。
    inline std::string WinEncoding::convert(
        WideToUtf8Tag /*tag*/,
        const std::wstring& src,
        bool remappingSjisToMbcs)
    {
        return convert(CodePageUtf8, src, remappingSjisToMbcs);
    }

    // [static] マルチバイト文字列(CP932)をUTF-8文字列に変換する。
    inline std::string WinEncoding::convert(
        MbcsToUtf8Tag /*tag*/,
        const std::string& src,
        bool remappingSjisToMbcs)
    {
        return
            convert(
                CodePageUtf8,
                convert(CodePageMbcs, src, remappingSjisToMbcs),
                remappingSjisToMbcs);
    }

    // [static] UTF-8文字列をマルチバイト文字列(CP932)に変換する。
    inline std::string WinEncoding::convert(
        Utf8ToMbcsTag /*tag*/,
        const std::string& src,
        bool remappingSjisToMbcs)
    {
        return
            convert(
                CodePageMbcs,
                convert(CodePageUtf8, src, remappingSjisToMbcs),
                remappingSjisToMbcs);
    }
} // namespace util
} // namespace amdaemon

#endif // AMDAEMON_UTIL_WINENCODING_H