Pointer to field value from structure array, given index and field number
#include "matrix.h" mxArray *mxGetFieldByNumber(const mxArray *pm, mwIndex index, int fieldnumber);
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 ten 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 |
In C, 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
if you
have a 1
-by-1
structure.
In Fortran, calling:
mxGetField(pm, index, 'fieldname')
is equivalent to calling:
fieldnum = mxGetFieldNumber(pm, 'fieldname') mxGetFieldByNumber(pm, index, fieldnum)
where index
is 1
if you
have a 1
-by-1
structure.
See the
following examples in matlabroot
/extern/examples/refbook
.
See the
following examples in matlabroot
/extern/examples/mx
.
See the
following examples in matlabroot
/extern/examples/mex
.
mxGetField
, mxGetFieldNameByNumber
, mxGetFieldNumber
, mxGetNumberOfFields
, mxIsStruct
, mxSetField
, mxSetFieldByNumber