This is Info file octave.info, produced by Makeinfo-1.52 from the input
file octave.texi.

   Copyright (C) 1993 John W. Eaton.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: octave.info,  Node: Top,  Next: Acknowledgements,  Prev: (dir),  Up: (dir)



   This manual documents how to run, install and port Octave, as well as
its new features and incompatibilities, and how to report bugs.  It
corresponds to Octave version 0.74.

* Menu:

* Acknowledgements::            Thanks.
* Introduction::                A brief introduction to Octave.
* Expressions::                 Expressions.
* Statements::                  Looping and program flow control.
* Built-in Variables::          Descriptions of all built-in variables.
* Built-in Functions::          Descriptions of all built-in functions.
* Invoking Octave::             Command options supported by Octave.
* Command Line Editing::        Command history and editing.
* Installation::                How to configure, compile and install Octave.
* Trouble::                     If you have trouble installing Octave.
* Concept Index::               An item for each concept.
* Variable Index::              An item for each documented variable.
* Function Index::              An item for each documented function.

 -- The Detailed Node Listing --

Acknowledgements

* Contributors::                People who contributed to developing of Octave.

A Brief Introduction to Octave

* Getting Started::
* Running Octave::
* Simple Examples::

Expressions

* Constant Expressions::
* Matrices::
* Ranges::
* Variables::
* Index Expressions::
* Calling Functions::
* Global Variables::
* Keywords::
* Arithmetic Ops::
* Comparison Ops::
* Boolean Expressions::
* Assignment Ops::
* Increment Ops::
* Operator Precedence::

Statements

* Statement Lists::
* Declaration Statements::
* Selection Statements::
* Iteration Statements::
* Defining Functions::
* Jump Statements::

Command Line Editing

* Introduction and Notation::   Notation used in this text.
* Readline Interaction::        The minimum set of commands for editing a line.
* Readline Init File::          Customizing Readline from a user's view.

Readline Interaction

* Readline Bare Essentials::    The least you need to know about Readline.
* Readline Movement Commands::  Moving about the input line.
* Readline Killing Commands::   How to delete text, and how to get it back!
* Readline Arguments::          Giving numeric arguments to commands.

Readline Init File

* Readline Init Syntax::        Syntax for the commands in `~/.inputrc'.
* Readline Vi Mode::            Switching to `vi' mode in Readline.

Readline Init Syntax

* Commands For Moving::         Moving about the line.
* Commands For History::        Getting at previous lines.
* Commands For Text::           Commands for changing text.
* Commands For Killing::        Commands for killing and yanking.
* Numeric Arguments::           Specifying numeric arguments, repeat counts.
* Commands For Completion::     Getting Readline to do the typing for you.
* Miscellaneous Commands::      Other miscellaneous commands.

Installing Octave

* Binary Distributions::

Binary Distributions

* Installing Octave from a Binary Distribution::
* Creating a Binary Distribution::

Known Causes of Trouble with Octave

* Actual Bugs::                 Bugs we will fix later.
* Installation Problems::       Problems that manifest when you install Octave.
* Disappointments::             Regrettable things we can't change.
* Reporting Bugs::
* Bug Criteria::
* Bug Lists::
* Bug Reporting::
* Sending Patches::
* Service::

Reporting Bugs

* Bug Criteria::
* Where: Bug Lists.             Where to send your bug report.
* Reporting: Bug Reporting.     How to report a bug effectively.
* Patches: Sending Patches.     How to send a patch for Octave.


File: octave.info,  Node: Acknowledgements,  Next: Introduction,  Prev: Top,  Up: Top

Acknowledgements
****************

* Menu:

* Contributors::                People who contributed to developing of Octave.


File: octave.info,  Node: Contributors,  Up: Acknowledgements

Contributors to Octave
======================

   In addition to John W. Eaton, several people have written parts of
Octave.

   * John Campbell (jcc@che.utexas.edu) wrote most of the file and
     C-style input and output functions.

   * Bruce Tenison (Bruce.Tenison@eng.auburn.edu) wrote the `hess' and
     `schur' functions.

   * Fook Fah Yap (ffy@eng.cam.ac.uk) provided the `fft' and `ifft'
     functions.

   * Brian Fox (bfox@gnu.ai.mit.edu) wrote the readline library used for
     command history editing, and the portion of this manual that
     documents it.

   Special thanks to the following people and organizations for
