<html lang="en">
<head>
<title>Defining Indexing And Indexed Assignment - GNU Octave</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GNU Octave">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Indexing-Objects.html#Indexing-Objects" title="Indexing Objects">
<link rel="next" href="Indexed-Assignment-Optimization.html#Indexed-Assignment-Optimization" title="Indexed Assignment Optimization">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Defining-Indexing-And-Indexed-Assignment"></a>
<p>
Next: <a rel="next" accesskey="n" href="Indexed-Assignment-Optimization.html#Indexed-Assignment-Optimization">Indexed Assignment Optimization</a>,
Up: <a rel="up" accesskey="u" href="Indexing-Objects.html#Indexing-Objects">Indexing Objects</a>
<hr>
</div>
<h4 class="subsection">34.3.1 Defining Indexing And Indexed Assignment</h4>
<p>Objects can be indexed with parentheses, either like
<var>a</var><code> (</code><var>idx</var><code>)</code> or like <var>a</var><code> {</code><var>idx</var><code>}</code>, or even
like <var>a</var><code> (</code><var>idx</var><code>).</code><var>field</var>. However, it is up to the user
to decide what this indexing actually means. In the case of our polynomial
class <var>p</var><code> (</code><var>n</var><code>)</code> might mean either the coefficient of the
<var>n</var>-th power of the polynomial, or it might be the evaluation of the
polynomial at <var>n</var>. The meaning of this subscripted referencing is
determined by the <code>subsref</code> method.
<!-- subsref src/ov.cc -->
<p><a name="doc_002dsubsref"></a>
<div class="defun">
— Built-in Function: <b>subsref</b> (<var>val, idx</var>)<var><a name="index-subsref-2995"></a></var><br>
<blockquote><p>Perform the subscripted element selection operation according to
the subscript specified by <var>idx</var>.
<p>The subscript <var>idx</var> is expected to be a structure array with
fields ‘<samp><span class="samp">type</span></samp>’ and ‘<samp><span class="samp">subs</span></samp>’. Valid values for ‘<samp><span class="samp">type</span></samp>’
are ‘<samp><span class="samp">"()"</span></samp>’, ‘<samp><span class="samp">"{}"</span></samp>’, and ‘<samp><span class="samp">"."</span></samp>’.
The ‘<samp><span class="samp">subs</span></samp>’ field may be either ‘<samp><span class="samp">":"</span></samp>’ or a cell array
of index values.
<p>The following example shows how to extract the two first columns of
a matrix
<pre class="example"> val = magic(3)
⇒ val = [ 8 1 6
3 5 7
4 9 2 ]
idx.type = "()";
idx.subs = {":", 1:2};
subsref(val, idx)
⇒ [ 8 1
3 5
4 9 ]
</pre>
<p class="noindent">Note that this is the same as writing <code>val(:,1:2)</code>.
<p>If <var>idx</var> is an empty structure array with fields ‘<samp><span class="samp">type</span></samp>’
and ‘<samp><span class="samp">subs</span></samp>’, return <var>val</var>.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dsubsasgn.html#doc_002dsubsasgn">subsasgn</a>, <a href="doc_002dsubstruct.html#doc_002dsubstruct">substruct</a>.
</p></blockquote></div>
<p>For example we might decide that indexing with "()" evaluates the
polynomial and indexing with "{}" returns the <var>n</var>-th coefficient (of
<var>n</var>-th power). In this case the <code>subsref</code> method of our polynomial
class might look like
<pre class="example"><pre class="verbatim"> function b = subsref (a, s)
if (isempty (s))
error ("polynomial: missing index");
endif
switch (s(1).type)
case "()"
ind = s(1).subs;
if (numel (ind) != 1)
error ("polynomial: need exactly one index");
else
b = polyval (fliplr (a.poly), ind{1});
endif
case "{}"
ind = s(1).subs;
if (numel (ind) != 1)
error ("polynomial: need exactly one index");
else
if (isnumeric (ind{1}))
b = a.poly(ind{1}+1);
else
b = a.poly(ind{1});
endif
endif
case "."
fld = s.subs;
if (strcmp (fld, "poly"))
b = a.poly;
else
error ("@polynomial/subsref: invalid property \"%s\"", fld);
endif
otherwise
error ("invalid subscript type");
endswitch
if (numel (s) > 1)
b = subsref (b, s(2:end));
endif
endfunction
</pre>
</pre>
<p>The equivalent functionality for subscripted assignments uses the
<code>subsasgn</code> method.
<!-- subsasgn src/ov.cc -->
<p><a name="doc_002dsubsasgn"></a>
<div class="defun">
— Built-in Function: <b>subsasgn</b> (<var>val, idx, rhs</var>)<var><a name="index-subsasgn-2996"></a></var><br>
<blockquote><p>Perform the subscripted assignment operation according to
the subscript specified by <var>idx</var>.
<p>The subscript <var>idx</var> is expected to be a structure array with
fields ‘<samp><span class="samp">type</span></samp>’ and ‘<samp><span class="samp">subs</span></samp>’. Valid values for ‘<samp><span class="samp">type</span></samp>’
are ‘<samp><span class="samp">"()"</span></samp>’, ‘<samp><span class="samp">"{}"</span></samp>’, and ‘<samp><span class="samp">"."</span></samp>’.
The ‘<samp><span class="samp">subs</span></samp>’ field may be either ‘<samp><span class="samp">":"</span></samp>’ or a cell array
of index values.
<p>The following example shows how to set the two first columns of a
3-by-3 matrix to zero.
<pre class="example"> val = magic(3);
idx.type = "()";
idx.subs = {":", 1:2};
subsasgn (val, idx, 0)
⇒ [ 0 0 6
0 0 7
0 0 2 ]
</pre>
<p>Note that this is the same as writing <code>val(:,1:2) = 0</code>.
<p>If <var>idx</var> is an empty structure array with fields ‘<samp><span class="samp">type</span></samp>’
and ‘<samp><span class="samp">subs</span></samp>’, return <var>rhs</var>.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dsubsref.html#doc_002dsubsref">subsref</a>, <a href="doc_002dsubstruct.html#doc_002dsubstruct">substruct</a>.
</p></blockquote></div>
<!-- optimize_subsasgn_calls src/ov-usr-fcn.cc -->
<p><a name="doc_002doptimize_005fsubsasgn_005fcalls"></a>
<div class="defun">
— Built-in Function: <var>val</var> = <b>optimize_subsasgn_calls</b> ()<var><a name="index-optimize_005fsubsasgn_005fcalls-2997"></a></var><br>
— Built-in Function: <var>old_val</var> = <b>optimize_subsasgn_calls</b> (<var>new_val</var>)<var><a name="index-optimize_005fsubsasgn_005fcalls-2998"></a></var><br>
— Built-in Function: <b>optimize_subsasgn_calls</b> (<var>new_val, "local"</var>)<var><a name="index-optimize_005fsubsasgn_005fcalls-2999"></a></var><br>
<blockquote><p>Query or set the internal flag for subsasgn method call optimizations.
If true, Octave will attempt to eliminate the redundant copying when calling
subsasgn method of a user-defined class.
<p>When called from inside a function with the "local" option, the variable is
changed locally for the function and any subroutines it calls. The original
variable value is restored when exiting the function.
</p></blockquote></div>
<p>Note that the <code>subsref</code> and <code>subsasgn</code> methods always receive the
whole index chain, while they usually handle only the first element. It is the
responsibility of these methods to handle the rest of the chain (if needed),
usually by forwarding it again to <code>subsref</code> or <code>subsasgn</code>.
<p>If you wish to use the <code>end</code> keyword in subscripted expressions
of an object, then the user needs to define the <code>end</code> method for
the class. For example, the <code>end</code> method for our polynomial class might
look like
<pre class="example"><pre class="verbatim"> function r = end (obj, index_pos, num_indices)
if (num_indices != 1)
error ("polynomial object may only have one index")
endif
r = length (obj.poly) - 1;
endfunction
</pre>
</pre>
<p class="noindent">which is a fairly generic <code>end</code> method that has a behavior similar to
the <code>end</code> keyword for Octave Array classes. It can then be used as
follows:
<pre class="example"> p = polynomial([1,2,3,4]);
p(end-1)
⇒ 3
</pre>
<p>Objects can also be used as the index in a subscripted expression themselves
and this is controlled with the <code>subsindex</code> function.
<!-- subsindex scripts/general/subsindex.m -->
<p><a name="doc_002dsubsindex"></a>
<div class="defun">
— Function File: <var>idx</var> = <b>subsindex</b> (<var>a</var>)<var><a name="index-subsindex-3000"></a></var><br>
<blockquote><p>Convert an object to an index vector. When <var>a</var> is a class object
defined with a class constructor, then <code>subsindex</code> is the
overloading method that allows the conversion of this class object to
a valid indexing vector. It is important to note that
<code>subsindex</code> must return a zero-based real integer vector of the
class "double". For example, if the class constructor
<pre class="example"> function b = myclass (a)
b = class (struct ("a", a), "myclass");
endfunction
</pre>
<p class="noindent">then the <code>subsindex</code> function
<pre class="example"> function idx = subsindex (a)
idx = double (a.a) - 1.0;
endfunction
</pre>
<p class="noindent">can then be used as follows
<pre class="example"> a = myclass (1:4);
b = 1:10;
b(a)
⇒ 1 2 3 4
</pre>
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dclass.html#doc_002dclass">class</a>, <a href="doc_002dsubsref.html#doc_002dsubsref">subsref</a>, <a href="doc_002dsubsasgn.html#doc_002dsubsasgn">subsasgn</a>.
</p></blockquote></div>
<p>Finally, objects can equally be used like ranges, using the <code>colon</code>
method
<!-- colon scripts/general/colon.m -->
<p><a name="doc_002dcolon"></a>
<div class="defun">
— Function File: <var>r</var> = <b>colon</b> (<var>a, b</var>)<var><a name="index-colon-3001"></a></var><br>
— Function File: <var>r</var> = <b>colon</b> (<var>a, b, c</var>)<var><a name="index-colon-3002"></a></var><br>
<blockquote><p>Method of a class to construct a range with the <code>:</code> operator. For
example:
<pre class="example"> a = myclass (...);
b = myclass (...);
c = a : b
</pre>
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dclass.html#doc_002dclass">class</a>, <a href="doc_002dsubsref.html#doc_002dsubsref">subsref</a>, <a href="doc_002dsubsasgn.html#doc_002dsubsasgn">subsasgn</a>.
</p></blockquote></div>
</body></html>
