codecvt 类

一个类模板，描述可用作区域设置 facet 的对象。 它可以控制用于对程序中和程序外的字符进行编码的值序列之间的转换。

语法

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

参数

CharType
在程序中用于对字符进行编码的类型。

Byte
用于对程序外的字符进行编码的类型。

StateType
一种类型，此类型可用于表示字符表示形式的内部和外部类型之间转换的中间状态。

注解

这个类模板描述可用作区域设置 facet 的对象，用于控制 CharType 类型的值序列和 Byte 类型的值序列之间的转换。 StateType 类描述转换，StateType 类的对象存储转换期间的任何必要状态信息。

内部编码使用每个字符都包含固定字节数的表示形式，通常为 char 类型或 wchar_t 类型。

对于任何区域设置 facet，静态对象 id 的初始存储值为零。 首次尝试访问其存储值后，将在 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	用作区域设置 facet 以处理转换的 codecvt 类的对象的构造函数。

Typedef

类型名称	说明
extern_type	用于外部表示形式的字符类型。
intern_type	用于内部表示形式的字符类型。
state_type	一种字符类型，此类型用于表示内部和外部表示形式进行转换期间的中间状态。

成员函数

成员函数	说明
always_noconv	测试是否不需要完成转换。
do_always_noconv	为测试是否不需要完成转换而调用的虚拟函数。
do_encoding	测试 Byte 流的编码是否依赖于状态、使用的 Byte 值和生成的 CharType 值之间的比率是否恒定（如果是，则确定此比率的值）的虚拟函数。
do_in	为将内部 Byte 值序列转换为外部 CharType 值序列而调用的虚拟函数。
do_length	确定给定外部 Byte 值序列中有多少 Byte 值生成的内部 CharType 值不超过给定数量并返回此 Byte 值的虚拟函数。
do_max_length	返回生成一个内部 CharType 所需的最大外部字节数的虚拟函数。
do_out	为将内部 CharType 值序列转换为外部 Byte 序列而调用的虚拟函数。
do_unshift	一种虚拟函数，通过调用此函数可提供依赖于状态的转换中需要的 Byte 值以完成 Byte 值序列中的最后一个字符。
encoding	测试 Byte 流的编码是否依赖于状态、使用的 Byte 值和生成的 CharType 值之间的比率是否恒定（如果是，则确定此比率的值）。
in	将 Byte 值序列的外部表示形式转换为 CharType 值序列的内部表示形式。
length	确定给定外部 Byte 值序列中有多少 Byte 值生成的内部 CharType 值不超过给定数量并返回此 Byte 值。
max_length	返回生成一个内部 CharType 所需的最大外部 Byte 值。
out	将内部 CharType 值序列转换为外部 Byte 值序列。
unshift	提供依赖于状态的转换中需要的外部 Byte 值以完成 Byte 值序列中的最后一个字符。

要求

标头：<locale>

命名空间：std

codecvt::always_noconv

测试是否不需要完成转换。

bool always_noconv() const throw();

返回值

一个布尔值，如果不需要完成转换，则为 true；如果至少需要完成一个转换，则为 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

用作区域设置 facet 以处理转换的 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();

返回值

只有每次调用 do_in 或 do_out 返回 noconv 时，受保护的虚拟成员函数才会返回 true。

模板版本始终返回 true。

示例

请参阅 always_noconv 示例，它调用 do_always_noconv。

codecvt::do_encoding

测试 Byte 流的编码是否依赖于状态、使用的 Byte 值和生成的 CharType 值之间的比率是否恒定（如果是，则确定此比率的值）的虚拟函数。

virtual int do_encoding() const throw();

返回值

受保护的虚拟成员函数返回：

• 如果 extern_type 类型序列的编码为依赖状态，则为 -1。

• 如果编码涉及不同长度的序列，则为 0。

• 如果编码仅涉及 N 长度的序列，则为 N

示例

请参阅 encoding 的示例，它调用 do_encoding。

codecvt::do_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 值序列中有多少 Byte 值生成的内部 CharType 值不超过给定数量并返回此 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。

注解

受保护的虚拟成员函数针对 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

返回生成一个内部 CharType 所需的最大外部 Byte 值数的虚拟函数。

virtual int do_max_length() const throw();

返回值

生成一个 CharType 所需的 Byte 值的最大数量。

备注

受保护的虚拟成员函数将返回可能由 do_length( first1, last1, 1) 针对 first1 和 last1 的任意有效值返回的最大允许值。

示例

请参阅 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

备注

受保护的虚拟成员函数尝试将源元素 CharType(0) 转换为其存储在 [ first2, last2) 中的目标序列，终止元素 Byte(0) 除外。 它始终存储在指向目标序列中第一个未更改元素的指针 next2 中。

State 必须代表新源序列开头的初始转换状态。 此函数根据需要来更改其存储的值以反映成功转换的当前状态。 通常情况下，转换源元素 CharType(0) 将使当前状态处于初始转换状态。

示例

请参阅 unshift 示例，它调用 do_unshift。

codecvt::encoding

测试 Byte 流的编码是否依赖于状态、使用的 Byte 值和生成的 CharType 值之间的比率是否恒定（如果是，则确定此比率的值）。

int encoding() const throw();

返回值

如果返回值为正，则该值是生成 CharType 字符所需的 Byte 字符的固定数目。

受保护的虚拟成员函数返回：

• 如果 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 值序列中有多少 Byte 值生成的内部 CharType 值不超过给定数量并返回此 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

返回生成一个内部 CharType 所需的最大外部 Byte 值。

int max_length() const throw();

返回值

生成一个 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。

注解

受保护的虚拟成员函数尝试将源元素 CharType(0) 转换为其存储在 [ first2, last2) 中的目标序列，终止元素 Byte(0) 除外。 它始终存储在指向目标序列中第一个未更改元素的指针 next2 中。

state 必须代表新源序列开头的初始转换状态。 此函数根据需要来更改其存储的值以反映成功转换的当前状态。 通常情况下，转换源元素 CharType(0) 将使当前状态处于初始转换状态。

成员函数返回 do_unshift( state, first2, last2, next2 )。

另请参阅

<locale>
代码页
区域设置名称、语言和国家/地区字符串
C++ 标准库中的线程安全