mxSetIr (MATLAB Application Program Interface)

Set the ir array of a sparse mxArray

#include "matrix.h"
void mxSetIr(mxArray *array_ptr, int *ir);

Arguments

array_ptr
Pointer to a sparse mxArray.

ir
Pointer to the ir array. The ir array must be sorted in column-major order.

Description

Use mxSetIr to specify the ir array of a sparse mxArray. The ir array is an array of integers; the length of the ir array should equal the value of nzmax.

Each element in the 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. See mxSetJc for more details on jc.)

For example, suppose you create a 7-by-3 sparse mxArray named Sparrow containing six nonzero elements by typing

>> Sparrow=zeros(7,3);
>> Sparrow(2,1)=1;
>> Sparrow(5,1)=1;
>> Sparrow(3,2)=1;
>> Sparrow(2,3)=2;
>> Sparrow(5,3)=1;
>> Sparrow(6,3)=1;
>> Sparrow=sparse(Sparrow);

The pr array holds the real data for the sparse matrix, which in Sparrow is the five 1s and the one 2. If there is any nonzero imaginary data, then it is in a pi array.


Subscript	ir	pr	jc	Comments
`(2,1)`	`1`	`1`	`0`	Column 1; ir is 1 because row is 2.
`(5,1)`	`4`	`1`	`2`	Column 1; ir is 4 because row is 5.
`(3,2)`	`2`	`1`	`3`	Column 2; ir is 2 because row is 3.
`(2,3)`	`1`	`2`	`6`	Column 3; ir is 1 because row is 2.
`(5,3)`	`4`	`1`		Column 3; ir is 4 because row is 5.
`(6,3)`	`5`	`1`		Column 3; ir is 5 because row is 6.

Notice how each element of the ir array is always 1 less than the row of the corresponding nonzero element. For instance, the first nonzero element is in row 2; therefore, the first element in ir is 1 (that is, 2-1). The second nonzero element is in row 5; therefore, the second element in ir is 4 (5-1).

The ir array must be in column-major order. That means that the ir array must define the row positions in column 1 (if any) first, then the row positions in column 2 (if any) second, and so on through column N. Within each column, row position 1 must appear prior to row position 2, and so on.

mxSetIr does not sort the ir array for you; you must specify an ir array that is already sorted.

Examples

See the examples on the mxSetNzmax reference page, and mxsetir.c in the mx subdirectory of the examples directory