`codecvt` 類別

發行項
07/05/2024

類別範本，描述可作為地區設定 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_indo_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` 類別物件的建構函式。

Typedefs

類型名稱	描述
`extern_type`	用於外部表示的字元類型。
`intern_type`	用於內部表示的字元類型。
`state_type`	字元類型，用來表示內部和外部表示之間轉換期間的中繼狀態。

成員函式

成員函數	描述
`always_noconv`	測試是否不需要完成轉換。
`do_always_noconv`	虛擬函式，呼叫以測試是否不需要完成轉換。
`do_encoding`	虛擬函式，測試數據流的`Byte`編碼是否相依於狀態、所使用的值與`CharType`產生的值之間的`Byte`比率是否為常數，如果是，則判斷該比率的值。
`do_in`	名為的虛擬函式，可將內部 `Byte` 值序列轉換成外部 `CharType` 值的序列。
`do_length`	虛擬函式，決定特定外部`Byte`值序列中的值數目，不會產生超過指定數目`Byte`的內部`CharType`值，並傳回該數目`Byte`的值。
`do_max_length`	虛擬函式，傳回產生一個內部 `CharType` 所需的外部 Byte 數目上限。
`do_out`	名為的虛擬函式，可將內部 `CharType` 值序列轉換成外部 Bytes 序列。
`do_unshift`	稱為的虛擬函式，提供 `Byte` 狀態相依轉換中所需的值，以完成值序列 `Byte` 中的最後一個字元。
`encoding`	測試數據流的`Byte`編碼是否相依於狀態、所使用的值與`CharType`產生的值之間的`Byte`比率是否為常數，如果是，則判斷該比率的值。
`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();

傳回值

只有在每次呼叫或傳回 true 時，受保護的虛擬成員函式才會傳noconv回。do_out do_in

樣本版本一律會傳 true回。

範例

請參閱的 always_noconv範例，其會呼叫 do_always_noconv。

`codecvt::do_encoding`

虛擬函式，測試數據流的Byte編碼是否相依於狀態、所使用的值與CharType產生的值之間的Byte比率是否為常數，如果是，則判斷該比率的值。

virtual int do_encoding() const throw();

傳回值

此受保護的虛擬成員函式會傳回：

-1，如果型 extern_type 別序列的編碼方式相依於狀態。
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值序列中的值數目，不會產生超過指定數目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 的計數。

備註

受保護的虛擬成員函式會有效呼叫do_in( state, first1, last1, next1, buf, buf + len2, next2)狀態（狀態複本）、某些緩衝區buf和指標next1和 next2。

然後它會傳回 next2 - buf。它會計算來源序列在 [ first1， last1所定義的轉換數目上限，而不是大於 len2。

樣本版本一律會傳回和的last1 - first1len2小於。

範例

請參閱的 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
目的序列中第一個未變更的元素指標。

傳回值

此函式會傳回：

codecvt_base::error 如果狀態代表無效的狀態
codecvt_base::noconv (如果函式不會執行任何轉換)
codecvt_base::ok 如果轉換成功，則為
codecvt_base::partial 如果目的地不夠大，轉換才能成功

備註

受保護的虛擬成員函式會嘗試將來源專案 CharType（0）轉換成它儲存在 [ first2last2的目的地序列，但終止專案 Byte（0）除外。它一律會將目的序列中第一個未變更的元素指標儲存在 next2 中。

State 必須是新來源序列開頭的初始轉換狀態。此函式會視需要改變其預存值，以反映成功轉換的目前狀態。一般而言，轉換來源專案 CharType（0）會讓目前狀態處於初始轉換狀態。

範例

請參閱的 unshift範例，其會呼叫 do_unshift。

`codecvt::encoding`

測試數據流的Byte編碼是否相依於狀態、所使用的值與CharType產生的值之間的Byte比率是否為常數，如果是，則判斷該比率的值。

int encoding() const throw();

傳回值

如果傳回值為正數，該值就是產生CharType字元所需的常數字元數Byte。

此受保護的虛擬成員函式會傳回：

-1，如果型 extern_type 別序列的編碼方式相依於狀態。
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
可由成員函式傳回的位元組數目上限。

傳回值

代表轉換數目上限的整數，不得大於 [ 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';
}

`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
目的序列中第一個未變更的元素指標。

傳回值

此函式會傳回：

codecvt_base::error 如果 state 代表無效的狀態。
codecvt_base::noconv (如果函式不會執行任何轉換)。
codecvt_base::ok 如果轉換成功，則為。
codecvt_base::partial 如果目的地不夠大，無法成功轉換，則為。

備註

state 必須是新來源序列開頭的初始轉換狀態。此函式會視需要改變其預存值，以反映成功轉換的目前狀態。一般而言，轉換來源專案 CharType（0）會讓目前狀態處於初始轉換狀態。

此成員函式會傳回 do_unshift( state, first2, last2, next2 )。

另請參閱

<locale>
字碼頁
 地區設定名稱、語言和國家/地區字串
 C++ 標準程式庫中的執行緒安全

共用方式為

codecvt 類別

語法

參數

備註

建構函式

Typedefs

成員函式

需求

codecvt::always_noconv

傳回值

備註

範例

codecvt::codecvt

參數

備註

codecvt::do_always_noconv

傳回值

範例

codecvt::do_encoding

傳回值

範例

codecvt：:d o_in

參數

傳回值

備註

範例

codecvt::do_length

參數

傳回值

備註

範例

codecvt::do_max_length

傳回值

備註

範例

codecvt::do_out

參數

傳回值

備註

範例

codecvt::do_unshift

參數

傳回值

備註

範例

codecvt::encoding

傳回值

備註

範例

codecvt::extern_type

備註

codecvt：：in

參數

傳回值

備註

範例

codecvt::intern_type

備註

codecvt：：length

參數

傳回值

備註

範例

codecvt::max_length

傳回值

備註

範例

codecvt::out

參數

傳回值

備註

範例

codecvt::state_type

備註

codecvt：：unshift

參數

傳回值

備註

另請參閱

`codecvt` 類別

`codecvt::always_noconv`

`codecvt::codecvt`

`codecvt::do_always_noconv`

`codecvt::do_encoding`

`codecvt::do_length`

`codecvt::do_max_length`

`codecvt::do_out`

`codecvt::do_unshift`

`codecvt::encoding`

`codecvt::extern_type`

`codecvt::intern_type`

`codecvt::max_length`

`codecvt::out`

`codecvt::state_type`