This is Info file octave, produced by Makeinfo-1.64 from the input file
octave.tex.

START-INFO-DIR-ENTRY
* Octave: (octave).     Interactive language for numerical computations.
END-INFO-DIR-ENTRY

   Copyright (C) 1996 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,  Node: Empty Matrices,  Prev: Matrices,  Up: Matrices

Empty Matrices
--------------

   A matrix may have one or both dimensions zero, and operations on
empty matrices are handled as described by Carl de Boor in `An Empty
Exercise', SIGNUM, Volume 25, pages 2-6, 1990 and C. N. Nett and W. M.
Haddad, in `A System-Theoretic Appropriate Realization of the Empty
Matrix Concept', IEEE Transactions on Automatic Control, Volume 38,
Number 5, May 1993.  Briefly, given a scalar `s', and an M by N matrix
`M(mxn)', and an M by N empty matrix `[](mxn)' (with either one or both
dimensions equal to zero), the following are true:

     s * [](mxn) = [](mxn) * s = [](mxn)
     
         [](mxn) + [](mxn) = [](mxn)
     
         [](0xm) *  M(mxn) = [](0xn)
     
          M(mxn) * [](nx0) = [](mx0)
     
         [](mx0) * [](0xn) =  0(mxn)

   By default, dimensions of the empty matrix are printed along with the
empty matrix symbol, `[]'.  For example:

     octave:13> zeros (3, 0)
     ans =
     
     [](3x0)

   The built-in variable `print_empty_dimensions' controls this
behavior.

 - Built-in Variable: print_empty_dimensions
     If the value of `print_empty_dimensions' is nonzero, the
     dimensions of empty matrices are printed along with the empty
     matrix symbol, `[]'.  For example, the expression

          zeros (3, 0)

     will print

          ans =
          
          [](3x0)

   Empty matrices may also be used in assignment statements as a
convenient way to delete rows or columns of matrices.  *Note Assignment
Expressions: Assignment Ops.

   Octave will normally issue a warning if it finds an empty matrix in
the list of elements that make up another matrix.  You can use the
variable `empty_list_elements_ok' to suppress the warning or to treat
it as an error.

 - Built-in Variable: 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 nonzero,
     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"'.


File: octave,  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, an optional value for the increment between
elements, and a maximum value which the elements of the range will not
exceed.  The base, increment, and limit 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, the range

     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 ]'.

   Although a range constant specifies a row vector, Octave does *not*
convert range constants to vectors unless it is necessary to do so.
This allows you to write a constant like `1 : 10000' without using up
80,000 bytes of storage on a typical 32-bit workstation.

   Note that the upper (or lower, if the increment is negative) 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 Special Matrices::.).


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

   A number of variables have special built-in meanings.  For example,
`PWD' holds the current working directory, and `pi' names the ratio of
the circumference of a circle to its diameter. *Note 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.


File: octave,  Node: Index Expressions,  Next: Data Structures,  Prev: Variables,  Up: Expressions

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

   An "index expression" allows you to reference or extract selected
elements of a matrix or vector.

   Indices may be scalars, vectors, ranges, or the special operator
`:', which may be used to select entire rows or columns.

   Vectors are indexed using a single expression.  Matrices require two
indices unless the value of the built-in variable `do_fortran_indexing'
is nonzero, in which case matrices may also be indexed by a single
expression.

 - Built-in Variable: do_fortran_indexing
     If the value of `do_fortran_indexing' is nonzero, 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 0.

   Given the matrix

     a = [1, 2; 3, 4]

all of the following expressions are equivalent

     a (1, [1, 2])
     a (1, 1:2)
     a (1, :)

and select the first row of the matrix.

   A special form of indexing may be used to select elements of a
matrix or vector.  If the indices are vectors made up of only ones and
zeros, the result is a new matrix whose elements correspond to the
elements of the index vector that are equal to one.  For example,

     a = [1, 2; 3, 4];
     a ([1, 0], :)

selects the first row of the matrix `a'.

   This operation can be useful for selecting elements of a matrix
based on some condition, since the comparison operators return matrices
of ones and zeros.

   This special zero-one form of indexing leads to a conflict with the
