mbrtoc16() — マルチバイト文字の char16_t 文字への変換
標準
| 標準/拡張機能 | C/C++ | 依存項目 |
|---|---|---|
ISO C 改訂 |
両方 | z/OS® V2R1 |
形式
#include <uchar.h>
size_t mbrtoc16(char16_t * restrict pc16,
const char * restrict s,
size_t n,
mbstate_t * restrict ps);機能説明
mbrtoc16() 関数は、マルチバイト文字を char16_t 型のワイド文字に変換し、マルチバイト文字のバイト数を戻します。
s が NULL ポインターでない場合、mbrtoc16() 関数は、s が示すバイトから始まる最大 n バイトを検査して、次のマルチバイト文字を完成するのに必要なバイト数を判別します (シフト・シーケンスを含む)。この関数は、次のマルチバイト文字が完成していて有効であると判断すると、対応するワイド文字の値を判別し、pc16 が NULL ポインターでなければ、該当する最初の (または唯一の) 文字を、pc16 が指すオブジェクトに保管します。以降の呼び出しは、すべての文字が保管されるまで、追加の入力を使用することなく、連続するワイド文字を保管します。対応するワイド文字が NULL ワイド文字の場合には、記述されている結果の状態は初期変換状態です。
s が NULL ポインターである場合、mbrtoc16() 関数は、mbrtoc16(NULL,"",1,ps) 呼び出しと同等になります。この場合、パラメーター pc16 および n の値は無視されます。
ps が NULL ポインターである場合、mbrtoc16() は独自の内部オブジェクトを使用してシフト状態をトラッキングします。そうでない場合、*ps は、有効な mbstate_t オブジェクトでなければなりません。mbstate_t オブジェクト *ps に 0 を割り当てるか、mbrtoc16(NULL,NULL,0,ps) を呼び出すことによって、このオブジェクトを初期状態に初期化できます。
使用上の注意
- mbrtoc16() 関数を使用するには、LANGLVL(EXTC1X) オプションを指定してソース・コードをコンパイルします。
- mbrtoc16() 関数は、Unicode Services によって提供される CCSID のみをサポートします。
- 複数の mbstate_t オブジェクト (内部のものを含む) を使用して、複数のストリングを 1 つのスレッドで交互に変換した結果は、未定義です。
戻り値
mbrtoc16() 関数は、該当する以降の文字の最初の文字を戻します (現在の変換状態が考慮されます)。
- 0
- 次の n 以下のバイト数によって、NULL ワイド文字に対応するマルチバイト文字が完成する場合 (これが、保管される値になります)。
- 1 から n まで
- 次の n 以下のバイト数によって、有効なマルチバイト文字が完成する場合 (これが、保管される値になります)。つまり、戻り値はマルチバイト文字を完成するバイト数となります。
- -3
- 前回の呼び出し結果である次の文字が保管された場合 (この呼び出しでは入力からのバイトは使用されていません)。
- -2
- 次の n バイトが不完全な (ただし有効である可能性もある) マルチバイト文字の原因となっていて、すべての n バイトが処理された場合 (値は保管されません)。n に少なくとも MB_CUR_MAX マクロの値があるときは、このケースが発生するのは、s が冗長シフト・シーケンスのシーケンス (状態に依存するエンコードによるインプリメンテーションのため) を指している場合のみです。
- -1
- エンコード・エラーが発生した場合 (次の n または それよりも少ないバイト数でさえ、完全で有効なマルチバイト文字の作成に使用できないとき)。EILSEQ マクロの値は errno に保管され、変換状態は未指定です。
例
#include <stdio.h>
#include <stdlib.h>
#include <uchar.h>
int main(void)
{
char16_t c16;
char mbs[] = "a" ; /* string containing the multibyte character */
mbstate_t ss = 0 ; /* set shift state to the initial state */
int length = 0 ;
/* Determine the length of the multibyte character pointed to by */
/* mbs. Store the multibyte character in the char16_t object */
/* called c16. */
length = mbrtoc16(&c16, mbs, MB_CUR_MAX, &ss);
if (length < 0) {
/* -2 and -3 return value could not happen during converting the 'a' */
perror("mbrtoc16() fails to convert");
exit(-1);
}
printf(" mbs:¥"%s¥"¥n", mbs);
printf(" length: %d ¥n", length);
printf(" c16: 0x%04hx ¥n", c16);
}出力:
mbs:"a"
length: 1
c16: 0x0061