mxSetN (MATLAB Application Program Interface)

Set the number of columns

#include "matrix.h"
void mxSetN(mxArray *array_ptr, int n);

Arguments

array_ptr
Pointer to an mxArray.

n
The desired number of columns.

Description

Call mxSetN to set the number of columns in the specified mxArray. The term "columns" always means the second dimension of a matrix. Calling mxSetN forces an mxArray to have two dimensions. For example, if array_ptr points to an mxArray having three dimensions, calling mxSetN reduces the mxArray to two dimensions.

You typically use mxSetN to change the shape of an existing mxArray. Note that mxSetN does not allocate or deallocate any space for the pr, pi, ir, or jc arrays. Consequently, if your calls to mxSetN and mxSetM increase the number of elements in the mxArray, then you must enlarge the pr, pi, ir, and/or jc arrays.

If your calls to mxSetM and mxSetN end up reducing the number of elements in the mxArray, then you may want to reduce the size of the pr, pi, ir, or jc arrays in order to reduce heap space usage. However, reducing the size is not mandatory.

Examples

Consider a 3-by-3 mxArray containing


10	14	20
12	17	22
13	18	23

Suppose you enlarge the mxArray to 4-by-4 but preserve the positions of the original 3-by-3 to yield an mxArray containing


10	14	20
12	17	22
13	18	23
0	0	0

The code to create the original 3-by-3 mxArray and the expanded 4-by-4 mxArray is

#define COLS_IN_OLD_ARRAY 3
#define ROWS_IN_OLD_ARRAY 3
#define ROWS_IN_NEW_ARRAY 4
  mxArray  *array_ptr;
  double    old_pr[9] = {10,12,13,14,17,18,20,22,23};
  double   *dest, *src, *new_heap_pr, *pr;
  int       col;

 /* Create a 3-by-3 real-only mxArray of doubles. */ 
   array_ptr = mxCreateDoubleMatrix(3, 3, mxREAL);
   pr = mxGetPr(array_ptr);
   memcpy((void *)pr,(const void *)old_pr,9*sizeof(double));
   mxSetName(array_ptr, "Apricots");

   ...
/* Reshape Apricots into a 4-by-4 mxArray. */ 
   mxSetM(array_ptr, 4);
   mxSetN(array_ptr, 4);
 
 /* Redo pr to respond to the new size of Apricots; preserve the
    positions of the original 3-by-3. */
 
 /* First, allocate heap to hold 16 real elements. */ 
   new_heap_pr = (double *)mxCalloc(16, sizeof(double)); 

 /* Next, copy the original 9 elements. */ 
   for (col=0; col<COLS_IN_OLD_ARRAY; col++)  {
      dest = new_heap_pr + (ROWS_IN_NEW_ARRAY * col);
      src  = &old_pr[ROWS_IN_OLD_ARRAY * col];
      memcpy(dest, src, ROWS_IN_OLD_ARRAY * sizeof(double));
   }

 /* First, deallocate the old pr data. */
   mxFree(mxGetPr(array_ptr));

 /* Then, associate the new data with the real data of Apricots. */ 
   mxSetPr(array_ptr, new_heap_pr);

For an additional example, see mxsetn.c in the mx subdirectory of the examples directory.