standard indexing operation.  For example, should the following
statements

     a = [1, 2; 3, 4];
     a ([1, 1], :)

return the original matrix, or the matrix formed by selecting the first
row twice?  Although this conflict is not likely to arise very often in
practice, you may select the behavior you prefer by setting the built-in
variable `prefer_zero_one_indexing'.

 - Built-in Variable: prefer_zero_one_indexing
     If the value of `prefer_zero_one_indexing' is nonzero, 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 nonzero, the expression

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

     results in the matrix `[ 1  2  3  4 ]'.  If the value of
     `prefer_zero_one_indexing' set to 0, 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 0.

   Finally, indexing a scalar with a vector of ones can be used to
create a vector the same size as the the index vector, with each
element equal to the value of the original scalar.  For example, the
following statements

     a = 13;
     a ([1, 1, 1, 1])

produce a vector whose four elements are all equal to 13.

   Similarly, indexing a scalar with two vectors of ones can be used to
create a matrix.  For example the following statements

     a = 13;
     a ([1, 1], [1, 1, 1])

create a 2 by 3 matrix with all elements equal to 13.

   This is an obscure notation and should be avoided.  It is better to
use the function `ones' to generate a matrix of the appropriate size
whose elements are all one, and then to scale it to produce the desired
result.  *Note Special Matrices::.

 - Built-in Variable: prefer_column_vectors
     If `prefer_column_vectors' is nonzero, operations like

          for i = 1:10
            a (i) = i;
          endfor

     (for `a' previously  undefined) produce column vectors.
     Otherwise, row vectors are preferred.  The default value is 0.

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

 - Built-in Variable: resize_on_range_error
     If the value of `resize_on_range_error' is nonzero, expressions
     like

          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 0, an error message is printed and
     control is returned to the top level.  The default value is 1.


File: octave,  Node: Data Structures,  Next: Calling Functions,  Prev: Index Expressions,  Up: Expressions

Data Structures
===============

   Octave includes support for organizing data in structures.  The
current implementation uses an associative array with indices limited to
strings, but the syntax is more like C-style structures.  Here are some
examples of using data structures in Octave.

   Elements of structures can be of any value type.  For example, the
list of statements

     octave:1> x.a = 1; x.b = [1, 2; 3, 4]; x.c = "string";

creates a structure with three elements.  To print the value of the
structure, you can type its name, just as for any other variable:

     octave:2> x
     x =
     {
       a = 1
       b =
     
         1  2
         3  4
     
       c = string
     }

Note that Octave may print the elements in any order.

   Structures may be copied.

     octave:1> y = x
     y =
     {
       a = 1
       b =
     
         1  2
         3  4
     
       c = string
     }

   Since structures are themselves values, structure elements may
reference other structures.  The following statements change the value
of the element `b' of the structure `x' to be a data structure
containing the single element `d', which has a value of 3.

     octave:1> x.b.d = 3
     x.b.d = 3
     octave:2> x.b
     ans =
     {
       d = 3
     }
     octave:3> x
     x =
     {
       a = 1
       b =
       {
         d = 3
       }
     
       c = string
     }

   Note that when Octave prints the value of a structure that contains
other structures, only a few levels are displayed.  For example,

     octave:1> a.b.c.d.e = 1;
     octave:2> a
     a =
     {
       b =
       {
         c = <structure>
       }
     }

This prevents long and confusing output from large deeply nested
structures.

 - Built-in Variable: struct_levels_to_print
     You can tell Octave how many structure levels to display by
     setting the built-in variable `struct_levels_to_print'.  The
     default value is 2.

   Functions can return structures.  For example, the following function
separates the real and complex parts of a matrix and stores them in two
elements of the same structure variable.

     octave:1> function y = f (x)
     > y.re = real (x);
     > y.im = imag (x);
     > endfunction

   When called with a complex-valued argument, `f' returns the data
structure containing the real and imaginary parts of the original
function argument.

     octave:2> f (rand (3) + rand (3) * I);
     ans =
     {
       im =
     
         0.26475  0.14828
         0.18436  0.83669
     
       re =
     
         0.040239  0.242160
         0.238081  0.402523
     }

   Function return lists can include structure elements, and they may be
indexed like any other variable.  For example,

     octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4])
     x.u =
     
       -0.40455  -0.91451
       -0.91451   0.40455
     
     x.s =
     
       0.00000  0.00000  0.00000
       0.00000  5.46499  0.00000
       0.00000  0.00000  0.36597
     
     x.v =
     
       -0.57605   0.81742
       -0.81742  -0.57605

   It is also possible to cycle through all the elements of a structure
in a loop, using a special form of the `for' statement (*note The for
Statement::.)

   The following functions and variableare available to give you