supporting the development of Octave:

   * Digital Equipment Corporation, for an equipment grant as part of
     their External Research Program.

   * Sun Microsystems, Inc., for an Academic Equipment grant.

   * The University of Texas College of Engineering, for providing a
     Challenge for Excellence Research Supplement, and for providing an
     Academic Development Funds grant.

   * Texaco Chemical Company, for providing funding to continue the
     development of this software.

   * Noel Bell, Senior Engineer, Texaco Chemical Company, Austin Texas.

   * James B. Rawlings, Associate Professor, Department of Chemical
     Engineering, The University of Texas at Austin.

   Portions of this document have been adapted from the GAWK, readline,
and GCC manuals, published by the Free Software Foundation, 675 Mass
Ave, Cambridge, MA 02139, USA.

   This project would not have been possible without the GNU software
used in and used to produce Octave.


File: octave.info,  Node: Introduction,  Next: Expressions,  Prev: Acknowledgements,  Up: Top

A Brief Introduction to Octave
******************************

   This manual will eventually document how to run, install and port
Octave, and how to report bugs.

   This document corresponds to Octave version 0.74.

* Menu:

* Getting Started::
* Running Octave::
* Simple Examples::


File: octave.info,  Node: Getting Started,  Next: Running Octave,  Up: Introduction

Getting Started
===============


File: octave.info,  Node: Running Octave,  Next: Simple Examples,  Prev: Getting Started,  Up: Introduction

Running Octave
==============


File: octave.info,  Node: Simple Examples,  Prev: Running Octave,  Up: Introduction

Simple Examples
===============


File: octave.info,  Node: Expressions,  Next: Statements,  Prev: Introduction,  Up: Top

Expressions
***********

   Expressions are the basic building block of statements in Octave.  An
expression evaluates to a value, which you can print, test, store in a
variable, pass to a function, or assign a new value to a variable with
an assignment operator.

   An expression can serve as a statement on its own.  Most other kinds
of statements contain one or more expressions which specify data to be
operated on.  As in other languages, expressions in Octave include
variables, array references, constants, and function calls, as well as
combinations of these with various operators.

* Menu:

* Constant Expressions::
* Matrices::
* Ranges::
* Variables::
* Index Expressions::
* Calling Functions::
* Global Variables::
* Keywords::
* Arithmetic Ops::
* Comparison Ops::
* Boolean Expressions::
* Assignment Ops::
* Increment Ops::
* Operator Precedence::


File: octave.info,  Node: Constant Expressions,  Next: Matrices,  Up: Expressions

Constant Expressions
====================

   The simplest type of expression is the "constant", which always has
the same value.  There are two types of constants: numeric constants and
string constants.

Numeric Constants
-----------------

   A "numeric constant" may be a scalar, a vector, or a matrix, and it
may contain complex values.

   The simplest form of a numeric constant, a scalar, is a single number
that can be an integer, a decimal fraction, a number in scientific
(exponential) notation, or a complex number.  Note that all numeric
values are represented within Octave in double-precision floating point
format (complex constants are stored as pairs of double-precision
floating point values).  Here are some examples of real-valued numeric
constants, which all have the same value:

     105
     1.05e+2
     1050e-1

   To specify complex constants, you can write an expression of the form

     3 + 4i
     3.0 + 4.0i
     0.3e1 + 40e-1i

   all of which are equivalent.  The letter `i' in the previous example
stands for the pure imaginary constant, defined as   `sqrt (-1)'.

   For Octave to recognize a value as the imaginary part of a complex
constant, a space must not appear between the number and the `i'.  If
it does, Octave will print an error message, like this:

     octave:13> 3 + 4 i
     
     parse error:
     
       3 + 4 i
             ^

   You may also use `j', `I', or `J' in place of the `i' above.  All
four forms are equivalent.

String Constants
----------------

   A "string constant" consists of a sequence of characters enclosed in
either double-quote or single-quote marks.  For example, both of the
following expressions

     "parrot"
     'parrot'

represent the string whose contents are `parrot'.  Strings in Octave
can be of any length.

   Since the single-quote mark is also used for the transpose operator
(*note Arithmetic Ops::.) but double-quote marks have no other purpose
in Octave, it is best to use double-quote marks to denote strings.

   Some characters cannot be included literally in a string constant.
You represent them instead with "escape sequences", which are character
sequences beginning with a backslash (`\').

   One use of an escape sequence is to include a double-quote
(single-quote) character in a string constant that has been defined
using double-quote (single-quote) marks.  Since a plain double-quote
would end the string, you must use `\"' to represent a single
double-quote character as a part of the string.  The backslash character
itself is another character that cannot be included normally.  You must
write `\\' to put one backslash in the string.  Thus, the string whose
contents are the two characters `"\' must be written `"\"\\"'.

   Another use of backslash is to represent unprintable characters such
