/usr/share/doc/octave/octave.html/Status-of-Variables.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Status of Variables (GNU Octave)</title>

<meta name="description" content="Status of Variables (GNU Octave)">
<meta name="keywords" content="Status of Variables (GNU Octave)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Variables.html#Variables" rel="up" title="Variables">
<link href="Expressions.html#Expressions" rel="next" title="Expressions">
<link href="Persistent-Variables.html#Persistent-Variables" rel="prev" title="Persistent Variables">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">


</head>

<body lang="en">
<a name="Status-of-Variables"></a>
<div class="header">
<p>
Previous: <a href="Persistent-Variables.html#Persistent-Variables" accesskey="p" rel="prev">Persistent Variables</a>, Up: <a href="Variables.html#Variables" accesskey="u" rel="up">Variables</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Status-of-Variables-1"></a>
<h3 class="section">7.3 Status of Variables</h3>

<p>When creating simple one-shot programs it can be very convenient to
see which variables are available at the prompt.  The function <code>who</code>
and its siblings <code>whos</code> and <code>whos_line_format</code> will show
different information about what is in memory, as the following shows.
</p>
<div class="example">
<pre class="example">str = &quot;A random string&quot;;
who
 -| Variables in the current scope:
 -|
 -| ans  str
</pre></div>

<a name="XREFwho"></a><dl>
<dt><a name="index-who"></a>: <em></em> <strong>who</strong></dt>
<dt><a name="index-who-1"></a>: <em></em> <strong>who</strong> <em>pattern &hellip;</em></dt>
<dt><a name="index-who-2"></a>: <em></em> <strong>who</strong> <em>option pattern &hellip;</em></dt>
<dt><a name="index-who-3"></a>: <em>C =</em> <strong>who</strong> <em>(&quot;pattern&quot;, &hellip;)</em></dt>
<dd><p>List currently defined variables matching the given patterns.
</p>
<p>Valid pattern syntax is the same as described for the <code>clear</code> command.
If no patterns are supplied, all variables are listed.
</p>
<p>By default, only variables visible in the local scope are displayed.
</p>
<p>The following are valid options, but may not be combined.
</p>
<dl compact="compact">
<dt><code>global</code></dt>
<dd><p>List variables in the global scope rather than the current scope.
</p>
</dd>
<dt><code>-regexp</code></dt>
<dd><p>The patterns are considered to be regular expressions when matching the
variables to display.  The same pattern syntax accepted by the <code>regexp</code>
function is used.
</p>
</dd>
<dt><code>-file</code></dt>
<dd><p>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.
</p></dd>
</dl>

<p>If called as a function, return a cell array of defined variable names
matching the given patterns.
</p>
<p><strong>See also:</strong> <a href="#XREFwhos">whos</a>, <a href="Global-Variables.html#XREFisglobal">isglobal</a>, <a href="Variables.html#XREFisvarname">isvarname</a>, <a href="#XREFexist">exist</a>, <a href="Manipulating-Strings.html#XREFregexp">regexp</a>.
</p></dd></dl>


<a name="XREFwhos"></a><dl>
<dt><a name="index-whos"></a>: <em></em> <strong>whos</strong></dt>
<dt><a name="index-whos-1"></a>: <em></em> <strong>whos</strong> <em>pattern &hellip;</em></dt>
<dt><a name="index-whos-2"></a>: <em></em> <strong>whos</strong> <em>option pattern &hellip;</em></dt>
<dt><a name="index-whos-3"></a>: <em>S =</em> <strong>whos</strong> <em>(&quot;pattern&quot;, &hellip;)</em></dt>
<dd><p>Provide detailed information on currently defined variables matching the
given patterns.
</p>
<p>Options and pattern syntax are the same as for the <code>who</code> command.
</p>
<p>Extended information about each variable is summarized in a table with the
following default entries.
</p>
<dl compact="compact">
<dt>Attr</dt>
<dd><p>Attributes of the listed variable.  Possible attributes are:
</p>
<dl compact="compact">
<dt>blank</dt>
<dd><p>Variable in local scope
</p>
</dd>
<dt><code>a</code></dt>
<dd><p>Automatic variable.  An automatic variable is one created by the
interpreter, for example <code>argn</code>.
</p>
</dd>
<dt><code>c</code></dt>
<dd><p>Variable of complex type.
</p>
</dd>
<dt><code>f</code></dt>
<dd><p>Formal parameter (function argument).
</p>
</dd>
<dt><code>g</code></dt>
<dd><p>Variable with global scope.
</p>
</dd>
<dt><code>p</code></dt>
<dd><p>Persistent variable.
</p></dd>
</dl>

