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