C 行列 API の文字列処理関数

MATLAB の MEX ファイルにおける文字列の表現方法

C 行列 API でビルドされた C/C++ MEX 関数では、MATLAB^® 文字ベクトルは mxChar 型の mxArray であり、ロケールに依存しないデータ表現 (Unicode^® エンコード) を使用します。MATLAB は C スタイルの文字列を char 型として表現し、ユーザーのロケール設定で指定された文字エンコードスキームを使用します。

以下の C/C++ 行列 API 関数の文字列処理関数を使用することで、mxArrays と C スタイルの文字列の両方を扱えます。

mxCreateString — 入力文字列に初期化された mxChar mxArray を作成します。
mxArrayToString — mxChar mxArray を C スタイルの文字列にコピーします。マルチバイトにエンコードされた文字をサポートします。
mxGetString — mxChar mxArray を C スタイルの文字列にコピーします。シングルバイトにエンコードされた文字に最も適しています。文字列のバッファーサイズを計算する際は、マルチバイトにエンコードされた文字をサポートします。
mxGetChars — mxArray の 1 番目の mxChar 要素へのポインターを返します。

文字列の処理関数を選択する際は、以下のトピックを考慮してください。

文字エンコードスキームとマルチバイトエンコードスキーム

MATLAB は、ユーザーのロケール設定で指定された文字エンコードスキームをサポートします。MX ライブラリ関数が mxChar データを C の char 型に変換する際、MATLAB はその文字をユーザーの既定エンコードに変換します。

マルチバイトエンコードスキームを使用する場合、関数 mxArrayToString を使用してください。

関数 mxGetChars は mxChar 配列へのポインターを提供します。文字エンコードは変更しません。

また、関数 mxGetString もマルチバイトエンコードスキームで使用できます。mxGetString は mxChar データをユーザーの既定エンコードに変換し、変換した文字を格納先バッファーにコピーします。ただし、格納先バッファーのサイズを計算しなければなりません。シングルバイトエンコードでは、バッファーのサイズは文字数に null 終端文字用に 1 を追加した値となります。マルチバイトエンコードでは、文字サイズは 1 バイト以上です。バッファーサイズの計算オプションには、実際よりも大きめにサイズを推定するもの (文字数とエンコードスキームで使用されるバイトの最大数を乗算して計算)、文字列を解析して各文字が使用している正確なサイズを特定するものまたはサードパーティ製文字列バッファーライブラリを使用するものなどがあります。この計算の後、null 終端文字用に 1 を追加します。

C スタイルの文字列への MATLAB 文字ベクトルの変換

MEX 関数に文字配列を渡す場合、それは mxChar 型の mxArray です。C 関数を呼び出してその文字列を操作する場合、まず関数 mxArrayToString または関数 mxGetString を使用して、データを C の char 型に変換します。

MATLAB 文字ベクトルへの C スタイルの文字列の変換

MEX ファイルが C の文字列を作成し、そのデータを MATLAB に返す場合、関数 mxCreateString を使用して C の文字列を配列 mxChar にコピーします。

変更された入力文字列を返す

MEX ファイルが文字入力を取り、それを変更し、結果を返すと仮定します。MEX ファイルの入力パラメーター (配列 prhs) は読み取り専用であるため、変更された文字列を処理するための出力パラメーターを別に定義しなければなりません。

メモリ管理

MathWorks^® では、MEX ファイル関数が独自の一時的な配列を破棄し、動的に割り当てられた独自のメモリを解放することを推奨します。メモリの解放に使用する関数は、文字列バッファーの使い方とそのバッファーの作成に使用する関数に応じて異なります。

呼び出す関数	メモリ解放に使用する関数
ここにリストされている文字列関数のいずれか	ソース MEX ファイルの `mxArray` が以下の場合は、これを破棄しないでください。右辺のリスト `prhs[]` で MEX ファイルに渡される場合。左辺の引数リスト `plhs[]` に返される場合。関数 `mexGetVariablePtr` で返された場合。構造体の作成に使用される場合。
`mxArrayToString`	`mxFree`
`mxGetString`	`mxCalloc` / `mxMalloc` / `mxRealloc` を使用して入力引数 `buf` を作成する場合、`mxFree(buf)` を呼び出します。
`mxCreateString`	`mxDestroyArray`
`mxGetChars`	なし。関数は `mxArray` へのポインターを作成しますが、追加メモリは割り当てません。