mxGetFieldNumber (C and Fortran)

Field number from structure array, given field name

C Syntax

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

Fortran Syntax

#include "fintrf.h"
integer*4 mxGetFieldNumber(pm, fieldname)
mwPointer pm
character*(*) fieldname

Arguments

pm

Pointer to a structure mxArray

fieldname

Name of a field in the structure mxArray

Returns

Field number of the specified fieldname, on success. In C, the first field has a field number of 0, the second field has a field number of 1, and so on. In Fortran, the first field has a field number of 1, the second field has a field number of 2, and so on. Returns -1 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 the fieldname of a nonexistent field.

Description

If you know the name of a field but do not know its field number, call mxGetFieldNumber. Conversely, if you know the field number but do not know its field name, call mxGetFieldNameByNumber.

For example, 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 name has a field number of 0; the field billing has a field number of 1; and the field test has a field number of 2. If you call mxGetFieldNumber and specify a field name of anything other than name, billing, or test, mxGetFieldNumber returns -1.

If you have a 1-by-1 structure, then calling:

mxGetField(pa, index, "field_name");

is equivalent to calling:

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

where index is 0.

In Fortran, the field name has a field number of 1; the field billing has a field number of 2; and the field test has a field number of 3. If you call mxGetFieldNumber and specify a field name of anything other than name, billing, or test, mxGetFieldNumber returns 0.

If you have a 1-by-1 structure, then calling:

mxGetField(pm, index, 'fieldname');

is equivalent to calling:

fieldnum = mxGetFieldNumber(pm, 'fieldname');
mxGetFieldByNumber(pm, index, fieldnum);

where index is 1.

Examples

To open an example, type:

edit([fullfile(matlabroot,"extern","examples","mx","filename")]);

where filename is:

• mxcreatestructarray.c