octave: Status of 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.
DONTPRINTYET See also: 
whos XREFwhos, isglobal XREFisglobal, *noteDONTPRINTYET DONTPRINTYET See also: whos XREFwhos, isglobal XREFisglobal,
isvarname XREFisvarname, exist XREFexist, *noteregexp:
DONTPRINTYET DONTPRINTYET See also: whos XREFwhos, isglobal XREFisglobal,
isvarname XREFisvarname, exist XREFexist, 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
‘a’
Automatic variable. An automatic variable is one created
by the interpreter, for example ‘argn’.
‘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.
DONTPRINTYET See also: who XREFwho, *notewhos_line_format:
DONTPRINTYET See also: who XREFwho, 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]<command>[:width[:left-min[:balance]]];
The following command sequences are available:
‘%a’
Prints attributes of variables (g=global, p=persistent,
f=formal parameter, a=automatic variable).
‘%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: 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.
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. If you want information about other types of
files not on the search path you should 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.
DONTPRINTYET See also: file_in_loadpath XREFfile_in_loadpath, *noteDONTPRINTYET DONTPRINTYET See also: file_in_loadpath XREFfile_in_loadpath,
file_in_path XREFfile_in_path, *notedir_in_loadpath:
DONTPRINTYET DONTPRINTYET See also: file_in_loadpath XREFfile_in_loadpath,
file_in_path XREFfile_in_path, dir_in_loadpath
XREFdir_in_loadpath, 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’
function allows this.
-- : 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 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 (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’
Clear all local and global user-defined variables and all
functions from the symbol table.
‘-exclusive, -x’
Clear the variables that don’t match the following pattern.
‘-functions, -f’
Clear the function names and the built-in symbols names.
‘-global, -g’
Clear global symbol names.
‘-variables, -v’
Clear local variable names.
‘-classes, -c’
Clears the class structure table and clears all objects.
‘-regexp, -r’
The arguments are treated as regular expressions as any
variables that match will be cleared.
With the exception of ‘exclusive’, all long options can be used
without the dash as well.
DONTPRINTYET See also: who XREFwho, whos XREFwhos, *noteexist:
DONTPRINTYET See also: who XREFwho, whos XREFwhos, exist
XREFexist.
-- : pack ()
Consolidate workspace memory in MATLAB.
This function is provided for compatibility, but does nothing in
Octave.
See also: 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: help XREFhelp, 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;
nor does it support package directories. ‘what’ will always return
an empty list for these categories.
DONTPRINTYET See also: which XREFwhich, ls XREFls, *noteexist:
DONTPRINTYET See also: which XREFwhich, ls XREFls, exist
XREFexist.
Info Catalog
octave: Persistent Variables
octave: Variables