Mercurial > jwe > octave
annotate doc/interpreter/stmt.txi @ 21122:dba88797f69f
doc: Periodic grammarcheck of documentation.
author | Rik <rik@octave.org> |
---|---|
date | Wed, 20 Jan 2016 21:14:47 -0800 |
parents | fdffc955b4ed |
children | dcf8922b724b |
rev | line source |
---|---|
19697
4197fc428c7d
maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents:
19597
diff
changeset
|
1 @c Copyright (C) 1996-2015 John W. Eaton |
7018 | 2 @c |
3 @c This file is part of Octave. | |
4 @c | |
5 @c Octave is free software; you can redistribute it and/or modify it | |
6 @c under the terms of the GNU General Public License as published by the | |
7 @c Free Software Foundation; either version 3 of the License, or (at | |
8 @c your option) any later version. | |
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18230
diff
changeset
|
9 @c |
7018 | 10 @c Octave is distributed in the hope that it will be useful, but WITHOUT |
11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
13 @c for more details. | |
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18230
diff
changeset
|
14 @c |
7018 | 15 @c You should have received a copy of the GNU General Public License |
16 @c along with Octave; see the file COPYING. If not, see | |
17 @c <http://www.gnu.org/licenses/>. | |
3294 | 18 |
4167 | 19 @node Statements |
3294 | 20 @chapter Statements |
21 @cindex statements | |
22 | |
23 Statements may be a simple constant expression or a complicated list of | |
24 nested loops and conditional statements. | |
25 | |
26 @dfn{Control statements} such as @code{if}, @code{while}, and so on | |
27 control the flow of execution in Octave programs. All the control | |
28 statements start with special keywords such as @code{if} and | |
29 @code{while}, to distinguish them from simple expressions. | |
30 Many control statements contain other statements; for example, the | |
31 @code{if} statement contains another statement which may or may not be | |
32 executed. | |
33 | |
34 @cindex @code{end} statement | |
35 Each control statement has a corresponding @dfn{end} statement that | |
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
7018
diff
changeset
|
36 marks the end of the control statement. For example, the |
3294 | 37 keyword @code{endif} marks the end of an @code{if} statement, and |
38 @code{endwhile} marks the end of a @code{while} statement. You can use | |
39 the keyword @code{end} anywhere a more specific end keyword is expected, | |
40 but using the more specific keywords is preferred because if you use | |
41 them, Octave is able to provide better diagnostics for mismatched or | |
42 missing end tokens. | |
43 | |
44 The list of statements contained between keywords like @code{if} or | |
45 @code{while} and the corresponding end statement is called the | |
46 @dfn{body} of a control statement. | |
47 | |
48 @menu | |
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
49 * The if Statement:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
50 * The switch Statement:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
51 * The while Statement:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
52 * The do-until Statement:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
53 * The for Statement:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
54 * The break Statement:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
55 * The continue Statement:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
56 * The unwind_protect Statement:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
57 * The try Statement:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
58 * Continuation Lines:: |
3294 | 59 @end menu |
60 | |
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
61 @node The if Statement |
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
62 @section The if Statement |
3294 | 63 @cindex @code{if} statement |
64 @cindex @code{else} statement | |
65 @cindex @code{elseif} statement | |
66 @cindex @code{endif} statement | |
67 | |
68 The @code{if} statement is Octave's decision-making statement. There | |
69 are three basic forms of an @code{if} statement. In its simplest form, | |
70 it looks like this: | |
71 | |
72 @example | |
73 @group | |
74 if (@var{condition}) | |
75 @var{then-body} | |
76 endif | |
77 @end group | |
78 @end example | |
79 | |
80 @noindent | |
81 @var{condition} is an expression that controls what the rest of the | |
82 statement will do. The @var{then-body} is executed only if | |
83 @var{condition} is true. | |
84 | |
85 The condition in an @code{if} statement is considered true if its value | |
18812
9ac2357f19bc
doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents:
18230
diff
changeset
|
86 is nonzero, and false if its value is zero. If the value of the |
3294 | 87 conditional expression in an @code{if} statement is a vector or a |
6637 | 88 matrix, it is considered true only if it is non-empty and @emph{all} |
20750
fdffc955b4ed
doc: Clarify how if statement determines true or false for a matrix input.
Rik <rik@octave.org>
parents:
20571
diff
changeset
|
89 of the elements are nonzero. The conceptually equivalent code when |
fdffc955b4ed
doc: Clarify how if statement determines true or false for a matrix input.
Rik <rik@octave.org>
parents:
20571
diff
changeset
|
90 @var{condition} is a matrix is shown below. |
3294 | 91 |
20750
fdffc955b4ed
doc: Clarify how if statement determines true or false for a matrix input.
Rik <rik@octave.org>
parents:
20571
diff
changeset
|
92 @example |
fdffc955b4ed
doc: Clarify how if statement determines true or false for a matrix input.
Rik <rik@octave.org>
parents:
20571
diff
changeset
|
93 if (@var{matrix}) @equiv{} if (all (@var{matrix}(:))) |
fdffc955b4ed
doc: Clarify how if statement determines true or false for a matrix input.
Rik <rik@octave.org>
parents:
20571
diff
changeset
|
94 @end example |
fdffc955b4ed
doc: Clarify how if statement determines true or false for a matrix input.
Rik <rik@octave.org>
parents:
20571
diff
changeset
|
95 |
fdffc955b4ed
doc: Clarify how if statement determines true or false for a matrix input.
Rik <rik@octave.org>
parents:
20571
diff
changeset
|
96 @noindent |
3294 | 97 The second form of an if statement looks like this: |
98 | |
99 @example | |
100 @group | |
101 if (@var{condition}) | |
102 @var{then-body} | |
103 else | |
104 @var{else-body} | |
105 endif | |
106 @end group | |
107 @end example | |
108 | |
109 @noindent | |
110 If @var{condition} is true, @var{then-body} is executed; otherwise, | |
111 @var{else-body} is executed. | |
112 | |
113 Here is an example: | |
114 | |
115 @example | |
116 @group | |
117 if (rem (x, 2) == 0) | |
118 printf ("x is even\n"); | |
119 else | |
120 printf ("x is odd\n"); | |
121 endif | |
122 @end group | |
123 @end example | |
124 | |
125 In this example, if the expression @code{rem (x, 2) == 0} is true (that | |
126 is, the value of @code{x} is divisible by 2), then the first | |
127 @code{printf} statement is evaluated, otherwise the second @code{printf} | |
128 statement is evaluated. | |
129 | |
130 The third and most general form of the @code{if} statement allows | |
131 multiple decisions to be combined in a single statement. It looks like | |
132 this: | |
133 | |
134 @example | |
135 @group | |
136 if (@var{condition}) | |
137 @var{then-body} | |
138 elseif (@var{condition}) | |
139 @var{elseif-body} | |
140 else | |
141 @var{else-body} | |
142 endif | |
143 @end group | |
144 @end example | |
145 | |
146 @noindent | |
147 Any number of @code{elseif} clauses may appear. Each condition is | |
148 tested in turn, and if one is found to be true, its corresponding | |
149 @var{body} is executed. If none of the conditions are true and the | |
150 @code{else} clause is present, its body is executed. Only one | |
151 @code{else} clause may appear, and it must be the last part of the | |
152 statement. | |
153 | |
154 In the following example, if the first condition is true (that is, the | |
155 value of @code{x} is divisible by 2), then the first @code{printf} | |
156 statement is executed. If it is false, then the second condition is | |
157 tested, and if it is true (that is, the value of @code{x} is divisible | |
158 by 3), then the second @code{printf} statement is executed. Otherwise, | |
159 the third @code{printf} statement is performed. | |
160 | |
161 @example | |
162 @group | |
163 if (rem (x, 2) == 0) | |
164 printf ("x is even\n"); | |
165 elseif (rem (x, 3) == 0) | |
166 printf ("x is odd and divisible by 3\n"); | |
167 else | |
168 printf ("x is odd\n"); | |
169 endif | |
170 @end group | |
171 @end example | |
172 | |
173 Note that the @code{elseif} keyword must not be spelled @code{else if}, | |
174 as is allowed in Fortran. If it is, the space between the @code{else} | |
175 and @code{if} will tell Octave to treat this as a new @code{if} | |
176 statement within another @code{if} statement's @code{else} clause. For | |
177 example, if you write | |
178 | |
179 @example | |
180 @group | |
181 if (@var{c1}) | |
182 @var{body-1} | |
183 else if (@var{c2}) | |
184 @var{body-2} | |
185 endif | |
186 @end group | |
187 @end example | |
188 | |
189 @noindent | |
190 Octave will expect additional input to complete the first @code{if} | |
191 statement. If you are using Octave interactively, it will continue to | |
192 prompt you for additional input. If Octave is reading this input from a | |
193 file, it may complain about missing or mismatched @code{end} statements, | |
194 or, if you have not used the more specific @code{end} statements | |
195 (@code{endif}, @code{endfor}, etc.), it may simply produce incorrect | |
196 results, without producing any warning messages. | |
197 | |
198 It is much easier to see the error if we rewrite the statements above | |
199 like this, | |
200 | |
201 @example | |
202 @group | |
203 if (@var{c1}) | |
204 @var{body-1} | |
205 else | |
206 if (@var{c2}) | |
207 @var{body-2} | |
208 endif | |
209 @end group | |
210 @end example | |
211 | |
212 @noindent | |
213 using the indentation to show how Octave groups the statements. | |
214 @xref{Functions and Scripts}. | |
215 | |
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
216 @node The switch Statement |
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
217 @section The switch Statement |
3294 | 218 @cindex @code{switch} statement |
219 @cindex @code{case} statement | |
220 @cindex @code{otherwise} statement | |
221 @cindex @code{endswitch} statement | |
222 | |
6530 | 223 It is very common to take different actions depending on the value of |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
224 one variable. This is possible using the @code{if} statement in the |
6530 | 225 following way |
226 | |
227 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
228 @group |
6530 | 229 if (X == 1) |
230 do_something (); | |
231 elseif (X == 2) | |
232 do_something_else (); | |
233 else | |
234 do_something_completely_different (); | |
235 endif | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
236 @end group |
6530 | 237 @end example |
238 | |
239 @noindent | |
240 This kind of code can however be very cumbersome to both write and | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
241 maintain. To overcome this problem Octave supports the @code{switch} |
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
242 statement. Using this statement, the above example becomes |
6530 | 243 |
244 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
245 @group |
6530 | 246 switch (X) |
247 case 1 | |
248 do_something (); | |
249 case 2 | |
250 do_something_else (); | |
251 otherwise | |
252 do_something_completely_different (); | |
253 endswitch | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
254 @end group |
6530 | 255 @end example |
256 | |
257 @noindent | |
258 This code makes the repetitive structure of the problem more explicit, | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
259 making the code easier to read, and hence maintain. Also, if the |
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
7018
diff
changeset
|
260 variable @code{X} should change its name, only one line would need |
6530 | 261 changing compared to one line per case when @code{if} statements are |
262 used. | |
3294 | 263 |
264 The general form of the @code{switch} statement is | |
265 | |
266 @example | |
267 @group | |
16934
48f5b993b819
doc: Use parentheses around if, switch conditions in documentation.
Rik <rik@octave.org>
parents:
16826
diff
changeset
|
268 switch (@var{expression}) |
3294 | 269 case @var{label} |
270 @var{command_list} | |
271 case @var{label} | |
272 @var{command_list} | |
273 @dots{} | |
274 | |
275 otherwise | |
276 @var{command_list} | |
277 endswitch | |
278 @end group | |
279 @end example | |
280 | |
6530 | 281 @noindent |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
282 where @var{label} can be any expression. However, duplicate |
6530 | 283 @var{label} values are not detected, and only the @var{command_list} |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
284 corresponding to the first match will be executed. For the |
6530 | 285 @code{switch} statement to be meaningful at least one |
286 @code{case @var{label} @var{command_list}} clause must be present, | |
287 while the @code{otherwise @var{command_list}} clause is optional. | |
3294 | 288 |
6637 | 289 If @var{label} is a cell array the corresponding @var{command_list} |
290 is executed if @emph{any} of the elements of the cell array match | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
291 @var{expression}. As an example, the following program will print |
6637 | 292 @samp{Variable is either 6 or 7}. |
293 | |
294 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
295 @group |
6637 | 296 A = 7; |
16934
48f5b993b819
doc: Use parentheses around if, switch conditions in documentation.
Rik <rik@octave.org>
parents:
16826
diff
changeset
|
297 switch (A) |
6637 | 298 case @{ 6, 7 @} |
299 printf ("variable is either 6 or 7\n"); | |
300 otherwise | |
301 printf ("variable is neither 6 nor 7\n"); | |
302 endswitch | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
303 @end group |
6637 | 304 @end example |
305 | |
3294 | 306 As with all other specific @code{end} keywords, @code{endswitch} may be |
307 replaced by @code{end}, but you can get better diagnostics if you use | |
308 the specific forms. | |
309 | |
6530 | 310 @c Strings can be matched |
311 | |
312 One advantage of using the @code{switch} statement compared to using | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
313 @code{if} statements is that the @var{label}s can be strings. If an |
6530 | 314 @code{if} statement is used it is @emph{not} possible to write |
315 | |
316 @example | |
317 if (X == "a string") # This is NOT valid | |
318 @end example | |
319 | |
320 @noindent | |
321 since a character-to-character comparison between @code{X} and the | |
322 string will be made instead of evaluating if the strings are equal. | |
323 This special-case is handled by the @code{switch} statement, and it | |
324 is possible to write programs that look like this | |
325 | |
326 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
327 @group |
6530 | 328 switch (X) |
329 case "a string" | |
330 do_something | |
331 @dots{} | |
332 endswitch | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
333 @end group |
6530 | 334 @end example |
335 | |
6535 | 336 @menu |
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
337 * Notes for the C Programmer:: |
6535 | 338 @end menu |
339 | |
11255
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
340 @node Notes for the C Programmer |
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
341 @subsection Notes for the C Programmer |
6530 | 342 |
6637 | 343 The @code{switch} statement is also available in the widely used C |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
344 programming language. There are, however, some differences |
6530 | 345 between the statement in Octave and C |
346 | |
347 @itemize @bullet | |
3294 | 348 @item |
349 Cases are exclusive, so they don't `fall through' as do the cases | |
6637 | 350 in the @code{switch} statement of the C language. |
3294 | 351 |
352 @item | |
353 The @var{command_list} elements are not optional. Making the list | |
354 optional would have meant requiring a separator between the label and | |
355 the command list. Otherwise, things like | |
356 | |
357 @example | |
358 @group | |
359 switch (foo) | |
360 case (1) -2 | |
361 @dots{} | |
362 @end group | |
363 @end example | |
364 | |
365 @noindent | |
366 would produce surprising results, as would | |
367 | |
368 @example | |
369 @group | |
370 switch (foo) | |
371 case (1) | |
372 case (2) | |
373 doit (); | |
374 @dots{} | |
375 @end group | |
376 @end example | |
377 | |
378 @noindent | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
379 particularly for C programmers. If @code{doit()} should be executed if |
6637 | 380 @var{foo} is either @code{1} or @code{2}, the above code should be |
381 written with a cell array like this | |
382 | |
383 @example | |
384 @group | |
385 switch (foo) | |
386 case @{ 1, 2 @} | |
387 doit (); | |
388 @dots{} | |
389 @end group | |
390 @end example | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
9209
diff
changeset
|
391 |
3294 | 392 @end itemize |
393 | |
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
394 @node The while Statement |
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
395 @section The while Statement |
3294 | 396 @cindex @code{while} statement |
397 @cindex @code{endwhile} statement | |
398 @cindex loop | |
399 @cindex body of a loop | |
400 | |
401 In programming, a @dfn{loop} means a part of a program that is (or at least can | |
402 be) executed two or more times in succession. | |
403 | |
404 The @code{while} statement is the simplest looping statement in Octave. | |
405 It repeatedly executes a statement as long as a condition is true. As | |
406 with the condition in an @code{if} statement, the condition in a | |
18812
9ac2357f19bc
doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents:
18230
diff
changeset
|
407 @code{while} statement is considered true if its value is nonzero, and |
3294 | 408 false if its value is zero. If the value of the conditional expression |
409 in a @code{while} statement is a vector or a matrix, it is considered | |
18812
9ac2357f19bc
doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents:
18230
diff
changeset
|
410 true only if it is non-empty and @emph{all} of the elements are nonzero. |
3294 | 411 |
412 Octave's @code{while} statement looks like this: | |
413 | |
414 @example | |
415 @group | |
416 while (@var{condition}) | |
417 @var{body} | |
418 endwhile | |
419 @end group | |
420 @end example | |
421 | |
422 @noindent | |
423 Here @var{body} is a statement or list of statements that we call the | |
424 @dfn{body} of the loop, and @var{condition} is an expression that | |
425 controls how long the loop keeps running. | |
426 | |
427 The first thing the @code{while} statement does is test @var{condition}. | |
428 If @var{condition} is true, it executes the statement @var{body}. After | |
429 @var{body} has been executed, @var{condition} is tested again, and if it | |
430 is still true, @var{body} is executed again. This process repeats until | |
431 @var{condition} is no longer true. If @var{condition} is initially | |
432 false, the body of the loop is never executed. | |
433 | |
434 This example creates a variable @code{fib} that contains the first ten | |
435 elements of the Fibonacci sequence. | |
436 | |
437 @example | |
438 @group | |
439 fib = ones (1, 10); | |
440 i = 3; | |
441 while (i <= 10) | |
442 fib (i) = fib (i-1) + fib (i-2); | |
443 i++; | |
444 endwhile | |
445 @end group | |
446 @end example | |
447 | |
448 @noindent | |
449 Here the body of the loop contains two statements. | |
450 | |
451 The loop works like this: first, the value of @code{i} is set to 3. | |
452 Then, the @code{while} tests whether @code{i} is less than or equal to | |
453 10. This is the case when @code{i} equals 3, so the value of the | |
454 @code{i}-th element of @code{fib} is set to the sum of the previous two | |
455 values in the sequence. Then the @code{i++} increments the value of | |
456 @code{i} and the loop repeats. The loop terminates when @code{i} | |
457 reaches 11. | |
458 | |
459 A newline is not required between the condition and the | |
460 body; but using one makes the program clearer unless the body is very | |
461 simple. | |
462 | |
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
463 @node The do-until Statement |
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
464 @section The do-until Statement |
3489 | 465 @cindex @code{do-until} statement |
466 | |
467 The @code{do-until} statement is similar to the @code{while} statement, | |
468 except that it repeatedly executes a statement until a condition becomes | |
469 true, and the test of the condition is at the end of the loop, so the | |
470 body of the loop is always executed at least once. As with the | |
471 condition in an @code{if} statement, the condition in a @code{do-until} | |
18812
9ac2357f19bc
doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents:
18230
diff
changeset
|
472 statement is considered true if its value is nonzero, and false if its |
3489 | 473 value is zero. If the value of the conditional expression in a |
19597
db92e7e28e1f
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
19596
diff
changeset
|
474 @code{do-until} statement is a vector or a matrix, it is considered |
18812
9ac2357f19bc
doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents:
18230
diff
changeset
|
475 true only if it is non-empty and @emph{all} of the elements are nonzero. |
3489 | 476 |
477 Octave's @code{do-until} statement looks like this: | |
478 | |
479 @example | |
480 @group | |
481 do | |
482 @var{body} | |
483 until (@var{condition}) | |
484 @end group | |
485 @end example | |
486 | |
487 @noindent | |
488 Here @var{body} is a statement or list of statements that we call the | |
489 @dfn{body} of the loop, and @var{condition} is an expression that | |
490 controls how long the loop keeps running. | |
491 | |
492 This example creates a variable @code{fib} that contains the first ten | |
493 elements of the Fibonacci sequence. | |
494 | |
495 @example | |
496 @group | |
497 fib = ones (1, 10); | |
498 i = 2; | |
499 do | |
500 i++; | |
501 fib (i) = fib (i-1) + fib (i-2); | |
502 until (i == 10) | |
503 @end group | |
504 @end example | |
505 | |
506 A newline is not required between the @code{do} keyword and the | |
507 body; but using one makes the program clearer unless the body is very | |
508 simple. | |
509 | |
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
510 @node The for Statement |
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
511 @section The for Statement |
3294 | 512 @cindex @code{for} statement |
513 @cindex @code{endfor} statement | |
514 | |
515 The @code{for} statement makes it more convenient to count iterations of a | |
516 loop. The general form of the @code{for} statement looks like this: | |
517 | |
518 @example | |
519 @group | |
520 for @var{var} = @var{expression} | |
521 @var{body} | |
522 endfor | |
523 @end group | |
524 @end example | |
525 | |
526 @noindent | |
527 where @var{body} stands for any statement or list of statements, | |
528 @var{expression} is any valid expression, and @var{var} may take several | |
529 forms. Usually it is a simple variable name or an indexed variable. If | |
530 the value of @var{expression} is a structure, @var{var} may also be a | |
6637 | 531 vector with two elements. @xref{Looping Over Structure Elements}, below. |
3294 | 532 |
533 The assignment expression in the @code{for} statement works a bit | |
534 differently than Octave's normal assignment statement. Instead of | |
535 assigning the complete result of the expression, it assigns each column | |
536 of the expression to @var{var} in turn. If @var{expression} is a range, | |
537 a row vector, or a scalar, the value of @var{var} will be a scalar each | |
538 time the loop body is executed. If @var{var} is a column vector or a | |
539 matrix, @var{var} will be a column vector each time the loop body is | |
540 executed. | |
541 | |
542 The following example shows another way to create a vector containing | |
543 the first ten elements of the Fibonacci sequence, this time using the | |
544 @code{for} statement: | |
545 | |
546 @example | |
547 @group | |
548 fib = ones (1, 10); | |
549 for i = 3:10 | |
20571
1b62fc4e1b2f
doc: Cuddle parentheses in example code of for loop.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
550 fib(i) = fib(i-1) + fib(i-2); |
3294 | 551 endfor |
552 @end group | |
553 @end example | |
554 | |
555 @noindent | |
556 This code works by first evaluating the expression @code{3:10}, to | |
557 produce a range of values from 3 to 10 inclusive. Then the variable | |
558 @code{i} is assigned the first element of the range and the body of the | |
559 loop is executed once. When the end of the loop body is reached, the | |
560 next value in the range is assigned to the variable @code{i}, and the | |
561 loop body is executed again. This process continues until there are no | |
562 more elements to assign. | |
563 | |
6587 | 564 Within Octave is it also possible to iterate over matrices or cell arrays |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
565 using the @code{for} statement. For example consider |
6587 | 566 |
567 @example | |
568 @group | |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
569 disp ("Loop over a matrix") |
6587 | 570 for i = [1,3;2,4] |
571 i | |
572 endfor | |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
573 disp ("Loop over a cell array") |
6587 | 574 for i = @{1,"two";"three",4@} |
575 i | |
576 endfor | |
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18230
diff
changeset
|
577 @end group |
6587 | 578 @end example |
579 | |
580 @noindent | |
581 In this case the variable @code{i} takes on the value of the columns of | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
582 the matrix or cell matrix. So the first loop iterates twice, producing |
7001 | 583 two column vectors @code{[1;2]}, followed by @code{[3;4]}, and likewise |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
584 for the loop over the cell array. This can be extended to loops over |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
9209
diff
changeset
|
585 multi-dimensional arrays. For example: |
6587 | 586 |
587 @example | |
588 @group | |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
589 a = [1,3;2,4]; c = cat (3, a, 2*a); |
6587 | 590 for i = c |
591 i | |
592 endfor | |
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18230
diff
changeset
|
593 @end group |
6587 | 594 @end example |
595 | |
596 @noindent | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
9209
diff
changeset
|
597 In the above case, the multi-dimensional matrix @var{c} is reshaped to a |
20750
fdffc955b4ed
doc: Clarify how if statement determines true or false for a matrix input.
Rik <rik@octave.org>
parents:
20571
diff
changeset
|
598 two-dimensional matrix as @code{reshape (c, rows (c), prod (size (c)(2:end)))} |
21122
dba88797f69f
doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents:
20750
diff
changeset
|
599 and then the same behavior as a loop over a two-dimensional matrix is produced. |
6587 | 600 |
3294 | 601 Although it is possible to rewrite all @code{for} loops as @code{while} |
602 loops, the Octave language has both statements because often a | |
603 @code{for} loop is both less work to type and more natural to think of. | |
604 Counting the number of iterations is very common in loops and it can be | |
605 easier to think of this counting as part of looping rather than as | |
606 something to do inside the loop. | |
607 | |
608 @menu | |
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
609 * Looping Over Structure Elements:: |
3294 | 610 @end menu |
611 | |
4167 | 612 @node Looping Over Structure Elements |
3294 | 613 @subsection Looping Over Structure Elements |
614 @cindex structure elements, looping over | |
615 @cindex looping over structure elements | |
616 | |
617 A special form of the @code{for} statement allows you to loop over all | |
618 the elements of a structure: | |
619 | |
620 @example | |
621 @group | |
622 for [ @var{val}, @var{key} ] = @var{expression} | |
623 @var{body} | |
624 endfor | |
625 @end group | |
626 @end example | |
627 | |
628 @noindent | |
629 In this form of the @code{for} statement, the value of @var{expression} | |
630 must be a structure. If it is, @var{key} and @var{val} are set to the | |
631 name of the element and the corresponding value in turn, until there are | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
9209
diff
changeset
|
632 no more elements. For example: |
3294 | 633 |
634 @example | |
635 @group | |
636 x.a = 1 | |
637 x.b = [1, 2; 3, 4] | |
638 x.c = "string" | |
639 for [val, key] = x | |
640 key | |
641 val | |
642 endfor | |
643 | |
644 @print{} key = a | |
645 @print{} val = 1 | |
646 @print{} key = b | |
647 @print{} val = | |
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18230
diff
changeset
|
648 @print{} |
3294 | 649 @print{} 1 2 |
650 @print{} 3 4 | |
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18230
diff
changeset
|
651 @print{} |
3294 | 652 @print{} key = c |
653 @print{} val = string | |
654 @end group | |
655 @end example | |
656 | |
657 The elements are not accessed in any particular order. If you need to | |
658 cycle through the list in a particular way, you will have to use the | |
6637 | 659 function @code{fieldnames} and sort the list yourself. |
3294 | 660 |
661 The @var{key} variable may also be omitted. If it is, the brackets are | |
662 also optional. This is useful for cycling through the values of all the | |
663 structure elements when the names of the elements do not need to be | |
664 known. | |
665 | |
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
666 @node The break Statement |
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
667 @section The break Statement |
3294 | 668 @cindex @code{break} statement |
669 | |
15898
a7d89366d7ed
Document that break and continue statements work for do-until loops.
Rik <rik@octave.org>
parents:
15685
diff
changeset
|
670 The @code{break} statement jumps out of the innermost @code{while}, |
a7d89366d7ed
Document that break and continue statements work for do-until loops.
Rik <rik@octave.org>
parents:
15685
diff
changeset
|
671 @code{do-until}, or @code{for} loop that encloses it. The @code{break} |
a7d89366d7ed
Document that break and continue statements work for do-until loops.
Rik <rik@octave.org>
parents:
15685
diff
changeset
|
672 statement may only be used within the body of a loop. The following |
a7d89366d7ed
Document that break and continue statements work for do-until loops.
Rik <rik@octave.org>
parents:
15685
diff
changeset
|
673 example finds the smallest divisor of a given integer, and also |
a7d89366d7ed
Document that break and continue statements work for do-until loops.
Rik <rik@octave.org>
parents:
15685
diff
changeset
|
674 identifies prime numbers: |
3294 | 675 |
676 @example | |
677 @group | |
678 num = 103; | |
679 div = 2; | |
680 while (div*div <= num) | |
681 if (rem (num, div) == 0) | |
682 break; | |
683 endif | |
684 div++; | |
685 endwhile | |
686 if (rem (num, div) == 0) | |
687 printf ("Smallest divisor of %d is %d\n", num, div) | |
688 else | |
689 printf ("%d is prime\n", num); | |
690 endif | |
691 @end group | |
692 @end example | |
693 | |
694 When the remainder is zero in the first @code{while} statement, Octave | |
695 immediately @dfn{breaks out} of the loop. This means that Octave | |
696 proceeds immediately to the statement following the loop and continues | |
697 processing. (This is very different from the @code{exit} statement | |
698 which stops the entire Octave program.) | |
699 | |
700 Here is another program equivalent to the previous one. It illustrates | |
701 how the @var{condition} of a @code{while} statement could just as well | |
702 be replaced with a @code{break} inside an @code{if}: | |
703 | |
704 @example | |
705 @group | |
706 num = 103; | |
707 div = 2; | |
708 while (1) | |
709 if (rem (num, div) == 0) | |
710 printf ("Smallest divisor of %d is %d\n", num, div); | |
711 break; | |
712 endif | |
713 div++; | |
714 if (div*div > num) | |
715 printf ("%d is prime\n", num); | |
716 break; | |
717 endif | |
718 endwhile | |
719 @end group | |
720 @end example | |
721 | |
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
722 @node The continue Statement |
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
723 @section The continue Statement |
3294 | 724 @cindex @code{continue} statement |
725 | |
726 The @code{continue} statement, like @code{break}, is used only inside | |
15898
a7d89366d7ed
Document that break and continue statements work for do-until loops.
Rik <rik@octave.org>
parents:
15685
diff
changeset
|
727 @code{while}, @code{do-until}, or @code{for} loops. It skips over the |
a7d89366d7ed
Document that break and continue statements work for do-until loops.
Rik <rik@octave.org>
parents:
15685
diff
changeset
|
728 rest of the loop body, causing the next cycle around the loop to begin |
a7d89366d7ed
Document that break and continue statements work for do-until loops.
Rik <rik@octave.org>
parents:
15685
diff
changeset
|
729 immediately. Contrast this with @code{break}, which jumps out of the |
a7d89366d7ed
Document that break and continue statements work for do-until loops.
Rik <rik@octave.org>
parents:
15685
diff
changeset
|
730 loop altogether. |
3294 | 731 Here is an example: |
732 | |
733 @example | |
734 @group | |
735 # print elements of a vector of random | |
736 # integers that are even. | |
737 | |
738 # first, create a row vector of 10 random | |
739 # integers with values between 0 and 100: | |
740 | |
741 vec = round (rand (1, 10) * 100); | |
742 | |
743 # print what we're interested in: | |
744 | |
745 for x = vec | |
746 if (rem (x, 2) != 0) | |
747 continue; | |
748 endif | |
749 printf ("%d\n", x); | |
750 endfor | |
751 @end group | |
752 @end example | |
753 | |
754 If one of the elements of @var{vec} is an odd number, this example skips | |
755 the print statement for that element, and continues back to the first | |
756 statement in the loop. | |
757 | |
758 This is not a practical example of the @code{continue} statement, but it | |
759 should give you a clear understanding of how it works. Normally, one | |
760 would probably write the loop like this: | |
761 | |
762 @example | |
763 @group | |
764 for x = vec | |
765 if (rem (x, 2) == 0) | |
766 printf ("%d\n", x); | |
767 endif | |
768 endfor | |
769 @end group | |
770 @end example | |
771 | |
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
772 @node The unwind_protect Statement |
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
773 @section The unwind_protect Statement |
3294 | 774 @cindex @code{unwind_protect} statement |
775 @cindex @code{unwind_protect_cleanup} | |
776 @cindex @code{end_unwind_protect} | |
777 | |
16826
a4969508008e
doc: Periodic spellcheck of the documentation.
Rik <rik@octave.org>
parents:
15898
diff
changeset
|
778 Octave supports a limited form of exception handling modeled after the |
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18230
diff
changeset
|
779 unwind-protect form of Lisp. |
3294 | 780 |
781 The general form of an @code{unwind_protect} block looks like this: | |
782 | |
783 @example | |
784 @group | |
785 unwind_protect | |
786 @var{body} | |
787 unwind_protect_cleanup | |
788 @var{cleanup} | |
789 end_unwind_protect | |
790 @end group | |
791 @end example | |
792 | |
793 @noindent | |
6637 | 794 where @var{body} and @var{cleanup} are both optional and may contain any |
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18230
diff
changeset
|
795 Octave expressions or commands. The statements in @var{cleanup} are |
3294 | 796 guaranteed to be executed regardless of how control exits @var{body}. |
797 | |
798 This is useful to protect temporary changes to global variables from | |
799 possible errors. For example, the following code will always restore | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
800 the original value of the global variable @code{frobnosticate} |
8542
ef2dfe33e5b5
stmt.txi: unwind_protect doc fix
John W. Eaton <jwe@octave.org>
parents:
8347
diff
changeset
|
801 even if an error occurs in the first part of the @code{unwind_protect} |
ef2dfe33e5b5
stmt.txi: unwind_protect doc fix
John W. Eaton <jwe@octave.org>
parents:
8347
diff
changeset
|
802 block. |
3294 | 803 |
804 @example | |
805 @group | |
6501 | 806 save_frobnosticate = frobnosticate; |
3294 | 807 unwind_protect |
6501 | 808 frobnosticate = true; |
809 @dots{} | |
3294 | 810 unwind_protect_cleanup |
6501 | 811 frobnosticate = save_frobnosticate; |
3294 | 812 end_unwind_protect |
813 @end group | |
814 @end example | |
815 | |
6637 | 816 @noindent |
6501 | 817 Without @code{unwind_protect}, the value of @var{frobnosticate} |
8542
ef2dfe33e5b5
stmt.txi: unwind_protect doc fix
John W. Eaton <jwe@octave.org>
parents:
8347
diff
changeset
|
818 would not be restored if an error occurs while evaluating the first part |
ef2dfe33e5b5
stmt.txi: unwind_protect doc fix
John W. Eaton <jwe@octave.org>
parents:
8347
diff
changeset
|
819 of the @code{unwind_protect} block because evaluation would stop at the |
ef2dfe33e5b5
stmt.txi: unwind_protect doc fix
John W. Eaton <jwe@octave.org>
parents:
8347
diff
changeset
|
820 point of the error and the statement to restore the value would not be |
ef2dfe33e5b5
stmt.txi: unwind_protect doc fix
John W. Eaton <jwe@octave.org>
parents:
8347
diff
changeset
|
821 executed. |
3294 | 822 |
18221
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
823 In addition to unwind_protect, Octave supports another form of |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
824 exception handling, the @code{try} block. |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
825 |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
826 |
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
827 @node The try Statement |
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
828 @section The try Statement |
3294 | 829 @cindex @code{try} statement |
830 @cindex @code{catch} | |
831 @cindex @code{end_try_catch} | |
832 | |
18221
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
833 The original form of a @code{try} block looks like this: |
3294 | 834 |
835 @example | |
836 @group | |
837 try | |
838 @var{body} | |
839 catch | |
840 @var{cleanup} | |
841 end_try_catch | |
842 @end group | |
843 @end example | |
844 | |
6637 | 845 @noindent |
846 where @var{body} and @var{cleanup} are both optional and may contain any | |
3294 | 847 Octave expressions or commands. The statements in @var{cleanup} are |
848 only executed if an error occurs in @var{body}. | |
849 | |
18221
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
850 No warnings or error messages are printed while @var{body} is executing. |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
851 If an error does occur during the execution of @var{body}, @var{cleanup} |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
852 can use the functions @code{lasterr} or @code{lasterror} to access the |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
853 text of the message that would have been printed, as well as its |
18230
faf32a725693
* stmt.txi: Fix missing comma after @xref.
John W. Eaton <jwe@octave.org>
parents:
18221
diff
changeset
|
854 identifier. The alternative form, |
18221
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
855 |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
856 @example |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
857 @group |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
858 try |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
859 @var{body} |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
860 catch @var{err} |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
861 @var{cleanup} |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
862 end_try_catch |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
863 @end group |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
864 @end example |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
865 |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
866 @noindent |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
867 will automatically store the output of @code{lasterror} in the structure |
18230
faf32a725693
* stmt.txi: Fix missing comma after @xref.
John W. Eaton <jwe@octave.org>
parents:
18221
diff
changeset
|
868 @var{err}. @xref{Errors and Warnings}, for more information about the |
18221
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
869 @code{lasterr} and @code{lasterror} functions. |
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
870 |
3294 | 871 |
17418
0bcbbd82c9b5
doc: Fix indexing of continuation lines
Stefan Mahr <dac922@gmx.de>
parents:
17259
diff
changeset
|
872 @node Continuation Lines |
0bcbbd82c9b5
doc: Fix indexing of continuation lines
Stefan Mahr <dac922@gmx.de>
parents:
17259
diff
changeset
|
873 @section Continuation Lines |
3294 | 874 @cindex continuation lines |
875 @cindex @code{...} continuation marker | |
876 @cindex @code{\} continuation marker | |
877 | |
878 In the Octave language, most statements end with a newline character and | |
879 you must tell Octave to ignore the newline character in order to | |
880 continue a statement from one line to the next. Lines that end with the | |
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
881 characters @code{...} are joined with the following line before they are |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
882 divided into tokens by Octave's parser. For example, the lines |
3294 | 883 |
884 @example | |
885 @group | |
886 x = long_variable_name ... | |
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
887 + longer_variable_name ... |
3294 | 888 - 42 |
889 @end group | |
890 @end example | |
891 | |
892 @noindent | |
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
893 form a single statement. |
3294 | 894 |
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
895 Any text between the continuation marker and the newline character is |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
896 ignored. For example, the statement |
3294 | 897 |
898 @example | |
899 @group | |
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
900 x = long_variable_name ... # comment one |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
901 + longer_variable_name ...comment two |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
902 - 42 # last comment |
3294 | 903 @end group |
904 @end example | |
905 | |
906 @noindent | |
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
907 is equivalent to the one shown above. |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
908 |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
909 Inside double-quoted string constants, the character @code{\} has to be |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
910 used as continuation marker. The @code{\} must appear at the end of the |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
911 line just before the newline character: |
3294 | 912 |
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
913 @example |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
914 @group |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
915 s = "This text starts in the first line \ |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
916 and is continued in the second line." |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
917 @end group |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
918 @end example |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
919 |
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
920 @noindent |
3294 | 921 Input that occurs inside parentheses can be continued to the next line |
922 without having to use a continuation marker. For example, it is | |
923 possible to write statements like | |
924 | |
925 @example | |
926 @group | |
927 if (fine_dining_destination == on_a_boat | |
928 || fine_dining_destination == on_a_train) | |
4541 | 929 seuss (i, will, not, eat, them, sam, i, am, i, |
3294 | 930 will, not, eat, green, eggs, and, ham); |
931 endif | |
932 @end group | |
933 @end example | |
934 | |
935 @noindent | |
936 without having to add to the clutter with continuation markers. |