std::codecvt_byname

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

文字處理庫

本地化庫

正則表示式庫 (C++11)

格式化庫 (C++20)

空終止序列工具

位元組字串

多位元組字串

寬字串

原生數值轉換

to_chars (C++17) to_chars_result (C++17) from_chars (C++17) from_chars_result (C++17) chars_format (C++17)

文字編碼標識

text_encoding (C++26)

 

本地化庫

區域設定和刻面 (Locales and facets)   區域設定 has_facet use_facet locale 刻面類別 (Facet category) 基類 (base classes) ctype_base codecvt_base messages_base time_base money_base ctype 刻面 ctype ctype<char> ctype_byname codecvt codecvt_byname 數字刻面 (numeric facets) num_get num_put numpunct numpunct_byname collate 刻面 collate collate_byname 時間刻面 (time facets) time_get time_put time_get_byname time_put_byname

貨幣刻面 (monetary facets) money_get money_put moneypunct moneypunct_byname messages 刻面 messages messages_byname 字元分類與轉換 字元分類 isspace    iscntrl isupper islower    isalpha ispunct isdigit    isxdigit isalnum isblank (C++11) isprint isgraph 字元轉換 toupper    tolower 字串和流轉換 wstring_convert (C++11/17/26*) wbuffer_convert (C++11/17/26*) Unicode 轉換刻面 codecvt_utf8 (C++11/17/26*) codecvt_utf16 (C++11/17/26*) codecvt_utf8_utf16 (C++11/17/26*) codecvt_mode (C++11/17/26*) C 庫區域設定 LC_ALLLC_COLLATELC_CTYPELC_MONETARYLC_NUMERICLC_TIME    setlocale localeconv lconv

 

定義於標頭檔案 <locale>
template< class InternT, class ExternT, class State > class codecvt_byname : public std::codecvt<InternT, ExternT, State>;

std::codecvt_byname 是一個 std::codecvt facet，它封裝了在其構造時指定的區域設定的多位元組/寬字元轉換規則。

特化

標準庫保證提供以下特化

定義於標頭檔案 <locale>
std::codecvt_byname<char, char, std::mbstate_t>	同一性轉換
std::codecvt_byname<char16_t, char, std::mbstate_t> (C++11 起)(C++20 中棄用)	UTF-16 和 UTF-8 之間的轉換
std::codecvt_byname<char16_t, char8_t, std::mbstate_t> (C++20 起)	UTF-16 和 UTF-8 之間的轉換
std::codecvt_byname<char32_t, char, std::mbstate_t> (C++11 起)(C++20 中棄用)	UTF-32 和 UTF-8 之間的轉換
std::codecvt_byname<char32_t, char8_t, std::mbstate_t> (C++20 起)	UTF-32 和 UTF-8 之間的轉換
std::codecvt_byname<wchar_t, char, std::mbstate_t>	寬字串和窄字元集之間的區域設定特定轉換

成員函式

(建構函式)	構造一個新的 codecvt_byname facet (public member function)
(解構函式)	銷燬一個 codecvt_byname facet (protected member function)

std::codecvt_byname::codecvt_byname

explicit codecvt_byname( const char* name, std::size_t refs = 0 );
explicit codecvt_byname( const std::string& name, std::size_t refs = 0 );		(C++11 起)

為具有 name 的區域設定構造一個新的 std::codecvt_byname facet。

refs 用於資源管理：如果 refs == 0，則當最後一個持有它的 std::locale 物件被銷燬時，實現會銷燬該 facet。否則，物件不會被銷燬。

引數

name	-	區域設定的名稱
refs	-	連結到 facet 的引用計數

std::codecvt_byname::~codecvt_byname

protected: ~codecvt_byname();

銷燬 facet。

繼承自 std::codecvt

巢狀型別

型別	定義
intern_type	internT
extern_type	externT
state_type	stateT

資料成員

成員	描述
std::locale::id id [static]	facet 的識別符號

成員函式

out	呼叫 do_out (std::codecvt<InternT,ExternT,StateT> 的公共成員函式)
in	呼叫 do_in (std::codecvt<InternT,ExternT,StateT> 的公共成員函式)
unshift	呼叫 do_unshift (std::codecvt<InternT,ExternT,StateT> 的公共成員函式)
encoding	呼叫 do_encoding (std::codecvt<InternT,ExternT,StateT> 的公共成員函式)
always_noconv	呼叫 do_always_noconv (std::codecvt<InternT,ExternT,StateT> 的公共成員函式)
length	呼叫 do_length (std::codecvt<InternT,ExternT,StateT> 的公共成員函式)
max_length	呼叫 do_max_length (std::codecvt<InternT,ExternT,StateT> 的公共成員函式)

受保護的成員函式

do_out [virtual]	將字串從 InternT 轉換為 ExternT，例如寫入檔案時 (std::codecvt<InternT,ExternT,StateT> 的虛保護成員函式)
do_in [virtual]	將字串從 ExternT 轉換為 InternT，例如從檔案讀取時 (std::codecvt<InternT,ExternT,StateT> 的虛保護成員函式)
do_unshift [virtual]	為不完整的轉換生成 ExternT 字元的終止字元序列 (std::codecvt<InternT,ExternT,StateT> 的虛保護成員函式)
do_encoding [virtual]	返回生成一個 InternT 字元所需的 ExternT 字元數（如果恆定） (std::codecvt<InternT,ExternT,StateT> 的虛保護成員函式)
do_always_noconv [virtual]	測試 facet 是否為所有有效引數值編碼同一性轉換 (std::codecvt<InternT,ExternT,StateT> 的虛保護成員函式)
do_length [virtual]	計算轉換為給定 InternT 緩衝區時將消耗的 ExternT 字串的長度 (std::codecvt<InternT,ExternT,StateT> 的虛保護成員函式)
do_max_length [virtual]	返回可以轉換為單個 InternT 字元的最大 ExternT 字元數 (std::codecvt<InternT,ExternT,StateT> 的虛保護成員函式)

繼承自 std::codecvt_base

巢狀型別	定義
enum result { ok, partial, error, noconv };	無作用域列舉型別

列舉常量	定義
ok	轉換完成，無錯誤
部分	並非所有源字元都已轉換
error	遇到無效字元
noconv	無需轉換，輸入和輸出型別相同

示例

此示例演示如何使用來自支援 GB18030 的區域設定的 codecvt facet 讀取 GB18030 編碼的檔案。

執行此程式碼

#include <fstream>
#include <iostream>
#include <locale>
#include <string>
 
int main()
{
    // GB18030 narrow multibyte encoding
    std::ofstream("text.txt") << "\x7a"              // letter 'z', U+007a
                                 "\x81\x30\x89\x38"  // letter 'ß', U+00df
                                 "\xcb\xae"          // CJK ideogram '水' (water), U+6c34
                                 "\x94\x32\xbc\x35"; // musical sign '𝄋' (segno), U+1d10b
 
    std::wifstream fin("text.txt");
    fin.imbue(std::locale(fin.getloc(),
              new std::codecvt_byname<wchar_t, char, std::mbstate_t>("zh_CN.gb18030")));
 
    for (wchar_t c; fin.get(c);)
        std::cout << std::hex << std::showbase << static_cast<unsigned>(c) << '\n';
}

可能的輸出

0x7a
0xdf
0x6c34
0x1d10b

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 21	C++98	標準庫不需要提供 任何 std::codecvt_byname 特化	需要兩個特化

參閱

codecvt

在字元編碼之間轉換，包括 UTF-8、UTF-16、UTF-32 (類模板)