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

@node Built-in Variables, Arithmetic, Functions and Scripts, Top
@chapter Built-in Variables
@cindex variables
@cindex built-in variables
@cindex variables, built-in

Most Octave variables are available for you to use for your own
purposes; they never change except when your program assigns values to
them, and never affect anything except when your program examines them.

A few variables have special built-in meanings.  Some of them, like
@code{pi} and @code{eps} provide useful predefined constant values.
Others, like @code{do_fortran_indexing} and @code{page_screen_output}
are examined automatically by Octave, so that you can to tell Octave how
to do certain things.  There are also two special variables, @code{ans}
and @code{PWD}, that are set automatically by Octave and carry
information from the internal workings of Octave to your program.

This chapter documents all the built-in variables of Octave.
Most of them are also documented in the chapters that describe functions
that use them, or are affected by their values.
@c XXX FIXME XXX -- this should eventually happen.

@menu
* Predefined Constants::        
* User Preferences::            
* Other Built-in Variables::    
* Summary of Preference Variables::  
@end menu

@node Predefined Constants, User Preferences, Built-in Variables, Built-in Variables
@section Predefined Constants

@vtable @code
@item I@r{,} i@r{,} J@r{,} j
A pure imaginary number, defined as
@iftex
@tex
  $\sqrt{-1}$.
@end tex
@end iftex
@ifinfo
  @code{sqrt (-1)}.
@end ifinfo
The @code{I} and @code{J} forms are true constants, and cannot be
modified.  The @code{i} and @code{j} forms are like ordinary variables,
and may be used for other purposes.  However, unlike other variables,
they once again assume their special predefined values if they are
cleared @xref{Miscellaneous Utilities}.

@item Inf@r{,} inf
Infinity.  This is the result of an operation like 1/0, or an operation
that results in a floating point overflow.

@item NaN@r{,} nan
Not a number.  This is the result of an operation like @samp{0/0}, or
@samp{Inf - Inf}, or any operation with a NaN.

@item SEEK_SET
@itemx SEEK_CUR
@itemx SEEK_END
These variables may be used as the optional third argument for the
function @code{fseek}.

@item eps
The machine precision.  More precisely, @code{eps} is the smallest value
such that @samp{1+eps} is not equal to 1.  This number is
system-dependent.  On machines that support 64 bit IEEE floating point
arithmetic, @code{eps} is approximately
@ifinfo
 2.2204e-16.
@end ifinfo
@iftex
@tex
 $2.2204\times10^{-16}$.
@end tex
@end iftex

@item pi
The ratio of the circumference of a circle to its diameter.
Internally, @code{pi} is computed as @samp{4.0 * atan (1.0)}.

@ignore
@item read_only_constants
XXX FIXME XXX -- need description here.
@end ignore

@item realmax
The largest floating point number that is representable.  The actual
value is system-dependent.  On machines that support 64 bit IEEE
floating point arithmetic, @code{realmax} is approximately
@ifinfo
 1.7977e+308
@end ifinfo
@iftex
@tex
 $1.7977\times10^{308}$.
@end tex
@end iftex

@item realmin
The smallest floating point number that is representable.  The actual
value is system-dependent.  On machines that support 64 bit IEEE
floating point arithmetic, @code{realmin} is approximately
@ifinfo
 2.2251e-308
@end ifinfo
@iftex
@tex
 $2.2251\times10^{-308}$.
@end tex
@end iftex

@item stdin
@itemx stdout
@itemx stderr
These variables are the file numbers corresponding to the standard
input, standard output, and standard error streams.  These streams are
preconnected and available when Octave starts.
@end vtable

@node User Preferences, Other Built-in Variables, Predefined Constants, Built-in Variables
@section User Preferences

This section describes the variables that you can use to customize
Octave's behavior.

Normally, preferences are set in the file @file{~/.octaverc}, so that
you can customize your environment in the same way each time you use
Octave without having to remember and retype all the necessary commands.
@xref{Startup Files} for more information.

@vtable @code
@item EDITOR
A string naming the editor to use with the @code{edit_history} command.
If the environment variable @code{EDITOR} is set when Octave starts, its
value is used as the default.  Otherwise, @code{EDITOR} is set to
@code{"vi"}.

@item IMAGEPATH			
A colon separated list of directories in which to search for image
files.  @xref{Image Processing} for a description of Octave's image
processing capabilities.

@item INFO_FILE
A string naming the location of the Octave info file.

The default value is @code{"@value{OCTAVEHOME}/info/octave.info"}.

