c16rtomb

 

C

編譯器支援

語言

標頭檔案

型別支援

程式工具

變參函式支援

錯誤處理

動態記憶體管理

字串庫

演算法

數值

日期和時間工具

輸入/輸出支援

本地化支援

併發支援 (C11)

技術規範

符號索引

 

字串庫

空終止位元組字串

空終止多位元組字串

空終止寬字串

 

空終止多位元組字串

函式
寬字元/多位元組轉換
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)   mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
型別
mbstate_t (C95) char8_t (C23)	char16_t (C11) char32_t (C11)
宏
MB_LEN_MAX	MB_CUR_MAX

 

在標頭檔案 <uchar.h> 中定義
size_t c16rtomb( char* restrict s, char16_t c16, mbstate_t* restrict ps );		(C11 起)

將單個碼點從其可變長度的16位寬字元表示（通常是 UTF-16）轉換為其窄多位元組字元表示。

如果 s 不是空指標，並且 c16 是碼點有效可變長度編碼中的最後一個16位程式碼單元，則函式確定儲存該碼點多位元組字元表示所需的位元組數（包括任何移位序列，並考慮當前的多位元組轉換狀態 *ps），並將多位元組字元表示儲存在第一個元素由 s 指向的字元陣列中，同時根據需要更新 *ps。此函式最多可以寫入 MB_CUR_MAX 位元組。

如果 s 是空指標，則此呼叫等同於 c16rtomb(buf, u'\0', ps)，其中 buf 是某個內部緩衝區。

如果 c16 是空寬字元 u'\0'，則儲存一個空位元組，前面是任何必要的移位序列以恢復初始移位狀態，並且轉換狀態引數 *ps 會更新以表示初始移位狀態。

如果 c16 不是寬字元16位表示中的最後一個程式碼單元，則它不會寫入 s 所指向的陣列，只更新 *ps。

如果宏 __STDC_UTF_16__ 已定義，則此函式使用的16位編碼是 UTF-16；否則，它是實現定義的。該宏始終定義，編碼始終是 UTF-16。(自 C23 起) 無論如何，此函式使用的多位元組字元編碼由當前活動的 C 語言環境指定。

引數

s	-	指向窄字元陣列的指標，多位元組字元將儲存在此處
c16	-	要轉換的16位寬字元
ps	-	指向轉換狀態物件的指標，用於解釋多位元組字串

返回值

成功時，返回寫入到第一個元素由 s 指向的字元陣列中的位元組數（包括任何移位序列）。此值可能為 ​0​，例如在處理多 char16_t 單元序列中的前導 char16_t 單元時（在處理 UTF-16 代理對中的前導代理時發生）。

失敗時（如果 c16 不是有效的16位程式碼單元），返回 -1，將 EILSEQ 儲存在 errno 中，並使 *ps 處於未指定狀態。

注意

在已釋出的 C11 中，與 mbrtoc16 不同，後者將可變寬度多位元組（例如 UTF-8）轉換為可變寬度16位（例如 UTF-16）編碼，此函式只能轉換單單元16位編碼，這意味著它無法將 UTF-16 轉換為 UTF-8，儘管這是此函式的最初意圖。C11 後的缺陷報告 DR488 糾正了這一點。

示例

注意：此示例假定已應用缺陷報告 DR488 的修復。
在 MSVC 上，您可能需要 /utf-8 編譯器標誌才能使 UTF_8 正常工作。

執行此程式碼

#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <uchar.h>
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char16_t in[] = u"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    const size_t in_sz = sizeof in / sizeof *in;
 
    printf("Processing %zu UTF-16 code units: [", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%s%04X", n ? " " : "", in[n]);
    puts("]");
 
    char* out = malloc(MB_CUR_MAX * in_sz);
    char* p = out;
    mbstate_t state = {0};
 
    for (size_t n = 0; n < in_sz; ++n)
    {
        size_t rc = c16rtomb(p, in[n], &state);
        if (rc == (size_t)-1)
            break;
        p += rc;
    }
 
    size_t out_sz = p - out;
    printf("into %zu UTF-8 code units: [", out_sz);
    for (size_t x = 0; x < out_sz; ++x)
        printf("%s%02X", x ? " " : "", +(unsigned char)out[x]);
    puts("]");
    free(out);
}

輸出

Processing 6 UTF-16 code units: [007A 00DF 6C34 D83C DF4C 0000]
into 13 UTF-8 code units: [7A C3 9F E6 B0 B4 ED A0 BC ED BD 8C 00]

參考資料

• C23 標準 (ISO/IEC 9899:2024)

• 7.28.1.2 The c16rtomb function (p: TBD)

• C17 標準 (ISO/IEC 9899:2018)

• 7.28.1.2 The c16rtomb function (p: TBD)

• C11 標準 (ISO/IEC 9899:2011)

• 7.28.1.2 The c16rtomb function (p: 399-400)

參閱

mbrtoc16 (C11)	將窄多位元組字元轉換為 UTF-16 編碼 (function)
C++ documentation for c16rtomb