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

本記事では、C++ STLに用意されているstd::mbrtoc32()関数について、その仕組み・構文・具体的な使用例を交えながら詳しく解説します。

std::mbrtoc32()とは？

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

関連する文字ポインタがNULLでなく、その他のパラメータも適切に指定されていれば、対応する32ビット文字への変換が実行されます。

構文

size_t mbrtoc32( char32_t* pc32, char* str, size_t n, mbstate_t* ps);

パラメータ

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

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

戻り値

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

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

使用例1

#include <cstdio>
#include <cstdlib>
#include <iostream>
#include <uchar.h>
#include <wchar.h>
using namespace std;
int main(void) {
    char32_t hold;
    char str[] = "I";
    mbstate_t arr{};
    int len;
    // 関数の初期化
    len = mbrtoc32(&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("32-bit character = 0g%02hd\n", hold);
}

出力結果

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

使用例2

#include <cstdio>
#include <cstdlib>
#include <iostream>
#include <uchar.h>
#include <wchar.h>
using namespace std;
int main(void){
    char32_t hold;
    char str[] = "I";
    mbstate_t arr{};
    int len;
    // 関数の初期化
    len = mbrtoc32(&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("32-bit character = 0x%08hx\n", hold);
}

出力結果

String is: I
Length is: 1
32-bit character = 0x00000049

まとめ

std::mbrtoc32()関数は、マルチバイト文字列をUTF-32形式に変換するための重要な関数です。戻り値の意味（0、正の値、-1、-2、-3）を正しく理解することで、変換の進行状況やエラー状態を適切に判定できます。国際化対応のプログラムやUnicode文字列を扱う際にぜひ活用してください。