mbrtowc() — マルチバイト文字をワイド文字へ変換する (再始動可能)

オンライン編集

形式

#include <wchar.h>
size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

言語レベル

ANSI

スレッド・セーフ

はい (ps が NULL 以外の場合)。

ロケール依存

この関数の振る舞いは、現行ロケールの LC_CTYPE カテゴリーの影響を受ける可能性があります。 この関数は、LOCALETYPE(*LOCALEUCS2) または LOCALETYPE(*LOCALEUTF) をコンパイル・コマンドで指定した場合も、現行ロケールの LC_UNI_CTYPE カテゴリーによって影響を受ける可能性があります。 この関数は、コンパイル・コマンドに対して LOCALETYPE(*CLD) が指定されている場合には使用できません。 詳しくは、 CCSID とロケールについてを参照してください。

ワイド文字関数

詳しくは、 ワイド文字 を参照してください。

説明

この関数は、 mbtowc() 関数の再始動可能バージョンです。

s が NULL ポインターの場合、 mbrtowc() 関数は初期シフト状態に入るために必要なバイト数を判別します (エンコードが状態依存でない場合、または初期変換状態が記述されている場合は、ゼロになります)。 この状態において、pwc パラメーターの値は無視され、結果として、記述されているシフト状態が初期変換状態となります。

s が NULL ポインターでない場合、 mbrtowc() 関数は、 sが指すマルチバイト文字 (および先行シフト・シーケンス) 内のバイト数を判別し、対応するマルチバイト文字の値を生成します。 pwc が NULL ポインターでない場合は、その値を pwcが指すオブジェクトに保管します。 対応するマルチバイト文字が NULL ワイド文字の場合には、結果の状態は初期変換状態にリセットされます。

この関数は、対応する内部状態のマルチバイト文字関数とは以下の点で異なります。 この関数には追加のパラメーターとして mbstate_t の型を指す ps ポインター があり、このポインターは、関連するマルチバイト文字シーケンスの現在の変換状態を完全に表すことができる オブジェクトを指します。 ps が NULL の場合、この関数は内部の静的変数を状態に使用します。

最大で、n バイトのマルチバイト・ストリングが検証されます。

戻り値

s が NULL ポインターの場合、 mbrtowc() 関数は初期シフト状態に入るのに必要なバイト数を戻します。 戻り値は MB_CUR_MAX マクロ未満でなければなりません。

変換エラーが発生した場合、errno は ECONVERT に設定される可能性があります。

s が NULL ポインターでない場合、 mbrtowc() 関数は以下のいずれかを戻します。
0
続く n 以下のバイト数によって、NULL ワイド文字に対応するマルチバイト文字が形成される場合。
正の値
続く n 以下のバイト数によって、有効なマルチバイト文字が形成される場合。 戻り値は、マルチバイト文字を構成するバイト数です。
(size_t)-2
次の n バイトが不完全な (ただし有効である可能性もある) マルチバイト文字を形成し、すべて の n バイトが処理された場合。 n の値が MB_CUR_MAX マクロの値よりも小さい場合、これが起こるかどうかは指定されていません。
(size_t)-1
エンコード・エラーが発生した場合 (次の n または数バイトが完全で正確なマルチバイト文字を形成しないとき)。 EILSEQ マクロの値は errno に保管されるが、変換状態は未変更のままになります。
注意: -2の値が返された場合、文字列には冗長なシフトアウト文字やシフトイン文字、あるいは部分的なUTF-8文字が含まれている可能性があります。 マルチバイト・ストリングの処理を続行するには、ポインターを値 nだけ増分し、再度 mbrtowc() を呼び出します。

例

/* This program is compiled with LOCALETYPE(*LOCALE) and   */
/* SYSIFCOPT(*IFSIO)                                       */

#include  <stdio.h>
#include  <stdlib.h>
#include  <locale.h>
#include  <wchar.h>
#include  <errno.h>

#define  LOCNAME     "/qsys.lib/JA_JP.locale"
#define  LOCNAME_EN  "/qsys.lib/EN_US.locale"

int main(void)
{
    int length, sl = 0;
    char  string[10];
    wchar_t buffer[10];
    mbstate_t ps = 0;
    memset(string, '\0', 10);
    string[0] = 0xC1;
    string[1] = 0x0E;
    string[2] = 0x41;
    string[3] = 0x71;
    string[4] = 0x41;
    string[5] = 0x72;
    string[6] = 0x0F;
    string[7] = 0xC2;
    /* In this first example we will convert                  */
    /* a multibyte character when the CCSID of locale         */
    /* associated with LC_CTYPE is 37.                        */
    /* For single byte cases the state will always            */
    /* remain in the initial state  0                         */

    if (setlocale(LC_ALL, LOCNAME_EN) == NULL)
        printf("setlocale failed.\n");

    length = mbrtowc(buffer, string, MB_CUR_MAX, &ps);

    /* In this case length is 1, and C1 is converted 0x00C1   */

    printf("length = %d, state = %d\n\n", length, ps);
    printf("MB_CUR_MAX: %d\n\n", MB_CUR_MAX);

    /* Now lets try a multibyte example.  We first must set the */
    /* locale to a multibyte locale.  We choose a locale with     */
    /* CCSID 5026  */

    if (setlocale(LC_ALL, LOCNAME) == NULL)
        printf("setlocale failed.\n");

    length = mbrtowc(buffer, string, MB_CUR_MAX, &ps);

    /* The first is single byte so length is 1 and             */
    /* the state is still the initial state 0.  C1 is converted*/
    /* to 0x00C1     */

    printf("length = %d, state = %d\n\n", length, ps);
    printf("MB_CUR_MAX: %d\n\n", MB_CUR_MAX);

    sl += length;

    length = mbrtowc(&buffer[1], &string[sl], MB_CUR_MAX, &ps);

    /* The next character is a mixed byte.  Length is 3 to     */
    /* account for the shiftout 0x0e.  State is                */
    /* changed to double byte state.  0x4171 is copied into    */
    /* the buffer   */

    printf("length = %d, state = %d\n\n", length, ps);

    sl += length;

    length = mbrtowc(&buffer[2], &string[sl], MB_CUR_MAX, &ps);

    /* The next character is also a double byte character.     */
    /* The state is changed to initial state since this was   */
    /* the last double byte character.  Length is 3 to         */
    /* account for the ending 0x0f shiftin.  0x4172 is copied  */
    /* into the buffer.  */

    printf("length = %d, state = %d\n\n", length, ps);

    sl += length;

    length = mbrtowc(&buffer[3], &string[sl], MB_CUR_MAX, &ps);

    /* The next character is single byte so length is 1 and    */
    /* state remains in initial state.  0xC2 is converted to   */
    /* 0x00C2.   The buffer now has the value:                 */
    /* 0x00C14171417200C2                                      */

    printf("length = %d, state = %d\n\n", length, ps);

}
/*  The output should look like this:

length = 1, state = 0

MB_CUR_MAX: 1

length = 1, state = 0

MB_CUR_MAX: 4

length = 3, state = 2

length = 3, state = 0

length = 1, state = 0
                                   */

関連情報