Mercurial > octave-nkf
annotate doc/interpreter/stmt.txi @ 20606:1b62fc4e1b2f stable
doc: Cuddle parentheses in example code of for loop.
* stmt.txi: Cuddle parentheses in example code of for loop.
| author | Rik <rik@octave.org> |
|---|---|
| date | Wed, 07 Oct 2015 14:41:39 -0700 |
| parents | 4197fc428c7d |
| children |
| rev | line source |
|---|---|
|
19731
4197fc428c7d
maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents:
19631
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. | |
|
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18229
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. | |
|
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18229
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 | |
|
18851
9ac2357f19bc
doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents:
18229
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} |
|
18851
9ac2357f19bc
doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents:
18229
diff
changeset
|
89 of the elements are nonzero. |
| 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 | |
|
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
210 @node The switch Statement |
|
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
211 @section The switch Statement |
| 3294 | 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 | |
|
16934
48f5b993b819
doc: Use parentheses around if, switch conditions in documentation.
Rik <rik@octave.org>
parents:
16826
diff
changeset
|
262 switch (@var{expression}) |
| 3294 | 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; |
|
16934
48f5b993b819
doc: Use parentheses around if, switch conditions in documentation.
Rik <rik@octave.org>
parents:
16826
diff
changeset
|
291 switch (A) |
| 6637 | 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 |
|
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
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 | |
|
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
388 @node The while Statement |
|
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
389 @section The while Statement |
| 3294 | 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 | |
|
18851
9ac2357f19bc
doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents:
18229
diff
changeset
|
401 @code{while} statement is considered true if its value is nonzero, and |
| 3294 | 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 | |
|
18851
9ac2357f19bc
doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents:
18229
diff
changeset
|
404 true only if it is non-empty and @emph{all} of the elements are nonzero. |
| 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 | |
|
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
457 @node The do-until Statement |
|
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
458 @section The do-until Statement |
| 3489 | 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} | |
|
18851
9ac2357f19bc
doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents:
18229
diff
changeset
|
466 statement is considered true if its value is nonzero, and false if its |
| 3489 | 467 value is zero. If the value of the conditional expression in a |
|
19631
db92e7e28e1f
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
19630
diff
changeset
|
468 @code{do-until} statement is a vector or a matrix, it is considered |
|
18851
9ac2357f19bc
doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents:
18229
diff
changeset
|
469 true only if it is non-empty and @emph{all} of the elements are nonzero. |
| 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 | |
|
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
504 @node The for Statement |
|
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
505 @section The for Statement |
| 3294 | 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 | |
|
20606
1b62fc4e1b2f
doc: Cuddle parentheses in example code of for loop.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
544 fib(i) = fib(i-1) + fib(i-2); |
| 3294 | 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 | |
|
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18229
diff
changeset
|
571 @end group |
| 6587 | 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 | |
|
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18229
diff
changeset
|
587 @end group |
| 6587 | 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 | |
|
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
16934
diff
changeset
|
604 * Looping Over Structure Elements:: |
| 3294 | 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 = | |
|
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18229
diff
changeset
|
643 @print{} |
| 3294 | 644 @print{} 1 2 |
| 645 @print{} 3 4 | |
|
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18229
diff
changeset
|
646 @print{} |
| 3294 | 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 | |
|
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
661 @node The break Statement |
|
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
662 @section The break Statement |
| 3294 | 663 @cindex @code{break} statement |
| 664 | |
|
15898
a7d89366d7ed
Document that break and continue statements work for do-until loops.
Rik <rik@octave.org>
parents:
15685
diff
changeset
|
665 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
|
666 @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
|
667 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
|
668 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
|
669 identifies prime numbers: |
| 3294 | 670 |
| 671 @example | |
| 672 @group | |
| 673 num = 103; | |
| 674 div = 2; | |
| 675 while (div*div <= num) | |
| 676 if (rem (num, div) == 0) | |
| 677 break; | |
| 678 endif | |
| 679 div++; | |
| 680 endwhile | |
| 681 if (rem (num, div) == 0) | |
| 682 printf ("Smallest divisor of %d is %d\n", num, div) | |
| 683 else | |
| 684 printf ("%d is prime\n", num); | |
| 685 endif | |
| 686 @end group | |
| 687 @end example | |
| 688 | |
| 689 When the remainder is zero in the first @code{while} statement, Octave | |
| 690 immediately @dfn{breaks out} of the loop. This means that Octave | |
| 691 proceeds immediately to the statement following the loop and continues | |
| 692 processing. (This is very different from the @code{exit} statement | |
| 693 which stops the entire Octave program.) | |
| 694 | |
| 695 Here is another program equivalent to the previous one. It illustrates | |
| 696 how the @var{condition} of a @code{while} statement could just as well | |
| 697 be replaced with a @code{break} inside an @code{if}: | |
| 698 | |
| 699 @example | |
| 700 @group | |
| 701 num = 103; | |
| 702 div = 2; | |
| 703 while (1) | |
| 704 if (rem (num, div) == 0) | |
| 705 printf ("Smallest divisor of %d is %d\n", num, div); | |
| 706 break; | |
| 707 endif | |
| 708 div++; | |
| 709 if (div*div > num) | |
| 710 printf ("%d is prime\n", num); | |
| 711 break; | |
| 712 endif | |
| 713 endwhile | |
| 714 @end group | |
| 715 @end example | |
| 716 | |
|
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
717 @node The continue Statement |
|
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
718 @section The continue Statement |
| 3294 | 719 @cindex @code{continue} statement |
| 720 | |
| 721 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
|
722 @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
|
723 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
|
724 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
|
725 loop altogether. |
| 3294 | 726 Here is an example: |
| 727 | |
| 728 @example | |
| 729 @group | |
| 730 # print elements of a vector of random | |
| 731 # integers that are even. | |
| 732 | |
| 733 # first, create a row vector of 10 random | |
| 734 # integers with values between 0 and 100: | |
| 735 | |
| 736 vec = round (rand (1, 10) * 100); | |
| 737 | |
| 738 # print what we're interested in: | |
| 739 | |
| 740 for x = vec | |
| 741 if (rem (x, 2) != 0) | |
| 742 continue; | |
| 743 endif | |
| 744 printf ("%d\n", x); | |
| 745 endfor | |
| 746 @end group | |
| 747 @end example | |
| 748 | |
| 749 If one of the elements of @var{vec} is an odd number, this example skips | |
| 750 the print statement for that element, and continues back to the first | |
| 751 statement in the loop. | |
| 752 | |
| 753 This is not a practical example of the @code{continue} statement, but it | |
| 754 should give you a clear understanding of how it works. Normally, one | |
| 755 would probably write the loop like this: | |
| 756 | |
| 757 @example | |
| 758 @group | |
| 759 for x = vec | |
| 760 if (rem (x, 2) == 0) | |
| 761 printf ("%d\n", x); | |
| 762 endif | |
| 763 endfor | |
| 764 @end group | |
| 765 @end example | |
| 766 | |
|
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
767 @node The unwind_protect Statement |
|
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
768 @section The unwind_protect Statement |
| 3294 | 769 @cindex @code{unwind_protect} statement |
| 770 @cindex @code{unwind_protect_cleanup} | |
| 771 @cindex @code{end_unwind_protect} | |
| 772 | |
|
16826
a4969508008e
doc: Periodic spellcheck of the documentation.
Rik <rik@octave.org>
parents:
15898
diff
changeset
|
773 Octave supports a limited form of exception handling modeled after the |
|
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18229
diff
changeset
|
774 unwind-protect form of Lisp. |
| 3294 | 775 |
| 776 The general form of an @code{unwind_protect} block looks like this: | |
| 777 | |
| 778 @example | |
| 779 @group | |
| 780 unwind_protect | |
| 781 @var{body} | |
| 782 unwind_protect_cleanup | |
| 783 @var{cleanup} | |
| 784 end_unwind_protect | |
| 785 @end group | |
| 786 @end example | |
| 787 | |
| 788 @noindent | |
| 6637 | 789 where @var{body} and @var{cleanup} are both optional and may contain any |
|
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18229
diff
changeset
|
790 Octave expressions or commands. The statements in @var{cleanup} are |
| 3294 | 791 guaranteed to be executed regardless of how control exits @var{body}. |
| 792 | |
| 793 This is useful to protect temporary changes to global variables from | |
| 794 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
|
795 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
|
796 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
|
797 block. |
| 3294 | 798 |
| 799 @example | |
| 800 @group | |
| 6501 | 801 save_frobnosticate = frobnosticate; |
| 3294 | 802 unwind_protect |
| 6501 | 803 frobnosticate = true; |
| 804 @dots{} | |
| 3294 | 805 unwind_protect_cleanup |
| 6501 | 806 frobnosticate = save_frobnosticate; |
| 3294 | 807 end_unwind_protect |
| 808 @end group | |
| 809 @end example | |
| 810 | |
| 6637 | 811 @noindent |
| 6501 | 812 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
|
813 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
|
814 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
|
815 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
|
816 executed. |
| 3294 | 817 |
|
18220
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
818 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
|
819 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
|
820 |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
821 |
|
15684
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
822 @node The try Statement |
|
ddc651eecf7a
Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
823 @section The try Statement |
| 3294 | 824 @cindex @code{try} statement |
| 825 @cindex @code{catch} | |
| 826 @cindex @code{end_try_catch} | |
| 827 | |
|
18220
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
828 The original form of a @code{try} block looks like this: |
| 3294 | 829 |
| 830 @example | |
| 831 @group | |
| 832 try | |
| 833 @var{body} | |
| 834 catch | |
| 835 @var{cleanup} | |
| 836 end_try_catch | |
| 837 @end group | |
| 838 @end example | |
| 839 | |
| 6637 | 840 @noindent |
| 841 where @var{body} and @var{cleanup} are both optional and may contain any | |
| 3294 | 842 Octave expressions or commands. The statements in @var{cleanup} are |
| 843 only executed if an error occurs in @var{body}. | |
| 844 | |
|
18220
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
845 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
|
846 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
|
847 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
|
848 text of the message that would have been printed, as well as its |
|
18229
faf32a725693
* stmt.txi: Fix missing comma after @xref.
John W. Eaton <jwe@octave.org>
parents:
18220
diff
changeset
|
849 identifier. The alternative form, |
|
18220
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
850 |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
851 @example |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
852 @group |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
853 try |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
854 @var{body} |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
855 catch @var{err} |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
856 @var{cleanup} |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
857 end_try_catch |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
858 @end group |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
859 @end example |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
860 |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
861 @noindent |
|
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
862 will automatically store the output of @code{lasterror} in the structure |
|
18229
faf32a725693
* stmt.txi: Fix missing comma after @xref.
John W. Eaton <jwe@octave.org>
parents:
18220
diff
changeset
|
863 @var{err}. @xref{Errors and Warnings}, for more information about the |
|
18220
6fd22474783e
doc: Update manual for "catch err" syntax (bug #33217)
Felipe G. Nievinski <fgnievinski@gmail.com>
parents:
17744
diff
changeset
|
864 @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
|
865 |
| 3294 | 866 |
|
17418
0bcbbd82c9b5
doc: Fix indexing of continuation lines
Stefan Mahr <dac922@gmx.de>
parents:
17259
diff
changeset
|
867 @node Continuation Lines |
|
0bcbbd82c9b5
doc: Fix indexing of continuation lines
Stefan Mahr <dac922@gmx.de>
parents:
17259
diff
changeset
|
868 @section Continuation Lines |
| 3294 | 869 @cindex continuation lines |
| 870 @cindex @code{...} continuation marker | |
| 871 @cindex @code{\} continuation marker | |
| 872 | |
| 873 In the Octave language, most statements end with a newline character and | |
| 874 you must tell Octave to ignore the newline character in order to | |
| 875 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
|
876 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
|
877 divided into tokens by Octave's parser. For example, the lines |
| 3294 | 878 |
| 879 @example | |
| 880 @group | |
| 881 x = long_variable_name ... | |
|
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
882 + longer_variable_name ... |
| 3294 | 883 - 42 |
| 884 @end group | |
| 885 @end example | |
| 886 | |
| 887 @noindent | |
|
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
888 form a single statement. |
| 3294 | 889 |
|
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
890 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
|
891 ignored. For example, the statement |
| 3294 | 892 |
| 893 @example | |
| 894 @group | |
|
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
895 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
|
896 + longer_variable_name ...comment two |
|
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
897 - 42 # last comment |
| 3294 | 898 @end group |
| 899 @end example | |
| 900 | |
| 901 @noindent | |
|
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
902 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
|
903 |
|
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
904 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
|
905 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
|
906 line just before the newline character: |
| 3294 | 907 |
|
17259
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
908 @example |
|
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
909 @group |
|
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
910 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
|
911 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
|
912 @end group |
|
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
913 @end example |
|
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
914 |
|
a654c1eccd29
doc: Modify chapter 'continuation lines' to fit actual behaviour
Stefan Mahr <dac922@gmx.de>
parents:
17152
diff
changeset
|
915 @noindent |
| 3294 | 916 Input that occurs inside parentheses can be continued to the next line |
| 917 without having to use a continuation marker. For example, it is | |
| 918 possible to write statements like | |
| 919 | |
| 920 @example | |
| 921 @group | |
| 922 if (fine_dining_destination == on_a_boat | |
| 923 || fine_dining_destination == on_a_train) | |
| 4541 | 924 seuss (i, will, not, eat, them, sam, i, am, i, |
| 3294 | 925 will, not, eat, green, eggs, and, ham); |
| 926 endif | |
| 927 @end group | |
| 928 @end example | |
| 929 | |
| 930 @noindent | |
| 931 without having to add to the clutter with continuation markers. |