mxGetNzmax (MATLAB Application Program Interface)

Get the number of elements in the ir, pr, and (if it exists) pi arrays

#include "matrix.h"
int mxGetNzmax(const mxArray *array_ptr);

Arguments

array_ptr
Pointer to a sparse mxArray.

Returns

The number of elements allocated to hold nonzero entries in the specified sparse mxArray, on success. Returns an indeterminate value on error. The most likely cause of failure is that array_ptr points to a full (nonsparse) mxArray.

Description

Use mxGetNzmax to get the value of the nzmax field. The nzmax field holds an integer value that signifies the number of elements in the ir, pr, and, if it exists, the pi arrays. The value of nzmax is always greater than or equal to the number of nonzero elements in a sparse mxArray. In addition, the value of nzmax is always less than or equal to the number of rows times the number of columns.

As you adjust the number of nonzero elements in a sparse mxArray, MATLAB often adjusts the value of the nzmax field. MATLAB adjusts nzmax in order to reduce the number of costly reallocations and in order to optimize its use of heap space.

Examples

Consider a MEX-file named SparCnt that displays

The number of nonzero elements in the mxArray.

The value of nzmax.

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 int nzmax, nnz, columns;

  if (mxIsSparse(prhs[0]))  {
    nzmax = mxGetNzmax(prhs[0]);
    columns = mxGetN(prhs[0]);
    nnz = *(mxGetJc(prhs[0]) + columns);
    mexPrintf("Contains %d nonzero elements.\n", nnz);
    mexPrintf("Allocates memory to hold %d elements.\n", nzmax);
  }
  else
    mexErrMsgTxt("First argument must be a sparse array."); 
}

In MATLAB, create a sparse mxArray named sparrow. Then, pass sparrow as an argument to SparCnt:

>> sparrow = sparse(eye(100));
>> SparCnt(sparrow)
Contains 100 nonzero elements.
Allocates memory to hold 100 elements.

Adding one nonzero element to sparrow causes MATLAB to increase nzmax by 10

>> sparrow(50, 75)=1;
>> mxGetNzmax(sparrow)
Contains 101 nonzero elements.
Allocates memory to hold 110 elements.

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