11.7 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.(4) 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. See section 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.

Built-in Function: mfilename ()

Built-in Function: mfilename ("fullpath")

Built-in Function: mfilename ("fullpathext")

Return the name of the currently executing file. At the top-level, return the empty string. Given the argument "fullpath", include the directory part of the file name, but not the extension. Given the argument "fullpathext", include the directory part of the file name and the extension.

Built-in Function: val = ignore_function_time_stamp ()

Built-in Function: 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/lib/version' 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 be recompiled.

11.7.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 the 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.

Built-in Function: addpath (dir1, …)

Built-in Function: addpath (dir1, …, option)

Add dir1, … to the current function search path. If option is `"-begin"' or 0 (the default), prepend the directory name to the current path. If option is `"-end"' or 1, append the directory name to the current path. Directories added to the path must exist.
See also: path, rmpath, genpath, pathdef, savepath, pathsep.

Built-in Function: genpath (dir)

Return a path constructed from dir and all its subdiretories.

Built-in Function: rmpath (dir1, …)

Remove dir1, … from the current function search path.

See also: path, addpath, genpath, pathdef, savepath, pathsep.

Function File: savepath (file)

Save the current function search path to file. If file is omitted, `~/.octaverc' is used. If successful, savepath returns 0.
See also: path, addpath, rmpath, genpath, pathdef, pathsep.

Built-in Function: path (…)

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: addpath, rmpath, genpath, pathdef, savepath, pathsep.

Built-in Function: val = pathdef ()

Return the default list of directories in which to search for function files.
See also: path, addpath, rmpath, genpath, savepath, pathsep.

Built-in Function: pathsep ()

Return the system-dependent character used to separate directories in a path.
See also: filesep, dir, ls.

Built-in Function: rehash ()

Reinitialize Octave's load path directory cache.

Built-in Function: file_in_loadpath (file)

Built-in Function: 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 matrix.

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: file_in_path, path.

11.7.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'.

11.7.3 Overloading and Autoloading

The dispatch function can be used to alias one function name to another. It can be used to alias all calls to a particular function name to another function, or the alias can be limited to only a particular variable type. Consider the example

function y = spsin (x)
  printf ("Calling spsin\n");
  fflush(stdout);
  y = spfun ("sin", x);
endfunction

dispatch ("sin", "spsin", "sparse matrix");
y0 = sin(eye(3));
y1 = sin(speye(3));

Which aliases the spsin to sin, but only for real sparse matrices. Note that the builtin sin already correctly treats sparse matrices and so this example is only illustrative.

Loadable Function: dispatch (f, r, type)

Replace the function f with a dispatch so that function r is called when f is called with the first argument of the named type. If the type is any then call r if no other type matches. The original function f is accessible using builtin (f, …).

If r is omitted, clear dispatch function associated with type.

If both r and type are omitted, list dispatch functions for f.
See also: builtin.

Loadable Function: […] builtin (f, …)

Call the base function f even if f is overloaded to some other function for the given type signature.
See also: dispatch.

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 also possible, but is undesirable as it multiples 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.

Built-in Function: autoload (function, file)

Define function to autoload from file.

The second argument, file, should be an absolute file name 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 the 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 when bar.oct is not in the same directory or uses like

autoload ("foo", file_in_loadpath ("bar.oct"))

are strongly discouraged, as their behavior might be unpredictable.

With no arguments, return a structure containing the current autoload map.
See also: PKG_ADD.

11.7.4 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,

mlock ("my_function");

prevents my_function from being removed from memory, 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 illustrates.

mlock ("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()
  persistent calls = 0;
  printf ("'count_calls' has been called %d times\n",
          ++calls);
endfunction
mlock ("count_calls");

count_calls ();
-| 'count_calls' has been called 1 times

clear count_calls
count_calls ();
-| 'count_calls' has been called 2 times

It is, however, often inconvenient to lock a function from the prompt, so it is also possible to lock a function from within its body. This is simply done by calling mlock from within the function.

function count_calls ()
  mlock ();
  persistent calls = 0;
  printf ("'count_calls' has been called %d times\n",
          ++calls);
endfunction

mlock might equally be used to prevent changes to a function from having effect in Octave, though a similar effect can be had with the ignore_function_time_stamp function.

Built-in Function: mlock (name)

Lock the named function into memory. If no function is named then lock in the current function.
See also: munlock, mislocked, persistent.

Built-in Function: munlock (fcn)

Unlock the named function. If no function is named then unlock the current function.
See also: mlock, mislocked, persistent.

Built-in Function: mislocked (fcn)

Return true if the named function is locked. If no function is named then return true if the current function is locked.
See also: mlock, munlock, persistent.

This document was generated on December, 26 2007 using texi2html 1.76.