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