MATLAB Application Program Interface Reference | Help Desk |
mxGetField
Get a field value, given a field name and an index in a structure array
#include "matrix.h" mxArray *mxGetField(const mxArray *array_ptr, int index, const char *field_name);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
.
The name of the field whose value you want to extract.
A pointer to themxArray
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
. To determine if array_ptr
points to a structure mxArray
, call mxIsStruct
.
index
to an element past the end of the mxArray
. For example, given a structure mxArray
that contains 10 elements, you cannot specify an index
greater than 9.
field_name
. Call mxGetFieldNameByNumber
or mxGetFieldNumber
to get existing field name
s.
mxArray
.
mxGetField
to get the value held in the specified element of the specified field. In pseudo-C terminology, mxGetField
returns the value at
array_ptr[index].field_name
mxGetFieldByIndex
is similar to mxGetField
. Both functions return the same value. The only difference is in the way you specify the field. mxGetFieldByIndex
takes field_num
as its third argument, and mxGetField
takes field_name
as its third argument.
When you finish using the returned mxArray
, call mxDestroyArray
to deallocate it.
Consider a MEX-file named WhatBill
that prints the value of the "Billing
" field in each element of an input structure mxArray
:
void mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray *prhs[]) { mxArray *field_array_ptr; double value_in_billing_field; int index, number_of_elements; /* Find the values of the billing field. */ if (mxIsStruct(prhs[0])) { /* Loop through each element of the structure. */ number_of_elements = mxGetM(prhs[0]) * mxGetN(prhs[0]); for (index=0; index<number_of_elements; index++) { /* Get the value in the "billing" field at this index. */ field_array_ptr = mxGetField(prhs[0], index, "billing"); /* The returned "field" is a pointer to a scalar mxArray. Get the value associated with the scalar mxArray. */ if (field_array_ptr) { value_in_billing_field = mxGetScalar(field_array_ptr); mexPrintf("%g\n", value_in_billing_field); } else mexWarnMsgTxt("Missing 'billing' field."); } } else mexErrMsgTxt("You must pass a structure mxArray."); }In MATLAB, create a structure named
patient
initialized to
>> patient(1).name='Cheryl Doe'; >> patient(1).billing=827; >> patient(2).name='Scott Woe'; >> patient(2).billing=435; >> patient(3).name='Cleve Roe'; >> patient(3).billing=256;Passing
patient
as the first argument to WhatBill
yields
>> WhatBill(patient) 827 435 256For an additional example, see
mxGetField.c
in the mx
subdirectory of the examples
directory.
mxGetFieldByNumber
, mxGetFieldNameByNumber
, mxGetFieldNumber
, mxGetNumberOfFields
, mxIsStruct
, mxSetField
, mxSetFieldByNumber