Mercurial > octave-nkf
annotate doc/interpreter/func.txi @ 19074:0850b5212619
doc: Add @nospell macro around proper names in documentation.
* aspell-octave.en.pws: Remove proper names from Octave's custom dictionary.
* doc/interpreter/audio.txi, doc/interpreter/diagperm.txi,
doc/interpreter/diffeq.txi, doc/interpreter/emacs.txi,
doc/interpreter/func.txi, doc/interpreter/geometry.txi,
doc/interpreter/intro.txi, doc/interpreter/linalg.txi,
doc/interpreter/numbers.txi, doc/interpreter/preface.txi,
doc/interpreter/quad.txi, doc/interpreter/sparse.txi,
libinterp/corefcn/colloc.cc, libinterp/corefcn/ellipj.cc,
libinterp/corefcn/gammainc.cc, libinterp/corefcn/hess.cc,
libinterp/corefcn/quadcc.cc, libinterp/corefcn/rand.cc,
libinterp/corefcn/sqrtm.cc, libinterp/dldfcn/ccolamd.cc,
libinterp/dldfcn/colamd.cc, libinterp/dldfcn/dmperm.cc,
libinterp/dldfcn/symrcm.cc, scripts/general/quadgk.m, scripts/general/quadl.m,
scripts/linear-algebra/commutation_matrix.m, scripts/linear-algebra/condest.m,
scripts/linear-algebra/duplication_matrix.m, scripts/linear-algebra/expm.m,
scripts/linear-algebra/housh.m, scripts/linear-algebra/krylov.m,
scripts/linear-algebra/onenormest.m, scripts/linear-algebra/qzhess.m,
scripts/optimization/fminsearch.m, scripts/optimization/glpk.m,
scripts/signal/arch_fit.m, scripts/signal/bartlett.m,
scripts/signal/blackman.m, scripts/signal/diffpara.m,
scripts/signal/durbinlevinson.m, scripts/signal/hamming.m,
scripts/signal/hanning.m, scripts/sparse/eigs.m, scripts/sparse/pcg.m,
scripts/sparse/pcr.m, scripts/specfun/ellipke.m,
scripts/special-matrix/gallery.m, scripts/special-matrix/invhilb.m,
scripts/statistics/base/quantile.m,
scripts/statistics/tests/kruskal_wallis_test.m,
scripts/statistics/tests/manova.m, scripts/statistics/tests/mcnemar_test.m:
Add @nospell macro around proper names in documentation.
| author | Rik <rik@octave.org> |
|---|---|
| date | Thu, 21 Aug 2014 15:57:18 -0700 |
| parents | ff820f92cbb5 |
| children | be8a12acb20a |
| rev | line source |
|---|---|
|
17744
d63878346099
maint: Update copyright notices for release.
John W. Eaton <jwe@octave.org>
parents:
17281
diff
changeset
|
1 @c Copyright (C) 1996-2013 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 | |
|
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
32 * Introduction to Function and Script Files:: |
|
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
33 * Defining Functions:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
34 * Multiple Return Values:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
35 * Variable-length Argument Lists:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
36 * Ignoring Arguments:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
37 * Variable-length Return Lists:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
38 * Returning from a Function:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
39 * Default Arguments:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
40 * Function Files:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
41 * Script Files:: |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
42 * Function Handles Anonymous Functions Inline Functions:: |
| 6549 | 43 * Commands:: |
|
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
44 * Organization of Functions:: |
| 3294 | 45 @end menu |
| 46 | |
|
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
47 @node Introduction to Function and Script Files |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
48 @section Introduction to Function and Script Files |
|
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
49 |
|
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
50 There are seven different things covered in this section. |
|
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
51 @enumerate |
|
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
52 @item |
|
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
53 Typing in a function at the command prompt. |
|
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
54 |
|
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
55 @item |
|
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
56 Storing a group of commands in a file --- called a script file. |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
57 |
|
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
58 @item |
|
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
59 Storing a function in a file---called a function file. |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
60 |
|
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
61 @item |
|
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
62 Subfunctions in function files. |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
63 |
|
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
64 @item |
|
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
65 Multiple functions in one script file. |
|
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
66 |
|
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
67 @item |
|
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
68 Private functions. |
|
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
69 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
70 @item |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
71 Nested functions. |
|
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
72 @end enumerate |
|
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
73 |
|
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
74 Both function files and script files end with an extension of .m, for |
|
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
75 @sc{matlab} compatibility. If you want more than one independent |
|
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
76 functions in a file, it must be a script file (@pxref{Script Files}), |
|
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
77 and to use these functions you must execute the script file before you |
|
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
78 can use the functions that are in the script file. |
|
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
79 |
| 4167 | 80 @node Defining Functions |
| 3294 | 81 @section Defining Functions |
| 82 @cindex @code{function} statement | |
| 83 @cindex @code{endfunction} statement | |
| 84 | |
| 85 In its simplest form, the definition of a function named @var{name} | |
| 86 looks like this: | |
| 87 | |
| 88 @example | |
| 89 @group | |
| 90 function @var{name} | |
| 91 @var{body} | |
| 92 endfunction | |
| 93 @end group | |
| 94 @end example | |
| 95 | |
| 96 @noindent | |
| 97 A valid function name is like a valid variable name: a sequence of | |
| 98 letters, digits and underscores, not starting with a digit. Functions | |
| 99 share the same pool of names as variables. | |
| 100 | |
| 101 The function @var{body} consists of Octave statements. It is the | |
| 102 most important part of the definition, because it says what the function | |
| 103 should actually @emph{do}. | |
| 104 | |
| 105 For example, here is a function that, when executed, will ring the bell | |
| 106 on your terminal (assuming that it is possible to do so): | |
| 107 | |
| 108 @example | |
| 109 @group | |
| 110 function wakeup | |
| 111 printf ("\a"); | |
| 112 endfunction | |
| 113 @end group | |
| 114 @end example | |
| 115 | |
| 116 The @code{printf} statement (@pxref{Input and Output}) simply tells | |
|
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
17152
diff
changeset
|
117 Octave to print the string @qcode{"\a"}. The special character @samp{\a} |
| 3294 | 118 stands for the alert character (ASCII 7). @xref{Strings}. |
| 119 | |
| 120 Once this function is defined, you can ask Octave to evaluate it by | |
| 121 typing the name of the function. | |
| 122 | |
| 123 Normally, you will want to pass some information to the functions you | |
| 124 define. The syntax for passing parameters to a function in Octave is | |
| 125 | |
| 126 @example | |
| 127 @group | |
| 128 function @var{name} (@var{arg-list}) | |
| 129 @var{body} | |
| 130 endfunction | |
| 131 @end group | |
| 132 @end example | |
| 133 | |
| 134 @noindent | |
| 135 where @var{arg-list} is a comma-separated list of the function's | |
| 136 arguments. When the function is called, the argument names are used to | |
| 137 hold the argument values given in the call. The list of arguments may | |
| 138 be empty, in which case this form is equivalent to the one shown above. | |
| 139 | |
| 140 To print a message along with ringing the bell, you might modify the | |
| 6510 | 141 @code{wakeup} to look like this: |
| 3294 | 142 |
| 143 @example | |
| 144 @group | |
| 145 function wakeup (message) | |
| 146 printf ("\a%s\n", message); | |
| 147 endfunction | |
| 148 @end group | |
| 149 @end example | |
| 150 | |
| 151 Calling this function using a statement like this | |
| 152 | |
| 153 @example | |
| 154 wakeup ("Rise and shine!"); | |
| 155 @end example | |
| 156 | |
| 157 @noindent | |
| 158 will cause Octave to ring your terminal's bell and print the message | |
| 159 @samp{Rise and shine!}, followed by a newline character (the @samp{\n} | |
| 160 in the first argument to the @code{printf} statement). | |
| 161 | |
| 162 In most cases, you will also want to get some information back from the | |
| 163 functions you define. Here is the syntax for writing a function that | |
| 164 returns a single value: | |
| 165 | |
| 166 @example | |
| 167 @group | |
| 168 function @var{ret-var} = @var{name} (@var{arg-list}) | |
| 169 @var{body} | |
| 170 endfunction | |
| 171 @end group | |
| 172 @end example | |
| 173 | |
| 174 @noindent | |
| 175 The symbol @var{ret-var} is the name of the variable that will hold the | |
| 176 value to be returned by the function. This variable must be defined | |
| 177 before the end of the function body in order for the function to return | |
| 178 a value. | |
| 179 | |
| 180 Variables used in the body of a function are local to the | |
| 181 function. Variables named in @var{arg-list} and @var{ret-var} are also | |
| 182 local to the function. @xref{Global Variables}, for information about | |
| 183 how to access global variables inside a function. | |
| 184 | |
| 185 For example, here is a function that computes the average of the | |
| 186 elements of a vector: | |
| 187 | |
| 188 @example | |
| 189 @group | |
| 190 function retval = avg (v) | |
| 191 retval = sum (v) / length (v); | |
| 192 endfunction | |
| 193 @end group | |
| 194 @end example | |
| 195 | |
| 196 If we had written @code{avg} like this instead, | |
| 197 | |
| 198 @example | |
| 199 @group | |
| 200 function retval = avg (v) | |
| 4029 | 201 if (isvector (v)) |
| 3294 | 202 retval = sum (v) / length (v); |
| 203 endif | |
| 204 endfunction | |
| 205 @end group | |
| 206 @end example | |
| 207 | |
| 208 @noindent | |
| 209 and then called the function with a matrix instead of a vector as the | |
| 210 argument, Octave would have printed an error message like this: | |
| 211 | |
| 212 @example | |
| 213 @group | |
|
8015
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7984
diff
changeset
|
214 error: value on right hand side of assignment is undefined |
| 3294 | 215 @end group |
| 216 @end example | |
| 217 | |
| 218 @noindent | |
| 219 because the body of the @code{if} statement was never executed, and | |
| 220 @code{retval} was never defined. To prevent obscure errors like this, | |
| 221 it is a good idea to always make sure that the return variables will | |
| 222 always have values, and to produce meaningful error messages when | |
| 223 problems are encountered. For example, @code{avg} could have been | |
| 224 written like this: | |
| 225 | |
| 226 @example | |
| 227 @group | |
| 228 function retval = avg (v) | |
| 229 retval = 0; | |
| 4029 | 230 if (isvector (v)) |
| 3294 | 231 retval = sum (v) / length (v); |
| 232 else | |
| 233 error ("avg: expecting vector argument"); | |
| 234 endif | |
| 235 endfunction | |
| 236 @end group | |
| 237 @end example | |
| 238 | |
| 239 There is still one additional problem with this function. What if it is | |
| 240 called without an argument? Without additional error checking, Octave | |
| 241 will probably print an error message that won't really help you track | |
| 242 down the source of the error. To allow you to catch errors like this, | |
| 243 Octave provides each function with an automatic variable called | |
| 244 @code{nargin}. Each time a function is called, @code{nargin} is | |
| 245 automatically initialized to the number of arguments that have actually | |
| 246 been passed to the function. For example, we might rewrite the | |
| 247 @code{avg} function like this: | |
| 248 | |
| 249 @example | |
| 250 @group | |
| 251 function retval = avg (v) | |
| 252 retval = 0; | |
| 253 if (nargin != 1) | |
| 254 usage ("avg (vector)"); | |
| 255 endif | |
| 4029 | 256 if (isvector (v)) |
| 3294 | 257 retval = sum (v) / length (v); |
| 258 else | |
| 259 error ("avg: expecting vector argument"); | |
| 260 endif | |
| 261 endfunction | |
| 262 @end group | |
| 263 @end example | |
| 264 | |
| 265 Although Octave does not automatically report an error if you call a | |
| 266 function with more arguments than expected, doing so probably indicates | |
| 267 that something is wrong. Octave also does not automatically report an | |
| 268 error if a function is called with too few arguments, but any attempt to | |
| 269 use a variable that has not been given a value will result in an error. | |
| 270 To avoid such problems and to provide useful messages, we check for both | |
| 271 possibilities and issue our own error message. | |
| 272 | |
| 4700 | 273 @DOCSTRING(nargin) |
| 3294 | 274 |
| 6558 | 275 @DOCSTRING(inputname) |
| 276 | |
| 3371 | 277 @DOCSTRING(silent_functions) |
| 3294 | 278 |
| 4167 | 279 @node Multiple Return Values |
| 3294 | 280 @section Multiple Return Values |
| 281 | |
| 282 Unlike many other computer languages, Octave allows you to define | |
| 283 functions that return more than one value. The syntax for defining | |
| 284 functions that return multiple values is | |
| 285 | |
| 286 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
287 @group |
| 3294 | 288 function [@var{ret-list}] = @var{name} (@var{arg-list}) |
| 289 @var{body} | |
| 290 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
291 @end group |
| 3294 | 292 @end example |
| 293 | |
| 294 @noindent | |
| 295 where @var{name}, @var{arg-list}, and @var{body} have the same meaning | |
| 296 as before, and @var{ret-list} is a comma-separated list of variable | |
| 297 names that will hold the values returned from the function. The list of | |
| 298 return values must have at least one element. If @var{ret-list} has | |
| 299 only one element, this form of the @code{function} statement is | |
| 300 equivalent to the form described in the previous section. | |
| 301 | |
| 302 Here is an example of a function that returns two values, the maximum | |
| 303 element of a vector and the index of its first occurrence in the vector. | |
| 304 | |
| 305 @example | |
| 306 @group | |
| 307 function [max, idx] = vmax (v) | |
| 308 idx = 1; | |
| 309 max = v (idx); | |
| 310 for i = 2:length (v) | |
| 311 if (v (i) > max) | |
| 312 max = v (i); | |
| 313 idx = i; | |
| 314 endif | |
| 315 endfor | |
| 316 endfunction | |
| 317 @end group | |
| 318 @end example | |
| 319 | |
| 320 In this particular case, the two values could have been returned as | |
| 321 elements of a single array, but that is not always possible or | |
| 322 convenient. The values to be returned may not have compatible | |
| 323 dimensions, and it is often desirable to give the individual return | |
| 324 values distinct names. | |
| 325 | |
|
13749
62d1f56b0be7
New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12642
diff
changeset
|
326 It is possible to use the @code{nthargout} function to obtain only some |
|
14038
b0cdd60db5e5
doc: Grammarcheck documentation ahead of 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
13852
diff
changeset
|
327 of the return values or several at once in a cell array. |
|
17097
e7a059a9a644
doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer.
Rik <rik@octave.org>
parents:
16772
diff
changeset
|
328 @xref{Cell Array Objects}. |
|
13749
62d1f56b0be7
New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12642
diff
changeset
|
329 |
|
62d1f56b0be7
New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12642
diff
changeset
|
330 @DOCSTRING(nthargout) |
|
62d1f56b0be7
New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12642
diff
changeset
|
331 |
| 3294 | 332 In addition to setting @code{nargin} each time a function is called, |
| 333 Octave also automatically initializes @code{nargout} to the number of | |
| 334 values that are expected to be returned. This allows you to write | |
| 335 functions that behave differently depending on the number of values that | |
| 336 the user of the function has requested. The implicit assignment to the | |
| 337 built-in variable @code{ans} does not figure in the count of output | |
| 338 arguments, so the value of @code{nargout} may be zero. | |
| 339 | |
| 340 The @code{svd} and @code{lu} functions are examples of built-in | |
| 341 functions that behave differently depending on the value of | |
| 342 @code{nargout}. | |
| 343 | |
| 344 It is possible to write functions that only set some return values. For | |
| 345 example, calling the function | |
| 346 | |
| 347 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
348 @group |
| 3294 | 349 function [x, y, z] = f () |
| 350 x = 1; | |
| 351 z = 2; | |
| 352 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
353 @end group |
| 3294 | 354 @end example |
| 355 | |
| 356 @noindent | |
| 357 as | |
| 358 | |
| 359 @example | |
| 360 [a, b, c] = f () | |
| 361 @end example | |
| 362 | |
| 363 @noindent | |
| 364 produces: | |
| 365 | |
| 366 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
367 @group |
| 3294 | 368 a = 1 |
| 369 | |
| 370 b = [](0x0) | |
| 371 | |
| 372 c = 2 | |
|
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 |
| 3294 | 374 @end example |
| 375 | |
| 376 @noindent | |
| 6501 | 377 along with a warning. |
| 3294 | 378 |
| 4700 | 379 @DOCSTRING(nargout) |
| 3294 | 380 |
|
12629
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
381 It is good practice at the head of a function to verify that it has been called |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
382 correctly. In Octave the following idiom is seen frequently |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
383 |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
384 @example |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
385 @group |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
386 if (nargin < min_#_inputs || nargin > max_#_inputs) |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
387 print_usage (); |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
388 endif |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
389 @end group |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
390 @end example |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
391 |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
392 @noindent |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
393 which stops the function execution and prints a message about the correct |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
394 way to call the function whenever the number of inputs is wrong. |
|
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
395 |
|
18038
c404cec84eb4
New function validaattributes to perform input checking for functions.
Carnë Draug <carandraug@octave.org>
parents:
17744
diff
changeset
|
396 @DOCSTRING(validateattributes) |
|
c404cec84eb4
New function validaattributes to perform input checking for functions.
Carnë Draug <carandraug@octave.org>
parents:
17744
diff
changeset
|
397 |
|
13852
e36817e2ee60
New function narginchk
Carnë Draug <carandraug+dev@gmail.com>
parents:
13749
diff
changeset
|
398 For compatibility with @sc{matlab}, @code{nargchk}, @code{narginchk} and |
|
e36817e2ee60
New function narginchk
Carnë Draug <carandraug+dev@gmail.com>
parents:
13749
diff
changeset
|
399 @code{nargoutchk} are available which provide similar error checking. |
|
12629
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
400 |
| 3371 | 401 @DOCSTRING(nargchk) |
| 3294 | 402 |
|
13852
e36817e2ee60
New function narginchk
Carnë Draug <carandraug+dev@gmail.com>
parents:
13749
diff
changeset
|
403 @DOCSTRING(narginchk) |
|
e36817e2ee60
New function narginchk
Carnë Draug <carandraug+dev@gmail.com>
parents:
13749
diff
changeset
|
404 |
|
7984
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
405 @DOCSTRING(nargoutchk) |
|
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
406 |
|
19069
ff820f92cbb5
inputParser: classdef port of @inputParser from Octave Forge general pkg.
Carnë Draug <carandraug@octave.org>
parents:
18537
diff
changeset
|
407 There is also the class @code{inputParser} which can perform extremely |
|
ff820f92cbb5
inputParser: classdef port of @inputParser from Octave Forge general pkg.
Carnë Draug <carandraug@octave.org>
parents:
18537
diff
changeset
|
408 complex input checking for functions. |
|
ff820f92cbb5
inputParser: classdef port of @inputParser from Octave Forge general pkg.
Carnë Draug <carandraug@octave.org>
parents:
18537
diff
changeset
|
409 |
|
ff820f92cbb5
inputParser: classdef port of @inputParser from Octave Forge general pkg.
Carnë Draug <carandraug@octave.org>
parents:
18537
diff
changeset
|
410 @DOCSTRING(inputParser) |
|
ff820f92cbb5
inputParser: classdef port of @inputParser from Octave Forge general pkg.
Carnë Draug <carandraug@octave.org>
parents:
18537
diff
changeset
|
411 |
|
17097
e7a059a9a644
doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer.
Rik <rik@octave.org>
parents:
16772
diff
changeset
|
412 @anchor{XREFvarargin} @anchor{XREFvarargout} |
| 4167 | 413 @node Variable-length Argument Lists |
| 3294 | 414 @section Variable-length Argument Lists |
| 4933 | 415 @cindex variable-length argument lists |
| 8567 | 416 @cindex @code{varargin} |
| 8072 | 417 |
| 6510 | 418 Sometimes the number of input arguments is not known when the function |
| 419 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
|
420 of all its input arguments. For example: |
| 6510 | 421 |
| 422 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
423 @group |
| 6510 | 424 a = smallest (1, 2, 3); |
| 425 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
|
426 @end group |
| 6510 | 427 @end example |
| 428 | |
| 429 @noindent | |
| 430 In this example both @code{a} and @code{b} would be 1. One way to write | |
| 431 the @code{smallest} function is | |
| 432 | |
| 433 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
434 @group |
| 6510 | 435 function val = smallest (arg1, arg2, arg3, arg4, arg5) |
| 436 @var{body} | |
| 437 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
438 @end group |
| 6510 | 439 @end example |
| 440 | |
| 441 @noindent | |
| 442 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
|
443 arguments should be considered. The problem with this approach is |
| 6510 | 444 that it can only handle a limited number of input arguments. |
| 445 | |
|
7588
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
446 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
|
447 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
|
448 number of input arguments. Using @code{varargin} the function |
| 6510 | 449 looks like this |
| 450 | |
| 451 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
452 @group |
| 6510 | 453 function val = smallest (varargin) |
| 454 @var{body} | |
| 455 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
456 @end group |
| 6510 | 457 @end example |
| 458 | |
| 459 @noindent | |
| 460 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
|
461 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
|
462 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
|
463 with cell arrays. The @code{smallest} function can now be defined |
| 6510 | 464 like this |
| 465 | |
| 466 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
467 @group |
| 6510 | 468 function val = smallest (varargin) |
| 469 val = min ([varargin@{:@}]); | |
| 470 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
471 @end group |
| 6510 | 472 @end example |
| 473 | |
| 474 @noindent | |
| 475 This implementation handles any number of input arguments, but it's also | |
| 476 a very simple solution to the problem. | |
| 477 | |
| 478 A slightly more complex example of @code{varargin} is a function | |
| 479 @code{print_arguments} that prints all input arguments. Such a function | |
| 480 can be defined like this | |
| 481 | |
| 482 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
483 @group |
| 6510 | 484 function print_arguments (varargin) |
| 485 for i = 1:length (varargin) | |
| 486 printf ("Input argument %d: ", i); | |
| 487 disp (varargin@{i@}); | |
| 488 endfor | |
| 489 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
490 @end group |
| 6510 | 491 @end example |
| 492 | |
| 493 @noindent | |
| 494 This function produces output like this | |
| 495 | |
| 496 @example | |
| 497 @group | |
| 498 print_arguments (1, "two", 3); | |
| 499 @print{} Input argument 1: 1 | |
| 500 @print{} Input argument 2: two | |
| 501 @print{} Input argument 3: 3 | |
| 502 @end group | |
| 503 @end example | |
| 3294 | 504 |
| 6558 | 505 @DOCSTRING(parseparams) |
| 506 | |
|
10209
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
507 @node Ignoring Arguments |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
508 @section Ignoring Arguments |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
509 |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
510 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
|
511 @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
|
512 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
|
513 |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
514 @example |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
515 @group |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
516 function val = pick2nd (~, arg2) |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
517 val = arg2; |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
518 endfunction |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
519 @end group |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
520 @end example |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
521 |
|
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
522 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
|
523 |
|
12592
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
524 Return arguments can also be ignored using the same syntax. Functions may |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
525 take advantage of ignored outputs to reduce the number of calculations |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
526 performed. To do so, use the @code{isargout} function to query whether the |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
527 output argument is wanted. For example: |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
528 |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
529 @example |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
530 @group |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
531 function [out1, out2] = long_function (x, y, z) |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
532 if (isargout (1)) |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
533 ## Long calculation |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
534 @dots{} |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
535 out1 = result; |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
536 endif |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
537 @dots{} |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
538 endfunction |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
539 @end group |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
540 @end example |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
541 |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
542 @DOCSTRING(isargout) |
|
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
543 |
| 4167 | 544 @node Variable-length Return Lists |
| 3294 | 545 @section Variable-length Return Lists |
| 4933 | 546 @cindex variable-length return lists |
| 8567 | 547 @cindex @code{varargout} |
| 8072 | 548 |
| 6510 | 549 It is possible to return a variable number of output arguments from a |
| 550 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
|
551 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
|
552 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
|
553 @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
|
554 a cell array that will contain the requested output arguments. |
| 6510 | 555 |
| 556 As an example the following function sets the first output argument to | |
| 557 1, the second to 2, and so on. | |
| 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 varargout = one_to_n () |
| 562 for i = 1:nargout | |
| 563 varargout@{i@} = i; | |
| 564 endfor | |
| 565 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
566 @end group |
| 6510 | 567 @end example |
| 568 | |
| 569 @noindent | |
| 570 When called this function returns values like this | |
| 571 | |
| 572 @example | |
| 573 @group | |
| 574 [a, b, c] = one_to_n () | |
| 575 @result{} a = 1 | |
| 576 @result{} b = 2 | |
| 577 @result{} c = 3 | |
| 578 @end group | |
| 579 @end example | |
| 3294 | 580 |
|
7588
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
581 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
|
582 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
|
583 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
|
584 |
| 6558 | 585 @DOCSTRING(deal) |
| 586 | |
|
11255
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
587 @node Returning from a Function |
|
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
588 @section Returning from a Function |
| 3294 | 589 |
| 590 The body of a user-defined function can contain a @code{return} statement. | |
| 591 This statement returns control to the rest of the Octave program. It | |
| 592 looks like this: | |
| 593 | |
| 594 @example | |
| 595 return | |
| 596 @end example | |
| 597 | |
| 598 Unlike the @code{return} statement in C, Octave's @code{return} | |
| 599 statement cannot be used to return a value from a function. Instead, | |
| 600 you must assign values to the list of return variables that are part of | |
| 601 the @code{function} statement. The @code{return} statement simply makes | |
| 602 it easier to exit a function from a deeply nested loop or conditional | |
| 603 statement. | |
| 604 | |
| 605 Here is an example of a function that checks to see if any elements of a | |
| 606 vector are nonzero. | |
| 607 | |
| 608 @example | |
| 609 @group | |
| 610 function retval = any_nonzero (v) | |
| 611 retval = 0; | |
| 612 for i = 1:length (v) | |
| 613 if (v (i) != 0) | |
| 614 retval = 1; | |
| 615 return; | |
| 616 endif | |
| 617 endfor | |
| 618 printf ("no nonzero elements found\n"); | |
| 619 endfunction | |
| 620 @end group | |
| 621 @end example | |
| 622 | |
| 623 Note that this function could not have been written using the | |
| 624 @code{break} statement to exit the loop once a nonzero value is found | |
| 625 without adding extra logic to avoid printing the message if the vector | |
| 626 does contain a nonzero element. | |
| 627 | |
| 11547 | 628 @deftypefn {Keyword} {} return |
| 3294 | 629 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
|
630 script, it returns control to the caller immediately. At the top level, |
| 3294 | 631 the return statement is ignored. A @code{return} statement is assumed |
| 632 at the end of every function definition. | |
| 11547 | 633 @end deftypefn |
| 3294 | 634 |
| 6510 | 635 @node Default Arguments |
| 636 @section Default Arguments | |
| 637 @cindex default arguments | |
| 638 | |
| 639 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
|
640 to assign default values to some input arguments. When an input argument |
| 6510 | 641 is declared in the argument list it is possible to assign a default |
| 642 value to the argument like this | |
| 643 | |
| 644 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
645 @group |
| 6510 | 646 function @var{name} (@var{arg1} = @var{val1}, @dots{}) |
| 647 @var{body} | |
| 648 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
649 @end group |
| 6510 | 650 @end example |
| 651 | |
| 652 @noindent | |
| 653 If no value is assigned to @var{arg1} by the user, it will have the | |
| 654 value @var{val1}. | |
| 655 | |
| 656 As an example, the following function implements a variant of the classic | |
| 657 ``Hello, World'' program. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
658 |
| 6510 | 659 @example |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
660 @group |
| 6510 | 661 function hello (who = "World") |
| 662 printf ("Hello, %s!\n", who); | |
| 663 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
664 @end group |
| 6510 | 665 @end example |
| 666 | |
| 667 @noindent | |
| 668 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
|
669 |
| 6510 | 670 @example |
| 671 @group | |
| 672 hello (); | |
| 673 @print{} Hello, World! | |
| 674 @end group | |
| 675 @end example | |
| 676 | |
| 677 @noindent | |
| 678 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
|
679 |
| 6510 | 680 @example |
| 681 @group | |
| 682 hello ("Beautiful World of Free Software"); | |
| 683 @print{} Hello, Beautiful World of Free Software! | |
| 684 @end group | |
| 685 @end example | |
| 686 | |
| 687 Sometimes it is useful to explicitly tell Octave to use the default value | |
| 688 of an input argument. This can be done writing a @samp{:} as the value | |
| 689 of the input argument when calling the function. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
690 |
| 6510 | 691 @example |
| 692 @group | |
| 693 hello (:); | |
| 694 @print{} Hello, World! | |
| 695 @end group | |
| 696 @end example | |
| 697 | |
| 4167 | 698 @node Function Files |
| 3294 | 699 @section Function Files |
| 700 @cindex function file | |
| 701 | |
| 702 Except for simple one-shot programs, it is not practical to have to | |
| 703 define all the functions you need each time you need them. Instead, you | |
| 704 will normally want to save them in a file so that you can easily edit | |
| 705 them, and save them for use at a later time. | |
| 706 | |
| 707 Octave does not require you to load function definitions from files | |
| 708 before using them. You simply need to put the function definitions in a | |
| 709 place where Octave can find them. | |
| 710 | |
| 711 When Octave encounters an identifier that is undefined, it first looks | |
| 712 for variables or functions that are already compiled and currently | |
| 713 listed in its symbol table. If it fails to find a definition there, it | |
| 6556 | 714 searches a list of directories (the @dfn{path}) for files ending in |
| 6554 | 715 @file{.m} that have the same base name as the undefined |
| 716 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
|
717 with @sc{matlab}.} Once Octave finds a file with a name that matches, |
| 6554 | 718 the contents of the file are read. If it defines a @emph{single} |
| 719 function, it is compiled and executed. @xref{Script Files}, for more | |
| 720 information about how you can define more than one function in a single | |
| 721 file. | |
| 3294 | 722 |
| 723 When Octave defines a function from a function file, it saves the full | |
| 6554 | 724 name of the file it read and the time stamp on the file. If the time |
| 725 stamp on the file changes, Octave may reload the file. When Octave is | |
| 726 running interactively, time stamp checking normally happens at most once | |
| 727 each time Octave prints the prompt. Searching for new function | |
| 728 definitions also occurs if the current working directory changes. | |
| 3294 | 729 |
| 730 Checking the time stamp allows you to edit the definition of a function | |
| 731 while Octave is running, and automatically use the new function | |
| 6554 | 732 definition without having to restart your Octave session. |
| 3294 | 733 |
| 734 To avoid degrading performance unnecessarily by checking the time stamps | |
| 735 on functions that are not likely to change, Octave assumes that function | |
| 736 files in the directory tree | |
| 737 @file{@var{octave-home}/share/octave/@var{version}/m} | |
| 738 will not change, so it doesn't have to check their time stamps every time the | |
| 739 functions defined in those files are used. This is normally a very good | |
| 740 assumption and provides a significant improvement in performance for the | |
| 741 function files that are distributed with Octave. | |
| 742 | |
| 743 If you know that your own function files will not change while you are | |
| 6554 | 744 running Octave, you can improve performance by calling |
| 745 @code{ignore_function_time_stamp ("all")}, so that Octave will | |
| 746 ignore the time stamps for all function files. Passing | |
|
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
17152
diff
changeset
|
747 @qcode{"system"} to this function resets the default behavior. |
| 3294 | 748 |
| 5775 | 749 @c FIXME -- note about time stamps on files in NFS environments? |
| 3294 | 750 |
|
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
751 @DOCSTRING(edit) |
|
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
752 |
| 6549 | 753 @DOCSTRING(mfilename) |
| 754 | |
| 6638 | 755 @DOCSTRING(ignore_function_time_stamp) |
| 756 | |
| 757 @menu | |
|
11255
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
758 * Manipulating the Load Path:: |
| 6638 | 759 * Subfunctions:: |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
760 * Private Functions:: |
|
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
761 * Nested Functions:: |
| 6638 | 762 * Overloading and Autoloading:: |
| 763 * Function Locking:: | |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
764 * Function Precedence:: |
| 6638 | 765 @end menu |
| 766 | |
|
11257
8d4c57258523
fix some menu problems in the manual
John W. Eaton <jwe@octave.org>
parents:
11255
diff
changeset
|
767 @node Manipulating the Load Path |
|
8d4c57258523
fix some menu problems in the manual
John W. Eaton <jwe@octave.org>
parents:
11255
diff
changeset
|
768 @subsection Manipulating the Load Path |
| 6638 | 769 |
| 8828 | 770 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
|
771 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
|
772 is known as the load path. By default the load path contains |
| 6638 | 773 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
|
774 working directory. To see your current load path call the @code{path} |
| 6638 | 775 function without any input or output arguments. |
| 776 | |
| 777 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
|
778 using @code{addpath} and @code{rmpath}. As an example, the following |
| 6638 | 779 code adds @samp{~/Octave} to the load path. |
| 780 | |
| 781 @example | |
|
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14851
diff
changeset
|
782 addpath ("~/Octave") |
| 6638 | 783 @end example |
| 784 | |
| 785 @noindent | |
| 786 After this the directory @samp{~/Octave} will be searched for functions. | |
| 787 | |
| 6502 | 788 @DOCSTRING(addpath) |
| 789 | |
| 790 @DOCSTRING(genpath) | |
| 791 | |
| 792 @DOCSTRING(rmpath) | |
| 793 | |
| 794 @DOCSTRING(savepath) | |
| 795 | |
| 6477 | 796 @DOCSTRING(path) |
| 3294 | 797 |
| 6502 | 798 @DOCSTRING(pathdef) |
| 799 | |
| 800 @DOCSTRING(pathsep) | |
| 801 | |
| 3428 | 802 @DOCSTRING(rehash) |
| 803 | |
| 804 @DOCSTRING(file_in_loadpath) | |
| 805 | |
|
7638
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7588
diff
changeset
|
806 @DOCSTRING(restoredefaultpath) |
|
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7588
diff
changeset
|
807 |
|
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
808 @DOCSTRING(command_line_path) |
|
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
809 |
|
18109
2217bc116aa9
maint: Dummy merge with gui-release, ignoring all recent backout merges
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
18104
diff
changeset
|
810 @DOCSTRING(dir_in_loadpath) |
|
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
811 |
| 6556 | 812 @node Subfunctions |
| 813 @subsection Subfunctions | |
| 814 | |
| 815 A function file may contain secondary functions called | |
| 816 @dfn{subfunctions}. These secondary functions are only visible to the | |
| 817 other functions in the same function file. For example, a file | |
| 818 @file{f.m} containing | |
| 819 | |
| 820 @example | |
| 821 @group | |
| 822 function f () | |
| 823 printf ("in f, calling g\n"); | |
| 824 g () | |
| 825 endfunction | |
| 826 function g () | |
| 827 printf ("in g, calling h\n"); | |
| 6638 | 828 h () |
| 6556 | 829 endfunction |
| 830 function h () | |
| 831 printf ("in h\n") | |
| 832 endfunction | |
| 833 @end group | |
| 834 @end example | |
| 835 | |
| 836 @noindent | |
| 837 defines a main function @code{f} and two subfunctions. The | |
| 838 subfunctions @code{g} and @code{h} may only be called from the main | |
| 839 function @code{f} or from the other subfunctions, but not from outside | |
| 840 the file @file{f.m}. | |
| 841 | |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
842 @node Private Functions |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
843 @subsection Private Functions |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
844 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
845 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
|
846 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
|
847 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
|
848 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
|
849 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
|
850 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
|
851 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
|
852 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
853 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
|
854 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
|
855 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
856 @example |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
857 @group |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
858 function y = func1 (x) |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
859 y = func2 (x); |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
860 endfunction |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
861 @end group |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
862 @end example |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
863 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
864 @noindent |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
865 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
|
866 @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
|
867 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
|
868 @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
|
869 |
|
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
870 @node Nested Functions |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
871 @subsection Nested Functions |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
872 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
873 Nested functions are similar to subfunctions in that only the main function is |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
874 visible outside the file. However, they also allow for child functions to |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
875 access the local variables in their parent function. This shared access mimics |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
876 using a global variable to share information --- but a global variable which is |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
877 not visible to the rest of Octave. As a programming strategy, sharing data |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
878 this way can create code which is difficult to maintain. It is recommended to |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
879 use subfunctions in place of nested functions when possible. |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
880 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
881 As a simple example, consider a parent function @code{foo}, that calls a nested |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
882 child function @code{bar}, with a shared variable @var{x}. |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
883 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
884 @example |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
885 @group |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
886 function y = foo () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
887 x = 10; |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
888 bar (); |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
889 y = x; |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
890 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
891 function bar () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
892 x = 20; |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
893 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
894 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
895 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
896 foo () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
897 @result{} 20 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
898 @end group |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
899 @end example |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
900 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
901 @noindent |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
902 Notice that there is no special syntax for sharing @var{x}. This can lead to |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
903 problems with accidental variable sharing between a parent function and its |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
904 child. While normally variables are inherited, child function parameters and |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
905 return values are local to the child function. |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
906 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
907 Now consider the function @code{foobar} that uses variables @var{x} and |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
908 @var{y}. @code{foobar} calls a nested function @code{foo} which takes |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
909 @var{x} as a parameter and returns @var{y}. @code{foo} then calls @code{bat} |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
910 which does some computation. |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
911 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
912 @example |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
913 @group |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
914 function z = foobar () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
915 x = 0; |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
916 y = 0; |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
917 z = foo (5); |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
918 z += x + y; |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
919 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
920 function y = foo (x) |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
921 y = x + bat (); |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
922 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
923 function z = bat () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
924 z = x; |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
925 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
926 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
927 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
928 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
929 foobar () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
930 @result{} 10 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
931 @end group |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
932 @end example |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
933 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
934 @noindent |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
935 It is important to note that the @var{x} and @var{y} in @code{foobar} remain |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
936 zero, as in @code{foo} they are a return value and parameter respectively. The |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
937 @var{x} in @code{bat} refers to the @var{x} in @code{foo}. |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
938 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
939 Variable inheritance leads to a problem for @code{eval} and scripts. If a |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
940 new variable is created in a parent function, it is not clear what should happen |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
941 in nested child functions. For example, consider a parent function @code{foo} |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
942 with a nested child function @code{bar}: |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
943 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
944 @example |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
945 @group |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
946 function y = foo (to_eval) |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
947 bar (); |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
948 eval (to_eval); |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
949 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
950 function bar () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
951 eval ("x = 100;"); |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
952 eval ("y = x;"); |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
953 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
954 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
955 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
956 foo ("x = 5;") |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
957 @result{} error: can not add variable "x" to a static workspace |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
958 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
959 foo ("y = 10;") |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
960 @result{} 10 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
961 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
962 foo ("") |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
963 @result{} 100 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
964 @end group |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
965 @end example |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
966 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
967 @noindent |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
968 The parent function @code{foo} is unable to create a new variable |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
969 @var{x}, but the child function @code{bar} was successful. Furthermore, even |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
970 in an @code{eval} statement @var{y} in @code{bar} is the same @var{y} as in its |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
971 parent function @code{foo}. The use of @code{eval} in conjunction with nested |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
972 functions is best avoided. |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
973 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
974 As with subfunctions, only the first nested function in a file may be called |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
975 from the outside. Inside a function the rules are more complicated. In |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
976 general a nested function may call: |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
977 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
978 @enumerate 0 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
979 @item |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
980 Globally visible functions |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
981 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
982 @item |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
983 Any function that the nested function's parent can call |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
984 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
985 @item |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
986 Sibling functions (functions that have the same parents) |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
987 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
988 @item |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
989 Direct children |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
990 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
991 @end enumerate |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
992 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
993 As a complex example consider a parent function @code{ex_top} with two |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
994 child functions, @code{ex_a} and @code{ex_b}. In addition, @code{ex_a} has two |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
995 more child functions, @code{ex_aa} and @code{ex_ab}. For example: |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
996 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
997 @example |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
998 function ex_top () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
999 ## Can call: ex_top, ex_a, and ex_b |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1000 ## Can NOT call: ex_aa and ex_ab |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1001 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1002 function ex_a () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1003 ## Call call everything |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1004 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1005 function ex_aa () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1006 ## Can call everything |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1007 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1008 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1009 function ex_ab () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1010 ## Can call everything |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1011 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1012 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1013 |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1014 function ex_b () |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1015 ## Can call: ex_top, ex_a, and ex_b |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1016 ## Can NOT call: ex_aa and ex_ab |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1017 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1018 endfunction |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1019 @end example |
|
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1020 |
| 6635 | 1021 @node Overloading and Autoloading |
| 1022 @subsection Overloading and Autoloading | |
| 1023 | |
|
11396
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
1024 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
|
1025 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
|
1026 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
|
1027 functions is through classes and object oriented programming |
|
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
1028 (@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
|
1029 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
|
1030 type. The @code{builtin} function exists for this purpose. |
| 6635 | 1031 |
| 1032 @DOCSTRING(builtin) | |
| 1033 | |
| 1034 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
|
1035 functions. However, as Octave searches for functions based on the |
| 6635 | 1036 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
|
1037 functions in the dynamically linked file. On operating systems that |
| 6635 | 1038 support symbolic links, it is possible to create a symbolic link to the |
| 1039 original file for each of the functions which it contains. | |
| 1040 | |
| 1041 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
|
1042 support symbolic links. Making copies of the original file for each of |
| 8828 | 1043 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
|
1044 amount of disk space used by Octave. Instead Octave supplies the |
| 6635 | 1045 @code{autoload} function, that permits the user to define in which |
| 1046 file a certain function will be found. | |
| 1047 | |
| 1048 @DOCSTRING(autoload) | |
| 1049 | |
| 1050 @node Function Locking | |
| 1051 @subsection Function Locking | |
| 1052 | |
| 1053 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
|
1054 @code{mlock} function. This is typically used for dynamically linked |
| 6899 | 1055 functions in Oct-files or mex-files that contain some initialization, |
| 1056 and it is desirable that calling @code{clear} does not remove this | |
| 6635 | 1057 initialization. |
| 1058 | |
| 6899 | 1059 As an example, |
| 1060 | |
| 1061 @example | |
|
18491
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1062 @group |
|
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1063 function my_function () |
|
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1064 mlock (); |
|
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1065 @dots{} |
|
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1066 @end group |
| 6899 | 1067 @end example |
| 1068 | |
| 1069 @noindent | |
|
18491
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1070 prevents @code{my_function} from being removed from memory after it is |
|
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1071 called, even if @code{clear} is called. It is possible to determine if |
|
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1072 a function is locked into memory with the @code{mislocked}, and to unlock |
|
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1073 a function with @code{munlock}, which the following illustrates. |
| 6899 | 1074 |
| 1075 @example | |
| 1076 @group | |
|
18491
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1077 my_function (); |
| 6899 | 1078 mislocked ("my_function") |
| 1079 @result{} ans = 1 | |
| 1080 munlock ("my_function"); | |
| 1081 mislocked ("my_function") | |
| 1082 @result{} ans = 0 | |
| 1083 @end group | |
| 1084 @end example | |
| 1085 | |
| 1086 A common use of @code{mlock} is to prevent persistent variables from | |
| 8828 | 1087 being removed from memory, as the following example shows: |
| 6899 | 1088 |
| 1089 @example | |
| 1090 @group | |
|
14846
460a3c6d8bf1
maint: Use Octave coding convention for cuddled parenthis in function calls with empty argument lists.
Rik <octave@nomad.inbox5.com>
parents:
14442
diff
changeset
|
1091 function count_calls () |
|
18491
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1092 mlock (); |
| 6899 | 1093 persistent calls = 0; |
| 7031 | 1094 printf ("'count_calls' has been called %d times\n", |
| 1095 ++calls); | |
| 6899 | 1096 endfunction |
| 1097 | |
| 1098 count_calls (); | |
| 1099 @print{} 'count_calls' has been called 1 times | |
| 1100 | |
| 1101 clear count_calls | |
| 1102 count_calls (); | |
| 1103 @print{} 'count_calls' has been called 2 times | |
| 1104 @end group | |
| 1105 @end example | |
| 1106 | |
| 1107 @code{mlock} might equally be used to prevent changes to a function from having | |
| 6635 | 1108 effect in Octave, though a similar effect can be had with the |
| 1109 @code{ignore_function_time_stamp} function. | |
| 1110 | |
| 1111 @DOCSTRING(mlock) | |
| 1112 | |
| 1113 @DOCSTRING(munlock) | |
| 1114 | |
| 1115 @DOCSTRING(mislocked) | |
| 1116 | |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1117 @node Function Precedence |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1118 @subsection Function Precedence |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1119 |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1120 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
|
1121 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
|
1122 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
|
1123 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
|
1124 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1125 @enumerate 1 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1126 @item Subfunction |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1127 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
|
1128 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1129 @item Private function |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1130 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
|
1131 which contains the current function. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1132 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1133 @item Class constructor |
|
19074
0850b5212619
doc: Add @nospell macro around proper names in documentation.
Rik <rik@octave.org>
parents:
19069
diff
changeset
|
1134 A function that constructs a user class as defined in chapter |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1135 @ref{Object Oriented Programming}. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1136 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1137 @item Class method |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1138 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
|
1139 @ref{Object Oriented Programming}. |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1140 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1141 @item Command-line Function |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1142 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
|
1143 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1144 @item Autoload function |
|
17097
e7a059a9a644
doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer.
Rik <rik@octave.org>
parents:
16772
diff
changeset
|
1145 A function that is marked as autoloaded with @xref{XREFautoload,,autoload}. |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1146 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1147 @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
|
1148 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
|
1149 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
|
1150 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
|
1151 |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1152 @item Built-in function |
|
18534
f51c1498b9f3
doc: Replace "builtin" with "built-in" for consistency and correctness.
Rik <rik@octave.org>
parents:
18491
diff
changeset
|
1153 A function that is a part of core Octave such as @code{numel}, @code{size}, |
|
f51c1498b9f3
doc: Replace "builtin" with "built-in" for consistency and correctness.
Rik <rik@octave.org>
parents:
18491
diff
changeset
|
1154 etc. |
|
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1155 @end enumerate |
|
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1156 |
| 4167 | 1157 @node Script Files |
| 3294 | 1158 @section Script Files |
| 1159 | |
| 1160 A script file is a file containing (almost) any sequence of Octave | |
| 1161 commands. It is read and evaluated just as if you had typed each | |
| 1162 command at the Octave prompt, and provides a convenient way to perform a | |
| 1163 sequence of commands that do not logically belong inside a function. | |
| 1164 | |
| 1165 Unlike a function file, a script file must @emph{not} begin with the | |
| 1166 keyword @code{function}. If it does, Octave will assume that it is a | |
| 1167 function file, and that it defines a single function that should be | |
| 1168 evaluated as soon as it is defined. | |
| 1169 | |
| 1170 A script file also differs from a function file in that the variables | |
| 1171 named in a script file are not local variables, but are in the same | |
| 1172 scope as the other variables that are visible on the command line. | |
| 1173 | |
| 1174 Even though a script file may not begin with the @code{function} | |
| 1175 keyword, it is possible to define more than one function in a single | |
| 1176 script file and load (but not execute) all of them at once. To do | |
| 1177 this, the first token in the file (ignoring comments and other white | |
| 1178 space) must be something other than @code{function}. If you have no | |
| 1179 other statements to evaluate, you can use a statement that has no | |
| 1180 effect, like this: | |
| 1181 | |
| 1182 @example | |
| 1183 @group | |
| 1184 # Prevent Octave from thinking that this | |
| 1185 # is a function file: | |
| 1186 | |
| 1187 1; | |
| 1188 | |
| 1189 # Define function one: | |
| 1190 | |
| 1191 function one () | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1192 @dots{} |
| 3294 | 1193 @end group |
| 1194 @end example | |
| 1195 | |
| 1196 To have Octave read and compile these functions into an internal form, | |
| 6638 | 1197 you need to make sure that the file is in Octave's load path |
| 6477 | 1198 (accessible through the @code{path} function), then simply type the |
| 1199 base name of the file that contains the commands. (Octave uses the | |
| 1200 same rules to search for script files as it does to search for | |
| 1201 function files.) | |
| 3294 | 1202 |
| 1203 If the first token in a file (ignoring comments) is @code{function}, | |
| 1204 Octave will compile the function and try to execute it, printing a | |
| 1205 message warning about any non-whitespace characters that appear after | |
| 1206 the function definition. | |
| 1207 | |
| 1208 Note that Octave does not try to look up the definition of any identifier | |
| 1209 until it needs to evaluate it. This means that Octave will compile the | |
| 1210 following statements if they appear in a script file, or are typed at | |
| 1211 the command line, | |
| 1212 | |
| 1213 @example | |
| 1214 @group | |
| 1215 # not a function file: | |
| 1216 1; | |
| 1217 function foo () | |
| 1218 do_something (); | |
| 1219 endfunction | |
| 1220 function do_something () | |
| 1221 do_something_else (); | |
| 1222 endfunction | |
| 1223 @end group | |
| 1224 @end example | |
| 1225 | |
| 1226 @noindent | |
| 1227 even though the function @code{do_something} is not defined before it is | |
| 1228 referenced in the function @code{foo}. This is not an error because | |
| 1229 Octave does not need to resolve all symbols that are referenced by a | |
| 1230 function until the function is actually evaluated. | |
| 1231 | |
| 1232 Since Octave doesn't look for definitions until they are needed, the | |
| 1233 following code will always print @samp{bar = 3} whether it is typed | |
| 1234 directly on the command line, read from a script file, or is part of a | |
| 1235 function body, even if there is a function or script file called | |
| 6477 | 1236 @file{bar.m} in Octave's path. |
| 3294 | 1237 |
| 1238 @example | |
| 1239 @group | |
| 1240 eval ("bar = 3"); | |
| 1241 bar | |
| 1242 @end group | |
| 1243 @end example | |
| 1244 | |
| 1245 Code like this appearing within a function body could fool Octave if | |
| 1246 definitions were resolved as the function was being compiled. It would | |
| 1247 be virtually impossible to make Octave clever enough to evaluate this | |
| 1248 code in a consistent fashion. The parser would have to be able to | |
| 1249 perform the call to @code{eval} at compile time, and that would be | |
| 1250 impossible unless all the references in the string to be evaluated could | |
| 1251 also be resolved, and requiring that would be too restrictive (the | |
| 1252 string might come from user input, or depend on things that are not | |
| 1253 known until the function is evaluated). | |
| 1254 | |
| 1255 Although Octave normally executes commands from script files that have | |
| 1256 the name @file{@var{file}.m}, you can use the function @code{source} to | |
| 1257 execute commands from any file. | |
| 1258 | |
| 3371 | 1259 @DOCSTRING(source) |
| 3294 | 1260 |
|
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
1261 @node Function Handles Anonymous Functions Inline Functions |
|
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
1262 @section Function Handles, Anonymous Functions, Inline Functions |
| 4933 | 1263 @cindex handle, function handles |
|
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
1264 @cindex anonymous functions |
| 4933 | 1265 @cindex inline, inline functions |
| 1266 | |
| 6638 | 1267 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
|
1268 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
|
1269 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
|
1270 should be minimized. |
| 4933 | 1271 |
| 1272 @menu | |
| 1273 * Function Handles:: | |
| 6554 | 1274 * Anonymous Functions:: |
| 4933 | 1275 * Inline Functions:: |
| 1276 @end menu | |
| 1277 | |
| 1278 @node Function Handles | |
| 1279 @subsection Function Handles | |
| 1280 | |
| 6554 | 1281 A function handle is a pointer to another function and is defined with |
| 1282 the syntax | |
| 1283 | |
| 1284 @example | |
| 1285 @@@var{function-name} | |
| 1286 @end example | |
| 1287 | |
| 1288 @noindent | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
1289 For example, |
| 6554 | 1290 |
| 1291 @example | |
| 6556 | 1292 f = @@sin; |
| 6554 | 1293 @end example |
| 1294 | |
| 1295 @noindent | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
1296 creates a function handle called @code{f} that refers to the |
| 6554 | 1297 function @code{sin}. |
| 1298 | |
| 1299 Function handles are used to call other functions indirectly, or to pass | |
| 1300 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
|
1301 @code{fsolve}. For example: |
| 6554 | 1302 |
| 1303 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1304 @group |
| 6556 | 1305 f = @@sin; |
| 6554 | 1306 quad (f, 0, pi) |
| 6929 | 1307 @result{} 2 |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1308 @end group |
| 6554 | 1309 @end example |
| 1310 | |
| 1311 You may use @code{feval} to call a function using function handle, or | |
| 6570 | 1312 simply write the name of the function handle followed by an argument |
| 6554 | 1313 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
|
1314 @samp{()}. For example: |
| 6554 | 1315 |
| 1316 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1317 @group |
| 6556 | 1318 f = @@sin; |
| 6554 | 1319 feval (f, pi/4) |
| 6570 | 1320 @result{} 0.70711 |
| 6554 | 1321 f (pi/4) |
| 6570 | 1322 @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
|
1323 @end group |
| 6554 | 1324 @end example |
| 1325 | |
|
14175
3972c4caa60a
Add new function is_function_handle (patch #7695)
Juan Pablo Carbajal <carbajal@ifi.uzh.ch>
parents:
14138
diff
changeset
|
1326 @DOCSTRING(is_function_handle) |
|
3972c4caa60a
Add new function is_function_handle (patch #7695)
Juan Pablo Carbajal <carbajal@ifi.uzh.ch>
parents:
14138
diff
changeset
|
1327 |
| 4933 | 1328 @DOCSTRING(functions) |
| 1329 | |
| 1330 @DOCSTRING(func2str) | |
| 1331 | |
| 1332 @DOCSTRING(str2func) | |
| 1333 | |
| 6570 | 1334 @node Anonymous Functions |
| 6554 | 1335 @subsection Anonymous Functions |
| 1336 | |
| 1337 Anonymous functions are defined using the syntax | |
| 1338 | |
| 1339 @example | |
| 1340 @@(@var{argument-list}) @var{expression} | |
| 1341 @end example | |
| 1342 | |
| 1343 @noindent | |
| 1344 Any variables that are not found in the argument list are inherited from | |
| 1345 the enclosing scope. Anonymous functions are useful for creating simple | |
| 1346 unnamed functions from expressions or for wrapping calls to other | |
| 1347 functions to adapt them for use by functions like @code{quad}. For | |
| 1348 example, | |
| 1349 | |
| 1350 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1351 @group |
| 6554 | 1352 f = @@(x) x.^2; |
| 1353 quad (f, 0, 10) | |
| 6570 | 1354 @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
|
1355 @end group |
| 6554 | 1356 @end example |
| 1357 | |
| 1358 @noindent | |
| 1359 creates a simple unnamed function from the expression @code{x.^2} and | |
| 1360 passes it to @code{quad}, | |
| 1361 | |
| 1362 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1363 @group |
| 6554 | 1364 quad (@@(x) sin (x), 0, pi) |
| 6933 | 1365 @result{} 2 |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1366 @end group |
| 6554 | 1367 @end example |
| 1368 | |
| 1369 @noindent | |
| 1370 wraps another function, and | |
| 1371 | |
| 1372 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1373 @group |
| 6554 | 1374 a = 1; |
| 1375 b = 2; | |
| 1376 quad (@@(x) betainc (x, a, b), 0, 0.4) | |
| 6929 | 1377 @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
|
1378 @end group |
| 6554 | 1379 @end example |
| 1380 | |
| 1381 @noindent | |
| 1382 adapts a function with several parameters to the form required by | |
| 1383 @code{quad}. In this example, the values of @var{a} and @var{b} that | |
| 1384 are passed to @code{betainc} are inherited from the current | |
| 1385 environment. | |
| 1386 | |
| 4933 | 1387 @node Inline Functions |
| 1388 @subsection Inline Functions | |
| 1389 | |
| 6638 | 1390 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
|
1391 body using the @code{inline} function. The following code defines the |
| 6638 | 1392 function @math{f(x) = x^2 + 2}. |
| 1393 | |
| 1394 @example | |
|
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14851
diff
changeset
|
1395 f = inline ("x^2 + 2"); |
| 6638 | 1396 @end example |
| 1397 | |
| 1398 @noindent | |
| 1399 After this it is possible to evaluate @math{f} at any @math{x} by | |
| 1400 writing @code{f(x)}. | |
| 1401 | |
| 4933 | 1402 @DOCSTRING(inline) |
| 1403 | |
| 1404 @DOCSTRING(argnames) | |
| 1405 | |
| 1406 @DOCSTRING(formula) | |
| 1407 | |
|
7984
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
1408 @DOCSTRING(symvar) |
|
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
1409 |
| 6549 | 1410 @node Commands |
| 1411 @section Commands | |
| 1412 | |
| 6638 | 1413 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
|
1414 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
|
1415 it can also be called without the parentheses. For example, |
| 6638 | 1416 |
| 1417 @example | |
| 1418 my_command hello world | |
| 1419 @end example | |
| 1420 | |
| 1421 @noindent | |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1422 is equivalent to |
| 6638 | 1423 |
| 1424 @example | |
|
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14851
diff
changeset
|
1425 my_command ("hello", "world") |
| 6638 | 1426 @end example |
| 1427 | |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1428 @noindent |
| 6638 | 1429 The general form of a command call is |
| 1430 | |
| 1431 @example | |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1432 @var{cmdname} @var{arg1} @var{arg2} @dots{} |
| 6638 | 1433 @end example |
| 1434 | |
| 1435 @noindent | |
| 1436 which translates directly to | |
| 1437 | |
| 1438 @example | |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1439 @var{cmdname} ("@var{arg1}", "@var{arg2}", @dots{}) |
| 6638 | 1440 @end example |
| 1441 | |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1442 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
|
1443 arguments. For example: |
|
11573
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11547
diff
changeset
|
1444 |
| 6638 | 1445 @example |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1446 @group |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1447 toupper lower_case_arg |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1448 @result{} ans = LOWER_CASE_ARG |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1449 @end group |
| 6638 | 1450 @end example |
| 1451 | |
| 1452 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
|
1453 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
|
1454 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
|
1455 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
|
1456 called as a function. For example: |
| 6549 | 1457 |
|
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1458 @example |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1459 @group |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1460 strvar = "hello world"; |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1461 toupper strvar |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1462 @result{} ans = STRVAR |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1463 toupper (strvar) |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1464 @result{} ans = HELLO WORLD |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1465 @end group |
|
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1466 @end example |
| 6549 | 1467 |
| 1468 | |
| 4167 | 1469 @node Organization of Functions |
| 3294 | 1470 @section Organization of Functions Distributed with Octave |
| 1471 | |
| 1472 Many of Octave's standard functions are distributed as function files. | |
| 1473 They are loosely organized by topic, in subdirectories of | |
| 1474 @file{@var{octave-home}/lib/octave/@var{version}/m}, to make it easier | |
| 1475 to find them. | |
| 1476 | |
| 1477 The following is a list of all the function file subdirectories, and the | |
| 1478 types of functions you will find there. | |
| 1479 | |
| 1480 @table @file | |
| 1481 @item audio | |
| 1482 Functions for playing and recording sounds. | |
| 1483 | |
|
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1484 @item deprecated |
|
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1485 Out-of-date functions which will eventually be removed from Octave. |
| 3294 | 1486 |
| 1487 @item elfun | |
|
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1488 Elementary functions, principally trigonometric. |
| 3294 | 1489 |
|
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1490 @item @@ftp |
|
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1491 Class functions for the FTP object. |
| 6554 | 1492 |
| 3294 | 1493 @item general |
| 1494 Miscellaneous matrix manipulations, like @code{flipud}, @code{rot90}, | |
| 1495 and @code{triu}, as well as other basic functions, like | |
| 4029 | 1496 @code{ismatrix}, @code{nargchk}, etc. |
| 3294 | 1497 |
|
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1498 @item geometry |
|
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1499 Functions related to Delaunay triangulation. |
|
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1500 |
|
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1501 @item help |
|
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1502 Functions for Octave's built-in help system. |
|
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1503 |
| 3294 | 1504 @item image |
| 1505 Image processing tools. These functions require the X Window System. | |
| 1506 | |
| 1507 @item io | |
|
8325
b93ac0586e4b
spelling corrections
Brian Gough<bjg@network-theory.co.uk>
parents:
8286
diff
changeset
|
1508 Input-output functions. |
| 3294 | 1509 |
| 1510 @item linear-algebra | |
| 1511 Functions for linear algebra. | |
| 1512 | |
| 1513 @item miscellaneous | |
| 1514 Functions that don't really belong anywhere else. | |
| 1515 | |
| 6554 | 1516 @item optimization |
|
12642
f96b9b9f141b
doc: Periodic grammarcheck and spellcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
12632
diff
changeset
|
1517 Functions related to minimization, optimization, and root finding. |
| 6554 | 1518 |
| 1519 @item path | |
| 1520 Functions to manage the directory path Octave uses to find functions. | |
| 1521 | |
| 1522 @item pkg | |
|
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1523 Package manager for installing external packages of functions in Octave. |
| 6554 | 1524 |
| 3294 | 1525 @item plot |
| 6556 | 1526 Functions for displaying and printing two- and three-dimensional graphs. |
| 3294 | 1527 |
| 1528 @item polynomial | |
| 1529 Functions for manipulating polynomials. | |
| 1530 | |
|
14133
b25559bd5aaa
doc: Document prefs directory in list of installed script files.
Rik <octave@nomad.inbox5.com>
parents:
14116
diff
changeset
|
1531 @item prefs |
|
b25559bd5aaa
doc: Document prefs directory in list of installed script files.
Rik <octave@nomad.inbox5.com>
parents:
14116
diff
changeset
|
1532 Functions implementing user-defined preferences. |
|
b25559bd5aaa
doc: Document prefs directory in list of installed script files.
Rik <octave@nomad.inbox5.com>
parents:
14116
diff
changeset
|
1533 |
| 3294 | 1534 @item set |
| 1535 Functions for creating and manipulating sets of unique values. | |
| 1536 | |
| 1537 @item signal | |
| 1538 Functions for signal processing applications. | |
| 1539 | |
| 6554 | 1540 @item sparse |
| 1541 Functions for handling sparse matrices. | |
| 1542 | |
| 3294 | 1543 @item specfun |
|
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1544 Special functions such as @code{bessel} or @code{factor}. |
| 3294 | 1545 |
| 1546 @item special-matrix | |
|
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1547 Functions that create special matrix forms such as Hilbert or Vandermonde |
|
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1548 matrices. |
| 3294 | 1549 |
| 1550 @item startup | |
| 1551 Octave's system-wide startup file. | |
| 1552 | |
| 1553 @item statistics | |
| 1554 Statistical functions. | |
| 1555 | |
| 1556 @item strings | |
| 1557 Miscellaneous string-handling functions. | |
| 1558 | |
| 6554 | 1559 @item testfun |
|
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1560 Functions for performing unit tests on other functions. |
| 6554 | 1561 |
| 3294 | 1562 @item time |
|
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1563 Functions related to time and date processing. |
| 3294 | 1564 @end table |