as newline.  While there is nothing to stop you from writing most of
these characters directly in a string constant, they may look ugly.

   Here is a table of all the escape sequences used in `awk':

`\\'
     Represents a literal backslash, `\'.

`\"'
     Represents a literal double-quote character, `"'.

`\''
     Represents a literal single-quote character, `''.

`\a'
     Represents the "alert" character, control-g, ASCII code 7.

`\b'
     Represents a backspace, control-h, ASCII code 8.

`\f'
     Represents a formfeed, control-l, ASCII code 12.

`\n'
     Represents a newline, control-j, ASCII code 10.

`\r'
     Represents a carriage return, control-m, ASCII code 13.

`\t'
     Represents a horizontal tab, control-i, ASCII code 9.

`\v'
     Represents a vertical tab, control-k, ASCII code 11.

   Strings may be concatenated using the notation for defining matrices.
For example, the expression

     [ "foo" , "bar" , "baz" ]

produces the string whose contents are `foobarbaz'


File: octave.info,  Node: Matrices,  Next: Ranges,  Prev: Constant Expressions,  Up: Expressions

Matrices
========


File: octave.info,  Node: Ranges,  Next: Variables,  Prev: Matrices,  Up: Expressions

Ranges
======

   A "range" is a convenient way to write a row vector with evenly
spaced elements.  A range constant is defined by the value of the first
element in the range, a maximum value which the elements of the range
will not exceed, and an optional value for the increment between
elements.  The base, limit, and increment are separated by colons (the
`:' character) and may contain any arithmetic expressions and function
calls.  If the increment is omitted, it is assumed to be 1.  For
example,

     1 : 5

defines the set of values `[ 1 2 3 4 5 ]', and the range

     1 : 3 : 5

defines the set of values `[ 1 4 ]'.

   The increment is specified between the base and the limit in order to
be compatible with Matlab.

   Note that the upper bound on the range is not always included in the
set of values, and that ranges defined by floating point values can
produce surprising results because Octave uses floating point
arithmetic to compute the values in the range.  If it is important to
include the endpoints of a range and the number of elements is known,
you should use the `linspace' function instead *Note Built-in
Functions::.


File: octave.info,  Node: Variables,  Next: Index Expressions,  Prev: Ranges,  Up: Expressions

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.  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".  *Note Assignment
Expressions: Assignment Ops.

   A number of variables have special built-in meanings, such as `PWD',
which holds the current working directory, and `pi', the ratio of the
circumference of a circle to its diameter.  *Note Built-in Variables::,
for a list of them.  Most of these built-in variables can be used and
assigned just like all other variables, but their values are also used
or changed automatically by Octave.

   Variables in Octave can be assigned either numeric or string values.
Variables may not be used before they have been given a value.  Doing so
results in an error.


File: octave.info,  Node: Index Expressions,  Next: Calling Functions,  Prev: Variables,  Up: Expressions

Index Expressions
=================


File: octave.info,  Node: Calling Functions,  Next: Global Variables,  Prev: Index Expressions,  Up: Expressions

Calling Functions
=================

   A "function" is a name for a particular calculation.  Because it has
a name, you can ask for it by name at any point in the program.  For
example, the function `sqrt' computes the square root of a number.

   A fixed set of functions are "built-in", which means they are
available in every Octave program.  The `sqrt' function is one of
these.  *Note Built-in Functions::, for a list of built-in functions and
their descriptions.  In addition, you can define your own functions in
the program for use elsewhere in the same program.  *Note Defining
Functions::, for how to do this.

   The way to use a function is with a "function call" expression,
which consists of the function name followed by a list of "arguments"
in parentheses. The arguments are expressions which give the raw
materials for the calculation that the function will do.  When there is
more than one argument, they are separated by commas.  If there are no
arguments, write just `()' after the function name (1).  Here are some
examples:

     sqrt (x^2 + y^2)      # One argument
     ones (n, m)           # Two arguments
     rand ()               # No arguments

   Each function expects a particular number of arguments.  For
example, the `sqrt' function must be called with a single argument, the
number to take the square root of:

     sqrt (ARGUMENT)

   Some of the built-in functions take a variable number of arguments,
depending on the particular usage, and their behavior is different
depending on the number of arguments supplied.

   Like every other expression, the function call has a value, which is
computed by the function based on the arguments you give it.  In this
example, the value of `sqrt (ARGUMENT)' is the square root of the
argument.  A function can also have side effects, such as assigning the
values of certain variables or doing input or output operations.

   Unlike most languages, functions in Octave may return multiple
