Main Content

Pointer to field value from structure array, given index and field number

#include "matrix.h" mxArray *mxGetFieldByNumber(const mxArray *pm, mwIndex index, int fieldnumber);

#include "fintrf.h" mwPointer mxGetFieldByNumber(pm, index, fieldnumber) mwPointer pm mwIndex index integer*4 fieldnumber

`pm`

Pointer to a structure

`mxArray`

`index`

Index of the desired element.

In C, the first element of an

`mxArray`

has an`index`

of`0`

. The`index`

of the last element is`N-1`

, where`N`

is the number of elements in the array. In Fortran, the first element of an`mxArray`

has an`index`

of`1`

. The`index`

of the last element is`N`

, where`N`

is the number of elements in the array.See

`mxCalcSingleSubscript`

for more details on calculating an`index`

.`fieldnumber`

Position of the field whose value you want to extract

In C, 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.In Fortran, the first field within each element has a field number of

`1`

, the second field has a field number of`2`

, and so on. The last field has a field number of`N`

, where`N`

is the number of fields.

Pointer to the `mxArray`

in the specified field for the desired
element, on success. Returns `NULL`

in C (`0`

in
Fortran) if passed an invalid argument or if there is no value assigned to the specified
field. 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 an

`index`

to an element outside the bounds of the`mxArray`

. For example, given a structure`mxArray`

that contains 10 elements, you cannot specify an`index`

greater than`9`

in C (`10`

in Fortran).Specifying a nonexistent field number. Call

`mxGetFieldNumber`

to determine the field number that corresponds to a given field name.

Call `mxGetFieldByNumber`

to get the value held in the specified
`fieldnumber`

at the indexed element.

Do not call `mxDestroyArray`

on an `mxArray`

returned by the `mxGetFieldByNumber`

function.

**Note**

Inputs to a MEX-file are constant read-only `mxArray`

s.
Do not modify the inputs. Using `mxSetCell`

`*`

or `mxSetField`

`*`

functions
to modify the cells or fields of a MATLAB^{®} argument causes unpredictable
results.

In C, 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, 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`

.

See these examples in

:* matlabroot*/extern/examples/refbook

See these examples in

:* matlabroot*/extern/examples/mx

See these examples in

:* matlabroot*/extern/examples/mex

`mxGetField`

,
`mxGetFieldNameByNumber`

, `mxGetFieldNumber`

, `mxGetNumberOfFields`

, `mxIsStruct`

,
`mxSetField`

,
`mxSetFieldByNumber`