C/C++のmbsrtowcs()関数とは？構文・パラメータ・戻り値と実例を解説

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

std::mbsrtowcs()とは？

std::mbsrtowcs()は、C++ STLに組み込まれている関数で、<cwchar>ヘッダーファイル内で定義されています。関数名のmbsrtowcs()は「multibyte string to wide character string（マルチバイト文字列からワイド文字列への変換）」を意味し、再開可能な変換状態を維持しながら、NULL終端されたマルチバイト文字列をワイド文字列表現へと変換します。この関数は、変換の結果に応じた値を返します。

構文

size_t mbsrtowcs( wchar_t* pwc, char** str, size_t n, mbstate_t* ps);

パラメータ

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

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

戻り値

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

• 0 − 変換対象の文字列strがNULLである場合に返されます。
• 1〜n − NULL終端までに正常に変換されたワイド文字の数を返します。
• -1 − 変換中にエラーが発生した場合に返され、その際errnoにはEILSEQが設定されます。

使用例1：マルチバイト文字列をワイド文字列へ変換する

#include <bits/stdc++.h>
using namespace std;
int main(){
    setlocale(LC_ALL, "en_US.utf8");
    const char* ch = "\u0777\u0755";
    wchar_t arr[20];
    mbstate_t hold = mbstate_t();
    int highest = 10;
    int val = mbsrtowcs ( arr, &ch, highest, &hold );
    wcout << L"Wide characters are: "<< val << endl;
    wcout << L"Given Wide character is: " << arr << endl;
    return 0;
}

出力

Wide characters are: 2
Given Wide character is: ݷݕ

この例では、Unicodeの拡張アラビア文字領域に属する2文字（\u0777と\u0755）をマルチバイト文字列として定義し、mbsrtowcs()を使ってワイド文字列へ変換しています。出力結果から、2つのワイド文字が正常に変換されたことが確認できます。

使用例2：UTF-8文字列をワイド文字列へ変換する

#include <bits/stdc++.h>
using namespace std;
int main() {
   setlocale(LC_ALL, "en_US.utf8");
   const char* ch = u8"z\u00df\u6c34";
   wchar_t arr[20];
   mbstate_t hold = mbstate_t();
   int highest = 10;
   int val = mbsrtowcs ( arr, &ch, highest, &hold );
   wcout << L"Total Wide characters are: "<< val << endl;
   wcout << L"Given Wide character is: " << arr << endl;
   return 0;
}

出力

Total Wide characters are: 3
Given Wide character is: zß水

この例では、UTF-8文字列リテラル「u8"z\u00df\u6c34"」（ラテン文字のz、ドイツ語のエスツェットß、漢字の水）を変換対象としています。マルチバイト文字を含む3文字が、それぞれ正しくワイド文字へ変換されていることがわかります。

まとめ

mbsrtowcs()関数は、ロケール設定に依存してマルチバイト文字列をワイド文字列へ変換するため、使用前にsetlocale()で適切なロケールを設定することが重要です。また、mbstate_t型の状態オブジェクトを利用することで、変換の途中状態を管理でき、文字列を分割して段階的に処理する場合にも対応できます。