Programming Utilities

• Evaluating Strings as Commands
• Miscellaneous Utilities

Evaluating Strings as Commands

It is often useful to evaluate a string as if it were an Octave program, or use a string as the name of a function to call. These functions are necessary in order to evaluate commands that are not known until run time, or to write functions that will need to call user-supplied functions.

The function eval (command) parses command and evaluates it as if it were an Octave program, returning the last value computed. The command is evaluated in the current context, so any results remain available after eval returns. For example,

octave:13> a
error: `a' undefined
octave:14> eval ("a = 13")
a = 13
ans = 13
octave:15> a
a = 13

In this case, two values are printed: one for the expression that was evaluated, and one for the value returned from eval. Just as with any other expression, you can turn printing off by ending the expression in a semicolon. For example,

octave:13> a
error: `a' undefined
octave:14> eval ("a = 13;")
ans = 13
octave:15> a
a = 13

The function feval (name, ...) can be used to evaluate the function named name. Any arguments after the first are passed on to the named function. For example,

octave:12> feval ("acos", -1)
ans = 3.1416

calls the function acos with the argument `-1'.

The function feval is necessary in order to be able to write functions that call user-supplied functions, because Octave does not have a way to declare a pointer to a function (like C) or to declare a special kind of variable that can be used to hold the name of a function (like EXTERNAL in Fortran). Instead, you must refer to functions by name, and use feval to call them.

For example, here is a simple-minded function for finding the root of a function of one variable:

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.

Miscellaneous Utilities

The following functions allow you to determine the size of a variable or expression, find out whether a variable exists, print error messages, or delete variable names from the symbol table.

columns (a)

Return the number of columns of a.

rows (a)

Return the number of rows of a.

length (a)

Return the number of rows of a or the number of columns of a, whichever is larger.

size (a [, n])

Return the number rows and columns of a. With one input argument and one output argument, the result is returned in a 2 element row vector. If there are two output arguments, the number of rows is assigned to the first, and the number of columns to the second. For example,

octave:13> size ([1, 2; 3, 4; 5, 6])
ans =

  3  2

octave:14> [nr, nc] = size ([1, 2; 3, 4; 5, 6])
nr = 3

nc = 2

If given a second argument of either 1 or 2, size will return only the row or column dimension. For example

octave:15> size ([1, 2; 3, 4; 5, 6], 2)
ans = 2

returns the number of columns in the given matrix.

is_global (a)

Return 1 if a is globally visible. Otherwise, return 0.

is_matrix (a)

Return 1 if a is a matrix. Otherwise, return 0.

is_vector (a)

Return 1 if a is a vector. Otherwise, return 0.

is_scalar (a)

Return 1 if a is a scalar. Otherwise, return 0.

is_square (x)

If x is a square matrix, then return the dimension of x. Otherwise, return 0.

is_symmetric (x, tol)

If x is symmetric within the tolerance specified by tol, then return the dimension of x. Otherwise, return 0. If tol is omitted, use a tolerance equal to the machine precision.

isstr (a)

Return 1 if a is a string. Otherwise, return 0.

isempty (a)

Return 1 if a is an empty matrix (either the number of rows, or the number of columns, or both are zero). Otherwise, return 0.

clear pattern ...

Delete the names matching the given patterns from the symbol table. 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 lower and upper case 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 (local and global) are cleared from the symbol table. If clear is called with at least one argument, only the visible names matching the arguments are cleared. 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. This command may not be used within a function body.

who options pattern ...

List currently defined symbols matching the given patterns. The following are valid options. They may be shortened to one character but may not be combined.

-all

List all currently defined symbols.

-builtins

List built-in variables and functions. This includes all currently compiled function files, but does not include all function files that are in the LOADPATH.

-functions

List user-defined functions.

-long

Print a long listing including the type and dimensions of any symbols. The symbols in the first column of output indicate whether it is possible to redefine the symbol, and whether it is possible for it to be cleared.

-variables

List user-defined variables.

Valid patterns are the same as described for the clear command above. If no patterns are supplied, all symbols from the given category are listed. By default, only user defined functions and variables visible in the local scope are displayed. The command whos is equivalent to who -long.

exist (name)

Return 1 if the name exists as a variable, and 2 if the name (after appending `.m') is a function file in the path. Otherwise, return 0.

error (msg)

Print the message msg, prefixed by the string `error: ', and set Octave's internal error state such that control will return to the top level without evaluating any more commands. This is useful for aborting from functions. If msg does not end with a new line character, Octave will print a traceback of all the function calls leading to the error. For example,

function f () g () end
function g () h () end
function h () nargin == 1 || error ("nargin != 1"); end
f ()
error: nargin != 1
error: evaluating index expression near line 1, column 30
error: evaluating binary operator `||' near line 1, column 27
error: called from `h'
error: called from `g'
error: called from `f'

produces a list of messages that can help you to quickly locate the exact location of the error. If msg ends in a new line character, Octave will only print msg and 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 new line causes Octave to only print a single message:

function h () nargin == 1 || error ("nargin != 1\n"); end
f ()
error: nargin != 1

warning (msg)

Print the message msg prefixed by the string `warning: '.

usage (msg)

Print the message msg, prefixed by the string `usage: ', and set Octave's internal error state such that control will return to the top level without evaluating any more commands. This is useful for aborting from functions. After usage is evaluated, Octave will print a traceback of all the function calls leading to the usage message.

perror (name, num)

Print the error message for function name corresponding to the error number num. This function is intended to be used to print useful error messages for those functions that return numeric error codes.

menu (title, opt1, ...)

Print a title string followed by a series of options. Each option will be printed along with a number. The return value is the number of the option selected by the user. This function is useful for interactive programs. There is no limit to the number of options that may be passed in, but it may be confusing to present more than will fit easily on one screen.

document symbol text

Set the documentation string for symbol to text.

file_in_path (path, file)

Return the absolute name name of file if it can be found in path. The value of path should be a colon-separated list of directories in the format described for the built-in variable LOADPATH. If the file cannot be found in the path, an empty matrix is returned. For example,

octave:13> file_in_path (LOADPATH, "nargchk.m")
ans = /usr/local/lib/octave/1.1.0/m/general/nargchk.m

nargchk (nargin_min, nargin_max, n)

If n is in the range nargin_min through nargin_max inclusive, return the empty matrix. Otherwise, return a message indicating whether n is too large or too small. This is useful for checking to see that the number of arguments supplied to a function is within an acceptable range.

octave_tmp_file_name

Return a unique temporary file name. Since the named file is not opened, by octave_tmp_file_name, it is possible (though relatively unlikely) that it will not be available by the time your program attempts to open it.

type name ...

Display the definition of each name that refers to a function. Currently, Octave can only display functions that can be compiled cleanly, because it uses its internal representation of the function to recreate the program text. Comments are not displayed because Octave's currently discards them as it converts the text of a function file to its internal representation. This problem may be fixed in a future release.

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.