information about structures.

 - Built-in Function:  is_struct (EXPR)
     Returns 1 if the value of the expression EXPR is a structure.

 - Built-in Function:  struct_contains (EXPR, NAME)
     This function returns 1 if the expression EXPR is a structure and
     it includes an element named NAME.  The first argument must be a
     structure and the second must be a string.

 - Built-in Function:  struct_elements (EXPR)
     If the expression EXPR is a structure, this function returns a
     list of strings naming the elements of the structure.  It is an
     error to call `struct_elements' with an argument that is not a
     structure.


File: octave,  Node: Calling Functions,  Next: Global Variables,  Prev: Data Structures,  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.  In addition, you can define your own functions.  *Note
Functions and Scripts::, for information about 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, you can omit the parentheses, but it is a good idea to
include them anyway, to clearly indicate that a function call was
intended.  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.  For example, the following statement

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

computes the singular value decomposition of the matrix `a' and assigns
the three result matrices to `u', `s', and `v'.

   The left side of a multiple assignment expression is itself a list of
expressions, and is allowed to be a list of variable names or index
expressions.  See also *Note Index Expressions::, and *Note Assignment
Ops::.

* Menu:

* Call by Value::
* Recursion::


File: octave,  Node: Call by Value,  Next: Recursion,  Prev: Calling Functions,  Up: Calling Functions

Call by Value
-------------

   In Octave, unlike Fortran, function arguments are passed by value,
which means that each argument in a function call is evaluated and
assigned to a temporary location in memory before being passed to the
function.  There is currently no way to specify that a function
parameter should be passed by reference instead of by value.  This
means that it is impossible to directly alter the value of function
parameter in the calling function.  It can only change the local copy
within the function body.  For example, the function

     function f (x, n)
       while (n-- > 0)
         disp (x);
       endwhile
     endfunction

displays the value of the first argument N times.  In this function,
the variable N is used as a temporary variable without having to worry
that its value might also change in the calling function.  Call by
value is also useful because it is always possible to pass constants
for any function parameter without first having to determine that the
function will not attempt to modify the parameter.

   The caller may use a variable as the expression for the argument, but
the called function does not know this: it only knows what value the
argument had.  For example, given a function called as

     foo = "bar";
     fcn (foo)

you should not think of the argument as being "the variable `foo'."
Instead, think of the argument as the string value, `"bar"'.

   Even though Octave uses pass-by-value semantics for function
arguments, values are not copied unnecessarily.  For example,

     x = rand (1000);
     f (x);

does not actually force two 1000 by 1000 element matrices to exist
*unless* the function `f' modifies the value of its argument.  Then
Octave must create a copy to avoid changing the value outside the scope
of the function `f', or attempting (and probably failing!) to modify
the value of a constant or the value of a temporary result.


File: octave,  Node: Recursion,  Prev: Call by Value,  Up: Calling Functions

Recursion
---------

   With some restrictions(1), recursive function calls are allowed.  A
"recursive function" is one which calls itself, either directly or
indirectly.  For example, here is an inefficient(2) way to compute the
factorial of a given integer:

     function retval = fact (n)
       if (n > 0)
         retval = n * fact (n-1);
       else
         retval = 1;
       endif
     endfunction

   This function is recursive because it calls itself directly.  It
eventually terminates because each time it calls itself, it uses an
argument that is one less than was used for the previous call.  Once the
argument is no longer greater than zero, it does not call itself, and
the recursion ends.

   There is currently no limit on the recursion depth, so infinite
recursion is possible.  If this happens, Octave will consume more and
more memory attempting to store intermediate values for each function
call context until there are no more resources available.  This is
obviously undesirable, and will probably be fixed in some future version
of Octave by allowing users to specify a maximum allowable recursion
depth.

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

   (1)  Some of Octave's function are implemented in terms of functions
that cannot be called recursively.  For example, the ODE solver `lsode'
is ultimiately implemented in a Fortran subroutine which cannot be
called recursively, so `lsode' should not be called either directly or
indirectly from within the user-supplied function that `lsode'
requires.  Doing so will result in undefined behavior.

   (2)  It would be much better to use `prod (1:n)', or `gamma (n+1)'
