<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Index Expressions (GNU Octave (version 5.1.0))</title>
<meta name="description" content="Index Expressions (GNU Octave (version 5.1.0))">
<meta name="keywords" content="Index Expressions (GNU Octave (version 5.1.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Expressions.html#Expressions" rel="up" title="Expressions">
<link href="Advanced-Indexing.html#Advanced-Indexing" rel="next" title="Advanced Indexing">
<link href="Expressions.html#Expressions" rel="prev" title="Expressions">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<a name="Index-Expressions"></a>
<div class="header">
<p>
Next: <a href="Calling-Functions.html#Calling-Functions" accesskey="n" rel="next">Calling Functions</a>, Up: <a href="Expressions.html#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Index-Expressions-1"></a>
<h3 class="section">8.1 Index Expressions</h3>
<a name="index-_0028"></a>
<a name="index-_0029"></a>
<a name="index-_003a"></a>
<p>An <em>index expression</em> allows you to reference or extract selected
elements of a vector, a matrix (2-D), or a higher-dimensional array.
</p>
<p>Indices may be scalars, vectors, ranges, or the special operator ‘<samp>:</samp>’,
which selects entire rows, columns, or higher-dimensional slices.
</p>
<p>An index expression consists of a set of parentheses enclosing <em>M</em>
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 <em>M</em>
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.
</p>
<p>In the simplest case, 1) all components are scalars, and 2) the dimensionality
of the index expression <em>M</em> is equal to the dimensionality of the object
it is applied to. For example:
</p>
<div class="example">
<pre class="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
</pre></div>
<p>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:
</p>
<div class="example">
<pre class="example">A([1, 2], 1, 2) ≡ [A(1,1,2); A(2,1,2)]
⇒
ans =
5
6
</pre></div>
<p>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.
</p>
<p>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 (<code>[1, 2]</code>) 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.
</p>
<div class="example">
<pre class="example">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]
</pre></div>
<p>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.
</p>
<p>The above rules apply whenever the dimensionality of the index expression
is greater than one (<em>M > 1</em>). However, for one-dimensional index
expressions special rules apply and the shape of the output <strong>is</strong>
determined by the shape of the indexing component. For example:
</p>
<div class="example">
<pre class="example">A([1, 2]) # result is a row vector: ans = [1, 2]
A([1; 2]) # result is a column vector: ans = [1; 2]
</pre></div>
<p>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.
</p>
<div class="example">
<pre class="example">A(5) # linear indexing into three-dimensional array: ans = 5
A(3:5) # result has shape of index component: ans = [3, 4, 5]
</pre></div>
<a name="index-_003a_002c-indexing-expressions"></a>
<p>A colon (‘<samp>:</samp>’) may be used as an index component to select all of the
elements in a specified dimension. Given the matrix,
</p>
<div class="example">
<pre class="example">A = [1, 2; 3, 4]
</pre></div>
<p>all of the following expressions are equivalent and select the first row of the
matrix.
</p>
<div class="example">
<pre class="example">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
</pre></div>
<p>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
<code>reshape</code> for this case.
</p>
<div class="example">
<pre class="example">A(:) # result is column vector: ans = [1; 2; 3; 4]
A(:)' # result is row vector: ans = [1, 2, 3, 4]
</pre></div>
<a name="index-end_002c-indexing"></a>
<a name="index-end_003aend_003a-and-_003aend"></a>
<p>In index expressions the keyword <code>end</code> 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 <code>size</code> or <code>length</code> to
gather array bounds before indexing. For example:
</p>
<div class="example">
<pre class="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]
</pre></div>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="Advanced-Indexing.html#Advanced-Indexing" accesskey="1">Advanced Indexing</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<div class="header">
<p>
Next: <a href="Calling-Functions.html#Calling-Functions" accesskey="n" rel="next">Calling Functions</a>, Up: <a href="Expressions.html#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
