Mercurial > octave
annotate doc/interpreter/func.txi @ 11902:a79ef0364d2a release-3-0-x
func.txi: remove reference to return_last_computed_value
author | Soren Hauberg <hauberg@gmail.com> |
---|---|
date | Mon, 12 Jan 2009 10:39:42 +0100 |
parents | 3342d1a7c4c9 |
children |
rev | line source |
---|---|
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 |
6510 | 502 @node Default Arguments |
503 @section Default Arguments | |
504 @cindex default arguments | |
505 | |
506 Since Octave supports variable number of input arguments, it is very useful | |
507 to assign default values to some input arguments. When an input argument | |
508 is declared in the argument list it is possible to assign a default | |
509 value to the argument like this | |
510 | |
511 @example | |
512 function @var{name} (@var{arg1} = @var{val1}, @dots{}) | |
513 @var{body} | |
514 endfunction | |
515 @end example | |
516 | |
517 @noindent | |
518 If no value is assigned to @var{arg1} by the user, it will have the | |
519 value @var{val1}. | |
520 | |
521 As an example, the following function implements a variant of the classic | |
522 ``Hello, World'' program. | |
523 @example | |
524 function hello (who = "World") | |
525 printf ("Hello, %s!\n", who); | |
526 endfunction | |
527 @end example | |
528 | |
529 @noindent | |
530 When called without an input argument the function prints the following | |
531 @example | |
532 @group | |
533 hello (); | |
534 @print{} Hello, World! | |
535 @end group | |
536 @end example | |
537 | |
538 @noindent | |
539 and when it's called with an input argument it prints the following | |
540 @example | |
541 @group | |
542 hello ("Beautiful World of Free Software"); | |
543 @print{} Hello, Beautiful World of Free Software! | |
544 @end group | |
545 @end example | |
546 | |
547 Sometimes it is useful to explicitly tell Octave to use the default value | |
548 of an input argument. This can be done writing a @samp{:} as the value | |
549 of the input argument when calling the function. | |
550 @example | |
551 @group | |
552 hello (:); | |
553 @print{} Hello, World! | |
554 @end group | |
555 @end example | |
556 | |
4167 | 557 @node Function Files |
3294 | 558 @section Function Files |
559 @cindex function file | |
560 | |
561 Except for simple one-shot programs, it is not practical to have to | |
562 define all the functions you need each time you need them. Instead, you | |
563 will normally want to save them in a file so that you can easily edit | |
564 them, and save them for use at a later time. | |
565 | |
566 Octave does not require you to load function definitions from files | |
567 before using them. You simply need to put the function definitions in a | |
568 place where Octave can find them. | |
569 | |
570 When Octave encounters an identifier that is undefined, it first looks | |
571 for variables or functions that are already compiled and currently | |
572 listed in its symbol table. If it fails to find a definition there, it | |
6556 | 573 searches a list of directories (the @dfn{path}) for files ending in |
6554 | 574 @file{.m} that have the same base name as the undefined |
575 identifier.@footnote{The @samp{.m} suffix was chosen for compatibility | |
576 with @sc{Matlab}.} Once Octave finds a file with a name that matches, | |
577 the contents of the file are read. If it defines a @emph{single} | |
578 function, it is compiled and executed. @xref{Script Files}, for more | |
579 information about how you can define more than one function in a single | |
580 file. | |
3294 | 581 |
582 When Octave defines a function from a function file, it saves the full | |
6554 | 583 name of the file it read and the time stamp on the file. If the time |
584 stamp on the file changes, Octave may reload the file. When Octave is | |
585 running interactively, time stamp checking normally happens at most once | |
586 each time Octave prints the prompt. Searching for new function | |
587 definitions also occurs if the current working directory changes. | |
3294 | 588 |
589 Checking the time stamp allows you to edit the definition of a function | |
590 while Octave is running, and automatically use the new function | |
6554 | 591 definition without having to restart your Octave session. |
3294 | 592 |
593 To avoid degrading performance unnecessarily by checking the time stamps | |
594 on functions that are not likely to change, Octave assumes that function | |
595 files in the directory tree | |
596 @file{@var{octave-home}/share/octave/@var{version}/m} | |
597 will not change, so it doesn't have to check their time stamps every time the | |
598 functions defined in those files are used. This is normally a very good | |
599 assumption and provides a significant improvement in performance for the | |
600 function files that are distributed with Octave. | |
601 | |
602 If you know that your own function files will not change while you are | |
6554 | 603 running Octave, you can improve performance by calling |
604 @code{ignore_function_time_stamp ("all")}, so that Octave will | |
605 ignore the time stamps for all function files. Passing | |
606 @code{"system"} to this function resets the default behavior. | |
3294 | 607 |
5775 | 608 @c FIXME -- note about time stamps on files in NFS environments? |
3294 | 609 |
6549 | 610 @DOCSTRING(mfilename) |
611 | |
6638 | 612 @DOCSTRING(ignore_function_time_stamp) |
613 | |
614 @menu | |
615 * Manipulating the load path:: | |
616 * Subfunctions:: | |
617 * Overloading and Autoloading:: | |
618 * Function Locking:: | |
619 @end menu | |
620 | |
621 @node Manipulating the load path | |
622 @subsection Manipulating the load path | |
623 | |
624 When a function is called Octave searches a list of directories for | |
625 a file that contains the function declaration. This list of directories | |
626 is known as the load path. By default the load path contains | |
627 a list of directories distributed with Octave plus the current | |
628 working directory. To see your current load path call the @code{path} | |
629 function without any input or output arguments. | |
630 | |
631 It is possible to add or remove directories to or from the load path | |
632 using the @code{addpath} and @code{rmpath}. As an example, the following | |
633 code adds @samp{~/Octave} to the load path. | |
634 | |
635 @example | |
636 addpath("~/Octave") | |
637 @end example | |
638 | |
639 @noindent | |
640 After this the directory @samp{~/Octave} will be searched for functions. | |
641 | |
6502 | 642 @DOCSTRING(addpath) |
643 | |
644 @DOCSTRING(genpath) | |
645 | |
646 @DOCSTRING(rmpath) | |
647 | |
648 @DOCSTRING(savepath) | |
649 | |
6477 | 650 @DOCSTRING(path) |
3294 | 651 |
6502 | 652 @DOCSTRING(pathdef) |
653 | |
654 @DOCSTRING(pathsep) | |
655 | |
3428 | 656 @DOCSTRING(rehash) |
657 | |
658 @DOCSTRING(file_in_loadpath) | |
659 | |
6556 | 660 @node Subfunctions |
661 @subsection Subfunctions | |
662 | |
663 A function file may contain secondary functions called | |
664 @dfn{subfunctions}. These secondary functions are only visible to the | |
665 other functions in the same function file. For example, a file | |
666 @file{f.m} containing | |
667 | |
668 @example | |
669 @group | |
670 function f () | |
671 printf ("in f, calling g\n"); | |
672 g () | |
673 endfunction | |
674 function g () | |
675 printf ("in g, calling h\n"); | |
6638 | 676 h () |
6556 | 677 endfunction |
678 function h () | |
679 printf ("in h\n") | |
680 endfunction | |
681 @end group | |
682 @end example | |
683 | |
684 @noindent | |
685 defines a main function @code{f} and two subfunctions. The | |
686 subfunctions @code{g} and @code{h} may only be called from the main | |
687 function @code{f} or from the other subfunctions, but not from outside | |
688 the file @file{f.m}. | |
689 | |
6635 | 690 @node Overloading and Autoloading |
691 @subsection Overloading and Autoloading | |
692 | |
693 The @code{dispatch} function can be used to alias one function name to | |
694 another. It can be used to alias all calls to a particular function name | |
695 to another function, or the alias can be limited to only a particular | |
696 variable type. Consider the example | |
697 | |
698 @example | |
699 @group | |
700 function y = spsin (x) | |
701 printf ("Calling spsin\n"); | |
702 fflush(stdout); | |
703 y = spfun ("sin", x); | |
704 endfunction | |
705 | |
706 dispatch ("sin", "spsin", "sparse matrix"); | |
707 y0 = sin(eye(3)); | |
708 y1 = sin(speye(3)); | |
709 @end group | |
710 @end example | |
711 | |
712 @noindent | |
713 Which aliases the @code{spsin} to @code{sin}, but only for real sparse | |
714 matrices. Note that the builtin @code{sin} already correctly treats | |
715 sparse matrices and so this example is only illustrative. | |
716 | |
717 @DOCSTRING(dispatch) | |
718 | |
719 @DOCSTRING(builtin) | |
720 | |
721 A single dynamically linked file might define several | |
722 functions. However, as Octave searches for functions based on the | |
723 functions filename, Octave needs a manner in which to find each of the | |
724 functions in the dynamically linked file. On operating systems that | |
725 support symbolic links, it is possible to create a symbolic link to the | |
726 original file for each of the functions which it contains. | |
727 | |
728 However, there is at least one well known operating system that doesn't | |
729 support symbolic links. Making copies of the original file for each of | |
730 the functions is also possible, but is undesirable as it multiples the | |
731 amount of disk space used by Octave. Instead Octave supplies the | |
732 @code{autoload} function, that permits the user to define in which | |
733 file a certain function will be found. | |
734 | |
735 @DOCSTRING(autoload) | |
736 | |
737 @node Function Locking | |
738 @subsection Function Locking | |
739 | |
740 It is sometime desirable to lock a function into memory with the | |
741 @code{mlock} function. This is typically used for dynamically linked | |
6899 | 742 functions in Oct-files or mex-files that contain some initialization, |
743 and it is desirable that calling @code{clear} does not remove this | |
6635 | 744 initialization. |
745 | |
6899 | 746 As an example, |
747 | |
748 @example | |
749 mlock ("my_function"); | |
750 @end example | |
751 | |
752 @noindent | |
753 prevents @code{my_function} from being removed from memory, even if | |
754 @code{clear} is called. It is possible to determine if a function is | |
755 locked into memory with the @code{mislocked}, and to unlock a function | |
756 with @code{munlock}, which the following illustrates. | |
757 | |
758 @example | |
759 @group | |
760 mlock ("my_function"); | |
761 mislocked ("my_function") | |
762 @result{} ans = 1 | |
763 munlock ("my_function"); | |
764 mislocked ("my_function") | |
765 @result{} ans = 0 | |
766 @end group | |
767 @end example | |
768 | |
769 A common use of @code{mlock} is to prevent persistent variables from | |
770 being removed from memory, as the following example shows. | |
771 | |
772 @example | |
773 @group | |
774 function count_calls() | |
775 persistent calls = 0; | |
7031 | 776 printf ("'count_calls' has been called %d times\n", |
777 ++calls); | |
6899 | 778 endfunction |
779 mlock ("count_calls"); | |
780 | |
781 count_calls (); | |
782 @print{} 'count_calls' has been called 1 times | |
783 | |
784 clear count_calls | |
785 count_calls (); | |
786 @print{} 'count_calls' has been called 2 times | |
787 @end group | |
788 @end example | |
789 | |
790 @noindent | |
791 It is, however, often inconvenient to lock a function from the prompt, | |
792 so it is also possible to lock a function from within its body. This | |
793 is simply done by calling @code{mlock} from within the function. | |
794 | |
795 @example | |
796 @group | |
797 function count_calls () | |
798 mlock (); | |
799 persistent calls = 0; | |
7031 | 800 printf ("'count_calls' has been called %d times\n", |
801 ++calls); | |
6899 | 802 endfunction |
803 @end group | |
804 @end example | |
805 | |
806 @code{mlock} might equally be used to prevent changes to a function from having | |
6635 | 807 effect in Octave, though a similar effect can be had with the |
808 @code{ignore_function_time_stamp} function. | |
809 | |
810 @DOCSTRING(mlock) | |
811 | |
812 @DOCSTRING(munlock) | |
813 | |
814 @DOCSTRING(mislocked) | |
815 | |
4167 | 816 @node Script Files |
3294 | 817 @section Script Files |
818 | |
819 A script file is a file containing (almost) any sequence of Octave | |
820 commands. It is read and evaluated just as if you had typed each | |
821 command at the Octave prompt, and provides a convenient way to perform a | |
822 sequence of commands that do not logically belong inside a function. | |
823 | |
824 Unlike a function file, a script file must @emph{not} begin with the | |
825 keyword @code{function}. If it does, Octave will assume that it is a | |
826 function file, and that it defines a single function that should be | |
827 evaluated as soon as it is defined. | |
828 | |
829 A script file also differs from a function file in that the variables | |
830 named in a script file are not local variables, but are in the same | |
831 scope as the other variables that are visible on the command line. | |
832 | |
833 Even though a script file may not begin with the @code{function} | |
834 keyword, it is possible to define more than one function in a single | |
835 script file and load (but not execute) all of them at once. To do | |
836 this, the first token in the file (ignoring comments and other white | |
837 space) must be something other than @code{function}. If you have no | |
838 other statements to evaluate, you can use a statement that has no | |
839 effect, like this: | |
840 | |
841 @example | |
842 @group | |
843 # Prevent Octave from thinking that this | |
844 # is a function file: | |
845 | |
846 1; | |
847 | |
848 # Define function one: | |
849 | |
850 function one () | |
851 ... | |
852 @end group | |
853 @end example | |
854 | |
855 To have Octave read and compile these functions into an internal form, | |
6638 | 856 you need to make sure that the file is in Octave's load path |
6477 | 857 (accessible through the @code{path} function), then simply type the |
858 base name of the file that contains the commands. (Octave uses the | |
859 same rules to search for script files as it does to search for | |
860 function files.) | |
3294 | 861 |
862 If the first token in a file (ignoring comments) is @code{function}, | |
863 Octave will compile the function and try to execute it, printing a | |
864 message warning about any non-whitespace characters that appear after | |
865 the function definition. | |
866 | |
867 Note that Octave does not try to look up the definition of any identifier | |
868 until it needs to evaluate it. This means that Octave will compile the | |
869 following statements if they appear in a script file, or are typed at | |
870 the command line, | |
871 | |
872 @example | |
873 @group | |
874 # not a function file: | |
875 1; | |
876 function foo () | |
877 do_something (); | |
878 endfunction | |
879 function do_something () | |
880 do_something_else (); | |
881 endfunction | |
882 @end group | |
883 @end example | |
884 | |
885 @noindent | |
886 even though the function @code{do_something} is not defined before it is | |
887 referenced in the function @code{foo}. This is not an error because | |
888 Octave does not need to resolve all symbols that are referenced by a | |
889 function until the function is actually evaluated. | |
890 | |
891 Since Octave doesn't look for definitions until they are needed, the | |
892 following code will always print @samp{bar = 3} whether it is typed | |
893 directly on the command line, read from a script file, or is part of a | |
894 function body, even if there is a function or script file called | |
6477 | 895 @file{bar.m} in Octave's path. |
3294 | 896 |
897 @example | |
898 @group | |
899 eval ("bar = 3"); | |
900 bar | |
901 @end group | |
902 @end example | |
903 | |
904 Code like this appearing within a function body could fool Octave if | |
905 definitions were resolved as the function was being compiled. It would | |
906 be virtually impossible to make Octave clever enough to evaluate this | |
907 code in a consistent fashion. The parser would have to be able to | |
908 perform the call to @code{eval} at compile time, and that would be | |
909 impossible unless all the references in the string to be evaluated could | |
910 also be resolved, and requiring that would be too restrictive (the | |
911 string might come from user input, or depend on things that are not | |
912 known until the function is evaluated). | |
913 | |
914 Although Octave normally executes commands from script files that have | |
915 the name @file{@var{file}.m}, you can use the function @code{source} to | |
916 execute commands from any file. | |
917 | |
3371 | 918 @DOCSTRING(source) |
3294 | 919 |
6638 | 920 @node Function Handles Inline Functions and Anonymous Functions |
921 @section Function Handles, Inline Functions, and Anonymous Functions | |
4933 | 922 @cindex handle, function handles |
923 @cindex inline, inline functions | |
6638 | 924 @cindex anonymous functions |
4933 | 925 |
6638 | 926 It can be very convenient store a function in a variable so that it |
927 can be passed to a different function. For example, a function that | |
928 performs numerical minimisation needs access to the function that | |
929 should be minimised. | |
4933 | 930 |
931 @menu | |
932 * Function Handles:: | |
6554 | 933 * Anonymous Functions:: |
4933 | 934 * Inline Functions:: |
935 @end menu | |
936 | |
937 @node Function Handles | |
938 @subsection Function Handles | |
939 | |
6554 | 940 A function handle is a pointer to another function and is defined with |
941 the syntax | |
942 | |
943 @example | |
944 @@@var{function-name} | |
945 @end example | |
946 | |
947 @noindent | |
948 For example | |
949 | |
950 @example | |
6556 | 951 f = @@sin; |
6554 | 952 @end example |
953 | |
954 @noindent | |
6570 | 955 Creates a function handle called @code{f} that refers to the |
6554 | 956 function @code{sin}. |
957 | |
958 Function handles are used to call other functions indirectly, or to pass | |
959 a function as an argument to another function like @code{quad} or | |
960 @code{fsolve}. For example | |
961 | |
962 @example | |
6556 | 963 f = @@sin; |
6554 | 964 quad (f, 0, pi) |
6929 | 965 @result{} 2 |
6554 | 966 @end example |
967 | |
968 You may use @code{feval} to call a function using function handle, or | |
6570 | 969 simply write the name of the function handle followed by an argument |
6554 | 970 list. If there are no arguments, you must use an empty argument list |
971 @samp{()}. For example | |
972 | |
973 @example | |
6556 | 974 f = @@sin; |
6554 | 975 feval (f, pi/4) |
6570 | 976 @result{} 0.70711 |
6554 | 977 f (pi/4) |
6570 | 978 @result{} 0.70711 |
6554 | 979 @end example |
980 | |
4933 | 981 @DOCSTRING(functions) |
982 | |
983 @DOCSTRING(func2str) | |
984 | |
985 @DOCSTRING(str2func) | |
986 | |
6570 | 987 @node Anonymous Functions |
6554 | 988 @subsection Anonymous Functions |
989 | |
990 Anonymous functions are defined using the syntax | |
991 | |
992 @example | |
993 @@(@var{argument-list}) @var{expression} | |
994 @end example | |
995 | |
996 @noindent | |
997 Any variables that are not found in the argument list are inherited from | |
998 the enclosing scope. Anonymous functions are useful for creating simple | |
999 unnamed functions from expressions or for wrapping calls to other | |
1000 functions to adapt them for use by functions like @code{quad}. For | |
1001 example, | |
1002 | |
1003 @example | |
1004 f = @@(x) x.^2; | |
1005 quad (f, 0, 10) | |
6570 | 1006 @result{} 333.33 |
6554 | 1007 @end example |
1008 | |
1009 @noindent | |
1010 creates a simple unnamed function from the expression @code{x.^2} and | |
1011 passes it to @code{quad}, | |
1012 | |
1013 @example | |
1014 quad (@@(x) sin (x), 0, pi) | |
6933 | 1015 @result{} 2 |
6554 | 1016 @end example |
1017 | |
1018 @noindent | |
1019 wraps another function, and | |
1020 | |
1021 @example | |
1022 a = 1; | |
1023 b = 2; | |
1024 quad (@@(x) betainc (x, a, b), 0, 0.4) | |
6929 | 1025 @result{} 0.13867 |
6554 | 1026 @end example |
1027 | |
1028 @noindent | |
1029 adapts a function with several parameters to the form required by | |
1030 @code{quad}. In this example, the values of @var{a} and @var{b} that | |
1031 are passed to @code{betainc} are inherited from the current | |
1032 environment. | |
1033 | |
4933 | 1034 @node Inline Functions |
1035 @subsection Inline Functions | |
1036 | |
6638 | 1037 An inline function is created from a string containing the function |
1038 body using the @code{inline} function. The following code defines the | |
1039 function @math{f(x) = x^2 + 2}. | |
1040 | |
1041 @example | |
1042 f = inline("x^2 + 2"); | |
1043 @end example | |
1044 | |
1045 @noindent | |
1046 After this it is possible to evaluate @math{f} at any @math{x} by | |
1047 writing @code{f(x)}. | |
1048 | |
4933 | 1049 @DOCSTRING(inline) |
1050 | |
1051 @DOCSTRING(argnames) | |
1052 | |
1053 @DOCSTRING(formula) | |
1054 | |
1055 @DOCSTRING(vectorize) | |
1056 | |
6549 | 1057 @node Commands |
1058 @section Commands | |
1059 | |
6638 | 1060 Commands are a special class of functions that only accept string |
1061 input arguments. A command can be called as an ordinary function, but | |
1062 it can also be called without the parentheses like the following example | |
1063 shows | |
1064 | |
1065 @example | |
1066 my_command hello world | |
1067 @end example | |
1068 | |
1069 @noindent | |
1070 which is the same as | |
1071 | |
1072 @example | |
1073 my_command("hello", "world") | |
1074 @end example | |
1075 | |
1076 The general form of a command call is | |
1077 | |
1078 @example | |
1079 @var{name} @var{arg1} @var{arg2} @dots{} | |
1080 @end example | |
1081 | |
1082 @noindent | |
1083 which translates directly to | |
1084 | |
1085 @example | |
1086 @var{name} ("@var{arg1}", "@var{arg2}", @dots{}) | |
1087 @end example | |
1088 | |
7001 | 1089 A function can be used as a command if it accepts string input arguments. |
6638 | 1090 To do this, the function must be marked as a command, which can be done |
1091 with the @code{mark_as_command} command like this | |
1092 | |
1093 @example | |
1094 mark_as_command name | |
1095 @end example | |
1096 | |
1097 @noindent | |
1098 where @code{name} is the function to be marked as a command. | |
1099 | |
1100 One difficulty of commands occurs when one of the string input arguments | |
1101 are stored in a variable. Since Octave can't tell the difference between | |
1102 a variable name, and an ordinary string, it is not possible to pass a | |
1103 variable as input to a command. In such a situation a command must be | |
1104 called as a function. | |
1105 | |
6549 | 1106 @DOCSTRING(mark_as_command) |
1107 | |
1108 @DOCSTRING(unmark_command) | |
1109 | |
1110 @DOCSTRING(iscommand) | |
1111 | |
1112 @DOCSTRING(mark_as_rawcommand) | |
1113 | |
1114 @DOCSTRING(unmark_rawcommand) | |
1115 | |
1116 @DOCSTRING(israwcommand) | |
1117 | |
4167 | 1118 @node Organization of Functions |
3294 | 1119 @section Organization of Functions Distributed with Octave |
1120 | |
1121 Many of Octave's standard functions are distributed as function files. | |
1122 They are loosely organized by topic, in subdirectories of | |
1123 @file{@var{octave-home}/lib/octave/@var{version}/m}, to make it easier | |
1124 to find them. | |
1125 | |
1126 The following is a list of all the function file subdirectories, and the | |
1127 types of functions you will find there. | |
1128 | |
1129 @table @file | |
1130 @item audio | |
1131 Functions for playing and recording sounds. | |
1132 | |
1133 @item control | |
1134 Functions for design and simulation of automatic control systems. | |
1135 | |
1136 @item elfun | |
1137 Elementary functions. | |
1138 | |
6554 | 1139 @item finance |
1140 Functions for computing interest payments, investment values, and rates | |
1141 of return. | |
1142 | |
3294 | 1143 @item general |
1144 Miscellaneous matrix manipulations, like @code{flipud}, @code{rot90}, | |
1145 and @code{triu}, as well as other basic functions, like | |
4029 | 1146 @code{ismatrix}, @code{nargchk}, etc. |
3294 | 1147 |
1148 @item image | |
1149 Image processing tools. These functions require the X Window System. | |
1150 | |
1151 @item io | |
11885
3342d1a7c4c9
spelling corrections
Brian Gough<bjg@network-theory.co.uk>
parents:
7031
diff
changeset
|
1152 Input-output functions. |
3294 | 1153 |
1154 @item linear-algebra | |
1155 Functions for linear algebra. | |
1156 | |
1157 @item miscellaneous | |
1158 Functions that don't really belong anywhere else. | |
1159 | |
6554 | 1160 @item optimization |
1161 Minimization of functions. | |
1162 | |
1163 @item path | |
1164 Functions to manage the directory path Octave uses to find functions. | |
1165 | |
1166 @item pkg | |
1167 Install external packages of functions in Octave. | |
1168 | |
3294 | 1169 @item plot |
6556 | 1170 Functions for displaying and printing two- and three-dimensional graphs. |
3294 | 1171 |
1172 @item polynomial | |
1173 Functions for manipulating polynomials. | |
1174 | |
1175 @item set | |
1176 Functions for creating and manipulating sets of unique values. | |
1177 | |
1178 @item signal | |
1179 Functions for signal processing applications. | |
1180 | |
6554 | 1181 @item sparse |
1182 Functions for handling sparse matrices. | |
1183 | |
3294 | 1184 @item specfun |
1185 Special functions. | |
1186 | |
1187 @item special-matrix | |
1188 Functions that create special matrix forms. | |
1189 | |
1190 @item startup | |
1191 Octave's system-wide startup file. | |
1192 | |
1193 @item statistics | |
1194 Statistical functions. | |
1195 | |
1196 @item strings | |
1197 Miscellaneous string-handling functions. | |
1198 | |
6554 | 1199 @item testfun |
1200 Perform unit tests on other functions. | |
1201 | |
3294 | 1202 @item time |
1203 Functions related to time keeping. | |
1204 @end table |