instead, after first checking to ensure that the value `n' is actually a
positive integer.


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

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 b = 2
     global c = 3, d, e = 5

   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:

     octave:1> function f (x)
     > x = 3
     > endfunction
     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.

 - Built-in Variable: warn_comma_in_global_decl
     If the value of `warn_comma_in_global_decl' is nonzero, a warning
     is issued for statements like

          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 nonzero.


File: octave,  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:

     all_va_args             endwhile
     break                   for
     catch                   function
     continue                global
     else                    gplot
     elseif                  gsplot
     end                     if
     end_try_catch           return
     end_unwind_protect      try
     endfor                  unwind_protect
     endfunction             unwind_protect_cleanup
     endif                   while

   The following command-like functions are also reserved, and may not
be used as variable or function names:

     casesen       echo          load          show
     cd            edit_history  ls            type
     chdir         format        more          which
     clear         help          run_history   who
     diary         history       save          whos
     dir           hold          set


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

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

   The following arithmetic operators are available, and work on scalars
and matrices.

`X + Y'
     Addition.  If both operands are matrices, the number of rows and
     columns must both agree.  If one operand is a scalar, its value is
     added to all the elements of the other operand.

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

`X - Y'
     Subtraction.  If both operands are matrices, the number of rows and
     columns of both must agree.

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

`X * Y'
     Matrix multiplication.  The number of columns of `x' must agree
     with the number of rows of `y'.

`X .* Y'
     Element by element multiplication.  If both operands are matrices,
     the number of rows and columns must both agree.

`X / Y'
     Right division.  This is conceptually equivalent to the expression

          (inverse (y') * x')'

     but it is computed without forming the inverse of `y''.

     If the system is not square, or if the coefficient matrix is
     singular, a minimum norm solution is computed.

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

`X \ Y'
     Left division.  This is conceptually equivalent to the expression

          inverse (x) * y

     but it is computed without forming the inverse of `x'.

     If the system is not square, or if the coefficient matrix is
     singular, a minimum norm solution is computed.

`X .\ Y'
     Element by element left division.  Each element of `y' is divided
     by each corresponding element of `x'.

`X ^ Y'
`X ** Y'
     Power operator.  If X and Y are both scalars, this operator
     returns X raised to the power Y.  If X is a scalar and Y is a
     square matrix, the result is computed using an eigenvalue
     expansion.  If X is a square matrix. the result is computed by
     repeated multiplication if Y is an integer, and by an eigenvalue
     expansion if Y is not an integer.  An error results if both X and
     Y are matrices.

     The implementation of this operator needs to be improved.

`X .^ Y'
`X .** Y'
     Element by element power operator.  If both operands are matrices,
     the number of rows and columns must both agree.

`-X'
     Negation.

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

`X''
     Complex conjugate transpose.  For real arguments, this operator is
     the same as the transpose operator.  For complex arguments, this
     operator is equivalent to the expression

          conj (x.')

`X.''
     Transpose.

   Note that because Octave's element by element operators begin with a
`.', there is a possible ambiguity for statements like

     1./m

because the period could be interpreted either as part of the constant
or as part of the operator.  To resolve this conflict, Octave treats the
expression as if you had typed

     (1) ./ m

and not

     (1.) / m

Although this is inconsistent with the normal behavior of Octave's
lexer, which usually prefers to break the input into tokens by
preferring the longest possible match at any given point, it is more
useful in this case.

 - Built-in Variable: warn_divide_by_zero
     If the value of `warn_divide_by_zero' is nonzero, a warning is
     issued when Octave encounters a division by zero.  If the value is
     0, the warning is omitted.  The default value is 1.


