MATLAB データ

MATLAB 配列

MATLAB^® 言語が使用可能なオブジェクト型は、唯一、MATLAB 配列のみです。スカラー、ベクトル、行列、文字配列、cell 配列、構造体およびオブジェクトを含むすべての MATLAB 変数は、MATLAB 配列として保存されます。C/C++ では、MATLAB 配列は mxArray 型として宣言されます。mxArray 構造体には配列に関する以下の情報が含まれます。

• 型

• 次元

• 配列に関連付けられたデータ

• 数値の場合は、変数が実数か複素数か

• スパースの場合は、インデックス、およびゼロ以外の最大要素

• 構造体またはオブジェクトの場合は、フィールド数とフィールド名

mxArray 構造体にアクセスするには、C または Fortran の行列 API の関数を使用します。これらの関数により、MEX ファイルの MATLAB データに関する情報を作成し、読み取り、クエリすることができます。移植性の問題を回避し、MEX ソース ファイルがすべてのシステムで正しくコンパイルされるように、行列 API では mwSize 型と mwIndex 型を使用しています。

mxArray のライフサイクル

MATLAB 関数と同じく、MEX ファイルのゲートウェイ ルーチンでは参照によって MATLAB 変数を受け渡します。ただし、これらの引数は C のポインターです。変数への "ポインター" は、変数の "アドレス" (メモリ内の位置) です。MATLAB 関数ではデータ ストレージが自動的に処理されます。データを MEX ファイルに受け渡すときにはポインターを使用します。ポインターは、変数へのアクセスや変数の操作に際して固有の規則に従います。ポインターの操作の詳細は、Kernighan, B. W および D. M. Ritchie 著『The C Programming Language』などのプログラミングの参考書を参照してください。

メモ

変数ではメモリが使用されるので、MEX ファイルによる mxArray の作成方法とメモリの解放責任について理解しておく必要があります。これはメモリ リークを回避するために重要です。mxArray のライフサイクルとメモリ管理の規則は、それが入力引数、出力引数またはローカル変数のいずれであるかに依存します。mxArray の割り当てを解除するために呼び出す関数は、その作成に使用した関数によって異なります。詳細については、C 行列 API で配列を作成する関数を検索してください。

入力引数 prhs

mxArray は入力パラメーター prhs を通じて MEX ファイルに引き渡されますが、これは MEX ファイルのスコープ外に存在します。prhs パラメーター内にある mxArray のメモリは解放しないようにしてください。また、変数 prhs は読み取り専用です。MEX ファイル内では変更しないでください。

出力引数 plhs

mxArray (メモリ割り当てとデータ作成) を出力引数として作成する場合、そのメモリとデータは MEX ファイルのスコープ外に存在します。出力パラメーター plhs に返された mxArray のメモリは解放しないようにしてください。

ローカル変数

mxArray を作成するために関数 mxCreate* を使用する場合や、mxCalloc および関連する関数を呼び出す場合には常にメモリを割り当てます。入力引数と出力引数の処理規則を遵守した後、MEX ファイルでは一時的な配列を破棄し、動的に割り当てられたメモリを解放する必要があります。メモリ割り当てを解除するには、mxDestroyArray または mxFree を使用します。使用する関数の詳細については、MX 行列ライブラリを参照してください。

データの保存

MATLAB は、列優先 (列方向) の番号付けスキームでデータを保存します。これは Fortran が行列を保存する方法です。MATLAB は当初 Fortran で作成されたため、この規則を使用します。MATLAB では、最初の列、2 番目の列、という順序で最後の列まで、データ要素が内部的に保存されます。

たとえば、以下の行列を考えてみます。

a = ['house'; 'floor'; 'porch']

a =
   house
   floor
   porch

次元は、次のとおりです。

size(a)

ans =
     3     5

データは以下のように格納されます。

行列が N 次元の場合、MATLAB は N 優先の順序でデータを表します。たとえば、4 x 2 x 3 の次元をもつ 3 次元配列を考えます。データは次のようにイメージできます。

ただし、MATLAB は、内部的にはこの 3 次元配列のデータを次の順序で表します。

A	B	C	D	E	F	G	H	I	J	K	L	M	N	O	P	Q	R	S	T	U	V	W	X
0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20	21	22	23

