Main Content

mxSetDimensions (C)

Modify number of dimensions and size of each dimension

C Syntax

#include "matrix.h"
int mxSetDimensions(mxArray *pm, const mwSize *dims, mwSize ndim);

Description

mxSetDimensions returns 0 on success, and 1 on failure. mxSetDimensions allocates heap space to hold the input size array. So it is possible (though unlikely) that increasing the number of dimensions can cause the system to run out of heap space.

Call mxSetDimensions to reshape an existing mxArray. mxSetDimensions is like mxSetM and mxSetN; however, mxSetDimensions provides greater control for reshaping an mxArray that has more than two dimensions.

mxSetDimensions does not allocate or deallocate any space for the pr or pi arrays. So, if your call to mxSetDimensions increases the number of elements in the mxArray, then enlarge the pr (and pi, if it exists) arrays accordingly.

If your call to mxSetDimensions reduces the number of elements in the mxArray, then you can optionally reduce the size of the pr and pi arrays using mxRealloc.

MATLAB® automatically removes any trailing singleton dimensions specified in the dims argument. For example, if ndim equals 5 and dims equals [4 1 7 1 1], then the resulting array has the dimensions 4-by-1-by-7.

Input Arguments

expand all

Pointer to an mxArray array, specified as const mxArray*.

Dimensions array. Each element in the dimensions array contains the size of the array in that dimension, specified as mwSize. For example, in Fortran, setting dims(1) to 5 and dims(2) to 7 establishes a 5-by-7 mxArray. In most cases, there are ndim elements in the dims array.

Number of dimensions, specified as mwSize.

Examples

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

Introduced before R2006a