mxSetField (C and Fortran)

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

C Syntax

#include "matrix.h"
void mxSetField(mxArray *pm, mwIndex index,
  const char *fieldname, mxArray *pvalue);

Fortran Syntax

#include "fintrf.h"
subroutine mxSetField(pm, index, fieldname, pvalue)
mwPointer pm, pvalue
mwIndex index
character*(*) fieldname

Arguments

pm

Pointer to a structure mxArray. Call mxIsStruct to determine whether pm points to a structure mxArray.

index

Index of an element in the array.

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.

fieldname

Name of a field in the structure. The field must exist in the structure. Call mxGetFieldNameByNumber or mxGetFieldNumber to determine existing field names.

pvalue

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

Description

Use mxSetField to assign the contents of pvalue to the field fieldname of element index.

If you want to replace the contents of fieldname, then first free the memory of the existing data. Use the mxGetField function to get a pointer to the field, call mxDestroyArray on the pointer, then call mxSetField 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 mxSetField 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.

Examples

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

mxcreatestructarray.c

Alternatives

C Language

In C, you can replace the statements:

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

with a call to mxSetField:

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

Fortran Language

In Fortran, you can replace the statements:

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