</dd>
<dt>Name</dt>
<dd><p>The name of the variable.
</p>
</dd>
<dt>Size</dt>
<dd><p>The logical size of the variable.  A scalar is 1x1, a vector is
1xN or Nx1, a 2-D matrix is MxN.
</p>
</dd>
<dt>Bytes</dt>
<dd><p>The amount of memory currently used to store the variable.
</p>
</dd>
<dt>Class</dt>
<dd><p>The class of the variable.  Examples include double, single, char, uint16,
cell, and struct.
</p></dd>
</dl>

<p>The table can be customized to display more or less information through
the function <code>whos_line_format</code>.
</p>
<p>If <code>whos</code> 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.
</p>
<p><strong>See also:</strong> <a href="#XREFwho">who</a>, <a href="#XREFwhos_005fline_005fformat">whos_line_format</a>.
</p></dd></dl>


<a name="XREFwhos_005fline_005fformat"></a><dl>
<dt><a name="index-whos_005fline_005fformat"></a>: <em><var>val</var> =</em> <strong>whos_line_format</strong> <em>()</em></dt>
<dt><a name="index-whos_005fline_005fformat-1"></a>: <em><var>old_val</var> =</em> <strong>whos_line_format</strong> <em>(<var>new_val</var>)</em></dt>
<dt><a name="index-whos_005fline_005fformat-2"></a>: <em></em> <strong>whos_line_format</strong> <em>(<var>new_val</var>, &quot;local&quot;)</em></dt>
<dd><p>Query or set the format string used by the command <code>whos</code>.
</p>
<p>A full format string is:
</p>
<div class="smallexample">
<pre class="smallexample">%[modifier]&lt;command&gt;[:width[:left-min[:balance]]];
</pre></div>

<p>The following command sequences are available:
</p>
<dl compact="compact">
<dt><code>%a</code></dt>
<dd><p>Prints attributes of variables (g=global, p=persistent, f=formal parameter,
a=automatic variable).
</p>
</dd>
<dt><code>%b</code></dt>
<dd><p>Prints number of bytes occupied by variables.
</p>
</dd>
<dt><code>%c</code></dt>
<dd><p>Prints class names of variables.
</p>
</dd>
<dt><code>%e</code></dt>
<dd><p>Prints elements held by variables.
</p>
</dd>
<dt><code>%n</code></dt>
<dd><p>Prints variable names.
</p>
</dd>
<dt><code>%s</code></dt>
<dd><p>Prints dimensions of variables.
</p>
</dd>
<dt><code>%t</code></dt>
<dd><p>Prints type names of variables.
</p></dd>
</dl>

<p>Every command may also have an alignment modifier:
</p>
<dl compact="compact">
<dt><code>l</code></dt>
<dd><p>Left alignment.
</p>
</dd>
<dt><code>r</code></dt>
<dd><p>Right alignment (default).
</p>
</dd>
<dt><code>c</code></dt>
<dd><p>Column-aligned (only applicable to command %s).
</p></dd>
</dl>

