mxSetJc (C and Fortran)

JC array of sparse array

C Syntax

#include "matrix.h"
void mxSetJc(mxArray *pm, mwIndex *jc);

Fortran Syntax

#include "fintrf.h"
subroutine mxSetJc(pm, jc)
mwPointer pm, jc

Arguments

pm

Pointer to a sparse mxArray

jc

Pointer to the jc array

Description

Use mxSetJc to specify a new jc array for a sparse mxArray. The jc array is an integer array having n+1 elements, where n is the number of columns in the sparse mxArray.

If the jth column of the sparse mxArray has any nonzero elements, then:

• jc[j] is the index in ir, pr, and pi (if it exists) of the first nonzero element in the jth column.

• jc[j+1]-1 is the index of the last nonzero element in the jth column.

• For the jth column of the sparse matrix, jc[j] is the total number of nonzero elements in all preceding columns.

The number of nonzero elements in the jth column of the sparse mxArray is:

jc[j+1] - jc[j];

For the jth column of the sparse mxArray, jc[j] is the total number of nonzero elements in all preceding columns. The last element of the jc array, jc[number of columns], is equal to nnz, which is the number of nonzero elements in the entire sparse mxArray.

For example, consider a 7-by-3 sparse mxArray named Sparrow containing six nonzero elements, created 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 following table lists the contents of the ir, jc, and pr arrays.

Subscript	ir	pr	jc	Comment
(2,1)	1	1	0	Column 1 contains two nonzero elements, with rows designated by ir[0] and ir[1]
(5,1)	4	1	2	Column 2 contains one nonzero element, with row designated by ir[2]
(3,2)	2	1	3	Column 3 contains three nonzero elements, with rows designated by ir[3],ir[4], and ir[5]
(2,3)	1	2	6	There are six nonzero elements in all.
(5,3)	4	1
(6,3)	5	1

As an example of a much sparser mxArray, consider a 1000-by-8 sparse mxArray named Spacious containing only three nonzero elements. The ir, pr, and jc arrays contain the values listed in this table.

Subscript	ir	pr	jc	Comment
(73,2)	72	1	0	Column 1 contains no nonzero elements.
(50,3)	49	1	0	Column 2 contains one nonzero element, with row designated by ir[0].
(64,5)	63	1	1	Column 3 contains one nonzero element, with row designated by ir[1].
			2	Column 4 contains no nonzero elements.
			2	Column 5 contains one nonzero element, with row designated by ir[2].
			3	Column 6 contains no nonzero elements.
			3	Column 7 contains no nonzero elements.
			3	Column 8 contains no nonzero elements.
			3	There are three nonzero elements in all.

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 mxGetJc before you call mxSetJc.

Examples

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

• mxsetdimensions.c

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

• explore.c