values.

   ---------- Footnotes ----------

   (1)  You can omit the parenthesis for functions that do not require
any arguments, but it is a good idea to include them anyway, to clearly
indicate that a function call was intended.


File: octave.info,  Node: Global Variables,  Next: Keywords,  Prev: Calling Functions,  Up: Expressions

Global Variables
================

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

     octave:1> function f (x)
     > x = 3
     > end
     octave:2> global x = 0
     octave:3> x              # This is the value of the global variable.
     x = 0
     octave:4> f (x)
     x = 3                    # The value of the local variable x is 3.
     octave:5> x              # But it was a *copy* so the global variable
     x = 0                    # remains unchanged.


File: octave.info,  Node: Keywords,  Next: Arithmetic Ops,  Prev: Global Variables,  Up: Expressions

Keywords
========

   The following identifiers are keywords, and may not be used as
variable or function names:

     break       endfor         function    return
     continue    endfunction    global      while
     else        endif          gplot
     elseif      endwhile       gsplot
     end         for            if

   The following text-style functions are also keywords, and may not be
used as variable or function names:

     casesen     document       history     set
     cd          edit           load        show
     clear       help           ls          who
     dir         format         save


File: octave.info,  Node: Arithmetic Ops,  Next: Comparison Ops,  Prev: Keywords,  Up: Expressions

Arithmetic Operators
====================

   The arithmetic operators in Octave are:

`X + Y'
     Addition.

`X .+ Y'
     Element by element addition.  This operator is equivalent to `+'.

`X - Y'
     Subtraction.

`X .- Y'
     Element by element subtraction.  This operator is equivalent to
     `-'.

`X * Y'
     Matrix multiplication.

`X .* Y'
     Element by element multiplication.

`X / Y'
     Right division.

`X ./ Y'
     Element by element right division.

`X \ Y'
     Left division.

`X .\ Y'
     Element by element left division.

`X ^ Y'
`X ** Y'
     Power operator.

`X .^ Y'
`X .** Y'
     Element by element power operator.

`-X'
     Negation.

`+X'
     Unary plus.  This operator has no effect on the operand.

`X''
     Complex conjugate transpose.

`X.''
     Transpose.


File: octave.info,  Node: Comparison Ops,  Next: Boolean Expressions,  Prev: Arithmetic Ops,  Up: Expressions

Comparison Operators
====================

   *Comparison operators* compare numeric values for relationships such
as equality.  They are written using *relational operators*, which are
a superset of those in C.

   For matrix values, they all work on an element by element basis.  For
example, evaluating the expression

     [1, 2; 3, 4] == [1, 3; 2, 4]

returns the result

     ans =
     
       1  0
       0  1

`X < Y'
     True if X is less than Y.

`X <= Y'
     True if X is less than or equal to Y.

`X == Y'
     True if X is equal to Y.

`X >= Y'
     True if X is greater than or equal to Y.

