mxGetFieldByNumber (C and Fortran) - Field value, given field number and index, into structure array

C Syntax

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

Fortran Syntax

mwPointer mxGetFieldByNumber(pm, index, fieldnumber)
mwPointer pm
mwIndex index
integer*4 fieldnumber

Arguments

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.

Returns

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.

Description

Call mxGetFieldByNumber to get the value held in the specified fieldnumber at the indexed element.

Note   Inputs to a MEX-file are constant read-only mxArrays. 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, 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.

Examples

See the following examples in matlabroot/extern/examples/refbook.

• phonebook.c

See the following examples in matlabroot/extern/examples/mx.

• mxisclass.c

See the following examples in matlabroot/extern/examples/mex.

• explore.c

See Also

mxGetField, mxGetFieldNameByNumber, mxGetFieldNumber, mxGetNumberOfFields, mxIsStruct, mxSetField, mxSetFieldByNumber

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit