codecvt クラス

ロケールのファセットとして使用できるオブジェクトを表すクラス テンプレート。 プログラム内で文字をエンコードするために使用される値のシーケンスと、プログラム外で文字をエンコードするために使用される値のシーケンスとの変換を制御できます。

構文

template <class CharType, class Byte, class StateType>
class codecvt : public locale::facet, codecvt_base;

パラメーター

CharType
文字をエンコードするためにプログラム内で使用される型。

Byte
文字をエンコードするためにプログラム外で使用される型。

StateType
文字表現の内部型と外部型との変換の中間状態を表すために使用できる型。

解説

このクラス テンプレートは、CharType 型の値のシーケンスと Byte 型の値のシーケンスとの変換を制御するために、ロケール ファセットとして使用できるオブジェクトを表します。 StateType クラスは変換を特徴付けます。また、StateType クラスのオブジェクトは変換中に必要な状態情報を格納します。

内部エンコードでは、1 文字あたりのバイト数が固定された表現、通常 char 型または wchar_t 型を使用します。

すべてのロケールのファセットと同様、静的オブジェクト id に最初に格納されている値は 0 です。 格納されている値に初めてアクセスしようとすると、id に一意の正の値が格納されます。

do_in と do_out のテンプレート バージョンは、常に codecvt_base::noconv を返します。

C++ 標準ライブラリは複数の明示的な特殊化を定義します。

template<>
codecvt<wchar_t, char, mbstate_t>

これは、wchar_t シーケンスと char シーケンスとの変換を実行します。

template<>
codecvt<char16_t, char, mbstate_t>

これは、UTF-16 としてエンコードされる char16_t シーケンスと UTF-8 としてエンコードされる char シーケンスとの変換を実行します。

template<>
codecvt<char32_t, char, mbstate_t>

これは、UTF-32 (UCS-4) としてエンコードされる char32_t シーケンスと UTF-8 としてエンコードされる char シーケンスとの変換を実行します。

コンストラクター

コンストラクター	説明
codecvt	変換を処理するためにロケールのファセットとして機能する codecvt クラスのオブジェクトのコンストラクター。

Typedefs

型名	説明
extern_type	外部表現に使用される文字型。
intern_type	内部表現に使用される文字型。
state_type	内部表現と外部表現との変換時の中間状態を表すために使用される文字型。

メンバー関数

メンバー関数	説明
always_noconv	変換を実行する必要がないかどうかをテストします。
do_always_noconv	変換を実行する必要がないかどうかをテストするために呼び出される仮想関数。
do_encoding	Byte ストリームのエンコードが状態に依存する場合に、使用される Byte 値と生成される CharType 値との比率が一定であるかどうかをテストし、一定である場合は、その比率の値を特定する仮想関数。
do_in	内部の Byte 値のシーケンスを外部の CharType 値のシーケンスに変換するために呼び出される仮想関数。
do_length	特定の外部 Byte 値のシーケンスから生成された内部 CharType 値が特定の数を超えずに最大となる Byte 値の数を特定し、その Byte 値の数を返す仮想関数。
do_max_length	1 つの内部 CharType を生成するために必要な最大外部 Byte 数を返す仮想関数。
do_out	内部の CharType 値のシーケンスを外部の Bytes のシーケンスに変換するために呼び出される仮想関数。
do_unshift	状態に依存する変換で、Byte 値のシーケンスの最後の文字を完了するために必要な Byte 値を提供するために呼び出される仮想関数。
encoding	Byte ストリームのエンコードが状態に依存する場合に、使用される Byte 値と生成される CharType 値との比率が一定であるかどうかをテストし、一定である場合は、その比率の値を特定します。
in	Byte 値のシーケンスの外部表現を、CharType 値のシーケンスの内部表現に変換します。
length	特定の外部 Byte 値のシーケンスから生成された内部 CharType 値が特定の数を超えずに最大となる Byte 値の数を特定し、その Byte 値の数を返します。
max_length	1 つの内部 CharType を生成するために必要な最大外部 Byte 値の数を返します。
out	内部の CharType 値のシーケンスを外部の Byte 値のシーケンスに変換します。
unshift	状態に依存する変換で、Byte 値のシーケンスの最後の文字を完了するために必要な外部の Byte 値を提供します。

要件

ヘッダー: <locale>

名前空間: std

codecvt::always_noconv

変換を実行する必要がないかどうかをテストします。

bool always_noconv() const throw();

戻り値

変換する必要がない場合は true、少なくとも 1 回は変換する必要がある場合は false のブール値。

解説

このメンバー関数は、do_always_noconv を返します。

例

