7018
|
1 @c Copyright (C) 1996, 1997, 1999, 2000, 2002, 2003, 2004, 2005, |
|
2 @c 2006, 2007 John W. Eaton |
|
3 @c |
|
4 @c This file is part of Octave. |
|
5 @c |
|
6 @c Octave is free software; you can redistribute it and/or modify it |
|
7 @c under the terms of the GNU General Public License as published by the |
|
8 @c Free Software Foundation; either version 3 of the License, or (at |
|
9 @c your option) any later version. |
|
10 @c |
|
11 @c Octave is distributed in the hope that it will be useful, but WITHOUT |
|
12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 @c for more details. |
|
15 @c |
|
16 @c You should have received a copy of the GNU General Public License |
|
17 @c along with Octave; see the file COPYING. If not, see |
|
18 @c <http://www.gnu.org/licenses/>. |
3294
|
19 |
4167
|
20 @node Variables |
3294
|
21 @chapter Variables |
|
22 @cindex variables, user-defined |
|
23 @cindex user-defined variables |
|
24 |
|
25 Variables let you give names to values and refer to them later. You have |
|
26 already seen variables in many of the examples. The name of a variable |
|
27 must be a sequence of letters, digits and underscores, but it may not begin |
|
28 with a digit. Octave does not enforce a limit on the length of variable |
|
29 names, but it is seldom useful to have variables with names longer than |
|
30 about 30 characters. The following are all valid variable names |
|
31 |
|
32 @cindex job hunting |
|
33 @cindex getting a good job |
|
34 @cindex flying high and fast |
|
35 @example |
|
36 @group |
|
37 x |
|
38 x15 |
|
39 __foo_bar_baz__ |
|
40 fucnrdthsucngtagdjb |
|
41 @end group |
|
42 @end example |
|
43 |
|
44 @noindent |
|
45 However, names like @code{__foo_bar_baz__} that begin and end with two |
|
46 underscores are understood to be reserved for internal use by Octave. |
|
47 You should not use them in code you write, except to access Octave's |
|
48 documented internal variables and built-in symbolic constants. |
|
49 |
|
50 Case is significant in variable names. The symbols @code{a} and |
|
51 @code{A} are distinct variables. |
|
52 |
|
53 A variable name is a valid expression by itself. It represents the |
|
54 variable's current value. Variables are given new values with |
|
55 @dfn{assignment operators} and @dfn{increment operators}. |
|
56 @xref{Assignment Ops, ,Assignment Expressions}. |
|
57 |
|
58 A number of variables have special built-in meanings. For example, |
|
59 @code{ans} holds the current working directory, and @code{pi} names the |
|
60 ratio of the circumference of a circle to its diameter. @xref{Summary of |
|
61 Built-in Variables}, for a list of all the predefined variables. Some |
|
62 of these built-in symbols are constants and may not be changed. Others |
|
63 can be used and assigned just like all other variables, but their values |
|
64 are also used or changed automatically by Octave. |
|
65 |
|
66 Variables in Octave do not have fixed types, so it is possible to first |
|
67 store a numeric value in a variable and then to later use the same name |
|
68 to hold a string value in the same program. Variables may not be used |
|
69 before they have been given a value. Doing so results in an error. |
|
70 |
6550
|
71 @DOCSTRING(isvarname) |
|
72 |
3294
|
73 @menu |
|
74 * Global Variables:: |
4686
|
75 * Persistent Variables:: |
3294
|
76 * Status of Variables:: |
|
77 * Summary of Built-in Variables:: |
|
78 * Defaults from the Environment:: |
|
79 @end menu |
|
80 |
4167
|
81 @node Global Variables |
3294
|
82 @section Global Variables |
|
83 @cindex global variables |
|
84 @cindex @code{global} statement |
|
85 @cindex variables, global |
|
86 |
|
87 A variable that has been declared @dfn{global} may be accessed from |
|
88 within a function body without having to pass it as a formal parameter. |
|
89 |
|
90 A variable may be declared global using a @code{global} declaration |
|
91 statement. The following statements are all global declarations. |
|
92 |
|
93 @example |
|
94 @group |
|
95 global a |
4504
|
96 global a b |
|
97 global c = 2 |
|
98 global d = 3 e f = 5 |
3294
|
99 @end group |
|
100 @end example |
|
101 |
4504
|
102 A global variable may only be initialized once in a @code{global} |
|
103 statement. For example, after executing the following code |
|
104 |
|
105 @example |
|
106 @group |
|
107 global gvar = 1 |
|
108 global gvar = 2 |
|
109 @end group |
|
110 @end example |
|
111 |
|
112 @noindent |
6077
|
113 the value of the global variable @code{gvar} is 1, not 2. Issuing a |
6623
|
114 @samp{clear gvar} command does not change the above behavior, but |
6077
|
115 @samp{clear all} does. |
4504
|
116 |
3294
|
117 It is necessary declare a variable as global within a function body in |
|
118 order to access it. For example, |
|
119 |
|
120 @example |
|
121 @group |
|
122 global x |
|
123 function f () |
|
124 x = 1; |
|
125 endfunction |
|
126 f () |
|
127 @end group |
|
128 @end example |
|
129 |
|
130 @noindent |
|
131 does @emph{not} set the value of the global variable @code{x} to 1. In |
|
132 order to change the value of the global variable @code{x}, you must also |
|
133 declare it to be global within the function body, like this |
|
134 |
|
135 @example |
|
136 @group |
|
137 function f () |
|
138 global x; |
|
139 x = 1; |
|
140 endfunction |
|
141 @end group |
|
142 @end example |
|
143 |
|
144 Passing a global variable in a function parameter list will |
|
145 make a local copy and not modify the global value. For example, given |
|
146 the function |
|
147 |
|
148 @example |
|
149 @group |
|
150 function f (x) |
|
151 x = 0 |
|
152 endfunction |
|
153 @end group |
|
154 @end example |
|
155 |
|
156 @noindent |
|
157 and the definition of @code{x} as a global variable at the top level, |
|
158 |
|
159 @example |
|
160 global x = 13 |
|
161 @end example |
|
162 |
|
163 @noindent |
|
164 the expression |
|
165 |
|
166 @example |
|
167 f (x) |
|
168 @end example |
|
169 |
|
170 @noindent |
|
171 will display the value of @code{x} from inside the function as 0, |
|
172 but the value of @code{x} at the top level remains unchanged, because |
|
173 the function works with a @emph{copy} of its argument. |
|
174 |
4029
|
175 @DOCSTRING(isglobal) |
3294
|
176 |
4686
|
177 @node Persistent Variables |
|
178 @section Persistent Variables |
|
179 @cindex persistent variables |
|
180 @cindex @code{persistent} statement |
|
181 @cindex variables, persistent |
|
182 |
|
183 A variable that has been declared @dfn{persistent} within a function |
|
184 will retain its contents in memory between subsequent calls to the |
|
185 same function. The difference between persistent variables and global |
|
186 variables is that persistent variables are local in scope to a |
|
187 particular function and are not visible elsewhere. |
|
188 |
6899
|
189 The following example uses a persistent variable to create a function |
|
190 that prints the number of times it has been called. |
|
191 |
|
192 @example |
|
193 @group |
|
194 function count_calls () |
|
195 persistent calls = 0; |
7031
|
196 printf ("'count_calls' has been called %d times\n", |
|
197 ++calls); |
6899
|
198 endfunction |
|
199 |
|
200 for i = 1:3 |
|
201 count_calls (); |
|
202 endfor |
|
203 |
|
204 @print{} 'count_calls' has been called 1 times |
|
205 @print{} 'count_calls' has been called 2 times |
|
206 @print{} 'count_calls' has been called 3 times |
|
207 @end group |
|
208 @end example |
|
209 |
|
210 As the example shows, a variable may be declared persistent using a |
|
211 @code{persistent} declaration statement. The following statements are |
|
212 all persistent declarations. |
4686
|
213 |
|
214 @example |
|
215 @group |
|
216 persistent a |
|
217 persistent a b |
|
218 persistent c = 2 |
|
219 persistent d = 3 e f = 5 |
|
220 @end group |
|
221 @end example |
|
222 |
|
223 The behavior of persistent variables is equivalent to the behavior of |
|
224 static variables in C. The command @code{static} in octave is also |
6899
|
225 recognized and is equivalent to @code{persistent}. |
|
226 |
|
227 Like global variables, a persistent variable may only be initialized once. |
6896
|
228 For example, after executing the following code |
4686
|
229 |
|
230 @example |
|
231 @group |
|
232 persistent pvar = 1 |
|
233 persistent pvar = 2 |
|
234 @end group |
|
235 @end example |
|
236 |
|
237 @noindent |
6896
|
238 the value of the persistent variable @code{pvar} is 1, not 2. |
4686
|
239 |
6899
|
240 If a persistent variable is declared but not initialized to a specific |
|
241 value, it will contain an empty matrix. So, it is also possible to |
|
242 initialize a persistent variable by checking whether it is empty, as the |
|
243 following example illustrates. |
|
244 |
|
245 @example |
|
246 @group |
|
247 function count_calls () |
|
248 persistent calls; |
|
249 if (isempty (calls)) |
|
250 calls = 0; |
|
251 endif |
7031
|
252 printf ("'count_calls' has been called %d times\n", |
|
253 ++calls); |
6899
|
254 endfunction |
|
255 @end group |
|
256 @end example |
|
257 |
|
258 @noindent |
|
259 This implementation behaves in exactly the same way as the previous |
|
260 implementation of @code{count_calls}. |
|
261 |
|
262 The value of a persistent variable is kept in memory until it is |
|
263 explicitly cleared. Assuming that the implementation of @code{count_calls} |
|
264 is saved on disc, we get the following behaviour. |
|
265 |
|
266 @example |
|
267 @group |
|
268 for i = 1:2 |
|
269 count_calls (); |
|
270 endfor |
|
271 @print{} 'count_calls' has been called 1 times |
|
272 @print{} 'count_calls' has been called 2 times |
|
273 |
|
274 clear |
|
275 for i = 1:2 |
|
276 count_calls(); |
|
277 endfor |
|
278 @print{} 'count_calls' has been called 3 times |
|
279 @print{} 'count_calls' has been called 4 times |
|
280 |
|
281 clear all |
|
282 for i = 1:2 |
|
283 count_calls(); |
|
284 endfor |
|
285 @print{} 'count_calls' has been called 1 times |
|
286 @print{} 'count_calls' has been called 2 times |
|
287 |
|
288 clear count_calls |
|
289 for i = 1:2 |
|
290 count_calls(); |
|
291 endfor |
|
292 @print{} 'count_calls' has been called 1 times |
|
293 @print{} 'count_calls' has been called 2 times |
|
294 @end group |
|
295 @end example |
|
296 |
|
297 @noindent |
|
298 That is, the persistent variable is only removed from memory when the |
|
299 function containing the variable is removed. Note that if the function |
|
300 definition is typed directly into the Octave prompt, the persistent |
|
301 variable will be cleared by a simple @code{clear} command as the entire |
|
302 function definition will be removed from memory. If you do not want |
|
303 a persistent variable to be removed from memory even if the function is |
|
304 cleared, you should use the @code{mlock} function as described in |
|
305 @xref{Function Locking}. |
|
306 |
4167
|
307 @node Status of Variables |
3294
|
308 @section Status of Variables |
|
309 |
6623
|
310 When creating simple one-shot programs it can be very convenient to |
|
311 see which variables are available at the prompt. The function @code{who} |
|
312 and its siblings @code{whos} and @code{whos_line_format} will show |
|
313 different information about what is in memory, as the following shows. |
|
314 |
|
315 @example |
|
316 str = "A random string"; |
|
317 who -variables |
|
318 @print{} *** local user variables: |
|
319 @print{} |
|
320 @print{} __nargin__ str |
|
321 @end example |
3294
|
322 |
3361
|
323 @DOCSTRING(who) |
3294
|
324 |
4913
|
325 @DOCSTRING(whos) |
|
326 |
|
327 @DOCSTRING(whos_line_format) |
|
328 |
6623
|
329 Instead of displaying which variables are in memory, it is possible |
|
330 to determine if a given variable is available. That way it is possible |
|
331 to alter the behaviour of a program depending on the existence of a |
|
332 variable. The following example illustrates this. |
|
333 |
|
334 @example |
|
335 if (! exist ("meaning", "var")) |
|
336 disp ("The program has no 'meaning'"); |
|
337 endif |
|
338 @end example |
|
339 |
3361
|
340 @DOCSTRING(exist) |
3294
|
341 |
6623
|
342 Usually Octave will manage the memory, but sometimes it can be practical |
|
343 to remove variables from memory manually. This is usually needed when |
|
344 working with large variables that fill a substantial part of the memory. |
|
345 On a computer that uses the IEEE floating point format, the following |
|
346 program allocates a matrix that requires around 128 MB memory. |
|
347 |
|
348 @example |
|
349 large_matrix = zeros (4000, 4000); |
|
350 @end example |
|
351 |
|
352 @noindent |
|
353 Since having this variable in memory might slow down other computations, |
|
354 it can be necessary to remove it manually from memory. The @code{clear} |
|
355 function allows this. |
|
356 |
|
357 @DOCSTRING(clear) |
|
358 |
|
359 Information about a function or variable such as it's location in the |
|
360 file system can also be acquired from within Octave. This is usually |
|
361 only useful during development of programs, and not within a program. |
|
362 |
3361
|
363 @DOCSTRING(document) |
3294
|
364 |
3361
|
365 @DOCSTRING(type) |
3294
|
366 |
3361
|
367 @DOCSTRING(which) |
3294
|
368 |
4167
|
369 @node Summary of Built-in Variables |
3294
|
370 @section Summary of Built-in Variables |
|
371 |
|
372 Here is a summary of all of Octave's built-in variables along with |
|
373 cross references to additional information and their default values. In |
|
374 the following table @var{octave-home} stands for the root directory |
|
375 where all of Octave is installed (the default is @file{@value{OCTAVEHOME}}, |
|
376 @var{version} stands for the Octave version number (for example, |
|
377 @value{VERSION}) and @var{arch} stands for the type of system for which |
5942
|
378 Octave was compiled (for example, @code{x86_64-unknown-linux-gnu}). |
3294
|
379 |
|
380 @vtable @code |
|
381 @item EDITOR |
|
382 @xref{Commands For History}. |
|
383 |
|
384 Default value: @code{"emacs"}. |
|
385 |
|
386 @item EXEC_PATH |
|
387 @xref{Controlling Subprocesses}. |
|
388 |
|
389 Default value: @code{":$PATH"}. |
|
390 |
|
391 @item OCTAVE_HOME |
|
392 |
|
393 Default value: @code{"@value{OCTAVEHOME}"}. |
|
394 |
|
395 @item PAGER |
|
396 @xref{Input and Output}. |
|
397 |
|
398 Default value: @code{"less", or "more"}. |
|
399 |
|
400 @item PS1 |
|
401 @xref{Customizing the Prompt}. |
|
402 |
|
403 Default value: @code{"\s:\#> "}. |
|
404 |
|
405 @item PS2 |
|
406 @xref{Customizing the Prompt}. |
|
407 |
|
408 Default value: @code{"> "}. |
|
409 |
|
410 @item PS4 |
|
411 @xref{Customizing the Prompt}. |
|
412 |
|
413 Default value: @code{"+ "}. |
|
414 |
|
415 @item beep_on_error |
6667
|
416 @xref{Errors and Warnings}. |
3294
|
417 |
|
418 Default value: 0. |
|
419 |
|
420 @item completion_append_char |
|
421 @xref{Commands For Completion}. |
|
422 |
|
423 Default value: @code{" "}. |
|
424 |
5287
|
425 @item default_save_options |
3294
|
426 @xref{Simple File I/O}. |
|
427 |
|
428 Default value: @code{"ascii"}. |
|
429 |
|
430 @item crash_dumps_octave_core |
|
431 @xref{Simple File I/O}. |
|
432 |
|
433 Default value: 1. |
|
434 |
|
435 @item fixed_point_format |
|
436 @xref{Matrices}. |
|
437 |
|
438 Default value: 0. |
|
439 |
|
440 @item gnuplot_binary |
|
441 @xref{Three-Dimensional Plotting}. |
|
442 |
|
443 Default value: @code{"gnuplot"}. |
|
444 |
|
445 @item history_file |
|
446 @xref{Commands For History}. |
|
447 |
|
448 Default value: @code{"~/.octave_hist"}. |
|
449 |
|
450 @item history_size |
|
451 @xref{Commands For History}. |
|
452 |
|
453 Default value: 1024. |
|
454 |
|
455 @item ignore_function_time_stamp |
|
456 @xref{Function Files}. |
|
457 |
|
458 Default value: @code{"system"}. |
|
459 |
|
460 @item max_recursion_depth |
|
461 @xref{Recursion}. |
|
462 |
|
463 Default value: 256. |
|
464 |
|
465 @item output_max_field_width |
|
466 @xref{Matrices}. |
|
467 |
|
468 Default value: 10. |
|
469 |
|
470 @item output_precision |
|
471 @xref{Matrices}. |
|
472 |
|
473 Default value: 5. |
|
474 |
|
475 @item page_screen_output |
|
476 @xref{Input and Output}. |
|
477 |
|
478 Default value: 1. |
|
479 |
|
480 @item print_answer_id_name |
|
481 @xref{Terminal Output}. |
|
482 |
|
483 Default value: 1. |
|
484 |
|
485 @item print_empty_dimensions |
|
486 @xref{Empty Matrices}. |
|
487 |
|
488 Default value: 1. |
|
489 |
|
490 @item return_last_computed_value |
|
491 @xref{Returning From a Function}. |
|
492 |
|
493 Default value: 0. |
|
494 |
|
495 @item save_precision |
|
496 @xref{Simple File I/O}. |
|
497 |
|
498 Default value: 17. |
|
499 |
|
500 @item saving_history |
|
501 @xref{Commands For History}. |
|
502 |
|
503 Default value: 1. |
|
504 |
4449
|
505 @item sighup_dumps_octave_core |
|
506 @xref{Simple File I/O}. |
|
507 |
|
508 Default value: 1. |
|
509 |
|
510 @item sigterm_dumps_octave_core |
|
511 @xref{Simple File I/O}. |
|
512 |
|
513 Default value: 1. |
|
514 |
3294
|
515 @item silent_functions |
|
516 @xref{Defining Functions}. |
|
517 |
|
518 Default value: 0. |
|
519 |
|
520 @item split_long_rows |
|
521 @xref{Matrices}. |
|
522 |
|
523 Default value: 1. |
|
524 |
|
525 @item struct_levels_to_print |
|
526 @xref{Data Structures}. |
|
527 |
|
528 Default value: 2. |
|
529 |
|
530 @item suppress_verbose_help_message |
|
531 @xref{Getting Help}. |
|
532 |
|
533 Default value: 1. |
|
534 @end vtable |
|
535 |
|
536 |
4167
|
537 @node Defaults from the Environment |
3294
|
538 @section Defaults from the Environment |
|
539 |
|
540 Octave uses the values of the following environment variables to set the |
6477
|
541 default values for the corresponding built-in or internal variables. |
|
542 In addition, the values from the environment may be overridden by |
|
543 command-line arguments. @xref{Command Line Options}. |
3294
|
544 |
|
545 @vtable @code |
|
546 @item EDITOR |
|
547 @xref{Commands For History}. |
|
548 |
|
549 Built-in variable: @code{EDITOR}. |
|
550 |
|
551 @item OCTAVE_EXEC_PATH |
|
552 @xref{Controlling Subprocesses}. |
|
553 |
|
554 Built-in variable: @code{EXEC_PATH}. |
|
555 Command-line argument: @code{--exec-path}. |
|
556 |
|
557 @item OCTAVE_PATH |
|
558 @xref{Function Files}. |
|
559 |
6477
|
560 Internal variable changed by function @code{path}. |
3294
|
561 Command-line argument: @code{--path}. |
|
562 |
|
563 @item OCTAVE_INFO_FILE |
|
564 @xref{Getting Help}. |
|
565 |
6477
|
566 Internal variable changed by function @code{info_file}. |
3294
|
567 Command-line argument: @code{--info-file}. |
|
568 |
|
569 @item OCTAVE_INFO_PROGRAM |
|
570 @xref{Getting Help}. |
|
571 |
6477
|
572 Internal variable changed by function @code{info_program}. |
3294
|
573 Command-line argument: @code{--info-program}. |
|
574 |
|
575 @item OCTAVE_HISTSIZE |
|
576 @xref{Commands For History}. |
|
577 |
|
578 Built-in variable: @code{history_size}. |
|
579 |
|
580 @item OCTAVE_HISTFILE |
|
581 @xref{Commands For History}. |
|
582 |
|
583 Built-in variable: @code{history_file}. |
|
584 @end vtable |