mxGetFieldByNumber (MATLAB Application Program Interface)

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

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. See mxCalcSingleSubscript for more details on calculating an index.

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

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. Call mxIsStruct to determine if array_ptr points to is a structure mxArray.
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 determine existing field names.
Insufficient heap space to hold the returned mxArray.

Description

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

Examples

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.