8.1 Index Expressions

An index expression allows you to reference or extract selected elements of a vector, a matrix (2-D), or a higher-dimensional array.

Indices may be scalars, vectors, ranges, or the special operator ‘:’, which selects entire rows, columns, or higher-dimensional slices.

An index expression consists of a set of parentheses enclosing M expressions separated by commas. Each individual index value, or component, is used for the respective dimension of the object that it is applied to. In other words, the first index component is used for the first dimension (rows) of the object, the second index component is used for the second dimension (columns) of the object, and so on. The number of index components M defines the dimensionality of the index expression. An index with two components would be referred to as a 2-D index because it has two dimensions.

In the simplest case, 1) all components are scalars, and 2) the dimensionality of the index expression M is equal to the dimensionality of the object it is applied to. For example:

A = reshape (1:8, 2, 2, 2)  # Create 3-D array
A =

ans(:,:,1) =

   1   3
   2   4

ans(:,:,2) =

   5   7
   6   8

A(2, 1, 2)   # second row, first column of second slice
             # in third dimension: ans = 6

The size of the returned object in a specific dimension is equal to the number of elements in the corresponding component of the index expression. When all components are scalars, the result is a single output value. However, if any component is a vector or range then the returned values are the Cartesian product of the indices in the respective dimensions. For example:

A([1, 2], 1, 2) ≡ [A(1,1,2); A(2,1,2)]
⇒
ans =
   5
   6

The total number of returned values is the product of the number of elements returned for each index component. In the example above, the total is 2*1*1 = 2 elements.

Notice that the size of the returned object in a given dimension is equal to the number of elements in the index expression for that dimension. In the code above, the first index component ([1, 2]) was specified as a row vector, but its shape is unimportant. The important fact is that the component specified two values, and hence the result must have a size of two in the first dimension; and because the first dimension corresponds to rows, the overall result is a column vector.

A(1, [2, 1, 1], 1)    # result is a row vector: ans = [3, 1, 1]
A(ones (2, 2), 1, 1)  # result is a column vector: ans = [1; 1; 1; 1]

The first line demonstrates again that the size of the output in a given dimension is equal to the number of elements in the respective indexing component. In this case, the output has three elements in the second dimension (which corresponds to columns), so the result is a row vector. The example also shows how repeating entries in the index expression can be used to replicate elements in the output. The last example further proves that the shape of the indexing component is irrelevant, it is only the number of elements (2x2 = 4) which is important.

The above rules apply whenever the dimensionality of the index expression is greater than one (M > 1). However, for one-dimensional index expressions special rules apply and the shape of the output is determined by the shape of the indexing component. For example:

A([1, 2])  # result is a row vector: ans = [1, 2]
A([1; 2])  # result is a column vector: ans = [1; 2]

Note that it is permissible to use a 1-D index with a multi-dimensional object (also called linear indexing). In this case, the elements of the multi-dimensional array are taken in column-first order like Fortran. That is, the columns of the array are imagined to be stacked on top of each other to form a column vector and then the single linear index is applied to this vector.

A(5)    # linear indexing into three-dimensional array: ans = 5
A(3:5)  # result has shape of index component: ans = [3, 4, 5]

A colon (‘:’) may be used as an index component to select all of the elements in a specified dimension. Given the matrix,

A = [1, 2; 3, 4]

all of the following expressions are equivalent and select the first row of the matrix.

A(1, [1, 2])  # row 1, columns 1 and 2
A(1, 1:2)     # row 1, columns in range 1-2
A(1, :)       # row 1, all columns

When a colon is used in the special case of 1-D indexing the result is always a column vector. Creating column vectors with a colon index is a very frequently encountered code idiom and is faster and generally clearer than calling reshape for this case.

A(:)    # result is column vector: ans = [1; 2; 3; 4]
A(:)'   # result is row vector: ans = [1, 2, 3, 4]

In index expressions the keyword end automatically refers to the last entry for a particular dimension. This magic index can also be used in ranges and typically eliminates the needs to call size or length to gather array bounds before indexing. For example:

A(1:end/2)        # first half of A => [1, 2]
A(end + 1) = 5;   # append element
A(end) = [];      # delete element
A(1:2:end)        # odd elements of A => [1, 3]
A(2:2:end)        # even elements of A => [2, 4]
A(end:-1:1)       # reversal of A => [4, 3, 2, 1]