mbrtowc | Programming Place Plus　Ｃ言語編　標準ライブラリのリファレンス

概要

マルチバイト文字をワイド文字に変換する。

ヘッダ

wchar.h

形式

size_t mbrtowc(wchar_t* restrict ws, const char* restrict s, size_t n, mbstate_t* restrict ps);

引数

ws

変換結果を受け取るメモリアドレス。受け取らない場合はヌルポインタでも良い。

s

変換対象のマルチバイト文字列。

n

変換する最大バイト数。

ps

変換状態を管理するオブジェクトへのポインタ。またはヌルポインタ。

戻り値

引数s が指すバイトから、引数n で指定したバイト数だけを調べ、それがマルチバイト文字として有効なバイト列であれば、マルチバイト文字を構成するバイト数を返す。それがヌル文字ならば 0 を返す。

マルチバイト文字として有効なバイト列でなければ、-1 を size_t型にキャストした値が返される。

詳細

mbstate_t型の引数が追加されていることを除けば、mbtowc関数と同じことを行う関数である。戻り値の内容は異なる。

引数ps は、マルチバイト文字の並びの現時点までの変換状態を管理しているオブジェクトを指す。引数ps をヌルポインタとした場合は、この関数が内部で持っている mbstate_t オブジェクトを使う。これは、プログラム開始時点で適切に初期化されている。

引数s がヌルポインタの場合、mbrtowc(NULL, "", 1, ps) のように呼び出した場合と同じ意味になる。

バイト列がマルチバイト文字を構成しているものと考え、引数 n で指定したバイト数分だけ調べる。マルチバイト文字が必要とする可能性がある最大バイト数は、ロケールによって異なるので、引数n には MB_CUR_MAX を指定することが多い。調べた範囲が、有効なマルチバイト文字を構成していれば、それに対応するワイド文字の値を決定し、その値を引数ws で指定した位置へ格納する。引数ws がヌルポインタの場合は格納せず処理を終える。

マルチバイト文字を構成するバイト列が無効であるとき、表現形式エラーが発生し、errno に EILSEQ が格納される。

注意

あくまで文字の変換なので、末尾に終端文字(L’\0’) は付加されない。

使用例

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

int main(void)
{
    const char mb[] = "あいうえお";

    // LC_CTYPE をネイティブロケールに変更
    if (setlocale(LC_CTYPE, "") == NULL) {
        fputs("ロケールの設定に失敗しました。\n", stderr);
        return EXIT_FAILURE;
    }

    wchar_t wc;
    mbstate_t mbstate = {0};
    int i = 0;

    for (;;) {
        const int result = (int)mbrtowc(&wc, &mb[i], MB_CUR_MAX, &mbstate);
        if (result > 0) {
            wprintf(L"%lc", wc);
            i += result;
        }
        else if (result == 0) {
            break;
        }
        else {
            fputs("無効なバイト列です。\n", stderr);
            break;
        }
    }
    wprintf(L"\n");
}

実行結果：

あいうえお

関連

mbstate_t型の引数を伴わない mbtowc関数がある。
逆方向の変換であるワイド文字からマルチバイト文字列への変換は、wcrtomb関数で行える。なお、終端文字のあるマルチバイト文字列からワイド文字列への変換は、mbstowcs関数で行える。

解説章