関数 mxCalcSingleSubscript は N 次元の添字指定により、配列の最初の要素から目的の要素へのオフセットを作成します。

MATLAB データ型

倍精度複素行列

MATLAB の最も一般的なデータ型は、倍精度の非スパース複素行列です。これらの行列は、double 型で、m 行 n 列の次元をもっています。ここで、m は行数、n は列数です。データは、実数部と虚数部が互いに隣接して格納される、インターリーブされた倍精度数のベクトルとして格納されます。このデータへのポインターは pa (配列へのポインター) として参照されます。非複素行列をテストするには、mxIsComplex を呼び出します。

MATLAB Version 9.4 (R2018a) 以前は、MATLAB は "実数/虚数分離型" 格納表現を使用していました。データは倍精度の数値の 2 つのベクトルとして保存されます。一方のベクトルには実数データ、他方には虚数データが含まれます。このデータへのポインターは、それぞれ pr (実数データへのポインター) および pi (虚数データへのポインター) と呼ばれます。非複素行列では pi が NULL となります。ただし、非複素行列をテストするには、mxIsComplex を呼び出します。

その他の数値行列

MATLAB では、単精度浮動小数点の 8、16、32、64 ビットの整数が、符号付きと符号なしの両方でサポートされています。

論理行列

logical データ型は、論理状態である true または false を、それぞれ 1 と 0 の数値を使用して表現します。特定の MATLAB 関数や演算子では、logical 1 または 0 を返して、特定の状態が真か偽かを示します。たとえば、(5 * 10) > 40 というステートメントは logical 値 1 を返します。

MATLABchar 配列

MATLAB char 配列は、データを符号なしの 16 ビットの整数として格納します。MATLAB char 配列を C スタイルの文字列に変換するには、mxArrayToString を呼び出します。C スタイルの文字列を char 配列に変換するには、mxCreateString を呼び出します。

cell 配列

cell 配列は MATLAB 配列の集合体で、各 mxArray はセルと呼ばれます。cell 配列を使うと、異なる型の MATLAB 配列を一緒に保存できます。cell 配列は、データ部分に mxArrays へのポインターの単一ベクトルが含まれていることを除き、数値行列と同様な方法で保存されます。このベクトルのメンバーがセルと呼ばれます。各セルは、別の cell 配列も含め、サポートされる任意のデータ型を取ることができます。

構造体

1 行 1 列の構造体は、1 行 n 列の cell 配列と同じ方法で保存されます。ここで n は構造体内のフィールド数です。データ ベクトルのメンバーはフィールドと呼ばれます。各フィールドは mxArray に保存された名前に関連付けられています。

オブジェクト

オブジェクトは、構造体と同じ方法で保存およびアクセスされます。MATLAB では、オブジェクトは登録されたメソッドをもつ名前付き構造体です。MATLAB 以外では、オブジェクトはオブジェクト名を識別する別のクラス名用のストレージを含む構造体です。

多次元配列

任意の型の MATLAB 配列は多次元になり得ます。整数のベクトルは、各要素が対応する次元のサイズとなるように保存されます。データのストレージ方法は、行列の場合と同じです。

空配列

任意の型の MATLAB 配列は空になり得ます。空の mxArray では、少なくとも 1 つの次元がゼロです。たとえば、m および n が 0 で、pa が NULL である double 型の倍精度 mxArray は空配列です。

スパース行列

スパース行列には MATLAB の非スパース行列とは異なる格納規則があります。パラメーター pa も倍精度数値または logical 値の配列ですが、この配列には非ゼロのデータ要素のみが含まれます。

また、追加のパラメーターとして nzmax、ir、jc の 3 つがあります。これらのパラメーターに対し変数を宣言する場合は、mwSize 型と mwIndex 型を使用します。

• nzmax は、ir および pa の長さを含む整数です。これは、スパース行列の非ゼロ要素の最大数です。

• ir は、長さ nzmax の整数配列を指し、pa 内の対応要素の行インデックスを含みます。

