mxGetFieldNameByNumber (C and Fortran)

C Syntax

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

Fortran Syntax

#include "fintrf.h"
character*(*) mxGetFieldNameByNumber(pm, fieldnumber)
mwPointer pm
integer*4 fieldnumber

Arguments

pm: Pointer to a structure mxArray
fieldnumber: Position of the desired field. For instance, in C, to get the name of the first field, set fieldnumber to 0; to get the name of the second field, set fieldnumber to 1; and so on. In Fortran, to get the name of the first field, set fieldnumber to 1; to get the name of the second field, set fieldnumber to 2; and so on.

Returns

Pointer to the nth field name, on success. Returns NULL in C (0 in Fortran) on failure. Common causes of failure include

Specifying an array pointer pm that does not point to a structure mxArray. Call mxIsStruct to determine whether pm points to a structure mxArray.
Specifying a value of fieldnumber outside the bounds of the number of fields in the structure mxArray. In C, fieldnumber 0 represents the first field, and fieldnumber N-1 represents the last field, where N is the number of fields in the structure mxArray. In Fortran, fieldnumber 1 represents the first field, and fieldnumber N represents 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 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];

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

In Fortran, the field number 1 represents the field name; field number 2 represents field billing; field number 3 represents field test. A field number other than 1, 2, or 3 causes mxGetFieldNameByNumber to return 0.