MATLAB^®

mxSetField (C and Fortran) - Set structure array field, given field name and index

C Syntax

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

Fortran Syntax

mxSetField(pm, index, fieldname, value)
mwPointer pm, value
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 the desired element.

In C, the first element of an mxArray has an index of 0, the second element has an index of 1, and the last element has an index of N-1, where N is the total number of elements in the mxArray.

In Fortran, the first element of an mxArray has an index of 1, the second element has an index of 2, and the last element has an index of N, where N is the total number of elements in the mxArray.

See mxCalcSingleSubscript for details on calculating an index.

fieldname

The name of the field whose value you are assigning. Call mxGetFieldNameByNumber or mxGetFieldNumber to determine existing field names.

value

Pointer to the mxArray you are assigning.

Description

Use mxSetField to assign a value to the specified element of the specified field. In pseudo-C terminology, mxSetField performs the assignment:

pm[index].fieldname = value;

Note Inputs to a MEX-file are constant read-only mxArrays and should not be modified. Using mxSetCell* or mxSetField* to modify the cells or fields of a MATLAB^® argument causes unpredictable results.

In C, calling:

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

is equivalent to calling:

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

In Fortran, calling:

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

is equivalent to calling:

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

This function does not free any memory allocated for existing data that it displaces. To free existing memory, call mxDestroyArray on the pointer returned by mxGetField before you call mxSetField.

To free memory for structures created using mxSetField, call mxDestroyArray only on the structure array, not the array used by mxSetField. If you also call mxDestroyArray on the mxArray value points to, the same memory is freed twice and this can corrupt memory.

C Examples