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
変換する UTF-8 マルチバイト文字と等価の char16_t または char32_t 文字へのポインター。 null の場合、関数では値を格納しません。

source
変換する UTF-8 マルチバイト文字列へのポインター。

max_bytes
変換する文字を検査する source 内の最大バイト数。 この引数は、1 から、 sourceに残っている null ターミネータを含むバイト数の間の値である必要があります。

state
UTF-8 マルチバイト文字列を 1 つ以上の出力文字に解釈するために使用する、 mbstate_t 変換状態オブジェクトへのポインター。

戻り値

成功した場合、次の条件のうち、現在の state 値の場合に当てはまる最初の値を返します。

Value	条件
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 出力文字が必要な場合、state値は、次の mbrtoc16 呼び出しのdestinationに次の UTF-16 文字を格納するように設定されます。 mbrtoc32 関数は同一ですが、出力は UTF-32 文字として格納されます。

sourceが null の場合、これらの関数は、destinationのNULLの引数、source の"" (空の null で終わる文字列)、およびmax_bytesの場合は 1 を使用して行われた呼び出しと同等の呼び出しを返します。 destination と max_bytes に渡した値は無視されます。

sourceが null でない場合、関数は文字列の先頭から開始し、最大max_bytes バイトを検査して、シフト シーケンスを含む、次の UTF-8 マルチバイト文字を完了するために必要なバイト数を決定します。 検査したバイトの中に正しくかつ完全な UTF-8 マルチバイト文字が含まれる場合、関数では、その文字を等価の 16 ビットまたは 32 ビットの 1 つまたは複数のワイド文字に変換します。 destinationが null でない場合、関数は最初の結果文字 (および場合によってはのみ) を宛先に格納します。 追加の出力文字が必要な場合は、 stateに値が設定されるため、後続の関数の呼び出しで余分な文字が出力され、値 -3 が返されます。 出力文字がこれ以上必要ない場合、 state は初期のシフト状態に設定されます。

UTF-8 以外のマルチバイト文字を UTF-16 LE 文字に変換するには、 mbrtowc、 mbtowc、または_mbtowc_l 関数を使用します。

既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 この動作を変更するには、「CRT でのグローバル状態」を参照してください。

要件

機能	C ヘッダー	C++ ヘッダー
mbrtoc16, mbrtoc32	<uchar.h>	<cuchar>

互換性の詳細については、「 Compatibility」を参照してください。

関連項目

データ変換
ロケール
マルチバイト文字のシーケンスの解釈
c16rtomb, c32rtomb
mbrtowc
mbsrtowcs
mbsrtowcs_s