mbrtoc16, mbrtoc32

將字串中的第一個 UTF-8 多位元組字元轉譯為對等的 UTF-16 或 UTF-32 字元。

語法

size_t mbrtoc16(
   char16_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

size_t mbrtoc32(
   char32_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

參數

destination
要 char16_t 轉換之 UTF-8 多位元組字元的或 char32_t 對等的指標。 如果為 null，則函式不會儲存值。

source
要轉換之 UTF-8 多位元組字元字串的指標。

max_bytes
source 的位元組數目上限，用來檢查是否有要轉換字元。 這個引數應該是介於一到位元組數目之間的值，包括任何 Null 結束字元，其餘在 中 source 。

state
mbstate_t轉換狀態物件的指標，用來將 UTF-8 多位元組字元串解譯為一或多個輸出字元。

傳回值

成功時會傳回適用條件中第一個條件的值，假設目前的 state 值是：

值	Condition
0	從 source 轉換的下一 max_bytes 個或更少字元會對應至 Null 寬字元，這是如果 destination 不是 Null，則儲存的值。 state 包含初始移位狀態。
介於 1 和 max_bytes(含) 之間	傳回的值是完成有效多位元組字元的 source 位元組數目。 如果 destination 不是 Null，則會儲存轉換的寬字元。
-3	如果 destination 不是 Null，則先前呼叫函式所產生的下一個寬字元已儲存在 中 destination 。 這個函式呼叫不會消耗 source 任何位元組。 當 source 指向需要一個以上的寬字元來表示的 UTF-8 多位元組字元時（例如代理字組），則會 state 更新值，讓下一個函式呼叫寫出額外的字元。
-2	下一個 max_bytes 位元組代表不完整但可能有效的 UTF-8 多位元組字元。 沒有任何值儲存在 destination中。 如果 max_bytes 為零就可能發生這個結果。
-1	發生了編碼錯誤。 下一 max_bytes 個或更少的位元組不會造成完整且有效的 UTF-8 多位元組字元。 沒有任何值儲存在 destination中。 EILSEQ 會儲存在 中 errno ，且轉換狀態值 state 未指定。

備註

函 mbrtoc16 式會從 讀取最多位元組 source ， max_bytes 以尋找第一個完整有效的 UTF-8 多位元組字元，然後將對等的 UTF-16 字元儲存在 中 destination 。 如果字元需要一個以上的 UTF-16 輸出字元，例如 Surrogate 配對，則 state 值會設定為在下一次呼叫 mbrtoc16 時，將下一個 UTF-16 字元儲存在 destination 中。 mbrtoc32 函式相同，但輸出儲存為 UTF-32 字元。

如果 source 為 null，則這些函式會針對 傳回使用 的引數 NULL""destination 所呼叫的對等呼叫，針對 傳回 的對等專案， source 針對 傳回 的 ，針對 max_bytes 傳回 1。 忽略 destination 和 max_bytes 傳遞的值。

如果 source 不是 Null，函式會從字串開頭開始，並檢查最多 max_bytes 位元組，以判斷完成下一個 UTF-8 多位元組字元所需的位元組數目，包括任何移位序列。 如果檢查的位元組包含有效且完整的 UTF-8 多位元組字元，函式會將字元轉換成相等的 16 位或 32 位寬字元或字元。 如果 destination 不是 Null，函式會將第一個結果字元儲存在目的地中。而且可能只有結果字元。 如果需要額外的輸出字元，則會在 中 state 設定值，以便後續呼叫函式輸出額外的字元，並傳回值 -3。 如果不需要更多輸出字元，則會將 state 設為初始移位狀態。

若要將非 UTF-8 多位元組字元轉換成 UTF-16 LE 字元，請使用 mbrtowc 、 mbtowc 或 _mbtowc_l 函式。

根據預設，此函式的全域狀態會限定于應用程式。 若要變更此行為，請參閱 CRT 中的全域狀態。

需求

函式	C 標頭	C++ 標頭
mbrtoc16, mbrtoc32	<uchar.h>	<cuchar>

如需相容性詳細資訊，請參閱相容性。

另請參閱

資料轉換
地區設定
多位元組字元序列的解譯
c16rtomb, c32rtomb
mbrtowc
mbsrtowcs
mbsrtowcs_s