GNU Octave Manual Version 3 by John W. Eaton, David Bateman, Søren Hauberg Paperback (6"x9"), 568 pages ISBN 095461206X RRP £24.95 ($39.95) Get a printed copy>>>

GNU Octave Manual Version 3 Buy the book here >>> $39.95

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
     -| *** local user variables:
     -| 
     -| __nargin__  str

Command: who options pattern ...

Command: whos 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 functions. This includes all currently compiled function files, but does not include all function files that are in the search path.

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

Command: whos options pattern ...

See who.

Built-in Function: val = whos_line_format ()

Built-in Function: old_val = whos_line_format (new_val)

Query or set the format string used by the whos.

The following escape sequences may be used in the format:

%b

Prints number of bytes occupied by variables.

%c

Prints class names of variables.

%e

Prints elements held by variables.

%n

Prints variable names.

%p

Prints protection attributes of variables.

%s

Prints dimensions of variables.

%t

Prints type names of variables.

Every command may also have a modifier:

l

Left alignment.

r

Right alignment (this is the default).

c

Centered (may only be applied to command %s).

A command is composed like this:

%[modifier]<command>[:size_of_parameter[:center-specific[
       :print_dims[:balance]]]];

Command and modifier is already explained. Size_of_parameter tells how many columns the parameter will need for printing. print_dims tells how many dimensions to print. If number of dimensions exceeds print_dims, dimensions will be printed like x-D. center-specific and print_dims may only be applied to command %s. A negative value for print_dims will cause Octave to print all dimensions whatsoever. balance specifies the offset for printing of the dimensions string.

The default format is " %p:4; %ln:6; %cs:16:6:8:1; %rb:12; %lc:-1;\n".

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 behaviour 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

Built-in Function: exist (name, type)

Return 1 if the name exists as a variable, 2 if the name is an absolute file name, an ordinary file in Octave's path, or (after appending ‘.m’) a function file in Octave's path, 3 if the name is a ‘.oct’ or ‘.mex’ file in Octave's path, 5 if the name is a built-in function, 7 if the name is a directory, or 103 if the name is a function not associated with a file (entered on the command line).

Otherwise, return 0.

This function also returns 2 if a regular file called name exists in Octave's search path. If you want information about other types of files, you should use some combination of the functions file_in_path and stat instead.

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.

‘"file"’

Check only for files.

‘"dir"’

Check only for directories.

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 function allows this.

Command: clear [options] 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.

The following options are available in both long and short form

-all, -a

Clears all local and global user-defined variables and all functions from the symbol table.

-exclusive, -x

Clears the variables that don't match the following pattern.

-functions, -f

Clears the function names and the built-in symbols names.

-global, -g

Clears the global symbol names.

-variables, -v

Clears the local variable names.

With the exception of exclusive, all long options can be used without the dash as well.

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.

Built-in Function: document (symbol, text)

Set the documentation string for symbol to text.

Command: type options name ...

Display the definition of each name that refers to a function.

Normally also displays whether each name is user-defined or built-in; the -q option suppresses this behaviour.

Command: 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 help, lookfor