This is octave.info, produced by makeinfo version 6.7 from octave.texi. INFO-DIR-SECTION Math START-INFO-DIR-ENTRY * Octave: (octave). Interactive language for numerical computations. END-INFO-DIR-ENTRY Copyright © 1996-2020 John W. Eaton. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.  File: octave.info, Node: Cell Arrays of Strings, Next: Processing Data in Cell Arrays, Prev: Indexing Cell Arrays, Up: Cell Arrays 6.3.4 Cell Arrays of Strings ---------------------------- One common use of cell arrays is to store multiple strings in the same variable. It is also possible to store multiple strings in a character matrix by letting each row be a string. This, however, introduces the problem that all strings must be of equal length. Therefore, it is recommended to use cell arrays to store multiple strings. For cases, where the character matrix representation is required for an operation, there are several functions that convert a cell array of strings to a character array and back. ‘char’ and ‘strvcat’ convert cell arrays to a character array (*note Concatenating Strings::), while the function ‘cellstr’ converts a character array to a cell array of strings: a = ["hello"; "world"]; c = cellstr (a) ⇒ c = { [1,1] = hello [2,1] = world } -- : CSTR = cellstr (STRMAT) Create a new cell array object from the elements of the string array STRMAT. Each row of STRMAT becomes an element of CSTR. Any trailing spaces in a row are deleted before conversion. To convert back from a cellstr to a character array use ‘char’. See also: *note cell: XREFcell, *note char: XREFchar. One further advantage of using cell arrays to store multiple strings is that most functions for string manipulations included with Octave support this representation. As an example, it is possible to compare one string with many others using the ‘strcmp’ function. If one of the arguments to this function is a string and the other is a cell array of strings, each element of the cell array will be compared to the string argument: c = {"hello", "world"}; strcmp ("hello", c) ⇒ ans = 1 0 The following string functions support cell arrays of strings: ‘char’, ‘strvcat’, ‘strcat’ (*note Concatenating Strings::), ‘strcmp’, ‘strncmp’, ‘strcmpi’, ‘strncmpi’ (*note Comparing Strings::), ‘str2double’, ‘deblank’, ‘strtrim’, ‘strtrunc’, ‘strfind’, ‘strmatch’, , ‘regexp’, ‘regexpi’ (*note Manipulating Strings::) and ‘str2double’ (*note String Conversions::). The function ‘iscellstr’ can be used to test if an object is a cell array of strings. -- : iscellstr (CELL) Return true if every element of the cell array CELL is a character string. See also: *note ischar: XREFischar, *note isstring: XREFisstring.  File: octave.info, Node: Processing Data in Cell Arrays, Prev: Cell Arrays of Strings, Up: Cell Arrays 6.3.5 Processing Data in Cell Arrays ------------------------------------ Data that is stored in a cell array can be processed in several ways depending on the actual data. The simplest way to process that data is to iterate through it using one or more ‘for’ loops. The same idea can be implemented more easily through the use of the ‘cellfun’ function that calls a user-specified function on all elements of a cell array. *Note cellfun: XREFcellfun. An alternative is to convert the data to a different container, such as a matrix or a data structure. Depending on the data this is possible using the ‘cell2mat’ and ‘cell2struct’ functions. -- : M = cell2mat (C) Convert the cell array C into a matrix by concatenating all elements of C into a hyperrectangle. Elements of C must be numeric, logical, or char matrices; or cell arrays; or structs; and ‘cat’ must be able to concatenate them together. See also: *note mat2cell: XREFmat2cell, *note num2cell: XREFnum2cell. -- : cell2struct (CELL, FIELDS) -- : cell2struct (CELL, FIELDS, DIM) Convert CELL to a structure. The number of fields in FIELDS must match the number of elements in CELL along dimension DIM, that is ‘numel (FIELDS) == size (CELL, DIM)’. If DIM is omitted, a value of 1 is assumed. A = cell2struct ({"Peter", "Hannah", "Robert"; 185, 170, 168}, {"Name","Height"}, 1); A(1) ⇒ { Name = Peter Height = 185 } See also: *note struct2cell: XREFstruct2cell, *note cell2mat: XREFcell2mat, *note struct: XREFstruct.  File: octave.info, Node: Comma Separated Lists, Prev: Cell Arrays, Up: Data Containers 6.4 Comma Separated Lists ========================= Comma separated lists (1) are the basic argument type to all Octave functions - both for input and return arguments. In the example max (A, B) ‘A, B’ is a comma separated list. Comma separated lists can appear on both the right and left hand side of an assignment. For example x = [1 0 1 0 0 1 1; 0 0 0 0 0 0 7]; [I, J] = find (X, 2, "last"); Here, ‘X, 2, "last"’ is a comma separated list constituting the input arguments of ‘find’. ‘find’ returns a comma separated list of output arguments which is assigned element by element to the comma separated list ‘I, J’. Another example of where comma separated lists are used is in the creation of a new array with ‘[]’ (*note Matrices::) or the creation of a cell array with ‘{}’ (*note Basic Usage of Cell Arrays::). In the expressions a = [1, 2, 3, 4]; c = {4, 5, 6, 7}; both ‘1, 2, 3, 4’ and ‘4, 5, 6, 7’ are comma separated lists. Comma separated lists cannot be directly manipulated by the user. However, both structure arrays and cell arrays can be converted into comma separated lists, and thus used in place of explicitly written comma separated lists. This feature is useful in many ways, as will be shown in the following subsections. * Menu: * Comma Separated Lists Generated from Cell Arrays:: * Comma Separated Lists Generated from Structure Arrays:: ---------- Footnotes ---------- (1) Comma-separated lists are also sometimes informally referred to as “cs-lists”.  File: octave.info, Node: Comma Separated Lists Generated from Cell Arrays, Next: Comma Separated Lists Generated from Structure Arrays, Up: Comma Separated Lists 6.4.1 Comma Separated Lists Generated from Cell Arrays ------------------------------------------------------ As has been mentioned above (*note Indexing Cell Arrays::), elements of a cell array can be extracted into a comma separated list with the ‘{’ and ‘}’ operators. By surrounding this list with ‘[’ and ‘]’, it can be concatenated into an array. For example: a = {1, [2, 3], 4, 5, 6}; b = [a{1:4}] ⇒ b = 1 2 3 4 5 Similarly, it is possible to create a new cell array containing cell elements selected with ‘{}’. By surrounding the list with ‘{’ and ‘}’ a new cell array will be created, as the following example illustrates: a = {1, rand(2, 2), "three"}; b = { a{ [1, 3] } } ⇒ b = { [1,1] = 1 [1,2] = three } Furthermore, cell elements (accessed by ‘{}’) can be passed directly to a function. The list of elements from the cell array will be passed as an argument list to a given function as if it is called with the elements as individual arguments. The two calls to ‘printf’ in the following example are identical but the latter is simpler and can handle cell arrays of an arbitrary size: c = {"GNU", "Octave", "is", "Free", "Software"}; printf ("%s ", c{1}, c{2}, c{3}, c{4}, c{5}); ⊣ GNU Octave is Free Software printf ("%s ", c{:}); ⊣ GNU Octave is Free Software If used on the left-hand side of an assignment, a comma separated list generated with ‘{}’ can be assigned to. An example is in{1} = [10, 20, 30]; in{2} = inf; in{3} = "last"; in{4} = "first"; out = cell (4, 1); [out{1:3}] = in{1 : 3}; [out{4:6}] = in{[1, 2, 4]}) ⇒ out = { [1,1] = 10 20 30 [2,1] = Inf [3,1] = last [4,1] = 10 20 30 [5,1] = Inf [6,1] = first }  File: octave.info, Node: Comma Separated Lists Generated from Structure Arrays, Prev: Comma Separated Lists Generated from Cell Arrays, Up: Comma Separated Lists 6.4.2 Comma Separated Lists Generated from Structure Arrays ----------------------------------------------------------- Structure arrays can equally be used to create comma separated lists. This is done by addressing one of the fields of a structure array. For example: x = ceil (randn (10, 1)); in = struct ("call1", {x, 3, "last"}, "call2", {x, inf, "first"}); out = struct ("call1", cell (2, 1), "call2", cell (2, 1)); [out.call1] = find (in.call1); [out.call2] = find (in.call2);  File: octave.info, Node: Variables, Next: Expressions, Prev: Data Containers, Up: Top 7 Variables *********** Variables let you give names to values and refer to them later. You have already seen variables in many of the examples. The name of a variable must be a sequence of letters, digits and underscores, but it may not begin with a digit. Octave does not enforce a limit on the length of variable names, but it is seldom useful to have variables with names longer than about 30 characters. The following are all valid variable names x x15 __foo_bar_baz__ fucnrdthsucngtagdjb However, names like ‘__foo_bar_baz__’ that begin and end with two underscores are understood to be reserved for internal use by Octave. You should not use them in code you write, except to access Octave’s documented internal variables and built-in symbolic constants. Case is significant in variable names. The symbols ‘a’ and ‘A’ are distinct variables. A variable name is a valid expression by itself. It represents the variable’s current value. Variables are given new values with “assignment operators” and “increment operators”. *Note Assignment Expressions: Assignment Ops. There is one automatically created variable with a special meaning. The ‘ans’ variable always contains the result of the last computation, where the output wasn’t assigned to any variable. The code ‘a = cos (pi)’ will assign the value -1 to the variable ‘a’, but will not change the value of ‘ans’. However, the code ‘cos (pi)’ will set the value of ‘ans’ to -1. Variables in Octave do not have fixed types, so it is possible to first store a numeric value in a variable and then to later use the same name to hold a string value in the same program. Variables may not be used before they have been given a value. Doing so results in an error. -- Automatic Variable: ans The most recently computed result that was not explicitly assigned to a variable. For example, after the expression 3^2 + 4^2 is evaluated, the value returned by ‘ans’ is 25. -- : isvarname (NAME) Return true if NAME is a valid variable name. A valid variable name is composed of letters, digits, and underscores ("_"), and the first character must not be a digit. See also: *note iskeyword: XREFiskeyword, *note exist: XREFexist, *note who: XREFwho. -- : VARNAME = matlab.lang.makeValidName (STR) -- : VARNAME = matlab.lang.makeValidName (..., "ReplacementStyle", RS) -- : VARNAME = matlab.lang.makeValidName (..., "Prefix", PFX) -- : [VARNAME, ISMODIFIED] = matlab.lang.makeValidName (...) Create valid variable name VARNAME from STR. The input STR must be a string or a cell array of strings. The output VARNAME will be of the same type. A valid variable name is a sequence of letters, digits, and underscores that does not begin with a digit. The "ReplacementStyle" option specifies how invalid characters are handled. Acceptable values are "underscore" (default) Replace all invalid characters with an underscore ("_"). "delete" Remove any invalid character. "hex" Replace all invalid characters with their hexadecimal representation. Whitespace characters are always removed *prior* to the application of the "ReplacementStyle". Lowercase letters following a whitespace will be changed to uppercase. The "Prefix" option specifies the string PFX to add as a prefix to the input if it begins with a digit. PFX must be a valid variable name itself. The default prefix is "x". The optional output ISMODIFIED is a logical array indicating whether the respective element in STR was a valid name or not. See also: *note iskeyword: XREFiskeyword, *note isvarname: XREFisvarname, *note matlab.lang.makeUniqueStrings: XREFmatlab_lang_makeUniqueStrings. -- : UNIQSTR = matlab.lang.makeUniqueStrings (STR) -- : UNIQSTR = matlab.lang.makeUniqueStrings (STR, EX) -- : UNIQSTR = matlab.lang.makeUniqueStrings (STR, EX, MAXLENGTH) -- : [UNIQSTR, ISMODIFIED] = matlab.lang.makeUniqueStrings (...) Construct a list of unique strings from a list of strings. The input STR must be a string or a cell array of strings. The output UNIQSTR will be of the same type. The algorithm makes two strings unique by appending an underscore ("_" and a numeric count to the second string. If EX is a string or a cell array of strings, UNIQSTR will contain elements that are unique between themselves and with respect to EX. If EX is an index array or a logical array for STR then it selects the subset of STR that are made unique. Unselected elements are not modified. The optional input MAXLENGTH specifies the maximum length of any string in UNIQSTR. If an input string cannot be made unique without exceeding MAXLENGTH an error is emitted. The optional output ISMODIFIED is a logical array indicating whether each element in STR was modified to make it unique. See also: *note unique: XREFunique, *note matlab.lang.makeValidName: XREFmatlab_lang_makeValidName. -- : namelengthmax () Return the MATLAB compatible maximum variable name length. Octave is capable of storing strings up to 2^{31} - 1 in length. However for MATLAB compatibility all variable, function, and structure field names should be shorter than the length returned by ‘namelengthmax’. In particular, variables stored to a MATLAB file format (‘*.mat’) will have their names truncated to this length. * Menu: * Global Variables:: * Persistent Variables:: * Status of Variables::  File: octave.info, Node: Global Variables, Next: Persistent Variables, Up: Variables 7.1 Global Variables ==================== A “global” variable is one that may be accessed anywhere within Octave. This is in contrast to a local variable which can only be accessed outside of its current context if it is passed explicitly, such as by including it as a parameter when calling a function (‘fcn (LOCAL_VAR1, LOCAL_VAR2)’). A variable is declared global by using a ‘global’ declaration statement. The following statements are all global declarations. global a global a b global c = 2 global d = 3 e f = 5 Note that the ‘global’ qualifier extends only to the next end-of-statement indicator which could be a comma (‘,’), semicolon (‘;’), or newline (‘'\n'’). For example, the following code declares one global variable, A, and one local variable B to which the value 1 is assigned. global a, b = 1 A global variable may only be initialized once in a ‘global’ statement. For example, after executing the following code global gvar = 1 global gvar = 2 the value of the global variable ‘gvar’ is 1, not 2. Issuing a ‘clear gvar’ command does not change the above behavior, but ‘clear all’ does. It is necessary declare a variable as global within a function body in order to access the one universal variable. For example, global x function f () x = 1; endfunction f () does _not_ set the value of the global variable ‘x’ to 1. Instead, a local variable, with name ‘x’, is created and assigned the value of 1. In order to change the value of the global variable ‘x’, you must also declare it to be global within the function body, like this function f () global x; x = 1; endfunction Passing a global variable in a function parameter list will make a local copy and _not_ modify the global value. For example, given the function function f (x) x = 0 endfunction and the definition of ‘x’ as a global variable at the top level, global x = 13 the expression f (x) will display the value of ‘x’ from inside the function as 0, but the value of ‘x’ at the top level remains unchanged, because the function works with a _copy_ of its argument. Programming Note: While global variables occasionally are the right solution to a coding problem, modern best practice discourages their use. Code which relies on global variables may behave unpredictably between different users and can be difficult to debug. This is because global variables can introduce systemic changes so that localizing a bug to a particular function, or to a particular loop within a function, becomes difficult. -- : isglobal (NAME) Return true if NAME is a globally visible variable. For example: global x isglobal ("x") ⇒ 1 See also: *note isvarname: XREFisvarname, *note exist: XREFexist.  File: octave.info, Node: Persistent Variables, Next: Status of Variables, Prev: Global Variables, Up: Variables 7.2 Persistent Variables ======================== A variable that has been declared “persistent” within a function will retain its contents in memory between subsequent calls to the same function. The difference between persistent variables and global variables is that persistent variables are local in scope to a particular function and are not visible elsewhere. The following example uses a persistent variable to create a function that prints the number of times it has been called. function count_calls () persistent calls = 0; printf ("'count_calls' has been called %d times\n", ++calls); endfunction for i = 1:3 count_calls (); endfor ⊣ 'count_calls' has been called 1 times ⊣ 'count_calls' has been called 2 times ⊣ 'count_calls' has been called 3 times As the example shows, a variable may be declared persistent using a ‘persistent’ declaration statement. The following statements are all persistent declarations. persistent a persistent a b persistent c = 2 persistent d = 3 e f = 5 The behavior of persistent variables is equivalent to the behavior of static variables in C. One restriction for persistent variables is, that neither input nor output arguments of a function can be persistent: function y = foo () persistent y = 0; # Not allowed! endfunction foo () ⊣ error: can't make function parameter y persistent Like global variables, a persistent variable may only be initialized once. For example, after executing the following code persistent pvar = 1 persistent pvar = 2 the value of the persistent variable ‘pvar’ is 1, not 2. If a persistent variable is declared but not initialized to a specific value, it will contain an empty matrix. So, it is also possible to initialize a persistent variable by checking whether it is empty, as the following example illustrates. function count_calls () persistent calls; if (isempty (calls)) calls = 0; endif printf ("'count_calls' has been called %d times\n", ++calls); endfunction This implementation behaves in exactly the same way as the previous implementation of ‘count_calls’. The value of a persistent variable is kept in memory until it is explicitly cleared. Assuming that the implementation of ‘count_calls’ is saved on disk, we get the following behavior. for i = 1:2 count_calls (); endfor ⊣ 'count_calls' has been called 1 times ⊣ 'count_calls' has been called 2 times clear for i = 1:2 count_calls (); endfor ⊣ 'count_calls' has been called 3 times ⊣ 'count_calls' has been called 4 times clear all for i = 1:2 count_calls (); endfor ⊣ 'count_calls' has been called 1 times ⊣ 'count_calls' has been called 2 times clear count_calls for i = 1:2 count_calls (); endfor ⊣ 'count_calls' has been called 1 times ⊣ 'count_calls' has been called 2 times That is, the persistent variable is only removed from memory when the function containing the variable is removed. Note that if the function definition is typed directly into the Octave prompt, the persistent variable will be cleared by a simple ‘clear’ command as the entire function definition will be removed from memory. If you do not want a persistent variable to be removed from memory even if the function is cleared, you should use the ‘mlock’ function (*note Function Locking::).  File: octave.info, Node: Status of Variables, Prev: Persistent Variables, Up: Variables 7.3 Status of Variables ======================= When creating simple one-shot programs it can be very convenient to see which variables are available at the prompt. The function ‘who’ and its siblings ‘whos’ and ‘whos_line_format’ will show different information about what is in memory, as the following shows. str = "A random string"; who ⊣ Variables in the current scope: ⊣ ⊣ ans str -- : who -- : who pattern ... -- : who option pattern ... -- : C = who ("pattern", ...) List currently defined variables matching the given patterns. Valid pattern syntax is the same as described for the ‘clear’ command. If no patterns are supplied, all variables are listed. By default, only variables visible in the local scope are displayed. The following are valid options, but may not be combined. ‘global’ List variables in the global scope rather than the current scope. ‘-regexp’ The patterns are considered to be regular expressions when matching the variables to display. The same pattern syntax accepted by the ‘regexp’ function is used. ‘-file’ The next argument is treated as a filename. All variables found within the specified file are listed. No patterns are accepted when reading variables from a file. If called as a function, return a cell array of defined variable names matching the given patterns. See also: *note whos: XREFwhos, *note isglobal: XREFisglobal, *note isvarname: XREFisvarname, *note exist: XREFexist, *note regexp: XREFregexp. -- : whos -- : whos pattern ... -- : whos option pattern ... -- : S = whos ("pattern", ...) Provide detailed information on currently defined variables matching the given patterns. Options and pattern syntax are the same as for the ‘who’ command. Extended information about each variable is summarized in a table with the following default entries. Attr Attributes of the listed variable. Possible attributes are: blank Variable in local scope ‘c’ Variable of complex type. ‘f’ Formal parameter (function argument). ‘g’ Variable with global scope. ‘p’ Persistent variable. Name The name of the variable. Size The logical size of the variable. A scalar is 1x1, a vector is 1xN or Nx1, a 2-D matrix is MxN. Bytes The amount of memory currently used to store the variable. Class The class of the variable. Examples include double, single, char, uint16, cell, and struct. The table can be customized to display more or less information through the function ‘whos_line_format’. If ‘whos’ is called as a function, return a struct array of defined variable names matching the given patterns. Fields in the structure describing each variable are: name, size, bytes, class, global, sparse, complex, nesting, persistent. See also: *note who: XREFwho, *note whos_line_format: XREFwhos_line_format. -- : VAL = whos_line_format () -- : OLD_VAL = whos_line_format (NEW_VAL) -- : whos_line_format (NEW_VAL, "local") Query or set the format string used by the command ‘whos’. A full format string is: %[modifier][:width[:left-min[:balance]]]; The following command sequences are available: ‘%a’ Prints attributes of variables (g=global, p=persistent, f=formal parameter). ‘%b’ Prints number of bytes occupied by variables. ‘%c’ Prints class names of variables. ‘%e’ Prints elements held by variables. ‘%n’ Prints variable names. ‘%s’ Prints dimensions of variables. ‘%t’ Prints type names of variables. Every command may also have an alignment modifier: ‘l’ Left alignment. ‘r’ Right alignment (default). ‘c’ Column-aligned (only applicable to command %s). The ‘width’ parameter is a positive integer specifying the minimum number of columns used for printing. No maximum is needed as the field will auto-expand as required. The parameters ‘left-min’ and ‘balance’ are only available when the column-aligned modifier is used with the command ‘%s’. ‘balance’ specifies the column number within the field width which will be aligned between entries. Numbering starts from 0 which indicates the leftmost column. ‘left-min’ specifies the minimum field width to the left of the specified balance column. The default format is: " %a:4; %ln:6; %cs:16:6:1; %rb:12; %lc:-1;\n" When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note whos: XREFwhos. Instead of displaying which variables are in memory, it is possible to determine if a given variable is available. That way it is possible to alter the behavior of a program depending on the existence of a variable. The following example illustrates this. if (! exist ("meaning", "var")) disp ("The program has no 'meaning'"); endif -- : C = exist (NAME) -- : C = exist (NAME, TYPE) Check for the existence of NAME as a variable, function, file, directory, or class. The return code C is one of 1 NAME is a variable. 2 NAME is an absolute filename, an ordinary file in Octave’s ‘path’, or (after appending ‘.m’) a function file in Octave’s ‘path’. 3 NAME is a ‘.oct’ or ‘.mex’ file in Octave’s ‘path’. 5 NAME is a built-in function. 7 NAME is a directory. 8 NAME is a class. (Note: not currently implemented) 103 NAME is a function not associated with a file (entered on the command line). 0 NAME does not exist. If the optional argument TYPE is supplied, check only for symbols of the specified type. Valid types are "var" Check only for variables. "builtin" Check only for built-in functions. "dir" Check only for directories. "file" Check only for files and directories. "class" Check only for classes. (Note: This option is accepted, but not currently implemented) If no type is given, and there are multiple possible matches for name, ‘exist’ will return a code according to the following priority list: variable, built-in function, oct-file, directory, file, class. ‘exist’ returns 2 if a regular file called NAME is present in Octave’s search path. For information about other types of files not on the search path use some combination of the functions ‘file_in_path’ and ‘stat’ instead. Programming Note: If NAME is implemented by a buggy .oct/.mex file, calling EXIST may cause Octave to crash. To maintain high performance, Octave trusts .oct/.mex files instead of sandboxing them. See also: *note file_in_loadpath: XREFfile_in_loadpath, *note file_in_path: XREFfile_in_path, *note dir_in_loadpath: XREFdir_in_loadpath, *note stat: XREFstat. Usually Octave will manage the memory, but sometimes it can be practical to remove variables from memory manually. This is usually needed when working with large variables that fill a substantial part of the memory. On a computer that uses the IEEE floating point format, the following program allocates a matrix that requires around 128 MB memory. large_matrix = zeros (4000, 4000); Since having this variable in memory might slow down other computations, it can be necessary to remove it manually from memory. The ‘clear’ or ‘clearvars’ functions do this. -- : clear -- : clear PATTERN ... -- : clear OPTIONS PATTERN ... Delete the names matching the given PATTERNs thereby freeing memory. The PATTERN may contain the following special characters: ‘?’ Match any single character. ‘*’ Match zero or more characters. ‘[ LIST ]’ Match the list of characters specified by LIST. If the first character is ‘!’ or ‘^’, match all characters except those specified by LIST. For example, the pattern ‘[a-zA-Z]’ will match all lowercase and uppercase alphabetic characters. For example, the command clear foo b*r clears the name ‘foo’ and all names that begin with the letter ‘b’ and end with the letter ‘r’. If ‘clear’ is called without any arguments, all user-defined variables are cleared from the current workspace (i.e., local variables). Any global variables present will no longer be visible in the current workspace, but they will continue to exist in the global workspace. Functions are unaffected by this form of ‘clear’. The following options are available in both long and short form ‘all, -all, -a’ Clear all local and global user-defined variables, and all functions from the symbol table. ‘-exclusive, -x’ Clear variables that do *not* match the following pattern. ‘functions, -functions, -f’ Clear function names from the function symbol table. Persistent variables will be re-initialized to their default value unless the function has been locked in memory with ‘mlock’. ‘global, -global, -g’ Clear global variable names. ‘variables, -variables, -v’ Clear local variable names. ‘classes, -classes, -c’ Clear the class structure table and all objects. ‘-regexp, -r’ The PATTERN arguments are treated as regular expressions and any matches will be cleared. With the exception of ‘-exclusive’ and ‘-regexp’, all long options can be used without the dash as well. Note that, aside from ‘-exclusive’, only one other option may appear. All options must appear before any patterns. Programming Notes: The command ‘clear NAME’ only clears the variable NAME when both a variable and a (shadowed) function named NAME are currently defined. For example, suppose you have defined a function ‘foo’, and then hidden it by performing the assignment ‘foo = 2’. Executing the command ‘clear foo’ once will clear the variable definition and restore the definition of ‘foo’ as a function. Executing ‘clear foo’ a second time will clear the function definition. When a local variable name, which is linked to a global variable, is cleared only the local copy of the variable is removed. The global copy is untouched and can be restored with ‘global GLOBAL_VARNAME’. Conversely, ‘clear -g GLOBAL_VARNAME’ will remove both the local and global variables. See also: *note clearvars: XREFclearvars, *note who: XREFwho, *note whos: XREFwhos, *note exist: XREFexist, *note mlock: XREFmlock. -- : clearvars -- : clearvars PATTERN ... -- : clearvars -regexp PATTERN ... -- : clearvars ... -except PATTERN ... -- : clearvars ... -except -regexp PATTERN ... -- : clearvars -global ... Delete the variables matching the given PATTERNs from memory. The PATTERN may contain the following special characters: ‘?’ Match any single character. ‘*’ Match zero or more characters. ‘[ LIST ]’ Match the list of characters specified by LIST. If the first character is ‘!’ or ‘^’, match all characters except those specified by LIST. For example, the pattern ‘[a-zA-Z]’ will match all lowercase and uppercase alphabetic characters. If the ‘-regexp’ option is given then subsequent patterns are treated as regular expressions and any matches will be cleared. If the ‘-except’ option is given then subsequent patterns select variables that will *not* be cleared. If the ‘-global’ option is given then all patterns will be applied to global variables rather than local variables. When called with no arguments, ‘clearvars’ deletes all local variables. Example Code: Clear all variables starting with ’x’ and the specific variable "foobar" clearvars x* foobar Clear the specific variable "foobar" and use regular expressions to clear all variables starting with ’x’ or ’y’. clearvars foobar -regexp ^x ^y Clear all variables except for "foobar" clearvars -except foobar Clear all variables beginning with "foo", except for those ending in "bar" clearvars foo* -except -regexp bar$ See also: *note clear: XREFclear, *note who: XREFwho, *note whos: XREFwhos, *note exist: XREFexist. -- : pack () Consolidate workspace memory in MATLAB. This function is provided for compatibility, but does nothing in Octave. See also: *note clear: XREFclear. Information about a function or variable such as its location in the file system can also be acquired from within Octave. This is usually only useful during development of programs, and not within a program. -- : type NAME ... -- : type -q NAME ... -- : text = type ("NAME", ...) Display the contents of NAME which may be a file, function (m-file), variable, operator, or keyword. ‘type’ normally prepends a header line describing the category of NAME such as function or variable; The ‘-q’ option suppresses this behavior. If no output variable is used the contents are displayed on screen. Otherwise, a cell array of strings is returned, where each element corresponds to the contents of each requested function. -- : which name ... Display the type of each NAME. If NAME is defined from a function file, the full name of the file is also displayed. See also: *note help: XREFhelp, *note lookfor: XREFlookfor. -- : what -- : what DIR -- : w = what (DIR) List the Octave specific files in directory DIR. If DIR is not specified then the current directory is used. If a return argument is requested, the files found are returned in the structure W. The structure contains the following fields: path Full path to directory DIR m Cell array of m-files mat Cell array of mat files mex Cell array of mex files oct Cell array of oct files mdl Cell array of mdl files slx Cell array of slx files p Cell array of p-files classes Cell array of class directories (‘@CLASSNAME/’) packages Cell array of package directories (‘+PKGNAME/’) Compatibility Note: Octave does not support mdl, slx, and p files. ‘what’ will always return an empty list for these categories. See also: *note which: XREFwhich, *note ls: XREFls, *note exist: XREFexist.  File: octave.info, Node: Expressions, Next: Evaluation, Prev: Variables, Up: Top 8 Expressions ************* Expressions are the basic building block of statements in Octave. An expression evaluates to a value, which you can print, test, store in a variable, pass to a function, or assign a new value to a variable with an assignment operator. An expression can serve as a statement on its own. Most other kinds of statements contain one or more expressions which specify data to be operated on. As in other languages, expressions in Octave include variables, array references, constants, and function calls, as well as combinations of these with various operators. * Menu: * Index Expressions:: * Calling Functions:: * Arithmetic Ops:: * Comparison Ops:: * Boolean Expressions:: * Assignment Ops:: * Increment Ops:: * Operator Precedence::  File: octave.info, Node: Index Expressions, Next: Calling Functions, Up: Expressions 8.1 Index Expressions ===================== An “index expression” allows you to reference or extract selected elements of a vector, a matrix (2-D), or a higher-dimensional array. Indices may be scalars, vectors, ranges, or the special operator ‘:’, which selects entire rows, columns, or higher-dimensional slices. An index expression consists of a set of parentheses enclosing M expressions separated by commas. Each individual index value, or component, is used for the respective dimension of the object that it is applied to. In other words, the first index component is used for the first dimension (rows) of the object, the second index component is used for the second dimension (columns) of the object, and so on. The number of index components M defines the dimensionality of the index expression. An index with two components would be referred to as a 2-D index because it has two dimensions. In the simplest case, 1) all components are scalars, and 2) the dimensionality of the index expression M is equal to the dimensionality of the object it is applied to. For example: A = reshape (1:8, 2, 2, 2) # Create 3-D array A = ans(:,:,1) = 1 3 2 4 ans(:,:,2) = 5 7 6 8 A(2, 1, 2) # second row, first column of second slice # in third dimension: ans = 6 The size of the returned object in a specific dimension is equal to the number of elements in the corresponding component of the index expression. When all components are scalars, the result is a single output value. However, if any component is a vector or range then the returned values are the Cartesian product of the indices in the respective dimensions. For example: A([1, 2], 1, 2) ≡ [A(1,1,2); A(2,1,2)] ⇒ ans = 5 6 The total number of returned values is the product of the number of elements returned for each index component. In the example above, the total is 2*1*1 = 2 elements. Notice that the size of the returned object in a given dimension is equal to the number of elements in the index expression for that dimension. In the code above, the first index component (‘[1, 2]’) was specified as a row vector, but its shape is unimportant. The important fact is that the component specified two values, and hence the result must have a size of two in the first dimension; and because the first dimension corresponds to rows, the overall result is a column vector. A(1, [2, 1, 1], 1) # result is a row vector: ans = [3, 1, 1] A(ones (2, 2), 1, 1) # result is a column vector: ans = [1; 1; 1; 1] The first line demonstrates again that the size of the output in a given dimension is equal to the number of elements in the respective indexing component. In this case, the output has three elements in the second dimension (which corresponds to columns), so the result is a row vector. The example also shows how repeating entries in the index expression can be used to replicate elements in the output. The last example further proves that the shape of the indexing component is irrelevant, it is only the number of elements (2x2 = 4) which is important. The above rules apply whenever the dimensionality of the index expression is greater than one (M > 1). However, for one-dimensional index expressions special rules apply and the shape of the output *is* determined by the shape of the indexing component. For example: A([1, 2]) # result is a row vector: ans = [1, 2] A([1; 2]) # result is a column vector: ans = [1; 2] Note that it is permissible to use a 1-D index with a multi-dimensional object (also called linear indexing). In this case, the elements of the multi-dimensional array are taken in column-first order like Fortran. That is, the columns of the array are imagined to be stacked on top of each other to form a column vector and then the single linear index is applied to this vector. A(5) # linear indexing into three-dimensional array: ans = 5 A(3:5) # result has shape of index component: ans = [3, 4, 5] A colon (‘:’) may be used as an index component to select all of the elements in a specified dimension. Given the matrix, A = [1, 2; 3, 4] all of the following expressions are equivalent and select the first row of the matrix. A(1, [1, 2]) # row 1, columns 1 and 2 A(1, 1:2) # row 1, columns in range 1-2 A(1, :) # row 1, all columns When a colon is used in the special case of 1-D indexing the result is always a column vector. Creating column vectors with a colon index is a very frequently encountered code idiom and is faster and generally clearer than calling ‘reshape’ for this case. A(:) # result is column vector: ans = [1; 2; 3; 4] A(:)' # result is row vector: ans = [1, 2, 3, 4] In index expressions the keyword ‘end’ automatically refers to the last entry for a particular dimension. This magic index can also be used in ranges and typically eliminates the needs to call ‘size’ or ‘length’ to gather array bounds before indexing. For example: A(1:end/2) # first half of A => [1, 2] A(end + 1) = 5; # append element A(end) = []; # delete element A(1:2:end) # odd elements of A => [1, 3] A(2:2:end) # even elements of A => [2, 4] A(end:-1:1) # reversal of A => [4, 3, 2, 1] * Menu: * Advanced Indexing::  File: octave.info, Node: Advanced Indexing, Up: Index Expressions 8.1.1 Advanced Indexing ----------------------- When it is necessary to extract subsets of entries out of an array whose indices cannot be written as a Cartesian product of components, linear indexing together with the function ‘sub2ind’ can be used. For example: A = reshape (1:8, 2, 2, 2) # Create 3-D array A = ans(:,:,1) = 1 3 2 4 ans(:,:,2) = 5 7 6 8 A(sub2ind (size (A), [1, 2, 1], [1, 1, 2], [1, 2, 1])) ⇒ ans = [A(1, 1, 1), A(2, 1, 2), A(1, 2, 1)] An array with ‘nd’ dimensions can be indexed by an index expression which has from 1 to ‘nd’ components. For the ordinary and most common case, the number of components ‘M’ matches the number of dimensions ‘nd’. In this case the ordinary indexing rules apply and each component corresponds to the respective dimension of the array. However, if the number of indexing components exceeds the number of dimensions (‘M > nd’) then the excess components must all be singletons (‘1’). Moreover, if ‘M < nd’, the behavior is equivalent to reshaping the input object so as to merge the trailing ‘nd - M’ dimensions into the last index dimension ‘M’. Thus, the result will have the dimensionality of the index expression, and not the original object. This is the case whenever dimensionality of the index is greater than one (‘M > 1’), so that the special rules for linear indexing are not applied. This is easiest to understand with an example: A = reshape (1:8, 2, 2, 2) # Create 3-D array A = ans(:,:,1) = 1 3 2 4 ans(:,:,2) = 5 7 6 8 ## 2-D indexing causes third dimension to be merged into second dimension. ## Equivalent array for indexing, Atmp, is now 2x4. Atmp = reshape (A, 2, 4) Atmp = 1 3 5 7 2 4 6 8 A(2,1) # Reshape to 2x4 matrix, second entry of first column: ans = 2 A(2,4) # Reshape to 2x4 matrix, second entry of fourth column: ans = 8 A(:,:) # Reshape to 2x4 matrix, select all rows & columns, ans = Atmp Note here the elegant use of the double colon to replace the call to the ‘reshape’ function. Another advanced use of linear indexing is to create arrays filled with a single value. This can be done by using an index of ones on a scalar value. The result is an object with the dimensions of the index expression and every element equal to the original scalar. For example, the following statements a = 13; a(ones (1, 4)) produce a row vector whose four elements are all equal to 13. Similarly, by indexing a scalar with two vectors of ones it is possible to create a matrix. The following statements a = 13; a(ones (1, 2), ones (1, 3)) create a 2x3 matrix with all elements equal to 13. This could also have been written as 13(ones (2, 3)) It is more efficient to use indexing rather than the code construction ‘scalar * ones (M, N, ...)’ because it avoids the unnecessary multiplication operation. Moreover, multiplication may not be defined for the object to be replicated whereas indexing an array is always defined. The following code shows how to create a 2x3 cell array from a base unit which is not itself a scalar. {"Hello"}(ones (2, 3)) It should be noted that ‘ones (1, n)’ (a row vector of ones) results in a range object (with zero increment). A range is stored internally as a starting value, increment, end value, and total number of values; hence, it is more efficient for storage than a vector or matrix of ones whenever the number of elements is greater than 4. In particular, when ‘r’ is a row vector, the expressions r(ones (1, n), :) r(ones (n, 1), :) will produce identical results, but the first one will be significantly faster, at least for ‘r’ and ‘n’ large enough. In the first case the index is held in compressed form as a range which allows Octave to choose a more efficient algorithm to handle the expression. A general recommendation for users unfamiliar with these techniques is to use the function ‘repmat’ for replicating smaller arrays into bigger ones, which uses such tricks. A second use of indexing is to speed up code. Indexing is a fast operation and judicious use of it can reduce the requirement for looping over individual array elements, which is a slow operation. Consider the following example which creates a 10-element row vector a containing the values a(i) = sqrt (i). for i = 1:10 a(i) = sqrt (i); endfor It is quite inefficient to create a vector using a loop like this. In this case, it would have been much more efficient to use the expression a = sqrt (1:10); which avoids the loop entirely. In cases where a loop cannot be avoided, or a number of values must be combined to form a larger matrix, it is generally faster to set the size of the matrix first (pre-allocate storage), and then insert elements using indexing commands. For example, given a matrix ‘a’, [nr, nc] = size (a); x = zeros (nr, n * nc); for i = 1:n x(:,(i-1)*nc+1:i*nc) = a; endfor is considerably faster than x = a; for i = 1:n-1 x = [x, a]; endfor because Octave does not have to repeatedly resize the intermediate result. -- : IND = sub2ind (DIMS, I, J) -- : IND = sub2ind (DIMS, S1, S2, ..., SN) Convert subscripts to linear indices. The input DIMS is a dimension vector where each element is the size of the array in the respective dimension (*note size: XREFsize.). The remaining inputs are scalars or vectors of subscripts to be converted. The output vector IND contains the converted linear indices. Background: Array elements can be specified either by a linear index which starts at 1 and runs through the number of elements in the array, or they may be specified with subscripts for the row, column, page, etc. The functions ‘ind2sub’ and ‘sub2ind’ interconvert between the two forms. The linear index traverses dimension 1 (rows), then dimension 2 (columns), then dimension 3 (pages), etc. until it has numbered all of the elements. Consider the following 3-by-3 matrices: [(1,1), (1,2), (1,3)] [1, 4, 7] [(2,1), (2,2), (2,3)] ==> [2, 5, 8] [(3,1), (3,2), (3,3)] [3, 6, 9] The left matrix contains the subscript tuples for each matrix element. The right matrix shows the linear indices for the same matrix. The following example shows how to convert the two-dimensional indices ‘(2,1)’ and ‘(2,3)’ of a 3-by-3 matrix to linear indices with a single call to ‘sub2ind’. s1 = [2, 2]; s2 = [1, 3]; ind = sub2ind ([3, 3], s1, s2) ⇒ ind = 2 8 See also: *note ind2sub: XREFind2sub, *note size: XREFsize. -- : [S1, S2, ..., SN] = ind2sub (DIMS, IND) Convert linear indices to subscripts. The input DIMS is a dimension vector where each element is the size of the array in the respective dimension (*note size: XREFsize.). The second input IND contains linear indies to be converted. The outputs S1, ..., SN contain the converted subscripts. Background: Array elements can be specified either by a linear index which starts at 1 and runs through the number of elements in the array, or they may be specified with subscripts for the row, column, page, etc. The functions ‘ind2sub’ and ‘sub2ind’ interconvert between the two forms. The linear index traverses dimension 1 (rows), then dimension 2 (columns), then dimension 3 (pages), etc. until it has numbered all of the elements. Consider the following 3-by-3 matrices: [1, 4, 7] [(1,1), (1,2), (1,3)] [2, 5, 8] ==> [(2,1), (2,2), (2,3)] [3, 6, 9] [(3,1), (3,2), (3,3)] The left matrix contains the linear indices for each matrix element. The right matrix shows the subscript tuples for the same matrix. The following example shows how to convert the two-dimensional indices ‘(2,1)’ and ‘(2,3)’ of a 3-by-3 matrix to linear indices with a single call to ‘sub2ind’. The following example shows how to convert the linear indices ‘2’ and ‘8’ in a 3-by-3 matrix into subscripts. ind = [2, 8]; [r, c] = ind2sub ([3, 3], ind) ⇒ r = 2 2 ⇒ c = 1 3 If the number of output subscripts exceeds the number of dimensions, the exceeded dimensions are set to ‘1’. On the other hand, if fewer subscripts than dimensions are provided, the exceeding dimensions are merged into the final requested dimension. For clarity, consider the following examples: ind = [2, 8]; dims = [3, 3]; ## same as dims = [3, 3, 1] [r, c, s] = ind2sub (dims, ind) ⇒ r = 2 2 ⇒ c = 1 3 ⇒ s = 1 1 ## same as dims = [9] r = ind2sub (dims, ind) ⇒ r = 2 8 See also: *note sub2ind: XREFsub2ind, *note size: XREFsize. -- : isindex (IND) -- : isindex (IND, N) Return true if IND is a valid index. Valid indices are either positive integers (although possibly of real data type), or logical arrays. If present, N specifies the maximum extent of the dimension to be indexed. When possible the internal result is cached so that subsequent indexing using IND will not perform the check again. Implementation Note: Strings are first converted to double values before the checks for valid indices are made. Unless a string contains the NULL character "\0", it will always be a valid index.  File: octave.info, Node: Calling Functions, Next: Arithmetic Ops, Prev: Index Expressions, Up: Expressions 8.2 Calling Functions ===================== A “function” is a name for a particular calculation. Because it has a name, you can ask for it by name at any point in the program. For example, the function ‘sqrt’ computes the square root of a number. A fixed set of functions are “built-in”, which means they are available in every Octave program. The ‘sqrt’ function is one of these. In addition, you can define your own functions. *Note Functions and Scripts::, for information about how to do this. The way to use a function is with a “function call” expression, which consists of the function name followed by a list of “arguments” in parentheses. The arguments are expressions which give the raw materials for the calculation that the function will do. When there is more than one argument, they are separated by commas. If there are no arguments, you can omit the parentheses, but it is a good idea to include them anyway, to clearly indicate that a function call was intended. Here are some examples: sqrt (x^2 + y^2) # One argument ones (n, m) # Two arguments rand () # No arguments Each function expects a particular number of arguments. For example, the ‘sqrt’ function must be called with a single argument, the number to take the square root of: sqrt (ARGUMENT) Some of the built-in functions take a variable number of arguments, depending on the particular usage, and their behavior is different depending on the number of arguments supplied. Like every other expression, the function call has a value, which is computed by the function based on the arguments you give it. In this example, the value of ‘sqrt (ARGUMENT)’ is the square root of the argument. A function can also have side effects, such as assigning the values of certain variables or doing input or output operations. Unlike most languages, functions in Octave may return multiple values. For example, the following statement [u, s, v] = svd (a) computes the singular value decomposition of the matrix ‘a’ and assigns the three result matrices to ‘u’, ‘s’, and ‘v’. The left side of a multiple assignment expression is itself a list of expressions, that is, a list of variable names potentially qualified by index expressions. See also *note Index Expressions::, and *note Assignment Ops::. * Menu: * Call by Value:: * Recursion:: * Access via Handle::  File: octave.info, Node: Call by Value, Next: Recursion, Up: Calling Functions 8.2.1 Call by Value ------------------- In Octave, unlike Fortran, function arguments are passed by value, which means that each argument in a function call is evaluated and assigned to a temporary location in memory before being passed to the function. There is currently no way to specify that a function parameter should be passed by reference instead of by value. This means that it is impossible to directly alter the value of a function parameter in the calling function. It can only change the local copy within the function body. For example, the function function f (x, n) while (n-- > 0) disp (x); endwhile endfunction displays the value of the first argument N times. In this function, the variable N is used as a temporary variable without having to worry that its value might also change in the calling function. Call by value is also useful because it is always possible to pass constants for any function parameter without first having to determine that the function will not attempt to modify the parameter. The caller may use a variable as the expression for the argument, but the called function does not know this: it only knows what value the argument had. For example, given a function called as foo = "bar"; fcn (foo) you should not think of the argument as being “the variable ‘foo’.” Instead, think of the argument as the string value, "bar". Even though Octave uses pass-by-value semantics for function arguments, values are not copied unnecessarily. For example, x = rand (1000); f (x); does not actually force two 1000 by 1000 element matrices to exist _unless_ the function ‘f’ modifies the value of its argument. Then Octave must create a copy to avoid changing the value outside the scope of the function ‘f’, or attempting (and probably failing!) to modify the value of a constant or the value of a temporary result.  File: octave.info, Node: Recursion, Next: Access via Handle, Prev: Call by Value, Up: Calling Functions 8.2.2 Recursion --------------- With some restrictions(1), recursive function calls are allowed. A “recursive function” is one which calls itself, either directly or indirectly. For example, here is an inefficient(2) way to compute the factorial of a given integer: function retval = fact (n) if (n > 0) retval = n * fact (n-1); else retval = 1; endif endfunction This function is recursive because it calls itself directly. It eventually terminates because each time it calls itself, it uses an argument that is one less than was used for the previous call. Once the argument is no longer greater than zero, it does not call itself, and the recursion ends. The function ‘max_recursion_depth’ may be used to specify a limit to the recursion depth and prevents Octave from recursing infinitely. Similarly, the function ‘max_stack_depth’ may be used to specify limit to the depth of function calls, whether recursive or not. These limits help prevent stack overflow on the computer Octave is running on, so that instead of exiting with a signal, the interpreter will throw an error and return to the command prompt. -- : VAL = max_recursion_depth () -- : OLD_VAL = max_recursion_depth (NEW_VAL) -- : max_recursion_depth (NEW_VAL, "local") Query or set the internal limit on the number of times a function may be called recursively. If the limit is exceeded, an error message is printed and control returns to the top level. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note max_stack_depth: XREFmax_stack_depth. -- : VAL = max_stack_depth () -- : OLD_VAL = max_stack_depth (NEW_VAL) -- : max_stack_depth (NEW_VAL, "local") Query or set the internal limit on the number of times a function may be called recursively. If the limit is exceeded, an error message is printed and control returns to the top level. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note max_recursion_depth: XREFmax_recursion_depth. ---------- Footnotes ---------- (1) Some of Octave’s functions are implemented in terms of functions that cannot be called recursively. For example, the ODE solver ‘lsode’ is ultimately implemented in a Fortran subroutine that cannot be called recursively, so ‘lsode’ should not be called either directly or indirectly from within the user-supplied function that ‘lsode’ requires. Doing so will result in an error. (2) It would be much better to use ‘prod (1:n)’, or ‘gamma (n+1)’ instead, after first checking to ensure that the value ‘n’ is actually a positive integer.  File: octave.info, Node: Access via Handle, Prev: Recursion, Up: Calling Functions 8.2.3 Access via Handle ----------------------- A function may be abstracted and referenced via a function handle acquired using the special operator ‘@’. For example, f = @plus; f (2, 2) ⇒ 4 is equivalent to calling ‘plus (2, 2)’ directly. Beyond abstraction for general programming, function handles find use in callback methods for figures and graphics by adding listeners to properties or assigning pre-existing actions, such as in the following example: function mydeletefcn (h, ~, msg) printf (msg); endfunction sombrero; set (gcf, "deletefcn", {@mydeletefcn, "Bye!\n"}); close; The above will print "Bye!" to the terminal upon the closing (deleting) of the figure. There are many graphics property actions for which a callback function may be assigned, including, ‘buttondownfcn’, ‘windowscrollwheelfcn’, ‘createfcn’, ‘deletefcn’, ‘keypressfcn’, etc. Note that the ‘@’ character also plays a role in defining class functions, i.e., methods, but not as a syntactical element. Rather it begins a directory name containing methods for a class that shares the directory name sans the ‘@’ character. See *note Object Oriented Programming::.  File: octave.info, Node: Arithmetic Ops, Next: Comparison Ops, Prev: Calling Functions, Up: Expressions 8.3 Arithmetic Operators ======================== The following arithmetic operators are available, and work on scalars and matrices. The element-by-element operators and functions broadcast (*note Broadcasting::). X + Y Addition. If both operands are matrices, the number of rows and columns must both agree, or they must be broadcastable to the same shape. X .+ Y Element-by-element addition. This operator is equivalent to ‘+’. X - Y Subtraction. If both operands are matrices, the number of rows and columns of both must agree, or they must be broadcastable to the same shape. X .- Y Element-by-element subtraction. This operator is equivalent to ‘-’. X * Y Matrix multiplication. The number of columns of X must agree with the number of rows of Y. X .* Y Element-by-element multiplication. If both operands are matrices, the number of rows and columns must both agree, or they must be broadcastable to the same shape. X / Y Right division. This is conceptually equivalent to the expression (inv (y') * x')' but it is computed without forming the inverse of Y’. If the system is not square, or if the coefficient matrix is singular, a minimum norm solution is computed. X ./ Y Element-by-element right division. X \ Y Left division. This is conceptually equivalent to the expression inv (x) * y but it is computed without forming the inverse of X. If the system is not square, or if the coefficient matrix is singular, a minimum norm solution is computed. X .\ Y Element-by-element left division. Each element of Y is divided by each corresponding element of X. X ^ Y X ** Y Power operator. If X and Y are both scalars, this operator returns X raised to the power Y. If X is a scalar and Y is a square matrix, the result is computed using an eigenvalue expansion. If X is a square matrix, the result is computed by repeated multiplication if Y is an integer, and by an eigenvalue expansion if Y is not an integer. An error results if both X and Y are matrices. The implementation of this operator needs to be improved. X .^ Y X .** Y Element-by-element power operator. If both operands are matrices, the number of rows and columns must both agree, or they must be broadcastable to the same shape. If several complex results are possible, the one with smallest non-negative argument (angle) is taken. This rule may return a complex root even when a real root is also possible. Use ‘realpow’, ‘realsqrt’, ‘cbrt’, or ‘nthroot’ if a real result is preferred. -X Negation. +X Unary plus. This operator has no effect on the operand. X’ Complex conjugate transpose. For real arguments, this operator is the same as the transpose operator. For complex arguments, this operator is equivalent to the expression conj (x.') X.’ Transpose. Note that because Octave’s element-by-element operators begin with a ‘.’, there is a possible ambiguity for statements like 1./m because the period could be interpreted either as part of the constant or as part of the operator. To resolve this conflict, Octave treats the expression as if you had typed (1) ./ m and not (1.) / m Although this is inconsistent with the normal behavior of Octave’s lexer, which usually prefers to break the input into tokens by preferring the longest possible match at any given point, it is more useful in this case. -- : ctranspose (X) Return the complex conjugate transpose of X. This function and X’ are equivalent. See also: *note transpose: XREFtranspose. -- : ldivide (X, Y) Return the element-by-element left division of X and Y. This function and X .\ Y are equivalent. See also: *note rdivide: XREFrdivide, *note mldivide: XREFmldivide, *note times: XREFtimes, *note plus: XREFplus. -- : minus (X, Y) This function and X - Y are equivalent. See also: *note plus: XREFplus, *note uminus: XREFuminus. -- : mldivide (X, Y) Return the matrix left division of X and Y. This function and X \ Y are equivalent. If the system is not square, or if the coefficient matrix is singular, a minimum norm solution is computed. See also: *note mrdivide: XREFmrdivide, *note ldivide: XREFldivide, *note rdivide: XREFrdivide, *note linsolve: XREFlinsolve. -- : mpower (X, Y) Return the matrix power operation of X raised to the Y power. This function and X ^ Y are equivalent. See also: *note power: XREFpower, *note mtimes: XREFmtimes, *note plus: XREFplus, *note minus: XREFminus. -- : mrdivide (X, Y) Return the matrix right division of X and Y. This function and X / Y are equivalent. If the system is not square, or if the coefficient matrix is singular, a minimum norm solution is computed. See also: *note mldivide: XREFmldivide, *note rdivide: XREFrdivide, *note plus: XREFplus, *note minus: XREFminus. -- : mtimes (X, Y) -- : mtimes (X1, X2, ...) Return the matrix multiplication product of inputs. This function and X * Y are equivalent. If more arguments are given, the multiplication is applied cumulatively from left to right: (...((X1 * X2) * X3) * ...) See also: *note times: XREFtimes, *note plus: XREFplus, *note minus: XREFminus, *note rdivide: XREFrdivide, *note mrdivide: XREFmrdivide, *note mldivide: XREFmldivide, *note mpower: XREFmpower. -- : plus (X, Y) -- : plus (X1, X2, ...) This function and X + Y are equivalent. If more arguments are given, the summation is applied cumulatively from left to right: (...((X1 + X2) + X3) + ...) See also: *note minus: XREFminus, *note uplus: XREFuplus. -- : power (X, Y) Return the element-by-element operation of X raised to the Y power. This function and X .^ Y are equivalent. If several complex results are possible, returns the one with smallest non-negative argument (angle). Use ‘realpow’, ‘realsqrt’, ‘cbrt’, or ‘nthroot’ if a real result is preferred. See also: *note mpower: XREFmpower, *note realpow: XREFrealpow, *note realsqrt: XREFrealsqrt, *note cbrt: XREFcbrt, *note nthroot: XREFnthroot. -- : rdivide (X, Y) Return the element-by-element right division of X and Y. This function and X ./ Y are equivalent. See also: *note ldivide: XREFldivide, *note mrdivide: XREFmrdivide, *note times: XREFtimes, *note plus: XREFplus. -- : times (X, Y) -- : times (X1, X2, ...) Return the element-by-element multiplication product of inputs. This function and X .* Y are equivalent. If more arguments are given, the multiplication is applied cumulatively from left to right: (...((X1 .* X2) .* X3) .* ...) See also: *note mtimes: XREFmtimes, *note rdivide: XREFrdivide. -- : transpose (X) Return the transpose of X. This function and X.’ are equivalent. See also: *note ctranspose: XREFctranspose. -- : uminus (X) This function and - X are equivalent. See also: *note uplus: XREFuplus, *note minus: XREFminus. -- : uplus (X) This function and + X are equivalent. See also: *note uminus: XREFuminus, *note plus: XREFplus.  File: octave.info, Node: Comparison Ops, Next: Boolean Expressions, Prev: Arithmetic Ops, Up: Expressions 8.4 Comparison Operators ======================== “Comparison operators” compare numeric values for relationships such as equality. They are written using _relational operators_. All of Octave’s comparison operators return a value of 1 if the comparison is true, or 0 if it is false. For matrix values, they all work on an element-by-element basis. Broadcasting rules apply. *Note Broadcasting::. For example: [1, 2; 3, 4] == [1, 3; 2, 4] ⇒ 1 0 0 1 According to broadcasting rules, if one operand is a scalar and the other is a matrix, the scalar is compared to each element of the matrix in turn, and the result is the same size as the matrix. ‘X < Y’ True if X is less than Y. ‘X <= Y’ True if X is less than or equal to Y. ‘X == Y’ True if X is equal to Y. ‘X >= Y’ True if X is greater than or equal to Y. ‘X > Y’ True if X is greater than Y. ‘X != Y’ ‘X ~= Y’ True if X is not equal to Y. For complex numbers, the following ordering is defined: Z1 < Z2 if and only if abs (Z1) < abs (Z2) || (abs (Z1) == abs (Z2) && arg (Z1) < arg (Z2)) This is consistent with the ordering used by “max”, “min” and “sort”, but is not consistent with MATLAB, which only compares the real parts. String comparisons may also be performed with the ‘strcmp’ function, not with the comparison operators listed above. *Note Strings::. -- : eq (X, Y) Return true if the two inputs are equal. This function is equivalent to ‘X == Y’. See also: *note ne: XREFne, *note isequal: XREFisequal, *note le: XREFle, *note ge: XREFge, *note gt: XREFgt, *note ne: XREFne, *note lt: XREFlt. -- : ge (X, Y) This function is equivalent to ‘X >= Y’. See also: *note le: XREFle, *note eq: XREFeq, *note gt: XREFgt, *note ne: XREFne, *note lt: XREFlt. -- : gt (X, Y) This function is equivalent to ‘X > Y’. See also: *note le: XREFle, *note eq: XREFeq, *note ge: XREFge, *note ne: XREFne, *note lt: XREFlt. -- : isequal (X1, X2, ...) Return true if all of X1, X2, ... are equal. See also: *note isequaln: XREFisequaln. -- : isequaln (X1, X2, ...) Return true if all of X1, X2, ... are equal under the additional assumption that NaN == NaN (no comparison of NaN placeholders in dataset). See also: *note isequal: XREFisequal. -- : le (X, Y) This function is equivalent to ‘X <= Y’. See also: *note eq: XREFeq, *note ge: XREFge, *note gt: XREFgt, *note ne: XREFne, *note lt: XREFlt. -- : lt (X, Y) This function is equivalent to ‘X < Y’. See also: *note le: XREFle, *note eq: XREFeq, *note ge: XREFge, *note gt: XREFgt, *note ne: XREFne. -- : ne (X, Y) Return true if the two inputs are not equal. This function is equivalent to ‘X != Y’. See also: *note eq: XREFeq, *note isequal: XREFisequal, *note le: XREFle, *note ge: XREFge, *note lt: XREFlt.  File: octave.info, Node: Boolean Expressions, Next: Assignment Ops, Prev: Comparison Ops, Up: Expressions 8.5 Boolean Expressions ======================= * Menu: * Element-by-element Boolean Operators:: * Short-circuit Boolean Operators::  File: octave.info, Node: Element-by-element Boolean Operators, Next: Short-circuit Boolean Operators, Up: Boolean Expressions 8.5.1 Element-by-element Boolean Operators ------------------------------------------ An “element-by-element boolean expression” is a combination of comparison expressions using the boolean operators “or” (‘|’), “and” (‘&’), and “not” (‘!’), along with parentheses to control nesting. The truth of the boolean expression is computed by combining the truth values of the corresponding elements of the component expressions. A value is considered to be false if it is zero, and true otherwise. Element-by-element boolean expressions can be used wherever comparison expressions can be used. They can be used in ‘if’ and ‘while’ statements. However, a matrix value used as the condition in an ‘if’ or ‘while’ statement is only true if _all_ of its elements are nonzero. Like comparison operations, each element of an element-by-element boolean expression also has a numeric value (1 if true, 0 if false) that comes into play if the result of the boolean expression is stored in a variable, or used in arithmetic. Here are descriptions of the three element-by-element boolean operators. ‘BOOLEAN1 & BOOLEAN2’ Elements of the result are true if both corresponding elements of BOOLEAN1 and BOOLEAN2 are true. ‘BOOLEAN1 | BOOLEAN2’ Elements of the result are true if either of the corresponding elements of BOOLEAN1 or BOOLEAN2 is true. ‘! BOOLEAN’ ‘~ BOOLEAN’ Each element of the result is true if the corresponding element of BOOLEAN is false. These operators work on an element-by-element basis. For example, the expression [1, 0; 0, 1] & [1, 0; 2, 3] returns a two by two identity matrix. For the binary operators, broadcasting rules apply. *Note Broadcasting::. In particular, if one of the operands is a scalar and the other a matrix, the operator is applied to the scalar and each element of the matrix. For the binary element-by-element boolean operators, both subexpressions BOOLEAN1 and BOOLEAN2 are evaluated before computing the result. This can make a difference when the expressions have side effects. For example, in the expression a & b++ the value of the variable B is incremented even if the variable A is zero. This behavior is necessary for the boolean operators to work as described for matrix-valued operands. -- : Z = and (X, Y) -- : Z = and (X1, X2, ...) Return the logical AND of X and Y. This function is equivalent to the operator syntax ‘X & Y’. If more than two arguments are given, the logical AND is applied cumulatively from left to right: (...((X1 & X2) & X3) & ...) See also: *note or: XREFor, *note not: XREFnot, *note xor: XREFxor. -- : Z = not (X) Return the logical NOT of X. This function is equivalent to the operator syntax ‘! X’. See also: *note and: XREFand, *note or: XREFor, *note xor: XREFxor. -- : Z = or (X, Y) -- : Z = or (X1, X2, ...) Return the logical OR of X and Y. This function is equivalent to the operator syntax ‘X | Y’. If more than two arguments are given, the logical OR is applied cumulatively from left to right: (...((X1 | X2) | X3) | ...) See also: *note and: XREFand, *note not: XREFnot, *note xor: XREFxor.  File: octave.info, Node: Short-circuit Boolean Operators, Prev: Element-by-element Boolean Operators, Up: Boolean Expressions 8.5.2 Short-circuit Boolean Operators ------------------------------------- Combined with the implicit conversion to scalar values in ‘if’ and ‘while’ conditions, Octave’s element-by-element boolean operators are often sufficient for performing most logical operations. However, it is sometimes desirable to stop evaluating a boolean expression as soon as the overall truth value can be determined. Octave’s “short-circuit” boolean operators work this way. ‘BOOLEAN1 && BOOLEAN2’ The expression BOOLEAN1 is evaluated and converted to a scalar using the equivalent of the operation ‘all (BOOLEAN1(:))’. If it is false, the result of the overall expression is 0. If it is true, the expression BOOLEAN2 is evaluated and converted to a scalar using the equivalent of the operation ‘all (BOOLEAN2(:))’. If it is true, the result of the overall expression is 1. Otherwise, the result of the overall expression is 0. *Warning:* there is one exception to the rule of evaluating ‘all (BOOLEAN1(:))’, which is when ‘boolean1’ is the empty matrix. The truth value of an empty matrix is always ‘false’ so ‘[] && true’ evaluates to ‘false’ even though ‘all ([])’ is ‘true’. ‘BOOLEAN1 || BOOLEAN2’ The expression BOOLEAN1 is evaluated and converted to a scalar using the equivalent of the operation ‘all (BOOLEAN1(:))’. If it is true, the result of the overall expression is 1. If it is false, the expression BOOLEAN2 is evaluated and converted to a scalar using the equivalent of the operation ‘all (BOOLEAN2(:))’. If it is true, the result of the overall expression is 1. Otherwise, the result of the overall expression is 0. *Warning:* the truth value of an empty matrix is always ‘false’, see the previous list item for details. The fact that both operands may not be evaluated before determining the overall truth value of the expression can be important. For example, in the expression a && b++ the value of the variable B is only incremented if the variable A is nonzero. This can be used to write somewhat more concise code. For example, it is possible write function f (a, b, c) if (nargin > 2 && ischar (c)) ... instead of having to use two ‘if’ statements to avoid attempting to evaluate an argument that doesn’t exist. For example, without the short-circuit feature, it would be necessary to write function f (a, b, c) if (nargin > 2) if (ischar (c)) ... Writing function f (a, b, c) if (nargin > 2 & ischar (c)) ... would result in an error if ‘f’ were called with one or two arguments because Octave would be forced to try to evaluate both of the operands for the operator ‘&’. MATLAB has special behavior that allows the operators ‘&’ and ‘|’ to short-circuit when used in the truth expression for ‘if’ and ‘while’ statements. Octave behaves the same way for compatibility, however, the use of the ‘&’ and ‘|’ operators in this way is strongly discouraged and a warning will be issued. Instead, you should use the ‘&&’ and ‘||’ operators that always have short-circuit behavior. Finally, the ternary operator (?:) is not supported in Octave. If short-circuiting is not important, it can be replaced by the ‘ifelse’ function. -- : merge (MASK, TVAL, FVAL) -- : ifelse (MASK, TVAL, FVAL) Merge elements of TRUE_VAL and FALSE_VAL, depending on the value of MASK. If MASK is a logical scalar, the other two arguments can be arbitrary values. Otherwise, MASK must be a logical array, and TVAL, FVAL should be arrays of matching class, or cell arrays. In the scalar mask case, TVAL is returned if MASK is true, otherwise FVAL is returned. In the array mask case, both TVAL and FVAL must be either scalars or arrays with dimensions equal to MASK. The result is constructed as follows: result(mask) = tval(mask); result(! mask) = fval(! mask); MASK can also be arbitrary numeric type, in which case it is first converted to logical. See also: *note logical: XREFlogical, *note diff: XREFdiff.  File: octave.info, Node: Assignment Ops, Next: Increment Ops, Prev: Boolean Expressions, Up: Expressions 8.6 Assignment Expressions ========================== An “assignment” is an expression that stores a new value into a variable. For example, the following expression assigns the value 1 to the variable ‘z’: z = 1 After this expression is executed, the variable ‘z’ has the value 1. Whatever old value ‘z’ had before the assignment is forgotten. The ‘=’ sign is called an “assignment operator”. Assignments can store string values also. For example, the following expression would store the value "this food is good" in the variable ‘message’: thing = "food" predicate = "good" message = [ "this " , thing , " is " , predicate ] (This also illustrates concatenation of strings.) Most operators (addition, concatenation, and so on) have no effect except to compute a value. If you ignore the value, you might as well not use the operator. An assignment operator is different. It does produce a value, but even if you ignore the value, the assignment still makes itself felt through the alteration of the variable. We call this a “side effect”. The left-hand operand of an assignment need not be a variable (*note Variables::). It can also be an element of a matrix (*note Index Expressions::) or a list of return values (*note Calling Functions::). These are all called “lvalues”, which means they can appear on the left-hand side of an assignment operator. The right-hand operand may be any expression. It produces the new value which the assignment stores in the specified variable, matrix element, or list of return values. It is important to note that variables do _not_ have permanent types. The type of a variable is simply the type of whatever value it happens to hold at the moment. In the following program fragment, the variable ‘foo’ has a numeric value at first, and a string value later on: octave:13> foo = 1 foo = 1 octave:13> foo = "bar" foo = bar When the second assignment gives ‘foo’ a string value, the fact that it previously had a numeric value is forgotten. Assignment of a scalar to an indexed matrix sets all of the elements that are referenced by the indices to the scalar value. For example, if ‘a’ is a matrix with at least two columns, a(:, 2) = 5 sets all the elements in the second column of ‘a’ to 5. Assigning an empty matrix ‘[]’ works in most cases to allow you to delete rows or columns of matrices and vectors. *Note Empty Matrices::. For example, given a 4 by 5 matrix A, the assignment A (3, :) = [] deletes the third row of A, and the assignment A (:, 1:2:5) = [] deletes the first, third, and fifth columns. An assignment is an expression, so it has a value. Thus, ‘z = 1’ as an expression has the value 1. One consequence of this is that you can write multiple assignments together: x = y = z = 0 stores the value 0 in all three variables. It does this because the value of ‘z = 0’, which is 0, is stored into ‘y’, and then the value of ‘y = z = 0’, which is 0, is stored into ‘x’. This is also true of assignments to lists of values, so the following is a valid expression [a, b, c] = [u, s, v] = svd (a) that is exactly equivalent to [u, s, v] = svd (a) a = u b = s c = v In expressions like this, the number of values in each part of the expression need not match. For example, the expression [a, b] = [u, s, v] = svd (a) is equivalent to [u, s, v] = svd (a) a = u b = s The number of values on the left side of the expression can, however, not exceed the number of values on the right side. For example, the following will produce an error. [a, b, c, d] = [u, s, v] = svd (a); ⊣ error: element number 4 undefined in return list The symbol ‘~’ may be used as a placeholder in the list of lvalues, indicating that the corresponding return value should be ignored and not stored anywhere: [~, s, v] = svd (a); This is cleaner and more memory efficient than using a dummy variable. The ‘nargout’ value for the right-hand side expression is not affected. If the assignment is used as an expression, the return value is a comma-separated list with the ignored values dropped. A very common programming pattern is to increment an existing variable with a given value, like this a = a + 2; This can be written in a clearer and more condensed form using the ‘+=’ operator a += 2; Similar operators also exist for subtraction (‘-=’), multiplication (‘*=’), and division (‘/=’). An expression of the form EXPR1 OP= EXPR2 is evaluated as EXPR1 = (EXPR1) OP (EXPR2) where OP can be either ‘+’, ‘-’, ‘*’, or ‘/’, as long as EXPR2 is a simple expression with no side effects. If EXPR2 also contains an assignment operator, then this expression is evaluated as TEMP = EXPR2 EXPR1 = (EXPR1) OP TEMP where TEMP is a placeholder temporary value storing the computed result of evaluating EXPR2. So, the expression a *= b+1 is evaluated as a = a * (b+1) and _not_ a = a * b + 1 You can use an assignment anywhere an expression is called for. For example, it is valid to write ‘x != (y = 1)’ to set ‘y’ to 1 and then test whether ‘x’ equals 1. But this style tends to make programs hard to read. Except in a one-shot program, you should rewrite it to get rid of such nesting of assignments. This is never very hard.  File: octave.info, Node: Increment Ops, Next: Operator Precedence, Prev: Assignment Ops, Up: Expressions 8.7 Increment Operators ======================= _Increment operators_ increase or decrease the value of a variable by 1. The operator to increment a variable is written as ‘++’. It may be used to increment a variable either before or after taking its value. For example, to pre-increment the variable X, you would write ‘++X’. This would add one to X and then return the new value of X as the result of the expression. It is exactly the same as the expression ‘X = X + 1’. To post-increment a variable X, you would write ‘X++’. This adds one to the variable X, but returns the value that X had prior to incrementing it. For example, if X is equal to 2, the result of the expression ‘X++’ is 2, and the new value of X is 3. For matrix and vector arguments, the increment and decrement operators work on each element of the operand. Here is a list of all the increment and decrement expressions. ‘++X’ This expression increments the variable X. The value of the expression is the _new_ value of X. It is equivalent to the expression ‘X = X + 1’. ‘--X’ This expression decrements the variable X. The value of the expression is the _new_ value of X. It is equivalent to the expression ‘X = X - 1’. ‘X++’ This expression causes the variable X to be incremented. The value of the expression is the _old_ value of X. ‘X--’ This expression causes the variable X to be decremented. The value of the expression is the _old_ value of X.  File: octave.info, Node: Operator Precedence, Prev: Increment Ops, Up: Expressions 8.8 Operator Precedence ======================= “Operator precedence” determines how operators are grouped, when different operators appear close by in one expression. For example, ‘*’ has higher precedence than ‘+’. Thus, the expression ‘a + b * c’ means to multiply ‘b’ and ‘c’, and then add ‘a’ to the product (i.e., ‘a + (b * c)’). You can overrule the precedence of the operators by using parentheses. You can think of the precedence rules as saying where the parentheses are assumed if you do not write parentheses yourself. In fact, it is wise to use parentheses whenever you have an unusual combination of operators, because other people who read the program may not remember what the precedence is in this case. You might forget as well, and then you too could make a mistake. Explicit parentheses will help prevent any such mistake. When operators of equal precedence are used together, the leftmost operator groups first, except for the assignment operators, which group in the opposite order. Thus, the expression ‘a - b + c’ groups as ‘(a - b) + c’, but the expression ‘a = b = c’ groups as ‘a = (b = c)’. The precedence of prefix unary operators is important when another operator follows the operand. For example, ‘-x^2’ means ‘-(x^2)’, because ‘-’ has lower precedence than ‘^’. Here is a table of the operators in Octave, in order of decreasing precedence. Unless noted, all operators group left to right. ‘function call and array indexing, cell array indexing, and structure element indexing’ ‘()’ ‘{}’ ‘.’ ‘postfix increment, and postfix decrement’ ‘++’ ‘--’ These operators group right to left. ‘transpose and exponentiation’ ‘'’ ‘.'’ ‘^’ ‘**’ ‘.^’ ‘.**’ ‘unary plus, unary minus, prefix increment, prefix decrement, and logical "not"’ ‘+’ ‘-’ ‘++’ ‘--’ ‘~’ ‘!’ ‘multiply and divide’ ‘*’ ‘/’ ‘\’ ‘.\’ ‘.*’ ‘./’ ‘add, subtract’ ‘+’ ‘-’ ‘colon’ ‘:’ ‘relational’ ‘<’ ‘<=’ ‘==’ ‘>=’ ‘>’ ‘!=’ ‘~=’ ‘element-wise "and"’ ‘&’ ‘element-wise "or"’ ‘|’ ‘logical "and"’ ‘&&’ ‘logical "or"’ ‘||’ ‘assignment’ ‘=’ ‘+=’ ‘-=’ ‘*=’ ‘/=’ ‘\=’ ‘^=’ ‘.*=’ ‘./=’ ‘.\=’ ‘.^=’ ‘|=’ ‘&=’ These operators group right to left.  File: octave.info, Node: Evaluation, Next: Statements, Prev: Expressions, Up: Top 9 Evaluation ************ Normally, you evaluate expressions simply by typing them at the Octave prompt, or by asking Octave to interpret commands that you have saved in a file. Sometimes, you may find it necessary to evaluate an expression that has been computed and stored in a string, which is exactly what the ‘eval’ function lets you do. -- : eval (TRY) -- : eval (TRY, CATCH) Parse the string TRY and evaluate it as if it were an Octave program. If execution fails, evaluate the optional string CATCH. The string TRY is evaluated in the current context, so any results remain available after ‘eval’ returns. The following example creates the variable A with the approximate value of 3.1416 in the current workspace. eval ("A = acos(-1);"); If an error occurs during the evaluation of TRY then the CATCH string is evaluated, as the following example shows: eval ('error ("This is a bad example");', 'printf ("This error occurred:\n%s\n", lasterr ());'); ⊣ This error occurred: This is a bad example Programming Note: if you are only using ‘eval’ as an error-capturing mechanism, rather than for the execution of arbitrary code strings, Consider using try/catch blocks or unwind_protect/unwind_protect_cleanup blocks instead. These techniques have higher performance and don’t introduce the security considerations that the evaluation of arbitrary code does. See also: *note evalin: XREFevalin, *note evalc: XREFevalc, *note assignin: XREFassignin, *note feval: XREFfeval. The ‘evalc’ function additionally captures any console output produced by the evaluated expression. -- : S = evalc (TRY) -- : S = evalc (TRY, CATCH) Parse and evaluate the string TRY as if it were an Octave program, while capturing the output into the return variable S. If execution fails, evaluate the optional string CATCH. This function behaves like ‘eval’, but any output or warning messages which would normally be written to the console are captured and returned in the string S. The ‘diary’ is disabled during the execution of this function. When ‘system’ is used, any output produced by external programs is _not_ captured, unless their output is captured by the ‘system’ function itself. s = evalc ("t = 42"), t ⇒ s = t = 42 ⇒ t = 42 See also: *note eval: XREFeval, *note diary: XREFdiary. * Menu: * Calling a Function by its Name:: * Evaluation in a Different Context::  File: octave.info, Node: Calling a Function by its Name, Next: Evaluation in a Different Context, Up: Evaluation 9.1 Calling a Function by its Name ================================== The ‘feval’ function allows you to call a function from a string containing its name. This is useful when writing a function that needs to call user-supplied functions. The ‘feval’ function takes the name of the function to call as its first argument, and the remaining arguments are given to the function. The following example is a simple-minded function using ‘feval’ that finds the root of a user-supplied function of one variable using Newton’s method. function result = newtroot (fname, x) # usage: newtroot (fname, x) # # fname : a string naming a function f(x). # x : initial guess delta = tol = sqrt (eps); maxit = 200; fx = feval (fname, x); for i = 1:maxit if (abs (fx) < tol) result = x; return; else fx_new = feval (fname, x + delta); deriv = (fx_new - fx) / delta; x = x - fx / deriv; fx = fx_new; endif endfor result = x; endfunction Note that this is only meant to be an example of calling user-supplied functions and should not be taken too seriously. In addition to using a more robust algorithm, any serious code would check the number and type of all the arguments, ensure that the supplied function really was a function, etc. *Note Predicates for Numeric Objects::, for a list of predicates for numeric objects, and *note Status of Variables::, for a description of the ‘exist’ function. -- : feval (NAME, ...) Evaluate the function named NAME. Any arguments after the first are passed as inputs to the named function. For example, feval ("acos", -1) ⇒ 3.1416 calls the function ‘acos’ with the argument ‘-1’. The function ‘feval’ can also be used with function handles of any sort (*note Function Handles::). Historically, ‘feval’ was the only way to call user-supplied functions in strings, but function handles are now preferred due to the cleaner syntax they offer. For example, F = @exp; feval (F, 1) ⇒ 2.7183 F (1) ⇒ 2.7183 are equivalent ways to call the function referred to by F. If it cannot be predicted beforehand whether F is a function handle, function name in a string, or inline function then ‘feval’ can be used instead. A similar function ‘run’ exists for calling user script files, that are not necessarily on the user path -- : run SCRIPT -- : run ("SCRIPT") Run SCRIPT in the current workspace. Scripts which reside in directories specified in Octave’s load path, and which end with the extension ‘.m’, can be run simply by typing their name. For scripts not located on the load path, use ‘run’. The filename SCRIPT can be a bare, fully qualified, or relative filename and with or without a file extension. If no extension is specified, Octave will first search for a script with the ‘.m’ extension before falling back to the script name without an extension. Implementation Note: If SCRIPT includes a path component, then ‘run’ first changes the working directory to the directory where SCRIPT is found. Next, the script is executed. Finally, ‘run’ returns to the original working directory _unless_ SCRIPT has specifically changed directories. See also: *note path: XREFpath, *note addpath: XREFaddpath, *note source: XREFsource.  File: octave.info, Node: Evaluation in a Different Context, Prev: Calling a Function by its Name, Up: Evaluation 9.2 Evaluation in a Different Context ===================================== Before you evaluate an expression you need to substitute the values of the variables used in the expression. These are stored in the symbol table. Whenever the interpreter starts a new function it saves the current symbol table and creates a new one, initializing it with the list of function parameters and a couple of predefined variables such as ‘nargin’. Expressions inside the function use the new symbol table. Sometimes you want to write a function so that when you call it, it modifies variables in your own context. This allows you to use a pass-by-name style of function, which is similar to using a pointer in programming languages such as C. Consider how you might write ‘save’ and ‘load’ as m-files. For example: function create_data x = linspace (0, 10, 10); y = sin (x); save mydata x y endfunction With ‘evalin’, you could write ‘save’ as follows: function save (file, name1, name2) f = open_save_file (file); save_var (f, name1, evalin ("caller", name1)); save_var (f, name2, evalin ("caller", name2)); endfunction Here, ‘caller’ is the ‘create_data’ function and ‘name1’ is the string "x", which evaluates simply as the value of ‘x’. You later want to load the values back from ‘mydata’ in a different context: function process_data load mydata ... do work ... endfunction With ‘assignin’, you could write ‘load’ as follows: function load (file) f = open_load_file (file); [name, val] = load_var (f); assignin ("caller", name, val); [name, val] = load_var (f); assignin ("caller", name, val); endfunction Here, ‘caller’ is the ‘process_data’ function. You can set and use variables at the command prompt using the context ‘base’ rather than ‘caller’. These functions are rarely used in practice. One example is the ‘fail (‘code’, ‘pattern’)’ function which evaluates ‘code’ in the caller’s context and checks that the error message it produces matches the given pattern. Other examples such as ‘save’ and ‘load’ are written in C++ where all Octave variables are in the ‘caller’ context and ‘evalin’ is not needed. -- : evalin (CONTEXT, TRY) -- : evalin (CONTEXT, TRY, CATCH) Like ‘eval’, except that the expressions are evaluated in the context CONTEXT, which may be either "caller" or "base". See also: *note eval: XREFeval, *note assignin: XREFassignin. -- : assignin (CONTEXT, VARNAME, VALUE) Assign VALUE to VARNAME in context CONTEXT, which may be either "base" or "caller". See also: *note evalin: XREFevalin.  File: octave.info, Node: Statements, Next: Functions and Scripts, Prev: Evaluation, Up: Top 10 Statements ************* Statements may be a simple constant expression or a complicated list of nested loops and conditional statements. “Control statements” such as ‘if’, ‘while’, and so on control the flow of execution in Octave programs. All the control statements start with special keywords such as ‘if’ and ‘while’, to distinguish them from simple expressions. Many control statements contain other statements; for example, the ‘if’ statement contains another statement which may or may not be executed. Each control statement has a corresponding “end” statement that marks the end of the control statement. For example, the keyword ‘endif’ marks the end of an ‘if’ statement, and ‘endwhile’ marks the end of a ‘while’ statement. You can use the keyword ‘end’ anywhere a more specific end keyword is expected, but using the more specific keywords is preferred because if you use them, Octave is able to provide better diagnostics for mismatched or missing end tokens. The list of statements contained between keywords like ‘if’ or ‘while’ and the corresponding end statement is called the “body” of a control statement. * Menu: * The if Statement:: * The switch Statement:: * The while Statement:: * The do-until Statement:: * The for Statement:: * The break Statement:: * The continue Statement:: * The unwind_protect Statement:: * The try Statement:: * Continuation Lines::  File: octave.info, Node: The if Statement, Next: The switch Statement, Up: Statements 10.1 The if Statement ===================== The ‘if’ statement is Octave’s decision-making statement. There are three basic forms of an ‘if’ statement. In its simplest form, it looks like this: if (CONDITION) THEN-BODY endif CONDITION is an expression that controls what the rest of the statement will do. The THEN-BODY is executed only if CONDITION is true. The condition in an ‘if’ statement is considered true if its value is nonzero, and false if its value is zero. If the value of the conditional expression in an ‘if’ statement is a vector or a matrix, it is considered true only if it is non-empty and _all_ of the elements are nonzero. The conceptually equivalent code when CONDITION is a matrix is shown below. if (MATRIX) ≡ if (all (MATRIX(:))) The second form of an if statement looks like this: if (CONDITION) THEN-BODY else ELSE-BODY endif If CONDITION is true, THEN-BODY is executed; otherwise, ELSE-BODY is executed. Here is an example: if (rem (x, 2) == 0) printf ("x is even\n"); else printf ("x is odd\n"); endif In this example, if the expression ‘rem (x, 2) == 0’ is true (that is, the value of ‘x’ is divisible by 2), then the first ‘printf’ statement is evaluated, otherwise the second ‘printf’ statement is evaluated. The third and most general form of the ‘if’ statement allows multiple decisions to be combined in a single statement. It looks like this: if (CONDITION) THEN-BODY elseif (CONDITION) ELSEIF-BODY else ELSE-BODY endif Any number of ‘elseif’ clauses may appear. Each condition is tested in turn, and if one is found to be true, its corresponding BODY is executed. If none of the conditions are true and the ‘else’ clause is present, its body is executed. Only one ‘else’ clause may appear, and it must be the last part of the statement. In the following example, if the first condition is true (that is, the value of ‘x’ is divisible by 2), then the first ‘printf’ statement is executed. If it is false, then the second condition is tested, and if it is true (that is, the value of ‘x’ is divisible by 3), then the second ‘printf’ statement is executed. Otherwise, the third ‘printf’ statement is performed. if (rem (x, 2) == 0) printf ("x is even\n"); elseif (rem (x, 3) == 0) printf ("x is odd and divisible by 3\n"); else printf ("x is odd\n"); endif Note that the ‘elseif’ keyword must not be spelled ‘else if’, as is allowed in Fortran. If it is, the space between the ‘else’ and ‘if’ will tell Octave to treat this as a new ‘if’ statement within another ‘if’ statement’s ‘else’ clause. For example, if you write if (C1) BODY-1 else if (C2) BODY-2 endif Octave will expect additional input to complete the first ‘if’ statement. If you are using Octave interactively, it will continue to prompt you for additional input. If Octave is reading this input from a file, it may complain about missing or mismatched ‘end’ statements, or, if you have not used the more specific ‘end’ statements (‘endif’, ‘endfor’, etc.), it may simply produce incorrect results, without producing any warning messages. It is much easier to see the error if we rewrite the statements above like this, if (C1) BODY-1 else if (C2) BODY-2 endif using the indentation to show how Octave groups the statements. *Note Functions and Scripts::.  File: octave.info, Node: The switch Statement, Next: The while Statement, Prev: The if Statement, Up: Statements 10.2 The switch Statement ========================= It is very common to take different actions depending on the value of one variable. This is possible using the ‘if’ statement in the following way if (X == 1) do_something (); elseif (X == 2) do_something_else (); else do_something_completely_different (); endif This kind of code can however be very cumbersome to both write and maintain. To overcome this problem Octave supports the ‘switch’ statement. Using this statement, the above example becomes switch (X) case 1 do_something (); case 2 do_something_else (); otherwise do_something_completely_different (); endswitch This code makes the repetitive structure of the problem more explicit, making the code easier to read, and hence maintain. Also, if the variable ‘X’ should change its name, only one line would need changing compared to one line per case when ‘if’ statements are used. The general form of the ‘switch’ statement is switch (EXPRESSION) case LABEL COMMAND_LIST case LABEL COMMAND_LIST ... otherwise COMMAND_LIST endswitch where LABEL can be any expression. However, duplicate LABEL values are not detected, and only the COMMAND_LIST corresponding to the first match will be executed. For the ‘switch’ statement to be meaningful at least one ‘case LABEL COMMAND_LIST’ clause must be present, while the ‘otherwise COMMAND_LIST’ clause is optional. If LABEL is a cell array the corresponding COMMAND_LIST is executed if _any_ of the elements of the cell array match EXPRESSION. As an example, the following program will print ‘Variable is either 6 or 7’. A = 7; switch (A) case { 6, 7 } printf ("variable is either 6 or 7\n"); otherwise printf ("variable is neither 6 nor 7\n"); endswitch As with all other specific ‘end’ keywords, ‘endswitch’ may be replaced by ‘end’, but you can get better diagnostics if you use the specific forms. One advantage of using the ‘switch’ statement compared to using ‘if’ statements is that the LABELs can be strings. If an ‘if’ statement is used it is _not_ possible to write if (X == "a string") # This is NOT valid since a character-to-character comparison between ‘X’ and the string will be made instead of evaluating if the strings are equal. This special-case is handled by the ‘switch’ statement, and it is possible to write programs that look like this switch (X) case "a string" do_something ... endswitch * Menu: * Notes for the C Programmer::  File: octave.info, Node: Notes for the C Programmer, Up: The switch Statement 10.2.1 Notes for the C Programmer --------------------------------- The ‘switch’ statement is also available in the widely used C programming language. There are, however, some differences between the statement in Octave and C • Cases are exclusive, so they don’t ‘fall through’ as do the cases in the ‘switch’ statement of the C language. • The COMMAND_LIST elements are not optional. Making the list optional would have meant requiring a separator between the label and the command list. Otherwise, things like switch (foo) case (1) -2 ... would produce surprising results, as would switch (foo) case (1) case (2) doit (); ... particularly for C programmers. If ‘doit()’ should be executed if FOO is either ‘1’ or ‘2’, the above code should be written with a cell array like this switch (foo) case { 1, 2 } doit (); ...  File: octave.info, Node: The while Statement, Next: The do-until Statement, Prev: The switch Statement, Up: Statements 10.3 The while Statement ======================== In programming, a “loop” means a part of a program that is (or at least can be) executed two or more times in succession. The ‘while’ statement is the simplest looping statement in Octave. It repeatedly executes a statement as long as a condition is true. As with the condition in an ‘if’ statement, the condition in a ‘while’ statement is considered true if its value is nonzero, and false if its value is zero. If the value of the conditional expression in a ‘while’ statement is a vector or a matrix, it is considered true only if it is non-empty and _all_ of the elements are nonzero. Octave’s ‘while’ statement looks like this: while (CONDITION) BODY endwhile Here BODY is a statement or list of statements that we call the “body” of the loop, and CONDITION is an expression that controls how long the loop keeps running. The first thing the ‘while’ statement does is test CONDITION. If CONDITION is true, it executes the statement BODY. After BODY has been executed, CONDITION is tested again, and if it is still true, BODY is executed again. This process repeats until CONDITION is no longer true. If CONDITION is initially false, the body of the loop is never executed. This example creates a variable ‘fib’ that contains the first ten elements of the Fibonacci sequence. fib = ones (1, 10); i = 3; while (i <= 10) fib (i) = fib (i-1) + fib (i-2); i++; endwhile Here the body of the loop contains two statements. The loop works like this: first, the value of ‘i’ is set to 3. Then, the ‘while’ tests whether ‘i’ is less than or equal to 10. This is the case when ‘i’ equals 3, so the value of the ‘i’-th element of ‘fib’ is set to the sum of the previous two values in the sequence. Then the ‘i++’ increments the value of ‘i’ and the loop repeats. The loop terminates when ‘i’ reaches 11. A newline is not required between the condition and the body; but using one makes the program clearer unless the body is very simple.  File: octave.info, Node: The do-until Statement, Next: The for Statement, Prev: The while Statement, Up: Statements 10.4 The do-until Statement =========================== The ‘do-until’ statement is similar to the ‘while’ statement, except that it repeatedly executes a statement until a condition becomes true, and the test of the condition is at the end of the loop, so the body of the loop is always executed at least once. As with the condition in an ‘if’ statement, the condition in a ‘do-until’ statement is considered true if its value is nonzero, and false if its value is zero. If the value of the conditional expression in a ‘do-until’ statement is a vector or a matrix, it is considered true only if it is non-empty and _all_ of the elements are nonzero. Octave’s ‘do-until’ statement looks like this: do BODY until (CONDITION) Here BODY is a statement or list of statements that we call the “body” of the loop, and CONDITION is an expression that controls how long the loop keeps running. This example creates a variable ‘fib’ that contains the first ten elements of the Fibonacci sequence. fib = ones (1, 10); i = 2; do i++; fib (i) = fib (i-1) + fib (i-2); until (i == 10) A newline is not required between the ‘do’ keyword and the body; but using one makes the program clearer unless the body is very simple.  File: octave.info, Node: The for Statement, Next: The break Statement, Prev: The do-until Statement, Up: Statements 10.5 The for Statement ====================== The ‘for’ statement makes it more convenient to count iterations of a loop. The general form of the ‘for’ statement looks like this: for VAR = EXPRESSION BODY endfor where BODY stands for any statement or list of statements, EXPRESSION is any valid expression, and VAR may take several forms. Usually it is a simple variable name or an indexed variable. If the value of EXPRESSION is a structure, VAR may also be a vector with two elements. *Note Looping Over Structure Elements::, below. The assignment expression in the ‘for’ statement works a bit differently than Octave’s normal assignment statement. Instead of assigning the complete result of the expression, it assigns each column of the expression to VAR in turn. If EXPRESSION is a range, a row vector, or a scalar, the value of VAR will be a scalar each time the loop body is executed. If VAR is a column vector or a matrix, VAR will be a column vector each time the loop body is executed. The following example shows another way to create a vector containing the first ten elements of the Fibonacci sequence, this time using the ‘for’ statement: fib = ones (1, 10); for i = 3:10 fib(i) = fib(i-1) + fib(i-2); endfor This code works by first evaluating the expression ‘3:10’, to produce a range of values from 3 to 10 inclusive. Then the variable ‘i’ is assigned the first element of the range and the body of the loop is executed once. When the end of the loop body is reached, the next value in the range is assigned to the variable ‘i’, and the loop body is executed again. This process continues until there are no more elements to assign. Within Octave is it also possible to iterate over matrices or cell arrays using the ‘for’ statement. For example consider disp ("Loop over a matrix") for i = [1,3;2,4] i endfor disp ("Loop over a cell array") for i = {1,"two";"three",4} i endfor In this case the variable ‘i’ takes on the value of the columns of the matrix or cell matrix. So the first loop iterates twice, producing two column vectors ‘[1;2]’, followed by ‘[3;4]’, and likewise for the loop over the cell array. This can be extended to loops over multi-dimensional arrays. For example: a = [1,3;2,4]; c = cat (3, a, 2*a); for i = c i endfor In the above case, the multi-dimensional matrix C is reshaped to a two-dimensional matrix as ‘reshape (c, rows (c), prod (size (c)(2:end)))’ and then the same behavior as a loop over a two-dimensional matrix is produced. Although it is possible to rewrite all ‘for’ loops as ‘while’ loops, the Octave language has both statements because often a ‘for’ loop is both less work to type and more natural to think of. Counting the number of iterations is very common in loops and it can be easier to think of this counting as part of looping rather than as something to do inside the loop. * Menu: * Looping Over Structure Elements::  File: octave.info, Node: Looping Over Structure Elements, Up: The for Statement 10.5.1 Looping Over Structure Elements -------------------------------------- A special form of the ‘for’ statement allows you to loop over all the elements of a structure: for [ VAL, KEY ] = EXPRESSION BODY endfor In this form of the ‘for’ statement, the value of EXPRESSION must be a structure. If it is, KEY and VAL are set to the name of the element and the corresponding value in turn, until there are no more elements. For example: x.a = 1 x.b = [1, 2; 3, 4] x.c = "string" for [val, key] = x key val endfor ⊣ key = a ⊣ val = 1 ⊣ key = b ⊣ val = ⊣ ⊣ 1 2 ⊣ 3 4 ⊣ ⊣ key = c ⊣ val = string The elements are not accessed in any particular order. If you need to cycle through the list in a particular way, you will have to use the function ‘fieldnames’ and sort the list yourself.  File: octave.info, Node: The break Statement, Next: The continue Statement, Prev: The for Statement, Up: Statements 10.6 The break Statement ======================== The ‘break’ statement jumps out of the innermost ‘while’, ‘do-until’, or ‘for’ loop that encloses it. The ‘break’ statement may only be used within the body of a loop. The following example finds the smallest divisor of a given integer, and also identifies prime numbers: num = 103; div = 2; while (div*div <= num) if (rem (num, div) == 0) break; endif div++; endwhile if (rem (num, div) == 0) printf ("Smallest divisor of %d is %d\n", num, div) else printf ("%d is prime\n", num); endif When the remainder is zero in the first ‘while’ statement, Octave immediately “breaks out” of the loop. This means that Octave proceeds immediately to the statement following the loop and continues processing. (This is very different from the ‘exit’ statement which stops the entire Octave program.) Here is another program equivalent to the previous one. It illustrates how the CONDITION of a ‘while’ statement could just as well be replaced with a ‘break’ inside an ‘if’: num = 103; div = 2; while (1) if (rem (num, div) == 0) printf ("Smallest divisor of %d is %d\n", num, div); break; endif div++; if (div*div > num) printf ("%d is prime\n", num); break; endif endwhile  File: octave.info, Node: The continue Statement, Next: The unwind_protect Statement, Prev: The break Statement, Up: Statements 10.7 The continue Statement =========================== The ‘continue’ statement, like ‘break’, is used only inside ‘while’, ‘do-until’, or ‘for’ loops. It skips over the rest of the loop body, causing the next cycle around the loop to begin immediately. Contrast this with ‘break’, which jumps out of the loop altogether. Here is an example: # print elements of a vector of random # integers that are even. # first, create a row vector of 10 random # integers with values between 0 and 100: vec = round (rand (1, 10) * 100); # print what we're interested in: for x = vec if (rem (x, 2) != 0) continue; endif printf ("%d\n", x); endfor If one of the elements of VEC is an odd number, this example skips the print statement for that element, and continues back to the first statement in the loop. This is not a practical example of the ‘continue’ statement, but it should give you a clear understanding of how it works. Normally, one would probably write the loop like this: for x = vec if (rem (x, 2) == 0) printf ("%d\n", x); endif endfor  File: octave.info, Node: The unwind_protect Statement, Next: The try Statement, Prev: The continue Statement, Up: Statements 10.8 The unwind_protect Statement ================================= Octave supports a limited form of exception handling modeled after the unwind-protect form of Lisp. The general form of an ‘unwind_protect’ block looks like this: unwind_protect BODY unwind_protect_cleanup CLEANUP end_unwind_protect where BODY and CLEANUP are both optional and may contain any Octave expressions or commands. The statements in CLEANUP are guaranteed to be executed regardless of how control exits BODY. This is useful to protect temporary changes to global variables from possible errors. For example, the following code will always restore the original value of the global variable ‘frobnosticate’ even if an error occurs in the first part of the ‘unwind_protect’ block. save_frobnosticate = frobnosticate; unwind_protect frobnosticate = true; ... unwind_protect_cleanup frobnosticate = save_frobnosticate; end_unwind_protect Without ‘unwind_protect’, the value of FROBNOSTICATE would not be restored if an error occurs while evaluating the first part of the ‘unwind_protect’ block because evaluation would stop at the point of the error and the statement to restore the value would not be executed. In addition to unwind_protect, Octave supports another form of exception handling, the ‘try’ block.  File: octave.info, Node: The try Statement, Next: Continuation Lines, Prev: The unwind_protect Statement, Up: Statements 10.9 The try Statement ====================== The original form of a ‘try’ block looks like this: try BODY catch CLEANUP end_try_catch where BODY and CLEANUP are both optional and may contain any Octave expressions or commands. The statements in CLEANUP are only executed if an error occurs in BODY. No warnings or error messages are printed while BODY is executing. If an error does occur during the execution of BODY, CLEANUP can use the functions ‘lasterr’ or ‘lasterror’ to access the text of the message that would have been printed, as well as its identifier. The alternative form, try BODY catch ERR CLEANUP end_try_catch will automatically store the output of ‘lasterror’ in the structure ERR. *Note Errors and Warnings::, for more information about the ‘lasterr’ and ‘lasterror’ functions.  File: octave.info, Node: Continuation Lines, Prev: The try Statement, Up: Statements 10.10 Continuation Lines ======================== In the Octave language, most statements end with a newline character and you must tell Octave to ignore the newline character in order to continue a statement from one line to the next. Lines that end with the characters ‘...’ are joined with the following line before they are divided into tokens by Octave’s parser. For example, the lines x = long_variable_name ... + longer_variable_name ... - 42 form a single statement. Any text between the continuation marker and the newline character is ignored. For example, the statement x = long_variable_name ... # comment one + longer_variable_name ...comment two - 42 # last comment is equivalent to the one shown above. Inside double-quoted string constants, the character ‘\’ has to be used as continuation marker. The ‘\’ must appear at the end of the line just before the newline character: s = "This text starts in the first line \ and is continued in the second line." Input that occurs inside parentheses can be continued to the next line without having to use a continuation marker. For example, it is possible to write statements like if (fine_dining_destination == on_a_boat || fine_dining_destination == on_a_train) seuss (i, will, not, eat, them, sam, i, am, i, will, not, eat, green, eggs, and, ham); endif without having to add to the clutter with continuation markers.  File: octave.info, Node: Functions and Scripts, Next: Errors and Warnings, Prev: Statements, Up: Top 11 Functions and Scripts ************************ 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::  File: octave.info, Node: Introduction to Function and Script Files, Next: Defining Functions, Up: Functions and Scripts 11.1 Introduction to Function and Script Files ============================================== There are seven different things covered in this section. 1. Typing in a function at the command prompt. 2. Storing a group of commands in a file — called a script file. 3. Storing a function in a file—called a function file. 4. Subfunctions in function files. 5. Multiple functions in one script file. 6. Private functions. 7. Nested functions. Both function files and script files end with an extension of .m, for MATLAB compatibility. If you want more than one independent functions in a file, it must be a script file (*note 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.  File: octave.info, Node: Defining Functions, Next: Returning from a Function, Prev: Introduction to Function and Script Files, Up: Functions and Scripts 11.2 Defining Functions ======================= In its simplest form, the definition of a function named NAME looks like this: function NAME BODY endfunction 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 BODY consists of Octave statements. It is the most important part of the definition, because it says what the function should actually _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): function wakeup printf ("\a"); endfunction The ‘printf’ statement (*note Input and Output::) simply tells Octave to print the string "\a". The special character ‘\a’ stands for the alert character (ASCII 7). *Note 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 function NAME (ARG-LIST) BODY endfunction where 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 ‘wakeup’ to look like this: function wakeup (message) printf ("\a%s\n", message); endfunction Calling this function using a statement like this wakeup ("Rise and shine!"); will cause Octave to ring your terminal’s bell and print the message ‘Rise and shine!’, followed by a newline character (the ‘\n’ in the first argument to the ‘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: function RET-VAR = NAME (ARG-LIST) BODY endfunction The symbol 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 ARG-LIST and RET-VAR are also local to the function. *Note 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: function retval = avg (v) retval = sum (v) / length (v); endfunction If we had written ‘avg’ like this instead, function retval = avg (v) if (isvector (v)) retval = sum (v) / length (v); endif endfunction and then called the function with a matrix instead of a vector as the argument, Octave would have printed an error message like this: error: value on right hand side of assignment is undefined because the body of the ‘if’ statement was never executed, and ‘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, ‘avg’ could have been written like this: function retval = avg (v) retval = 0; if (isvector (v)) retval = sum (v) / length (v); else error ("avg: expecting vector argument"); endif endfunction 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 ‘nargin’. Each time a function is called, ‘nargin’ is automatically initialized to the number of arguments that have actually been passed to the function. For example, we might rewrite the ‘avg’ function like this: 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 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. -- : nargin () -- : nargin (FCN) Report the number of input arguments to a function. Called from within a function, return the number of arguments passed to the function. At the top level, return the number of command line arguments passed to Octave. If called with the optional argument FCN—a function name or handle—return the declared number of arguments that the function can accept. If the last argument to FCN is VARARGIN the returned value is negative. For example, the function ‘union’ for sets is declared as function [y, ia, ib] = union (a, b, varargin) and nargin ("union") ⇒ -3 Programming Note: ‘nargin’ does not work on compiled functions (‘.oct’ files) such as built-in or dynamically loaded functions. See also: *note nargout: XREFnargout, *note narginchk: XREFnarginchk, *note varargin: XREFvarargin, *note inputname: XREFinputname. -- : inputname (N) -- : inputname (N, IDS_ONLY) Return the name of the N-th argument to the calling function. If the argument is not a simple variable name, return an empty string. As an example, a reference to a field in a structure such as ‘s.field’ is not a simple name and will return "". ‘inputname’ is only useful within a function. When used at the command line it always returns an empty string. By default, return an empty string if the N-th argument is not a valid variable name. If the optional argument IDS_ONLY is false, return the text of the argument even if it is not a valid variable name. See also: *note nargin: XREFnargin, *note nthargout: XREFnthargout. -- : VAL = silent_functions () -- : OLD_VAL = silent_functions (NEW_VAL) -- : silent_functions (NEW_VAL, "local") Query or set the internal variable that controls whether internal output from a function is suppressed. If this option is disabled, Octave will display the results produced by evaluating expressions within a function body that are not terminated with a semicolon. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.  File: octave.info, Node: Returning from a Function, Next: Multiple Return Values, Prev: Defining Functions, Up: Functions and Scripts 11.3 Returning from a Function ============================== The body of a user-defined function can contain a ‘return’ statement. This statement returns control to the rest of the Octave program. It looks like this: return Unlike the ‘return’ statement in C, Octave’s ‘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 ‘function’ statement. The ‘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. 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 Note that this function could not have been written using the ‘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. -- : return When Octave encounters the keyword ‘return’ inside a function or script, it returns control to the caller immediately. At the top level, the return statement is ignored. A ‘return’ statement is assumed at the end of every function definition.  File: octave.info, Node: Multiple Return Values, Next: Variable-length Return Lists, Prev: Returning from a Function, Up: Functions and Scripts 11.4 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 function [RET-LIST] = NAME (ARG-LIST) BODY endfunction where NAME, ARG-LIST, and BODY have the same meaning as before, and 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 RET-LIST has only one element, this form of the ‘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. 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 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 ‘nthargout’ function to obtain only some of the return values or several at once in a cell array. *Note Cell Array Objects::. -- : nthargout (N, FUNC, ...) -- : nthargout (N, NTOT, FUNC, ...) Return the Nth output argument of the function specified by the function handle or string FUNC. Any additional arguments are passed directly to FUNC. The total number of arguments to call FUNC with can be passed in NTOT; by default NTOT is N. The input N can also be a vector of indices of the output, in which case the output will be a cell array of the requested output arguments. The intended use ‘nthargout’ is to avoid intermediate variables. For example, when finding the indices of the maximum entry of a matrix, the following two compositions of nthargout M = magic (5); cell2mat (nthargout ([1, 2], @ind2sub, size (M), nthargout (2, @max, M(:)))) ⇒ 5 3 are completely equivalent to the following lines: M = magic (5); [~, idx] = max (M(:)); [i, j] = ind2sub (size (M), idx); [i, j] ⇒ 5 3 It can also be helpful to have all output arguments in a single cell in the following manner: USV = nthargout ([1:3], @svd, hilb (5)); See also: *note nargin: XREFnargin, *note nargout: XREFnargout, *note varargin: XREFvarargin, *note varargout: XREFvarargout, *note isargout: XREFisargout. In addition to setting ‘nargin’ each time a function is called, Octave also automatically initializes ‘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 ‘ans’ does not figure in the count of output arguments, so the value of ‘nargout’ may be zero. The ‘svd’ and ‘lu’ functions are examples of built-in functions that behave differently depending on the value of ‘nargout’. It is possible to write functions that only set some return values. For example, calling the function function [x, y, z] = f () x = 1; z = 2; endfunction as [a, b, c] = f () produces: a = 1 b = [](0x0) c = 2 along with a warning. -- : nargout () -- : nargout (FCN) Report the number of output arguments from a function. Called from within a function, return the number of values the caller expects to receive. At the top level, ‘nargout’ with no argument is undefined and will produce an error. If called with the optional argument FCN—a function name or handle—return the number of declared output values that the function can produce. If the final output argument is VARARGOUT the returned value is negative. For example, f () will cause ‘nargout’ to return 0 inside the function ‘f’ and [s, t] = f () will cause ‘nargout’ to return 2 inside the function ‘f’. In the second usage, nargout (@histc) # or nargout ("histc") using a string input will return 2, because ‘histc’ has two outputs, whereas nargout (@imread) will return -2, because ‘imread’ has two outputs and the second is VARARGOUT. Programming Note. ‘nargout’ does not work for built-in functions and returns -1 for all anonymous functions. See also: *note nargin: XREFnargin, *note varargout: XREFvarargout, *note isargout: XREFisargout, *note nthargout: XREFnthargout.  File: octave.info, Node: Variable-length Return Lists, Next: Variable-length Argument Lists, Prev: Multiple Return Values, Up: Functions and Scripts 11.5 Variable-length Return Lists ================================= 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 ‘varargin’ parameter name. To let a function return a variable number of output arguments the special output parameter name ‘varargout’ is used. As with ‘varargin’, ‘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. function varargout = one_to_n () for i = 1:nargout varargout{i} = i; endfor endfunction When called this function returns values like this [a, b, c] = one_to_n () ⇒ a = 1 ⇒ b = 2 ⇒ c = 3 If ‘varargin’ (‘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. -- : [R1, R2, ..., RN] = deal (A) -- : [R1, R2, ..., RN] = deal (A1, A2, ..., AN) Copy the input parameters into the corresponding output parameters. If only a single input parameter is supplied, its value is copied to each of the outputs. For example, [a, b, c] = deal (x, y, z); is equivalent to a = x; b = y; c = z; and [a, b, c] = deal (x); is equivalent to a = b = c = x; Programming Note: ‘deal’ is often used with comma separated lists derived from cell arrays or structures. This is unnecessary as the interpreter can perform the same action without the overhead of a function call. For example: c = {[1 2], "Three", 4}; [x, y, z] = c{:} ⇒ x = 1 2 y = Three z = 4 See also: *note cell2struct: XREFcell2struct, *note struct2cell: XREFstruct2cell, *note repmat: XREFrepmat.  File: octave.info, Node: Variable-length Argument Lists, Next: Ignoring Arguments, Prev: Variable-length Return Lists, Up: Functions and Scripts 11.6 Variable-length Argument Lists =================================== 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: a = smallest (1, 2, 3); b = smallest (1, 2, 3, 4); In this example both ‘a’ and ‘b’ would be 1. One way to write the ‘smallest’ function is function val = smallest (arg1, arg2, arg3, arg4, arg5) BODY endfunction and then use the value of ‘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 ‘varargin’ appears at the end of a function parameter list it indicates that the function takes a variable number of input arguments. Using ‘varargin’ the function looks like this function val = smallest (varargin) BODY endfunction In the function body the input arguments can be accessed through the variable ‘varargin’. This variable is a cell array containing all the input arguments. *Note Cell Arrays::, for details on working with cell arrays. The ‘smallest’ function can now be defined like this function val = smallest (varargin) val = min ([varargin{:}]); endfunction 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 ‘varargin’ is a function ‘print_arguments’ that prints all input arguments. Such a function can be defined like this function print_arguments (varargin) for i = 1:length (varargin) printf ("Input argument %d: ", i); disp (varargin{i}); endfor endfunction This function produces output like this print_arguments (1, "two", 3); ⊣ Input argument 1: 1 ⊣ Input argument 2: two ⊣ Input argument 3: 3 -- : [REG, PROP] = parseparams (PARAMS) -- : [REG, VAR1, ...] = parseparams (PARAMS, NAME1, DEFAULT1, ...) Return in REG the cell elements of PARAM up to the first string element and in PROP all remaining elements beginning with the first string element. For example: [reg, prop] = parseparams ({1, 2, "linewidth", 10}) reg = { [1,1] = 1 [1,2] = 2 } prop = { [1,1] = linewidth [1,2] = 10 } The parseparams function may be used to separate regular numeric arguments from additional arguments given as property/value pairs of the VARARGIN cell array. In the second form of the call, available options are specified directly with their default values given as name-value pairs. If PARAMS do not form name-value pairs, or if an option occurs that does not match any of the available options, an error occurs. When called from an m-file function, the error is prefixed with the name of the caller function. The matching of options is case-insensitive. See also: *note varargin: XREFvarargin, *note inputParser: XREFinputParser.  File: octave.info, Node: Ignoring Arguments, Next: Default Arguments, Prev: Variable-length Argument Lists, Up: Functions and Scripts 11.7 Ignoring Arguments ======================= In the formal argument list, it is possible to use the dummy placeholder ‘~’ instead of a name. This indicates that the corresponding argument value should be ignored and not stored to any variable. function val = pick2nd (~, arg2) val = arg2; endfunction The value of ‘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 ‘~’ placeholder. x = [2, 3, 1]; [s, i] = sort (x) ⇒ s = 1 2 3 i = 3 1 2 [~, i] = sort (x) ⇒ i = 3 1 2 When using the ‘~’ placeholder, commas—not whitespace—must be used to separate output arguments. Otherwise, the interpreter will view ‘~’ as the logical not operator. [~ i] = sort (x) parse error: invalid left hand side of assignment Functions may take advantage of ignored outputs to reduce the number of calculations performed. To do so, use the ‘isargout’ function to query whether the output argument is wanted. For example: function [out1, out2] = long_function (x, y, z) if (isargout (1)) ## Long calculation ... out1 = result; endif ... endfunction -- : isargout (K) Within a function, return a logical value indicating whether the argument K will be assigned to a variable on output. If the result is false, the argument has been ignored during the function call through the use of the tilde (~) special output argument. Functions can use ‘isargout’ to avoid performing unnecessary calculations for outputs which are unwanted. If K is outside the range ‘1:max (nargout)’, the function returns false. K can also be an array, in which case the function works element-by-element and a logical array is returned. At the top level, ‘isargout’ returns an error. See also: *note nargout: XREFnargout, *note varargout: XREFvarargout, *note nthargout: XREFnthargout.  File: octave.info, Node: Default Arguments, Next: Validating Arguments, Prev: Ignoring Arguments, Up: Functions and Scripts 11.8 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 function NAME (ARG1 = VAL1, ...) BODY endfunction If no value is assigned to ARG1 by the user, it will have the value VAL1. As an example, the following function implements a variant of the classic “Hello, World” program. function hello (who = "World") printf ("Hello, %s!\n", who); endfunction When called without an input argument the function prints the following hello (); ⊣ Hello, World! and when it’s called with an input argument it prints the following hello ("Beautiful World of Free Software"); ⊣ Hello, Beautiful World of Free Software! Sometimes it is useful to explicitly tell Octave to use the default value of an input argument. This can be done writing a ‘:’ as the value of the input argument when calling the function. hello (:); ⊣ Hello, World!  File: octave.info, Node: Validating Arguments, Next: Function Files, Prev: Default Arguments, Up: Functions and Scripts 11.9 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::  File: octave.info, Node: Validating the number of Arguments, Next: Validating the type of Arguments, Up: Validating Arguments 11.9.1 Validating the number of Arguments ----------------------------------------- In Octave the following idiom is seen frequently at the beginning of a function definition: if (nargin < min_#_inputs || nargin > max_#_inputs) print_usage (); endif 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 ‘narginchk’ and ‘nargoutchk’. -- : narginchk (MINARGS, MAXARGS) Check for correct number of input arguments. Generate an error message if the number of arguments in the calling function is outside the range MINARGS and MAXARGS. Otherwise, do nothing. Both MINARGS and MAXARGS must be scalar numeric values. Zero, Inf, and negative values are all allowed, and MINARGS and MAXARGS may be equal. Note that this function evaluates ‘nargin’ on the caller. See also: *note nargoutchk: XREFnargoutchk, *note error: XREFerror, *note nargout: XREFnargout, *note nargin: XREFnargin. -- : nargoutchk (MINARGS, MAXARGS) -- : MSGSTR = nargoutchk (MINARGS, MAXARGS, NARGS) -- : MSGSTR = nargoutchk (MINARGS, MAXARGS, NARGS, "string") -- : MSGSTRUCT = nargoutchk (MINARGS, MAXARGS, NARGS, "struct") Check for correct number of output arguments. In the first form, return an error if the number of arguments is not between MINARGS and MAXARGS. Otherwise, do nothing. Note that this function evaluates the value of ‘nargout’ on the caller so its value must have not been tampered with. Both MINARGS and MAXARGS must be numeric scalars. Zero, Inf, and negative are all valid, and they can have the same value. For backwards compatibility, the other forms return an appropriate error message string (or structure) if the number of outputs requested is invalid. This is useful for checking to that the number of output arguments supplied to a function is within an acceptable range. See also: *note narginchk: XREFnarginchk, *note error: XREFerror, *note nargout: XREFnargout, *note nargin: XREFnargin.  File: octave.info, Node: Validating the type of Arguments, Next: Parsing Arguments, Prev: Validating the number of Arguments, Up: Validating Arguments 11.9.2 Validating the type of Arguments --------------------------------------- Besides the number of arguments, inputs can be checked for various properties. ‘validatestring’ is used for string arguments and ‘validateattributes’ for numeric arguments. -- : VALIDSTR = validatestring (STR, STRARRAY) -- : VALIDSTR = validatestring (STR, STRARRAY, FUNCNAME) -- : VALIDSTR = validatestring (STR, STRARRAY, FUNCNAME, VARNAME) -- : VALIDSTR = validatestring (..., POSITION) Verify that STR is an element, or substring of an element, in STRARRAY. When STR is a character string to be tested, and STRARRAY is a cellstr of valid values, then VALIDSTR will be the validated form of STR where validation is defined as STR being a member or substring of VALIDSTR. This is useful for both verifying and expanding short options, such as "r", to their longer forms, such as "red". If STR is a substring of VALIDSTR, and there are multiple matches, the shortest match will be returned if all matches are substrings of each other. Otherwise, an error will be raised because the expansion of STR is ambiguous. All comparisons are case insensitive. The additional inputs FUNCNAME, VARNAME, and POSITION are optional and will make any generated validation error message more specific. Examples: validatestring ("r", {"red", "green", "blue"}) ⇒ "red" validatestring ("b", {"red", "green", "blue", "black"}) ⇒ error: validatestring: multiple unique matches were found for 'b': blue, black See also: *note strcmp: XREFstrcmp, *note strcmpi: XREFstrcmpi, *note validateattributes: XREFvalidateattributes, *note inputParser: XREFinputParser. -- : validateattributes (A, CLASSES, ATTRIBUTES) -- : validateattributes (A, CLASSES, ATTRIBUTES, ARG_IDX) -- : validateattributes (A, CLASSES, ATTRIBUTES, FUNC_NAME) -- : validateattributes (A, CLASSES, ATTRIBUTES, FUNC_NAME, ARG_NAME) -- : validateattributes (A, CLASSES, ATTRIBUTES, FUNC_NAME, ARG_NAME, ARG_IDX) Check validity of input argument. Confirms that the argument A is valid by belonging to one of CLASSES, and holding all of the ATTRIBUTES. If it does not, an error is thrown, with a message formatted accordingly. The error message can be made further complete by the function name FUN_NAME, the argument name ARG_NAME, and its position in the input ARG_IDX. CLASSES must be a cell array of strings (an empty cell array is allowed) with the name of classes (remember that a class name is case sensitive). In addition to the class name, the following categories names are also valid: "float" Floating point value comprising classes "double" and "single". "integer" Integer value comprising classes (u)int8, (u)int16, (u)int32, (u)int64. "numeric" Numeric value comprising either a floating point or integer value. ATTRIBUTES must be a cell array with names of checks for A. Some of them require an additional value to be supplied right after the name (see details for each below). "<=" All values are less than or equal to the following value in ATTRIBUTES. "<" All values are less than the following value in ATTRIBUTES. ">=" All values are greater than or equal to the following value in ATTRIBUTES. ">" All values are greater than the following value in ATTRIBUTES. "2d" A 2-dimensional matrix. Note that vectors and empty matrices have 2 dimensions, one of them being of length 1, or both length 0. "3d" Has no more than 3 dimensions. A 2-dimensional matrix is a 3-D matrix whose 3rd dimension is of length 1. "binary" All values are either 1 or 0. "column" Values are arranged in a single column. "decreasing" No value is NAN, and each is less than the preceding one. "diag" Value is a diagonal matrix. "even" All values are even numbers. "finite" All values are finite. "increasing" No value is NAN, and each is greater than the preceding one. "integer" All values are integer. This is different than using ‘isinteger’ which only checks its an integer type. This checks that each value in A is an integer value, i.e., it has no decimal part. "ncols" Has exactly as many columns as the next value in ATTRIBUTES. "ndims" Has exactly as many dimensions as the next value in ATTRIBUTES. "nondecreasing" No value is NAN, and each is greater than or equal to the preceding one. "nonempty" It is not empty. "nonincreasing" No value is NAN, and each is less than or equal to the preceding one. "nonnan" No value is a ‘NaN’. "nonnegative" All values are non negative. "nonsparse" It is not a sparse matrix. "nonzero" No value is zero. "nrows" Has exactly as many rows as the next value in ATTRIBUTES. "numel" Has exactly as many elements as the next value in ATTRIBUTES. "odd" All values are odd numbers. "positive" All values are positive. "real" It is a non-complex matrix. "row" Values are arranged in a single row. "scalar" It is a scalar. "size" Its size has length equal to the values of the next in ATTRIBUTES. The next value must is an array with the length for each dimension. To ignore the check for a certain dimension, the value of ‘NaN’ can be used. "square" Is a square matrix. "vector" Values are arranged in a single vector (column or vector). See also: *note isa: XREFisa, *note validatestring: XREFvalidatestring, *note inputParser: XREFinputParser. As alternatives to ‘validateattributes’ there are several shorter convenience functions to check for individual properties. -- : mustBeFinite (X) Require that input X is finite. Raise an error if any element of the input X is not finite, as determined by ‘isfinite (x)’. See also: *note mustBeNonNan: XREFmustBeNonNan, *note isfinite: XREFisfinite. -- : mustBeGreaterThan (X, C) Require that input X is greater than C. Raise an error if any element of the input X is not greater than C, as determined by ‘X > C’. See also: *note mustBeGreaterThanOrEqual: XREFmustBeGreaterThanOrEqual, *note mustBeLessThan: XREFmustBeLessThan, *note gt: XREFgt. -- : mustBeGreaterThanOrEqual (X, C) Require that input X is greater than or equal to C. Raise an error if any element of the input X is not greater than or equal to C, as determined by ‘X >= C’. See also: *note mustBeGreaterThan: XREFmustBeGreaterThan, *note mustBeLessThanOrEqual: XREFmustBeLessThanOrEqual, *note ge: XREFge. -- : mustBeInteger (X) Require that input X is integer-valued (but not necessarily integer-typed). Raise an error if any element of the input X is not a finite, real, integer-valued numeric value, as determined by various checks. See also: *note mustBeNumeric: XREFmustBeNumeric. -- : mustBeLessThan (X, C) Require that input X is less than C. Raise an error if any element of the input X is not less than C, as determined by ‘X < C’. See also: *note mustBeLessThanOrEqual: XREFmustBeLessThanOrEqual, *note mustBeGreaterThan: XREFmustBeGreaterThan, *note lt: XREFlt. -- : mustBeLessThanOrEqual (X, C) Require that input is less than or equal to a given value. Raise an error if any element of the input X is not less than or equal to C, as determined by ‘X <= C’. See also: *note mustBeLessThan: XREFmustBeLessThan, *note mustBeGreaterThanOrEqual: XREFmustBeGreaterThanOrEqual, *note le: XREFle. -- : mustBeMember (X, VALID) Require that input X is a member of a set of given valid values. Raise an error if any element of the input X is not a member of the set VALID, as determined by ‘ismember (X)’. Programming Note: char inputs may behave strangely because of the interaction between chars and cellstrings when calling ‘ismember’ on them. But it will probably "do what you mean" if you just use it naturally. To guarantee operation, convert all char arrays to cellstrings with ‘cellstr’. See also: *note mustBeNonempty: XREFmustBeNonempty, *note ismember: XREFismember. -- : mustBeNegative (X) Require that input X is negative. Raise an error if any element of the input X is not negative, as determined by ‘X < 0’. See also: *note mustBeNonnegative: XREFmustBeNonnegative. -- : mustBeNonempty (X) Require that input X is nonempty. Raise an error if the input X is empty, as determined by ‘isempty (X)’. See also: *note mustBeMember: XREFmustBeMember, *note mustBeNonzero: XREFmustBeNonzero, *note isempty: XREFisempty. -- : mustBeNonNan (X) Require that input X is non-‘NaN’. Raise an error if any element of the input X is ‘NaN’, as determined by ‘isnan (X)’. See also: *note mustBeFinite: XREFmustBeFinite, *note mustBeNonempty: XREFmustBeNonempty, *note isnan: XREFisnan. -- : mustBeNonnegative (X) Require that input X is not negative. Raise an error if any element of the input X is negative, as determined by ‘X >= 0’. See also: *note mustBeNonzero: XREFmustBeNonzero, *note mustBePositive: XREFmustBePositive. -- : mustBeNonpositive (X) Require that input X is not positive. Raise an error if any element of the input X is positive, as determined by ‘X <= 0’. See also: *note mustBeNegative: XREFmustBeNegative, *note mustBeNonzero: XREFmustBeNonzero. -- : mustBeNonsparse (X) Require that input X is not sparse. Raise an error if the input X is sparse, as determined by ‘issparse (X)’. See also: *note issparse: XREFissparse. -- : mustBeNonzero (X) Require that input X is not zero. Raise an error if any element of the input X is zero, as determined by ‘X == 0’. See also: *note mustBeNonnegative: XREFmustBeNonnegative, *note mustBePositive: XREFmustBePositive. -- : mustBeNumeric (X) Require that input X is numeric. Raise an error if the input X is not numeric, as determined by ‘isnumeric (X)’. See also: *note mustBeNumericOrLogical: XREFmustBeNumericOrLogical, *note isnumeric: XREFisnumeric. -- : mustBeNumericOrLogical (X) Require that input X is numeric or logical. Raise an error if the input X is not numeric or logical, as determined by ‘isnumeric (X) || islogical (X)’. See also: *note mustBeNumeric: XREFmustBeNumeric, *note isnumeric: XREFisnumeric, *note islogical: XREFislogical. -- : mustBePositive (X) Require that input X is positive. Raise an error if any element of the input X is not positive, as determined by ‘X > 0’. See also: *note mustBeNonnegative: XREFmustBeNonnegative, *note mustBeNonzero: XREFmustBeNonzero. -- : mustBeReal (X) Require that input X is real. Raise an error if the input X is not real, as determined by ‘isreal (X)’. See also: *note mustBeFinite: XREFmustBeFinite, *note mustBeNonNan: XREFmustBeNonNan, *note isreal: XREFisreal.  File: octave.info, Node: Parsing Arguments, Prev: Validating the type of Arguments, Up: Validating Arguments 11.9.3 Parsing Arguments ------------------------ If none of the preceding validation functions is sufficient there is also the class ‘inputParser’ which can perform extremely complex input checking for functions. -- : P = inputParser () Create object P of the inputParser class. This class is designed to allow easy parsing of function arguments. The class supports four types of arguments: 1. mandatory (see ‘addRequired’); 2. optional (see ‘addOptional’); 3. named (see ‘addParameter’); 4. switch (see ‘addSwitch’). After defining the function API with these methods, the supplied arguments can be parsed with the ‘parse’ method and the parsing results accessed with the ‘Results’ accessor. -- : inputParser.Parameters Return list of parameter names already defined. -- : inputParser.Results Return structure with argument names as fieldnames and corresponding values. -- : inputParser.Unmatched Return structure similar to ‘Results’, but for unmatched parameters. See the ‘KeepUnmatched’ property. -- : inputParser.UsingDefaults Return cell array with the names of arguments that are using default values. -- : inputParser.CaseSensitive = BOOLEAN Set whether matching of argument names should be case sensitive. Defaults to false. -- : inputParser.FunctionName = NAME Set function name to be used in error messages; Defaults to empty string. -- : inputParser.KeepUnmatched = BOOLEAN Set whether an error should be given for non-defined arguments. Defaults to false. If set to true, the extra arguments can be accessed through ‘Unmatched’ after the ‘parse’ method. Note that since ‘Switch’ and ‘Parameter’ arguments can be mixed, it is not possible to know the unmatched type. If argument is found unmatched it is assumed to be of the ‘Parameter’ type and it is expected to be followed by a value. -- : inputParser.StructExpand = BOOLEAN Set whether a structure can be passed to the function instead of parameter/value pairs. Defaults to true. The following example shows how to use this class: function check (varargin) p = inputParser (); # create object p.FunctionName = "check"; # set function name p.addRequired ("pack", @ischar); # mandatory argument p.addOptional ("path", pwd(), @ischar); # optional argument ## create a function handle to anonymous functions for validators val_mat = @(x) isvector (x) && all (x <= 1) && all (x >= 0); p.addOptional ("mat", [0 0], val_mat); ## create two arguments of type "Parameter" val_type = @(x) any (strcmp (x, {"linear", "quadratic"})); p.addParameter ("type", "linear", val_type); val_verb = @(x) any (strcmp (x, {"low", "medium", "high"})); p.addParameter ("tolerance", "low", val_verb); ## create a switch type of argument p.addSwitch ("verbose"); p.parse (varargin{:}); # Run created parser on inputs ## the rest of the function can access inputs by using p.Results. ## for example, get the tolerance input with p.Results.tolerance endfunction check ("mech"); # valid, use defaults for other arguments check (); # error, one argument is mandatory check (1); # error, since ! ischar check ("mech", "~/dev"); # valid, use defaults for other arguments check ("mech", "~/dev", [0 1 0 0], "type", "linear"); # valid ## following is also valid. Note how the Switch argument type can ## be mixed into or before the Parameter argument type (but it ## must still appear after any Optional argument). check ("mech", "~/dev", [0 1 0 0], "verbose", "tolerance", "high"); ## following returns an error since not all optional arguments, ## 'path' and 'mat', were given before the named argument 'type'. check ("mech", "~/dev", "type", "linear"); _Note 1_: A function can have any mixture of the four API types but they must appear in a specific order. ‘Required’ arguments must be first and can be followed by any ‘Optional’ arguments. Only the ‘Parameter’ and ‘Switch’ arguments may be mixed together and they must appear at the end. _Note 2_: If both ‘Optional’ and ‘Parameter’ arguments are mixed in a function API then once a string Optional argument fails to validate it will be considered the end of the ‘Optional’ arguments. The remaining arguments will be compared against any ‘Parameter’ or ‘Switch’ arguments. See also: *note nargin: XREFnargin, *note validateattributes: XREFvalidateattributes, *note validatestring: XREFvalidatestring, *note varargin: XREFvarargin.  File: octave.info, Node: Function Files, Next: Script Files, Prev: Validating Arguments, Up: Functions and Scripts 11.10 Function Files ==================== 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 “path”) for files ending in ‘.m’ that have the same base name as the undefined identifier.(1) Once Octave finds a file with a name that matches, the contents of the file are read. If it defines a _single_ function, it is compiled and executed. *Note 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 ‘OCTAVE-HOME/share/octave/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 ‘ignore_function_time_stamp ("all")’, so that Octave will ignore the time stamps for all function files. Passing "system" to this function resets the default behavior. -- : edit NAME -- : edit FIELD VALUE -- : VALUE = edit ("get", FIELD) -- : VALUE = edit ("get", "all") Edit the named function, or change editor settings. If ‘edit’ is called with the name of a file or function as its argument it will be opened in the text editor defined by ‘EDITOR’. • If the function NAME is available in a file on your path, then it will be opened in the editor. If no file is found, then the m-file variant, ending with ".m", will be considered. If still no file is found, then variants with a leading "@" and then with both a leading "@" and trailing ".m" will be considered. • If NAME is the name of a command-line function, then an m-file will be created to contain that function along with its current definition. • If ‘NAME.cc’ is specified, then it will search for ‘NAME.cc’ in the path and open it in the editor. If the file is not found, then a new ‘.cc’ file will be created. If NAME happens to be an m-file or command-line function, then the text of that function will be inserted into the .cc file as a comment. • If ‘NAME.ext’ is on your path then it will be edited, otherwise the editor will be started with ‘NAME.ext’ in the current directory as the filename. *Warning:* You may need to clear NAME before the new definition is available. If you are editing a .cc file, you will need to execute ‘mkoctfile NAME.cc’ before the definition will be available. If ‘edit’ is called with FIELD and VALUE variables, the value of the control field FIELD will be set to VALUE. If an output argument is requested and the first input argument is ‘get’ then ‘edit’ will return the value of the control field FIELD. If the control field does not exist, edit will return a structure containing all fields and values. Thus, ‘edit ("get", "all")’ returns a complete control structure. The following control fields are used: ‘author’ This is the name to put after the "## Author:" field of new functions. By default it guesses from the ‘gecos’ field of the password database. ‘email’ This is the e-mail address to list after the name in the author field. By default it guesses ‘<$LOGNAME@$HOSTNAME>’, and if ‘$HOSTNAME’ is not defined it uses ‘uname -n’. You probably want to override this. Be sure to use the format ‘’. ‘license’ ‘gpl’ GNU General Public License (default). ‘bsd’ BSD-style license without advertising clause. ‘pd’ Public domain. ‘"text"’ Your own default copyright and license. Unless you specify ‘pd’, edit will prepend the copyright statement with "Copyright (C) YYYY Author". ‘mode’ This value determines whether the editor should be started in async mode (editor is started in the background and Octave continues) or sync mode (Octave waits until the editor exits). Set it to "sync" to start the editor in sync mode. The default is "async" (*note system: XREFsystem.). ‘editinplace’ Determines whether files should be edited in place, without regard to whether they are modifiable or not. The default is ‘true’. Set it to ‘false’ to have read-only function files automatically copied to ‘home’, if it exists, when editing them. ‘home’ This value indicates a directory that system m-files should be copied into before opening them in the editor. The intent is that this directory is also in the path, so that the edited copy of a system function file shadows the original. This setting only has an effect when ‘editinplace’ is set to ‘false’. The default is the empty matrix (‘[]’), which means it is not used. The default in previous versions of Octave was ‘~/octave’. See also: *note EDITOR: XREFEDITOR, *note path: XREFpath. -- : mfilename () -- : mfilename ("fullpath") -- : mfilename ("fullpathext") Return the name of the currently executing file. The base name of the currently executing script or function is returned without any extension. If called from outside an m-file, such as the command line, return the empty string. Given the argument "fullpath", include the directory part of the filename, but not the extension. Given the argument "fullpathext", include the directory part of the filename and the extension. See also: *note inputname: XREFinputname, *note dbstack: XREFdbstack. -- : VAL = ignore_function_time_stamp () -- : OLD_VAL = ignore_function_time_stamp (NEW_VAL) Query or set the internal variable that controls whether Octave checks the time stamp on files each time it looks up functions defined in function files. If the internal variable is set to "system", Octave will not automatically recompile function files in subdirectories of ‘OCTAVE-HOME/share/VERSION/m’ if they have changed since they were last compiled, but will recompile other function files in the search path if they change. If set to "all", Octave will not recompile any function files unless their definitions are removed with ‘clear’. If set to "none", Octave will always check time stamps on files to determine whether functions defined in function files need to recompiled. * Menu: * Manipulating the Load Path:: * Subfunctions:: * Private Functions:: * Nested Functions:: * Overloading and Autoloading:: * Function Locking:: * Function Precedence:: ---------- Footnotes ---------- (1) The ‘.m’ suffix was chosen for compatibility with MATLAB.  File: octave.info, Node: Manipulating the Load Path, Next: Subfunctions, Up: Function Files 11.10.1 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 ‘path’ function without any input or output arguments. It is possible to add or remove directories to or from the load path using ‘addpath’ and ‘rmpath’. As an example, the following code adds ‘~/Octave’ to the load path. addpath ("~/Octave") After this the directory ‘~/Octave’ will be searched for functions. -- : addpath (DIR1, ...) -- : addpath (DIR1, ..., OPTION) Add named directories to the function search path. If OPTION is "-begin" or 0 (the default), prepend the directory name(s) to the current path. If OPTION is "-end" or 1, append the directory name(s) to the current path. Directories added to the path must exist. In addition to accepting individual directory arguments, lists of directory names separated by ‘pathsep’ are also accepted. For example: addpath ("dir1:/dir2:~/dir3") The newly added paths appear in the load path in the same order that they appear in the arguments of ‘addpath’. When extending the load path to the front, the last path in the list of arguments is added first. When extending the load path to the end, the first path in the list of arguments is added first. For each directory that is added, and that was not already in the path, ‘addpath’ checks for the existence of a file named ‘PKG_ADD’ (note lack of .m extension) and runs it if it exists. See also: *note path: XREFpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef, *note savepath: XREFsavepath, *note pathsep: XREFpathsep. -- : genpath (DIR) -- : genpath (DIR, SKIP, ...) Return a path constructed from DIR and all its subdirectories. The path does not include package directories (beginning with ‘+’), old-style class directories (beginning with ‘@’), ‘private’ directories, or any subdirectories of these types. If additional string parameters are given, the resulting path will exclude directories with those names. See also: *note path: XREFpath, *note addpath: XREFaddpath. -- : rmpath (DIR1, ...) Remove DIR1, ... from the current function search path. In addition to accepting individual directory arguments, lists of directory names separated by ‘pathsep’ are also accepted. For example: rmpath ("dir1:/dir2:~/dir3") For each directory that is removed, ‘rmpath’ checks for the existence of a file named ‘PKG_DEL’ (note lack of .m extension) and runs it if it exists. See also: *note path: XREFpath, *note addpath: XREFaddpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef, *note savepath: XREFsavepath, *note pathsep: XREFpathsep. -- : savepath () -- : savepath (FILE) -- : STATUS = savepath (...) Save the unique portion of the current function search path that is not set during Octave’s initialization process to FILE. If FILE is omitted, Octave looks in the current directory for a project-specific ‘.octaverc’ file in which to save the path information. If no such file is present then the user’s configuration file ‘~/.octaverc’ is used. If successful, ‘savepath’ returns 0. The ‘savepath’ function makes it simple to customize a user’s configuration file to restore the working paths necessary for a particular instance of Octave. Assuming no filename is specified, Octave will automatically restore the saved directory paths from the appropriate ‘.octaverc’ file when starting up. If a filename has been specified then the paths may be restored manually by calling ‘source FILE’. See also: *note path: XREFpath, *note addpath: XREFaddpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef. -- : path () -- : STR = path () -- : STR = path (PATH1, ...) Modify or display Octave’s load path. If NARGIN and NARGOUT are zero, display the elements of Octave’s load path in an easy to read format. If NARGIN is zero and nargout is greater than zero, return the current load path. If NARGIN is greater than zero, concatenate the arguments, separating them with ‘pathsep’. Set the internal search path to the result and return it. No checks are made for duplicate elements. See also: *note addpath: XREFaddpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef, *note savepath: XREFsavepath, *note pathsep: XREFpathsep. -- : VAL = pathdef () Return the default path for Octave. The path information is extracted from one of four sources. The possible sources, in order of preference, are: 1. ‘.octaverc’ 2. ‘~/.octaverc’ 3. ‘/...//m/startup/octaverc’ 4. Octave’s path prior to changes by any octaverc file. See also: *note path: XREFpath, *note addpath: XREFaddpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note savepath: XREFsavepath. -- : VAL = pathsep () Query the character used to separate directories in a path. See also: *note filesep: XREFfilesep. -- : rehash () Reinitialize Octave’s load path directory cache. -- : FNAME = file_in_loadpath (FILE) -- : FNAME = file_in_loadpath (FILE, "all") Return the absolute name of FILE if it can be found in the list of directories specified by ‘path’. If no file is found, return an empty character string. When FILE is already an absolute name, the name is checked against the file system instead of Octave’s loadpath. In this case, if FILE exists it will be returned in FNAME, otherwise an empty string is returned. If the first argument is a cell array of strings, search each directory of the loadpath for element of the cell array and return the first that matches. If the second optional argument "all" is supplied, return a cell array containing the list of all files that have the same name in the path. If no files are found, return an empty cell array. See also: *note file_in_path: XREFfile_in_path, *note dir_in_loadpath: XREFdir_in_loadpath, *note path: XREFpath. -- : restoredefaultpath () Restore Octave’s path to its initial state at startup. See also: *note path: XREFpath, *note addpath: XREFaddpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef, *note savepath: XREFsavepath, *note pathsep: XREFpathsep. -- : command_line_path () Return the command line path variable. See also: *note path: XREFpath, *note addpath: XREFaddpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef, *note savepath: XREFsavepath, *note pathsep: XREFpathsep. -- : DIRNAME = dir_in_loadpath (DIR) -- : DIRNAME = dir_in_loadpath (DIR, "all") Return the absolute name of the loadpath element matching DIR if it can be found in the list of directories specified by ‘path’. If no match is found, return an empty character string. The match is performed at the end of each path element. For example, if DIR is "foo/bar", it matches the path element "/some/dir/foo/bar", but not "/some/dir/foo/bar/baz" "/some/dir/allfoo/bar". When DIR is an absolute name, rather than just a path fragment, it is matched against the file system instead of Octave’s loadpath. In this case, if DIR exists it will be returned in DIRNAME, otherwise an empty string is returned. If the optional second argument is supplied, return a cell array containing all name matches rather than just the first. See also: *note file_in_path: XREFfile_in_path, *note file_in_loadpath: XREFfile_in_loadpath, *note path: XREFpath.  File: octave.info, Node: Subfunctions, Next: Private Functions, Prev: Manipulating the Load Path, Up: Function Files 11.10.2 Subfunctions -------------------- A function file may contain secondary functions called “subfunctions”. These secondary functions are only visible to the other functions in the same function file. For example, a file ‘f.m’ containing 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 defines a main function ‘f’ and two subfunctions. The subfunctions ‘g’ and ‘h’ may only be called from the main function ‘f’ or from the other subfunctions, but not from outside the file ‘f.m’. -- : localfunctions () Return a list of all local functions, i.e., subfunctions, within the current file. The return value is a column cell array of function handles to all local functions accessible from the function from which ‘localfunctions’ is called. Nested functions are _not_ included in the list. If the call is from the command line, an anonymous function, or a script, the return value is an empty cell array. See also: *note functions: XREFfunctions.  File: octave.info, Node: Private Functions, Next: Nested Functions, Prev: Subfunctions, Up: Function Files 11.10.3 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 ‘func1’, that calls a helper function ‘func2’ to do much of the work. For example: function y = func1 (x) y = func2 (x); endfunction Then if the path to ‘func1’ is ‘/func1.m’, and if ‘func2’ is found in the directory ‘/private/func2.m’, then ‘func2’ is only available for use of the functions, like ‘func1’, that are found in ‘’.  File: octave.info, Node: Nested Functions, Next: Overloading and Autoloading, Prev: Private Functions, Up: Function Files 11.10.4 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 ‘foo’, that calls a nested child function ‘bar’, with a shared variable X. function y = foo () x = 10; bar (); y = x; function bar () x = 20; endfunction endfunction foo () ⇒ 20 Notice that there is no special syntax for sharing 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 ‘foobar’ that uses variables X and Y. ‘foobar’ calls a nested function ‘foo’ which takes X as a parameter and returns Y. ‘foo’ then calls ‘bat’ which does some computation. 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 () ⇒ 10 It is important to note that the X and Y in ‘foobar’ remain zero, as in ‘foo’ they are a return value and parameter respectively. The X in ‘bat’ refers to the X in ‘foo’. Variable inheritance leads to a problem for ‘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 ‘foo’ with a nested child function ‘bar’: function y = foo (to_eval) bar (); eval (to_eval); function bar () eval ("x = 100;"); eval ("y = x;"); endfunction endfunction foo ("x = 5;") ⇒ error: can not add variable "x" to a static workspace foo ("y = 10;") ⇒ 10 foo ("") ⇒ 100 The parent function ‘foo’ is unable to create a new variable X, but the child function ‘bar’ was successful. Furthermore, even in an ‘eval’ statement Y in ‘bar’ is the same Y as in its parent function ‘foo’. The use of ‘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: 0. Globally visible functions 1. Any function that the nested function’s parent can call 2. Sibling functions (functions that have the same parents) 3. Direct children As a complex example consider a parent function ‘ex_top’ with two child functions, ‘ex_a’ and ‘ex_b’. In addition, ‘ex_a’ has two more child functions, ‘ex_aa’ and ‘ex_ab’. For 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  File: octave.info, Node: Overloading and Autoloading, Next: Function Locking, Prev: Nested Functions, Up: Function Files 11.10.5 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 (*note Function Overloading::). Occasionally, however, one needs to undo user overloading and call the default function associated with a specific type. The ‘builtin’ function exists for this purpose. -- : [...] = builtin (F, ...) Call the base function F even if F is overloaded to another function for the given type signature. This is normally useful when doing object-oriented programming and there is a requirement to call one of Octave’s base functions rather than the overloaded one of a new class. A trivial example which redefines the ‘sin’ function to be the ‘cos’ function shows how ‘builtin’ works. sin (0) ⇒ 0 function y = sin (x), y = cos (x); endfunction sin (0) ⇒ 1 builtin ("sin", 0) ⇒ 0 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 ‘autoload’ function, that permits the user to define in which file a certain function will be found. -- : AUTOLOAD_MAP = autoload () -- : autoload (FUNCTION, FILE) -- : autoload (..., "remove") Define FUNCTION to autoload from FILE. The second argument, FILE, should be an absolute filename or a file name in the same directory as the function or script from which the autoload command was run. FILE _should not_ depend on the Octave load path. Normally, calls to ‘autoload’ appear in PKG_ADD script files that are evaluated when a directory is added to Octave’s load path. To avoid having to hardcode directory names in FILE, if FILE is in the same directory as the PKG_ADD script then autoload ("foo", "bar.oct"); will load the function ‘foo’ from the file ‘bar.oct’. The above usage when ‘bar.oct’ is not in the same directory, or usages such as autoload ("foo", file_in_loadpath ("bar.oct")) are strongly discouraged, as their behavior may be unpredictable. With no arguments, return a structure containing the current autoload map. If a third argument "remove" is given, the function is cleared and not loaded anymore during the current Octave session. See also: *note PKG_ADD: XREFPKG_ADD.  File: octave.info, Node: Function Locking, Next: Function Precedence, Prev: Overloading and Autoloading, Up: Function Files 11.10.6 Function Locking ------------------------ It is sometime desirable to lock a function into memory with the ‘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 ‘clear’ does not remove this initialization. As an example, function my_function () mlock (); ... endfunction prevents ‘my_function’ from being removed from memory after it is called, even if ‘clear’ is called. It is possible to determine if a function is locked into memory with the ‘mislocked’, and to unlock a function with ‘munlock’, which the following code illustrates. my_function (); mislocked ("my_function") ⇒ ans = 1 munlock ("my_function"); mislocked ("my_function") ⇒ ans = 0 A common use of ‘mlock’ is to prevent persistent variables from being removed from memory, as the following example shows: function count_calls () mlock (); persistent calls = 0; printf ("count_calls() has been called %d times\n", ++calls); endfunction count_calls (); ⊣ count_calls() has been called 1 times clear count_calls count_calls (); ⊣ count_calls() has been called 2 times ‘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 ‘ignore_function_time_stamp’ function. -- : mlock () Lock the current function into memory so that it can’t be removed with ‘clear’. See also: *note munlock: XREFmunlock, *note mislocked: XREFmislocked, *note persistent: XREFpersistent, *note clear: XREFclear. -- : munlock () -- : munlock (FCN) Unlock the named function FCN so that it may be removed from memory with ‘clear’. If no function is named then unlock the current function. See also: *note mlock: XREFmlock, *note mislocked: XREFmislocked, *note persistent: XREFpersistent, *note clear: XREFclear. -- : mislocked () -- : mislocked (FCN) Return true if the named function FCN is locked in memory. If no function is named then return true if the current function is locked. See also: *note mlock: XREFmlock, *note munlock: XREFmunlock, *note persistent: XREFpersistent, *note clear: XREFclear.  File: octave.info, Node: Function Precedence, Prev: Function Locking, Up: Function Files 11.10.7 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 1. Subfunction A subfunction with the required function name in the given scope. 2. Private function A function defined within a private directory of the directory which contains the current function. 3. Class constructor A function that constructs a user class as defined in chapter *note Object Oriented Programming::. 4. Class method An overloaded function of a class as in chapter *note Object Oriented Programming::. 5. Command-line Function A function that has been defined on the command-line. 6. Autoload function A function that is marked as autoloaded with *Note autoload: XREFautoload. 7. 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. 8. Built-in function A function that is a part of core Octave such as ‘numel’, ‘size’, etc.  File: octave.info, Node: Script Files, Next: Function Handles and Anonymous Functions, Prev: Function Files, Up: Functions and Scripts 11.11 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 _not_ begin with the keyword ‘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 ‘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 ‘function’. If you have no other statements to evaluate, you can use a statement that has no effect, like this: # Prevent Octave from thinking that this # is a function file: 1; # Define function one: function one () ... 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 ‘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 ‘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, # not a function file: 1; function foo () do_something (); endfunction function do_something () do_something_else (); endfunction even though the function ‘do_something’ is not defined before it is referenced in the function ‘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 ‘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 ‘bar.m’ in Octave’s path. eval ("bar = 3"); bar 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 ‘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.m’, you can use the function ‘source’ to execute commands from any file. -- : source (FILE) -- : source (FILE, CONTEXT) Parse and execute the contents of FILE. Without specifying CONTEXT, this is equivalent to executing commands from a script file, but without requiring the file to be named ‘FILE.m’ or to be on the execution path. Instead of the current context, the script may be executed in either the context of the function that called the present function ("caller"), or the top-level context ("base"). See also: *note run: XREFrun. * Menu: * Publish Octave Script Files:: * Publishing Markup::  File: octave.info, Node: Publish Octave Script Files, Next: Publishing Markup, Up: Script Files 11.11.1 Publish Octave Script Files ----------------------------------- The function ‘publish’ provides a dynamic possibility to document your script file. Unlike static documentation, ‘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 *note Publishing Markup:: to enhance and customize the output. -- : publish (FILE) -- : publish (FILE, OUTPUT_FORMAT) -- : publish (FILE, OPTION1, VALUE1, ...) -- : publish (FILE, OPTIONS) -- : OUTPUT_FILE = publish (FILE, ...) Generate a report from the Octave script file FILE in one of several output formats. The generated reports interpret any Publishing Markup in comments, which is explained in detail in the GNU Octave manual. Assume the following example, using some Publishing Markup, to be the contents of the script file ‘pub_example.m’: ## Headline title # # Some *bold*, _italic_, or |monospaced| Text with # a . ## # "Real" Octave commands to be evaluated sombrero () %% MATLAB comment style ('%') is supported as well % % * Bulleted list item 1 % * Bulleted list item 2 % % # Numbered list item 1 % # Numbered list item 2 To publish this script file, type ‘publish ("pub_example.m")’. With only FILE given, a HTML report is generated in a subdirectory ‘html’ relative to the current working directory. The Octave commands are evaluated in a separate context and any figures created while executing the script file are included in the report. All formatting syntax of FILE is treated according to the specified output format and included in the report. Using ‘publish (FILE, OUTPUT_FORMAT)’ is equivalent to the function call using a structure OPTIONS.format = OUTPUT_FORMAT; publish (FILE, OPTIONS) which is described below. The same holds for using option/value pairs OPTIONS.OPTION1 = VALUE1; publish (FILE, OPTIONS) The structure OPTIONS can have the following field names. If a field name is not specified, the default value is used: • ‘format’ — Output format of the published script file, one of ‘html’ (default), ‘doc’, ‘latex’, ‘ppt’, ‘pdf’, or ‘xml’. The output formats ‘doc’, ‘ppt’, and ‘xml’ are not currently supported. To generate a ‘doc’ report, open a generated ‘html’ report with your office suite. In Octave custom formats are supported by implementing all callback subfunctions in a function file named ‘__publish__output__.m’. To obtain a template for the HTML format type: edit (fullfile (fileparts (which ("publish")), ... "private", "__publish_html_output__.m")) • ‘outputDir’ — Full path of the directory where the generated report will be located. If no directory is given, the report is generated in a subdirectory ‘html’ relative to the current working directory. • ‘stylesheet’ — Not supported, only for MATLAB compatibility. • ‘createThumbnail’ — Not supported, only for MATLAB compatibility. • ‘figureSnapMethod’ — Not supported, only for MATLAB compatibility. • ‘imageFormat’ — Desired format for any images produced while evaluating the code. The allowed image formats depend on the output format: • ‘html’, ‘xml’ — ‘png’ (default), any image format supported by Octave • ‘latex’ — ‘epsc2’ (default), any image format supported by Octave • ‘pdf’ — ‘jpg’ (default) or ‘bmp’, note MATLAB uses ‘bmp’ as default • ‘doc’ or ‘ppt’ — ‘png’ (default), ‘jpg’, ‘bmp’, or ‘tiff’ • ‘maxWidth’ and ‘maxHeight’ — Maximum width (height) of the produced images in pixels. An empty value means no restriction. Both values must be set in order for the option to work properly. ‘[]’ (default), integer value ≥ 0 • ‘useNewFigure’ — Use a new figure window for figures created by the evaluated code. This avoids side effects with already opened figure windows. ‘true’ (default) or ‘false’ • ‘evalCode’ — Evaluate code of the Octave source file ‘true’ (default) or ‘false’ • ‘catchError’ — Catch errors while evaluating code and continue ‘true’ (default) or ‘false’ • ‘codeToEvaluate’ — Octave commands that should be evaluated prior to publishing the script file. These Octave commands do not appear in the generated report. • ‘maxOutputLines’ — Maximum number of output lines from code evaluation which are included in output. ‘Inf’ (default) or integer value > 0 • ‘showCode’ — Show the evaluated Octave commands in the generated report ‘true’ (default) or ‘false’ The option output OUTPUT_FILE is a string with path and file name of the generated report. See also: *note grabcode: XREFgrabcode. The counterpart to ‘publish’ is ‘grabcode’: -- : grabcode (URL) -- : grabcode (FILENAME) -- : CODE_STR = grabcode (...) Grab the code from a report created by the ‘publish’ function. The grabbed code inside the published report must be enclosed by the strings ‘##### SOURCE BEGIN #####’ and ‘##### SOURCE END #####’. The ‘publish’ function creates this format automatically. If no return value is requested the code is saved to a temporary file and opened in the default editor. NOTE: The temporary file must be saved under a new or the code will be lost. If an output is requested the grabbed code will be returned as string CODE_STR. Example: publish ("my_script.m"); grabcode ("html/my_script.html"); The example above publishes ‘my_script.m’ to the default location ‘html/my_script.html’. Next, the published Octave script is grabbed to edit its content in a new temporary file. See also: *note publish: XREFpublish.  File: octave.info, Node: Publishing Markup, Prev: Publish Octave Script Files, Up: Script Files 11.11.2 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::  File: octave.info, Node: Using Publishing Markup in Script Files, Next: Text Formatting, Up: Publishing Markup 11.11.2.1 Using Publishing Markup in Script Files ................................................. To use Publishing Markup, start by typing ‘##’ or ‘%%’ at the beginning of a new line. For MATLAB compatibility ‘%%%’ is treated the same way as ‘%%’. The lines following ‘##’ or ‘%%’ start with one of either ‘#’ or ‘%’ followed by at least one space. These lines are interpreted as section. A section ends at the first line not starting with ‘#’ or ‘%’, 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: %% Headline title % % Some *bold*, _italic_, or |monospaced| Text with % a . %% # "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  File: octave.info, Node: Text Formatting, Next: Sections, Prev: Using Publishing Markup in Script Files, Up: Publishing Markup 11.11.2.2 Text Formatting ......................... Basic text formatting is supported inside sections, see the example given below: ## # *bold*, _italic_, or |monospaced| Text Additionally two trademark symbols are supported, just embrace the letters ‘TM’ or ‘R’. ## # (TM) or (R)  File: octave.info, Node: Sections, Next: Preformatted Code, Prev: Text Formatting, Up: Publishing Markup 11.11.2.3 Sections .................. A section is started by typing ‘##’ or ‘%%’ 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 ‘##’ or ‘%%’. Without a section title, the section is interpreted as a continuation of the previous section. For MATLAB compatibility ‘%%%’ is treated the same way as ‘%%’. some_code (); ## Section 1 # ## Section 2 some_code (); ## # Still in section 2 some_code (); %%% Section 3 % %  File: octave.info, Node: Preformatted Code, Next: Preformatted Text, Prev: Sections, Up: Publishing Markup 11.11.2.4 Preformatted Code ........................... To write preformatted code inside a section, indent the code by three spaces after ‘#’ at the beginning of each line and leave the lines above and below the code blank, except for ‘#’ at the beginning of those lines. ## # This is a syntax highlighted for-loop: # # for i = 1:5 # disp (i); # endfor # # And more usual text.  File: octave.info, Node: Preformatted Text, Next: Bulleted Lists, Prev: Preformatted Code, Up: Publishing Markup 11.11.2.5 Preformatted Text ........................... To write preformatted text inside a section, indent the code by two spaces after ‘#’ at the beginning of each line and leave the lines above and below the preformatted text blank, except for ‘#’ at the beginning of those lines. ## # 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  File: octave.info, Node: Bulleted Lists, Next: Numbered Lists, Prev: Preformatted Text, Up: Publishing Markup 11.11.2.6 Bulleted Lists ........................ To create a bulleted list, type ## # # * Bulleted list item 1 # * Bulleted list item 2 # to get output like • Bulleted list item 1 • Bulleted list item 2 Notice the blank lines, except for the ‘#’ or ‘%’ before and after the bulleted list!  File: octave.info, Node: Numbered Lists, Next: Including File Content, Prev: Bulleted Lists, Up: Publishing Markup 11.11.2.7 Numbered Lists ........................ To create a numbered list, type ## # # # Numbered list item 1 # # Numbered list item 2 # to get output like 1. Numbered list item 1 2. Numbered list item 2 Notice the blank lines, except for the ‘#’ or ‘%’ before and after the numbered list!  File: octave.info, Node: Including File Content, Next: Including Graphics, Prev: Numbered Lists, Up: Publishing Markup 11.11.2.8 Including File Content ................................ To include the content of an external file, e.g., a file called ‘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. ## # # my_function.m # # /full/path/to/my_function.m # # ../relative/path/to/my_function.m #  File: octave.info, Node: Including Graphics, Next: Including URLs, Prev: Including File Content, Up: Publishing Markup 11.11.2.9 Including Graphics ............................ To include external graphics, e.g., a graphic called ‘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. ## # # <> # # <> # # <<../relative/path/to/my_graphic.png>> #  File: octave.info, Node: Including URLs, Next: Mathematical Equations, Prev: Including Graphics, Up: Publishing Markup 11.11.2.10 Including URLs ......................... Basically, a URL is written between an opening ‘<’ and a closing ‘>’ angle. ## # Text that is within these angles and separated by at least one space from the URL is a displayed text for the link. ## # A link starting with ‘  File: octave.info, Node: Mathematical Equations, Next: HTML Markup, Prev: Including URLs, Up: Publishing Markup 11.11.2.11 Mathematical Equations ................................. One can insert LaTeX inline math, surrounded by single ‘$’ signs, or displayed math, surrounded by double ‘$$’ signs, directly inside sections. ## # 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}.$$  File: octave.info, Node: HTML Markup, Next: LaTeX Markup, Prev: Mathematical Equations, Up: Publishing Markup 11.11.2.12 HTML Markup ...................... If the published output is a HTML report, you can insert HTML markup, that is only visible in this kind of output. ## # # # # #  File: octave.info, Node: LaTeX Markup, Prev: HTML Markup, Up: Publishing Markup 11.11.2.13 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. ## # # Some output only visible in LaTeX or PDF reports. # \begin{equation} # e^x = \lim\limits_{n\rightarrow\infty}\left(1+\dfrac{x}{n}\right)^{n} # \end{equation} #  File: octave.info, Node: Function Handles and Anonymous Functions, Next: Command Syntax and Function Syntax, Prev: Script Files, Up: Functions and Scripts 11.12 Function Handles and 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::  File: octave.info, Node: Function Handles, Next: Anonymous Functions, Up: Function Handles and Anonymous Functions 11.12.1 Function Handles ------------------------ A function handle is a pointer to another function and is defined with the syntax @FUNCTION-NAME For example, f = @sin; creates a function handle called ‘f’ that refers to the function ‘sin’. Function handles are used to call other functions indirectly, or to pass a function as an argument to another function like ‘quad’ or ‘fsolve’. For example: f = @sin; quad (f, 0, pi) ⇒ 2 You may use ‘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 ‘()’. For example: f = @sin; feval (f, pi/4) ⇒ 0.70711 f (pi/4) ⇒ 0.70711 -- : is_function_handle (X) Return true if X is a function handle. See also: *note isa: XREFisa, *note typeinfo: XREFtypeinfo, *note class: XREFclass, *note functions: XREFfunctions. -- : S = functions (FCN_HANDLE) Return a structure containing information about the function handle FCN_HANDLE. The structure S always contains these three fields: function The function name. For an anonymous function (no name) this will be the actual function definition. type Type of the function. anonymous The function is anonymous. private The function is private. overloaded The function overloads an existing function. simple The function is a built-in or m-file function. subfunction The function is a subfunction within an m-file. nested The function is nested. file The m-file that will be called to perform the function. This field is empty for anonymous and built-in functions. In addition, some function types may return more information in additional fields. *Warning:* ‘functions’ is provided for debugging purposes only. Its behavior may change in the future and programs should not depend on any particular output format. See also: *note func2str: XREFfunc2str, *note str2func: XREFstr2func. -- : func2str (FCN_HANDLE) Return a string containing the name of the function referenced by the function handle FCN_HANDLE. See also: *note str2func: XREFstr2func, *note functions: XREFfunctions. -- : str2func (FCN_NAME) Return a function handle constructed from the string FCN_NAME. Previous versions of Octave accepted an optional second argument, "global", that caused str2func to ignore locally visible functions. This option is no longer supported. See also: *note func2str: XREFfunc2str, *note functions: XREFfunctions.  File: octave.info, Node: Anonymous Functions, Prev: Function Handles, Up: Function Handles and Anonymous Functions 11.12.2 Anonymous Functions --------------------------- Anonymous functions are defined using the syntax @(ARGUMENT-LIST) EXPRESSION 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 ‘quad’. For example, f = @(x) x.^2; quad (f, 0, 10) ⇒ 333.33 creates a simple unnamed function from the expression ‘x.^2’ and passes it to ‘quad’, quad (@(x) sin (x), 0, pi) ⇒ 2 wraps another function, and a = 1; b = 2; quad (@(x) betainc (x, a, b), 0, 0.4) ⇒ 0.13867 adapts a function with several parameters to the form required by ‘quad’. In this example, the values of A and B that are passed to ‘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 ‘sin (x)’ is 5X faster if the code is written as quad (@sin, 0, pi) rather than using the anonymous function ‘@(x) sin (x)’. There are many operators which have functional equivalents that may be better choices than an anonymous function. Instead of writing f = @(x, y) x + y this should be coded as f = @plus *Note Operator Overloading::, for a list of operators which also have a functional form.  File: octave.info, Node: Command Syntax and Function Syntax, Next: Organization of Functions, Prev: Function Handles and Anonymous Functions, Up: Functions and Scripts 11.13 Command Syntax and Function Syntax ======================================== Additionally to the function syntax described above (i.e., calling a function like ‘fun (arg1, arg2, ...)’), a function can be called using command syntax (for example, calling a function like ‘fun arg1 arg2 ...’). In that case, all arguments are passed to the function as strings. For example, my_command hello world is equivalent to my_command ("hello", "world") The general form of a command call is cmdname arg1 arg2 ... which translates directly to cmdname ("arg1", "arg2", ...) If an argument including spaces should be passed to a function in command syntax, (double-)quotes can be used. For example, my_command "first argument" "second argument" is equivalent to my_command ("first argument", "second argument") Any function can be used as a command if it accepts string input arguments. For example: toupper lower_case_arg ⇒ ans = LOWER_CASE_ARG 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: strvar = "hello world"; toupper strvar ⇒ ans = STRVAR toupper (strvar) ⇒ ans = HELLO WORLD 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 ‘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.  File: octave.info, Node: Organization of Functions, Prev: Command Syntax and Function Syntax, Up: Functions and Scripts 11.14 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 ‘OCTAVE-HOME/share/octave/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. ‘@ftp’ Class functions for the FTP object. ‘+containers’ Package for the containers classes. ‘audio’ Functions for playing and recording sounds. ‘deprecated’ Out-of-date functions which will eventually be removed from Octave. ‘elfun’ Elementary functions, principally trigonometric. ‘general’ Miscellaneous matrix manipulations, like ‘flipud’, ‘rot90’, and ‘triu’, as well as other basic functions, like ‘ismatrix’, ‘narginchk’, etc. ‘geometry’ Functions related to Delaunay triangulation. ‘gui’ Functions for GUI elements like dialog, message box, etc. ‘help’ Functions for Octave’s built-in help system. ‘image’ Image processing tools. These functions require the X Window System. ‘io’ Input-output functions. ‘java’ Functions related to the Java integration. ‘linear-algebra’ Functions for linear algebra. ‘miscellaneous’ Functions that don’t really belong anywhere else. ‘ode’ Functions to solve ordinary differential equations (ODEs). ‘optimization’ Functions related to minimization, optimization, and root finding. ‘path’ Functions to manage the directory path Octave uses to find functions. ‘pkg’ Package manager for installing external packages of functions in Octave. ‘plot’ Functions for displaying and printing two- and three-dimensional graphs. ‘polynomial’ Functions for manipulating polynomials. ‘prefs’ Functions implementing user-defined preferences. ‘set’ Functions for creating and manipulating sets of unique values. ‘signal’ Functions for signal processing applications. ‘sparse’ Functions for handling sparse matrices. ‘specfun’ Special functions such as ‘bessel’ or ‘factor’. ‘special-matrix’ Functions that create special matrix forms such as Hilbert or Vandermonde matrices. ‘startup’ Octave’s system-wide startup file. ‘statistics’ Statistical functions. ‘strings’ Miscellaneous string-handling functions. ‘testfun’ Functions for performing unit tests on other functions. ‘time’ Functions related to time and date processing.  File: octave.info, Node: Errors and Warnings, Next: Debugging, Prev: Functions and Scripts, Up: Top 12 Errors and Warnings ********************** Octave includes several functions for printing error and warning messages. When you write functions that need to take special action when they encounter abnormal conditions, you should print the error messages using the functions described in this chapter. Since many of Octave’s functions use these functions, it is also useful to understand them, so that errors and warnings can be handled. * Menu: * Handling Errors:: * Handling Warnings::  File: octave.info, Node: Handling Errors, Next: Handling Warnings, Up: Errors and Warnings 12.1 Handling Errors ==================== An error is something that occurs when a program is in a state where it doesn’t make sense to continue. An example is when a function is called with too few input arguments. In this situation the function should abort with an error message informing the user of the lacking input arguments. Since an error can occur during the evaluation of a program, it is very convenient to be able to detect that an error occurred, so that the error can be fixed. This is possible with the ‘try’ statement described in *note The try Statement::. * Menu: * Raising Errors:: * Catching Errors:: * Recovering From Errors::  File: octave.info, Node: Raising Errors, Next: Catching Errors, Up: Handling Errors 12.1.1 Raising Errors --------------------- The most common use of errors is for checking input arguments to functions. The following example calls the ‘error’ function if the function ‘f’ is called without any input arguments. function f (arg1) if (nargin == 0) error ("not enough input arguments"); endif endfunction When the ‘error’ function is called, it prints the given message and returns to the Octave prompt. This means that no code following a call to ‘error’ will be executed. It is also possible to assign an identification string to an error. If an error has such an ID the user can catch this error as will be described in the next section. To assign an ID to an error, simply call ‘error’ with two string arguments, where the first is the identification string, and the second is the actual error. Note that error IDs are in the format "NAMESPACE:ERROR-NAME". The namespace "Octave" is used for Octave’s own errors. Any other string is available as a namespace for user’s own errors. -- : error (TEMPLATE, ...) -- : error (ID, TEMPLATE, ...) Display an error message and stop m-file execution. Format the optional arguments under the control of the template string TEMPLATE using the same rules as the ‘printf’ family of functions (*note Formatted Output::) and print the resulting message on the ‘stderr’ stream. The message is prefixed by the character string ‘error: ’. Calling ‘error’ also sets Octave’s internal error state such that control will return to the top level without evaluating any further commands. This is useful for aborting from functions or scripts. If the error message does not end with a newline character, Octave will print a traceback of all the function calls leading to the error. For example, given the following function definitions: function f () g (); end function g () h (); end function h () nargin == 1 || error ("nargin != 1"); end calling the function ‘f’ will result in a list of messages that can help you to quickly find the exact location of the error: f () error: nargin != 1 error: called from: error: h at line 1, column 27 error: g at line 1, column 15 error: f at line 1, column 15 If the error message ends in a newline character, Octave will print the message but will not display any traceback messages as it returns control to the top level. For example, modifying the error message in the previous example to end in a newline causes Octave to only print a single message: function h () nargin == 1 || error ("nargin != 1\n"); end f () error: nargin != 1 A null string ("") input to ‘error’ will be ignored and the code will continue running as if the statement were a NOP. This is for compatibility with MATLAB. It also makes it possible to write code such as err_msg = ""; if (CONDITION 1) err_msg = "CONDITION 1 found"; elseif (CONDITION2) err_msg = "CONDITION 2 found"; ... endif error (err_msg); which will only stop execution if an error has been found. Implementation Note: For compatibility with MATLAB, escape sequences in TEMPLATE (e.g., "\n" => newline) are processed regardless of whether TEMPLATE has been defined with single quotes, as long as there are two or more input arguments. To disable escape sequence expansion use a second backslash before the sequence (e.g., "\\n") or use the ‘regexptranslate’ function. See also: *note warning: XREFwarning, *note lasterror: XREFlasterror. Since it is common to use errors when there is something wrong with the input to a function, Octave supports functions to simplify such code. When the ‘print_usage’ function is called, it reads the help text of the function calling ‘print_usage’, and presents a useful error. If the help text is written in Texinfo it is possible to present an error message that only contains the function prototypes as described by the ‘@deftypefn’ parts of the help text. When the help text isn’t written in Texinfo, the error message contains the entire help message. Consider the following function. ## -*- texinfo -*- ## @deftypefn {} f (@var{arg1}) ## Function help text goes here... ## @end deftypefn function f (arg1) if (nargin == 0) print_usage (); endif endfunction When it is called with no input arguments it produces the following error. f () ⊣ error: Invalid call to f. Correct usage is: ⊣ ⊣ -- f (ARG1) ⊣ ⊣ ⊣ Additional help for built-in functions and operators is ⊣ available in the online version of the manual. Use the command ⊣ 'doc ' to search the manual index. ⊣ ⊣ Help and information about Octave is also available on the WWW ⊣ at https://www.octave.org and via the help@octave.org ⊣ mailing list. -- : print_usage () -- : print_usage (NAME) Print the usage message for the function NAME. When called with no input arguments the ‘print_usage’ function displays the usage message of the currently executing function. See also: *note help: XREFhelp. -- : beep () Produce a beep from the speaker (or visual bell). This function sends the alarm character "\a" to the terminal. Depending on the user’s configuration this may produce an audible beep, a visual bell, or nothing at all. See also: *note puts: XREFputs, *note fputs: XREFfputs, *note printf: XREFprintf, *note fprintf: XREFfprintf. -- : VAL = beep_on_error () -- : OLD_VAL = beep_on_error (NEW_VAL) -- : beep_on_error (NEW_VAL, "local") Query or set the internal variable that controls whether Octave will try to ring the terminal bell before printing an error message. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.  File: octave.info, Node: Catching Errors, Next: Recovering From Errors, Prev: Raising Errors, Up: Handling Errors 12.1.2 Catching Errors ---------------------- When an error occurs, it can be detected and handled using the ‘try’ statement as described in *note The try Statement::. As an example, the following piece of code counts the number of errors that occurs during a ‘for’ loop. number_of_errors = 0; for n = 1:100 try ... catch number_of_errors++; end_try_catch endfor The above example treats all errors the same. In many situations it can however be necessary to discriminate between errors, and take different actions depending on the error. The ‘lasterror’ function returns a structure containing information about the last error that occurred. As an example, the code above could be changed to count the number of errors related to the ‘*’ operator. number_of_errors = 0; for n = 1:100 try ... catch msg = lasterror.message; if (strfind (msg, "operator *")) number_of_errors++; endif end_try_catch endfor Alternatively, the output of the ‘lasterror’ function can be found in a variable indicated immediately after the ‘catch’ keyword, as in the example below showing how to redirect an error as a warning: try ... catch err warning(err.identifier, err.message); ... end_try_catch -- : LASTERR = lasterror () -- : lasterror (ERR) -- : lasterror ("reset") Query or set the last error message structure. When called without arguments, return a structure containing the last error message and other information related to this error. The elements of the structure are: ‘message’ The text of the last error message ‘identifier’ The message identifier of this error message ‘stack’ A structure containing information on where the message occurred. This may be an empty structure if the information cannot be obtained. The fields of the structure are: ‘file’ The name of the file where the error occurred ‘name’ The name of function in which the error occurred ‘line’ The line number at which the error occurred ‘column’ An optional field with the column number at which the error occurred The last error structure may be set by passing a scalar structure, ERR, as input. Any fields of ERR that match those above are set while any unspecified fields are initialized with default values. If ‘lasterror’ is called with the argument "reset", all fields are set to their default values. See also: *note lasterr: XREFlasterr, *note error: XREFerror, *note lastwarn: XREFlastwarn. -- : [MSG, MSGID] = lasterr () -- : lasterr (MSG) -- : lasterr (MSG, MSGID) Query or set the last error message. When called without input arguments, return the last error message and message identifier. With one argument, set the last error message to MSG. With two arguments, also set the last message identifier. See also: *note lasterror: XREFlasterror, *note error: XREFerror, *note lastwarn: XREFlastwarn. The next example counts indexing errors. The errors are caught using the field identifier of the structure returned by the function ‘lasterror’. number_of_errors = 0; for n = 1:100 try ... catch id = lasterror.identifier; if (strcmp (id, "Octave:invalid-indexing")) number_of_errors++; endif end_try_catch endfor The functions distributed with Octave can issue one of the following errors. ‘Octave:bad-alloc’ Indicates that memory couldn’t be allocated. ‘Octave:invalid-context’ Indicates the error was generated by an operation that cannot be executed in the scope from which it was called. For example, the function ‘print_usage ()’ when called from the Octave prompt raises this error. ‘Octave:invalid-fun-call’ Indicates that a function was called in an incorrect way, e.g., wrong number of input arguments. ‘Octave:invalid-indexing’ Indicates that a data-type was indexed incorrectly, e.g., real-value index for arrays, nonexistent field of a structure. ‘Octave:invalid-input-arg’ Indicates that a function was called with invalid input arguments. ‘Octave:undefined-function’ Indicates a call to a function that is not defined. The function may exist but Octave is unable to find it in the search path. When an error has been handled it is possible to raise it again. This can be useful when an error needs to be detected, but the program should still abort. This is possible using the ‘rethrow’ function. The previous example can now be changed to count the number of errors related to the ‘*’ operator, but still abort if another kind of error occurs. number_of_errors = 0; for n = 1:100 try ... catch msg = lasterror.message; if (strfind (msg, "operator *")) number_of_errors++; else rethrow (lasterror); endif end_try_catch endfor -- : rethrow (ERR) Reissue a previous error as defined by ERR. ERR is a structure that must contain at least the "message" and "identifier" fields. ERR can also contain a field "stack" that gives information on the assumed location of the error. Typically ERR is returned from ‘lasterror’. See also: *note lasterror: XREFlasterror, *note lasterr: XREFlasterr, *note error: XREFerror. -- : ERR = errno () -- : ERR = errno (VAL) -- : ERR = errno (NAME) Query or set the system-dependent variable errno. When called with no inputs, return the current value of errno. When called with a numeric input VAL, set the current value of errno to the specified value. The previous value of errno is returned as ERR. When called with a character string NAME, return the numeric value of errno which corresponds to the specified error code. If NAME is not a recognized error code then -1 is returned. See also: *note errno_list: XREFerrno_list. -- : errno_list () Return a structure containing the system-dependent errno values. See also: *note errno: XREFerrno.  File: octave.info, Node: Recovering From Errors, Prev: Catching Errors, Up: Handling Errors 12.1.3 Recovering From Errors ----------------------------- Octave provides several ways of recovering from errors. There are ‘try’/‘catch’ blocks, ‘unwind_protect’/‘unwind_protect_cleanup’ blocks, and finally the ‘onCleanup’ command. The ‘onCleanup’ command associates an ordinary Octave variable (the trigger) with an arbitrary function (the action). Whenever the Octave variable ceases to exist—whether due to a function return, an error, or simply because the variable has been removed with ‘clear’—then the assigned function is executed. The function can do anything necessary for cleanup such as closing open file handles, printing an error message, or restoring global variables to their initial values. The last example is a very convenient idiom for Octave code. For example: function rand42 old_state = rand ("state"); restore_state = onCleanup (@() rand ("state", old_state)); rand ("state", 42); ... endfunction # rand generator state restored by onCleanup -- : OBJ = onCleanup (FUNCTION) Create a special object that executes a given function upon destruction. If the object is copied to multiple variables (or cell or struct array elements) or returned from a function, FUNCTION will be executed after clearing the last copy of the object. Note that if multiple local onCleanup variables are created, the order in which they are called is unspecified. For similar functionality *Note The unwind_protect Statement::.  File: octave.info, Node: Handling Warnings, Prev: Handling Errors, Up: Errors and Warnings 12.2 Handling Warnings ====================== Like an error, a warning is issued when something unexpected happens. Unlike an error, a warning doesn’t abort the currently running program. A simple example of a warning is when a number is divided by zero. In this case Octave will issue a warning and assign the value ‘Inf’ to the result. a = 1/0 ⊣ warning: division by zero ⇒ a = Inf * Menu: * Issuing Warnings:: * Enabling and Disabling Warnings::  File: octave.info, Node: Issuing Warnings, Next: Enabling and Disabling Warnings, Up: Handling Warnings 12.2.1 Issuing Warnings ----------------------- It is possible to issue warnings from any code using the ‘warning’ function. In its most simple form, the ‘warning’ function takes a string describing the warning as its input argument. As an example, the following code controls if the variable ‘a’ is non-negative, and if not issues a warning and sets ‘a’ to zero. a = -1; if (a < 0) warning ("'a' must be non-negative. Setting 'a' to zero."); a = 0; endif ⊣ 'a' must be non-negative. Setting 'a' to zero. Since warnings aren’t fatal to a running program, it is not possible to catch a warning using the ‘try’ statement or something similar. It is however possible to access the last warning as a string using the ‘lastwarn’ function. It is also possible to assign an identification string to a warning. If a warning has such an ID the user can enable and disable this warning as will be described in the next section. To assign an ID to a warning, simply call ‘warning’ with two string arguments, where the first is the identification string, and the second is the actual warning. Note that warning IDs are in the format "NAMESPACE:WARNING-NAME". The namespace "Octave" is used for Octave’s own warnings. Any other string is available as a namespace for user’s own warnings. -- : warning (TEMPLATE, ...) -- : warning (ID, TEMPLATE, ...) -- : warning ("on", ID) -- : warning ("off", ID) -- : warning ("error", ID) -- : warning ("query", ID) -- : warning (STATE, ID, "local") -- : warning (WARNING_STRUCT) -- : WARNING_STRUCT = warning (...) -- : warning (STATE, MODE) Display a warning message or control the behavior of Octave’s warning system. The first call form uses a template TEMPLATE and optional additional arguments to display a message on the ‘stderr’ stream. The message is formatted using the same rules as the ‘printf’ family of functions (*note Formatted Output::) and prefixed by the character string ‘warning: ’. You should use this function when you want to notify the user of an unusual condition, but only when it makes sense for your program to go on. For example: warning ("foo: maybe something wrong here"); If the warning message does not end with a newline character, Octave will print a traceback of all the function calls leading to the warning. If the warning message does end in a newline character, Octave will suppress the traceback messages as it returns control to the top level. For more details and examples, see *note error: XREFerror. The optional warning identifier ID allows users to enable or disable warnings tagged by this identifier. A message identifier is a string of the form "NAMESPACE:WARNING-NAME". Octave’s own warnings use the "Octave" namespace (*note warning_ids: XREFwarning_ids.). For example: warning ("MyNameSpace:check-something", "foo: maybe something wrong here"); The second call form is meant to change and/or query the state of warnings. The first input argument must be a string STATE ("on", "off", "error", or "query") followed by an optional warning identifier ID or "all" (default). The optional output argument WARNING_STRUCT is a structure or structure array with fields "state" and "identifier". The STATE argument may have the following values: "on"|"off": Enable or disable the display of warnings identified by ID and optionally return their previous state STOUT. "error": Turn warnings identified by ID into errors and optionally return their previous state STOUT. "query": Return the current state of warnings identified by ID. A structure or structure array WARNING_STRUCT, with fields "state" and "identifier", may be given as an input to achieve equivalent results. The following example shows how to temporarily disable a warning and then restore its original state: loglog (-1:10); ## Disable the previous warning and save its original state [~, id] = lastwarn (); warnstate = warning ("off", id); loglog (-1:10); ## Restore its original state warning (warnstate); If a final argument "local" is provided then the warning state will be set temporarily until the end of the current function. Changes to warning states that are set locally affect the current function and all functions called from the current scope. The previous warning state is restored on return from the current function. The "local" option is ignored if used in the top-level workspace. With no input argument ‘warning ()’ is equivalent to ‘warning ("query", "all")’ except that in the absence of an output argument, the state of warnings is displayed on ‘stderr’. The level of verbosity of the warning system may also be controlled by two modes MODE: "backtrace": enable/disable the display of the stack trace after the warning message "verbose": enable/disable the display of additional information after the warning message In this case the STATE argument may only be "on" or "off". Implementation Note: For compatibility with MATLAB, escape sequences in TEMPLATE (e.g., "\n" => newline) are processed regardless of whether TEMPLATE has been defined with single quotes, as long as there are two or more input arguments. To disable escape sequence expansion use a second backslash before the sequence (e.g., "\\n") or use the ‘regexptranslate’ function. See also: *note warning_ids: XREFwarning_ids, *note lastwarn: XREFlastwarn, *note error: XREFerror. -- : [MSG, MSGID] = lastwarn () -- : lastwarn (MSG) -- : lastwarn (MSG, MSGID) Query or set the last warning message. When called without input arguments, return the last warning message and message identifier. With one argument, set the last warning message to MSG. With two arguments, also set the last message identifier. See also: *note warning: XREFwarning, *note lasterror: XREFlasterror, *note lasterr: XREFlasterr. The functions distributed with Octave can issue one of the following warnings. ‘Octave:abbreviated-property-match’ By default, the ‘Octave:abbreviated-property-match’ warning is enabled. ‘Octave:addpath-pkg’ If the ‘Octave:addpath-pkg’ warning is enabled, Octave will warn when a package directory (i.e., +package_name) is added to the ‘path’. Typically, only the parent directory which contains the package directory should be added to the load path. By default, the ‘Octave:addpath-pkg’ warning is enabled. ‘Octave:array-as-logical’ If the ‘Octave:array-as-logical’ warning is enabled, Octave will warn when an array of size greater than 1x1 is used as a truth value in an if, while, or until statement. By default, the ‘Octave:array-as-logical’ warning is disabled. ‘Octave:array-to-scalar’ If the ‘Octave:array-to-scalar’ warning is enabled, Octave will warn when an implicit conversion from an array to a scalar value is attempted. By default, the ‘Octave:array-to-scalar’ warning is disabled. ‘Octave:array-to-vector’ If the ‘Octave:array-to-vector’ warning is enabled, Octave will warn when an implicit conversion from an array to a vector value is attempted. By default, the ‘Octave:array-to-vector’ warning is disabled. ‘Octave:assign-as-truth-value’ If the ‘Octave:assign-as-truth-value’ warning is enabled, a warning is issued for statements like if (s = t) ... since such statements are not common, and it is likely that the intent was to write if (s == t) ... instead. There are times when it is useful to write code that contains assignments within the condition of a ‘while’ or ‘if’ statement. For example, statements like while (c = getc ()) ... are common in C programming. It is possible to avoid all warnings about such statements by disabling the ‘Octave:assign-as-truth-value’ warning, but that may also let real errors like if (x = 1) # intended to test (x == 1)! ... slip by. In such cases, it is possible suppress errors for specific statements by writing them with an extra set of parentheses. For example, writing the previous example as while ((c = getc ())) ... will prevent the warning from being printed for this statement, while allowing Octave to warn about other assignments used in conditional contexts. By default, the ‘Octave:assign-as-truth-value’ warning is enabled. ‘Octave:autoload-relative-file-name’ If the ‘Octave:autoload-relative-file-name’ is enabled, Octave will warn when parsing autoload() function calls with relative paths to function files. This usually happens when using autoload() calls in PKG_ADD files, when the PKG_ADD file is not in the same directory as the .oct file referred to by the autoload() command. By default, the ‘Octave:autoload-relative-file-name’ warning is enabled. ‘Octave:built-in-variable-assignment’ By default, the ‘Octave:built-in-variable-assignment’ warning is enabled. ‘Octave:classdef-to-struct’ If the ‘Octave:classdef-to-struct’ warning is enabled, a warning is issued when a classdef object is forcibly converted into a struct with ‘struct (CLASSDEF_OBJ)’. Conversion removes the access restrictions from the object and makes private and protected properties visible. By default, the ‘Octave:classdef-to-struct’ warning is enabled. ‘Octave:colon-complex-argument’ If the ‘Octave:colon-complex-argument’ warning is enabled, a warning is issued when one of the three arguments to the colon operator (base, increment, limit) is a complex value. For example, ‘1:3*i’ will cause a warning to be emitted. By default, the ‘Octave:colon-complex-argument’ warning is enabled. ‘Octave:colon-nonscalar-argument’ If the ‘Octave:colon-nonscalar-argument’ warning is enabled, a warning is issued when one of the three arguments to the colon operator (base, increment, limit) is not a scalar. For example, ‘1:[3, 5]’ will cause a warning to be emitted. By default, the ‘Octave:colon-nonscalar-argument’ warning is enabled. ‘Octave:data-file-in-path’ If the ‘Octave:data-file-in-path’ warning is enabled, a warning is issued when Octave does not find the target of a file operation such as ‘load’ or ‘fopen’ directly, but is able to locate the file in Octave’s search ‘path’ for files. The warning could indicate that a different file target than the programmer intended is being used. By default, the ‘Octave:data-file-in-path’ warning is enabled. ‘Octave:deprecated-function’ If the ‘Octave:deprecated-function’ warning is enabled, a warning is issued when Octave encounters a function that is obsolete and scheduled for removal from Octave. By default, the ‘Octave:deprecated-function’ warning is enabled. ‘Octave:deprecated-keyword’ If the ‘Octave:deprecated-keyword’ warning is enabled, a warning is issued when Octave encounters a keyword that is obsolete and scheduled for removal from Octave. By default, the ‘Octave:deprecated-keyword’ warning is enabled. ‘Octave:deprecated-property’ If the ‘Octave:deprecated-property’ warning is enabled, a warning is issued when Octave encounters a graphics property that is obsolete and scheduled for removal from Octave. By default, the ‘Octave:deprecated-property’ warning is enabled. ‘Octave:eigs:UnconvergedEigenvalues’ If the ‘Octave:eigs:UnconvergedEigenvalues’ warning is enabled then the eigs function will issue a warning if the number of calculated eigenvalues is less than the number of requested eigenvalues. By default, the ‘Octave:eigs:UnconvergedEigenvalues’ warning is enabled. ‘Octave:empty-index’ If the ‘Octave:empty-index’ warning is enabled then Octave will emit a warning whenever indexing operators are used without an index, for example ‘X()’. By default, the ‘Octave:empty-index’ warning is enabled. ‘Octave:erase:chararray’ If the ‘Octave:erase:chararray’ warning is enabled then the erase function will issue a warning if the input pattern is a character array rather than a string or cell array of strings. By default, the ‘Octave:erase:chararray’ warning is enabled. ‘Octave:function-name-clash’ If the ‘Octave:function-name-clash’ warning is enabled, a warning is issued when Octave finds that the name of a function defined in a function file differs from the name of the file. (If the names disagree, the name declared inside the file is ignored.) By default, the ‘Octave:function-name-clash’ warning is enabled. ‘Octave:future-time-stamp’ If the ‘Octave:future-time-stamp’ warning is enabled, Octave will print a warning if it finds a function file with a time stamp that is in the future. By default, the ‘Octave:future-time-stamp’ warning is enabled. ‘Octave:glyph-render’ If the ‘Octave:glyph-render’ warning is enabled, Octave will print a warning if the glyph for a character couldn’t be rendered with the current font. By default, the ‘Octave:glyph-render’ warning is enabled. ‘Octave:imag-to-real’ If the ‘Octave:imag-to-real’ warning is enabled, a warning is printed for implicit conversions of complex numbers to real numbers. By default, the ‘Octave:imag-to-real’ warning is disabled. ‘Octave:language-extension’ Print warnings when using features that are unique to the Octave language and that may still be missing in MATLAB. By default, the ‘Octave:language-extension’ warning is disabled. The ‘--traditional’ or ‘--braindead’ startup options for Octave may also be of use, *note Command Line Options::. ‘Octave:legacy-function’ If the ‘Octave:legacy-function’ warning is enabled, a warning is issued when Octave encounters a function that MATLAB has suggested should be avoided. The function may become obsolete at some point in the future and removed, in which case the warning will change to ‘Octave:deprecated-function’, and the function will continue to exist for two further versions of Octave before being removed. By default, the ‘Octave:legacy-function’ warning is enabled. ‘Octave:logical-conversion’ By default, the ‘Octave:logical-conversion’ warning is enabled. ‘Octave:lu:sparse_input’ If the ‘Octave:lu:sparse_input’ warning is enabled, Octave will warn when the lu function is called with a sparse input and less than four output arguments. In this case, sparsity-preserving column permutations are not performed and the result may be inaccurate. By default, the ‘Octave:lu:sparse_input’ warning is enabled. ‘Octave:missing-glyph’ If the ‘Octave:glyph-render’ warning is enabled, Octave will print a warning if the current font doesn’t provide a glyph for a used character. By default, the ‘Octave:missing-glyph’ warning is enabled. ‘Octave:missing-semicolon’ If the ‘Octave:missing-semicolon’ warning is enabled, Octave will warn when statements in function definitions don’t end in semicolons. By default the ‘Octave:missing-semicolon’ warning is disabled. ‘Octave:mixed-string-concat’ If the ‘Octave:mixed-string-concat’ warning is enabled, print a warning when concatenating a mixture of double and single quoted strings. By default, the ‘Octave:mixed-string-concat’ warning is disabled. ‘Octave:nearly-singular-matrix’ ‘Octave:singular-matrix’ These warnings are emitted if a (nearly) singular matrix is inverted. By default, the ‘Octave:nearly-singular-matrix’ and ‘Octave:singular-matrix’ warnings are enabled. ‘Octave:neg-dim-as-zero’ If the ‘Octave:neg-dim-as-zero’ warning is enabled, print a warning for expressions like eye (-1) By default, the ‘Octave:neg-dim-as-zero’ warning is disabled. ‘Octave:noninteger-range-as-index’ By default, the ‘Octave:noninteger-range-as-index’ warning is enabled. ‘Octave:num-to-str’ If the ‘Octave:num-to-str’ warning is enable, a warning is printed for implicit conversions of numbers to their UTF-8 encoded character equivalents when strings are constructed using a mixture of strings and numbers in matrix notation. For example, [ "f", 111, 111 ] ⇒ "foo" elicits a warning if the ‘Octave:num-to-str’ warning is enabled. By default, the ‘Octave:num-to-str’ warning is enabled. ‘Octave:possible-matlab-short-circuit-operator’ If the ‘Octave:possible-matlab-short-circuit-operator’ warning is enabled, Octave will warn about using the not short circuiting operators ‘&’ and ‘|’ inside ‘if’ or ‘while’ conditions. They normally never short circuit, but they do short circuit when used in a condition. By default, the ‘Octave:possible-matlab-short-circuit-operator’ warning is enabled. ‘Octave:recursive-path-search’ If the ‘Octave:recursive-path-search’ warning is enabled, Octave will issue a warning if ‘addpath’ is used with double trailing slashes. By default, the ‘Octave:recursive-path-search’ warning is enabled. ‘Octave:remove-init-dir’ The ‘path’ function changes the search path that Octave uses to find functions. It is possible to set the path to a value which excludes Octave’s own built-in functions. If the ‘Octave:remove-init-dir’ warning is enabled then Octave will warn when the ‘path’ function has been used in a way that may render Octave unworkable. By default, the ‘Octave:remove-init-dir’ warning is enabled. ‘Octave:reload-forces-clear’ If several functions have been loaded from the same file, Octave must clear all the functions before any one of them can be reloaded. If the ‘Octave:reload-forces-clear’ warning is enabled, Octave will warn you when this happens, and print a list of the additional functions that it is forced to clear. By default, the ‘Octave:reload-forces-clear’ warning is enabled. ‘Octave:separator-insert’ Print warning if commas or semicolons might be inserted automatically in literal matrices. By default, the ‘Octave:separator-insert’ warning is disabled. ‘Octave:shadowed-function’ If the ‘Octave:shadowed-function’ warning is enabled, Octave will warn if a path is added to the search path that contains functions that shadow core functions. By default, the ‘Octave:shadowed-function’ warning is enabled. ‘Octave:single-quote-string’ Print warning if a single quote character is used to introduce a string constant. By default, the ‘Octave:single-quote-string’ warning is disabled. ‘Octave:sqrtm:SingularMatrix’ By default, the ‘Octave:sqrtm:SingularMatrix’ warning is enabled. ‘Octave:str-to-num’ If the ‘Octave:str-to-num’ warning is enabled, a warning is printed for implicit conversions of strings to their numeric UTF-8 encoded byte sequences. For example, "abc" + 0 ⇒ 97 98 99 elicits a warning if the ‘Octave:str-to-num’ warning is enabled. By default, the ‘Octave:str-to-num’ warning is disabled. ‘Octave:text_interpreter’ If the ‘Octave:text_interpreter’ warning is enabled, a warning is printed when the "interpreter" property of a text graphics object is set to the unsupported value of "latex". Even when enabled, the warning message is printed just once per Octave session. By default, the ‘Octave:glyph-render’ warning is enabled. ‘Octave:variable-switch-label’ If the ‘Octave:variable-switch-label’ warning is enabled, Octave will print a warning if a switch label is not a constant or constant expression. By default, the ‘Octave:variable-switch-label’ warning is disabled.  File: octave.info, Node: Enabling and Disabling Warnings, Prev: Issuing Warnings, Up: Handling Warnings 12.2.2 Enabling and Disabling Warnings -------------------------------------- The ‘warning’ function also allows you to control which warnings are actually printed to the screen. If the ‘warning’ function is called with a string argument that is either "on" or "off" all warnings will be enabled or disabled. It is also possible to enable and disable individual warnings through their string identifications. The following code will issue a warning warning ("example:non-negative-variable", "'a' must be non-negative. Setting 'a' to zero."); while the following won’t issue a warning warning ("off", "example:non-negative-variable"); warning ("example:non-negative-variable", "'a' must be non-negative. Setting 'a' to zero.");  File: octave.info, Node: Debugging, Next: Input and Output, Prev: Errors and Warnings, Up: Top 13 Debugging ************ Octave includes a built-in debugger to aid in the development of scripts. This can be used to interrupt the execution of an Octave script at a certain point, or when certain conditions are met. Once execution has stopped, and debug mode is entered, the symbol table at the point where execution has stopped can be examined and modified to check for errors. The normal command-line editing and history functions are available in debug mode. * Menu: * Entering Debug Mode:: * Leaving Debug Mode:: * Breakpoints:: * Debug Mode:: * Call Stack:: * Profiling:: * Profiler Example::  File: octave.info, Node: Entering Debug Mode, Next: Leaving Debug Mode, Up: Debugging 13.1 Entering Debug Mode ======================== There are two basic means of interrupting the execution of an Octave script. These are breakpoints (*note Breakpoints::), discussed in the next section, and interruption based on some condition. Octave supports three means to stop execution based on the values set in the functions ‘debug_on_interrupt’, ‘debug_on_warning’, and ‘debug_on_error’. -- : VAL = debug_on_interrupt () -- : OLD_VAL = debug_on_interrupt (NEW_VAL) -- : debug_on_interrupt (NEW_VAL, "local") Query or set the internal variable that controls whether Octave will try to enter debugging mode when it receives an interrupt signal (typically generated with ‘C-c’). If a second interrupt signal is received before reaching the debugging mode, a normal interrupt will occur. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note debug_on_error: XREFdebug_on_error, *note debug_on_warning: XREFdebug_on_warning. -- : VAL = debug_on_warning () -- : OLD_VAL = debug_on_warning (NEW_VAL) -- : debug_on_warning (NEW_VAL, "local") Query or set the internal variable that controls whether Octave will try to enter the debugger when a warning is encountered. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note debug_on_error: XREFdebug_on_error, *note debug_on_interrupt: XREFdebug_on_interrupt. -- : VAL = debug_on_error () -- : OLD_VAL = debug_on_error (NEW_VAL) -- : debug_on_error (NEW_VAL, "local") Query or set the internal variable that controls whether Octave will try to enter the debugger when an error is encountered. This will also inhibit printing of the normal traceback message (you will only see the top-level error message). When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note debug_on_warning: XREFdebug_on_warning, *note debug_on_interrupt: XREFdebug_on_interrupt.  File: octave.info, Node: Leaving Debug Mode, Next: Breakpoints, Prev: Entering Debug Mode, Up: Debugging 13.2 Leaving Debug Mode ======================= Use either ‘dbcont’ or ‘return’ to leave the debug mode and continue the normal execution of the script. -- : dbcont Leave command-line debugging mode and continue code execution normally. See also: *note dbstep: XREFdbstep, *note dbquit: XREFdbquit. To quit debug mode and return directly to the prompt without executing any additional code use ‘dbquit’. -- : dbquit -- : dbquit all Quit debugging mode immediately without further code execution. With no arguments, exit the current debugging level. With argument ‘all’, exit all debugging levels and return to the Octave prompt. See also: *note dbcont: XREFdbcont, *note dbstep: XREFdbstep. Finally, typing ‘exit’ or ‘quit’ at the debug prompt will result in Octave terminating normally.  File: octave.info, Node: Breakpoints, Next: Debug Mode, Prev: Leaving Debug Mode, Up: Debugging 13.3 Breakpoints ================ Breakpoints can be set in any m-file function by using the ‘dbstop’ function. -- : dbstop FUNC -- : dbstop FUNC LINE -- : dbstop FUNC LINE1 LINE2 ... -- : dbstop LINE1 ... -- : dbstop in FUNC -- : dbstop in FUNC at LINE -- : dbstop in FUNC at LINE if "CONDITION" -- : dbstop in CLASS at METHOD -- : dbstop if EVENT -- : dbstop if EVENT ID -- : dbstop (BP_STRUCT) -- : RLINE = dbstop ... Set breakpoints for the built-in debugger. FUNC is the name of a function on the current ‘path’. When already in debug mode the FUNC argument can be omitted and the current function will be used. Breakpoints at subfunctions are set with the scope operator ‘>’. For example, If ‘file.m’ has a subfunction ‘func2’, then a breakpoint in ‘func2’ can be specified by ‘file>func2’. LINE is the line number at which to break. If LINE is not specified, it defaults to the first executable line in the file ‘func.m’. Multiple lines can be specified in a single command; when function syntax is used, the lines may also be passed as a single vector argument (‘[LINE1, LINE2, ...]’). CONDITION is any Octave expression that can be evaluated in the code context that exists at the breakpoint. When the breakpoint is encountered, CONDITION will be evaluated, and execution will stop if CONDITION is true. If CONDITION cannot be evaluated, for example because it refers to an undefined variable, an error will be thrown. Expressions with side effects (such as ‘y++ > 1’) will alter variables, and should generally be avoided. Conditions containing quotes (‘"’, ‘'’) or comment characters (‘#’, ‘%’) must be enclosed in quotes. (This does not apply to conditions entered from the editor’s context menu.) For example: dbstop in axis at 246 if 'any (opt == "x")' The form specifying EVENT does not cause a specific breakpoint at a given function and line number. Instead it causes debug mode to be entered when certain unexpected events are encountered. Possible values are ‘error’ Stop when an error is reported. This is equivalent to specifying both ‘debug_on_error (true)’ and ‘debug_on_interrupt (true)’. ‘caught error’ Stop when an error is caught by a try-catch block (not yet implemented). ‘interrupt’ Stop when an interrupt (‘Ctrl-C’) occurs. ‘naninf’ Stop when code returns a non-finite value (not yet implemented). ‘warning’ Stop when a warning is reported. This is equivalent to specifying ‘debug_on_warning (true)’. The events ‘error’, ‘caught error’, and ‘warning’ can all be followed by a string specifying an error ID or warning ID. If that is done, only errors with the specified ID will cause execution to stop. To stop on one of a set of IDs, multiple ‘dbstop’ commands must be issued. Breakpoints and events can be removed using the ‘dbclear’ command with the same syntax. It is possible to save all breakpoints and restore them at once by issuing the commands ‘bp_state = dbstatus; ...; dbstop (bp_state)’. The optional output RLINE is the real line number where the breakpoint was set. This can differ from the specified line if the line is not executable. For example, if a breakpoint attempted on a blank line then Octave will set the real breakpoint at the next executable line. When a file is re-parsed, such as when it is modified outside the GUI, all breakpoints within the file are cleared. See also: *note dbclear: XREFdbclear, *note dbstatus: XREFdbstatus, *note dbstep: XREFdbstep, *note debug_on_error: XREFdebug_on_error, *note debug_on_warning: XREFdebug_on_warning, *note debug_on_interrupt: XREFdebug_on_interrupt. Breakpoints in class methods are also supported (e.g., ‘dbstop ("@class/method")’). However, breakpoints cannot be set in built-in functions (e.g., ‘sin’, etc.) or dynamically loaded functions (i.e., oct-files). To set a breakpoint immediately upon entering a function use line number 1, or omit the line number entirely and just give the function name. When setting the breakpoint Octave will ignore the leading comment block, and the breakpoint will be set on the first executable statement in the function. For example: dbstop ("asind", 1) ⇒ 29 Note that the return value of ‘29’ means that the breakpoint was effectively set to line 29. The status of breakpoints in a function can be queried with ‘dbstatus’. -- : dbstatus -- : dbstatus FUNC -- : BP_LIST = dbstatus ... Report the location of active breakpoints. When called with no input or output arguments, print the list of all functions with breakpoints and the line numbers where those breakpoints are set. If a function name FUNC is specified then only report breakpoints for the named function and its subfunctions. The optional return argument BP_LIST is a struct array with the following fields. name The name of the function with a breakpoint. A subfunction, say ‘func2’ within an m-file, say ‘file.m’, is specified as ‘file>func2’. file The name of the m-file where the function code is located. line The line number with the breakpoint. cond The condition that must be satisfied for the breakpoint to be active, or the empty string for unconditional breakpoints. If ‘dbstop if error’ is true but no explicit IDs are specified, the return value will have an empty field called "errs". If IDs are specified, the ‘errs’ field will have one row per ID. If ‘dbstop if error’ is false, there is no "errs" field. The "warn" field is set similarly by ‘dbstop if warning’. See also: *note dbstop: XREFdbstop, *note dbclear: XREFdbclear, *note dbwhere: XREFdbwhere, *note dblist: XREFdblist, *note dbstack: XREFdbstack. Reusing the previous example, ‘dbstatus ("asind")’ will return 29. The breakpoints listed can then be cleared with the ‘dbclear’ function. -- : dbclear FUNC -- : dbclear FUNC LINE -- : dbclear FUNC LINE1 LINE2 ... -- : dbclear LINE ... -- : dbclear all -- : dbclear in FUNC -- : dbclear in FUNC at LINE -- : dbclear if EVENT -- : dbclear ("FUNC") -- : dbclear ("FUNC", LINE) -- : dbclear ("FUNC", LINE1, LINE2, ...) -- : dbclear ("FUNC", LINE1, ...) -- : dbclear (LINE, ...) -- : dbclear ("all") Delete a breakpoint at line number LINE in the function FUNC. Arguments are FUNC Function name as a string variable. When already in debug mode this argument can be omitted and the current function will be used. LINE Line number from which to remove a breakpoint. Multiple lines may be given as separate arguments or as a vector. EVENT An event such as ‘error’, ‘interrupt’, or ‘warning’ (*note dbstop: XREFdbstop. for details). When called without a line number specification all breakpoints in the named function are cleared. If the requested line is not a breakpoint no action is performed. The special keyword "all" will clear all breakpoints from all files. See also: *note dbstop: XREFdbstop, *note dbstatus: XREFdbstatus, *note dbwhere: XREFdbwhere. A breakpoint may also be set in a subfunction. For example, if a file contains the functions function y = func1 (x) y = func2 (x); endfunction function y = func2 (x) y = x + 1; endfunction then a breakpoint can be set at the start of the subfunction directly with dbstop func1>func2 ⇒ 5 Note that ‘>’ is the character that distinguishes subfunctions from the m-file containing them. Another simple way of setting a breakpoint in an Octave script is the use of the ‘keyboard’ function. -- : keyboard () -- : keyboard ("PROMPT") Stop m-file execution and enter debug mode. When the ‘keyboard’ function is executed, Octave prints a prompt and waits for user input. The input strings are then evaluated and the results are printed. This makes it possible to examine the values of variables within a function, and to assign new values if necessary. To leave the prompt and return to normal execution type ‘return’ or ‘dbcont’. The ‘keyboard’ function does not return an exit status. If ‘keyboard’ is invoked without arguments, a default prompt of ‘debug> ’ is used. See also: *note dbstop: XREFdbstop, *note dbcont: XREFdbcont, *note dbquit: XREFdbquit. The ‘keyboard’ function is placed in a script at the point where the user desires that the execution be stopped. It automatically sets the running script into the debug mode.  File: octave.info, Node: Debug Mode, Next: Call Stack, Prev: Breakpoints, Up: Debugging 13.4 Debug Mode =============== There are three additional support functions that allow the user to find out where in the execution of a script Octave entered the debug mode, and to print the code in the script surrounding the point where Octave entered debug mode. -- : dbwhere In debugging mode, report the current file and line number where execution is stopped. See also: *note dbstack: XREFdbstack, *note dblist: XREFdblist, *note dbstatus: XREFdbstatus, *note dbcont: XREFdbcont, *note dbstep: XREFdbstep, *note dbup: XREFdbup, *note dbdown: XREFdbdown. -- : dbtype -- : dbtype LINENO -- : dbtype STARTL:ENDL -- : dbtype STARTL:END -- : dbtype FUNC -- : dbtype FUNC LINENO -- : dbtype FUNC STARTL:ENDL -- : dbtype FUNC STARTL:END Display a script file with line numbers. When called with no arguments in debugging mode, display the script file currently being debugged. An optional range specification can be used to list only a portion of the file. The special keyword "end" is a valid line number specification for the last line of the file. When called with the name of a function, list that script file with line numbers. See also: *note dblist: XREFdblist, *note dbwhere: XREFdbwhere, *note dbstatus: XREFdbstatus, *note dbstop: XREFdbstop. -- : dblist -- : dblist N In debugging mode, list N lines of the function being debugged centered around the current line to be executed. If unspecified N defaults to 10 (+/- 5 lines) See also: *note dbwhere: XREFdbwhere, *note dbtype: XREFdbtype, *note dbstack: XREFdbstack. You may also use ‘isdebugmode’ to determine whether the debugger is currently active. -- : isdebugmode () Return true if in debugging mode, otherwise false. See also: *note dbwhere: XREFdbwhere, *note dbstack: XREFdbstack, *note dbstatus: XREFdbstatus. Debug mode also allows single line stepping through a function using the command ‘dbstep’. -- : dbstep -- : dbstep N -- : dbstep in -- : dbstep out -- : dbnext ... In debugging mode, execute the next N lines of code. If N is omitted, execute the next single line of code. If the next line of code is itself defined in terms of an m-file remain in the existing function. Using ‘dbstep in’ will cause execution of the next line to step into any m-files defined on the next line. Using ‘dbstep out’ will cause execution to continue until the current function returns. ‘dbnext’ is an alias for ‘dbstep’. See also: *note dbcont: XREFdbcont, *note dbquit: XREFdbquit. When in debug mode the key will execute the last entered command. This is useful, for example, after hitting a breakpoint and entering ‘dbstep’ once. After that, one can advance line by line through the code with only a single key stroke. This feature may be disabled using the ‘auto_repeat_debug_command’ function. -- : VAL = auto_repeat_debug_command () -- : OLD_VAL = auto_repeat_debug_command (NEW_VAL) -- : auto_repeat_debug_command (NEW_VAL, "local") Query or set the internal variable that controls whether debugging commands are automatically repeated when the input line is empty (typing just ). When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.  File: octave.info, Node: Call Stack, Next: Profiling, Prev: Debug Mode, Up: Debugging 13.5 Call Stack =============== The function being debugged may be the leaf node of a series of function calls. After examining values in the current subroutine it may turn out that the problem occurred in earlier pieces of code. Use ‘dbup’ and ‘dbdown’ to move up and down through the series of function calls to locate where variables first took on the wrong values. ‘dbstack’ shows the entire series of function calls and at what level debugging is currently taking place. -- : dbstack -- : dbstack N -- : dbstack -COMPLETENAMES -- : [STACK, IDX] = dbstack (...) Display or return current debugging function stack information. With optional argument N, omit the N innermost stack frames. Although accepted, the argument -COMPLETENAMES is silently ignored. Octave always returns absolute filenames. The arguments N and -COMPLETENAMES can be both specified in any order. The optional return argument STACK is a struct array with the following fields: file The name of the m-file where the function code is located. name The name of the function with a breakpoint. line The line number of an active breakpoint. column The column number of the line where the breakpoint begins. scope Undocumented. context Undocumented. The return argument IDX specifies which element of the STACK struct array is currently active. See also: *note dbup: XREFdbup, *note dbdown: XREFdbdown, *note dbwhere: XREFdbwhere, *note dblist: XREFdblist, *note dbstatus: XREFdbstatus. -- : dbup -- : dbup N In debugging mode, move up the execution stack N frames. If N is omitted, move up one frame. See also: *note dbstack: XREFdbstack, *note dbdown: XREFdbdown. -- : dbdown -- : dbdown N In debugging mode, move down the execution stack N frames. If N is omitted, move down one frame. See also: *note dbstack: XREFdbstack, *note dbup: XREFdbup.  File: octave.info, Node: Profiling, Next: Profiler Example, Prev: Call Stack, Up: Debugging 13.6 Profiling ============== Octave supports profiling of code execution on a per-function level. If profiling is enabled, each call to a function (supporting built-ins, operators, functions in oct- and mex-files, user-defined functions in Octave code and anonymous functions) is recorded while running Octave code. After that, this data can aid in analyzing the code behavior, and is in particular helpful for finding “hot spots” in the code which use up a lot of computation time and are the best targets to spend optimization efforts on. The main command for profiling is ‘profile’, which can be used to start or stop the profiler and also to query collected data afterwards. The data is returned in an Octave data structure which can then be examined or further processed by other routines or tools. -- : profile on -- : profile off -- : profile resume -- : profile clear -- : S = profile ("status") -- : T = profile ("info") Control the built-in profiler. ‘profile on’ Start the profiler, clearing all previously collected data if there is any. ‘profile off’ Stop profiling. The collected data can later be retrieved and examined with ‘T = profile ("info")’. ‘profile clear’ Clear all collected profiler data. ‘profile resume’ Restart profiling without clearing the old data. All newly collected statistics are added to the existing ones. ‘S = profile ("status")’ Return a structure with information about the current status of the profiler. At the moment, the only field is ‘ProfilerStatus’ which is either "on" or "off". ‘T = profile ("info")’ Return the collected profiling statistics in the structure T. The flat profile is returned in the field ‘FunctionTable’ which is an array of structures, each entry corresponding to a function which was called and for which profiling statistics are present. In addition, the field ‘Hierarchical’ contains the hierarchical call tree. Each node has an index into the ‘FunctionTable’ identifying the function it corresponds to as well as data fields for number of calls and time spent at this level in the call tree. See also: *note profshow: XREFprofshow, *note profexplore: XREFprofexplore. An easy way to get an overview over the collected data is ‘profshow’. This function takes the profiler data returned by ‘profile’ as input and prints a flat profile, for instance: Function Attr Time (s) Calls ---------------------------------------- >myfib R 2.195 13529 binary <= 0.061 13529 binary - 0.050 13528 binary + 0.026 6764 This shows that most of the run time was spent executing the function ‘myfib’, and some minor proportion evaluating the listed binary operators. Furthermore, it is shown how often the function was called and the profiler also records that it is recursive. -- : profshow (DATA) -- : profshow (DATA, N) -- : profshow () -- : profshow (N) Display flat per-function profiler results. Print out profiler data (execution time, number of calls) for the most critical N functions. The results are sorted in descending order by the total time spent in each function. If N is unspecified it defaults to 20. The input DATA is the structure returned by ‘profile ("info")’. If unspecified, ‘profshow’ will use the current profile dataset. The attribute column displays ‘R’ for recursive functions, and is blank for all other function types. See also: *note profexplore: XREFprofexplore, *note profile: XREFprofile. -- : profexport (DIR) -- : profexport (DIR, DATA) -- : profexport (DIR, NAME) -- : profexport (DIR, NAME, DATA) Export profiler data as HTML. Export the profiling data in DATA into a series of HTML files in the folder DIR. The initial file will be ‘DATA/index.html’. If NAME is specified, it must be a string that contains a “name” for the profile being exported. This name is included in the HTML. The input DATA is the structure returned by ‘profile ("info")’. If unspecified, ‘profexport’ will use the current profile dataset. See also: *note profshow: XREFprofshow, *note profexplore: XREFprofexplore, *note profile: XREFprofile. -- : profexplore () -- : profexplore (DATA) Interactively explore hierarchical profiler output. Assuming DATA is the structure with profile data returned by ‘profile ("info")’, this command opens an interactive prompt that can be used to explore the call-tree. Type ‘help’ to get a list of possible commands. If DATA is omitted, ‘profile ("info")’ is called and used in its place. See also: *note profile: XREFprofile, *note profshow: XREFprofshow.  File: octave.info, Node: Profiler Example, Prev: Profiling, Up: Debugging 13.7 Profiler Example ===================== Below, we will give a short example of a profiler session. *Note Profiling::, for the documentation of the profiler functions in detail. Consider the code: global N A; N = 300; A = rand (N, N); function xt = timesteps (steps, x0, expM) global N; if (steps == 0) xt = NA (N, 0); else xt = NA (N, steps); x1 = expM * x0; xt(:, 1) = x1; xt(:, 2 : end) = timesteps (steps - 1, x1, expM); endif endfunction function foo () global N A; initial = @(x) sin (x); x0 = (initial (linspace (0, 2 * pi, N)))'; expA = expm (A); xt = timesteps (100, x0, expA); endfunction function fib = bar (N) if (N <= 2) fib = 1; else fib = bar (N - 1) + bar (N - 2); endif endfunction If we execute the two main functions, we get: tic; foo; toc; ⇒ Elapsed time is 2.37338 seconds. tic; bar (20); toc; ⇒ Elapsed time is 2.04952 seconds. But this does not give much information about where this time is spent; for instance, whether the single call to ‘expm’ is more expensive or the recursive time-stepping itself. To get a more detailed picture, we can use the profiler. profile on; foo; profile off; data = profile ("info"); profshow (data, 10); This prints a table like: # Function Attr Time (s) Calls --------------------------------------------- 7 expm 1.034 1 3 binary * 0.823 117 41 binary \ 0.188 1 38 binary ^ 0.126 2 43 timesteps R 0.111 101 44 NA 0.029 101 39 binary + 0.024 8 34 norm 0.011 1 40 binary - 0.004 101 33 balance 0.003 1 The entries are the individual functions which have been executed (only the 10 most important ones), together with some information for each of them. The entries like ‘binary *’ denote operators, while other entries are ordinary functions. They include both built-ins like ‘expm’ and our own routines (for instance ‘timesteps’). From this profile, we can immediately deduce that ‘expm’ uses up the largest proportion of the processing time, even though it is only called once. The second expensive operation is the matrix-vector product in the routine ‘timesteps’. (1) Timing, however, is not the only information available from the profile. The attribute column shows us that ‘timesteps’ calls itself recursively. This may not be that remarkable in this example (since it’s clear anyway), but could be helpful in a more complex setting. As to the question of why is there a ‘binary \’ in the output, we can easily shed some light on that too. Note that ‘data’ is a structure array (*note Structure Arrays::) which contains the field ‘FunctionTable’. This stores the raw data for the profile shown. The number in the first column of the table gives the index under which the shown function can be found there. Looking up ‘data.FunctionTable(41)’ gives: scalar structure containing the fields: FunctionName = binary \ TotalTime = 0.18765 NumCalls = 1 IsRecursive = 0 Parents = 7 Children = [](1x0) Here we see the information from the table again, but have additional fields ‘Parents’ and ‘Children’. Those are both arrays, which contain the indices of functions which have directly called the function in question (which is entry 7, ‘expm’, in this case) or been called by it (no functions). Hence, the backslash operator has been used internally by ‘expm’. Now let’s take a look at ‘bar’. For this, we start a fresh profiling session (‘profile on’ does this; the old data is removed before the profiler is restarted): profile on; bar (20); profile off; profshow (profile ("info")); This gives: # Function Attr Time (s) Calls ------------------------------------------------------- 1 bar R 2.091 13529 2 binary <= 0.062 13529 3 binary - 0.042 13528 4 binary + 0.023 6764 5 profile 0.000 1 8 false 0.000 1 6 nargin 0.000 1 7 binary != 0.000 1 9 __profiler_enable__ 0.000 1 Unsurprisingly, ‘bar’ is also recursive. It has been called 13,529 times in the course of recursively calculating the Fibonacci number in a suboptimal way, and most of the time was spent in ‘bar’ itself. Finally, let’s say we want to profile the execution of both ‘foo’ and ‘bar’ together. Since we already have the run-time data collected for ‘bar’, we can restart the profiler without clearing the existing data and collect the missing statistics about ‘foo’. This is done by: profile resume; foo; profile off; profshow (profile ("info"), 10); As you can see in the table below, now we have both profiles mixed together. # Function Attr Time (s) Calls --------------------------------------------- 1 bar R 2.091 13529 16 expm 1.122 1 12 binary * 0.798 117 46 binary \ 0.185 1 45 binary ^ 0.124 2 48 timesteps R 0.115 101 2 binary <= 0.062 13529 3 binary - 0.045 13629 4 binary + 0.041 6772 49 NA 0.036 101 ---------- Footnotes ---------- (1) We only know it is the binary multiplication operator, but fortunately this operator appears only at one place in the code and thus we know which occurrence takes so much time. If there were multiple places, we would have to use the hierarchical profile to find out the exact place which uses up the time which is not covered in this example.
12
33