Return the offset (index) from the first element to the desired element
C Syntax
#include <matrix.h>
int mxCalcSingleSubscript(const mxArray *array_ptr, int nsubs,
int *subs);
Arguments
array_ptr
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 array_ptr points to.
subs
An array of integers. Each value in the array should specify that dimension's subscript. The value in subs[0] specifies the row subscript, and the value in subs[1] specifies the column subscript. Note that mxCalcSingleSubscript views 0 as the first element of an mxArray, but MATLAB sees 1 as the first element of an mxArray. For example, in MATLAB, (1,1) denotes the starting element of a two-dimensional mxArray; however, to express the starting element of a two-dimensional mxArray in subs, you must set subs[0] to 0 and subs[1] to 0.
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, then 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 (0,0) 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
shown below:
Although in fact, MATLAB internally represents the data as the following:
A
|
B
|
C
|
D
|
E
|
F
|
G
|
H
|
Index 0
|
Index 1
|
Index 2
|
Index 3
|
Index 4
|
Index 5
|
Index 6
|
Index 7
|
Thus, the first column has indices 0 through 3 and the second column has indices 4 through 7.
If an mxArray is N-dimensional, then 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 shown on the following page:
MATLAB internally represents the data for this three-dimensional array in the order shown below:
A
|
B
|
C
|
D
|
E
|
F
|
G
|
H
|
I
|
J
|
K
|
L
|
M
|
N
|
O
|
P
|
Q
|
R
|
S
|
T
|
U
|
V
|
W
|
X
|
0
|
1
|
2
|
3
|
4
|
5
|
6
|
7
|
8
|
9
|
10
|
11
|
12
|
13
|
14
|
15
|
16
|
17
|
18
|
19
|
20
|
21
|
22
|
23
|
Thus, the indices of page 1 are lower than the indices of page 2. Within each page, the indices of the first column are lower than the indices of the second column. Within each column, the indices of the first row are lower than the indices of the second row.
mxCalcSingleSubscript provides an efficient way to get an individual offset. However, most applications do not need to get just a single offset. Rather, most applications have to walk through each element of data in an array. In such cases, avoid using mxCalcSingleSubscript. To walk through all elements of the array, it is far more efficient to find the array's starting address and then use pointer auto-incrementing to access successive elements. For example, to find the starting address of a numerical array, call mxGetPr or mxGetPi.
Examples
Given a two-dimensional input array in prhs[0], find the value stored at element (2,3):
void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray
*prhs[])
{
int nsubs = 2;
int subs[] = {2, 3};
double *start_of_real_data;
int index;
double value;
/* Find the index of location (2, 3).
Note that (2,3) corresponds to (3,4) in MATLAB. */
index = mxCalcSingleSubscript(prhs[0], nsubs, subs);
/* Get the start of the real data in the array. */
if (mxIsDouble(prhs[0])) {
start_of_real_data = (double *)mxGetPr(prhs[0]);
/* Get the address for location (2,3), then dereference it,
and print it. */
value = *(start_of_real_data + index);
mexPrintf("The value at MATLAB's (%d,%d) is %g\n",
subs[0]+1, subs[1]+1, value);
}
else
mexErrMsgTxt("Input array must be a double.");
}
Given a three-dimensional array in prhs[0], setting
int nsubs = 3;
int subs[] = {5, 12, 9};
returns the offset of (5, 12, 9) from the (0, 0, 0) element. Given a three-dimensional array in prhs[0], setting
int nsubs = 2;
int subs[] = {5, 12, 9};
returns the offset of (5, 12, 0) from the (0, 0, 0) element. For an additional example, see mxcalcsinglesubscript.c in the mx subdirectory of the examples directory.
[ Previous | Help Desk | Next ]