[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 9. Variables

Variables let you give names to values and refer to them later. You have already seen variables in many of the examples. The name of a variable must be a sequence of letters, digits and underscores, but it may not begin with a digit. Octave does not enforce a limit on the length of variable names, but it is seldom useful to have variables with names longer than about 30 characters. The following are all valid variable names

    x
    x15
    __foo_bar_baz__
    fucnrdthsucngtagdjb

However, names like `__foo_bar_baz__` that begin and end with two underscores are understood to be reserved for internal use by Octave. You should not use them in code you write, except to access Octave's documented internal variables and built-in symbolic constants.

Case is significant in variable names. The symbols `a` and `A` are distinct variables.

A variable name is a valid expression by itself. It represents the variable's current value. Variables are given new values with assignment operators and increment operators. See section Assignment Expressions.

A number of variables have special built-in meanings. For example, `ans` holds the current working directory, and `pi` names the ratio of the circumference of a circle to its diameter. See section 9.4 Summary of Built-in Variables, for a list of all the predefined variables. Some of these built-in symbols are constants and may not be changed. Others can be used and assigned just like all other variables, but their values are also used or changed automatically by Octave.

Variables in Octave do not have fixed types, so it is possible to first store a numeric value in a variable and then to later use the same name to hold a string value in the same program. Variables may not be used before they have been given a value. Doing so results in an error.

9.1 Global Variables |  |
9.2 Persistent Variables |  |
9.3 Status of Variables |  |
9.4 Summary of Built-in Variables |  |
9.5 Defaults from the Environment |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 9.1 Global Variables

A variable that has been declared global may be accessed from within a function body without having to pass it as a formal parameter.

A variable may be declared global using a `global` declaration statement. The following statements are all global declarations.

    global a
    global a b
    global c = 2
    global d = 3 e f = 5

A global variable may only be initialized once in a `global` statement. For example, after executing the following code

    global gvar = 1
    global gvar = 2

the value of the global variable `gvar` is 1, not 2.

It is necessary declare a variable as global within a function body in order to access it. For example,

    global x
    function f ()
      x = 1;
    endfunction
    f ()

does not set the value of the global variable `x` to 1. In order to change the value of the global variable `x`, you must also declare it to be global within the function body, like this

    function f ()
      global x;
      x = 1;
    endfunction

Passing a global variable in a function parameter list will make a local copy and not modify the global value. For example, given the function

    function f (x)
      x = 0
    endfunction

and the definition of `x` as a global variable at the top level,

    global x = 13

the expression

    f (x)

will display the value of `x` from inside the function as 0, but the value of `x` at the top level remains unchanged, because the function works with a copy of its argument.

Built-in Function: isglobal (name)
  Return 1 if name is globally visible. Otherwise, return 0. For example,

      global x
      isglobal ("x")
           => 1

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 9.2 Persistent Variables

A variable that has been declared persistent within a function will retain its contents in memory between subsequent calls to the same function. The difference between persistent variables and global variables is that persistent variables are local in scope to a particular function and are not visible elsewhere.

A variable may be declared persistent using a `persistent` declaration statement. The following statements are all persistent declarations.

    persistent a
    persistent a b
    persistent c = 2
    persistent d = 3 e f = 5

The behavior of persistent variables is equivalent to the behavior of static variables in C. The command `static` in octave is also recognized and is equivalent to `persistent`. Unlike global variables, every initialization statement will re-initialize the variable. For example, after executing the following code

    persistent pvar = 1
    persistent pvar = 2

the value of the persistent variable `pvar` is 2.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 9.3 Status of Variables

Command: clear [-x] pattern ...
  Delete the names matching the given patterns from the symbol table. The pattern may contain the following special characters:

  `?`
    Match any single character.

  `*`
    Match zero or more characters.

  `[ list ]`
    Match the list of characters specified by list. If the first character is `!` or `^`, match all characters except those specified by list. For example, the pattern ``[a-zA-Z]`' will match all lower and upper case alphabetic characters.

  For example, the command

      clear foo b*r

  clears the name `foo` and all names that begin with the letter `b` and end with the letter `r`.

  If `clear` is called without any arguments, all user-defined variables (local and global) are cleared from the symbol table. If `clear` is called with at least one argument, only the visible names matching the arguments are cleared. For example, suppose you have defined a function `foo`, and then hidden it by performing the assignment `foo = 2`. Executing the command `clear foo` once will clear the variable definition and restore the definition of `foo` as a function. Executing `clear foo` a second time will clear the function definition.

  With -x, clear the variables that don't match the patterns.

  This command may not be used within a function body.

Command: who options pattern ...
Command: whos options pattern ...
  List currently defined symbols matching the given patterns. The following are valid options. They may be shortened to one character but may not be combined.

  `-all`
    List all currently defined symbols.

  `-builtins`
    List built-in variables and functions. This includes all currently compiled function files, but does not include all function files that are in the `LOADPATH`.

  `-functions`
    List user-defined functions.

  `-long`
    Print a long listing including the type and dimensions of any symbols. The symbols in the first column of output indicate whether it is possible to redefine the symbol, and whether it is possible for it to be cleared.

  `-variables`
    List user-defined variables.

  Valid patterns are the same as described for the `clear` command above. If no patterns are supplied, all symbols from the given category are listed. By default, only user defined functions and variables visible in the local scope are displayed.

  The command `whos` is equivalent to `who -long`.

Command: whos options pattern ...
  See who.

Built-in Variable: whos_line_format
  This string decides in what order attributtes of variables are to be printed. The following commands are used:
  `%b`
    Prints number of bytes occupied by variables.
  `%e`
    Prints elements held by variables.
  `%n`
    Prints variable names.
  `%p`
    Prints protection attributtes of variables.
  `%s`
    Prints dimensions of variables.
  `%t`
    Prints type names of variables.

  Every command may also have a modifier:

  `l`
    Left alignment.
  `r`
    Right alignment (this is the default).
  `c`
    Centered (may only be applied to command %s).

  A command is composed like this: %[modifier]<command>[:size_of_parameter[:center-specific[:print_dims[:balance]]]];

  Command and modifier is already explained. Size_of_parameter tells how many columns the parameter will need for printing. print_dims tells how many dimensions to print. If number of dimensions exceeds print_dims, dimensions will be printed like x-D. center-specific and print_dims may only be applied to command %s. A negative value for print_dims will cause Octave to print all dimensions whatsoever. balance specifies the offset for printing of the dimensions string.

  Default format is " %p:4; %ln:6; %cs:16:6:8:1; %rb:12; %lt:-1;\n".

Built-in Function: exist (name, type)
  Return 1 if the name exists as a variable, 2 if the name (after appending ``.m`') is a function file in Octave's LOADPATH, 3 if the name is a ``.oct`' file in Octave's LOADPATH, 5 if the name is a built-in function, 7 if the name is a directory, 101 if the name is a built-in variable, 102 if the name is a built-in constant, or 103 if the name is a function not associated with a file (entered on the command line).

  Otherwise, return 0.

  This function also returns 2 if a regular file called name exists in Octave's `LOADPATH`. If you want information about other types of files, you should use some combination of the functions `file_in_path` and `stat` instead.

  If the optional argument type is supplied, check only for symbols of the specified type. Valid types are

  ``"var"`'
    Check only for variables.
  ``"builtin"`'
    Check only for built-in functions.
  ``"file"`'
    Check only for files.
  ``"dir"`'
    Check only for directories.

Built-in Function: document (symbol, text)
  Set the documentation string for symbol to text.

Command: type options name ...
  Display the definition of each name that refers to a function.

  Normally also displays if each name is user-defined or builtin; the `-q` option suppresses this behaviour.

  Currently, Octave can only display functions that can be compiled cleanly, because it uses its internal representation of the function to recreate the program text.

  Comments are not displayed because Octave's parser currently discards them as it converts the text of a function file to its internal representation. This problem may be fixed in a future release.

Command: which name ...
  Display the type of each name. If name is defined from a function file, the full name of the file is also displayed.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 9.4 Summary of Built-in Variables

Here is a summary of all of Octave's built-in variables along with cross references to additional information and their default values. In the following table octave-home stands for the root directory where all of Octave is installed (the default is ``/usr/local`', version stands for the Octave version number (for example, 2.1.x) and arch stands for the type of system for which Octave was compiled (for example, `i586-pc-linux-gnu`).

`DEFAULT_LOADPATH`
  See section 13.6 Function Files.

  Default value: `".:octave-home/lib/version"`.

`EDITOR`
  See section 2.4.5 Commands For Manipulating The History.

  Default value: `"emacs"`.

`EXEC_PATH`
  See section 34.3 Controlling Subprocesses.

  Default value: `":$PATH"`.

`INFO_FILE`
  See section 2.3 Commands for Getting Help.

  Default value: `"octave-home/info/octave.info"`.

`INFO_PROGRAM`
  See section 2.3 Commands for Getting Help.

  Default value: `"octave-home/libexec/octave/version/exec/arch/info"`.

`LOADPATH`
  See section 13.6 Function Files.

  Default value: `":"`, which tells Octave to use the directories specified by the built-in variable `DEFAULT_LOADPATH`.

`OCTAVE_HOME`

  Default value: `"/usr/local"`.

`PAGER`
  See section 16. Input and Output.

  Default value: `"less", or "more"`.

`PS1`
  See section 2.4.7 Customizing the Prompt.

  Default value: `"\s:\#> "`.

`PS2`
  See section 2.4.7 Customizing the Prompt.

  Default value: `"> "`.

`PS4`
  See section 2.4.7 Customizing the Prompt.

  Default value: `"+ "`.

`automatic_replot`
  See section 17.1 Two-Dimensional Plotting.

  Default value: 0.

`beep_on_error`
  See section 14. Error Handling.

  Default value: 0.

`completion_append_char`
  See section 2.4.4 Letting Readline Type For You.

  Default value: `" "`.

`default_save_format`
  See section 16.1.3 Simple File I/O.

  Default value: `"ascii"`.

`crash_dumps_octave_core`
  See section 16.1.3 Simple File I/O.

  Default value: 1.

`fixed_point_format`
  See section 4.1 Matrices.

  Default value: 0.

`gnuplot_binary`
  See section 17.3 Three-Dimensional Plotting.

  Default value: `"gnuplot"`.

`history_file`
  See section 2.4.5 Commands For Manipulating The History.

  Default value: `"~/.octave_hist"`.

`history_size`
  See section 2.4.5 Commands For Manipulating The History.

  Default value: 1024.

`ignore_function_time_stamp`
  See section 13.6 Function Files.

  Default value: `"system"`.

`max_recursion_depth`
  See section 10.2.2 Recursion.

  Default value: 256.

`output_max_field_width`
  See section 4.1 Matrices.

  Default value: 10.

`output_precision`
  See section 4.1 Matrices.

  Default value: 5.

`page_screen_output`
  See section 16. Input and Output.

  Default value: 1.

`print_answer_id_name`
  See section 16.1.1 Terminal Output.

  Default value: 1.

`print_empty_dimensions`
  See section 4.1.1 Empty Matrices.

  Default value: 1.

`return_last_computed_value`
  See section 13.5 Returning From a Function.

  Default value: 0.

`save_precision`
  See section 16.1.3 Simple File I/O.

  Default value: 17.

`saving_history`
  See section 2.4.5 Commands For Manipulating The History.

  Default value: 1.

`sighup_dumps_octave_core`
  See section 16.1.3 Simple File I/O.

  Default value: 1.

`sigterm_dumps_octave_core`
  See section 16.1.3 Simple File I/O.

  Default value: 1.

`silent_functions`
  See section 13.1 Defining Functions.

  Default value: 0.

`split_long_rows`
  See section 4.1 Matrices.

  Default value: 1.

`struct_levels_to_print`
  See section 6. Data Structures.

  Default value: 2.

`suppress_verbose_help_message`
  See section 2.3 Commands for Getting Help.

  Default value: 1.

`warn_assign_as_truth_value`
  See section 12.1 The `if` Statement.

  Default value: 1.

`warn_comma_in_global_decl`
  See section 9.1 Global Variables.

  Default value: 1.

`warn_divide_by_zero`
  See section 10.3 Arithmetic Operators.

  Default value: 1.

`warn_empty_list_elements`
  See section 4.1.1 Empty Matrices.

  Default value: 0.

`warn_fortran_indexing`
  See section 10.1 Index Expressions.

  Default value: 0.

`warn_function_name_clash`
  See section 13.6 Function Files.

  Default value: 1.

`warn_imag_to_real`
  See section 18.3 Special Utility Matrices.

  Default value: 0.

`warn_missing_semicolon`
  See section 13.1 Defining Functions.

  Default value: 0.

`warn_neg_dim_as_zero`
  See section 18.3 Special Utility Matrices.

  Default value: 0.

`warn_num_to_str`
  See section 5.3 String Conversions.

  Default value: 1.

`warn_reload_forces_clear`
  See section 13.8 Dynamically Linked Functions.

  Default value: 1.

`warn_resize_on_range_error`
  See section 10.1 Index Expressions.

  Default value: 0.

`warn_separator_insert`
  See section 4.1 Matrices.

  Default value: 0.

`warn_single_quote_string`
  See section 5.3 String Conversions.

  Default value: 0.

`warn_str_to_num`
  See section 5.3 String Conversions.

  Default value: 0.

`warn_undefined_return_values`
  See section 13.2 Multiple Return Values.

  Default value: 0.

`warn_variable_switch_label`
  See section 12.2 The `switch` Statement.

  Default value: 0.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 9.5 Defaults from the Environment

Octave uses the values of the following environment variables to set the default values for the corresponding built-in variables. In addition, the values from the environment may be overridden by command-line arguments. See section 2.1.1 Command Line Options.

`EDITOR`
  See section 2.4.5 Commands For Manipulating The History.

  Built-in variable: `EDITOR`.

`OCTAVE_EXEC_PATH`
  See section 34.3 Controlling Subprocesses.

  Built-in variable: `EXEC_PATH`. Command-line argument: `--exec-path`.

`OCTAVE_PATH`
  See section 13.6 Function Files.

  Built-in variable: `LOADPATH`. Command-line argument: `--path`.

`OCTAVE_INFO_FILE`
  See section 2.3 Commands for Getting Help.

  Built-in variable: `INFO_FILE`. Command-line argument: `--info-file`.

`OCTAVE_INFO_PROGRAM`
  See section 2.3 Commands for Getting Help.

  Built-in variable: `INFO_PROGRAM`. Command-line argument: `--info-program`.

`OCTAVE_HISTSIZE`
  See section 2.4.5 Commands For Manipulating The History.

  Built-in variable: `history_size`.

`OCTAVE_HISTFILE`
  See section 2.4.5 Commands For Manipulating The History.

  Built-in variable: `history_file`.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by John W. Eaton on May, 18 2005 using texi2html