1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Defining Indexing And Indexed Assignment (GNU Octave (version 10.3.0))</title>
<meta name="description" content="Defining Indexing And Indexed Assignment (GNU Octave (version 10.3.0))">
<meta name="keywords" content="Defining Indexing And Indexed Assignment (GNU Octave (version 10.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Indexing-Objects.html" rel="up" title="Indexing Objects">
<link href="Indexed-Assignment-Optimization.html" rel="next" title="Indexed Assignment Optimization">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<div class="subsection-level-extent" id="Defining-Indexing-And-Indexed-Assignment">
<div class="nav-panel">
<p>
Next: <a href="Indexed-Assignment-Optimization.html" accesskey="n" rel="next">Indexed Assignment Optimization</a>, Up: <a href="Indexing-Objects.html" accesskey="u" rel="up">Indexing Objects</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsection" id="Defining-Indexing-And-Indexed-Assignment-1"><span>34.3.1 Defining Indexing And Indexed Assignment<a class="copiable-link" href="#Defining-Indexing-And-Indexed-Assignment-1"> ¶</a></span></h4>
<p>Objects can be indexed with parentheses or braces, either like
<code class="code"><var class="var">obj</var>(<var class="var">idx</var>)</code> or like <code class="code"><var class="var">obj</var>{<var class="var">idx</var>}</code>, or even
like <code class="code"><var class="var">obj</var>(<var class="var">idx</var>).<var class="var">field</var></code>. However, it is up to the
programmer to decide what this indexing actually means. In the case of the
polynomial class <code class="code"><var class="var">p</var>(<var class="var">n</var>)</code> might mean either the coefficient of
the <var class="var">n</var>-th power of the polynomial, or it might be the evaluation of the
polynomial at <var class="var">n</var>. The meaning of this subscripted referencing is
determined by the <code class="code">subsref</code> method.
</p>
<a class="anchor" id="XREFsubsref"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-subsref"><span><code class="def-type"><var class="var">newval</var> =</code> <strong class="def-name">subsref</strong> <code class="def-code-arguments">(<var class="var">val</var>, <var class="var">idx</var>)</code><a class="copiable-link" href="#index-subsref"> ¶</a></span></dt>
<dd><p>Perform the subscripted element selection operation on <var class="var">val</var> according
to the subscript specified by <var class="var">idx</var>.
</p>
<p>The subscript <var class="var">idx</var> must be a structure array with fields ‘<samp class="samp">type</samp>’
and ‘<samp class="samp">subs</samp>’. Valid values for ‘<samp class="samp">type</samp>’ are <code class="code">"()"</code>,
<code class="code">"{}"</code>, and <code class="code">"."</code>. The ‘<samp class="samp">subs</samp>’ field may be either
<code class="code">":"</code> or a cell array of index values.
</p>
<p>The following example shows how to extract the first two columns of a matrix
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">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></div></div>
<p>Note that this is the same as writing <code class="code">val(:, 1:2)</code>.
</p>
<p>If <var class="var">idx</var> is an empty structure array with fields ‘<samp class="samp">type</samp>’ and
‘<samp class="samp">subs</samp>’, return <var class="var">val</var>.
</p>
<p>The keyword <code class="code">end</code> cannot be used within <code class="code">subsref</code> for indexing
assignments.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFsubsasgn">subsasgn</a>, <a class="ref" href="Manipulating-Structures.html#XREFsubstruct">substruct</a>.
</p></dd></dl>
<p>For example, this class uses the convention that indexing with <code class="code">"()"</code>
evaluates the polynomial and indexing with <code class="code">"{}"</code> returns the
<var class="var">n</var>-th coefficient (of the <var class="var">n</var>-th power). The code for the
<code class="code">subsref</code> method looks like
</p>
<div class="example">
<pre class="verbatim">function r = subsref (p, s)
if (isempty (s))
error ("@polynomial/subsref: missing index");
endif
switch (s(1).type)
case "()"
idx = s(1).subs;
if (numel (idx) != 1)
error ("@polynomial/subsref: need exactly one index");
endif
r = polyval (fliplr (p.poly), idx{1});
case "{}"
idx = s(1).subs;
if (numel (idx) != 1)
error ("@polynomial/subsref: need exactly one index");
endif
if (isnumeric (idx{1}))
r = p.poly(idx{1}+1);
else
r = p.poly(idx{1});
endif
case "."
fld = s.subs;
if (! strcmp (fld, "poly"))
error ('@polynomial/subsref: invalid property "%s"', fld);
endif
r = p.poly;
otherwise
error ("@polynomial/subsref: invalid subscript type");
endswitch
if (numel (s) > 1)
r = subsref (r, s(2:end));
endif
endfunction
</pre></div>
<p>The equivalent functionality for subscripted assignments uses the
<code class="code">subsasgn</code> method.
</p>
<a class="anchor" id="XREFsubsasgn"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-subsasgn"><span><code class="def-type"><var class="var">newval</var> =</code> <strong class="def-name">subsasgn</strong> <code class="def-code-arguments">(<var class="var">val</var>, <var class="var">idx</var>, <var class="var">rhs</var>)</code><a class="copiable-link" href="#index-subsasgn"> ¶</a></span></dt>
<dd><p>Perform the subscripted assignment operation according to the subscript
specified by <var class="var">idx</var>.
</p>
<p>The subscript <var class="var">idx</var> must be a structure array with fields ‘<samp class="samp">type</samp>’
and ‘<samp class="samp">subs</samp>’. Valid values for ‘<samp class="samp">type</samp>’ are <code class="code">"()"</code>,
<code class="code">"{}"</code>, and <code class="code">"."</code>. The ‘<samp class="samp">subs</samp>’ field may be either
<code class="code">":"</code> or a cell array of index values.
</p>
<p>The following example shows how to set the two first columns of a 3-by-3
matrix to zero.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">val = magic (3);
idx.type = "()";
idx.subs = {":", 1:2};
val = subsasgn (val, idx, 0)
⇒ [ 0 0 6
0 0 7
0 0 2 ]
</pre></div></div>
<p>Note that this is the same as writing <code class="code">val(:, 1:2) = 0</code>.
</p>
<p>If <var class="var">idx</var> is an empty structure array with fields ‘<samp class="samp">type</samp>’ and
‘<samp class="samp">subs</samp>’, return <var class="var">rhs</var>.
</p>
<p>The keyword <code class="code">end</code> cannot be used within <code class="code">subsasgn</code> for indexing
assignments.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFsubsref">subsref</a>, <a class="ref" href="Manipulating-Structures.html#XREFsubstruct">substruct</a>, <a class="ref" href="#XREFoptimize_005fsubsasgn_005fcalls">optimize_subsasgn_calls</a>.
</p></dd></dl>
<a class="anchor" id="XREFoptimize_005fsubsasgn_005fcalls"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-optimize_005fsubsasgn_005fcalls"><span><code class="def-type"><var class="var">val</var> =</code> <strong class="def-name">optimize_subsasgn_calls</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-optimize_005fsubsasgn_005fcalls"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-optimize_005fsubsasgn_005fcalls-1"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">optimize_subsasgn_calls</strong> <code class="def-code-arguments">(<var class="var">new_val</var>)</code><a class="copiable-link" href="#index-optimize_005fsubsasgn_005fcalls-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-optimize_005fsubsasgn_005fcalls-2"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">optimize_subsasgn_calls</strong> <code class="def-code-arguments">(<var class="var">new_val</var>, "local")</code><a class="copiable-link" href="#index-optimize_005fsubsasgn_005fcalls-2"> ¶</a></span></dt>
<dd><p>Query or set the internal flag for <code class="code">subsasgn</code> method call
optimizations.
</p>
<p>If true, Octave will attempt to eliminate the redundant copying when calling
the <code class="code">subsasgn</code> method of a user-defined class.
</p>
<p>When called from inside a function with the <code class="code">"local"</code> 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>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFsubsasgn">subsasgn</a>.
</p></dd></dl>
<p>Note that the <code class="code">subsref</code> and <code class="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 class="code">subsref</code> or <code class="code">subsasgn</code>.
</p>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-numArgumentsFromSubscript"><span><code class="def-type"><var class="var">n</var> =</code> <strong class="def-name">numArgumentsFromSubscript</strong> <code class="def-code-arguments">(<var class="var">obj</var>, <var class="var">idx</var>, <var class="var">unused</var>)</code><a class="copiable-link" href="#index-numArgumentsFromSubscript"> ¶</a></span></dt>
<dd><p>Override <var class="var">nargout</var> for overloaded <code class="code">subsref</code> method.
</p>
<p><var class="var">obj</var> is the object for which the overloaded <code class="code">subsref</code> method is
called.
</p>
<p><var class="var">idx</var> is a structure array with fields ‘<samp class="samp">type</samp>’ and ‘<samp class="samp">subs</samp>’.
See <a class="ref" href="#XREFsubsref">subsref</a> for a description of that structure.
</p>
<p>The third input argument <var class="var">unused</var> is currently unused. It is always the
empty matrix <code class="code">[]</code>.
</p>
<p>The function must return a scalar integer which will be passed as <var class="var">nargout</var>
to the overloaded <code class="code">subsref</code> method
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFsubsref">subsref</a>, <a class="ref" href="Manipulating-Structures.html#XREFsubstruct">substruct</a>.
</p></dd></dl>
<p>If you wish to use the <code class="code">end</code> keyword in subscripted expressions of an
object, then there must be an <code class="code">end</code> method defined. For example, the
<code class="code">end</code> method for the polynomial class might look like
</p>
<div class="example">
<div class="group"><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></div></div>
<p>which is a fairly generic <code class="code">end</code> method that has a behavior similar to the
<code class="code">end</code> keyword for Octave Array classes. An example using the polynomial
class is then
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">p = polynomial ([1,2,3,4]);
p{end-1}
⇒ 3
</pre></div></div>
<p>Objects can also be used themselves as the index in a subscripted expression
and this is controlled by the <code class="code">subsindex</code> function.
</p>
<a class="anchor" id="XREFsubsindex"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-subsindex"><span><code class="def-type"><var class="var">idx</var> =</code> <strong class="def-name">subsindex</strong> <code class="def-code-arguments">(<var class="var">obj</var>)</code><a class="copiable-link" href="#index-subsindex"> ¶</a></span></dt>
<dd><p>Convert an object to an index vector.
</p>
<p>When <var class="var">obj</var> is a class object defined with a class constructor, then
<code class="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 class="code">subsindex</code> must return a zero-based real integer vector of the class
<code class="code">"double"</code>. For example, if the class constructor were
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">function obj = myclass (a)
obj = class (struct ("a", a), "myclass");
endfunction
</pre></div></div>
<p>then the <code class="code">subsindex</code> function
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">function idx = subsindex (obj)
idx = double (obj.a) - 1.0;
endfunction
</pre></div></div>
<p>could be used as follows
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">a = myclass (1:4);
b = 1:10;
b(a)
⇒ 1 2 3 4
</pre></div></div>
<p><strong class="strong">See also:</strong> <a class="ref" href="Built_002din-Data-Types.html#XREFclass">class</a>, <a class="ref" href="#XREFsubsref">subsref</a>, <a class="ref" href="#XREFsubsasgn">subsasgn</a>.
</p></dd></dl>
<p>Finally, objects can be used like ranges by providing a <code class="code">colon</code> method.
</p>
<a class="anchor" id="XREFcolon"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-colon"><span><code class="def-type"><var class="var">r</var> =</code> <strong class="def-name">colon</strong> <code class="def-code-arguments">(<var class="var">base</var>, <var class="var">limit</var>)</code><a class="copiable-link" href="#index-colon"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-colon-1"><span><code class="def-type"><var class="var">r</var> =</code> <strong class="def-name">colon</strong> <code class="def-code-arguments">(<var class="var">base</var>, <var class="var">increment</var>, <var class="var">limit</var>)</code><a class="copiable-link" href="#index-colon-1"> ¶</a></span></dt>
<dd><p>Return the result of the colon expression corresponding to <var class="var">base</var>,
<var class="var">limit</var>, and optionally, <var class="var">increment</var>.
</p>
<p>This function is equivalent to the operator syntax
<code class="code"><var class="var">base</var> : <var class="var">limit</var></code><!-- /@w --> or
<code class="code"><var class="var">base</var> : <var class="var">increment</var> : <var class="var">limit</var></code><!-- /@w -->.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="Special-Utility-Matrices.html#XREFlinspace">linspace</a>.
</p></dd></dl>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Indexed-Assignment-Optimization.html">Indexed Assignment Optimization</a>, Up: <a href="Indexing-Objects.html">Indexing Objects</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