<p>The <code>width</code> 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.
</p>
<p>The parameters <code>left-min</code> and <code>balance</code> are only available when
the column-aligned modifier is used with the command &lsquo;<samp>%s</samp>&rsquo;.
<code>balance</code> specifies the column number within the field width which
will be aligned between entries.  Numbering starts from 0 which indicates
the leftmost column.  <code>left-min</code> specifies the minimum field width to
the left of the specified balance column.
</p>
<p>The default format is:
</p>
<p><code>&quot;  %a:4; %ln:6; %cs:16:6:1;  %rb:12;  %lc:-1;\n&quot;</code>
</p>
<p>When called from inside a function with the <code>&quot;local&quot;</code> option, the
variable is changed locally for the function and any subroutines it calls.
The original variable value is restored when exiting the function.
</p>
<p><strong>See also:</strong> <a href="#XREFwhos">whos</a>.
</p></dd></dl>


<p>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.
</p>
<div class="example">
<pre class="example">if (! exist (&quot;meaning&quot;, &quot;var&quot;))
  disp (&quot;The program has no 'meaning'&quot;);
endif
</pre></div>

<a name="XREFexist"></a><dl>
<dt><a name="index-exist"></a>: <em><var>c</var> =</em> <strong>exist</strong> <em>(<var>name</var>)</em></dt>
<dt><a name="index-exist-1"></a>: <em><var>c</var> =</em> <strong>exist</strong> <em>(<var>name</var>, <var>type</var>)</em></dt>
<dd><p>Check for the existence of <var>name</var> as a variable, function, file,
directory, or class.
</p>
<p>The return code <var>c</var> is one of
</p>
<dl compact="compact">
<dt>1</dt>
<dd><p><var>name</var> is a variable.
</p>
</dd>
<dt>2</dt>
<dd><p><var>name</var> is an absolute filename, an ordinary file in Octave&rsquo;s
<code>path</code>, or (after appending &lsquo;<samp>.m</samp>&rsquo;) a function file in Octave&rsquo;s
<code>path</code>.
</p>
</dd>
<dt>3</dt>
<dd><p><var>name</var> is a &lsquo;<samp>.oct</samp>&rsquo; or &lsquo;<samp>.mex</samp>&rsquo; file in Octave&rsquo;s <code>path</code>.
</p>
</dd>
<dt>5</dt>
<dd><p><var>name</var> is a built-in function.
</p>
</dd>
<dt>7</dt>
<dd><p><var>name</var> is a directory.
</p>
</dd>
<dt>103</dt>
<dd><p><var>name</var> is a function not associated with a file (entered on the command
line).
</p>
</dd>
<dt>0</dt>
<dd><p><var>name</var> does not exist.
</p></dd>
</dl>

<p>If the optional argument <var>type</var> is supplied, check only for symbols of
the specified type.  Valid types are
</p>
<dl compact="compact">
<dt><code>&quot;var&quot;</code></dt>
<dd><p>Check only for variables.
</p>
</dd>
<dt><code>&quot;builtin&quot;</code></dt>
<dd><p>Check only for built-in functions.
</p>
</dd>
<dt><code>&quot;dir&quot;</code></dt>
<dd><p>Check only for directories.
</p>
</dd>
<dt><code>&quot;file&quot;</code></dt>
<dd><p>Check only for files and directories.
</p>
</dd>
<dt><code>&quot;class&quot;</code></dt>
<dd><p>Check only for classes.  (Note: This option is accepted, but not currently
implemented)
</p></dd>
</dl>

<p>If no type is given, and there are multiple possible matches for name,
<code>exist</code> will return a code according to the following priority list:
variable, built-in function, oct-file, directory, file, class.
</p>
<p><code>exist</code> returns 2 if a regular file called <var>name</var> is present in
Octave&rsquo;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
<code>file_in_path</code> and <code>stat</code> instead.
</p>
<p>Programming Note: If <var>name</var> is implemented by a buggy .oct/.mex file,
calling <var>exist</var> may cause Octave to crash.  To maintain high
performance, Octave trusts .oct/.mex files instead of sandboxing
them.
</p>

