|
3294
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
4167
|
5 @node Variables |
|
3294
|
6 @chapter Variables |
|
|
7 @cindex variables, user-defined |
|
|
8 @cindex user-defined variables |
|
|
9 |
|
|
10 Variables let you give names to values and refer to them later. You have |
|
|
11 already seen variables in many of the examples. The name of a variable |
|
|
12 must be a sequence of letters, digits and underscores, but it may not begin |
|
|
13 with a digit. Octave does not enforce a limit on the length of variable |
|
|
14 names, but it is seldom useful to have variables with names longer than |
|
|
15 about 30 characters. The following are all valid variable names |
|
|
16 |
|
|
17 @cindex job hunting |
|
|
18 @cindex getting a good job |
|
|
19 @cindex flying high and fast |
|
|
20 @example |
|
|
21 @group |
|
|
22 x |
|
|
23 x15 |
|
|
24 __foo_bar_baz__ |
|
|
25 fucnrdthsucngtagdjb |
|
|
26 @end group |
|
|
27 @end example |
|
|
28 |
|
|
29 @noindent |
|
|
30 However, names like @code{__foo_bar_baz__} that begin and end with two |
|
|
31 underscores are understood to be reserved for internal use by Octave. |
|
|
32 You should not use them in code you write, except to access Octave's |
|
|
33 documented internal variables and built-in symbolic constants. |
|
|
34 |
|
|
35 Case is significant in variable names. The symbols @code{a} and |
|
|
36 @code{A} are distinct variables. |
|
|
37 |
|
|
38 A variable name is a valid expression by itself. It represents the |
|
|
39 variable's current value. Variables are given new values with |
|
|
40 @dfn{assignment operators} and @dfn{increment operators}. |
|
|
41 @xref{Assignment Ops, ,Assignment Expressions}. |
|
|
42 |
|
|
43 A number of variables have special built-in meanings. For example, |
|
|
44 @code{ans} holds the current working directory, and @code{pi} names the |
|
|
45 ratio of the circumference of a circle to its diameter. @xref{Summary of |
|
|
46 Built-in Variables}, for a list of all the predefined variables. Some |
|
|
47 of these built-in symbols are constants and may not be changed. Others |
|
|
48 can be used and assigned just like all other variables, but their values |
|
|
49 are also used or changed automatically by Octave. |
|
|
50 |
|
|
51 Variables in Octave do not have fixed types, so it is possible to first |
|
|
52 store a numeric value in a variable and then to later use the same name |
|
|
53 to hold a string value in the same program. Variables may not be used |
|
|
54 before they have been given a value. Doing so results in an error. |
|
|
55 |
|
|
56 @menu |
|
|
57 * Global Variables:: |
|
4686
|
58 * Persistent Variables:: |
|
3294
|
59 * Status of Variables:: |
|
|
60 * Summary of Built-in Variables:: |
|
|
61 * Defaults from the Environment:: |
|
|
62 @end menu |
|
|
63 |
|
4167
|
64 @node Global Variables |
|
3294
|
65 @section Global Variables |
|
|
66 @cindex global variables |
|
|
67 @cindex @code{global} statement |
|
|
68 @cindex variables, global |
|
|
69 |
|
|
70 A variable that has been declared @dfn{global} may be accessed from |
|
|
71 within a function body without having to pass it as a formal parameter. |
|
|
72 |
|
|
73 A variable may be declared global using a @code{global} declaration |
|
|
74 statement. The following statements are all global declarations. |
|
|
75 |
|
|
76 @example |
|
|
77 @group |
|
|
78 global a |
|
4504
|
79 global a b |
|
|
80 global c = 2 |
|
|
81 global d = 3 e f = 5 |
|
3294
|
82 @end group |
|
|
83 @end example |
|
|
84 |
|
4504
|
85 A global variable may only be initialized once in a @code{global} |
|
|
86 statement. For example, after executing the following code |
|
|
87 |
|
|
88 @example |
|
|
89 @group |
|
|
90 global gvar = 1 |
|
|
91 global gvar = 2 |
|
|
92 @end group |
|
|
93 @end example |
|
|
94 |
|
|
95 @noindent |
|
6077
|
96 the value of the global variable @code{gvar} is 1, not 2. Issuing a |
|
|
97 @samp{clear a} command does not change the above behavior, but |
|
|
98 @samp{clear all} does. |
|
4504
|
99 |
|
3294
|
100 It is necessary declare a variable as global within a function body in |
|
|
101 order to access it. For example, |
|
|
102 |
|
|
103 @example |
|
|
104 @group |
|
|
105 global x |
|
|
106 function f () |
|
|
107 x = 1; |
|
|
108 endfunction |
|
|
109 f () |
|
|
110 @end group |
|
|
111 @end example |
|
|
112 |
|
|
113 @noindent |
|
|
114 does @emph{not} set the value of the global variable @code{x} to 1. In |
|
|
115 order to change the value of the global variable @code{x}, you must also |
|
|
116 declare it to be global within the function body, like this |
|
|
117 |
|
|
118 @example |
|
|
119 @group |
|
|
120 function f () |
|
|
121 global x; |
|
|
122 x = 1; |
|
|
123 endfunction |
|
|
124 @end group |
|
|
125 @end example |
|
|
126 |
|
|
127 Passing a global variable in a function parameter list will |
|
|
128 make a local copy and not modify the global value. For example, given |
|
|
129 the function |
|
|
130 |
|
|
131 @example |
|
|
132 @group |
|
|
133 function f (x) |
|
|
134 x = 0 |
|
|
135 endfunction |
|
|
136 @end group |
|
|
137 @end example |
|
|
138 |
|
|
139 @noindent |
|
|
140 and the definition of @code{x} as a global variable at the top level, |
|
|
141 |
|
|
142 @example |
|
|
143 global x = 13 |
|
|
144 @end example |
|
|
145 |
|
|
146 @noindent |
|
|
147 the expression |
|
|
148 |
|
|
149 @example |
|
|
150 f (x) |
|
|
151 @end example |
|
|
152 |
|
|
153 @noindent |
|
|
154 will display the value of @code{x} from inside the function as 0, |
|
|
155 but the value of @code{x} at the top level remains unchanged, because |
|
|
156 the function works with a @emph{copy} of its argument. |
|
|
157 |
|
4029
|
158 @DOCSTRING(isglobal) |
|
3294
|
159 |
|
4686
|
160 @node Persistent Variables |
|
|
161 @section Persistent Variables |
|
|
162 @cindex persistent variables |
|
|
163 @cindex @code{persistent} statement |
|
|
164 @cindex variables, persistent |
|
|
165 |
|
|
166 A variable that has been declared @dfn{persistent} within a function |
|
|
167 will retain its contents in memory between subsequent calls to the |
|
|
168 same function. The difference between persistent variables and global |
|
|
169 variables is that persistent variables are local in scope to a |
|
|
170 particular function and are not visible elsewhere. |
|
|
171 |
|
|
172 A variable may be declared persistent using a @code{persistent} |
|
|
173 declaration statement. The following statements are all persistent |
|
|
174 declarations. |
|
|
175 |
|
|
176 @example |
|
|
177 @group |
|
|
178 persistent a |
|
|
179 persistent a b |
|
|
180 persistent c = 2 |
|
|
181 persistent d = 3 e f = 5 |
|
|
182 @end group |
|
|
183 @end example |
|
|
184 |
|
|
185 The behavior of persistent variables is equivalent to the behavior of |
|
|
186 static variables in C. The command @code{static} in octave is also |
|
|
187 recognized and is equivalent to @code{persistent}. Unlike global |
|
|
188 variables, every initialization statement will re-initialize the |
|
|
189 variable. For example, after executing the following code |
|
|
190 |
|
|
191 @example |
|
|
192 @group |
|
|
193 persistent pvar = 1 |
|
|
194 persistent pvar = 2 |
|
|
195 @end group |
|
|
196 @end example |
|
|
197 |
|
|
198 @noindent |
|
|
199 the value of the persistent variable @code{pvar} is 2. |
|
|
200 |
|
4167
|
201 @node Status of Variables |
|
3294
|
202 @section Status of Variables |
|
|
203 |
|
3361
|
204 @DOCSTRING(clear) |
|
3294
|
205 |
|
3361
|
206 @DOCSTRING(who) |
|
3294
|
207 |
|
4913
|
208 @DOCSTRING(whos) |
|
|
209 |
|
|
210 @DOCSTRING(whos_line_format) |
|
|
211 |
|
3361
|
212 @DOCSTRING(exist) |
|
3294
|
213 |
|
3361
|
214 @DOCSTRING(document) |
|
3294
|
215 |
|
3361
|
216 @DOCSTRING(type) |
|
3294
|
217 |
|
3361
|
218 @DOCSTRING(which) |
|
3294
|
219 |
|
4167
|
220 @node Summary of Built-in Variables |
|
3294
|
221 @section Summary of Built-in Variables |
|
|
222 |
|
|
223 Here is a summary of all of Octave's built-in variables along with |
|
|
224 cross references to additional information and their default values. In |
|
|
225 the following table @var{octave-home} stands for the root directory |
|
|
226 where all of Octave is installed (the default is @file{@value{OCTAVEHOME}}, |
|
|
227 @var{version} stands for the Octave version number (for example, |
|
|
228 @value{VERSION}) and @var{arch} stands for the type of system for which |
|
5942
|
229 Octave was compiled (for example, @code{x86_64-unknown-linux-gnu}). |
|
3294
|
230 |
|
|
231 @vtable @code |
|
|
232 @item DEFAULT_LOADPATH |
|
|
233 @xref{Function Files}. |
|
|
234 |
|
|
235 Default value: @code{".:@var{octave-home}/lib/@var{version}"}. |
|
|
236 |
|
|
237 @item EDITOR |
|
|
238 @xref{Commands For History}. |
|
|
239 |
|
|
240 Default value: @code{"emacs"}. |
|
|
241 |
|
|
242 @item EXEC_PATH |
|
|
243 @xref{Controlling Subprocesses}. |
|
|
244 |
|
|
245 Default value: @code{":$PATH"}. |
|
|
246 |
|
|
247 @item INFO_FILE |
|
|
248 @xref{Getting Help}. |
|
|
249 |
|
|
250 Default value: @code{"@var{octave-home}/info/octave.info"}. |
|
|
251 |
|
|
252 @item INFO_PROGRAM |
|
|
253 @xref{Getting Help}. |
|
|
254 |
|
|
255 Default value: @code{"@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch}/info"}. |
|
|
256 |
|
|
257 @item LOADPATH |
|
|
258 @xref{Function Files}. |
|
|
259 |
|
|
260 Default value: @code{":"}, which tells Octave to use the directories |
|
|
261 specified by the built-in variable @code{DEFAULT_LOADPATH}. |
|
|
262 |
|
|
263 @item OCTAVE_HOME |
|
|
264 |
|
|
265 Default value: @code{"@value{OCTAVEHOME}"}. |
|
|
266 |
|
|
267 @item PAGER |
|
|
268 @xref{Input and Output}. |
|
|
269 |
|
|
270 Default value: @code{"less", or "more"}. |
|
|
271 |
|
|
272 @item PS1 |
|
|
273 @xref{Customizing the Prompt}. |
|
|
274 |
|
|
275 Default value: @code{"\s:\#> "}. |
|
|
276 |
|
|
277 @item PS2 |
|
|
278 @xref{Customizing the Prompt}. |
|
|
279 |
|
|
280 Default value: @code{"> "}. |
|
|
281 |
|
|
282 @item PS4 |
|
|
283 @xref{Customizing the Prompt}. |
|
|
284 |
|
|
285 Default value: @code{"+ "}. |
|
|
286 |
|
|
287 @item automatic_replot |
|
5763
|
288 @xref{Low-Level plotting commands}. |
|
3294
|
289 |
|
|
290 Default value: 0. |
|
|
291 |
|
|
292 @item beep_on_error |
|
|
293 @xref{Error Handling}. |
|
|
294 |
|
|
295 Default value: 0. |
|
|
296 |
|
|
297 @item completion_append_char |
|
|
298 @xref{Commands For Completion}. |
|
|
299 |
|
|
300 Default value: @code{" "}. |
|
|
301 |
|
5287
|
302 @item default_save_options |
|
3294
|
303 @xref{Simple File I/O}. |
|
|
304 |
|
|
305 Default value: @code{"ascii"}. |
|
|
306 |
|
|
307 @item crash_dumps_octave_core |
|
|
308 @xref{Simple File I/O}. |
|
|
309 |
|
|
310 Default value: 1. |
|
|
311 |
|
|
312 @item fixed_point_format |
|
|
313 @xref{Matrices}. |
|
|
314 |
|
|
315 Default value: 0. |
|
|
316 |
|
|
317 @item gnuplot_binary |
|
|
318 @xref{Three-Dimensional Plotting}. |
|
|
319 |
|
|
320 Default value: @code{"gnuplot"}. |
|
|
321 |
|
|
322 @item history_file |
|
|
323 @xref{Commands For History}. |
|
|
324 |
|
|
325 Default value: @code{"~/.octave_hist"}. |
|
|
326 |
|
|
327 @item history_size |
|
|
328 @xref{Commands For History}. |
|
|
329 |
|
|
330 Default value: 1024. |
|
|
331 |
|
|
332 @item ignore_function_time_stamp |
|
|
333 @xref{Function Files}. |
|
|
334 |
|
|
335 Default value: @code{"system"}. |
|
|
336 |
|
|
337 @item max_recursion_depth |
|
|
338 @xref{Recursion}. |
|
|
339 |
|
|
340 Default value: 256. |
|
|
341 |
|
|
342 @item output_max_field_width |
|
|
343 @xref{Matrices}. |
|
|
344 |
|
|
345 Default value: 10. |
|
|
346 |
|
|
347 @item output_precision |
|
|
348 @xref{Matrices}. |
|
|
349 |
|
|
350 Default value: 5. |
|
|
351 |
|
|
352 @item page_screen_output |
|
|
353 @xref{Input and Output}. |
|
|
354 |
|
|
355 Default value: 1. |
|
|
356 |
|
|
357 @item print_answer_id_name |
|
|
358 @xref{Terminal Output}. |
|
|
359 |
|
|
360 Default value: 1. |
|
|
361 |
|
|
362 @item print_empty_dimensions |
|
|
363 @xref{Empty Matrices}. |
|
|
364 |
|
|
365 Default value: 1. |
|
|
366 |
|
|
367 @item return_last_computed_value |
|
|
368 @xref{Returning From a Function}. |
|
|
369 |
|
|
370 Default value: 0. |
|
|
371 |
|
|
372 @item save_precision |
|
|
373 @xref{Simple File I/O}. |
|
|
374 |
|
|
375 Default value: 17. |
|
|
376 |
|
|
377 @item saving_history |
|
|
378 @xref{Commands For History}. |
|
|
379 |
|
|
380 Default value: 1. |
|
|
381 |
|
4449
|
382 @item sighup_dumps_octave_core |
|
|
383 @xref{Simple File I/O}. |
|
|
384 |
|
|
385 Default value: 1. |
|
|
386 |
|
|
387 @item sigterm_dumps_octave_core |
|
|
388 @xref{Simple File I/O}. |
|
|
389 |
|
|
390 Default value: 1. |
|
|
391 |
|
3294
|
392 @item silent_functions |
|
|
393 @xref{Defining Functions}. |
|
|
394 |
|
|
395 Default value: 0. |
|
|
396 |
|
|
397 @item split_long_rows |
|
|
398 @xref{Matrices}. |
|
|
399 |
|
|
400 Default value: 1. |
|
|
401 |
|
|
402 @item struct_levels_to_print |
|
|
403 @xref{Data Structures}. |
|
|
404 |
|
|
405 Default value: 2. |
|
|
406 |
|
|
407 @item suppress_verbose_help_message |
|
|
408 @xref{Getting Help}. |
|
|
409 |
|
|
410 Default value: 1. |
|
|
411 |
|
|
412 @item warn_assign_as_truth_value |
|
|
413 @xref{The if Statement}. |
|
|
414 |
|
|
415 Default value: 1. |
|
|
416 |
|
|
417 @item warn_comma_in_global_decl |
|
|
418 @xref{Global Variables}. |
|
|
419 |
|
|
420 Default value: 1. |
|
|
421 |
|
|
422 @item warn_divide_by_zero |
|
|
423 @xref{Arithmetic Ops}. |
|
|
424 |
|
|
425 Default value: 1. |
|
|
426 |
|
4460
|
427 @item warn_empty_list_elements |
|
|
428 @xref{Empty Matrices}. |
|
|
429 |
|
|
430 Default value: 0. |
|
|
431 |
|
4455
|
432 @item warn_fortran_indexing |
|
|
433 @xref{Index Expressions}. |
|
|
434 |
|
|
435 Default value: 0. |
|
|
436 |
|
4452
|
437 @item warn_function_name_clash |
|
|
438 @xref{Function Files}. |
|
|
439 |
|
|
440 Default value: 1. |
|
|
441 |
|
4451
|
442 @item warn_imag_to_real |
|
|
443 @xref{Special Utility Matrices}. |
|
|
444 |
|
|
445 Default value: 0. |
|
|
446 |
|
4452
|
447 @item warn_missing_semicolon |
|
|
448 @xref{Defining Functions}. |
|
|
449 |
|
|
450 Default value: 0. |
|
|
451 |
|
4457
|
452 @item warn_neg_dim_as_zero |
|
|
453 @xref{Special Utility Matrices}. |
|
|
454 |
|
|
455 Default value: 0. |
|
|
456 |
|
4452
|
457 @item warn_num_to_str |
|
|
458 @xref{String Conversions}. |
|
3294
|
459 |
|
|
460 Default value: 1. |
|
|
461 |
|
|
462 @item warn_reload_forces_clear |
|
|
463 @xref{Dynamically Linked Functions}. |
|
|
464 |
|
|
465 Default value: 1. |
|
|
466 |
|
4461
|
467 @item warn_resize_on_range_error |
|
|
468 @xref{Index Expressions}. |
|
|
469 |
|
|
470 Default value: 0. |
|
|
471 |
|
4476
|
472 @item warn_separator_insert |
|
|
473 @xref{Matrices}. |
|
|
474 |
|
|
475 Default value: 0. |
|
|
476 |
|
|
477 @item warn_single_quote_string |
|
4452
|
478 @xref{String Conversions}. |
|
|
479 |
|
|
480 Default value: 0. |
|
|
481 |
|
4466
|
482 @item warn_str_to_num |
|
|
483 @xref{String Conversions}. |
|
|
484 |
|
|
485 Default value: 0. |
|
|
486 |
|
|
487 @item warn_undefined_return_values |
|
|
488 @xref{Multiple Return Values}. |
|
|
489 |
|
|
490 Default value: 0. |
|
|
491 |
|
3294
|
492 @item warn_variable_switch_label |
|
|
493 @xref{The switch Statement}. |
|
|
494 |
|
|
495 Default value: 0. |
|
|
496 @end vtable |
|
|
497 |
|
|
498 |
|
4167
|
499 @node Defaults from the Environment |
|
3294
|
500 @section Defaults from the Environment |
|
|
501 |
|
|
502 Octave uses the values of the following environment variables to set the |
|
|
503 default values for the corresponding built-in variables. In addition, |
|
|
504 the values from the environment may be overridden by command-line |
|
|
505 arguments. @xref{Command Line Options}. |
|
|
506 |
|
|
507 @vtable @code |
|
|
508 @item EDITOR |
|
|
509 @xref{Commands For History}. |
|
|
510 |
|
|
511 Built-in variable: @code{EDITOR}. |
|
|
512 |
|
|
513 @item OCTAVE_EXEC_PATH |
|
|
514 @xref{Controlling Subprocesses}. |
|
|
515 |
|
|
516 Built-in variable: @code{EXEC_PATH}. |
|
|
517 Command-line argument: @code{--exec-path}. |
|
|
518 |
|
|
519 @item OCTAVE_PATH |
|
|
520 @xref{Function Files}. |
|
|
521 |
|
|
522 Built-in variable: @code{LOADPATH}. |
|
|
523 Command-line argument: @code{--path}. |
|
|
524 |
|
|
525 @item OCTAVE_INFO_FILE |
|
|
526 @xref{Getting Help}. |
|
|
527 |
|
|
528 Built-in variable: @code{INFO_FILE}. |
|
|
529 Command-line argument: @code{--info-file}. |
|
|
530 |
|
|
531 @item OCTAVE_INFO_PROGRAM |
|
|
532 @xref{Getting Help}. |
|
|
533 |
|
|
534 Built-in variable: @code{INFO_PROGRAM}. |
|
|
535 Command-line argument: @code{--info-program}. |
|
|
536 |
|
|
537 @item OCTAVE_HISTSIZE |
|
|
538 @xref{Commands For History}. |
|
|
539 |
|
|
540 Built-in variable: @code{history_size}. |
|
|
541 |
|
|
542 @item OCTAVE_HISTFILE |
|
|
543 @xref{Commands For History}. |
|
|
544 |
|
|
545 Built-in variable: @code{history_file}. |
|
|
546 @end vtable |
