std::text_encoding

 

C++

編譯器支援

獨立式與託管式

語言

標準函式庫

標準函式庫標頭檔

具名要求

特性測試巨集 (C++20)

語言支援函式庫

概念函式庫 (C++20)

診斷函式庫

記憶體管理函式庫

元編程函式庫 (C++11)

通用公用程式函式庫

容器函式庫

疊代器函式庫

Ranges 函式庫 (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)

 

std::text_encoding

成員函式

建立

text_encoding::text_encoding

text_encoding::literal

text_encoding::environment

觀察器

text_encoding::mib

text_encoding::name

text_encoding::aliases

text_encoding::environment_is

輔助工具

text_encoding::comp-name

非成員函式

operator==(std::text_encoding)

成員型別

text_encoding::id

text_encoding::aliases_view

輔助類別

hash<std::text_encoding>

 

定義於標頭檔 <text_encoding>
struct text_encoding;		（C++26 起）

text_encoding 類別提供了一種識別字元編碼的機制。它用於在編譯期確定翻譯環境的一般字元字面量編碼，以及在執行期確定執行環境的字元編碼。

每個 text_encoding 物件都封裝了一種「字元編碼方案」，由 text_encoding::id 中的列舉值唯一標識，並對應一個以空字元結尾的位元組字串名稱。這些資訊可分別透過 mib() 和 name() 成員函式進行存取。物件所代表的是翻譯環境還是執行環境中實作的字元編碼方案，其判定方式由實作定義。

text_encoding 類別是一個 TriviallyCopyable（可平凡複製）型別。代表字元編碼方案名稱的陣列物件嵌套在 text_encoding 物件本身之中。儲存的名稱長度限制為最多 max_name_length 個字元，不包含空字元 '\0'。

該類別支援已註冊和未註冊的字元編碼。已註冊的編碼是指那些可在 IANA 字元集註冊表 (IANA Character Sets Registry) 中找到的編碼，但不包含以下字元編碼：

• NATS-DANO (33)
• NATS-DANO-ADD (34)。

此外，該類別還提供以下已註冊字元編碼的存取方式：

1. 主要名稱 (Primary name)：註冊表中指定的正式名稱。
2. 別名 (Aliases)：註冊表中別名的實作定義超集。
3. MIBenum 值：用於識別編碼字元編碼的唯一識別碼。

未註冊的編碼可以使用列舉值 id::other 或 id::unknown 配合自訂名稱來表示。

若 text_encoding 物件 e 的 MIBenum 值既不是 id::other 也不是 id::unknown，則它必須滿足下列恆常性 (invariants)：

• *e.name() != '\0' 為 true，且
• e.mib() == std::text_encoding(e.name()).mib() 為 true。

成員型別

id	表示字元編碼的 MIBenum 值 (公開成員列舉)
aliases_view	一個關於字元編碼別名的 view (公開成員類別)

成員常數

名稱	數值
constexpr std::size_t max_name_length [靜態]	63 (公開靜態成員常數)

資料成員

成員	描述
std::text_encoding::id mib_ (私有)	一個 MIBenum 值，預設為 id::unknown (僅用於闡述的成員物件*)
char[max_name_length + 1] name_ (私有)	儲存的主要名稱 (僅用於闡述的成員物件*)

成員函式

建立
(建構子)	建構新的 text_encoding 物件 (公開成員函式)
literal [靜態]	建構一個代表一般字元字面量編碼的新的 text_encoding (公開靜態成員函式)
environment [靜態]	建構一個代表執行環境之實作定義字元編碼方案的新的 text_encoding (公開靜態成員函式)
觀察器
mib	傳回目前字元編碼的 MIBenum 值 (公開成員函式)
name (名稱)	傳回目前字元編碼的主要名稱 (公開成員函式)
aliases	傳回一個關於目前字元編碼別名的 view (公開成員函式)
environment_is [靜態]	以指定的 MIB 值檢查執行環境的字元編碼方案 (公開靜態成員函式)
輔助工具
comp-name [靜態](私有)	使用字元集別名匹配 (Charset Alias Matching) 比較兩個別名名稱 (僅供展示的靜態成員函式*)

非成員函式

operator==(std::text_encoding) (C++26)

比較兩個 text_encoding 物件。 (公開成員函式)

輔助類別

std::hash<std::text_encoding> (C++26)

std::text_encoding 的雜湊 (hash) 支援 (類別樣板特例化)

附註

處理字元編碼時，務必注意：當使用 Unicode 技術標準所述的字元集別名匹配進行比較時，兩個不同已註冊字元編碼的主要名稱或別名是不相等的。

為方便起見，text_encoding::id 的列舉值被引入為 text_encoding 的成員，可直接存取。這意味著 text_encoding::ASCII 和 text_encoding::id::ASCII 指向的是同一個實體。

建議實作將已註冊的編碼視為不可互換的。此外，除非有明確的先例，否則不應使用已註冊編碼的主要名稱來描述類似但不同的未註冊編碼。

功能測試巨集	數值	標準	功能
__cpp_lib_text_encoding	202306L	(C++26)	std::text_encoding

範例

執行此程式碼

#include <locale>
#include <print>
#include <text_encoding>
 
int main()
{
    // literal encoding is known at compile-time
    constexpr std::text_encoding literal_encoding = std::text_encoding::literal();
 
    // check for literal encoding
    static_assert(literal_encoding.mib() != std::text_encoding::other &&
                  literal_encoding.mib() != std::text_encoding::unknown);
 
    // environment encoding is only known at runtime
    std::text_encoding env_encoding = std::text_encoding::environment();
 
    // associated encoding of the default locale
    std::text_encoding locale_encoding = std::locale("").encoding();
 
    std::println("The literal encoding is {}", literal_encoding.name());
    std::println("The aliases of literal encoding:");
    for (const char* alias_name : literal_encoding.aliases())
        std::println(" -> {}", alias_name);
 
    if (env_encoding == locale_encoding)
        std::println("Both environment and locale encodings are the same");
 
    std::println("The environment encoding is {}", env_encoding.name());
    std::println("The aliases of environment encoding:");
    for (const char* alias_name : env_encoding.aliases())
        std::println(" -> {}", alias_name);
}

可能輸出

The literal encoding is UTF-8
The aliases of literal encoding:
 -> UTF-8
 -> csUTF8
Both environment and locale encodings are the same
The environment encoding is ANSI_X3.4-1968
The aliases of environment encoding:
 -> US-ASCII
 -> iso-ir-6
 -> ANSI_X3.4-1968
 -> ANSI_X3.4-1986
 -> ISO_646.irv:1991
 -> ISO646-US
 -> us
 -> IBM367
 -> cp367
 -> csASCII
 -> ASCII

參見

locale

封裝文化差異的多型 facet 集合 (類別)