// codecvt_always_noconv.cpp
// compile with: /EHsc
#include <locale>
#include <iostream>
using namespace std;

int main( )
{
   locale loc ( "German_Germany" );
   bool result1 = use_facet<codecvt<char, char, mbstate_t>>
      ( loc ).always_noconv( );

   if ( result1 )
      cout << "No conversion is needed." << '\n';
   else
      cout << "At least one conversion is required." << '\n';

   bool result2 = use_facet<codecvt<wchar_t, char, mbstate_t>>
      ( loc ).always_noconv( );

   if ( result2 )
      cout << "No conversion is needed." << '\n';
   else
      cout << "At least one conversion is required." << '\n';
}

No conversion is needed.
At least one conversion is required.

codecvt::codecvt

変換を処理するためにロケール ファセットとして機能する codecvt クラスのオブジェクトのコンストラクター。

explicit codecvt(size_t refs = 0);

パラメーター

refs
オブジェクトのメモリ管理の種類を指定するために使用する整数値。

解説

refs パラメーターの可能な値とその重要性は次のとおりです。

• 0: オブジェクトの有効期間はそれが含まれるロケールによって管理されます。

• 1: オブジェクトの有効期間を手動で管理する必要があります。

• 2: これらの値は定義されていません。

コンストラクターは、locale::facet(refs) を使用してその locale::facet 基本オブジェクトを初期化します。

codecvt::do_always_noconv

変換を実行する必要がないかどうかをテストするために呼び出される仮想関数。

virtual bool do_always_noconv() const throw();

戻り値

protected 仮想メンバー関数は、do_in または do_out のすべての呼び出しで noconv が返された場合にのみ、true を返します。

テンプレート バージョンでは常に true が返されます。

例

always_noconv の例 (do_always_noconv を呼び出す) を参照してください。

codecvt::do_encoding

Byte ストリームのエンコードが状態に依存する場合に、使用される Byte 値と生成される CharType 値との比率が一定であるかどうかをテストし、一定である場合は、その比率の値を特定する仮想関数。

virtual int do_encoding() const throw();

戻り値

protected 仮想メンバー関数は次の値を返します。

• extern_type 型のシーケンスのエンコードが状態に依存する場合は、-1。

• エンコードがさまざまな長さのシーケンスに関係する場合は、0。

• エンコードが長さ N のシーケンスのみに関係する場合は、N

例

encoding の例 (do_encoding を呼び出す) を参照してください。

codecvt::d o_in

外部の Byte 値のシーケンスを内部の CharType 値のシーケンスに変換するために呼び出される仮想関数。

virtual result do_in(
    StateType& state,
    const Byte* first1,
    const Byte* last1,
    const Byte*& next1,
    CharType* first2,
    CharType* last2,
    CharType*& next2,) const;

パラメーター

state
メンバー関数の呼び出し間で維持される変換の状態。

first1
変換されるシーケンスの先頭へのポインター。

last1
変換されるシーケンスの末尾へのポインター。

next1
変換されたシーケンスの末尾の後の、最初の非変換文字へのポインター。

first2
変換されたシーケンスの先頭へのポインター。

last2
変換されたシーケンスの末尾へのポインター。

next2
変換された最後の CharType の後の CharType (対象シーケンスの変更されていない最初の文字) へのポインター。

戻り値

操作の成功、一部成功、または失敗を示す戻り値。 この関数では次の値が返されます。

• ソース シーケンスが無効な形式である場合は、codecvt_base::error。

• 関数で変換が行われない場合は、codecvt_base::noconv。

• 変換が成功した場合は、codecvt_base::ok。

• 変換を正常に行うのに、ソースが十分でないか、変換先が十分な大きさでない場合は、codecvt_base::partial。

解説

state は、新しいソース シーケンスの先頭で初期の変換状態を表す必要があります。 関数は、変換に成功した現在の状態を反映するために必要に応じて、格納されている値を変更します。 それ以外の場合、格納されている値は指定されません。

例

in の例 (do_in を呼び出す) を参照してください。

codecvt::do_length

特定の外部 Byte 値のシーケンスから生成された内部 CharType 値が特定の数を超えずに最大となる Byte 値の数を特定し、その Byte 値の数を返す仮想関数。

virtual int do_length(
    const StateType& state,
    const Byte* first1,
    const Byte* last1,
    size_t len2) const;

パラメーター

state
メンバー関数の呼び出し間で維持される変換の状態。

first1
外部シーケンスの先頭へのポインター。

last1
外部シーケンスの末尾へのポインター。

len2
メンバー関数で返すことができる Byte 値の最大数。

戻り値