<p><strong>See also:</strong> <a href="Manipulating-the-Load-Path.html#XREFfile_005fin_005floadpath">file_in_loadpath</a>, <a href="Filesystem-Utilities.html#XREFfile_005fin_005fpath">file_in_path</a>, <a href="Manipulating-the-Load-Path.html#XREFdir_005fin_005floadpath">dir_in_loadpath</a>, <a href="Filesystem-Utilities.html#XREFstat">stat</a>.
</p></dd></dl>


<p>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.
</p>
<div class="example">
<pre class="example">large_matrix = zeros (4000, 4000);
</pre></div>

<p>Since having this variable in memory might slow down other computations,
it can be necessary to remove it manually from memory.  The <code>clear</code>
function allows this.
</p>
<a name="XREFclear"></a><dl>
<dt><a name="index-clear"></a>: <em></em> <strong>clear</strong> <em>[options] pattern &hellip;</em></dt>
<dd><p>Delete the names matching the given patterns from the symbol table.
</p>
<p>The pattern may contain the following special characters:
</p>
<dl compact="compact">
<dt><code>?</code></dt>
<dd><p>Match any single character.
</p>
</dd>
<dt><code>*</code></dt>
<dd><p>Match zero or more characters.
</p>
</dd>
<dt><code>[ <var>list</var> ]</code></dt>
<dd><p>Match the list of characters specified by <var>list</var>.  If the first
character is <code>!</code> or <code>^</code>, match all characters except those
specified by <var>list</var>.  For example, the pattern &lsquo;<samp>[a-zA-Z]</samp>&rsquo; will
match all lowercase and uppercase alphabetic characters.
</p></dd>
</dl>

<p>For example, the command
</p>
<div class="example">
<pre class="example">clear foo b*r
</pre></div>

<p>clears the name <code>foo</code> and all names that begin with the letter
<code>b</code> and end with the letter <code>r</code>.
</p>
<p>If <code>clear</code> is called without any arguments, all user-defined
variables (local and global) are cleared from the symbol table.
</p>
<p>If <code>clear</code> is called with at least one argument, only the visible
names matching the arguments are cleared.  For example, suppose you have
defined a function <code>foo</code>, and then hidden it by performing the
assignment <code>foo = 2</code>.  Executing the command <kbd>clear foo</kbd> once
will clear the variable definition and restore the definition of
<code>foo</code> as a function.  Executing <kbd>clear foo</kbd> a second time will
clear the function definition.
</p>
<p>The following options are available in both long and short form
</p>
<dl compact="compact">
<dt><code>-all, -a</code></dt>
<dd><p>Clear all local and global user-defined variables and all functions from the
symbol table.
</p>
</dd>
<dt><code>-exclusive, -x</code></dt>
<dd><p>Clear the variables that don&rsquo;t match the following pattern.
</p>
</dd>
<dt><code>-functions, -f</code></dt>
<dd><p>Clear the function names and the built-in symbols names.
</p>
</dd>
<dt><code>-global, -g</code></dt>
<dd><p>Clear global symbol names.
</p>
</dd>
<dt><code>-variables, -v</code></dt>
<dd><p>Clear local variable names.
</p>
</dd>
<dt><code>-classes, -c</code></dt>
<dd><p>Clears the class structure table and clears all objects.
</p>
</dd>
<dt><code>-regexp, -r</code></dt>
<dd><p>The arguments are treated as regular expressions as any variables that
match will be cleared.
</p></dd>
</dl>

<p>With the exception of <code>exclusive</code>, all long options can be used
without the dash as well.
</p>
<p><strong>See also:</strong> <a href="#XREFwho">who</a>, <a href="#XREFwhos">whos</a>, <a href="#XREFexist">exist</a>.
</p></dd></dl>


<a name="XREFpack"></a><dl>
<dt><a name="index-pack"></a>: <em></em> <strong>pack</strong> <em>()</em></dt>
<dd><p>Consolidate workspace memory in <small>MATLAB</small>.
</p>
<p>This function is provided for compatibility, but does nothing in Octave.
</p>
<p><strong>See also:</strong> <a href="#XREFclear">clear</a>.
</p></dd></dl>