@item LOADPATH
A colon separated list of directories in which to search for function
files.  @xref{Functions and Scripts}.  The value of @code{LOADPATH}
overrides the environment variable @code{OCTAVE_PATH}.  @xref{Installation}.

@code{LOADPATH} is now handled in the same way as @TeX{} handles
@code{TEXINPUTS}.  If the path starts with @samp{:}, the standard path
is prepended to the value of @code{LOADPATH}.  If it ends with @samp{:}
the standard path is appended to the value of @code{LOADPATH}.

In addition, if any path element ends in @samp{//}, that directory and
all subdirectories it contains are searched recursively for function
files.  This can result in a slight delay as Octave caches the lists of
files found in the @code{LOADPATH} the first time Octave searches for a
function.  After that, searching is usually much faster because Octave
normally only needs to search its internal cache for files.

To improve performance of recursive directory searching, it is best for
each directory that is to be searched recursively to contain
@emph{either} additional subdirectories @emph{or} function files, but
not a mixture of both.

@xref{Organization of Functions} for a description of the function file
directories that are distributed with Octave.

@item OCTAVE_VERSION
The version number of Octave, as a string.

@item PAGER
The default value is @code{"less"}, or, if @code{less} is not available
on your system, @code{"more"}.  @xref{Installation}, and
@ref{Input and Output}. 

@item PS1
The primary prompt string.  When executing interactively, Octave
displays the primary prompt @code{PS1} when it is ready to read a
command.  Octave allows the prompt to be customized by inserting a
number of backslash-escaped special characters that are decoded as
follows:

@table @samp
@item \t
The time.
@item \d
The date.
@item \n
Begins a new line by printing the equivalent of a carriage return
followed by a line feed.
@item \s
The name of the program (usually just @code{octave}).
@item \w
The current working directory.
@item \W
The basename of the current working directory.
@item \u
The username of the current user.
@item \h
The hostname.
@item \#
The command number of this command, counting from when Octave starts.
@item \!
The history number of this command.  This differs from @samp{\#} by the
number of commands in the history list when Octave starts.
@item \$
If the effective UID is 0, a #, otherwise a $.
@item \nnn
The character whose character code in octal is @samp{nnn}.
@item \\
A backslash.
@end table

The default value of @code{PS1} is @code{"\s:\#> "}.  To change it, use a
command like

@example
octave:13> PS1 = "\\u@@\\h> "
@end example

@noindent
which will result in the prompt @samp{boris@@kremvax> } for the user
@samp{boris} logged in on the host @samp{kremvax}.  Note that two
backslashes are required to enter a backslash into a string.
@xref{String Constants}.

@item PS2
The secondary prompt string, which is printed when Octave is
expecting additional input to complete a command.  For example, when
defining a function over several lines, Octave will print the value of
@code{PS1} at the beginning of each line after the first.  Octave allows
@code{PS2} to be customized in the same way as @code{PS1}.  The default
value of @code{PS2} is @code{"> "}.

@item PS4
If Octave is invoked with the @code{--echo-input} option, the value of
@code{PS4} is printed before each line of input that is echoed.  Octave
allows @code{PS4} to be customized in the same way as @code{PS1}.  The
default value of @code{PS4} is @code{"+ "}.  @xref{Invoking Octave}, for
a description of @code{--echo-input}.

@item automatic_replot
If this variable is @code{"true"}, Octave will automatically send a
@code{replot} command to @code{gnuplot} each time the plot changes.
Since this is fairly inefficient, the default value is @code{"false"}.

@item default_return_value
The value given to otherwise unitialized return values if
@code{define_all_return_values} is @code{"true"}.  The default value is
@code{[]}.

@item default_save_format
Specify the default format used by the @code{save} command.  Options are
@code{"ascii"}, @code{"binary"}, @code{"mat-binary"}, or
@code{"float-binary"}.  The default value is @code{ascii}.

@item define_all_return_values
If the value of @code{define_all_return_values} is @code{"true"}, Octave
will substitute the value specified by @code{default_return_value} for
any return values that remain undefined when a function returns.  The
default value is @code{"false"}.

@item do_fortran_indexing
If the value of @code{do_fortran_indexing} is @code{"true"}, Octave allows 
you to select elements of a two-dimensional matrix using a single index
by treating the matrix as a single vector created from the columns of
the matrix.  The default value is @code{"false"}. 

@item empty_list_elements_ok
This variable controls whether Octave ignores empty matrices in a matrix
list.

For example, if the value of @code{empty_list_elements_ok} is
@code{"true"}, Octave will ignore the empty matrices in the expression

@example
a = [1, [], 3, [], 5]
@end example

@noindent
and the variable @samp{a} will be assigned the value @samp{[ 1 3 5 ]}.

The default value is @code{"warn"}.

@item gnuplot_binary
The name of the program invoked by the plot command.  The default value
is @code{"gnuplot"}.  @xref{Installation}.

@item ignore_function_time_stamp
This variable variable can be used to prevent Octave from making the
system call @code{stat()} each time it looks up functions defined in
function files.  If @code{ignore_function_time_stamp} to
@code{"system"}, Octave will not automatically recompile function files
in subdirectories of @code{@value{OCTAVEHOME}/lib/@value{VERSION}} if
they have changed since they were last compiled, but will recompile
other function files in the @code{LOADPATH} if they change.  If set to
@code{"all"}, Octave will not recompile any function files unless their
definitions are removed with @code{clear}.  For any other value of
@code{ignore_function_time_stamp}, Octave will always check to see if
functions defined in function files need to recompiled.  The default
value of @code{ignore_function_time_stamp} is @code{"system"}.

@item implicit_str_to_num_ok
If the value of @code{implicit_str_to_num_ok} is @code{"true"}, implicit
conversions of strings to their numeric ASCII equivalents are allowed.
Otherwise, an error message is printed and control is returned to the
top level.  The default value is @code{"false"}.

@item ok_to_lose_imaginary_part
If the value of @code{ok_to_lose_imaginary_part} is @code{"true"},
implicit conversions of complex numbers to real numbers are allowed (for
example, by fsolve).  If the value is @code{"warn"}, the conversion is allowed,
but a warning is printed.  Otherwise, an error message is printed and
control is returned to the top level.  The default value is @code{"warn"}.

@item output_max_field_width
This variable specifies the maximum width of a numeric output field.
The default value is 10.

It is possible to achieve a wide range of output styles by using
different values of @code{output_precision} and
@code{output_max_field_width}.  Reasonable combinations can be set using
the @code{format} function.  @xref{Basic Input and Output}.

@item output_precision
This variable specifies the minimum number of significant figures to
display for numeric output.  The default value is 5.

It is possible to achieve a wide range of output styles by using
different values of @code{output_precision} and
@code{output_max_field_width}.  Reasonable combinations can be set using
the @code{format} function.  @xref{Basic Input and Output}.

@item page_screen_output
If the value of @code{page_screen_output} is @code{"true"}, all output
intended for the screen that is longer than one page is sent through a
pager.  This allows you to view one screenful at a time.  Some pagers
(such as @code{less}---see @ref{Installation}) are also capable of moving
backward on the output.  The default value is @code{"true"}.
@xref{Input and Output}.

You can choose the program to use as the pager by setting the variable
@code{PAGER}.

@item prefer_column_vectors
If @code{prefer_column_vectors} is @code{"true"}, operations like

@example
for i = 1:10
  a (i) = i;
endfor
@end example

@noindent
(for @samp{a} previously  undefined) produce column vectors.  Otherwise, row
vectors are preferred.  The default value is @code{"false"}.

If a variable is already defined to be a vector (a matrix with a single
row or column), the original orientation is respected, regardless of the
value of @code{prefer_column_vectors}.

@item prefer_zero_one_indexing
If the value of @code{prefer_zero_one_indexing} is @code{"true"}, Octave
will perform zero-one style indexing when there is a conflict with the
normal indexing rules.  @xref{Index Expressions}.  For example, given a
matrix

@example
a = [1, 2, 3, 4]
@end example

@noindent
with @code{prefer_zero_one_indexing} is set to @code{"true"}, the
expression

@example
a ([1, 1, 1, 1])
@end example

@noindent
results in the matrix @samp{[ 1  2  3  4 ]}.  If the value of
@code{prefer_zero_one_indexing} set to @code{"false"}, the result would be
the matrix @samp{[ 1 1 1 1 ]}.

In the first case, Octave is selecting each element corresponding to a
@samp{1} in the index vector.  In the second, Octave is selecting the
first element multiple times.

The default value for @code{prefer_zero_one_indexing} is @code{"false"}.

@item print_answer_id_name
If the value of @code{print_answer_id_name} is @code{"true"}, variable
names are printed along with the result.  Otherwise, only the result
values are printed.  The default value is @code{"true"}.

@item print_empty_dimensions
If the value of @code{print_empty_dimensions} is @code{"true"}, the
dimensions of empty matrices are printed along with the empty matrix
symbol, @samp{[]}.  For example, the expression

@example
zeros (3, 0)
@end example

@noindent
will print

@example
ans =

[](3x0)
@end example

@item propagate_empty_matrices
If the value of @code{propagate_empty_matrices} is @code{"true"},
functions like @code{inverse} and @code{svd} will return an empty matrix
if they are given one as an argument.  The default value is @code{"true"}.
@xref{Empty Matrices}.

@item resize_on_range_error
If the value of @code{resize_on_range_error} is @code{"true"}, expressions
like

@example
for i = 1:10
  a (i) = i;
endfor
@end example

@noindent
(for @samp{a} previously undefined) result in the variable @samp{a}
being resized to be just large enough to hold the new value.  Otherwise
uninitialized elements are set to zero.  If the value of
@code{resize_on_range_error} is @code{"false"}, an error message is
printed and control is returned to the top level.  The default value is
@code{"true"}.

@item return_last_computed_value
If the value of @code{return_last_computed_value} is true, and a
function is defined without explicitly specifying a return value, the
function will return the value of the last expression.  Otherwise, no
value will be returned.  The default value is @code{"false"}.

For example, the function

@example
function f ()
  2 + 2;
endfunction
@end example

@noindent
will either return nothing, if @code{return_last_computed_value} is
@code{"false"}, or 4, if it is @code{"true"}.

@item save_precision
This variable specifies the number of digits to keep when saving data
with the @code{save} command.  The default value is 17.

@item silent_functions
If the value of @code{silent_functions} is @code{"true"}, internal output
from a function is suppressed.  Otherwise, the results of expressions
within a function body that are not terminated with a semicolon will
have their values printed.  The default value is @code{"false"}.

For example, if the function

@example
function f ()
  2 + 2
endfunction
@end example

@noindent
is executed, Octave will either print @samp{ans = 4} or nothing
depending on the value of @code{silent_functions}.

@item split_long_rows
For large matrices, Octave may not be able to display all the columns of
a given row on one line of your screen.  This can result in missing
information or output that is nearly impossible to decipher, depending
on whether your terminal truncates or wraps long lines.

If the value of @code{split_long_rows} is @code{"true"}, Octave will
display the matrix in a series of smaller pieces, each of which can fit
within the limits of your terminal width.  Each set of rows is labeled
so that you can easily see which columns are currently being displayed.
For example:

@smallexample
octave:13> rand (2, 9)
ans =

 Columns 1 through 7:

   0.92205  0.72628  0.99841  0.62590  0.82422  0.77486  0.30258
   0.15999  0.79484  0.75443  0.86995  0.91430  0.23980  0.64591

 Columns 8 and 9:

  0.08894  0.13266
  0.28008  0.65575
@end smallexample

The default value of @code{split_long_rows} is @code{"true"}.

@item suppress_verbose_help_message
If the value of @code{suppress_verbose_help_message} is @code{"true"},
Octave will not add additional help information to the end of the output
from the @code{help} command and usage messages for built-in commands.

@item treat_neg_dim_as_zero
If the value of @code{treat_neg_dim_as_zero} is @code{"true"}, expressions
like

@example
eye (-1)
@end example

@noindent
produce an empty matrix (i.e., row and column dimensions are zero).
Otherwise, an error message is printed and control is returned to the
top level.  The default value is @code{"false"}.

@item warn_assign_as_truth_value
If the value of @code{warn_assign_as_truth_value} is @code{"true"}, a
warning is issued for statements like

@example
if (s = t)
  ...
@end example

@noindent
since such statements are not common, and it is likely that the intent
was to write

@example
if (s == t)
  ...
@end example

@noindent
instead.

There are times when it is useful to write code that contains
assignments within the condition of a @code{while} or @code{if}
statement.  For example, statements like

@example
while (c = getc())
  ...
@end example

@noindent
are common in C programming.

It is possible to avoid all warnings about such statements by setting
@code{warn_assign_as_truth_value} to @code{"false"}, but that may also
let real errors like

@example
if (x = 1)  # intended to test (x == 1)!
  ...
@end example

@noindent
slip by.

In such cases, it is possible suppress errors for specific statements by
writing them with an extra set of parentheses.  For example, writing the
previous example as

@example
while ((c = getc()))
  ...
@end example

@noindent
will prevent the warning from being printed for this statement, while
allowing Octave to warn about other assignments used in conditional
contexts.

The default value of @code{warn_assign_as_truth_value} is @code{"true"}.

@item warn_comma_in_global_decl
If the value of @code{warn_comma_in_global_decl} is @code{"true"}, a
warning is issued for statements like

@example
global a = 1, b
@end example

@noindent
which makes the variables @samp{a} and @samp{b} global and assigns the
value 1 to the variable @samp{a}, because in this context, the comma is
not interpreted as a statement separator.

The default value of @code{warn_comma_in_global_decl} is @code{"true"}.

@item warn_divide_by_zero
If the value of @code{warn_divide_by_zero} is @code{"true"}, a warning
is issued when Octave encounters a division by zero.  If the value is
@code{"false"}, the warning is omitted.  The default value is
@code{"true"}.

@item warn_function_name_clash
If the value of @code{warn_function_name_clash} is @code{"true"}, a
warning is issued when Octave finds that the name of a function defined
in a function file differs from the name of the file.  If the value is
@code{"false"}, the warning is omitted.  The default value is
@code{"true"}.

@item whitespace_in_literal_matrix
This variable allows some control over how Octave decides to convert
spaces to commas and semicolons in matrix expressions like
@samp{[m (1)]} or

@example
[ 1, 2,
  3, 4 ]
@end example

If the value of @code{whitespace_in_literal_matrix} is @code{"ignore"},
Octave will never insert a comma or a semicolon in a literal matrix
list.  For example, the expression @samp{[1 2]} will result in an error
instead of being treated the same as @samp{[1, 2]}, and the expression

@example
[ 1, 2,
  3, 4 ]
@end example

@noindent
will result in the vector [1 2 3 4] instead of a matrix.

If the value of @code{whitespace_in_literal_matrix} is @code{"traditional"},
Octave will convert spaces to a comma between identifiers and @samp{(}.  For
example, given the matrix

@example
m = [3 2]
@end example

@noindent
the expression

@example
[m (1)]
@end example

@noindent
will be parsed as

@example
[m, (1)]
@end example

@noindent
and will result in

@example
[3 2 1]
@end example

@noindent
and the expression

@example
[ 1, 2,
  3, 4 ]
@end example

@noindent
will result in a matrix because the newline character is converted to a
semicolon (row separator) even though there is a comma at the end of the
first line (trailing commas or semicolons are ignored).  This is
apparently how @sc{Matlab} behaves.

Any other value for @code{whitespace_in_literal_matrix} results in behavior
that is the same as traditional, except that Octave does not
convert spaces to a comma between identifiers and @samp{(}.  For
example, the expression

@example
[m (1)]
@end example

will produce @samp{3}.  This is the way Octave has always behaved.
@end vtable

@node Other Built-in Variables, Summary of Preference Variables, User Preferences, Built-in Variables
@section Other Built-in Variables

In addition to these variables, there are two other special built-in
variables whose values are automatically updated.

@vtable @code
@item ans
This variable holds the most recently computed result that was not
explicitly assigned to a variable.  For example, after the expression

@example
3^2 + 4^2
@end example

@noindent
is evaluated, the value of @code{ans} is @samp{25}.

@item PWD
The current working directory.  The value of @code{PWD} is updated each
time the current working directory is changed with the @samp{cd}
command.  @xref{System Utilities}.
@end vtable

@node Summary of Preference Variables,  , Other Built-in Variables, Built-in Variables
@section Summary of Preference Variables

Here is a summary of all of Octave's preference variables and their
default values.  In the following table @code{OCTAVE_HOME} stands for
the root directory where Octave is installed, and @code{VERSION} stands
for the Octave version number.

@smallexample
EDITOR                        EDITOR environment variable, or "vi"
INFO_FILE                     "OCTAVE_HOME/info/octave.info"
LOADPATH                      OCTAVE_PATH environment variable, or
                              ".:OCTAVE_HOME/lib/VERSION"
PAGER                         "less", or "more"
PS1                           "\s:\#> "
PS2                           "> "
PS4                           "+ "
automatic_replot              "false"
default_return_value          []
do_fortran_indexing           "false"
define_all_return_values      "false"
empty_list_elements_ok        "warn"
gnuplot_binary                "gnuplot"
ignore_function_time_stamp    "system"
implicit_str_to_num_ok        "false"
ok_to_lose_imaginary_part     "warn"
output_max_field_width        10
output_precision              5
page_screen_output            "true"
prefer_column_vectors         "false"
prefer_zero_one_indexing      "false"
print_answer_id_name          "true"
print_empty_dimensions        "true"
@c read_only_constants           "true"
resize_on_range_error         "true"
return_last_computed_value    "false"
save_precision                17
silent_functions              "false"
split_long_rows               "true"
suppress_verbose_help_message "true"
treat_neg_dim_as_zero         "false"
warn_assign_as_truth_value    "true"
warn_comma_in_global_decl     "true"
warn_divide_by_zero           "true"
warn_function_name_clash      "true"
whitespace_in_literal_matrix  ""
@end smallexample

@c XXX FIXME XXX Might be nice to have a list of the settings required
@c to have Octave behave as much like @sc{Matlab} as is possible.
