1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
|
<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.11">
<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">
<p>
<a name="Status-of-Variables"></a>
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>
|
