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

トップページC言語編標準ライブラリのリファレンス(名前順)

トップページC言語編標準ライブラリのリファレンス(ヘッダ別)


c16rtomb

概要

char16_t型の文字をマルチバイト文字列に変換する。

ヘッダ

uchar.h

形式

size_t c16rtomb(char* s, char16_t c16, mbstate_t* ps);

引数

s

変換結果を受け取るメモリアドレス。最低でも MB_CUR_MAX以上の要素数が必要。
受け取らない場合は、ヌルポインタでも良い。

c16

変換対象の char16_t型の文字。

ps

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

戻り値

引数c16 がマルチバイト文字に変換可能であれば、引数s が指す先へ格納されたマルチバイト文字のバイト数を返す。変換可能でなければ -1 を size_t型にキャストした値を返す。

返される大きさはつねに、MB_CUR_MAX 以下である。

詳細

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

引数s がヌルポインタの場合、c16rtomb(内部バッファ, L'\\0', ps) のように呼び出した場合と同じ意味になる。「内部バッファ」は c16rtomb関数内部にあるバッファのことを意味する。

char16_t型の文字を、対応するマルチバイト文字のバイト列へ変換する。文字数としては、いずれにしても1文字であるが、マルチバイト文字としては何バイト必要とするか分からないので、char型の配列で受け取る。

引数w にヌル文字を指定した場合、mbstate_t オブジェクトの変換状態が初期状態に戻される。

変換結果が正しいマルチバイト文字列にならない場合、表現形式エラーが発生し、errnoEILSEQ が格納される。

この関数は、ロケールの LC_CTYPE カテゴリの影響を受ける。

注意

あくまで文字の変換なので、末尾に終端文字(u’\0’) は付加されない。
Visual Studio 2017 で確認すると、ネイティブロケールではマルチバイト文字のエンコーディングエラーは Shift_JIS (CP932) であるが、その状態でこの関数を呼び出しても、変換結果は UTF-8 になるようである。

使用例

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

int main(void)
{
    const char16_t c16 = u'多';
    char mb[MB_LEN_MAX + 1];  // 全ロケールで可能性がある最大の大きさ + 末尾の '\0'
    mbstate_t mbstate = {0};
    size_t result;

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

    result = c16rtomb(mb, c16, &mbstate);
    if (result == (size_t)-1) {
        fputs("マルチバイト文字への変換に失敗しました。\n", stderr);
        return EXIT_FAILURE;
    }

    mb[result] = '\0';
    printf("%s\n", mb);
}

実行結果:

関連 逆方向の変換であるマルチバイト文字から char16_t型の文字への変換は、mbrtoc16関数で行える。
解説章


参考リンク


更新履歴

’2019/2/12 VisualStudio 2015 の対応終了。

’2018/7/5 新規作成。



標準ライブラリのリファレンス(名前順)のトップページへ

標準ライブラリのリファレンス(ヘッダ別)のトップページへ

C言語編のトップページへ

Programming Place Plus のトップページへ



はてなブックマーク に保存 Pocket に保存 Facebook でシェア
X で ポストフォロー LINE で送る noteで書く
rss1.0 取得ボタン RSS 管理者情報 プライバシーポリシー
先頭へ戻る