• jc は、長さ n+1 の整数配列を指し、ここで n は、スパース行列内の列数です。C では、mxArray の最初の要素はインデックスが 0 となります。配列 jc には列インデックス情報が格納されます。スパース行列の j 番目の列に非ゼロ要素がある場合、jc[j] は、j 番目の列にある最初の非ゼロ要素の ir および pa に対するインデックスです。インデックス jc[j+1] - 1 には、その列の最後の非ゼロ要素が含まれています。スパース行列の j 番目の列で、jc[j] は先行するすべての列の非ゼロ要素の合計数になります。配列 jc の最後の要素 jc[n] は、スパース行列全体の非ゼロ要素の数である nnz と等価です。nnz が nzmax より少ない場合、さらにストレージを割り当てなくても追加の非ゼロ エントリを配列に挿入できます。

データ型の使用

MATLAB でサポートされる任意のクラスまたはデータ型を受け入れるソース MEX ファイル、MAT ファイル アプリケーションおよびエンジン アプリケーションを C/C++ で作成できます (データ型を参照)。Fortran では、倍精度の n 行 m 列の配列および文字列のみがサポートされます。バイナリの C/C++ および Fortran MEX ファイルは MATLAB 関数と同様に使用します。

注意

MATLAB では、行列ライブラリの create 関数 (mxCreateStructArray など) を使用して C/C++ または Fortran で作成された MATLAB データ構造体の妥当性はチェックされません。無効な構文を使用して MATLAB データ構造体を作成すると、C/C++ または Fortran プログラムで予期しない動作が発生する可能性があります。

データ構造体の宣言

MATLAB 配列の処理には mxArray 型を使用します。次のステートメントでは、myData という名前の mxArray を宣言しています。

mxArray *myData;

関数 mxCreate* の 1 つで myData の値を定義します。mxCreateNumericArray、mxCreateCellArray、mxCreateCharArray などの関数は配列作成ルーチンとして有効です。たとえば、以下のステートメントは、0 に初期化された m 行 1 列の浮動小数点 mxArray を割り当てます。

myData = mxCreateDoubleMatrix(m, 1, mxREAL);

C/C++ のプログラマは、MATLAB 配列内のデータは列優先の順序であることに留意してください (詳しくは、データの保存を参照してください)。mxArray からデータを読み取るには、MATLAB の mxGet* 配列アクセス ルーチンを使用します。

データの操作

mxGet* 配列アクセス ルーチンは、mxArray のデータへの参照を取得します。これらのルーチンを使用して MEX ファイル内のデータを変更します。各関数は、mxArray 内の特定の情報へのアクセスを提供します。有効な関数には、mxGetDoubles、mxGetComplexDoubles、mxGetM および mxGetString があります。これらの関数の多くには対応する mxSet* ルーチンがあり、配列内の値を変更するために使用できます。

次のステートメントは、入力 prhs[0] を C スタイルの文字列 buf に読み取ります。

char *buf;
int buflen;
int status;
buflen = mxGetN(prhs[0])*sizeof(mxChar)+1;
buf = mxMalloc(buflen);
status = mxGetString(prhs[0], buf, buflen);

explore の例

MATLAB には、explore.c というサンプルのソース MEX ファイルが含まれています。このファイルは入力変数のデータ型を識別します。このソース コード サンプルは、matlabroot/extern/examples/mex にあります。ここで、matlabroot はシステムの、MATLAB がインストールされている最上位フォルダーを表しています。

メモ

このドキュメンテーションでは、フォルダー パスに関するプラットフォーム共通の説明で UNIX^® の表記規則を使用しています。たとえば、mex フォルダーへの全般的な参照は、matlabroot/extern/examples/mex です。

サンプルの MEX ファイルをビルドするには、まずパス上にある書き込み可能なフォルダーにファイルをコピーします。

copyfile(fullfile(matlabroot,'extern','examples','mex','explore.c'),'.','f')

mex コマンドを使用して MEX ファイルをビルドします。

mex explore.c -R2018a

以下を入力します。

x = 2;
explore(x)

------------------------------------------------
Name: prhs[0]
Dimensions: 1x1 
Class Name: double
------------------------------------------------
	(1,1) = 2

explore は任意のデータ型を受け入れます。以下の例で、explore を使用してみてください。

explore([1 2 3 4 5])
explore 1 2 3 4 5
explore({1 2 3 4 5})
explore(int8([1 2 3 4 5]))
explore {1 2 3 4 5}
explore(sparse(eye(5)))
explore(struct('name', 'Joe Jones', 'ext', 7332))
explore(1, 2, 3, 4, 5)
explore(complex(3,4))

関連するトピック

• データ型