MATLAB^®

mxSetFieldByNumber (C and Fortran) - Set structure array field, given field number and index

C Syntax

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

Fortran Syntax

mxSetFieldByNumber(pm, index, fieldnumber, value)
mwPointer pm, value
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 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.

fieldnumber

Position of the field whose value you want to extract.

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

In Fortran, the first field within each element has a fieldnumber of 1, the second field has a fieldnumber of 2, and so on. The last field has a fieldnumber of N.

value

Pointer to the mxArray you are assigning.

Description

Use mxSetFieldByNumber to assign a value to the specified element of the specified field. mxSetFieldByNumber is almost identical to mxSetField; however, the former takes a field number as its third argument and the latter takes a field name as its third argument.

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, "field_name", new_value_pa);

is equivalent to calling:

field_num = mxGetFieldNumber(pa, "field_name");
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 mxGetFieldByNumber before you call mxSetFieldByNumber.

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

C Examples