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