<html lang="en">
<head>
<title>Status of Variables - Untitled</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Untitled">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Variables.html#Variables" title="Variables">
<link rel="prev" href="Persistent-Variables.html#Persistent-Variables" title="Persistent Variables">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Status-of-Variables"></a>
<p>
Previous: <a rel="previous" accesskey="p" href="Persistent-Variables.html#Persistent-Variables">Persistent Variables</a>,
Up: <a rel="up" accesskey="u" href="Variables.html#Variables">Variables</a>
<hr>
</div>
<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.
<pre class="example"> str = "A random string";
who -variables
-| *** local user variables:
-|
-| __nargin__ str
</pre>
<!-- variables.cc -->
<p><a name="doc_002dwho"></a>
<div class="defun">
— Command: <b>who</b><var><a name="index-who-430"></a></var><br>
— Command: <b>who</b><var> pattern <small class="dots">...</small><a name="index-who-431"></a></var><br>
— Command: <b>who</b><var> option pattern <small class="dots">...</small><a name="index-who-432"></a></var><br>
— Command: <b>C</b><var> = who</var>(<var>"pattern", <small class="dots">...</small></var>)<var><a name="index-C-433"></a></var><br>
<blockquote><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>The following are valid options but may not be combined.
<dl>
<dt><code>global</code><dd>List variables in the global scope rather than the current scope.
<br><dt><code>-regexp</code><dd>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.
<br><dt><code>-file</code><dd>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.
</dl>
<p>If called as a function, return a cell array of defined variable names
matching the given patterns.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dwhos.html#doc_002dwhos">whos</a>, <a href="doc_002dregexp.html#doc_002dregexp">regexp</a>.
</p></blockquote></div>
<!-- variables.cc -->
<p><a name="doc_002dwhos"></a>
<div class="defun">
— Command: <b>whos</b><var><a name="index-whos-434"></a></var><br>
— Command: <b>whos</b><var> pattern <small class="dots">...</small><a name="index-whos-435"></a></var><br>
— Command: <b>whos</b><var> option pattern <small class="dots">...</small><a name="index-whos-436"></a></var><br>
— Command: <b>S</b><var> = whos</var>(<var>"pattern", <small class="dots">...</small></var>)<var><a name="index-S-437"></a></var><br>
<blockquote><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.
<dl>
<dt>Attr<dd>Attributes of the listed variable. Possible attributes are:
<dl>
<dt>blank<dd>Variable in local scope
<br><dt><code>g</code><dd>Variable with global scope
<br><dt><code>p</code><dd>Persistent variable
</dl>
<br><dt>Name<dd>The name of the variable.
<br><dt>Size<dd>The logical size of the variable. A scalar is 1x1, a vector is 1xN or Nx1,
a 2-D matrix is MxN.
<br><dt>Bytes<dd>The amount of memory currently used to store the variable.
<br><dt>Class<dd>The class of the variable. Examples include double, single, char, uint16,
cell, and struct.
</dl>
<p>The table can be customized to display more or less information through
the function <code>whos_line_format</code>.
<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.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dwho.html#doc_002dwho">who</a>, <a href="doc_002dwhos_005fline_005fformat.html#doc_002dwhos_005fline_005fformat">whos_line_format</a>.
</p></blockquote></div>
<!-- variables.cc -->
<p><a name="doc_002dwhos_005fline_005fformat"></a>
<div class="defun">
— Built-in Function: <var>val</var> = <b>whos_line_format</b> ()<var><a name="index-whos_005fline_005fformat-438"></a></var><br>
— Built-in Function: <var>old_val</var> = <b>whos_line_format</b> (<var>new_val</var>)<var><a name="index-whos_005fline_005fformat-439"></a></var><br>
<blockquote><p>Query or set the format string used by the command <code>whos</code>.
<p>A full format string is:
<!-- Set example in small font to prevent overfull line -->
<pre class="smallexample"> %[modifier]<command>[:width[:left-min[:balance]]];
</pre>
<p>The following command sequences are available:
<dl>
<dt><code>%a</code><dd>Prints attributes of variables (g=global, p=persistent,
f=formal parameter, a=automatic variable).
<br><dt><code>%b</code><dd>Prints number of bytes occupied by variables.
<br><dt><code>%c</code><dd>Prints class names of variables.
<br><dt><code>%e</code><dd>Prints elements held by variables.
<br><dt><code>%n</code><dd>Prints variable names.
<br><dt><code>%s</code><dd>Prints dimensions of variables.
<br><dt><code>%t</code><dd>Prints type names of variables.
</dl>
<p>Every command may also have an alignment modifier:
<dl>
<dt><code>l</code><dd>Left alignment.
<br><dt><code>r</code><dd>Right alignment (default).
<br><dt><code>c</code><dd>Column-aligned (only applicable to command %s).
</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>The parameters <code>left-min</code> and <code>balance</code> are only available when the
column-aligned modifier is used with the command ‘<samp><span class="samp">%s</span></samp>’.
<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>The default format is
<code>" %a:4; %ln:6; %cs:16:6:1; %rb:12; %lc:-1;\n"</code>.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dwhos.html#doc_002dwhos">whos</a>.
</p></blockquote></div>
<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.
<pre class="example"> if (! exist ("meaning", "var"))
disp ("The program has no 'meaning'");
endif
</pre>
<!-- variables.cc -->
<p><a name="doc_002dexist"></a>
<div class="defun">
— Built-in Function: <b>exist</b> (<var>name, type</var>)<var><a name="index-exist-440"></a></var><br>
<blockquote><p>Return 1 if the name exists as a variable, 2 if the name is an
absolute file name, an ordinary file in Octave's <code>path</code>, or (after
appending ‘<samp><span class="samp">.m</span></samp>’) a function file in Octave's <code>path</code>, 3 if the
name is a ‘<samp><span class="samp">.oct</span></samp>’ or ‘<samp><span class="samp">.mex</span></samp>’ file in Octave'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>Otherwise, return 0.
<p>This function also returns 2 if a regular file called <var>name</var>
exists in Octave'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>If the optional argument <var>type</var> is supplied, check only for
symbols of the specified type. Valid types are
<dl>
<dt>‘<samp><span class="samp">"var"</span></samp>’<dd>Check only for variables.
<br><dt>‘<samp><span class="samp">"builtin"</span></samp>’<dd>Check only for built-in functions.
<br><dt>‘<samp><span class="samp">"file"</span></samp>’<dd>Check only for files.
<br><dt>‘<samp><span class="samp">"dir"</span></samp>’<dd>Check only for directories.
</dl>
</p></blockquote></div>
<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.
<pre class="example"> large_matrix = zeros (4000, 4000);
</pre>
<p class="noindent">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.
<!-- variables.cc -->
<p><a name="doc_002dclear"></a>
<div class="defun">
— Command: <b>clear</b> [<var>options</var>]<var> pattern <small class="dots">...</small><a name="index-clear-441"></a></var><br>
<blockquote><p>Delete the names matching the given patterns from the symbol table. The
pattern may contain the following special characters:
<dl>
<dt><code>?</code><dd>Match any single character.
<br><dt><code>*</code><dd>Match zero or more characters.
<br><dt><code>[ </code><var>list</var><code> ]</code><dd>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 ‘<samp><span class="samp">[a-zA-Z]</span></samp>’ will
match all lower and upper case alphabetic characters.
</dl>
<p>For example, the command
<pre class="example"> clear foo b*r
</pre>
<p class="noindent">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>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>The following options are available in both long and short form
<dl>
<dt><code>-all, -a</code><dd>Clears all local and global user-defined variables and all functions
from the symbol table.
<br><dt><code>-exclusive, -x</code><dd>Clears the variables that don't match the following pattern.
<br><dt><code>-functions, -f</code><dd>Clears the function names and the built-in symbols names.
<br><dt><code>-global, -g</code><dd>Clears the global symbol names.
<br><dt><code>-variables, -v</code><dd>Clears the local variable names.
<br><dt><code>-classes, -c</code><dd>Clears the class structure table and clears all objects.
<br><dt><code>-regexp, -r</code><dd>The arguments are treated as regular expressions as any variables that
match will be cleared.
</dl>
With the exception of <code>exclusive</code>, all long options can be used
without the dash as well.
</p></blockquote></div>
<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.
<!-- ./help/type.m -->
<p><a name="doc_002dtype"></a>
<div class="defun">
— Command: type <b>options</b><var> name <small class="dots">...</small><a name="index-options-442"></a></var><br>
<blockquote><p>Display the definition of each <var>name</var> that refers to a function.
<p>Normally also displays whether each <var>name</var> is user-defined or built-in;
the <code>-q</code> option suppresses this behavior.
<p>If an output argument is requested nothing is displayed. Instead, a cell
array of strings is returned, where each element corresponds to the
definition of each requested function.
</p></blockquote></div>
<!-- ./help/which.m -->
<p><a name="doc_002dwhich"></a>
<div class="defun">
— Command: <b>which</b><var> name <small class="dots">...</small><a name="index-which-443"></a></var><br>
<blockquote><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.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dhelp.html#doc_002dhelp">help</a>, <a href="doc_002dlookfor.html#doc_002dlookfor">lookfor</a>.
</p></blockquote></div>
<!-- ./miscellaneous/what.m -->
<p><a name="doc_002dwhat"></a>
<div class="defun">
— Command: <b>what</b><var><a name="index-what-444"></a></var><br>
— Command: <b>what</b><var> dir<a name="index-what-445"></a></var><br>
— Function File: w = <b>what</b> (<var>dir</var>)<var><a name="index-what-446"></a></var><br>
<blockquote><p>List the Octave specific files in a directory. If the variable <var>dir</var>
is given then check that directory rather than the current directory. If
a return argument is requested, the files found are returned in the
structure <var>w</var>.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dwhich.html#doc_002dwhich">which</a>.
</p></blockquote></div>
<!-- DO NOT EDIT! Generated automatically by munge-texi. -->
<!-- Copyright (C) 1996, 1997, 1999, 2000, 2002, 2003, 2004, 2006, -->
<!-- 2007, 2008, 2009 John W. Eaton -->
<!-- This file is part of Octave. -->
<!-- Octave is free software; you can redistribute it and/or modify it -->
<!-- under the terms of the GNU General Public License as published by the -->
<!-- Free Software Foundation; either version 3 of the License, or (at -->
<!-- your option) any later version. -->
<!-- Octave is distributed in the hope that it will be useful, but WITHOUT -->
<!-- ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -->
<!-- FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -->
<!-- for more details. -->
<!-- You should have received a copy of the GNU General Public License -->
<!-- along with Octave; see the file COPYING. If not, see -->
<!-- <http://www.gnu.org/licenses/>. -->
</body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
3e60ff9d4d6f58c8fbd17208f14089fa
>
files
>
387
