MATLAB Application Program Interface Reference | Help Desk |
mxCreateSparse
Create a 2-dimensional unpopulated sparsemxArray
#include "matrix.h" mxArray *mxCreateSparse(int m, int n, int nzmax, mxComplexity ComplexFlag);m 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
.
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
.
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
.
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
pr
array of m-by-n elements.
pi
array of m-by-n elements (but only if ComplexFlag
is mxCOMPLEX
).
ir
array of nzmax
elements.
jc
array of m
elements.
mxArray
, call mxDestroyArray
to reclaim all its heap space.
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.
mxDestroyArray
, mxSetNzmax
, mxSetPr
, mxSetPi, mxSetIr
, mxSetJc
, mxComplexity