mxGetField (MATLAB Application Program Interface)

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);

Arguments

array_ptr
Pointer to a structure mxArray.

index
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.

field_name
The name of the field whose value you want to extract.

Returns

A pointer to the 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

Specifying an array_ptr that does not point to a structure mxArray. To determine if array_ptr points to a structure mxArray, call mxIsStruct.
Specifying an out-of-range 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.
Specifying a nonexistent field_name. Call mxGetFieldNameByNumber or mxGetFieldNumber to get existing field names.
Insufficient heap space to hold the returned mxArray.

Description

Call 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. Note: Changing data contained within the field may cause unpredictable results.

Examples

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
256

For an additional example, see mxgetfield.c in the mx subdirectory of the examples directory.