mxGetFieldNameByNumber (External Interfaces/API Reference)

Get a field name, given a field number in a structure array

C Syntax

#include "matrix.h"
const char *mxGetFieldNameByNumber(const mxArray *array_ptr, 
            int field_number);

Arguments

array_ptr
Pointer to a structure mxArray.

field_number
The position of the desired field. For instance, to get the name of the first field, set field_number to 0; to get the name of the second field, set field_number to 1; and so on.

Returns

A pointer to the nth field name, on success. Returns NULL on failure. 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 a structure mxArray.

Specifying a value of field_number greater than or equal to the number of fields in the structure mxArray. (Remember that field_number 0 symbolizes the first field, so index N-1 symbolizes the last field.)

Description

Call mxGetFieldNameByNumber to get the name of a field in the given structure mxArray. A typical use of mxGetFieldNameByNumber is to call it inside a loop in order to get the names of all the fields in a given mxArray.

Consider a MATLAB structure initialized to

patient.name = 'John Doe';
patient.billing = 127.00;
patient.test = [79 75 73; 180 178 177.5; 220 210 205];

The field_number 0 represents the field name name; field_number 1 represents field name billing; field_number 2 represents field name test. A field_number other than 0, 1, or 2 causes mxGetFieldNameByNumber to return NULL.

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.

mxGetFieldByNumber mxGetFieldNumber