Mercurial > jwe > octave
view doc/interpreter/func.txi @ 31145:7c5cb8f8a21e
pagetranspose.m, pagectranspose.m: New functions for transposing the page (3-D) of an N-D array.
* pagectranspose.m, pagetranspose.m: New functions.
* scripts/general/module.mk: Add new functions to build system.
* etc/NEWS.8.md: Announce new functions.
* expr.txi: Add functions to Octave manual.
author | Rik <rik@octave.org> |
---|---|
date | Mon, 11 Jul 2022 22:38:57 -0700 |
parents | 796f54d4ddbf |
children |
line wrap: on
line source
@c Copyright (C) 1996-2022 The Octave Project Developers @c @c This file is part of Octave. @c @c Octave is free software: you can redistribute it and/or modify it @c under the terms of the GNU General Public License as published by @c the Free Software Foundation, either version 3 of the License, or @c (at your option) any later version. @c @c Octave is distributed in the hope that it will be useful, but @c WITHOUT ANY WARRANTY; without even the implied warranty of @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @c GNU General Public License for more details. @c @c You should have received a copy of the GNU General Public License @c along with Octave; see the file COPYING. If not, see @c <https://www.gnu.org/licenses/>. @node Functions and Scripts @chapter Functions and Scripts @cindex defining functions @cindex user-defined functions @cindex functions, user-defined @cindex script files Complicated Octave programs can often be simplified by defining functions. Functions can be defined directly on the command line during interactive Octave sessions, or in external files, and can be called just like built-in functions. @menu * Introduction to Function and Script Files:: * Defining Functions:: * Returning from a Function:: * Multiple Return Values:: * Variable-length Return Lists:: * Variable-length Argument Lists:: * Ignoring Arguments:: * Default Arguments:: * Validating Arguments:: * Function Files:: * Script Files:: * Function Handles and Anonymous Functions:: * Command Syntax and Function Syntax:: * Organization of Functions:: @end menu @node Introduction to Function and Script Files @section Introduction to Function and Script Files There are seven different things covered in this section. @enumerate @item Typing in a function at the command prompt. @item Storing a group of commands in a file --- called a script file. @item Storing a function in a file---called a function file. @item Subfunctions in function files. @item Multiple functions in one script file. @item Private functions. @item Nested functions. @end enumerate Both function files and script files end with an extension of .m, for @sc{matlab} compatibility. If you want more than one independent functions in a file, it must be a script file (@pxref{Script Files}), and to use these functions you must execute the script file before you can use the functions that are in the script file. @node Defining Functions @section Defining Functions @cindex @code{function} statement @cindex @code{endfunction} statement In its simplest form, the definition of a function named @var{name} looks like this: @example @group function @var{name} @var{body} endfunction @end group @end example @noindent A valid function name is like a valid variable name: a sequence of letters, digits and underscores, not starting with a digit. Functions share the same pool of names as variables. The function @var{body} consists of Octave statements. It is the most important part of the definition, because it says what the function should actually @emph{do}. For example, here is a function that, when executed, will ring the bell on your terminal (assuming that it is possible to do so): @example @group function wakeup printf ("\a"); endfunction @end group @end example The @code{printf} statement (@pxref{Input and Output}) simply tells Octave to print the string @qcode{"@backslashchar{}a"}. The special character @samp{\a} stands for the alert character (ASCII 7). @xref{Strings}. Once this function is defined, you can ask Octave to evaluate it by typing the name of the function. Normally, you will want to pass some information to the functions you define. The syntax for passing parameters to a function in Octave is @example @group function @var{name} (@var{arg-list}) @var{body} endfunction @end group @end example @noindent where @var{arg-list} is a comma-separated list of the function's arguments. When the function is called, the argument names are used to hold the argument values given in the call. The list of arguments may be empty, in which case this form is equivalent to the one shown above. To print a message along with ringing the bell, you might modify the @code{wakeup} to look like this: @example @group function wakeup (message) printf ("\a%s\n", message); endfunction @end group @end example Calling this function using a statement like this @example wakeup ("Rise and shine!"); @end example @noindent will cause Octave to ring your terminal's bell and print the message @samp{Rise and shine!}, followed by a newline character (the @samp{\n} in the first argument to the @code{printf} statement). In most cases, you will also want to get some information back from the functions you define. Here is the syntax for writing a function that returns a single value: @example @group function @var{ret-var} = @var{name} (@var{arg-list}) @var{body} endfunction @end group @end example @noindent The symbol @var{ret-var} is the name of the variable that will hold the value to be returned by the function. This variable must be defined before the end of the function body in order for the function to return a value. Variables used in the body of a function are local to the function. Variables named in @var{arg-list} and @var{ret-var} are also local to the function. @xref{Global Variables}, for information about how to access global variables inside a function. For example, here is a function that computes the average of the elements of a vector: @example @group function retval = avg (v) retval = sum (v) / length (v); endfunction @end group @end example If we had written @code{avg} like this instead, @example @group function retval = avg (v) if (isvector (v)) retval = sum (v) / length (v); endif endfunction @end group @end example @noindent and then called the function with a matrix instead of a vector as the argument, Octave would have printed an error message like this: @example @group error: value on right hand side of assignment is undefined @end group @end example @noindent because the body of the @code{if} statement was never executed, and @code{retval} was never defined. To prevent obscure errors like this, it is a good idea to always make sure that the return variables will always have values, and to produce meaningful error messages when problems are encountered. For example, @code{avg} could have been written like this: @example @group function retval = avg (v) retval = 0; if (isvector (v)) retval = sum (v) / length (v); else error ("avg: expecting vector argument"); endif endfunction @end group @end example There is still one additional problem with this function. What if it is called without an argument? Without additional error checking, Octave will probably print an error message that won't really help you track down the source of the error. To allow you to catch errors like this, Octave provides each function with an automatic variable called @code{nargin}. Each time a function is called, @code{nargin} is automatically initialized to the number of arguments that have actually been passed to the function. For example, we might rewrite the @code{avg} function like this: @example @group function retval = avg (v) retval = 0; if (nargin != 1) usage ("avg (vector)"); endif if (isvector (v)) retval = sum (v) / length (v); else error ("avg: expecting vector argument"); endif endfunction @end group @end example Although Octave does not automatically report an error if you call a function with more arguments than expected, doing so probably indicates that something is wrong. Octave also does not automatically report an error if a function is called with too few arguments, but any attempt to use a variable that has not been given a value will result in an error. To avoid such problems and to provide useful messages, we check for both possibilities and issue our own error message. @DOCSTRING(nargin) @DOCSTRING(inputname) @DOCSTRING(silent_functions) @node Returning from a Function @section Returning from a Function The body of a user-defined function can contain a @code{return} statement. This statement returns control to the rest of the Octave program. It looks like this: @example return @end example Unlike the @code{return} statement in C, Octave's @code{return} statement cannot be used to return a value from a function. Instead, you must assign values to the list of return variables that are part of the @code{function} statement. The @code{return} statement simply makes it easier to exit a function from a deeply nested loop or conditional statement. Here is an example of a function that checks to see if any elements of a vector are nonzero. @example @group function retval = any_nonzero (v) retval = 0; for i = 1:length (v) if (v (i) != 0) retval = 1; return; endif endfor printf ("no nonzero elements found\n"); endfunction @end group @end example Note that this function could not have been written using the @code{break} statement to exit the loop once a nonzero value is found without adding extra logic to avoid printing the message if the vector does contain a nonzero element. @deftypefn {} {} return When Octave encounters the keyword @code{return} inside a function or script, it returns control to the caller immediately. At the top level, the return statement is ignored. A @code{return} statement is assumed at the end of every function definition. @end deftypefn @node Multiple Return Values @section Multiple Return Values Unlike many other computer languages, Octave allows you to define functions that return more than one value. The syntax for defining functions that return multiple values is @example @group function [@var{ret-list}] = @var{name} (@var{arg-list}) @var{body} endfunction @end group @end example @noindent where @var{name}, @var{arg-list}, and @var{body} have the same meaning as before, and @var{ret-list} is a comma-separated list of variable names that will hold the values returned from the function. The list of return values must have at least one element. If @var{ret-list} has only one element, this form of the @code{function} statement is equivalent to the form described in the previous section. Here is an example of a function that returns two values, the maximum element of a vector and the index of its first occurrence in the vector. @example @group function [max, idx] = vmax (v) idx = 1; max = v (idx); for i = 2:length (v) if (v (i) > max) max = v (i); idx = i; endif endfor endfunction @end group @end example In this particular case, the two values could have been returned as elements of a single array, but that is not always possible or convenient. The values to be returned may not have compatible dimensions, and it is often desirable to give the individual return values distinct names. It is possible to use the @code{nthargout} function to obtain only some of the return values or several at once in a cell array. @xref{Cell Array Objects}. @DOCSTRING(nthargout) In addition to setting @code{nargin} each time a function is called, Octave also automatically initializes @code{nargout} to the number of values that are expected to be returned. This allows you to write functions that behave differently depending on the number of values that the user of the function has requested. The implicit assignment to the built-in variable @code{ans} does not figure in the count of output arguments, so the value of @code{nargout} may be zero. The @code{svd} and @code{lu} functions are examples of built-in functions that behave differently depending on the value of @code{nargout}. It is possible to write functions that only set some return values. For example, calling the function @example @group function [x, y, z] = f () x = 1; z = 2; endfunction @end group @end example @noindent as @example [a, b, c] = f () @end example @noindent produces: @example @group a = 1 b = [](0x0) c = 2 @end group @end example @noindent along with a warning. @DOCSTRING(nargout) @node Variable-length Return Lists @section Variable-length Return Lists @cindex variable-length return lists @cindex @code{varargout} @anchor{XREFvarargout} It is possible to return a variable number of output arguments from a function using a syntax that's similar to the one used with the special @code{varargin} parameter name. To let a function return a variable number of output arguments the special output parameter name @code{varargout} is used. As with @code{varargin}, @code{varargout} is a cell array that will contain the requested output arguments. As an example the following function sets the first output argument to 1, the second to 2, and so on. @example @group function varargout = one_to_n () for i = 1:nargout varargout@{i@} = i; endfor endfunction @end group @end example @noindent When called this function returns values like this @example @group [a, b, c] = one_to_n () @result{} a = 1 @result{} b = 2 @result{} c = 3 @end group @end example If @code{varargin} (@code{varargout}) does not appear as the last element of the input (output) parameter list, then it is not special, and is handled the same as any other parameter name. @DOCSTRING(deal) @node Variable-length Argument Lists @section Variable-length Argument Lists @cindex variable-length argument lists @cindex @code{varargin} @anchor{XREFvarargin} Sometimes the number of input arguments is not known when the function is defined. As an example think of a function that returns the smallest of all its input arguments. For example: @example @group a = smallest (1, 2, 3); b = smallest (1, 2, 3, 4); @end group @end example @noindent In this example both @code{a} and @code{b} would be 1. One way to write the @code{smallest} function is @example @group function val = smallest (arg1, arg2, arg3, arg4, arg5) @var{body} endfunction @end group @end example @noindent and then use the value of @code{nargin} to determine which of the input arguments should be considered. The problem with this approach is that it can only handle a limited number of input arguments. If the special parameter name @code{varargin} appears at the end of a function parameter list it indicates that the function takes a variable number of input arguments. Using @code{varargin} the function looks like this @example @group function val = smallest (varargin) @var{body} endfunction @end group @end example @noindent In the function body the input arguments can be accessed through the variable @code{varargin}. This variable is a cell array containing all the input arguments. @xref{Cell Arrays}, for details on working with cell arrays. The @code{smallest} function can now be defined like this @example @group function val = smallest (varargin) val = min ([varargin@{:@}]); endfunction @end group @end example @noindent This implementation handles any number of input arguments, but it's also a very simple solution to the problem. A slightly more complex example of @code{varargin} is a function @code{print_arguments} that prints all input arguments. Such a function can be defined like this @example @group function print_arguments (varargin) for i = 1:length (varargin) printf ("Input argument %d: ", i); disp (varargin@{i@}); endfor endfunction @end group @end example @noindent This function produces output like this @example @group print_arguments (1, "two", 3); @print{} Input argument 1: 1 @print{} Input argument 2: two @print{} Input argument 3: 3 @end group @end example @DOCSTRING(parseparams) @node Ignoring Arguments @section Ignoring Arguments In the formal argument list, it is possible to use the dummy placeholder @code{~} instead of a name. This indicates that the corresponding argument value should be ignored and not stored to any variable. @example @group function val = pick2nd (~, arg2) val = arg2; endfunction @end group @end example The value of @code{nargin} is not affected by using this declaration. Return arguments can also be ignored using the same syntax. For example, the sort function returns both the sorted values, and an index vector for the original input which will result in a sorted output. Ignoring the second output is simple---don't request more than one output. But ignoring the first, and calculating just the second output, requires the use of the @code{~} placeholder. @example @group x = [2, 3, 1]; [s, i] = sort (x) @result{} s = 1 2 3 i = 3 1 2 [~, i] = sort (x) @result{} i = 3 1 2 @end group @end example When using the @code{~} placeholder, commas---not whitespace---must be used to separate output arguments. Otherwise, the interpreter will view @code{~} as the logical not operator. @example @group [~ i] = sort (x) parse error: invalid left hand side of assignment @end group @end example Functions may take advantage of ignored outputs to reduce the number of calculations performed. To do so, use the @code{isargout} function to query whether the output argument is wanted. For example: @example @group function [out1, out2] = long_function (x, y, z) if (isargout (1)) ## Long calculation @dots{} out1 = result; endif @dots{} endfunction @end group @end example @DOCSTRING(isargout) @node Default Arguments @section Default Arguments @cindex default arguments Since Octave supports variable number of input arguments, it is very useful to assign default values to some input arguments. When an input argument is declared in the argument list it is possible to assign a default value to the argument like this @example @group function @var{name} (@var{arg1} = @var{val1}, @dots{}) @var{body} endfunction @end group @end example @noindent If no value is assigned to @var{arg1} by the user, it will have the value @var{val1}. As an example, the following function implements a variant of the classic ``Hello, World'' program. @example @group function hello (who = "World") printf ("Hello, %s!\n", who); endfunction @end group @end example @noindent When called without an input argument the function prints the following @example @group hello (); @print{} Hello, World! @end group @end example @noindent and when it's called with an input argument it prints the following @example @group hello ("Beautiful World of Free Software"); @print{} Hello, Beautiful World of Free Software! @end group @end example Sometimes it is useful to explicitly tell Octave to use the default value of an input argument. This can be done writing a @samp{:} as the value of the input argument when calling the function. @example @group hello (:); @print{} Hello, World! @end group @end example @node Validating Arguments @section Validating Arguments @cindex validating arguments Octave is a weakly typed programming language. Thus it is possible to call a function with arguments, that probably cause errors or might have undesirable side effects. For example calling a string processing function with a huge sparse matrix. It is good practice at the head of a function to verify that it has been called correctly. Octave offers several functions for this purpose. @menu * Validating the number of Arguments:: * Validating the type of Arguments:: * Parsing Arguments:: @end menu @node Validating the number of Arguments @subsection Validating the number of Arguments In Octave the following idiom is seen frequently at the beginning of a function definition: @example @group if (nargin < min_#_inputs || nargin > max_#_inputs) print_usage (); endif @end group @end example @noindent which stops the function execution and prints a message about the correct way to call the function whenever the number of inputs is wrong. Similar error checking is provided by @code{narginchk} and @code{nargoutchk}. @DOCSTRING(narginchk) @DOCSTRING(nargoutchk) @node Validating the type of Arguments @subsection Validating the type of Arguments Besides the number of arguments, inputs can be checked for various properties. @code{validatestring} is used for string arguments and @code{validateattributes} for numeric arguments. @DOCSTRING(validatestring) @DOCSTRING(validateattributes) As alternatives to @code{validateattributes} there are several shorter convenience functions to check for individual properties. @DOCSTRING(mustBeFinite) @DOCSTRING(mustBeGreaterThan) @DOCSTRING(mustBeGreaterThanOrEqual) @DOCSTRING(mustBeInteger) @DOCSTRING(mustBeLessThan) @DOCSTRING(mustBeLessThanOrEqual) @DOCSTRING(mustBeMember) @DOCSTRING(mustBeNegative) @DOCSTRING(mustBeNonempty) @DOCSTRING(mustBeNonNan) @DOCSTRING(mustBeNonnegative) @DOCSTRING(mustBeNonpositive) @DOCSTRING(mustBeNonsparse) @DOCSTRING(mustBeNonzero) @DOCSTRING(mustBeNumeric) @DOCSTRING(mustBeNumericOrLogical) @DOCSTRING(mustBePositive) @DOCSTRING(mustBeReal) @node Parsing Arguments @subsection Parsing Arguments If none of the preceding validation functions is sufficient there is also the class @code{inputParser} which can perform extremely complex input checking for functions. @DOCSTRING(inputParser) @node Function Files @section Function Files @cindex function file Except for simple one-shot programs, it is not practical to have to define all the functions you need each time you need them. Instead, you will normally want to save them in a file so that you can easily edit them, and save them for use at a later time. Octave does not require you to load function definitions from files before using them. You simply need to put the function definitions in a place where Octave can find them. When Octave encounters an identifier that is undefined, it first looks for variables or functions that are already compiled and currently listed in its symbol table. If it fails to find a definition there, it searches a list of directories (the @dfn{path}) for files ending in @file{.m} that have the same base name as the undefined identifier.@footnote{The @samp{.m} suffix was chosen for compatibility with @sc{matlab}.} Once Octave finds a file with a name that matches, the contents of the file are read. If it defines a @emph{single} function, it is compiled and executed. @xref{Script Files}, for more information about how you can define more than one function in a single file. When Octave defines a function from a function file, it saves the full name of the file it read and the time stamp on the file. If the time stamp on the file changes, Octave may reload the file. When Octave is running interactively, time stamp checking normally happens at most once each time Octave prints the prompt. Searching for new function definitions also occurs if the current working directory changes. Checking the time stamp allows you to edit the definition of a function while Octave is running, and automatically use the new function definition without having to restart your Octave session. To avoid degrading performance unnecessarily by checking the time stamps on functions that are not likely to change, Octave assumes that function files in the directory tree @file{@var{octave-home}/share/octave/@var{version}/m} will not change, so it doesn't have to check their time stamps every time the functions defined in those files are used. This is normally a very good assumption and provides a significant improvement in performance for the function files that are distributed with Octave. If you know that your own function files will not change while you are running Octave, you can improve performance by calling @code{ignore_function_time_stamp ("all")}, so that Octave will ignore the time stamps for all function files. Passing @qcode{"system"} to this function resets the default behavior. @c FIXME: note about time stamps on files in NFS environments? @DOCSTRING(edit) @DOCSTRING(mfilename) @DOCSTRING(ignore_function_time_stamp) @menu * Manipulating the Load Path:: * Subfunctions:: * Private Functions:: * Nested Functions:: * Overloading and Autoloading:: * Function Locking:: * Function Precedence:: @end menu @node Manipulating the Load Path @subsection Manipulating the Load Path When a function is called, Octave searches a list of directories for a file that contains the function declaration. This list of directories is known as the load path. By default the load path contains a list of directories distributed with Octave plus the current working directory. To see your current load path call the @code{path} function without any input or output arguments. It is possible to add or remove directories to or from the load path using @code{addpath} and @code{rmpath}. As an example, the following code adds @samp{~/Octave} to the load path. @example addpath ("~/Octave") @end example @noindent After this the directory @samp{~/Octave} will be searched for functions. @DOCSTRING(addpath) @DOCSTRING(genpath) @DOCSTRING(rmpath) @DOCSTRING(savepath) @DOCSTRING(path) @DOCSTRING(pathdef) @DOCSTRING(pathsep) @DOCSTRING(rehash) @DOCSTRING(file_in_loadpath) @DOCSTRING(restoredefaultpath) @DOCSTRING(command_line_path) @DOCSTRING(dir_in_loadpath) @DOCSTRING(dir_encoding) @node Subfunctions @subsection Subfunctions A function file may contain secondary functions called @dfn{subfunctions}. These secondary functions are only visible to the other functions in the same function file. For example, a file @file{f.m} containing @example @group function f () printf ("in f, calling g\n"); g () endfunction function g () printf ("in g, calling h\n"); h () endfunction function h () printf ("in h\n") endfunction @end group @end example @noindent defines a main function @code{f} and two subfunctions. The subfunctions @code{g} and @code{h} may only be called from the main function @code{f} or from the other subfunctions, but not from outside the file @file{f.m}. @DOCSTRING(localfunctions) @node Private Functions @subsection Private Functions In many cases one function needs to access one or more helper functions. If the helper function is limited to the scope of a single function, then subfunctions as discussed above might be used. However, if a single helper function is used by more than one function, then this is no longer possible. In this case the helper functions might be placed in a subdirectory, called "private", of the directory in which the functions needing access to this helper function are found. As a simple example, consider a function @code{func1}, that calls a helper function @code{func2} to do much of the work. For example: @example @group function y = func1 (x) y = func2 (x); endfunction @end group @end example @noindent Then if the path to @code{func1} is @code{<directory>/func1.m}, and if @code{func2} is found in the directory @code{<directory>/private/func2.m}, then @code{func2} is only available for use of the functions, like @code{func1}, that are found in @code{<directory>}. @node Nested Functions @subsection Nested Functions Nested functions are similar to subfunctions in that only the main function is visible outside the file. However, they also allow for child functions to access the local variables in their parent function. This shared access mimics using a global variable to share information --- but a global variable which is not visible to the rest of Octave. As a programming strategy, sharing data this way can create code which is difficult to maintain. It is recommended to use subfunctions in place of nested functions when possible. As a simple example, consider a parent function @code{foo}, that calls a nested child function @code{bar}, with a shared variable @var{x}. @example @group function y = foo () x = 10; bar (); y = x; function bar () x = 20; endfunction endfunction foo () @result{} 20 @end group @end example @noindent Notice that there is no special syntax for sharing @var{x}. This can lead to problems with accidental variable sharing between a parent function and its child. While normally variables are inherited, child function parameters and return values are local to the child function. Now consider the function @code{foobar} that uses variables @var{x} and @var{y}. @code{foobar} calls a nested function @code{foo} which takes @var{x} as a parameter and returns @var{y}. @code{foo} then calls @code{bat} which does some computation. @example @group function z = foobar () x = 0; y = 0; z = foo (5); z += x + y; function y = foo (x) y = x + bat (); function z = bat () z = x; endfunction endfunction endfunction foobar () @result{} 10 @end group @end example @noindent It is important to note that the @var{x} and @var{y} in @code{foobar} remain zero, as in @code{foo} they are a return value and parameter respectively. The @var{x} in @code{bat} refers to the @var{x} in @code{foo}. Variable inheritance leads to a problem for @code{eval} and scripts. If a new variable is created in a parent function, it is not clear what should happen in nested child functions. For example, consider a parent function @code{foo} with a nested child function @code{bar}: @example @group function y = foo (to_eval) bar (); eval (to_eval); function bar () eval ("x = 100;"); eval ("y = x;"); endfunction endfunction foo ("x = 5;") @result{} error: can not add variable "x" to a static workspace foo ("y = 10;") @result{} 10 foo ("") @result{} 100 @end group @end example @noindent The parent function @code{foo} is unable to create a new variable @var{x}, but the child function @code{bar} was successful. Furthermore, even in an @code{eval} statement @var{y} in @code{bar} is the same @var{y} as in its parent function @code{foo}. The use of @code{eval} in conjunction with nested functions is best avoided. As with subfunctions, only the first nested function in a file may be called from the outside. Inside a function the rules are more complicated. In general a nested function may call: @enumerate 0 @item Globally visible functions @item Any function that the nested function's parent can call @item Sibling functions (functions that have the same parents) @item Direct children @end enumerate As a complex example consider a parent function @code{ex_top} with two child functions, @code{ex_a} and @code{ex_b}. In addition, @code{ex_a} has two more child functions, @code{ex_aa} and @code{ex_ab}. For example: @example function ex_top () ## Can call: ex_top, ex_a, and ex_b ## Can NOT call: ex_aa and ex_ab function ex_a () ## Can call everything function ex_aa () ## Can call everything endfunction function ex_ab () ## Can call everything endfunction endfunction function ex_b () ## Can call: ex_top, ex_a, and ex_b ## Can NOT call: ex_aa and ex_ab endfunction endfunction @end example @node Overloading and Autoloading @subsection Overloading and Autoloading Functions can be overloaded to work with different input arguments. For example, the operator '+' has been overloaded in Octave to work with single, double, uint8, int32, and many other arguments. The preferred way to overload functions is through classes and object oriented programming (@pxref{Function Overloading}). Occasionally, however, one needs to undo user overloading and call the default function associated with a specific type. The @code{builtin} function exists for this purpose. @DOCSTRING(builtin) A single dynamically linked file might define several functions. However, as Octave searches for functions based on the functions filename, Octave needs a manner in which to find each of the functions in the dynamically linked file. On operating systems that support symbolic links, it is possible to create a symbolic link to the original file for each of the functions which it contains. However, there is at least one well known operating system that doesn't support symbolic links. Making copies of the original file for each of the functions is undesirable as it increases the amount of disk space used by Octave. Instead Octave supplies the @code{autoload} function, that permits the user to define in which file a certain function will be found. @DOCSTRING(autoload) @node Function Locking @subsection Function Locking It is sometime desirable to lock a function into memory with the @code{mlock} function. This is typically used for dynamically linked functions in oct-files or mex-files that contain some initialization, and it is desirable that calling @code{clear} does not remove this initialization. As an example, @example @group function my_function () mlock (); @dots{} endfunction @end group @end example @noindent prevents @code{my_function} from being removed from memory after it is called, even if @code{clear} is called. It is possible to determine if a function is locked into memory with the @code{mislocked}, and to unlock a function with @code{munlock}, which the following code illustrates. @example @group my_function (); mislocked ("my_function") @result{} ans = 1 munlock ("my_function"); mislocked ("my_function") @result{} ans = 0 @end group @end example A common use of @code{mlock} is to prevent persistent variables from being removed from memory, as the following example shows: @example @group function count_calls () mlock (); persistent calls = 0; printf ("count_calls() has been called %d times\n", ++calls); endfunction count_calls (); @print{} count_calls() has been called 1 times clear count_calls count_calls (); @print{} count_calls() has been called 2 times @end group @end example @code{mlock} might also be used to prevent changes to an m-file, such as in an external editor, from having any effect in the current Octave session; A similar effect can be had with the @code{ignore_function_time_stamp} function. @DOCSTRING(mlock) @DOCSTRING(munlock) @DOCSTRING(mislocked) @node Function Precedence @subsection Function Precedence Given the numerous different ways that Octave can define a function, it is possible and even likely that multiple versions of a function, might be defined within a particular scope. The precedence of which function will be used within a particular scope is given by @enumerate 1 @item Subfunction A subfunction with the required function name in the given scope. @item Private function A function defined within a private directory of the directory which contains the current function. @item Class constructor A function that constructs a user class as defined in chapter @ref{Object Oriented Programming}. @item Class method An overloaded function of a class as in chapter @ref{Object Oriented Programming}. @item Command-line Function A function that has been defined on the command-line. @item Autoload function A function that is marked as autoloaded with @xref{XREFautoload,,autoload}. @item A Function on the Path A function that can be found on the users load-path. There can also be Oct-file, mex-file or m-file versions of this function and the precedence between these versions are in that order. @item Built-in function A function that is a part of core Octave such as @code{numel}, @code{size}, etc. @end enumerate @node Script Files @section Script Files A script file is a file containing (almost) any sequence of Octave commands. It is read and evaluated just as if you had typed each command at the Octave prompt, and provides a convenient way to perform a sequence of commands that do not logically belong inside a function. Unlike a function file, a script file must @emph{not} begin with the keyword @code{function}. If it does, Octave will assume that it is a function file, and that it defines a single function that should be evaluated as soon as it is defined. A script file also differs from a function file in that the variables named in a script file are not local variables, but are in the same scope as the other variables that are visible on the command line. Even though a script file may not begin with the @code{function} keyword, it is possible to define more than one function in a single script file and load (but not execute) all of them at once. To do this, the first token in the file (ignoring comments and other white space) must be something other than @code{function}. If you have no other statements to evaluate, you can use a statement that has no effect, like this: @example @group # Prevent Octave from thinking that this # is a function file: 1; # Define function one: function one () @dots{} @end group @end example To have Octave read and compile these functions into an internal form, you need to make sure that the file is in Octave's load path (accessible through the @code{path} function), then simply type the base name of the file that contains the commands. (Octave uses the same rules to search for script files as it does to search for function files.) If the first token in a file (ignoring comments) is @code{function}, Octave will compile the function and try to execute it, printing a message warning about any non-whitespace characters that appear after the function definition. Note that Octave does not try to look up the definition of any identifier until it needs to evaluate it. This means that Octave will compile the following statements if they appear in a script file, or are typed at the command line, @example @group # not a function file: 1; function foo () do_something (); endfunction function do_something () do_something_else (); endfunction @end group @end example @noindent even though the function @code{do_something} is not defined before it is referenced in the function @code{foo}. This is not an error because Octave does not need to resolve all symbols that are referenced by a function until the function is actually evaluated. Since Octave doesn't look for definitions until they are needed, the following code will always print @samp{bar = 3} whether it is typed directly on the command line, read from a script file, or is part of a function body, even if there is a function or script file called @file{bar.m} in Octave's path. @example @group eval ("bar = 3"); bar @end group @end example Code like this appearing within a function body could fool Octave if definitions were resolved as the function was being compiled. It would be virtually impossible to make Octave clever enough to evaluate this code in a consistent fashion. The parser would have to be able to perform the call to @code{eval} at compile time, and that would be impossible unless all the references in the string to be evaluated could also be resolved, and requiring that would be too restrictive (the string might come from user input, or depend on things that are not known until the function is evaluated). Although Octave normally executes commands from script files that have the name @file{@var{file}.m}, you can use the function @code{source} to execute commands from any file. @DOCSTRING(source) @menu * Publish Octave Script Files:: * Publishing Markup:: * Jupyter Notebooks:: @end menu @node Publish Octave Script Files @subsection Publish Octave Script Files The function @code{publish} provides a dynamic possibility to document your script file. Unlike static documentation, @code{publish} runs the script file, saves any figures and output while running the script, and presents them alongside static documentation in a desired output format. The static documentation can make use of @ref{Publishing Markup} to enhance and customize the output. @DOCSTRING(publish) The counterpart to @code{publish} is @code{grabcode}: @DOCSTRING(grabcode) @node Publishing Markup @subsection Publishing Markup @menu * Using Publishing Markup in Script Files:: * Text Formatting:: * Sections:: * Preformatted Code:: * Preformatted Text:: * Bulleted Lists:: * Numbered Lists:: * Including File Content:: * Including Graphics:: * Including URLs:: * Mathematical Equations:: * HTML Markup:: * LaTeX Markup:: @end menu @node Using Publishing Markup in Script Files @subsubsection Using Publishing Markup in Script Files To use Publishing Markup, start by typing @samp{##} or @samp{%%} at the beginning of a new line. For @sc{matlab} compatibility @samp{%%%} is treated the same way as @samp{%%}. The lines following @samp{##} or @samp{%%} start with one of either @samp{#} or @samp{%} followed by at least one space. These lines are interpreted as section. A section ends at the first line not starting with @samp{#} or @samp{%}, or when the end of the document is reached. A section starting in the first line of the document, followed by another start of a section that might be empty, is interpreted as a document title and introduction text. See the example below for clarity: @example @group %% Headline title % % Some *bold*, _italic_, or |monospaced| Text with % a <https://www.octave.org link to GNU Octave>. %% # "Real" Octave commands to be evaluated sombrero () ## Octave comment style supported as well # # * Bulleted list item 1 # * Bulleted list item 2 # # # Numbered list item 1 # # Numbered list item 2 @end group @end example @node Text Formatting @subsubsection Text Formatting Basic text formatting is supported inside sections, see the example given below: @example @group ## # @b{*bold*}, @i{_italic_}, or |monospaced| Text @end group @end example Additionally two trademark symbols are supported, just embrace the letters @samp{TM} or @samp{R}. @example @group ## # (TM) or (R) @end group @end example @node Sections @subsubsection Sections A section is started by typing @samp{##} or @samp{%%} at the beginning of a new line. A section title can be provided by writing it, separated by a space, in the first line after @samp{##} or @samp{%%}. Without a section title, the section is interpreted as a continuation of the previous section. For @sc{matlab} compatibility @samp{%%%} is treated the same way as @samp{%%}. @example @group some_code (); ## Section 1 # ## Section 2 some_code (); ## # Still in section 2 some_code (); %%% Section 3 % % @end group @end example @node Preformatted Code @subsubsection Preformatted Code To write preformatted code inside a section, indent the code by three spaces after @samp{#} at the beginning of each line and leave the lines above and below the code blank, except for @samp{#} at the beginning of those lines. @example @group ## # This is a syntax highlighted for-loop: # # for i = 1:5 # disp (i); # endfor # # And more usual text. @end group @end example @node Preformatted Text @subsubsection Preformatted Text To write preformatted text inside a section, indent the code by two spaces after @samp{#} at the beginning of each line and leave the lines above and below the preformatted text blank, except for @samp{#} at the beginning of those lines. @example @group ## # This following text is preformatted: # # "To be, or not to be: that is the question: # Whether 'tis nobler in the mind to suffer # The slings and arrows of outrageous fortune, # Or to take arms against a sea of troubles, # And by opposing end them? To die: to sleep;" # # --"Hamlet" by W. Shakespeare @end group @end example @node Bulleted Lists @subsubsection Bulleted Lists To create a bulleted list, type @example @group ## # # * Bulleted list item 1 # * Bulleted list item 2 # @end group @end example @noindent to get output like @itemize @bullet @item Bulleted list item 1 @item Bulleted list item 2 @end itemize Notice the blank lines, except for the @samp{#} or @samp{%} before and after the bulleted list! @node Numbered Lists @subsubsection Numbered Lists To create a numbered list, type @example @group ## # # # Numbered list item 1 # # Numbered list item 2 # @end group @end example @noindent to get output like @enumerate @item Numbered list item 1 @item Numbered list item 2 @end enumerate Notice the blank lines, except for the @samp{#} or @samp{%} before and after the numbered list! @node Including File Content @subsubsection Including File Content To include the content of an external file, e.g., a file called @samp{my_function.m} at the same location as the published Octave script, use the following syntax to include it with Octave syntax highlighting. Alternatively, you can write the full or relative path to the file. @example @group ## # # <include>my_function.m</include> # # <include>/full/path/to/my_function.m</include> # # <include>../relative/path/to/my_function.m</include> # @end group @end example @node Including Graphics @subsubsection Including Graphics To include external graphics, e.g., a graphic called @samp{my_graphic.png} at the same location as the published Octave script, use the following syntax. Alternatively, you can write the full path to the graphic. @example @group ## # # <<my_graphic.png>> # # <</full/path/to/my_graphic.png>> # # <<../relative/path/to/my_graphic.png>> # @end group @end example @node Including URLs @subsubsection Including URLs Basically, a URL is written between an opening @samp{<} and a closing @samp{>} angle. @example @group ## # <https://www.octave.org> @end group @end example Text that is within these angles and separated by at least one space from the URL is a displayed text for the link. @example @group ## # <https://www.octave.org GNU Octave> @end group @end example A link starting with @samp{<octave:} followed by the name of a GNU Octave function, optionally with a displayed text, results in a link to the online GNU Octave documentations function index. @example @group ## # <octave:DISP The display function> @end group @end example @node Mathematical Equations @subsubsection Mathematical Equations One can insert @LaTeX{} inline math, surrounded by single @samp{$} signs, or displayed math, surrounded by double @samp{$$} signs, directly inside sections. @example @group ## # Some shorter inline equation $e^@{ix@} = \cos x + i\sin x$. # # Or more complicated formulas as displayed math: # $$e^x = \lim_@{n\rightarrow\infty@}\left(1+\dfrac@{x@}@{n@}\right)^@{n@}.$$ @end group @end example @node HTML Markup @subsubsection HTML Markup If the published output is a HTML report, you can insert HTML markup, that is only visible in this kind of output. @example @group ## # <html> # <table style="border:1px solid black;"> # <tr><td>1</td><td>2</td></tr> # <tr><td>3</td><td>3</td></tr> # </html> @end group @end example @node LaTeX Markup @subsubsection LaTeX Markup If the published output is a @LaTeX{} or PDF report, you can insert @LaTeX{} markup, that is only visible in this kind of output. @example @group ## # <latex> # Some output only visible in @nospell{LaTeX} or PDF reports. # \begin@{equation@} # e^x = \lim\limits_@{n\rightarrow\infty@}\left(1+\dfrac@{x@}@{n@}\right)^@{n@} # \end@{equation@} # </latex> @end group @end example @node Jupyter Notebooks @subsection Jupyter Notebooks @cindex Jupyter Notebooks Jupyter notebooks are one popular technique for displaying code, text, and graphical output together in a comprehensive manner. Octave can publish results to a Jupyter notebook with the function @code{jupyter_notebook}. @DOCSTRING(jupyter_notebook) @node Function Handles and Anonymous Functions @section Function Handles and Anonymous Functions @cindex handle, function handles @cindex anonymous functions It can be very convenient store a function in a variable so that it can be passed to a different function. For example, a function that performs numerical minimization needs access to the function that should be minimized. @menu * Function Handles:: * Anonymous Functions:: @end menu @node Function Handles @subsection Function Handles A function handle is a pointer to another function and is defined with the syntax @example @@@var{function-name} @end example @noindent For example, @example f = @@sin; @end example @noindent creates a function handle called @code{f} that refers to the function @code{sin}. Function handles are used to call other functions indirectly, or to pass a function as an argument to another function like @code{quad} or @code{fsolve}. For example: @example @group f = @@sin; quad (f, 0, pi) @result{} 2 @end group @end example You may use @code{feval} to call a function using function handle, or simply write the name of the function handle followed by an argument list. If there are no arguments, you must use an empty argument list @samp{()}. For example: @example @group f = @@sin; feval (f, pi/4) @result{} 0.70711 f (pi/4) @result{} 0.70711 @end group @end example @DOCSTRING(is_function_handle) @DOCSTRING(functions) @DOCSTRING(func2str) @DOCSTRING(str2func) @DOCSTRING(symvar) @node Anonymous Functions @subsection Anonymous Functions Anonymous functions are defined using the syntax @example @@(@var{argument-list}) @var{expression} @end example @noindent Any variables that are not found in the argument list are inherited from the enclosing scope. Anonymous functions are useful for creating simple unnamed functions from expressions or for wrapping calls to other functions to adapt them for use by functions like @code{quad}. For example, @example @group f = @@(x) x.^2; quad (f, 0, 10) @result{} 333.33 @end group @end example @noindent creates a simple unnamed function from the expression @code{x.^2} and passes it to @code{quad}, @example @group quad (@@(x) sin (x), 0, pi) @result{} 2 @end group @end example @noindent wraps another function, and @example @group a = 1; b = 2; quad (@@(x) betainc (x, a, b), 0, 0.4) @result{} 0.13867 @end group @end example @noindent adapts a function with several parameters to the form required by @code{quad}. In this example, the values of @var{a} and @var{b} that are passed to @code{betainc} are inherited from the current environment. Note that for performance reasons it is better to use handles to existing Octave functions, rather than to define anonymous functions which wrap an existing function. The integration of @code{sin (x)} is 5X faster if the code is written as @example quad (@@sin, 0, pi) @end example @noindent rather than using the anonymous function @code{@@(x) sin (x)}. There are many operators which have functional equivalents that may be better choices than an anonymous function. Instead of writing @example f = @@(x, y) x + y @end example @noindent this should be coded as @example f = @@plus @end example @xref{Operator Overloading}, for a list of operators which also have a functional form. @node Command Syntax and Function Syntax @section Command Syntax and Function Syntax @cindex commands functions Additionally to the function syntax described above (i.e., calling a function like @code{fun (arg1, arg2, @dots{})}), a function can be called using command syntax (for example, calling a function like @code{fun arg1 arg2 @dots{}}). In that case, all arguments are passed to the function as strings. For example, @example my_command hello world @end example @noindent is equivalent to @example my_command ("hello", "world") @end example @noindent The general form of a command call is @example cmdname arg1 arg2 @dots{} @end example @noindent which translates directly to @example cmdname ("arg1", "arg2", @dots{}) @end example If an argument including spaces should be passed to a function in command syntax, (double-)quotes can be used. For example, @example my_command "first argument" "second argument" @end example @noindent is equivalent to @example my_command ("first argument", "second argument") @end example Any function can be used as a command if it accepts string input arguments. For example: @example @group toupper lower_case_arg @result{} ans = LOWER_CASE_ARG @end group @end example Since the arguments are passed as strings to the corresponding function, it is not possible to pass input arguments that are stored in variables. In that case, a command must be called using the function syntax. For example: @example @group strvar = "hello world"; toupper strvar @result{} ans = STRVAR toupper (strvar) @result{} ans = HELLO WORLD @end group @end example Additionally, the return values of functions cannot be assigned to variables using the command syntax. Only the first return argument is assigned to the built-in variable @code{ans}. If the output argument of a command should be assigned to a variable, or multiple output arguments of a function should be returned, the function syntax must be used. @node Organization of Functions @section Organization of Functions Distributed with Octave Many of Octave's standard functions are distributed as function files. They are loosely organized by topic, in subdirectories of @file{@var{octave-home}/share/octave/@var{version}/m}, to make it easier to find them. The following is a list of all the function file subdirectories, and the types of functions you will find there. @table @file @item @@ftp Class functions for the FTP object. @item +containers Package for the containers classes. @item audio Functions for playing and recording sounds. @item deprecated Out-of-date functions which will eventually be removed from Octave. @item elfun Elementary functions, principally trigonometric. @item general Miscellaneous matrix manipulations, like @code{flipud}, @code{rot90}, and @code{triu}, as well as other basic functions, like @code{ismatrix}, @code{narginchk}, etc. @item geometry Functions related to Delaunay triangulation. @item gui Functions for GUI elements like dialog, message box, etc. @item help Functions for Octave's built-in help system. @item image Image processing tools. These functions require the X Window System. @item io Input-output functions. @item java Functions related to the Java integration. @item linear-algebra Functions for linear algebra. @item miscellaneous Functions that don't really belong anywhere else. @item ode Functions to solve ordinary differential equations (ODEs). @item optimization Functions related to minimization, optimization, and root finding. @item path Functions to manage the directory path Octave uses to find functions. @item pkg Package manager for installing external packages of functions in Octave. @item plot Functions for displaying and printing two- and three-dimensional graphs. @item polynomial Functions for manipulating polynomials. @item prefs Functions implementing user-defined preferences. @item set Functions for creating and manipulating sets of unique values. @item signal Functions for signal processing applications. @item sparse Functions for handling sparse matrices. @item specfun Special functions such as @code{bessel} or @code{factor}. @item special-matrix Functions that create special matrix forms such as Hilbert or @nospell{Vandermonde} matrices. @item startup Octave's system-wide startup file. @item statistics Statistical functions. @item strings Miscellaneous string-handling functions. @item testfun Functions for performing unit tests on other functions. @item time Functions related to time and date processing. @end table