@c Copyright (C) 1996, 1997, 2007 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Variables
@chapter Variables
@cindex variables, user-defined
@cindex user-defined 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

@cindex job hunting
@cindex getting a good job
@cindex flying high and fast
@example
@group
x
x15
__foo_bar_baz__
fucnrdthsucngtagdjb
@end group
@end example

@noindent
However, names like @code{__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 @code{a} and
@code{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
@dfn{assignment operators} and @dfn{increment operators}.
@xref{Assignment Ops, ,Assignment Expressions}.

A number of variables have special built-in meanings.  For example,
@code{ans} holds the current working directory, and @code{pi} names the
ratio of the circumference of a circle to its diameter. @xref{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.

@DOCSTRING(isvarname)

@menu
* Global Variables::            
* Persistent Variables::        
* Status of Variables::         
* Summary of Built-in Variables::  
* Defaults from the Environment::  
@end menu

@node Global Variables
@section Global Variables
@cindex global variables
@cindex @code{global} statement
@cindex variables, global

A variable that has been declared @dfn{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 @code{global} declaration
statement.  The following statements are all global declarations.

@example
@group
global a
global a b
global c = 2
global d = 3 e f = 5
@end group
@end example

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

@example
@group
global gvar = 1
global gvar = 2
@end group
@end example

@noindent
the value of the global variable @code{gvar} is 1, not 2.  Issuing a
@samp{clear gvar} command does not change the above behavior, but
@samp{clear all} does.

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

@example
@group
global x
function f ()
  x = 1;
endfunction
f ()
@end group
@end example

@noindent
does @emph{not} set the value of the global variable @code{x} to 1.  In
order to change the value of the global variable @code{x}, you must also
declare it to be global within the function body, like this

@example
@group
function f ()
  global x;
  x = 1;
endfunction
@end group
@end example

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

@example
@group
function f (x)
  x = 0
endfunction
@end group
@end example

@noindent
and the definition of @code{x} as a global variable at the top level,

@example
global x = 13
@end example

@noindent
the expression

@example
f (x)
@end example

@noindent
will display the value of @code{x} from inside the function as 0,
but the value of @code{x} at the top level remains unchanged, because
the function works with a @emph{copy} of its argument.

@DOCSTRING(isglobal)

@node Persistent Variables
@section Persistent Variables
@cindex persistent variables
@cindex @code{persistent} statement
@cindex variables, persistent

A variable that has been declared @dfn{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 @code{persistent}
declaration statement.  The following statements are all persistent
declarations.

@example
@group
persistent a
persistent a b
persistent c = 2
persistent d = 3 e f = 5
@end group
@end example

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

@example
@group
persistent pvar = 1
persistent pvar = 2
@end group
@end example

@noindent
the value of the persistent variable @code{pvar} is 2.

@node Status of Variables
@section Status of Variables

When creating simple one-shot programs it can be very convenient to
see which variables are available at the prompt. The function @code{who}
and its siblings @code{whos} and @code{whos_line_format} will show
different information about what is in memory, as the following shows.

@example
str = "A random string";
who -variables
     @print{} *** local user variables:
     @print{} 
     @print{} __nargin__  str
@end example

@DOCSTRING(who)

@DOCSTRING(whos)

@DOCSTRING(whos_line_format)

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 behaviour of a program depending on the existence of a
variable. The following example illustrates this.

@example
if (! exist ("meaning", "var"))
  disp ("The program has no 'meaning'");
endif
@end example

@DOCSTRING(exist)

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.

@example
large_matrix = zeros (4000, 4000);
@end example

@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}
function allows this.

@DOCSTRING(clear)

Information about a function or variable such as it's 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.

@DOCSTRING(document)

@DOCSTRING(type)

@DOCSTRING(which)

@node Summary of Built-in Variables
@section 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 @var{octave-home} stands for the root directory
where all of Octave is installed (the default is @file{@value{OCTAVEHOME}},
@var{version} stands for the Octave version number (for example,
@value{VERSION}) and @var{arch} stands for the type of system for which
Octave was compiled (for example, @code{x86_64-unknown-linux-gnu}).

@vtable @code
@item EDITOR
@xref{Commands For History}.

Default value: @code{"emacs"}.

@item EXEC_PATH
@xref{Controlling Subprocesses}.

Default value: @code{":$PATH"}.

@item OCTAVE_HOME

Default value: @code{"@value{OCTAVEHOME}"}.

@item PAGER
@xref{Input and Output}.

Default value: @code{"less", or "more"}.

@item PS1
@xref{Customizing the Prompt}.

Default value: @code{"\s:\#> "}.

@item PS2
@xref{Customizing the Prompt}.

Default value: @code{"> "}.

@item PS4
@xref{Customizing the Prompt}.

Default value: @code{"+ "}.

@item beep_on_error
@xref{Errors and Warnings}.

Default value: 0.

@item completion_append_char
@xref{Commands For Completion}.

Default value: @code{" "}.

@item default_save_options
@xref{Simple File I/O}.

Default value: @code{"ascii"}.

@item crash_dumps_octave_core
@xref{Simple File I/O}.

Default value: 1.

@item fixed_point_format
@xref{Matrices}.

Default value: 0.

@item gnuplot_binary
@xref{Three-Dimensional Plotting}.

Default value: @code{"gnuplot"}.

@item history_file
@xref{Commands For History}.

Default value: @code{"~/.octave_hist"}.

@item history_size
@xref{Commands For History}.

Default value: 1024.

@item ignore_function_time_stamp
@xref{Function Files}.

Default value: @code{"system"}.

@item max_recursion_depth
@xref{Recursion}.

Default value: 256.

@item output_max_field_width
@xref{Matrices}.

Default value: 10.

@item output_precision
@xref{Matrices}.

Default value: 5.

@item page_screen_output
@xref{Input and Output}.

Default value: 1.

@item print_answer_id_name
@xref{Terminal Output}.

Default value: 1.

@item print_empty_dimensions
@xref{Empty Matrices}.

Default value: 1.

@item return_last_computed_value
@xref{Returning From a Function}.

Default value: 0.

@item save_precision
@xref{Simple File I/O}.

Default value: 17.

@item saving_history
@xref{Commands For History}.

Default value: 1.

@item sighup_dumps_octave_core
@xref{Simple File I/O}.

Default value: 1.

@item sigterm_dumps_octave_core
@xref{Simple File I/O}.

Default value: 1.

@item silent_functions
@xref{Defining Functions}.

Default value: 0.

@item split_long_rows
@xref{Matrices}.

Default value: 1.

@item struct_levels_to_print
@xref{Data Structures}.

Default value: 2.

@item suppress_verbose_help_message
@xref{Getting Help}.

Default value: 1.
@end vtable


@node Defaults from the Environment
@section Defaults from the Environment

Octave uses the values of the following environment variables to set the
default values for the corresponding built-in or internal variables.
In addition, the values from the environment may be overridden by
command-line arguments.  @xref{Command Line Options}.

@vtable @code
@item EDITOR
@xref{Commands For History}.

Built-in variable: @code{EDITOR}.

@item OCTAVE_EXEC_PATH        
@xref{Controlling Subprocesses}.

Built-in variable: @code{EXEC_PATH}.
Command-line argument: @code{--exec-path}.

@item OCTAVE_PATH
@xref{Function Files}.

Internal variable changed by function @code{path}.
Command-line argument: @code{--path}.

@item OCTAVE_INFO_FILE
@xref{Getting Help}.

Internal variable changed by function @code{info_file}.
Command-line argument: @code{--info-file}.

@item OCTAVE_INFO_PROGRAM
@xref{Getting Help}.

Internal variable changed by function @code{info_program}.
Command-line argument: @code{--info-program}.

@item OCTAVE_HISTSIZE
@xref{Commands For History}.

Built-in variable: @code{history_size}.

@item OCTAVE_HISTFILE
@xref{Commands For History}.

Built-in variable: @code{history_file}.
@end vtable