File: octave,  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.

   All of Octave's comparison operators return a value of 1 if the
comparison is true, or 0 if it is false.  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.

   For matrix and vector arguments, the above table should be read as
"an element of the result matrix (vector) is true if the corresponding
elements of the argument matrices (vectors) satisfy the specified
condition"

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


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

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

* Menu:

* Element-by-element Boolean Operators::
* Short-circuit Boolean Operators::


File: octave,  Node: Element-by-element Boolean Operators,  Next: Short-circuit Boolean Operators,  Prev: Boolean Expressions,  Up: Boolean Expressions

Element-by-element Boolean Operators
------------------------------------

   An "element-by-element 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 corresponding elements of
the component expressions.  A value is considered to be false if it is
zero, and true otherwise.

   Element-by-element boolean expressions can be used wherever
comparison expressions can be used.  They can be used in `if' and
`while' statements.  However, before being used in the condition of an
`if' or `while' statement, an implicit conversion from a matrix value to
a scalar value occurs using the equivalent of `all (all (X))'. That is,
a value used as the condition in an `if' or `while' statement is only
true if *all* of its elements are nonzero.

   Like comparison operations, each element of an element-by-element
boolean expression also has a numeric value (1 if true, 0 if false) that
comes into play if the result of the boolean expression is stored in a
variable, or used in arithmetic.

   Here are descriptions of the three element-by-element boolean
operators.

`BOOLEAN1 & BOOLEAN2'
     Elements of the result are true if both corresponding elements of
     BOOLEAN1 and BOOLEAN2 are true.

`BOOLEAN1 | BOOLEAN2'
     Elements of the result are true if either of the corresponding
     elements of BOOLEAN1 or BOOLEAN2 is true.

`! BOOLEAN'
`~ BOOLEAN'
     Each element of the result is true if the corresponding element of
     BOOLEAN is false.

   For matrix operands, these operators work on an element-by-element
basis.  For example, the expression

     [1, 0; 0, 1] & [1, 0; 2, 3]

returns a two by two identity matrix.

   For the binary operators, the dimensions of the operands must
conform if both are matrices.  If one of the operands is a scalar and
the other a matrix, the operator is applied to the scalar and each
element of the matrix.

   For the binary element-by-element boolean operators, both
subexpressions BOOLEAN1 and BOOLEAN2 are evaluated before computing the
result.  This can make a difference when the expressions have side
effects.  For example, in the expression

     a & b++

the value of the variable B is incremented even if the variable A is
zero.

   This behavior is necessary for the boolean operators to work as
described for matrix-valued operands.


File: octave,  Node: Short-circuit Boolean Operators,  Prev: Element-by-element Boolean Operators,  Up: Boolean Expressions

Short-circuit Boolean Operators
-------------------------------

   Combined with the implicit conversion to scalar values in `if' and
`while' conditions, Octave's element-by-element boolean operators are
often sufficient for performing most logical operations.  However, it
is sometimes desirable to stop evaluating a boolean expression as soon
as the overall truth value can be determined.  Octave's "short-circuit"
boolean operators work this way.

`BOOLEAN1 && BOOLEAN2'
     The expression BOOLEAN1 is evaluated and converted to a scalar
     using the equivalent of the operation `all (all (BOOLEAN1))'.  If
     it is false, the result of the expression is 0.  If it is true, the
     expression BOOLEAN2 is evaluated and converted to a scalar using
     the equivalent of the operation `all (all (BOOLEAN1))'.  If it is
     true, the result of the expression is 1.  Otherwise, the result of
     the expression is 0.

`BOOLEAN1 || BOOLEAN2'
     The expression BOOLEAN1 is evaluated and converted to a scalar
     using the equivalent of the operation `all (all (BOOLEAN1))'.  If
     it is true, the result of the expression is 1.  If it is false, the
     expression BOOLEAN2 is evaluated and converted to a scalar using
     the equivalent of the operation `all (all (BOOLEAN1))'.  If it is
     true, the result of the expression is 1.  Otherwise, the result of
     the expression is 0.

   The fact that both operands may not be evaluated before determining
