C/C++のmbrtoc16()関数とは？構文・戻り値・使用例をわかりやすく解説

この記事では、C++ STLにおけるstd::mbrtoc16()関数の仕組み、構文、そして具体的な使用例について詳しく解説します。

std::mbrtoc16()とは？

std::mbrtoc16()は、C++ STLに標準で用意されている組み込み関数の一つで、<cuchar>ヘッダーファイルに定義されています。この関数は、ナローマルチバイト文字をUTF-16形式の文字表現へと変換するために使用されます。

関連付けられた文字ポインタがNULLでなく、その他のパラメータもすべて正しく指定されていれば、対応する16ビット文字への変換が実行されます。

構文

size_t mbrtoc16( char16_t* pc16, char* str, size_t n, mbstate_t* ps);

パラメータ

この関数は、以下のパラメータを受け取ります。

• pc16 − 変換結果を格納する出力先へのポインタです。
• str − 入力として使用される文字列です。
• n − 検証対象となるバイト数です。
• ps − マルチバイト文字列を解釈する際に使用される状態オブジェクト（mbstate_t）へのポインタです。

戻り値

この関数の戻り値は、以下の条件に応じて異なります。

• 0 − str内の変換対象の文字がNULL文字（終端文字）である場合に返されます。
• 1…n − 文字列*strから変換されたマルチバイト文字のバイト数です。
• -3 − サロゲートペアが存在する場合、つまりchar16_tが複数のchar16_tで構成される文字の一部である場合に返されます。このとき、入力から新たに消費されるバイトはありません。
• -2 − 次のnバイトが不完全であるものの、そこまでの部分は有効なマルチバイト文字である場合に返されます。
• -1 − エンコーディングエラーが発生した場合に返され、*pc16には何も書き込まれません。

使用例

#include <cstdio>
#include <cstdlib>
#include <iostream>
#include <uchar.h>
#include <wchar.h>
using namespace std;
int main(void){
    char16_t hold;
    char str[] = "I";
    mbstate_t arr{};
    int len;
    // 関数を初期化して呼び出し
    len = mbrtoc16(&hold, str, MB_CUR_MAX, &arr);
    if (len < 0) {
       perror("conversion failed");
       exit(-1);
    }
    cout << "String is: " << str << endl;
    cout << "Length is: " << len << endl;
    printf("16-bit character = 0g%02hd\n", hold);
}

実行結果

String is: I
Length is: 1
16-bit character = 0g73