[ first1, last1) で外部ソース シーケンスによって定義されている len2 以下の、最大変換数を表す整数。

解説

protected 仮想メンバー関数は、state (状態のコピー)、一部のバッファー buf、ポインター next1 と next2 に対して、do_in( state, first1, last1, next1, buf, buf + len2, next2) を呼び出します。

その後で next2 - buf が返されます。 [ first1, last1) で外部ソース シーケンスによって定義されている len2 以下の、最大変換数がカウントされます。

テンプレート バージョンでは常に、last1 - first1 と len2 のいずれか小さい方が返されます。

例

length の例 (do_length を呼び出す) を参照してください。

codecvt::do_max_length

1 つの内部 Byte を生成するために必要な最大外部 CharType 値の数を返す仮想関数。

virtual int do_max_length() const throw();

戻り値

1 つの CharType を生成するために必要な Byte 値の最大数。

解説

protected 仮想メンバー関数は、first1 と last1 の任意の有効な値の do_length( first1, last1, 1) で返すことができる最大許容値を返します。

例

max_length の例 (do_max_length を呼び出す) を参照してください。

codecvt::do_out

内部の CharType 値のシーケンスを外部の Byte 値のシーケンスに変換するために呼び出される仮想関数。

virtual result do_out(
    StateType& state,
    const CharType* first1,
    const CharType* last1,
    const CharType*& next1,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

パラメーター

state
メンバー関数の呼び出し間で維持される変換の状態。

first1
変換されるシーケンスの先頭へのポインター。

last1
変換されるシーケンスの末尾へのポインター。

next1
変換された最後の CharType の後の、最初の未変換 CharType へのポインターの参照。

first2
変換されたシーケンスの先頭へのポインター。

last2
変換されたシーケンスの末尾へのポインター。

next2
変換された最後の Byte の後の、最初の未変換 Byte へのポインターの参照。

戻り値

この関数では次の値が返されます。

• ソース シーケンスが無効な形式である場合は、codecvt_base::error。

• 関数で変換が行われない場合は、codecvt_base::noconv。

• 変換が成功した場合は、codecvt_base::ok。

• 変換を正常に行うのに、ソースが十分でないか、変換先が十分な大きさでない場合は、codecvt_base::partial。

解説

state は、新しいソース シーケンスの先頭で初期の変換状態を表す必要があります。 関数は、変換に成功した現在の状態を反映するために必要に応じて、格納されている値を変更します。 それ以外の場合、格納されている値は指定されません。

例

out の例 (do_out を呼び出す) を参照してください。

codecvt::do_unshift

状態に依存する変換で、Byte 値のシーケンスの最後の文字を完了するために必要な Byte 値を提供するために呼び出される仮想関数。

virtual result do_unshift(
    StateType& state,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

パラメーター

state
メンバー関数の呼び出し間で維持される変換の状態。

first2
対象範囲内の最初の位置へのポインター。

last2
対象範囲内の最後の位置へのポインター。

next2
対象シーケンス内の変更されていない最初の要素へのポインター。

戻り値

この関数では次の値が返されます。

• state が無効な状態を表す場合は、codecvt_base::error

• 関数で変換が行われない場合は、codecvt_base::noconv。

• 変換が成功した場合は、codecvt_base::ok

• 変換先が、変換を正常に行うのに十分な大きさでない場合は、codecvt_base::partial

解説

protected 仮想メンバー関数は、ソース要素 CharType(0) を、終了要素 Byte(0) 以外の、[ first2, last2) 内に格納されている対象シーケンスに変換しようとします。 対象シーケンス内の変更されていない最初の要素へのポインター next2 に常に格納します。

State は、新しいソース シーケンスの先頭で初期の変換状態を表す必要があります。 関数は、変換に成功した現在の状態を反映するために必要に応じて、格納されている値を変更します。 通常、ソース要素 CharType(0) を変換した場合、現在の状態は初期の変換状態のままになります。

例

unshift の例 (do_unshift を呼び出す) を参照してください。

codecvt::encoding

Byte ストリームのエンコードが状態に依存する場合に、使用される Byte 値と生成される CharType 値との比率が一定であるかどうかをテストし、一定である場合は、その比率の値を特定します。

int encoding() const throw();

戻り値

戻り値が正の値の場合、その値は、CharType 文字の生成に必要な Byte 文字の定数になります。

protected 仮想メンバー関数は次の値を返します。

• extern_type 型のシーケンスのエンコードが状態に依存する場合は、-1。

• エンコードがさまざまな長さのシーケンスに関係する場合は、0。

• エンコードが長さ N のシーケンスのみに関係する場合は、N。

解説

このメンバー関数は、do_encoding を返します。

例

// codecvt_encoding.cpp
// compile with: /EHsc
#include <locale>
#include <iostream>
using namespace std;

int main( )
{
   locale loc ( "German_Germany" );
   int result1 = use_facet<codecvt<char, char, mbstate_t>> ( loc ).encoding ( );
   cout << result1 << '\n';
   result1 = use_facet<codecvt<wchar_t, char, mbstate_t>> ( loc ).encoding( );
   cout << result1 << '\n';
   result1 = use_facet<codecvt<char, wchar_t, mbstate_t>> ( loc ).encoding( );
   cout << result1 << '\n';
}

1
1
1

codecvt::extern_type

外部表現に使用される文字型。

typedef Byte extern_type;

解説

この型は、テンプレート パラメーター Byteのシノニムです。

codecvt::in

Byte 値のシーケンスの外部表現を、CharType 値のシーケンスの内部表現に変換します。

result in(
    StateType& state,
    const Byte* first1,
    const Byte* last1,
    const Byte*& next1,
    CharType* first2,
    CharType* last2,
    CharType*& next2,) const;

パラメーター

state
メンバー関数の呼び出し間で維持される変換の状態。

first1
変換されるシーケンスの先頭へのポインター。

last1
変換されるシーケンスの末尾へのポインター。

next1
変換されたシーケンスの末尾の後の、最初の未変換文字へのポインター。

first2
変換されたシーケンスの先頭へのポインター。

last2
変換されたシーケンスの末尾へのポインター。

next2
変換された最後の Chartype の後の CharType (対象シーケンスの変更されていない最初の文字) へのポインター。

戻り値

操作の成功、一部成功、または失敗を示す戻り値。 この関数では次の値が返されます。

• ソース シーケンスが無効な形式である場合は、codecvt_base::error。

• 関数で変換が行われない場合は、codecvt_base::noconv。

• 変換が成功した場合は、codecvt_base::ok。

• 変換を正常に行うのに、ソースが十分でないか、変換先が十分な大きさでない場合は、codecvt_base::partial。

解説

state は、新しいソース シーケンスの先頭で初期の変換状態を表す必要があります。 関数は、変換に成功した現在の状態を反映するために必要に応じて、格納されている値を変更します。 部分変換後に、state は、新しい文字の到着時に変換を再開できるように設定する必要があります。

このメンバー関数は、do_in( state, first1, last1, next1, first2, last2, next2) を返します。

例

// codecvt_in.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
using namespace std;
#define LEN 90
int main( )
{
   const char* pszExt = "This is the string to be converted!";
   wchar_t pwszInt [LEN+1];
   memset(&pwszInt[0], 0, (sizeof(wchar_t))*(LEN+1));
   const char* pszNext;
   wchar_t* pwszNext;
   mbstate_t state = {0}; // zero-initialization represents the initial conversion state for mbstate_t
   locale loc("C");//English_Britain");//German_Germany
   int res = use_facet<codecvt<wchar_t, char, mbstate_t>>
     ( loc ).in( state,
          pszExt, &pszExt[strlen(pszExt)], pszNext,
          pwszInt, &pwszInt[strlen(pszExt)], pwszNext );
   pwszInt[strlen(pszExt)] = 0;
   wcout << ( res!=codecvt_base::error ?  L"It worked! " : L"It didn't work! " )
       << L"The converted string is:\n ["
       << &pwszInt[0]
       << L"]" << '\n';
   exit(-1);
}

It worked! The converted string is:
[This is the string to be converted!]

codecvt::intern_type

内部表現に使用される文字型。

typedef CharType intern_type;

解説

この型は、テンプレート パラメーター CharTypeのシノニムです。

codecvt::length

特定の外部 Byte 値のシーケンスから生成された内部 CharType 値が特定の数を超えずに最大となる Byte 値の数を特定し、その Byte 値の数を返します。

int length(
    const StateType& state,
    const Byte* first1,
    const Byte* last1,
    size_t len2) const;

パラメーター

state
メンバー関数の呼び出し間で維持される変換の状態。

first1
外部シーケンスの先頭へのポインター。

last1
外部シーケンスの末尾へのポインター。

len2
メンバー関数で返すことができる Byte の最大数。

戻り値

[ first1, last1) で外部ソース シーケンスによって定義されている len2 以下の、最大変換数を表す整数。

解説

このメンバー関数は、do_length( state, first1, last1, len2) を返します。

例

// codecvt_length.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
using namespace std;
#define LEN 90
int main( )
{
   const char* pszExt = "This is the string whose length is to be measured!";
   mbstate_t state = {0}; // zero-initialization represents the initial conversion state for mbstate_t
   locale loc("C"); // English_Britain"); //German_Germany
   int res = use_facet<codecvt<wchar_t, char, mbstate_t>>
     ( loc ).length( state,
          pszExt, &pszExt[strlen(pszExt)], LEN );
   cout << "The length of the string is: ";
   wcout << res;
   cout << "." << '\n';
   exit(-1);
}

The length of the string is: 50.

codecvt::max_length

1 つの内部 CharType を生成するために必要な最大外部 Byte 値の数を返します。

int max_length() const throw();

戻り値

1 つの CharType を生成するために必要な Byte 値の最大数。

解説

このメンバー関数は、do_max_length を返します。

例

// codecvt_max_length.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
using namespace std;

int main( )
{
   locale loc( "C");//English_Britain" );//German_Germany
   int res = use_facet<codecvt<char, char, mbstate_t>>
     ( loc ).max_length( );
   wcout << res << '\n';
}

1

codecvt::out

内部の CharType 値のシーケンスを外部の Byte 値のシーケンスに変換します。

result out(
    StateType& state,
    const CharType* first1,
    const CharType* last1,
    const CharType*& next1,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

パラメーター

state
メンバー関数の呼び出し間で維持される変換の状態。

first1
変換されるシーケンスの先頭へのポインター。

last1
変換されるシーケンスの末尾へのポインター。

next1
変換された最後の CharType の後の、最初の未変換 CharType へのポインターの参照。

first2
変換されたシーケンスの先頭へのポインター。

last2
変換されたシーケンスの末尾へのポインター。

next2
変換された最後の Byte の後の、最初の未変換 Byte へのポインターの参照。

戻り値

このメンバー関数は、do_out( state, first1, last1, next1, first2, last2, next2) を返します。

解説

詳細については、codecvt::do_outを参照してください。

例

// codecvt_out.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
#include <wchar.h>
using namespace std;
#define LEN 90
int main( )
{
    char pszExt[LEN + 1];
    const wchar_t* pwszInt = L"This is the wchar_t string to be converted.";
    memset(&pszExt[0], 0, (sizeof(char)) * (LEN + 1));
    char* pszNext;
    const wchar_t* pwszNext;
    mbstate_t state;
    locale loc("C");//English_Britain");//German_Germany
    int res = use_facet<codecvt<wchar_t, char, mbstate_t>>
        (loc).out(state,
            pwszInt, &pwszInt[wcslen(pwszInt)], pwszNext,
            pszExt, &pszExt[wcslen(pwszInt)], pszNext);
    pszExt[wcslen(pwszInt)] = 0;
    cout << (res != codecvt_base::error ? "It worked: " : "It didn't work: ")
        << "The converted string is:\n ["
        << &pszExt[0]
        << "]" << '\n';

}

It worked: The converted string is:
[This is the wchar_t string to be converted.]

codecvt::state_type

内部表現と外部表現との変換時の中間状態を表すために使用される文字型。

typedef StateType state_type;

解説

この型は、テンプレート パラメーター StateTypeのシノニムです。

codecvt::unshift

状態に依存する変換で、Byte 値のシーケンスの最後の文字を完了するために必要な Byte 値を提供します。

result unshift(
    StateType& state,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

パラメーター

state
メンバー関数の呼び出し間で維持される変換の状態。

first2
対象範囲内の最初の位置へのポインター。

last2
対象範囲内の最後の位置へのポインター。

next2
対象シーケンス内の変更されていない最初の要素へのポインター。

戻り値

この関数では次の値が返されます。

• state が無効な状態を表す場合は、codecvt_base::error。

• 関数で変換が行われない場合は、codecvt_base::noconv。

• 変換が成功した場合は、codecvt_base::ok。

• 変換先が、変換を正常に行うのに十分な大きさでない場合は、codecvt_base::partial。

解説

protected 仮想メンバー関数は、ソース要素 CharType(0) を、終了要素 Byte(0) 以外の、[ first2, last2) 内に格納されている対象シーケンスに変換しようとします。 対象シーケンス内の変更されていない最初の要素へのポインター next2 に常に格納します。

state は、新しいソース シーケンスの先頭で初期の変換状態を表す必要があります。 関数は、変換に成功した現在の状態を反映するために必要に応じて、格納されている値を変更します。 通常、ソース要素 CharType(0) を変換した場合、現在の状態は初期の変換状態のままになります。

このメンバー関数は、do_unshift( state, first2, last2, next2 ) を返します。

関連項目

<locale>
コード ページ
ロケール名、言語、および国/地域識別文字列
C++ 標準ライブラリ内のスレッド セーフ