(octave.info)Index Expressions

---

Next: Calling Functions Up: Expressions

---

Enter node , (file) or (file)node

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]

Advanced Indexing