MATLAB Application Program Interface Reference Help Desk

mxSetNzmax

Purpose

Set the storage space for nonzero elements

C Syntax

Arguments

array_ptr

Pointer to a sparse mxArray.

nzmax

The number of elements that mxCreateSparse should allocate to hold the arrays pointed to by ir, pr, and pi (if it exists). You should set nzmax greater than or equal to the number of nonzero elements in the mxArray, but you should set it to be less than or equal to the number of rows times the number of columns. If you specify an nzmax value of 0, mxSetNzmax sets the value of nzmax to 1.

Description

Use mxSetNzmax to assign a new value to the nzmax field of the specified sparse mxArray. The nzmax field holds the maximum possible number of nonzero elements in the sparse mxArray.

The number of elements in the ir, pr, and pi (if it exists) arrays must be equal to nzmax. Therefore, after calling mxSetNzmax, you must change the size of the ir, pr, and pi arrays. To change the size of one of these arrays, you should

  1. Call mxCalloc, setting n to the new value of nzmax.
  2. Call the ANSI C routine memcpy to copy the contents of the old array to the new area allocated in Step 1.
  3. Call mxFree to free the memory occupied by the old array.
  4. Call the appropriate mxSet routine (mxSetIr, mxSetPr, or mxSetPi) to establish the new memory area as the current one.
How big should nzmax be? One philosophy is that you should set nzmax equal to or slightly greater than the number of nonzero elements in a sparse mxArray. This philosophy conserves precious heap space. Another philosophy is that you should make nzmax equal to the total number of elements in an mxArray. This philosophy eliminates (or, at least reduces) expensive reallocations.

Examples

Create a sparse mxArray, then reduce its nzmax value to conserve heap space:

There is no need to adjust pi because Sparrow is purely real. For an additional example, see mxSetNzmax.c in the mx subdirectory of the examples directory.

See Also

mxGetNzmax



[ Previous | Help Desk | Next ]