Using the C Math Library

Array Storage

MATLAB stores each array as a column of values regardless of the actual dimensions. This column consists of the array columns, appended top to bottom. For example, MATLAB stores

A = [2 6 9; 4 2 8; 3 0 1]

as

  2
  4
  3
  6
  2
  0
  9
  8
  1

Accessing A with a single subscript indexes directly into the storage column. A(3) accesses the third value in the column, the number 3. A(7) accesses the seventh value, 9, and so on.

If you supply more subscripts, MATLAB calculates an index into the storage column based on the array's dimensions. For example, assume a two-dimensional array like A has size [d1 d2], where d1 is the number of rows in the array and d2 is the number of columns. If you supply two subscripts (i,j) representing row-column indices, the equivalent one-dimensional index is

(j-1)*d1+i

Given the expression A(3,2), MATLAB calculates the offset into A's storage column as (2-1)*3+3, or 6. Counting down six elements in the column accesses the value 0.

This storage and indexing scheme also extends to multidimensional arrays. You can think of an N-dimensional array as a series of "pages," each of which is a two-dimensional array. The first two dimensions in the N-dimensional array determine the shape of the pages, and the remaining dimensions determine the number of pages.

In a three- (or higher) dimensional array, for example, MATLAB iterates over the pages to create the storage column, again appending elements column-wise. You can think of three-dimensional arrays as "books," with a two-dimensional array on each page. The term page is used frequently in this document to refer to a two-dimensional array that is part of a larger N-dimensional array.

Labeling the dimensions past three is more difficult. You can imagine shelves of books for dimension 4, rooms of shelves for dimension 5, libraries of rooms for dimension 6, etc. This document rarely uses an array of dimension greater than three or four, although MATLAB and the MATLAB C Math Library handle any number of dimensions that doesn't exceed the amount of memory available on your computer.

For example, consider a 5-by-4-by-3-by-2 array C.

Again, a single subscript indexes directly into this column. For example, C(4) produces the result

ans =

     0

If you specify two subscripts (i,j) indicating row-column indices, MATLAB calculates the offset as described above. Two subscripts always access the first page of a multidimensional array, provided they are within the range of the original array dimensions.

If more than one subscript is present, all subscripts must conform to the original array dimensions. For example, C(6,2) is invalid, because all pages of C have only five rows.

If you specify more than two subscripts, MATLAB extends its indexing scheme accordingly. For example, consider four subscripts (i,j,k,l) into a four-dimensional array with size [d1 d2 d3 d4]. MATLAB calculates the offset into the storage column by

(l-1)(d3)(d2)(d1)+(k-1)(d2)(d1)+(j-1)(d1)+i

For example, if you index the array C using subscripts (3,4,2,1), MATLAB returns the value 5 (index 38 in the storage column).

In general, the offset formula for an array with dimensions [d₁ d₂ d₃ ... d_n] using any subscripts (s₁ s₂ s₃ ... s_n) is:

(sn-1)(dn-1)(dn-2)...(d1)+(sn-1-1)(dn-2)...(d1)+...+(s2-1)(d1)+s1

Because of this scheme, you can index an array using any number of subscripts. You can append any number of 1s to the subscript list because these terms become zero. For example, C(3,2,1,1,1,1,1,1) is equivalent to C(3,2).

Indexing Functions

Calling the Indexing Functions