<p>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.
</p>
<a name="XREFtype"></a><dl>
<dt><a name="index-type"></a>: <em></em> <strong>type</strong> <em><var>name</var> &hellip;</em></dt>
<dt><a name="index-type-1"></a>: <em></em> <strong>type</strong> <em>-q <var>name</var> &hellip;</em></dt>
<dt><a name="index-type-2"></a>: <em>text =</em> <strong>type</strong> <em>(&quot;<var>name</var>&quot;, &hellip;)</em></dt>
<dd><p>Display the contents of <var>name</var> which may be a file, function (m-file),
variable, operator, or keyword.
</p>
<p><code>type</code> normally prepends a header line describing the category of
<var>name</var> such as function or variable; The <samp>-q</samp> option suppresses
this behavior.
</p>
<p>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.
</p></dd></dl>


<a name="XREFwhich"></a><dl>
<dt><a name="index-which"></a>: <em></em> <strong>which</strong> <em>name &hellip;</em></dt>
<dd><p>Display the type of each <var>name</var>.
</p>
<p>If <var>name</var> is defined from a function file, the full name of the file is
also displayed.
</p>
<p><strong>See also:</strong> <a href="Getting-Help.html#XREFhelp">help</a>, <a href="Getting-Help.html#XREFlookfor">lookfor</a>.
</p></dd></dl>


<a name="XREFwhat"></a><dl>
<dt><a name="index-what"></a>: <em></em> <strong>what</strong></dt>
<dt><a name="index-what-1"></a>: <em></em> <strong>what</strong> <em><var>dir</var></em></dt>
<dt><a name="index-what-2"></a>: <em>w =</em> <strong>what</strong> <em>(<var>dir</var>)</em></dt>
<dd><p>List the Octave specific files in directory <var>dir</var>.
</p>
<p>If <var>dir</var> is not specified then the current directory is used.
</p>
<p>If a return argument is requested, the files found are returned in the
structure <var>w</var>.  The structure contains the following fields:
</p>
<dl compact="compact">
<dt>path</dt>
<dd><p>Full path to directory <var>dir</var>
</p>
</dd>
<dt>m</dt>
<dd><p>Cell array of m-files
</p>
</dd>
<dt>mat</dt>
<dd><p>Cell array of mat files
</p>
</dd>
<dt>mex</dt>
<dd><p>Cell array of mex files
</p>
</dd>
<dt>oct</dt>
<dd><p>Cell array of oct files
</p>
</dd>
<dt>mdl</dt>
<dd><p>Cell array of mdl files
</p>
</dd>
<dt>slx</dt>
<dd><p>Cell array of slx files
</p>
</dd>
<dt>p</dt>
<dd><p>Cell array of p-files
</p>
</dd>
<dt>classes</dt>
<dd><p>Cell array of class directories (<samp>@<var>classname</var>/</samp>)
</p>
</dd>
<dt>packages</dt>
<dd><p>Cell array of package directories (<samp>+<var>pkgname</var>/</samp>)
</p></dd>
</dl>

<p>Compatibility Note: Octave does not support mdl, slx, and p files; nor does
it support package directories.  <code>what</code> will always return an empty
list for these categories.
</p>
<p><strong>See also:</strong> <a href="#XREFwhich">which</a>, <a href="Current-Working-Directory.html#XREFls">ls</a>, <a href="#XREFexist">exist</a>.
</p></dd></dl>



<hr>
<div class="header">
<p>
Previous: <a href="Persistent-Variables.html#Persistent-Variables" accesskey="p" rel="prev">Persistent Variables</a>, Up: <a href="Variables.html#Variables" accesskey="u" rel="up">Variables</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
octave-doc 4.2.2-1ubuntu1 / usr / share / doc / octave / octave.html / Status-of-Variables.html
