mxGetIr (MATLAB Application Program Interface)

Get the ir array of a sparse matrix

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

Arguments

array_ptr
Pointer to a sparse mxArray.

Returns

A pointer to the first element in the ir array, if successful. Otherwise, returns NULL. Possible causes of failure include

Specifying a full (nonsparse) mxArray.
Specifying a NULL array_ptr. (This usually means that an earlier call to mxCreateSparse failed.)

Description

Use mxGetIr to obtain the starting address of the ir array. The ir array is an array of integers; the length of the ir array is typically nzmax values. For example, if nzmax equals 100, then the ir array should contain 100 integers.

Each value in an ir array indicates a row (offset by 1) at which a nonzero element can be found. (The jc array is an index that indirectly specifies a column where nonzero elements can be found.)

For details on the ir and jc arrays, see mxSetIr and mxSetJc.

Examples

Consider a MEX-file named PrSparse that displays the positions and values of all nonzero elements in the input sparse mxArray.

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 double  *pr;
 int     *ir, *jc;
 int      row, col, total=0, number_of_columns;
 int      starting_row_index, stopping_row_index, 
current_row_index;

 /* Get the starting positions of the data in the sparse array. */  
   pr = mxGetPr(prhs[0]);
   ir = mxGetIr(prhs[0]);
   jc = mxGetJc(prhs[0]);

 /* Display the nonzero elements of the sparse array. */ 
   number_of_columns = mxGetN(prhs[0]);
   for (col=0; col<number_of_columns; col++)  { 
      starting_row_index = jc[col]; 
      stopping_row_index = jc[col+1]; 
      if (starting_row_index == stopping_row_index)
         continue;
      else {
         for (current_row_index = starting_row_index; 
              current_row_index < stopping_row_index; 
              current_row_index++) 
            mexPrintf("(%d,%d) = %g\n", ir[current_row_index]+1, 
                                        col+1, pr[total++]);
      }
   }
}

In MATLAB, create a sparse mxArray named Sparrow containing four nonzero elements:

>> Sparrow=sparse(zeros(100,3));
>> Sparrow(50,1)=1;
>> Sparrow(23,2)=1;
>> Sparrow(37,2)=1;
>> Sparrow(92,2)=1;

Passing Sparrow as the first argument to PrSparse yields:

>> PrSparse(Sparrow)
(50,1) = 1
(23,2) = 1
(37,2) = 1
(92,2) = 1

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