mxGetField (C および Fortran)

構造体配列からフィールド値へのポインター (インデックスおよびフィールド名を指定)

C 構文

#include "matrix.h"
mxArray *mxGetField(const mxArray *pm, mwIndex index, const char *fieldname);

Fortran 構文

#include "fintrf.h"
mwPointer mxGetField(pm, index, fieldname)
mwPointer pm
mwIndex index
character*(*) fieldname

引数

pm

構造体 mxArray へのポインター

index

目的の要素のインデックス。

C では、mxArray の最初の要素は 0 の index をもっています。最後の要素の index は N-1 です。ここで、N は配列内の要素の数です。Fortran では、mxArray の最初の要素の index は 1 です。最後の要素の index は N です。ここで、N は配列内の要素の数です。

fieldname

抽出する値をもつフィールドの名前。

戻り値

成功した場合、指定された fieldname にある指定されたフィールドの mxArray へのポインター。無効な引数が渡されたか、指定されたフィールドに値が割り当てられていない場合、C では NULL (Fortran では 0) を返します。よくある失敗の原因には、以下があります。

  • 構造体 mxArray を指していない配列ポインター pm を指定している。pm が構造体 mxArray を指しているかどうかを判断するには、mxIsStruct を呼び出します。

  • index を mxArray の範囲外の要素に指定している。たとえば、10 個の要素をもつ構造体 mxArray がある場合、C では 9 (Fortran では 10) より大きい index を指定することはできません。

  • 存在しない fieldname プロパティを指定している。mxGetFieldNameByNumber または mxGetFieldNumber を呼び出して、既存のフィールド名を取得します。

  • 不十分なヒープ領域。

説明

mxGetField を呼び出して、指定されたフィールドの指定された要素に格納されている値を取得します。疑似 C 用語では、mxGetField は以下での値を返します。

pm[index].fieldname

mxGetFieldByNumber は mxGetField に似ています。どちらの関数も同じ値を返します。唯一の違いはフィールドの指定方法です。mxGetFieldByNumber はフィールド番号をその 3 番目の引数として取り、mxGetField はフィールド名をその 3 番目の引数として取ります。

関数 mxGetField によって返された mxArray では、mxDestroyArray を呼び出さないでください。

メモ

MEX ファイルへの入力値は、読み取り専用の定数 mxArray です。入力値を変更しないでください。関数 mxSetCell* または関数 mxSetField* を使用して MATLAB® 引数のセルまたはフィールドを変更すると、予期しない結果が生じます。

C では、以下を呼び出すことは、

mxGetField(pa, index, "field_name");

以下を呼び出すことと等価です。

field_num = mxGetFieldNumber(pa, "field_name");
mxGetFieldByNumber(pa, index, field_num);

ここで、1 行 1 列の構造体がある場合、index は 0 です。

Fortan では、以下を呼び出すことは、

mxGetField(pm, index, 'fieldname')

以下を呼び出すことと等価です。

fieldnum = mxGetFieldNumber(pm, 'fieldname')
mxGetFieldByNumber(pm, index, fieldnum)

ここで、1 行 1 列の構造体がある場合、index は 1 です。

例

matlabroot/extern/examples/eng_mat の次の例を参照してください。

バージョン履歴

R2006a より前に導入