MATLAB Application Program Interface Reference | Help Desk |
mxGetFieldByNumber
Get a field value, given a field number and an index in a structure array
#include "matrix.h" mxArray *mxGetFieldNumber(const mxArray *array_ptr, int index, int *field_number);array_ptr
Pointer to a structure mxArray
.
The desired element. The first element of an mxArray
has an index
of 0
, the second element has an index
of 1
, and the last element has an index
of N-1
, where N
is the total number of elements in the structure mxArray
. See mxCalcSingleSubscript
for more details on calculating an index.
The position of the field whose value you want to extract. The first field within each element has a field number of 0
, the second field has a field number of 1
, and so on. The last field has a field number of N-1
, where N
is the number of fields.
mxArray
in the specified field at the specified field_name
, on success. Returns NULL
otherwise. One possibility is that there is no value assigned to the specified field. Another possibility is that there is a value, but the call failed. Common causes of failure include
array_ptr
that does not point to a structure mxArray
. Call mxIsStruct
to determine if array_ptr
points to is a structure mxArray
.
mxArray
. For example, given a structure mxArray
that contains 10 elements, you cannot specify an index greater than 9.
mxGetFieldNameByNumber
or mxGetFieldNumber
to determine existing field names.
mxArray
.
mxGetFieldByNumber
to get the value held in the specified field_number
at the index-th element.
When you finish using the returned mxArray
, call mxDestroyArray
to deallocate it.
Consider a MEX-file that gathers a pointer to the mxArray
stored at each field of each element in a structure mxArray
. For example, given an input 12-by-1 structure mxArray
in which each element contains three fields, the MEX-file calls mxGetFieldByNumber
36 times:
void mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray *prhs[]) { int total_array_elements, number_of_fields; int index, field_num; const char *field_name; mxArray *field_array_ptr; if (mxIsStruct(prhs[0])) { total_array_elements = mxGetM(prhs[0]) * mxGetN(prhs[0]); number_of_fields = mxGetNumberOfFields(prhs[0]); for (index=0; index < total_array_elements; index++) { for (field_num=0; field_num<number_of_fields; field_num++){ field_array_ptr = mxGetFieldByNumber(prhs[0], index, field_num); /* Code to analyze field_array_ptr. */ ... } } } else mexErrMsgTxt("You must specify a structure array."); }This MEX-file does not contain code to analyze the returned
field_array_ptr
. (The online example explore.c
does contain such code.) For an additional example, see mxGetFieldByNumber.c
in the mx
subdirectory of the examples
directory.
mxGetField
, mxGetFieldNameByNumber
, mxGetFieldNumber
, mxGetNumberOfFields
, mxSetField, mxSetFieldByNumber