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