`X > Y'
     True if X is greater than Y.

`X != Y'
`X ~= Y'
`X <> Y'
     True if X is not equal to Y.

   String comparisons should be performed with the `strcmp' function,
not with the comparison operators listed above.  *Note Calling
Functions::.


File: octave.info,  Node: Boolean Expressions,  Next: Assignment Ops,  Prev: Comparison Ops,  Up: Expressions

Boolean Expressions
===================

   A "boolean expression" is a combination of comparison expressions or
matching expressions, using the boolean operators "or" (`||'), "and"
(`&&'), and "not" (`!'), along with parentheses to control nesting.
The truth of the boolean expression is computed by combining the truth
values of the component expressions.

   Boolean expressions can be used wherever comparison and matching
expressions can be used.  They can be used in `if' and `while'
statements.  They have numeric values (1 if true, 0 if false), which
come into play if the result of the boolean expression is stored in a
variable, or used in arithmetic.

   In addition, every boolean expression is also a valid boolean
pattern, so you can use it as a pattern to control the execution of
rules.

   Here are descriptions of the three boolean operators, with an
example of each.  It may be instructive to compare these examples with
the analogous examples of boolean patterns (*note Boolean
Expressions::.), which use the same boolean operators in patterns
instead of expressions.

`BOOLEAN1 & BOOLEAN2'
`BOOLEAN1 && BOOLEAN2'
     True if both BOOLEAN1 and BOOLEAN2 are true.

     The subexpression BOOLEAN2 is evaluated only if BOOLEAN1 is true.
     This can make a difference when BOOLEAN2 is an expression that has
     side effects.  For example, in the expression

          a && b++

     the value of the variable B is only incremented if A is nonzero.

`BOOLEAN1 | BOOLEAN2'
`BOOLEAN1 || BOOLEAN2'
     True if at least one of BOOLEAN1 or BOOLEAN2 is true.

     The subexpression BOOLEAN2 is evaluated only if BOOLEAN1 is false.
     This can make a difference when BOOLEAN2 is an expression that
     has side effects.

`! BOOLEAN'
`~ BOOLEAN'
     True if BOOLEAN is false.


File: octave.info,  Node: Assignment Ops,  Next: Increment Ops,  Prev: Boolean Expressions,  Up: Expressions

Assignment Expressions
======================

   An "assignment" is an expression that stores a new value into a
variable.  For example, let's assign the value 1 to the variable `z':

     z = 1

   After this expression is executed, the variable `z' has the value 1.
Whatever old value `z' had before the assignment is forgotten.

   Assignments can store string values also.  For example, this would
store the value `"this food is good"' in the variable `message':

     thing = "food"
     predicate = "good"
     message = [ "this " , thing , " is " , predicate ]

(This also illustrates concatenation of strings.)

   The `=' sign is called an "assignment operator".  It is the simplest
assignment operator because the value of the right-hand operand is
stored unchanged.

   Most operators (addition, concatenation, and so on) have no effect
except to compute a value.  If you ignore the value, you might as well
not use the operator.  An assignment operator is different.  It does
produce a value, but even if you ignore the value, the assignment still
makes itself felt through the alteration of the variable.  We call this
a "side effect".

   The left-hand operand of an assignment need not be a variable (*note
Variables::.).  It can also be an element of a matrix (*note Index
Expressions::.) or a list of return values (*note Calling
Functions::.).  These are all called "lvalues", which means they can
appear on the left-hand side of an assignment operator.  The right-hand
operand may be any expression.  It produces the new value which the
assignment stores in the specified variable, matrix element, or list of
return values.

   It is important to note that variables do *not* have permanent types.
The type of a variable is simply the type of whatever value it happens
to hold at the moment.  In the following program fragment, the variable
`foo' has a numeric value at first, and a string value later on:

     octave:13> foo = 1
     foo = 1
     octave:13> foo = "bar"
     foo = bar

When the second assignment gives `foo' a string value, the fact that it
previously had a numeric value is forgotten.

   An assignment is an expression, so it has a value: the same value
that is assigned.  Thus, `z = 1' as an expression has the value 1.  One
consequence of this is that you can write multiple assignments together:

     x = y = z = 0

stores the value 0 in all three variables.  It does this because the
value of `z = 0', which is 0, is stored into `y', and then the value of
`y = z = 0', which is 0, is stored into `x'.

   This is also true of assignments to lists of values, so the
following is a valid expression

     [a, b, c] = [u, s, v] = svd (a)

that is exactly equivalent to

     [u, s, v] = svd (a)
     a = u
     b = s
     c = v

   In expressions like this, the number of values in each part of the
expression need not match.  Extra values on the the right or left of the
`=' sign are ignored.  For example, the expression

     [a, b, c, d] = [u, s, v] = svd (a)

is equivalent to the expression above, except that the value of the
variable `d' is left unchanged, and the expression

     [a, b] = [u, s, v] = svd (a)

is equivalent to

     [u, s, v] = svd (a)
     a = u
     b = s

   You can use an assignment anywhere an expression is called for.  For
example, it is valid to write `x != (y = 1)' to set `y' to 1 and then
test whether `x' equals 1.  But this style tends to make programs hard
to read.  Except in a one-shot program, you should rewrite it to get
rid of such nesting of assignments.  This is never very hard.


File: octave.info,  Node: Increment Ops,  Next: Operator Precedence,  Prev: Assignment Ops,  Up: Expressions

Increment Operators
===================

   *Increment operators* increase or decrease the value of a variable
by 1.

   The operator to increment a variable is written as `++'.  It may be
used to increment a variable either before or after taking its value.

   For example, to pre-increment the variable X, you would write `++X'.
This would add one to X and then return the new value of X as the
result of the expression.  It is exactly the same as the expression `X
= X + 1'.

   To post-increment a variable X, you would write `X++'.  This adds
one to the variable X, but returns the value that X had prior to
incrementing it.  For example, if X is equal to 2, the result of the
expression `X++' is 2, and the new value of X is 3.

   Here is a list of all the increment and decrement expressions.

`++X'
     This expression increments the variable X.  The value of the
     expression is the *new* value of X.  It is equivalent to the
     expression `X = X + 1'.

`--X'
     This expression decrements the variable X.  The value of the
     expression is the *new* value of X.  It is equivalent to the
     expression `X = X - 1'.

`X++'
     This expression causes the variable X to be incremented.  The
     value of the expression is the *old* value of X.

`X--'
     This expression causes the variable X to be decremented.  The
     value of the expression is the *old* value of X.


File: octave.info,  Node: Operator Precedence,  Prev: Increment Ops,  Up: Expressions

Operator Precedence
===================

   "Operator precedence" determines how operators are grouped, when
different operators appear close by in one expression.  For example,
`*' has higher precedence than `+'.  Thus, the expression `a + b * c'
means to multiply `b' and `c', and then add `a' to the product (i.e.,
`a + (b * c)').

   You can overrule the precedence of the operators by using
parentheses.  You can think of the precedence rules as saying where the
parentheses are assumed if you do not write parentheses yourself.  In
fact, it is wise to always use parentheses whenever you have an unusual
combination of operators, because other people who read the program may
not remember what the precedence is in this case.  You might forget as
well, and then you too could make a mistake.  Explicit parentheses will
help prevent any such mistake.

   When operators of equal precedence are used together, the leftmost
operator groups first, except for the assignment, and exponentiation
operators, which group in the opposite order.  Thus, the expression `a
- b + c' groups as `(a - b) + c', but the expression `a = b = c' groups
as `a = (b = c)'.

   The precedence of prefix unary operators is important when another
operator follows the operand.  For example, `-x^2' means `-(x^2)',
because `-' has lower precedence than `^'.

   Here is a table of the operators in `octave', in order of increasing
precedence.

`statement separators'
     `;', `,'.

`assignment'
     `='.  This operator groups right to left.

`logical ``or'' and ``and'''
     `|', `||', `&', `&&'.

`relational'
     `<', `<=', `==', `>=', `>', `!=', `~=', `<>'.

`colon'
     `:'.

`add, subtract'
     `+', `-'.

`multiply, divide'
     `*', `/', `\', `.\', `.*', `./'.

`transpose'
     `'', `.''

`unary plus, minus, increment, decrement, and ``not'''
     `+', `-', `++', `--', `!', `~'.

`exponentiation'
     `^', `**', `.^', `.**'.


File: octave.info,  Node: Statements,  Next: Built-in Variables,  Prev: Expressions,  Up: Top

Statements
**********

* Menu:

* Statement Lists::
* Declaration Statements::
* Selection Statements::
* Iteration Statements::
* Defining Functions::
* Jump Statements::


File: octave.info,  Node: Statement Lists,  Next: Declaration Statements,  Up: Statements

Statement Lists
===============

   A statement list is formed from a set of statements, separated by
commas, semicolons, or, in some contexts, newline characters.


File: octave.info,  Node: Declaration Statements,  Next: Selection Statements,  Prev: Statement Lists,  Up: Statements

Declaration Statements
======================

DECLARATION-STMT:
     global GLOBAL-DECL-LIST

GLOBAL-DECL-LIST:
     IDENTIFIER
     IDENTIFIER = EXPR
     GLOBAL-DECL-LIST IDENTIFIER
     GLOBAL-DECL-LIST IDENTIFIER = EXPR
     GLOBAL-DECL-LIST , IDENTIFIER
     GLOBAL-DECL-LIST , IDENTIFIER = EXPR


File: octave.info,  Node: Selection Statements,  Next: Iteration Statements,  Prev: Declaration Statements,  Up: Statements

Selection Statements
====================

   A selection statement executes one of several possible lists of
statements.

SELECTION-STATEMENT:
     if EXPR STMT-LIST ELSEIF-CLAUSE ELSE-CLAUSE endif

where the ELSEIF-CLAUSE and the ELSE-CLAUSE may be omitted.

ELSE-CLAUSE:
     else STMT-LIST

ELSEIF-CLAUSE:
     elseif EXPR STMT-LIST
     ELSEIF-CLAUSE elseif EXPR STMT-LIST

   Although it is not required, it is a good idea to surround the test
expression in parentheses to make the meaning clear.


File: octave.info,  Node: Iteration Statements,  Next: Defining Functions,  Prev: Selection Statements,  Up: Statements

Iteration Statements
====================

   An iteration statements specifies looping.

ITERATION-STMT:
     while EXPR STMT-LIST endwhile
     for IDENTIFIER = EXPR STMT-LIST endfor


File: octave.info,  Node: Defining Functions,  Next: Jump Statements,  Prev: Iteration Statements,  Up: Statements

Defining Functions
==================

   The `function' statement allows you to define your own functions.
The syntax of the `function' statement is:

FUNCTION:
     function RET-LIST IDENTIFIER ARG-LIST STMT-LIST endfunction

where the RET-LIST and ARG-LIST may be omitted.

RET-LIST:
     IDENTIFIER =
     [ IDENTIFIER-LIST ] =

ARG-LIST:
     ( )
     ( IDENTIFIER-LIST )

IDENTIFIER-LIST:
     IDENTIFIER
     IDENTIFIER-LIST IDENTIFIER


File: octave.info,  Node: Jump Statements,  Prev: Defining Functions,  Up: Statements

Jump Statements
===============

   A jump statement transfers control unconditionally.

   The `break' statement terminates execution of the innermost
enclosing loop statement.

   The `continue' statement transfers control to the end of the
innermost enclosing loop statement.  The condition controlling the
execution of loop is then tested again, and if it is not equal to zero,
the loop body is executed again.

JUMP-STMT:
     break
     continue
     return

   The `break' and `continue' statements may only be used within the
body of a loop, and the `return' statement may only be used within a
function body.


File: octave.info,  Node: Built-in Variables,  Next: Built-in Functions,  Prev: Statements,  Up: Top

Built-in Variables
******************

   Octave provides a number of predefined variables.  Some, like
`do_fortran_indexing' and `page_screen_output' change Octave's
behavior.  Others, like the constants `pi' and `Inf' are available to
make programming easier.

`I'
     A pure imaginary number, defined as   `sqrt (-1)'.

`Inf'
     Infinity.  This is the result of an operation like 1/0, or an
     operation that results in a floating point overflow.

`J'
     Another name for `I'.

`NaN'
     Not a number.  This is the result of an operation like `0/0', or
     `Inf - Inf', or any operation with a NaN.

`LOADPATH'
     A colon separated list of directories in which to search for macro
     files.  The value of `LOADPATH' overrides the environment variable
     `OCTAVE_PATH'.  *Note Installation::.

`PAGER'
     The default value is `less', or, if `less' is not available on
     your system, `more'.  *Note Installation::.

`PS1'
     The primary prompt string.  When executing interactively, Octave
     displays the primary prompt `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:

    `\t'
          The time.

    `\d'
          The date.

    `\n'
          Begins a new line by printing the equivalent of a carriage
          return followed by a line feed.

    `\s'
          The name of the program (usually just `octave').

    `\w'
          The current working directory.

    `\W'
          The basename of the current working directory.

    `\u'
          The username of the current user.

    `\h'
          The hostname.

    `\#'
          The command number of this command, counting from when Octave
          starts.

    `\!'
          The history number of this command.  This differs from `\#'
          by the number of commands in the history list when Octave
          starts.

    `\$'
          If the effective UID is 0, a #, otherwise a $.

    `\nnn'
          The character whose character code in octal is `nnn'.

    `\\'
          A backslash.

     The default value if `PS1' is `\s:\#> '.  To change it, use a
     command like

          octave:13> PS1 = '\u@\h> '

     which will result in the prompt `boris@kremvax> '.

     for the user `boris' logged in on the host `kremvax'.

`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 `PS1' at the beginning of each line after the first.
     Octave allows `PS2' to be customized in the same way as `PS1'.
     The default value of `PS2' is `> '.

`PWD'
     The current working directory.  The value of `PWD' is updated each
     time the current working directory is changed with the `cd' command
     *Note Built-in Functions::.

`SEEK_SET'
`SEEK_CUR'
`SEEK_END'
     These variables may be used as the optional third argument for the
     function `fseek'.

`ans'
     If an assignment is not explicitly specified, the result of an
     expression is assigned to `ans'.

`do_fortran_indexing'
     If the value of `do_fortran_indexing' is `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 `false'.

`empty_list_elements_ok'
     This variable controls whether Octave ignores empty matrices in a
     matrix list.

     For example, if the value of `empty_list_elements_ok' is `true',
     Octave will ignore the empty matrices in the expression

          a = [1, [], 3, [], 5]

     and the variable `a' will be assigned the value `[ 1 3 5 ]'.

     The default value is `warn'.

`eps'
     The machine precision.  More precisely, `eps' is the smallest value
     such that `1+eps' is not equal to 1.

`gnuplot_binary'
     The name of the program invoked by the plot command.  The default
     value is `gnuplot'.  *Note Installation::.

`i'
     Another name for `I'.

`implicit_str_to_num_ok'
     If the value of `implicit_str_to_num_ok' is `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 `true'.

`inf'
     Another name for `Inf'.

`j'
     Another name for `I'.

`nan'
     Another name for `NaN'.

`ok_to_lose_imaginary_part'
     If the value of `ok_to_lose_imaginary_part' is `true', implicit
     conversions of complex numbers to real numbers are allowed (for
     example, by fsolve).  If the value is `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 `warn'.

`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 `output_precision' and
     `output_max_field_width'.  Reasonable combinations can be set using
     the `format' function.  *Note Built-in Functions::.

`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 `output_precision' and
     `output_max_field_width'.  Reasonable combinations can be set using
     the `format' function.  *Note Built-in Functions::.

`page_screen_output'
     If the value of `page_screen_output' is `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 `less'--see *Note Installation::) are also
     capable of moving backward on the output.  The default value is
     `true'.

     You can choose the program to use as the pager by setting the
     variable `PAGER'.

`pi'
     The ratio of the circumference of a circle to its diameter.
     Internally, `pi' is computed as `4.0 * atan (1.0)'.

`prefer_column_vectors'
     If `prefer_column_vectors' is `true', operations like

          octave:13> for i = 1:10 a (i) = i; endfor

     (for `a' previously  undefined) produce column vectors.
     Otherwise, row vectors are preferred.  The default value is
     `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 `prefer_column_vectors'.

`prefer_zero_one_indexing'
     If the value of `prefer_zero_one_indexing' is `true', Octave will
     perform zero-one style indexing when there is a conflict with the
     normal indexing rules.  *Note Index Expressions::.  For example,
     given a matrix

          a = [1, 2, 3, 4]

     with `prefer_zero_one_indexing' is set to `true', the statement

          a ([1, 1, 1, 1])

     results in the matrix `[ 1  2  3  4 ]'.  If the value of
     `prefer_zero_one_indexing' set to `false', the result would be the
     matrix `[ 1 1 1 1 ]'.

     In the first case, Octave is selecting each element corresponding
     to a `1' in the index vector.  In the second, Octave is selecting
     the first element multiple times.

     The default value for `prefer_zero_one_indexing' is `false'.

`print_answer_id_name'
     If the value of `print_answer_id_name' is `true', variable names
     are printed along with the result.  Otherwise, only the result
     values are printed.  The default value is `true'.

`print_empty_dimensions'
     If the value of `print_empty_dimensions' is `true', the dimensions
     of empty matrices are printed along with the empty matrix symbol,
     `[]'.  For example, the expression

          octave:13> zeros (3, 0)

     will print

          ans =
          
          [](3x0)

`propagate_empty_matrices'
     If the value of `propagate_empty_matrices' is `true', functions
     like `inverse' and `svd' will return an empty matrix if they are
     given one as an argument.  The default value is `true'.  Not
     entirely correct now.  XXX FIXME XXX

`resize_on_range_error'
     If the value of `resize_on_range_error' is `true', expressions like

          octave:13> for i = 1:10 a (i) = i; endfor

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

`return_last_computed_value'
     If the value of `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
     `false'.

     For example, the function

          function f ()
            2 + 2;
          endfunction

     will either return nothing, if `return_last_computed_value' is
     `false', or 4, if it is `true'.

`silent_functions'
     If the value of `silent_functions' is `true', internal output from
     a function is suppressed.  Otherwise, the results of statements
     within a function body that are not terminated with a semicolon
     will have their values printed.  The default value is `false'.

     For example, if the function

          function f ()
            2 + 2
          endfunction

     is executed, Octave will either print `ans = 4' or nothing
     depending on the value of `silent_functions'.

`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 `split_long_rows' is `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:

          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

     The default value of `split_long_rows' is `true'.

`stdin'
`stdout'
`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.

`treat_neg_dim_as_zero'
     If the value of `treat_neg_dim_as_zero' is `true', expressions like

          octave:13> eye (-1)

     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 `false'.

`warn_comma_in_global_decl'
     If the value of `warn_comma_in_global_decl' is `true', a warning
     is issued for statements like

          octave:13> global a = 1, b

     which makes the variables `a' and `b' global and assigns the value
     1 to the variable `a', because in this context, the comma is not
     interpreted as a statement separator.

     The default value of `warn_comma_in_global_decl' is `true'.

