mxSetIr (C and Fortran)

C Syntax

#include "matrix.h"
void mxSetIr(mxArray *pm, mwIndex *ir);

Fortran Syntax

#include "fintrf.h"
subroutine mxSetIr(pm, ir)
mwPointer pm, ir

Arguments

pm: 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 equals the value of nzmax, the storage allocated for the sparse array, or nnz, the number of nonzero matrix elements.

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 that 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. 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 before 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.

This function does not free any memory allocated for existing data that it displaces. To free existing memory, call mxFree on the pointer returned by mxGetIr before you call mxSetIr.

Examples

See these examples in matlabroot/extern/examples/mx:

mxsetnzmax.c

See these examples in matlabroot/extern/examples/mex:

explore.c