Mercurial > hg > octave-nkf
annotate doc/interpreter/func.txi @ 12163:55ebf5df9ea6
Use Automake and GNU Make variables for increased portability in DLD-FUNCTIONS/*.oct creation
| author | Rik <octave@nomad.inbox5.com> |
|---|---|
| date | Tue, 25 Jan 2011 21:38:05 -0800 |
| parents | 6f8ffe2c6f76 |
| children | 732a568bf694 |
| rev | line source |
|---|---|
| 11523 | 1 @c Copyright (C) 1996-2011 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 Functions and Scripts |
|
9032
349616d9c38e
Cleanup top-level documentation menu in octave.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
20 @chapter Functions and Scripts |
| 3294 | 21 @cindex defining functions |
| 22 @cindex user-defined functions | |
| 23 @cindex functions, user-defined | |
| 24 @cindex script files | |
| 25 | |
| 26 Complicated Octave programs can often be simplified by defining | |
| 27 functions. Functions can be defined directly on the command line during | |
| 28 interactive Octave sessions, or in external files, and can be called just | |
| 29 like built-in functions. | |
| 30 | |
| 31 @menu | |
| 32 * Defining Functions:: | |
| 33 * Multiple Return Values:: | |
| 34 * Variable-length Argument Lists:: | |
|
10209
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
35 * Ignoring Arguments:: |
| 3294 | 36 * Variable-length Return Lists:: |
|
11255
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
37 * Returning from a Function:: |
| 6510 | 38 * Default Arguments:: |
| 3294 | 39 * Function Files:: |
| 40 * Script Files:: | |
| 6638 | 41 * Function Handles Inline Functions and Anonymous Functions:: |
| 6549 | 42 * Commands:: |
| 3294 | 43 * Organization of Functions:: |
| 44 @end menu | |
| 45 | |
| 4167 | 46 @node Defining Functions |
| 3294 | 47 @section Defining Functions |
| 48 @cindex @code{function} statement | |
| 49 @cindex @code{endfunction} statement | |
| 50 | |
| 51 In its simplest form, the definition of a function named @var{name} | |
| 52 looks like this: | |
| 53 | |
| 54 @example | |
| 55 @group | |
| 56 function @var{name} | |
| 57 @var{body} | |
| 58 endfunction | |
| 59 @end group | |
| 60 @end example | |
| 61 | |
| 62 @noindent | |
| 63 A valid function name is like a valid variable name: a sequence of | |
| 64 letters, digits and underscores, not starting with a digit. Functions | |
| 65 share the same pool of names as variables. | |
| 66 | |
| 67 The function @var{body} consists of Octave statements. It is the | |
| 68 most important part of the definition, because it says what the function | |
| 69 should actually @emph{do}. | |
| 70 | |
| 71 For example, here is a function that, when executed, will ring the bell | |
| 72 on your terminal (assuming that it is possible to do so): | |
| 73 | |
| 74 @example | |
| 75 @group | |
| 76 function wakeup | |
| 77 printf ("\a"); | |
| 78 endfunction | |
| 79 @end group | |
| 80 @end example | |
| 81 | |
| 82 The @code{printf} statement (@pxref{Input and Output}) simply tells | |
| 83 Octave to print the string @code{"\a"}. The special character @samp{\a} | |
| 84 stands for the alert character (ASCII 7). @xref{Strings}. | |
| 85 | |
| 86 Once this function is defined, you can ask Octave to evaluate it by | |
| 87 typing the name of the function. | |
| 88 | |
| 89 Normally, you will want to pass some information to the functions you | |
| 90 define. The syntax for passing parameters to a function in Octave is | |
| 91 | |
| 92 @example | |
| 93 @group | |
| 94 function @var{name} (@var{arg-list}) | |
| 95 @var{body} | |
| 96 endfunction | |
| 97 @end group | |
| 98 @end example | |
| 99 | |
| 100 @noindent | |
| 101 where @var{arg-list} is a comma-separated list of the function's | |
| 102 arguments. When the function is called, the argument names are used to | |
| 103 hold the argument values given in the call. The list of arguments may | |
| 104 be empty, in which case this form is equivalent to the one shown above. | |
| 105 | |
| 106 To print a message along with ringing the bell, you might modify the | |
| 6510 | 107 @code{wakeup} to look like this: |
| 3294 | 108 |
| 109 @example | |
| 110 @group | |
| 111 function wakeup (message) | |
| 112 printf ("\a%s\n", message); | |
| 113 endfunction | |
| 114 @end group | |
| 115 @end example | |
| 116 | |
| 117 Calling this function using a statement like this | |
| 118 | |
| 119 @example | |
| 120 wakeup ("Rise and shine!"); | |
| 121 @end example | |
| 122 | |
| 123 @noindent | |
| 124 will cause Octave to ring your terminal's bell and print the message | |
| 125 @samp{Rise and shine!}, followed by a newline character (the @samp{\n} | |
| 126 in the first argument to the @code{printf} statement). | |
| 127 | |
| 128 In most cases, you will also want to get some information back from the | |
| 129 functions you define. Here is the syntax for writing a function that | |
| 130 returns a single value: | |
| 131 | |
| 132 @example | |
| 133 @group | |
| 134 function @var{ret-var} = @var{name} (@var{arg-list}) | |
| 135 @var{body} | |
| 136 endfunction | |
| 137 @end group | |
| 138 @end example | |
| 139 | |
| 140 @noindent | |
| 141 The symbol @var{ret-var} is the name of the variable that will hold the | |
| 142 value to be returned by the function. This variable must be defined | |
| 143 before the end of the function body in order for the function to return | |
| 144 a value. | |
| 145 | |
| 146 Variables used in the body of a function are local to the | |
| 147 function. Variables named in @var{arg-list} and @var{ret-var} are also | |
| 148 local to the function. @xref{Global Variables}, for information about | |
| 149 how to access global variables inside a function. | |
| 150 | |
| 151 For example, here is a function that computes the average of the | |
| 152 elements of a vector: | |
| 153 | |
| 154 @example | |
| 155 @group | |
| 156 function retval = avg (v) | |
| 157 retval = sum (v) / length (v); | |
| 158 endfunction | |
| 159 @end group | |
| 160 @end example | |
| 161 | |
| 162 If we had written @code{avg} like this instead, | |
| 163 | |
| 164 @example | |
| 165 @group | |
| 166 function retval = avg (v) | |
| 4029 | 167 if (isvector (v)) |
| 3294 | 168 retval = sum (v) / length (v); |
| 169 endif | |
| 170 endfunction | |
| 171 @end group | |
| 172 @end example | |
| 173 | |
| 174 @noindent | |
| 175 and then called the function with a matrix instead of a vector as the | |
| 176 argument, Octave would have printed an error message like this: | |
| 177 | |
| 178 @example | |
| 179 @group | |
|
8015
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7984
diff
changeset
|
180 error: value on right hand side of assignment is undefined |
| 3294 | 181 @end group |
| 182 @end example | |
| 183 | |
| 184 @noindent | |
| 185 because the body of the @code{if} statement was never executed, and | |
| 186 @code{retval} was never defined. To prevent obscure errors like this, | |
| 187 it is a good idea to always make sure that the return variables will | |
| 188 always have values, and to produce meaningful error messages when | |
| 189 problems are encountered. For example, @code{avg} could have been | |
| 190 written like this: | |
| 191 | |
| 192 @example | |
| 193 @group | |
| 194 function retval = avg (v) | |
| 195 retval = 0; | |
| 4029 | 196 if (isvector (v)) |
| 3294 | 197 retval = sum (v) / length (v); |
| 198 else | |
| 199 error ("avg: expecting vector argument"); | |
| 200 endif | |
| 201 endfunction | |
| 202 @end group | |
| 203 @end example | |
| 204 | |
| 205 There is still one additional problem with this function. What if it is | |
| 206 called without an argument? Without additional error checking, Octave | |
| 207 will probably print an error message that won't really help you track | |
| 208 down the source of the error. To allow you to catch errors like this, | |
| 209 Octave provides each function with an automatic variable called | |
| 210 @code{nargin}. Each time a function is called, @code{nargin} is | |
| 211 automatically initialized to the number of arguments that have actually | |
| 212 been passed to the function. For example, we might rewrite the | |
| 213 @code{avg} function like this: | |
| 214 | |
| 215 @example | |
| 216 @group | |
| 217 function retval = avg (v) | |
| 218 retval = 0; | |
| 219 if (nargin != 1) | |
| 220 usage ("avg (vector)"); | |
| 221 endif | |
| 4029 | 222 if (isvector (v)) |
| 3294 | 223 retval = sum (v) / length (v); |
| 224 else | |
| 225 error ("avg: expecting vector argument"); | |
| 226 endif | |
| 227 endfunction | |
| 228 @end group | |
| 229 @end example | |
| 230 | |
| 231 Although Octave does not automatically report an error if you call a | |
| 232 function with more arguments than expected, doing so probably indicates | |
| 233 that something is wrong. Octave also does not automatically report an | |
| 234 error if a function is called with too few arguments, but any attempt to | |
| 235 use a variable that has not been given a value will result in an error. | |
| 236 To avoid such problems and to provide useful messages, we check for both | |
| 237 possibilities and issue our own error message. | |
| 238 | |
| 4700 | 239 @DOCSTRING(nargin) |
| 3294 | 240 |
| 6558 | 241 @DOCSTRING(inputname) |
| 242 | |
| 3371 | 243 @DOCSTRING(silent_functions) |
| 3294 | 244 |
| 4167 | 245 @node Multiple Return Values |
| 3294 | 246 @section Multiple Return Values |
| 247 | |
| 248 Unlike many other computer languages, Octave allows you to define | |
| 249 functions that return more than one value. The syntax for defining | |
| 250 functions that return multiple values is | |
| 251 | |
| 252 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
253 @group |
| 3294 | 254 function [@var{ret-list}] = @var{name} (@var{arg-list}) |
| 255 @var{body} | |
| 256 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
257 @end group |
| 3294 | 258 @end example |
| 259 | |
| 260 @noindent | |
| 261 where @var{name}, @var{arg-list}, and @var{body} have the same meaning | |
| 262 as before, and @var{ret-list} is a comma-separated list of variable | |
| 263 names that will hold the values returned from the function. The list of | |
| 264 return values must have at least one element. If @var{ret-list} has | |
| 265 only one element, this form of the @code{function} statement is | |
| 266 equivalent to the form described in the previous section. | |
| 267 | |
| 268 Here is an example of a function that returns two values, the maximum | |
| 269 element of a vector and the index of its first occurrence in the vector. | |
| 270 | |
| 271 @example | |
| 272 @group | |
| 273 function [max, idx] = vmax (v) | |
| 274 idx = 1; | |
| 275 max = v (idx); | |
| 276 for i = 2:length (v) | |
| 277 if (v (i) > max) | |
| 278 max = v (i); | |
| 279 idx = i; | |
| 280 endif | |
| 281 endfor | |
| 282 endfunction | |
| 283 @end group | |
| 284 @end example | |
| 285 | |
| 286 In this particular case, the two values could have been returned as | |
| 287 elements of a single array, but that is not always possible or | |
| 288 convenient. The values to be returned may not have compatible | |
| 289 dimensions, and it is often desirable to give the individual return | |
| 290 values distinct names. | |
| 291 | |
| 292 In addition to setting @code{nargin} each time a function is called, | |
| 293 Octave also automatically initializes @code{nargout} to the number of | |
| 294 values that are expected to be returned. This allows you to write | |
| 295 functions that behave differently depending on the number of values that | |
| 296 the user of the function has requested. The implicit assignment to the | |
| 297 built-in variable @code{ans} does not figure in the count of output | |
| 298 arguments, so the value of @code{nargout} may be zero. | |
| 299 | |
| 300 The @code{svd} and @code{lu} functions are examples of built-in | |
| 301 functions that behave differently depending on the value of | |
| 302 @code{nargout}. | |
| 303 | |
| 304 It is possible to write functions that only set some return values. For | |
| 305 example, calling the function | |
| 306 | |
| 307 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
308 @group |
| 3294 | 309 function [x, y, z] = f () |
| 310 x = 1; | |
| 311 z = 2; | |
| 312 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
313 @end group |
| 3294 | 314 @end example |
| 315 | |
| 316 @noindent | |
| 317 as | |
| 318 | |
| 319 @example | |
| 320 [a, b, c] = f () | |
| 321 @end example | |
| 322 | |
| 323 @noindent | |
| 324 produces: | |
| 325 | |
| 326 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
327 @group |
| 3294 | 328 a = 1 |
| 329 | |
| 330 b = [](0x0) | |
| 331 | |
| 332 c = 2 | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
333 @end group |
| 3294 | 334 @end example |
| 335 | |
| 336 @noindent | |
| 6501 | 337 along with a warning. |
| 3294 | 338 |
| 4700 | 339 @DOCSTRING(nargout) |
| 3294 | 340 |
| 3371 | 341 @DOCSTRING(nargchk) |
| 3294 | 342 |
|
7984
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
343 @DOCSTRING(nargoutchk) |
|
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
344 |
|
11431
0d9640d755b1
Improve docstrings for all isXXX functions.
Rik <octave@nomad.inbox5.com>
parents:
11396
diff
changeset
|
345 @DOCSTRING(isargout) |
|
0d9640d755b1
Improve docstrings for all isXXX functions.
Rik <octave@nomad.inbox5.com>
parents:
11396
diff
changeset
|
346 |
|
8286
6f2d95255911
fix @seealso references to point to existing anchors
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8276
diff
changeset
|
347 @anchor{doc-varargin} @anchor{doc-varargout} |
| 4167 | 348 @node Variable-length Argument Lists |
| 3294 | 349 @section Variable-length Argument Lists |
| 4933 | 350 @cindex variable-length argument lists |
| 8567 | 351 @cindex @code{varargin} |
| 8072 | 352 |
| 6510 | 353 Sometimes the number of input arguments is not known when the function |
| 354 is defined. As an example think of a function that returns the smallest | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
355 of all its input arguments. For example: |
| 6510 | 356 |
| 357 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
358 @group |
| 6510 | 359 a = smallest (1, 2, 3); |
| 360 b = smallest (1, 2, 3, 4); | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
361 @end group |
| 6510 | 362 @end example |
| 363 | |
| 364 @noindent | |
| 365 In this example both @code{a} and @code{b} would be 1. One way to write | |
| 366 the @code{smallest} function is | |
| 367 | |
| 368 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
369 @group |
| 6510 | 370 function val = smallest (arg1, arg2, arg3, arg4, arg5) |
| 371 @var{body} | |
| 372 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
373 @end group |
| 6510 | 374 @end example |
| 375 | |
| 376 @noindent | |
| 377 and then use the value of @code{nargin} to determine which of the input | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
378 arguments should be considered. The problem with this approach is |
| 6510 | 379 that it can only handle a limited number of input arguments. |
| 380 | |
|
7588
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
381 If the special parameter name @code{varargin} appears at the end of a |
|
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
382 function parameter list it indicates that the function takes a variable |
|
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
383 number of input arguments. Using @code{varargin} the function |
| 6510 | 384 looks like this |
| 385 | |
| 386 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
387 @group |
| 6510 | 388 function val = smallest (varargin) |
| 389 @var{body} | |
| 390 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
391 @end group |
| 6510 | 392 @end example |
| 393 | |
| 394 @noindent | |
| 395 In the function body the input arguments can be accessed through the | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
396 variable @code{varargin}. This variable is a cell array containing |
|
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
397 all the input arguments. @xref{Cell Arrays}, for details on working |
|
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
398 with cell arrays. The @code{smallest} function can now be defined |
| 6510 | 399 like this |
| 400 | |
| 401 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
402 @group |
| 6510 | 403 function val = smallest (varargin) |
| 404 val = min ([varargin@{:@}]); | |
| 405 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
406 @end group |
| 6510 | 407 @end example |
| 408 | |
| 409 @noindent | |
| 410 This implementation handles any number of input arguments, but it's also | |
| 411 a very simple solution to the problem. | |
| 412 | |
| 413 A slightly more complex example of @code{varargin} is a function | |
| 414 @code{print_arguments} that prints all input arguments. Such a function | |
| 415 can be defined like this | |
| 416 | |
| 417 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
418 @group |
| 6510 | 419 function print_arguments (varargin) |
| 420 for i = 1:length (varargin) | |
| 421 printf ("Input argument %d: ", i); | |
| 422 disp (varargin@{i@}); | |
| 423 endfor | |
| 424 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
425 @end group |
| 6510 | 426 @end example |
| 427 | |
| 428 @noindent | |
| 429 This function produces output like this | |
| 430 | |
| 431 @example | |
| 432 @group | |
| 433 print_arguments (1, "two", 3); | |
| 434 @print{} Input argument 1: 1 | |
| 435 @print{} Input argument 2: two | |
| 436 @print{} Input argument 3: 3 | |
| 437 @end group | |
| 438 @end example | |
| 3294 | 439 |
| 6558 | 440 @DOCSTRING(parseparams) |
| 441 | |
|
10209
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
442 @node Ignoring Arguments |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
443 @section Ignoring Arguments |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
444 |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
445 In the formal argument list, it is possible to use the dummy placeholder |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
446 @code{~} instead of a name. This indicates that the corresponding argument |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
447 value should be ignored and not stored to any variable. |
|
10209
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
448 |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
449 @example |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
450 @group |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
451 function val = pick2nd (~, arg2) |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
452 val = arg2; |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
453 endfunction |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
454 @end group |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
455 @end example |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
456 |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
457 The value of @code{nargin} is not affected by using this declaration. |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
458 |
| 4167 | 459 @node Variable-length Return Lists |
| 3294 | 460 @section Variable-length Return Lists |
| 4933 | 461 @cindex variable-length return lists |
| 8567 | 462 @cindex @code{varargout} |
| 8072 | 463 |
| 6510 | 464 It is possible to return a variable number of output arguments from a |
| 465 function using a syntax that's similar to the one used with the | |
|
7588
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
466 special @code{varargin} parameter name. To let a function return a |
|
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
467 variable number of output arguments the special output parameter name |
|
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
468 @code{varargout} is used. As with @code{varargin}, @code{varargout} is |
|
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
469 a cell array that will contain the requested output arguments. |
| 6510 | 470 |
| 471 As an example the following function sets the first output argument to | |
| 472 1, the second to 2, and so on. | |
| 473 | |
| 474 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
475 @group |
| 6510 | 476 function varargout = one_to_n () |
| 477 for i = 1:nargout | |
| 478 varargout@{i@} = i; | |
| 479 endfor | |
| 480 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
481 @end group |
| 6510 | 482 @end example |
| 483 | |
| 484 @noindent | |
| 485 When called this function returns values like this | |
| 486 | |
| 487 @example | |
| 488 @group | |
| 489 [a, b, c] = one_to_n () | |
| 490 @result{} a = 1 | |
| 491 @result{} b = 2 | |
| 492 @result{} c = 3 | |
| 493 @end group | |
| 494 @end example | |
| 3294 | 495 |
|
7588
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
496 If @code{varargin} (@code{varargout}) does not appear as the last |
|
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
497 element of the input (output) parameter list, then it is not special, |
|
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
498 and is handled the same as any other parameter name. |
|
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
499 |
| 6558 | 500 @DOCSTRING(deal) |
| 501 | |
|
11255
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
502 @node Returning from a Function |
|
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
503 @section Returning from a Function |
| 3294 | 504 |
| 505 The body of a user-defined function can contain a @code{return} statement. | |
| 506 This statement returns control to the rest of the Octave program. It | |
| 507 looks like this: | |
| 508 | |
| 509 @example | |
| 510 return | |
| 511 @end example | |
| 512 | |
| 513 Unlike the @code{return} statement in C, Octave's @code{return} | |
| 514 statement cannot be used to return a value from a function. Instead, | |
| 515 you must assign values to the list of return variables that are part of | |
| 516 the @code{function} statement. The @code{return} statement simply makes | |
| 517 it easier to exit a function from a deeply nested loop or conditional | |
| 518 statement. | |
| 519 | |
| 520 Here is an example of a function that checks to see if any elements of a | |
| 521 vector are nonzero. | |
| 522 | |
| 523 @example | |
| 524 @group | |
| 525 function retval = any_nonzero (v) | |
| 526 retval = 0; | |
| 527 for i = 1:length (v) | |
| 528 if (v (i) != 0) | |
| 529 retval = 1; | |
| 530 return; | |
| 531 endif | |
| 532 endfor | |
| 533 printf ("no nonzero elements found\n"); | |
| 534 endfunction | |
| 535 @end group | |
| 536 @end example | |
| 537 | |
| 538 Note that this function could not have been written using the | |
| 539 @code{break} statement to exit the loop once a nonzero value is found | |
| 540 without adding extra logic to avoid printing the message if the vector | |
| 541 does contain a nonzero element. | |
| 542 | |
| 11547 | 543 @deftypefn {Keyword} {} return |
| 3294 | 544 When Octave encounters the keyword @code{return} inside a function or |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
545 script, it returns control to the caller immediately. At the top level, |
| 3294 | 546 the return statement is ignored. A @code{return} statement is assumed |
| 547 at the end of every function definition. | |
| 11547 | 548 @end deftypefn |
| 3294 | 549 |
| 6510 | 550 @node Default Arguments |
| 551 @section Default Arguments | |
| 552 @cindex default arguments | |
| 553 | |
| 554 Since Octave supports variable number of input arguments, it is very useful | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
555 to assign default values to some input arguments. When an input argument |
| 6510 | 556 is declared in the argument list it is possible to assign a default |
| 557 value to the argument like this | |
| 558 | |
| 559 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
560 @group |
| 6510 | 561 function @var{name} (@var{arg1} = @var{val1}, @dots{}) |
| 562 @var{body} | |
| 563 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
564 @end group |
| 6510 | 565 @end example |
| 566 | |
| 567 @noindent | |
| 568 If no value is assigned to @var{arg1} by the user, it will have the | |
| 569 value @var{val1}. | |
| 570 | |
| 571 As an example, the following function implements a variant of the classic | |
| 572 ``Hello, World'' program. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
573 |
| 6510 | 574 @example |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
575 @group |
| 6510 | 576 function hello (who = "World") |
| 577 printf ("Hello, %s!\n", who); | |
| 578 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
579 @end group |
| 6510 | 580 @end example |
| 581 | |
| 582 @noindent | |
| 583 When called without an input argument the function prints the following | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
584 |
| 6510 | 585 @example |
| 586 @group | |
| 587 hello (); | |
| 588 @print{} Hello, World! | |
| 589 @end group | |
| 590 @end example | |
| 591 | |
| 592 @noindent | |
| 593 and when it's called with an input argument it prints the following | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
594 |
| 6510 | 595 @example |
| 596 @group | |
| 597 hello ("Beautiful World of Free Software"); | |
| 598 @print{} Hello, Beautiful World of Free Software! | |
| 599 @end group | |
| 600 @end example | |
| 601 | |
| 602 Sometimes it is useful to explicitly tell Octave to use the default value | |
| 603 of an input argument. This can be done writing a @samp{:} as the value | |
| 604 of the input argument when calling the function. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
605 |
| 6510 | 606 @example |
| 607 @group | |
| 608 hello (:); | |
| 609 @print{} Hello, World! | |
| 610 @end group | |
| 611 @end example | |
| 612 | |
| 4167 | 613 @node Function Files |
| 3294 | 614 @section Function Files |
| 615 @cindex function file | |
| 616 | |
| 617 Except for simple one-shot programs, it is not practical to have to | |
| 618 define all the functions you need each time you need them. Instead, you | |
| 619 will normally want to save them in a file so that you can easily edit | |
| 620 them, and save them for use at a later time. | |
| 621 | |
| 622 Octave does not require you to load function definitions from files | |
| 623 before using them. You simply need to put the function definitions in a | |
| 624 place where Octave can find them. | |
| 625 | |
| 626 When Octave encounters an identifier that is undefined, it first looks | |
| 627 for variables or functions that are already compiled and currently | |
| 628 listed in its symbol table. If it fails to find a definition there, it | |
| 6556 | 629 searches a list of directories (the @dfn{path}) for files ending in |
| 6554 | 630 @file{.m} that have the same base name as the undefined |
| 631 identifier.@footnote{The @samp{.m} suffix was chosen for compatibility | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
632 with @sc{matlab}.} Once Octave finds a file with a name that matches, |
| 6554 | 633 the contents of the file are read. If it defines a @emph{single} |
| 634 function, it is compiled and executed. @xref{Script Files}, for more | |
| 635 information about how you can define more than one function in a single | |
| 636 file. | |
| 3294 | 637 |
| 638 When Octave defines a function from a function file, it saves the full | |
| 6554 | 639 name of the file it read and the time stamp on the file. If the time |
| 640 stamp on the file changes, Octave may reload the file. When Octave is | |
| 641 running interactively, time stamp checking normally happens at most once | |
| 642 each time Octave prints the prompt. Searching for new function | |
| 643 definitions also occurs if the current working directory changes. | |
| 3294 | 644 |
| 645 Checking the time stamp allows you to edit the definition of a function | |
| 646 while Octave is running, and automatically use the new function | |
| 6554 | 647 definition without having to restart your Octave session. |
| 3294 | 648 |
| 649 To avoid degrading performance unnecessarily by checking the time stamps | |
| 650 on functions that are not likely to change, Octave assumes that function | |
| 651 files in the directory tree | |
| 652 @file{@var{octave-home}/share/octave/@var{version}/m} | |
| 653 will not change, so it doesn't have to check their time stamps every time the | |
| 654 functions defined in those files are used. This is normally a very good | |
| 655 assumption and provides a significant improvement in performance for the | |
| 656 function files that are distributed with Octave. | |
| 657 | |
| 658 If you know that your own function files will not change while you are | |
| 6554 | 659 running Octave, you can improve performance by calling |
| 660 @code{ignore_function_time_stamp ("all")}, so that Octave will | |
| 661 ignore the time stamps for all function files. Passing | |
| 662 @code{"system"} to this function resets the default behavior. | |
| 3294 | 663 |
| 5775 | 664 @c FIXME -- note about time stamps on files in NFS environments? |
| 3294 | 665 |
|
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
666 @DOCSTRING(edit) |
|
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
667 |
| 6549 | 668 @DOCSTRING(mfilename) |
| 669 | |
| 6638 | 670 @DOCSTRING(ignore_function_time_stamp) |
| 671 | |
| 672 @menu | |
|
11255
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
673 * Manipulating the Load Path:: |
| 6638 | 674 * Subfunctions:: |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
675 * Private Functions:: |
| 6638 | 676 * Overloading and Autoloading:: |
| 677 * Function Locking:: | |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
678 * Function Precedence:: |
| 6638 | 679 @end menu |
| 680 | |
|
11257
8d4c57258523
fix some menu problems in the manual
John W. Eaton <jwe@octave.org>
parents:
11255
diff
changeset
|
681 @node Manipulating the Load Path |
|
8d4c57258523
fix some menu problems in the manual
John W. Eaton <jwe@octave.org>
parents:
11255
diff
changeset
|
682 @subsection Manipulating the Load Path |
| 6638 | 683 |
| 8828 | 684 When a function is called, Octave searches a list of directories for |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
685 a file that contains the function declaration. This list of directories |
|
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
686 is known as the load path. By default the load path contains |
| 6638 | 687 a list of directories distributed with Octave plus the current |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
688 working directory. To see your current load path call the @code{path} |
| 6638 | 689 function without any input or output arguments. |
| 690 | |
| 691 It is possible to add or remove directories to or from the load path | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
692 using @code{addpath} and @code{rmpath}. As an example, the following |
| 6638 | 693 code adds @samp{~/Octave} to the load path. |
| 694 | |
| 695 @example | |
| 696 addpath("~/Octave") | |
| 697 @end example | |
| 698 | |
| 699 @noindent | |
| 700 After this the directory @samp{~/Octave} will be searched for functions. | |
| 701 | |
| 6502 | 702 @DOCSTRING(addpath) |
| 703 | |
| 704 @DOCSTRING(genpath) | |
| 705 | |
| 706 @DOCSTRING(rmpath) | |
| 707 | |
| 708 @DOCSTRING(savepath) | |
| 709 | |
| 6477 | 710 @DOCSTRING(path) |
| 3294 | 711 |
| 6502 | 712 @DOCSTRING(pathdef) |
| 713 | |
| 714 @DOCSTRING(pathsep) | |
| 715 | |
| 3428 | 716 @DOCSTRING(rehash) |
| 717 | |
| 718 @DOCSTRING(file_in_loadpath) | |
| 719 | |
|
7638
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7588
diff
changeset
|
720 @DOCSTRING(restoredefaultpath) |
|
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7588
diff
changeset
|
721 |
|
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
722 @DOCSTRING(command_line_path) |
|
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
723 |
|
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
724 @DOCSTRING(find_dir_in_path) |
|
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
725 |
| 6556 | 726 @node Subfunctions |
| 727 @subsection Subfunctions | |
| 728 | |
| 729 A function file may contain secondary functions called | |
| 730 @dfn{subfunctions}. These secondary functions are only visible to the | |
| 731 other functions in the same function file. For example, a file | |
| 732 @file{f.m} containing | |
| 733 | |
| 734 @example | |
| 735 @group | |
| 736 function f () | |
| 737 printf ("in f, calling g\n"); | |
| 738 g () | |
| 739 endfunction | |
| 740 function g () | |
| 741 printf ("in g, calling h\n"); | |
| 6638 | 742 h () |
| 6556 | 743 endfunction |
| 744 function h () | |
| 745 printf ("in h\n") | |
| 746 endfunction | |
| 747 @end group | |
| 748 @end example | |
| 749 | |
| 750 @noindent | |
| 751 defines a main function @code{f} and two subfunctions. The | |
| 752 subfunctions @code{g} and @code{h} may only be called from the main | |
| 753 function @code{f} or from the other subfunctions, but not from outside | |
| 754 the file @file{f.m}. | |
| 755 | |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
756 @node Private Functions |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
757 @subsection Private Functions |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
758 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
759 In many cases one function needs to access one or more helper |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
760 functions. If the helper function is limited to the scope of a single |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
761 function, then subfunctions as discussed above might be used. However, |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
762 if a single helper function is used by more than one function, then |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
763 this is no longer possible. In this case the helper functions might |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
764 be placed in a subdirectory, called "private", of the directory in which |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
765 the functions needing access to this helper function are found. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
766 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
767 As a simple example, consider a function @code{func1}, that calls a helper |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
768 function @code{func2} to do much of the work. For example: |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
769 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
770 @example |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
771 @group |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
772 function y = func1 (x) |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
773 y = func2 (x); |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
774 endfunction |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
775 @end group |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
776 @end example |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
777 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
778 @noindent |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
779 Then if the path to @code{func1} is @code{<directory>/func1.m}, and if |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
780 @code{func2} is found in the directory @code{<directory>/private/func2.m}, |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
781 then @code{func2} is only available for use of the functions, like |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
782 @code{func1}, that are found in @code{<directory>}. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
783 |
| 6635 | 784 @node Overloading and Autoloading |
| 785 @subsection Overloading and Autoloading | |
| 786 | |
|
11396
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
787 Functions can be overloaded to work with different input arguments. For |
|
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
788 example, the operator '+' has been overloaded in Octave to work with single, |
|
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
789 double, uint8, int32, and many other arguments. The preferred way to overload |
|
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
790 functions is through classes and object oriented programming |
|
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
791 (@pxref{Function Overloading}). Occasionally, however, one needs to undo |
|
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
792 user overloading and call the default function associated with a specific |
|
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
793 type. The @code{builtin} function exists for this purpose. |
| 6635 | 794 |
| 795 @DOCSTRING(builtin) | |
| 796 | |
| 797 A single dynamically linked file might define several | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
798 functions. However, as Octave searches for functions based on the |
| 6635 | 799 functions filename, Octave needs a manner in which to find each of the |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
800 functions in the dynamically linked file. On operating systems that |
| 6635 | 801 support symbolic links, it is possible to create a symbolic link to the |
| 802 original file for each of the functions which it contains. | |
| 803 | |
| 804 However, there is at least one well known operating system that doesn't | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
805 support symbolic links. Making copies of the original file for each of |
| 8828 | 806 the functions is undesirable as it increases the |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
807 amount of disk space used by Octave. Instead Octave supplies the |
| 6635 | 808 @code{autoload} function, that permits the user to define in which |
| 809 file a certain function will be found. | |
| 810 | |
| 811 @DOCSTRING(autoload) | |
| 812 | |
| 813 @node Function Locking | |
| 814 @subsection Function Locking | |
| 815 | |
| 816 It is sometime desirable to lock a function into memory with the | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
817 @code{mlock} function. This is typically used for dynamically linked |
| 6899 | 818 functions in Oct-files or mex-files that contain some initialization, |
| 819 and it is desirable that calling @code{clear} does not remove this | |
| 6635 | 820 initialization. |
| 821 | |
| 6899 | 822 As an example, |
| 823 | |
| 824 @example | |
| 825 mlock ("my_function"); | |
| 826 @end example | |
| 827 | |
| 828 @noindent | |
| 829 prevents @code{my_function} from being removed from memory, even if | |
| 830 @code{clear} is called. It is possible to determine if a function is | |
| 831 locked into memory with the @code{mislocked}, and to unlock a function | |
| 832 with @code{munlock}, which the following illustrates. | |
| 833 | |
| 834 @example | |
| 835 @group | |
| 836 mlock ("my_function"); | |
| 837 mislocked ("my_function") | |
| 838 @result{} ans = 1 | |
| 839 munlock ("my_function"); | |
| 840 mislocked ("my_function") | |
| 841 @result{} ans = 0 | |
| 842 @end group | |
| 843 @end example | |
| 844 | |
| 845 A common use of @code{mlock} is to prevent persistent variables from | |
| 8828 | 846 being removed from memory, as the following example shows: |
| 6899 | 847 |
| 848 @example | |
| 849 @group | |
| 850 function count_calls() | |
| 851 persistent calls = 0; | |
| 7031 | 852 printf ("'count_calls' has been called %d times\n", |
| 853 ++calls); | |
| 6899 | 854 endfunction |
| 855 mlock ("count_calls"); | |
| 856 | |
| 857 count_calls (); | |
| 858 @print{} 'count_calls' has been called 1 times | |
| 859 | |
| 860 clear count_calls | |
| 861 count_calls (); | |
| 862 @print{} 'count_calls' has been called 2 times | |
| 863 @end group | |
| 864 @end example | |
| 865 | |
| 866 @noindent | |
| 867 It is, however, often inconvenient to lock a function from the prompt, | |
| 868 so it is also possible to lock a function from within its body. This | |
| 869 is simply done by calling @code{mlock} from within the function. | |
| 870 | |
| 871 @example | |
| 872 @group | |
| 873 function count_calls () | |
| 874 mlock (); | |
| 875 persistent calls = 0; | |
| 7031 | 876 printf ("'count_calls' has been called %d times\n", |
| 877 ++calls); | |
| 6899 | 878 endfunction |
| 879 @end group | |
| 880 @end example | |
| 881 | |
| 882 @code{mlock} might equally be used to prevent changes to a function from having | |
| 6635 | 883 effect in Octave, though a similar effect can be had with the |
| 884 @code{ignore_function_time_stamp} function. | |
| 885 | |
| 886 @DOCSTRING(mlock) | |
| 887 | |
| 888 @DOCSTRING(munlock) | |
| 889 | |
| 890 @DOCSTRING(mislocked) | |
| 891 | |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
892 @node Function Precedence |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
893 @subsection Function Precedence |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
894 |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
895 Given the numerous different ways that Octave can define a function, it |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
896 is possible and even likely that multiple versions of a function, might be |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
897 defined within a particular scope. The precedence of which function will be |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
898 used within a particular scope is given by |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
899 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
900 @enumerate 1 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
901 @item Subfunction |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
902 A subfunction with the required function name in the given scope. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
903 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
904 @item Private function |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
905 A function defined within a private directory of the directory |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
906 which contains the current function. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
907 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
908 @item Class constructor |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
909 A function that constuctors a user class as defined in chapter |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
910 @ref{Object Oriented Programming}. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
911 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
912 @item Class method |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
913 An overloaded function of a class as in chapter |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
914 @ref{Object Oriented Programming}. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
915 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
916 @item Legacy Dispatch |
|
11396
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
917 An overloaded function as defined by @code{dispatch}. |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
918 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
919 @item Command-line Function |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
920 A function that has been defined on the command-line. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
921 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
922 @item Autoload function |
| 8235 | 923 A function that is marked as autoloaded with @xref{doc-autoload}. |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
924 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
925 @item A Function on the Path |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
926 A function that can be found on the users load-path. There can also be |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
927 Oct-file, mex-file or m-file versions of this function and the precedence |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
928 between these versions are in that order. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
929 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
930 @item Built-in function |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
931 A function that is builtin to Octave itself such as @code{numel}, |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
932 @code{size}, etc. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
933 @end enumerate |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
934 |
| 4167 | 935 @node Script Files |
| 3294 | 936 @section Script Files |
| 937 | |
| 938 A script file is a file containing (almost) any sequence of Octave | |
| 939 commands. It is read and evaluated just as if you had typed each | |
| 940 command at the Octave prompt, and provides a convenient way to perform a | |
| 941 sequence of commands that do not logically belong inside a function. | |
| 942 | |
| 943 Unlike a function file, a script file must @emph{not} begin with the | |
| 944 keyword @code{function}. If it does, Octave will assume that it is a | |
| 945 function file, and that it defines a single function that should be | |
| 946 evaluated as soon as it is defined. | |
| 947 | |
| 948 A script file also differs from a function file in that the variables | |
| 949 named in a script file are not local variables, but are in the same | |
| 950 scope as the other variables that are visible on the command line. | |
| 951 | |
| 952 Even though a script file may not begin with the @code{function} | |
| 953 keyword, it is possible to define more than one function in a single | |
| 954 script file and load (but not execute) all of them at once. To do | |
| 955 this, the first token in the file (ignoring comments and other white | |
| 956 space) must be something other than @code{function}. If you have no | |
| 957 other statements to evaluate, you can use a statement that has no | |
| 958 effect, like this: | |
| 959 | |
| 960 @example | |
| 961 @group | |
| 962 # Prevent Octave from thinking that this | |
| 963 # is a function file: | |
| 964 | |
| 965 1; | |
| 966 | |
| 967 # Define function one: | |
| 968 | |
| 969 function one () | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
970 @dots{} |
| 3294 | 971 @end group |
| 972 @end example | |
| 973 | |
| 974 To have Octave read and compile these functions into an internal form, | |
| 6638 | 975 you need to make sure that the file is in Octave's load path |
| 6477 | 976 (accessible through the @code{path} function), then simply type the |
| 977 base name of the file that contains the commands. (Octave uses the | |
| 978 same rules to search for script files as it does to search for | |
| 979 function files.) | |
| 3294 | 980 |
| 981 If the first token in a file (ignoring comments) is @code{function}, | |
| 982 Octave will compile the function and try to execute it, printing a | |
| 983 message warning about any non-whitespace characters that appear after | |
| 984 the function definition. | |
| 985 | |
| 986 Note that Octave does not try to look up the definition of any identifier | |
| 987 until it needs to evaluate it. This means that Octave will compile the | |
| 988 following statements if they appear in a script file, or are typed at | |
| 989 the command line, | |
| 990 | |
| 991 @example | |
| 992 @group | |
| 993 # not a function file: | |
| 994 1; | |
| 995 function foo () | |
| 996 do_something (); | |
| 997 endfunction | |
| 998 function do_something () | |
| 999 do_something_else (); | |
| 1000 endfunction | |
| 1001 @end group | |
| 1002 @end example | |
| 1003 | |
| 1004 @noindent | |
| 1005 even though the function @code{do_something} is not defined before it is | |
| 1006 referenced in the function @code{foo}. This is not an error because | |
| 1007 Octave does not need to resolve all symbols that are referenced by a | |
| 1008 function until the function is actually evaluated. | |
| 1009 | |
| 1010 Since Octave doesn't look for definitions until they are needed, the | |
| 1011 following code will always print @samp{bar = 3} whether it is typed | |
| 1012 directly on the command line, read from a script file, or is part of a | |
| 1013 function body, even if there is a function or script file called | |
| 6477 | 1014 @file{bar.m} in Octave's path. |
| 3294 | 1015 |
| 1016 @example | |
| 1017 @group | |
| 1018 eval ("bar = 3"); | |
| 1019 bar | |
| 1020 @end group | |
| 1021 @end example | |
| 1022 | |
| 1023 Code like this appearing within a function body could fool Octave if | |
| 1024 definitions were resolved as the function was being compiled. It would | |
| 1025 be virtually impossible to make Octave clever enough to evaluate this | |
| 1026 code in a consistent fashion. The parser would have to be able to | |
| 1027 perform the call to @code{eval} at compile time, and that would be | |
| 1028 impossible unless all the references in the string to be evaluated could | |
| 1029 also be resolved, and requiring that would be too restrictive (the | |
| 1030 string might come from user input, or depend on things that are not | |
| 1031 known until the function is evaluated). | |
| 1032 | |
| 1033 Although Octave normally executes commands from script files that have | |
| 1034 the name @file{@var{file}.m}, you can use the function @code{source} to | |
| 1035 execute commands from any file. | |
| 1036 | |
| 3371 | 1037 @DOCSTRING(source) |
| 3294 | 1038 |
| 6638 | 1039 @node Function Handles Inline Functions and Anonymous Functions |
| 1040 @section Function Handles, Inline Functions, and Anonymous Functions | |
| 4933 | 1041 @cindex handle, function handles |
| 1042 @cindex inline, inline functions | |
| 6638 | 1043 @cindex anonymous functions |
| 4933 | 1044 |
| 6638 | 1045 It can be very convenient store a function in a variable so that it |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1046 can be passed to a different function. For example, a function that |
|
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1047 performs numerical minimization needs access to the function that |
|
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1048 should be minimized. |
| 4933 | 1049 |
| 1050 @menu | |
| 1051 * Function Handles:: | |
| 6554 | 1052 * Anonymous Functions:: |
| 4933 | 1053 * Inline Functions:: |
| 1054 @end menu | |
| 1055 | |
| 1056 @node Function Handles | |
| 1057 @subsection Function Handles | |
| 1058 | |
| 6554 | 1059 A function handle is a pointer to another function and is defined with |
| 1060 the syntax | |
| 1061 | |
| 1062 @example | |
| 1063 @@@var{function-name} | |
| 1064 @end example | |
| 1065 | |
| 1066 @noindent | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
1067 For example, |
| 6554 | 1068 |
| 1069 @example | |
| 6556 | 1070 f = @@sin; |
| 6554 | 1071 @end example |
| 1072 | |
| 1073 @noindent | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
1074 creates a function handle called @code{f} that refers to the |
| 6554 | 1075 function @code{sin}. |
| 1076 | |
| 1077 Function handles are used to call other functions indirectly, or to pass | |
| 1078 a function as an argument to another function like @code{quad} or | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
1079 @code{fsolve}. For example: |
| 6554 | 1080 |
| 1081 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1082 @group |
| 6556 | 1083 f = @@sin; |
| 6554 | 1084 quad (f, 0, pi) |
| 6929 | 1085 @result{} 2 |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1086 @end group |
| 6554 | 1087 @end example |
| 1088 | |
| 1089 You may use @code{feval} to call a function using function handle, or | |
| 6570 | 1090 simply write the name of the function handle followed by an argument |
| 6554 | 1091 list. If there are no arguments, you must use an empty argument list |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
1092 @samp{()}. For example: |
| 6554 | 1093 |
| 1094 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1095 @group |
| 6556 | 1096 f = @@sin; |
| 6554 | 1097 feval (f, pi/4) |
| 6570 | 1098 @result{} 0.70711 |
| 6554 | 1099 f (pi/4) |
| 6570 | 1100 @result{} 0.70711 |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1101 @end group |
| 6554 | 1102 @end example |
| 1103 | |
| 4933 | 1104 @DOCSTRING(functions) |
| 1105 | |
| 1106 @DOCSTRING(func2str) | |
| 1107 | |
| 1108 @DOCSTRING(str2func) | |
| 1109 | |
| 6570 | 1110 @node Anonymous Functions |
| 6554 | 1111 @subsection Anonymous Functions |
| 1112 | |
| 1113 Anonymous functions are defined using the syntax | |
| 1114 | |
| 1115 @example | |
| 1116 @@(@var{argument-list}) @var{expression} | |
| 1117 @end example | |
| 1118 | |
| 1119 @noindent | |
| 1120 Any variables that are not found in the argument list are inherited from | |
| 1121 the enclosing scope. Anonymous functions are useful for creating simple | |
| 1122 unnamed functions from expressions or for wrapping calls to other | |
| 1123 functions to adapt them for use by functions like @code{quad}. For | |
| 1124 example, | |
| 1125 | |
| 1126 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1127 @group |
| 6554 | 1128 f = @@(x) x.^2; |
| 1129 quad (f, 0, 10) | |
| 6570 | 1130 @result{} 333.33 |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1131 @end group |
| 6554 | 1132 @end example |
| 1133 | |
| 1134 @noindent | |
| 1135 creates a simple unnamed function from the expression @code{x.^2} and | |
| 1136 passes it to @code{quad}, | |
| 1137 | |
| 1138 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1139 @group |
| 6554 | 1140 quad (@@(x) sin (x), 0, pi) |
| 6933 | 1141 @result{} 2 |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1142 @end group |
| 6554 | 1143 @end example |
| 1144 | |
| 1145 @noindent | |
| 1146 wraps another function, and | |
| 1147 | |
| 1148 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1149 @group |
| 6554 | 1150 a = 1; |
| 1151 b = 2; | |
| 1152 quad (@@(x) betainc (x, a, b), 0, 0.4) | |
| 6929 | 1153 @result{} 0.13867 |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1154 @end group |
| 6554 | 1155 @end example |
| 1156 | |
| 1157 @noindent | |
| 1158 adapts a function with several parameters to the form required by | |
| 1159 @code{quad}. In this example, the values of @var{a} and @var{b} that | |
| 1160 are passed to @code{betainc} are inherited from the current | |
| 1161 environment. | |
| 1162 | |
| 4933 | 1163 @node Inline Functions |
| 1164 @subsection Inline Functions | |
| 1165 | |
| 6638 | 1166 An inline function is created from a string containing the function |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1167 body using the @code{inline} function. The following code defines the |
| 6638 | 1168 function @math{f(x) = x^2 + 2}. |
| 1169 | |
| 1170 @example | |
| 1171 f = inline("x^2 + 2"); | |
| 1172 @end example | |
| 1173 | |
| 1174 @noindent | |
| 1175 After this it is possible to evaluate @math{f} at any @math{x} by | |
| 1176 writing @code{f(x)}. | |
| 1177 | |
| 4933 | 1178 @DOCSTRING(inline) |
| 1179 | |
| 1180 @DOCSTRING(argnames) | |
| 1181 | |
| 1182 @DOCSTRING(formula) | |
| 1183 | |
| 1184 @DOCSTRING(vectorize) | |
| 1185 | |
|
7984
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
1186 @DOCSTRING(symvar) |
|
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
1187 |
| 6549 | 1188 @node Commands |
| 1189 @section Commands | |
| 1190 | |
| 6638 | 1191 Commands are a special class of functions that only accept string |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1192 input arguments. A command can be called as an ordinary function, but |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1193 it can also be called without the parentheses. For example, |
| 6638 | 1194 |
| 1195 @example | |
| 1196 my_command hello world | |
| 1197 @end example | |
| 1198 | |
| 1199 @noindent | |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1200 is equivalent to |
| 6638 | 1201 |
| 1202 @example | |
| 1203 my_command("hello", "world") | |
| 1204 @end example | |
| 1205 | |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1206 @noindent |
| 6638 | 1207 The general form of a command call is |
| 1208 | |
| 1209 @example | |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1210 @var{cmdname} @var{arg1} @var{arg2} @dots{} |
| 6638 | 1211 @end example |
| 1212 | |
| 1213 @noindent | |
| 1214 which translates directly to | |
| 1215 | |
| 1216 @example | |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1217 @var{cmdname} ("@var{arg1}", "@var{arg2}", @dots{}) |
| 6638 | 1218 @end example |
| 1219 | |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1220 Any regular function can be used as a command if it accepts string input |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1221 arguments. For example: |
|
11573
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11547
diff
changeset
|
1222 |
| 6638 | 1223 @example |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1224 @group |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1225 toupper lower_case_arg |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1226 @result{} ans = LOWER_CASE_ARG |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1227 @end group |
| 6638 | 1228 @end example |
| 1229 | |
| 1230 One difficulty of commands occurs when one of the string input arguments | |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1231 is stored in a variable. Because Octave can't tell the difference between |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1232 a variable name and an ordinary string, it is not possible to pass a |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1233 variable as input to a command. In such a situation a command must be |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1234 called as a function. For example: |
| 6549 | 1235 |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1236 @example |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1237 @group |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1238 strvar = "hello world"; |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1239 toupper strvar |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1240 @result{} ans = STRVAR |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1241 toupper (strvar) |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1242 @result{} ans = HELLO WORLD |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1243 @end group |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1244 @end example |
| 6549 | 1245 |
| 1246 | |
| 4167 | 1247 @node Organization of Functions |
| 3294 | 1248 @section Organization of Functions Distributed with Octave |
| 1249 | |
| 1250 Many of Octave's standard functions are distributed as function files. | |
| 1251 They are loosely organized by topic, in subdirectories of | |
| 1252 @file{@var{octave-home}/lib/octave/@var{version}/m}, to make it easier | |
| 1253 to find them. | |
| 1254 | |
| 1255 The following is a list of all the function file subdirectories, and the | |
| 1256 types of functions you will find there. | |
| 1257 | |
| 1258 @table @file | |
| 1259 @item audio | |
| 1260 Functions for playing and recording sounds. | |
| 1261 | |
| 1262 @item control | |
| 1263 Functions for design and simulation of automatic control systems. | |
| 1264 | |
| 1265 @item elfun | |
| 1266 Elementary functions. | |
| 1267 | |
| 6554 | 1268 @item finance |
| 1269 Functions for computing interest payments, investment values, and rates | |
| 1270 of return. | |
| 1271 | |
| 3294 | 1272 @item general |
| 1273 Miscellaneous matrix manipulations, like @code{flipud}, @code{rot90}, | |
| 1274 and @code{triu}, as well as other basic functions, like | |
| 4029 | 1275 @code{ismatrix}, @code{nargchk}, etc. |
| 3294 | 1276 |
| 1277 @item image | |
| 1278 Image processing tools. These functions require the X Window System. | |
| 1279 | |
| 1280 @item io | |
|
8325
b93ac0586e4b
spelling corrections
Brian Gough<bjg@network-theory.co.uk>
parents:
8286
diff
changeset
|
1281 Input-output functions. |
| 3294 | 1282 |
| 1283 @item linear-algebra | |
| 1284 Functions for linear algebra. | |
| 1285 | |
| 1286 @item miscellaneous | |
| 1287 Functions that don't really belong anywhere else. | |
| 1288 | |
| 6554 | 1289 @item optimization |
| 1290 Minimization of functions. | |
| 1291 | |
| 1292 @item path | |
| 1293 Functions to manage the directory path Octave uses to find functions. | |
| 1294 | |
| 1295 @item pkg | |
| 1296 Install external packages of functions in Octave. | |
| 1297 | |
| 3294 | 1298 @item plot |
| 6556 | 1299 Functions for displaying and printing two- and three-dimensional graphs. |
| 3294 | 1300 |
| 1301 @item polynomial | |
| 1302 Functions for manipulating polynomials. | |
| 1303 | |
| 1304 @item set | |
| 1305 Functions for creating and manipulating sets of unique values. | |
| 1306 | |
| 1307 @item signal | |
| 1308 Functions for signal processing applications. | |
| 1309 | |
| 6554 | 1310 @item sparse |
| 1311 Functions for handling sparse matrices. | |
| 1312 | |
| 3294 | 1313 @item specfun |
| 1314 Special functions. | |
| 1315 | |
| 1316 @item special-matrix | |
| 1317 Functions that create special matrix forms. | |
| 1318 | |
| 1319 @item startup | |
| 1320 Octave's system-wide startup file. | |
| 1321 | |
| 1322 @item statistics | |
| 1323 Statistical functions. | |
| 1324 | |
| 1325 @item strings | |
| 1326 Miscellaneous string-handling functions. | |
| 1327 | |
| 6554 | 1328 @item testfun |
| 1329 Perform unit tests on other functions. | |
| 1330 | |
| 3294 | 1331 @item time |
| 1332 Functions related to time keeping. | |
| 1333 @end table |