mxCreateSparse (MATLAB Application Program Interface)

Create a 2-dimensional unpopulated sparse mxArray

#include "matrix.h"
mxArray *mxCreateSparse(int m, int n, int nzmax, 
         mxComplexity ComplexFlag);

Arguments

m
The desired number of rows.

n
The desired number of columns.

nzmax

The number of elements that mxCreateSparse should allocate to hold the pr, ir, and, if ComplexFlag is mxCOMPLEX, pi arrays. Set the value of nzmax to be greater than or equal to the number of nonzero elements you plan to put into the mxArray, but make sure that nzmax is less than or equal to m*n.

ComplexFlag
Set this value to mxREAL or mxCOMPLEX. If the mxArray you are creating is to contain imaginary data, then set ComplexFlag to mxCOMPLEX; otherwise, set ComplexFlag to mxREAL.

Returns

A pointer to the created sparse mxArray on success; returns NULL on failure. The most likely reason for failure is insufficient free heap space. If that happens, try reducing nzmax, m, or n.

Description

Call mxCreateSparse to create an unpopulated sparse mxArray. The returned sparse mxArray contains no sparse information and cannot be passed as an argument to any MATLAB sparse functions. In order to make the returned sparse mxArray useful, you must initialize the pr, ir, jc, and (if it exists) pi array.

mxCreateSparse allocates space for

A pr array of m-by-n elements.
A pi array of m-by-n elements (but only if ComplexFlag is mxCOMPLEX).
An ir array of nzmax elements.
A jc array of m elements.

When you finish using the sparse mxArray, call mxDestroyArray to reclaim all its heap space.

Examples

Create a sparse mxArray of real data. Although the mxArray is 3-by-2, only four of the six elements are occupied by nontrivial data.

#define NZMAX 4
#define ROWS  4
#define COLS  2
 int            rows=ROWS, cols=COLS;
 mxArray       *ptr_array; /* Pointer to created sparse array. */
 static double  static_pr_data[NZMAX] = {5.8, 6.2, 5.9, 6.1};
 static int     static_ir_data[NZMAX] = {0, 2, 1, 3};
 static int     static_jc_data[COLS+1] = {0, 2, 4};
 double        *start_of_pr;
 int           *start_of_ir, *start_of_jc;
 mxArray       *array_ptr;

 /* Create a sparse array and name it "Sparrow". */    
   array_ptr = mxCreateSparse(rows, cols, NZMAX, mxREAL); 
   mxSetName(array_ptr, "Sparrow");

 /* Place pr data into the newly created sparse array. */ 
   start_of_pr = (double *)mxGetPr(array_ptr); 
   memcpy(start_of_pr, static_pr_data, NZMAX*sizeof(double));

 /* Place ir data into the newly created sparse array. */ 
   start_of_ir = (int *)mxGetIr(array_ptr); 
   memcpy(start_of_ir, static_ir_data, NZMAX*sizeof(int));

 /* Place jc data into the newly created sparse array. */ 
   start_of_jc = (int *)mxGetJc(array_ptr); 
   memcpy(start_of_jc, static_jc_data, NZMAX*sizeof(int));

 /* ... Use the sparse array in some fashion. */
/* When finished with the mxArray, deallocate it. */

mxDestroyArray(array_ptr);
For an additional example, see mxcreatesparse.c in the mx subdirectory of the examples directory.