mxGetFieldByNumber (MATLAB Application Program Interface)

Get a field value, given a field number and an index in a structure array

C Syntax

#include "matrix.h"
mxArray *mxGetFieldByNumber(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 for the desired element, on success. Returns NULL if passed an invalid argument or if there is no value assigned to the specified field. 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 index < 0 or >= the number of elements in the array.
Specifying a nonexistent field number. Call mxGetFieldNameByNumber or mxGetFieldNumber to determine existing field names.

Description

Call mxGetFieldByNumber to get the value held in the specified field_number at the indexed element.

Note: Changing data contained within the field may cause unpredictable results.

Calling

mxGetField(pa, index, "field_name");

is equivalent to calling

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

where index is zero if you have a one-by-one structure.

Examples

See phonebook.c in the refbook subdirectory of the examples directory.

For additional examples, see mxisclass.c in the mx subdirectory of the examples directory and explore.c in the mex subdirectory of the examples directory.