the overall truth value of the expression can be important.  For
example, in the expression

     a && b++

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

   This can be used to write somewhat more concise code.  For example,
it is possible write

     function f (a, b, c)
       if (nargin > 2 && isstr (c))
         ...

instead of having to use two `if' statements to avoid attempting to
evaluate an argument that doesn't exist.

     function f (a, b, c)
       if (nargin > 2)
         if (isstr (c))
           ...


File: octave,  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, the following expression assigns 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, the following
expression 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.

   Assigning an empty matrix `[]' works in most cases to allow you to
delete rows or columns of matrices and vectors.  *Note Empty Matrices::.
For example, given a 4 by 5 matrix A, the assignment

     A (3, :) = []

deletes the third row of A, and the assignment

     A (:, 1:2:5) = []

deletes the first, third, and fifth columns.

   An assignment is an expression, so it has a value.  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.  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,  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.

   For matrix and vector arguments, the increment and decrement
operators work on each element of the operand.

   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.

   It is not currently possible to increment index expressions.  For
example, you might expect that the expression `V(4)++' would increment
the fourth element of the vector V, but instead it results in a parse
error.  This problem may be fixed in a future release of Octave.


File: octave,  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 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"'
     `||', `&&'.

`element-wise "or" and "and"'
     `|', `&'.

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

`colon'
     `:'.

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

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

`transpose'
     `'', `.''

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

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


File: octave,  Node: Statements,  Next: Functions and Scripts,  Prev: Expressions,  Up: Top

Statements
**********

   Statements may be a simple constant expression or a complicated list
of nested loops and conditional statements.

   "Control statements" such as `if', `while', and so on control the
flow of execution in Octave programs.  All the control statements start
with special keywords such as `if' and `while', to distinguish them
from simple expressions.  Many control statements contain other
statements; for example, the `if' statement contains another statement
which may or may not be executed.

   Each control statement has a corresponding "end" statement that
marks the end of the end of the control statement.  For example, the
keyword `endif' marks the end of an `if' statement, and `endwhile'
marks the end of a `while' statement.  You can use the keyword `end'
anywhere a more specific end keyword is expected, but using the more
specific keywords is preferred because if you use them, Octave is able
to provide better diagnostics for mismatched or missing end tokens.

   The list of statements contained between keywords like `if' or
`while' and the corresponding end statement is called the "body" of a
control statement.

* Menu:

* The if Statement::
* The while Statement::
* The for Statement::
* The break Statement::
* The continue Statement::
* The unwind_protect Statement::
* The try Statement::
* Continuation Lines::


File: octave,  Node: The if Statement,  Next: The while Statement,  Prev: Statements,  Up: Statements

The `if' Statement
==================

   The `if' statement is Octave's decision-making statement.  There are
three basic forms of an `if' statement.  In its simplest form, it looks
like this:

     if (CONDITION)
       THEN-BODY
     endif

CONDITION is an expression that controls what the rest of the statement
will do.  The THEN-BODY is executed only if CONDITION is true.

   The condition in an `if' statement is considered true if its value
is non-zero, and false if its value is zero.  If the value of the
conditional expression in an `if' statement is a vector or a matrix, it
is considered true only if *all* of the elements are non-zero.

   The second form of an if statement looks like this:

     if (CONDITION)
       THEN-BODY
     else
       ELSE-BODY
     endif

If CONDITION is true, THEN-BODY is executed; otherwise, ELSE-BODY is
executed.

   Here is an example:

     if (rem (x, 2) == 0)
       printf ("x is even\n");
     else
       printf ("x is odd\n");
     endif

   In this example, if the expression `rem (x, 2) == 0' is true (that
is, the value of `x' is divisible by 2), then the first `printf'
statement is evaluated, otherwise the second `printf' statement is
evaluated.

   The third and most general form of the `if' statement allows
multiple decisions to be combined in a single statement.  It looks like
this:

     if (CONDITION)
       THEN-BODY
     elseif (CONDITION)
       ELSEIF-BODY
     else
       ELSE-BODY
     endif

