MATLAB®

mxCalcSingleSubscript (C and Fortran) - Offset from first element to desired element

C Syntax

#include "matrix.h"
mwIndex mxCalcSingleSubscript(const mxArray *pm, mwSize nsubs, 
    mwIndex *subs);

Fortran Syntax

mwIndex mxCalcSingleSubscript(pm, nsubs, subs)
mwPointer pm
mwSize nsubs
mwIndex subs

Arguments

pm

Pointer to an mxArray

nsubs

The number of elements in the subs array. Typically, you set nsubs equal to the number of dimensions in the mxArray that pm points to.

subs

An array of integers. Each value in the array should specify that dimension's subscript. In C syntax, the value in subs[0] specifies the row subscript, and the value in subs[1] specifies the column subscript. Use zero-based indexing for subscripts. For example, to express the starting element of a two-dimensional mxArray in subs, set subs[0] to 0 and subs[1] to 0.

In Fortran syntax, the value in subs(1) specifies the row subscript, and the value in subs(2) specifies the column subscript. Use 1-based indexing for subscripts. For example, to express the starting element of a two-dimensional mxArray in subs, set subs(1) to 1 and subs(2) to 1.

Returns

The number of elements between the start of the mxArray and the specified subscript. This returned number is called an index; many mx routines (for example, mxGetField) require an index as an argument.

If subs describes the starting element of an mxArray, mxCalcSingleSubscript returns 0. If subs describes the final element of an mxArray, mxCalcSingleSubscript returns N-1 (where N is the total number of elements).

Description

Call mxCalcSingleSubscript to determine how many elements there are between the beginning of the mxArray and a given element of that mxArray. For example, given a subscript like (5,7), mxCalcSingleSubscript returns the distance from the first element of the array to the (5,7) element. Remember that the mxArray data type internally represents all data elements in a one-dimensional array no matter how many dimensions the MATLAB^® mxArray appears to have.

MATLAB uses a column-major numbering scheme to represent data elements internally. That means that MATLAB internally stores data elements from the first column first, then data elements from the second column second, and so on through the last column. For example, suppose you create a 4-by-2 variable. It is helpful to visualize the data as follows.

In fact, though, MATLAB internally represents the data as the following:

If an mxArray is N-dimensional, MATLAB represents the data in N-major order. For example, consider a three-dimensional array having dimensions 4-by-2-by-3. Although you can visualize the data as

MATLAB internally represents the data for this three-dimensional array in the following order:

Avoid using mxCalcSingleSubscript to traverse the elements of an array. In C, it is more efficient to do this by finding the array's starting address and then using pointer autoincrementing to access successive elements. For example, to find the starting address of a numerical array, call mxGetPr or mxGetPi.

C Examples

See mxcalcsinglesubscript.c in the mx subdirectory of the examples directory.

See Also

mxGetCell, mxSetCell

mxAssertS (C)

mxCalloc (C and Fortran)