mxSetFieldByNumber (C and Fortran)

Set field value in structure array, given index and field number

C Syntax

#include "matrix.h"
void mxSetFieldByNumber(mxArray *pm, mwIndex index,
  int fieldnumber, mxArray *pvalue);

Fortran Syntax

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

Arguments

pm

Pointer to a structure mxArray. Call mxIsStruct to determine whether pm points 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 details on calculating an index.

fieldnumber

Position of the field in the structure. The field must exist in the structure.

In C, the first field within each element has a fieldnumber of 0. The fieldnumber of the last is N-1, where N is the number of fields.

In Fortran, the first field within each element has a fieldnumber of 1. The fieldnumber of the last is N, where N is the number of fields.

pvalue

Pointer to the mxArray containing the data you want to assign.

Description

Use mxSetFieldByNumber to assign the contents of pvalue to the field specified by fieldnumber of element index. mxSetFieldByNumber is like mxSetField; however, the function identifies the field by position number, not by name.

If you want to replace the contents at fieldnumber, then first free the memory of the existing data. Use the mxGetFieldByNumber function to get a pointer to the field, call mxDestroyArray on the pointer, then call mxSetFieldByNumber to assign the new value.

You cannot assign pvalue to more than one field in a structure or to more than one element in the mxArray. If you want to assign the contents of pvalue to multiple fields, then use the mxDuplicateArray function to make copies of the data then call mxSetFieldByNumber on each copy.

To free memory for structures created using this function, call mxDestroyArray only on the structure array. Do not call mxDestroyArray on the array pvalue points to. If you do, then MATLAB^® attempts to free the same memory twice, which can corrupt memory.

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.

Alternatives

C Language

In C, calling:

mxSetField(pa, index, "field_name", new_value_pa);

is equivalent to calling:

field_num = mxGetFieldNumber(pa, "field_name");
mxSetFieldByNumber(pa, index, field_num, new_value_pa);

Fortran Language

In Fortran, calling:

mxSetField(pm, index, 'fieldname', newvalue)

is equivalent to calling:

fieldnum = mxGetFieldNumber(pm, 'fieldname')
mxSetFieldByNumber(pm, index, fieldnum, newvalue)

Examples

See these examples in matlabroot/extern/examples/mx:

mxcreatestructarray.c

Version History

Introduced before R2006a