Any number of `elseif' clauses may appear.  Each condition is tested in
turn, and if one is found to be true, its corresponding BODY is
executed.  If none of the conditions are true and the `else' clause is
present, its body is executed.  Only one `else' clause may appear, and
it must be the last part of the satement.

   In the following example, if the first condition is true (that is,
the value of `x' is divisible by 2), then the first `printf' statement
is executed.  If it is false, then the second condition is tested, and
if it is true (that is, the value of `x' is divisible by 3), then the
second `printf' statement is executed.  Otherwise, the third `printf'
statement is performed.

     if (rem (x, 2) == 0)
       printf ("x is even\n");
     elseif (rem (x, 3) == 0)
       printf ("x is odd and divisible by 3\n");
     else
       printf ("x is odd\n");
     endif

   Note that the `elseif' keyword must not be spelled `else if', as is
allowed in Fortran.  If it is, the space between the `else' and `if'
will tell Octave to treat this as a new `if' statement within another
`if' statement's `else' clause.  For example, if you write

     if (C1)
       BODY-1
     else if (C2)
       BODY-2
     endif

Octave will expect additional input to complete the first `if'
statement.  If you are using Octave interactively, it will continue to
prompt you for additional input.  If Octave is reading this input from a
file, it may complain about missing or mismatched `end' statements, or,
if you have not used the more specific `end' statements (`endif',
`endfor', etc.), it may simply produce incorrect results, without
producing any warning messages.

   It is much easier to see the error if we rewrite the statements above
like this,

     if (C1)
       BODY-1
     else
       if (C2)
         BODY-2
       endif

using the indentation to show how Octave groups the statements.  *Note
Functions and Scripts::.

 - Built-in Variable: warn_assign_as_truth_value
     If the value of `warn_assign_as_truth_value' is nonzero, a warning
     is issued for statements like

          if (s = t)
            ...

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

          if (s == t)
            ...

     instead.

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

          while (c = getc())
            ...

     are common in C programming.

     It is possible to avoid all warnings about such statements by
     setting `warn_assign_as_truth_value' to 0, but that may also let
     real errors like

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

     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

          while ((c = getc()))
            ...

     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 `warn_assign_as_truth_value' is 1.


File: octave,  Node: The while Statement,  Next: The for Statement,  Prev: The if Statement,  Up: Statements

The `while' Statement
=====================

   In programming, a "loop" means a part of a program that is (or at
least can be) executed two or more times in succession.

   The `while' statement is the simplest looping statement in Octave.
It repeatedly executes a statement as long as a condition is true.  As
with the condition in an `if' statement, the condition in a `while'
statement is considered true if its value is non-zero, and false if its
value is zero.  If the value of the conditional expression in an `if'
statement is a vector or a matrix, it is considered true only if *all*
of the elements are non-zero.

   Octave's `while' statement looks like this:

     while (CONDITION)
       BODY
     endwhile

Here BODY is a statement or list of statements that we call the "body"
of the loop, and CONDITION is an expression that controls how long the
loop keeps running.

   The first thing the `while' statement does is test CONDITION.  If
CONDITION is true, it executes the statement BODY.  After BODY has been
executed, CONDITION is tested again, and if it is still true, BODY is
executed again.  This process repeats until CONDITION is no longer
true.  If CONDITION is initially false, the body of the loop is never
executed.

   This example creates a variable `fib' that contains the elements of
the Fibonacci sequence.

     fib = ones (1, 10);
     i = 3;
     while (i <= 10)
       fib (i) = fib (i-1) + fib (i-2);
       i++;
     endwhile

Here the body of the loop contains two statements.

   The loop works like this: first, the value of `i' is set to 3.
Then, the `while' tests whether `i' is less than or equal to 10.  This
is the case when `i' equals 3, so the value of the `i'-th element of
`fib' is set to the sum of the previous two values in the sequence.
Then the `i++' increments the value of `i' and the loop repeats.  The
loop terminates when `i' reaches 11.

   A newline is not required between the condition and the body; but
using one makes the program clearer unless the body is very simple.

   *Note The if Statement:: for a description of the variable
`warn_assign_as_truth_value'.

