File: Status-of-Variables.html

package info (click to toggle)
octave 3.8.2-2~bpo70%2B1
links: PTS, VCS
area: main
in suites: wheezy-backports
size: 84,360 kB
sloc: cpp: 293,356; ansic: 42,041; fortran: 23,669; sh: 13,629; objc: 7,890; yacc: 7,093; lex: 3,442; java: 2,125; makefile: 1,589; perl: 1,009; awk: 974; xml: 34
file content (474 lines) | stat: -rw-r--r-- 18,577 bytes
parent folder | download | duplicates (3)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Octave: Status of Variables</title>

<meta name="description" content="GNU Octave: Status of Variables">
<meta name="keywords" content="GNU Octave: Status of Variables">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<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.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
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.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<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
     -| *** local user variables:
     -| 
     -| __nargin__  str
</pre></div>

<a name="XREFwho"></a><dl>
<dt><a name="index-who"></a>Command: <em></em> <strong>who</strong></dt>
<dt><a name="index-who-1"></a>Command: <em></em> <strong>who</strong> <em>pattern &hellip;</em></dt>
<dt><a name="index-who-2"></a>Command: <em></em> <strong>who</strong> <em>option pattern &hellip;</em></dt>
<dt><a name="index-who-3"></a>Command: <em>C =</em> <strong>who</strong> <em>(&quot;pattern&quot;, &hellip;)</em></dt>
<dd><p>List currently defined variables matching the given patterns.  Valid
pattern syntax is the same as described for the <code>clear</code> command.
If no patterns are supplied, all variables are listed.
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>Command: <em></em> <strong>whos</strong></dt>
<dt><a name="index-whos-1"></a>Command: <em></em> <strong>whos</strong> <em>pattern &hellip;</em></dt>
<dt><a name="index-whos-2"></a>Command: <em></em> <strong>whos</strong> <em>option pattern &hellip;</em></dt>
<dt><a name="index-whos-3"></a>Command: <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.  Options and pattern syntax are the same as for the
<code>who</code> command.  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>Built-in Function: <em><var>val</var> =</em> <strong>whos_line_format</strong> <em>()</em></dt>
<dt><a name="index-whos_005fline_005fformat-1"></a>Built-in Function: <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>Built-in Function: <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
<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>Built-in Function: <em></em> <strong>exist</strong> <em>(<var>name</var>, <var>type</var>)</em></dt>
<dd><p>Return 1 if the name exists as a variable, 2 if the name is an
absolute file name, 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>, 3 if the
name is a &lsquo;<samp>.oct</samp>&rsquo; or &lsquo;<samp>.mex</samp>&rsquo; file in Octave&rsquo;s <code>path</code>,
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).
</p>
<p>Otherwise, return 0.
</p>
<p>This function also returns 2 if a regular file called <var>name</var>
exists in Octave&rsquo;s search path.  If you want information about
other types of files, you should use some combination of the functions
<code>file_in_path</code> and <code>stat</code> instead.
</p>
<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;file&quot;</code></dt>
<dd><p>Check only for files and directories.
</p>
</dd>
<dt><code>&quot;dir&quot;</code></dt>
<dd><p>Check only for directories.
</p></dd>
</dl>


<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#XREFfind_005fdir_005fin_005fpath">find_dir_in_path</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>Command: <em></em> <strong>clear</strong> <em>[options] pattern &hellip;</em></dt>
<dd><p>Delete the names matching the given patterns from the symbol table.  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.  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>Clears all local and global user-defined variables and all functions
from the symbol table.
</p>
</dd>
<dt><code>-exclusive, -x</code></dt>
<dd><p>Clears the variables that don&rsquo;t match the following pattern.
</p>
</dd>
<dt><code>-functions, -f</code></dt>
<dd><p>Clears the function names and the built-in symbols names.
</p>
</dd>
<dt><code>-global, -g</code></dt>
<dd><p>Clears the global symbol names.
</p>
</dd>
<dt><code>-variables, -v</code></dt>
<dd><p>Clears the 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></dd></dl>


<a name="XREFpack"></a><dl>
<dt><a name="index-pack"></a>Function File: <em></em> <strong>pack</strong> <em>()</em></dt>
<dd><p>Consolidate workspace memory in <small>MATLAB</small>.  This function is provided for
compatibility, but does nothing in Octave.
</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>Command: <em></em> <strong>type</strong> <em><var>name</var> &hellip;</em></dt>
<dt><a name="index-type-1"></a>Command: <em></em> <strong>type</strong> <em>-q <var>name</var> &hellip;</em></dt>
<dt><a name="index-type-2"></a>Function File: <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>Command: <em></em> <strong>which</strong> <em>name &hellip;</em></dt>
<dd><p>Display the type of each <var>name</var>.  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>Command: <em></em> <strong>what</strong></dt>
<dt><a name="index-what-1"></a>Command: <em></em> <strong>what</strong> <em><var>dir</var></em></dt>
<dt><a name="index-what-2"></a>Function File: <em>w =</em> <strong>what</strong> <em>(<var>dir</var>)</em></dt>
<dd><p>List the Octave specific files in directory <var>dir</var>.  If <var>dir</var> is
not specified then the current directory is used.  If a return argument is
requested, the files found are returned in the structure <var>w</var>.
</p>
<p><strong>See also:</strong> <a href="#XREFwhich">which</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>