External Interfaces Reference |
Return offset from first element to desired element
C Syntax
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
A |
E |
B |
F |
C |
G |
D |
H |
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 |
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
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 |
Avoid using mxCalcSingleSubscript
to traverse the elements of an array. It is more efficient to do this by finding the array's starting address and then using pointer auto-incrementing to access successive elements. For example, to find the starting address of a numerical array, call mxGetPr
or mxGetPi
.
Examples
See mxcalcsinglesubscript.c
in the mx
subdirectory of the examples
directory.
mxAssertS | mxCalloc |
© 1994-2005 The MathWorks, Inc.