| 外部インタフェース/API リファレンス | |
最初の要素から希望する要素へのオフセット(インデックス)を出力
C 言語表示
#include <matrix.h> int mxCalcSingleSubscript(const mxArray *array_ptr, int nsubs, int *subs);
nsubs
subs配列内の要素数。一般的にnsubsは、array_ptrが指し示すmxArrayの次元数に等しくなるように設定します。
subs
subs[0]内の値は行のサブスクリプトを指定し、subs[1]内の値は列のサブスクリプトを指定します。mxCalcSingleSubscriptは0をmxArrayの最初の要素としますが、MATLABは1をmxArrayの最初の要素とします。たとえばMATLABでは、(1,1)は2次元のmxArrayの開始要素を示しますが、subs内の2次元のmxArrayの開始要素を表すには、subs[0]を0に設定し、subs[1]を0に設定しなければなりません。
戻り値
mxArrayの先頭と指定したサブスクリプトとの間の要素数。この戻り値は、"インデックス"と呼ばれます。多くのmxルーチン(たとえば、mxGetField)は、引数としてインデックスを必要とします。
subsがmxArrayの最初の要素を記述する場合、mxCalcSingleSubscriptは0を出力します。subsがmxArrayの最後の要素を記述する場合、mxCalcSingleSubscriptはN-1を出力します(ここで、Nは要素の総数です)。
詳細
mxCalcSingleSubscriptを呼び出すことによって、mxArrayの最初の要素とmxArrayの与えられた要素との間にある要素数を決定します。たとえば、サブスクリプトが(5,7)のように与えられた場合は、mxCalcSingleSubscriptは配列の(0,0)要素から(5,7)要素への距離を出力します。mxArrayのデータタイプは、MATLABのmxArrayの次元がどんなに大きくても、1次元配列ですべてのデータ要素を内部的に表します。
MATLABは、内部的にデータ要素を表すために、列単位のナンバリングを用います。MATLABは1列目のデータの要素を最初に内部的に格納し、その後2列目のデータの要素を2番目に格納するという方法で最後の列まで格納します。たとえば、4行2列の変数を作成するとします。データを以下のように可視化すると便利です。
| A |
E |
| B |
F |
| C |
G |
| D |
H |
| A |
B |
C |
D |
E |
F |
G |
H |
| Index 0 |
Index 1 |
Index 2 |
Index 3 |
Index 4 |
Index 5 |
Index 6 |
Index 7 |
その結果、1列目はインデックス0から3で、2列目はインデックス4から7です。
mxArrayがN次元ならば、MATLABはデータをNの順番で表します。たとえば、3次元配列の次元が4×2×3であると考えます。データをつぎのように可視化することができます。
MATLABは、3次元配列のデータをつぎのような順番で内部的に表します。
| 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 |
そのため、page 1のインデックスは、page 2のインデックスよりも小さくなります。各々のページ内で、1列目のインデックスは、2列目のインデックスよりも小さくなります。各々の列で、1行目のインデックスは2行目のインデックスより小さくなります。
mxCalcSingleSubscriptは、個々のオフセットを得るための効果的な方法を提供しています。しかし、ほとんどのアプリケーションは単一のオフセットだけを必要とするわけではありません。むしろ、ほとんどのアプリケーションでは、配列内のデータの各要素に渡っています。そのような場合には、 mxCalcSingleSubscriptの利用を避けてください。配列のすべての要素を用いるためには、配列の開始アドレスを求めて、連続する要素にアクセスするためにポインタの自動インクリメントを用いるほうがはるかに効率的です。たとえば、数値配列の開始アドレスを求めるためには、mxGetPrまたはmxGetPiを呼び出してください。
例題
examplesディレクトリのmxサブディレクトリのmxcalcsinglesubscript.cを参照してください。
| | mxAssertS | mxCalloc | |
