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: The for Statement,  Next: The break Statement,  Prev: The while Statement,  Up: Statements

The `for' Statement
===================

   The `for' statement makes it more convenient to count iterations of a
loop.  The general form of the `for' statement looks like this:

     for VAR = EXPRESSION
       BODY
     endfor

where BODY stands for any statement or list of statements, EXPRESSION
is any valid expression, and VAR may take several forms.  Usually it is
a simple variable name or an indexed variable.  If the value of
EXPRESSION is a structure, VAR may also be a list.  *Note Looping Over
Structure Elements::, below.

   The assignment expression in the `for' statement works a bit
differently than Octave's normal assignment statement.  Instead of
assigning the complete result of the expression, it assigns each column
of the expression to VAR in turn.  If EXPRESSION is either a row vector
or a scalar, the value of VAR will be a scalar each time the loop body
is executed.  If VAR is a column vector or a matrix, VAR will be a
column vector each time the loop body is executed.

   The following example shows another way to create a vector containing
the first ten elements of the Fibonacci sequence, this time using the
`for' statement:

     fib = ones (1, 10);
     for i = 3:10
       fib (i) = fib (i-1) + fib (i-2);
     endfor

This code works by first evaluating the expression `3:10', to produce a
range of values from 3 to 10 inclusive.  Then the variable `i' is
assigned the first element of the range and the body of the loop is
executed once.  When the end of the loop body is reached, the next
value in the range is assigned to the variable `i', and the loop body
is executed again.  This process continues until there are no more
elements to assign.

   Although it is possible to rewrite all `for' loops as `while' loops,
the Octave language has both statements because often a `for' loop is
both less work to type and more natural to think of.  Counting the
number of iterations is very common in loops and it can be easier to
think of this counting as part of looping rather than as something to
do inside the loop.

* Menu:

* Looping Over Structure Elements::


File: octave,  Node: Looping Over Structure Elements,  Prev: The for Statement,  Up: The for Statement

Looping Over Structure Elements
-------------------------------

   A special form of the `for' statement allows you to loop over all
the elements of a structure:

     for [ VAL, KEY ] = EXPRESSION
       BODY
     endfor

In this form of the `for' statement, the value of EXPRESSION must be a
structure.  If it is, KEY and VAL are set to the name of the element
and the corresponding value in turn, until there are no more elements.
For example,

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

will print

     key = a
     val = 1
     key = b
     val =
     
       1  2
       3  4
     
     key = c
     val = string

   The elements are not accessed in any particular order.  If you need
to cycle through the list in a particular way, you will have to use the
function `struct_elements' and sort the list yourself.

   The KEY variable may also be omitted.  If it is, the brackets are
also optional.  This is useful for cycling through the values of all the
structure elements when the names of the elements do not need to be
known.


File: octave,  Node: The break Statement,  Next: The continue Statement,  Prev: The for Statement,  Up: Statements

The `break' Statement
=====================

   The `break' statement jumps out of the innermost `for' or `while'
loop that encloses it.  The `break' statement may only be used within
the body of a loop.  The following example finds the smallest divisor
of a given integer, and also identifies prime numbers:

     num = 103;
     div = 2;
     while (div*div <= num)
       if (rem (num, div) == 0)
         break;
       endif
       div++;
     endwhile
     if (rem (num, div) == 0)
       printf ("Smallest divisor of %d is %d\n", num, div)
     else
       printf ("%d is prime\n", num);
     endif

   When the remainder is zero in the first `while' statement, Octave
immediately "breaks out" of the loop.  This means that Octave proceeds
immediately to the statement following the loop and continues
processing.  (This is very different from the `exit' statement which
stops the entire Octave program.)

   Here is another program equivalent to the previous one.  It
illustrates how the CONDITION of a `while' statement could just as well
be replaced with a `break' inside an `if':

     num = 103;
     div = 2;
     while (1)
       if (rem (num, div) == 0)
         printf ("Smallest divisor of %d is %d\n", num, div);
         break;
       endif
       div++;
       if (div*div > num)
         printf ("%d is prime\n", num);
         break;
       endif
     endwhile


File: octave,  Node: The continue Statement,  Next: The unwind_protect Statement,  Prev: The break Statement,  Up: Statements

The `continue' Statement
========================

   The `continue' statement, like `break', is used only inside `for' or
`while' loops.  It skips over the rest of the loop body, causing the
next cycle around the loop to begin immediately.  Contrast this with
`break', which jumps out of the loop altogether.  Here is an example:

     # print elements of a vector of random
     # integers that are even.
     
     # first, create a row vector of 10 random
     # integers with values between 0 and 100:
     
     vec = round (rand (1, 10) * 100);
     
     # print what we're interested in:
     
     for x = vec
       if (rem (x, 2) != 0)
         continue;
       endif
       printf ("%d\n", x);
     endfor

   If one of the elements of VEC is an odd number, this example skips
the print statement for that element, and continues back to the first
statement in the loop.

   This is not a practical example of the `continue' statement, but it
should give you a clear understanding of how it works.  Normally, one
would probably write the loop like this:

     for x = vec
       if (rem (x, 2) == 0)
         printf ("%d\n", x);
       endif
     endfor


File: octave,  Node: The unwind_protect Statement,  Next: The try Statement,  Prev: The continue Statement,  Up: Statements

The `unwind_protect' Statement
==============================

   Octave supports a limited form of exception handling modelled after
the unwind-protect form of Lisp.

   The general form of an `unwind_protect' block looks like this:

     unwind_protect
       BODY
     unwind_protect_cleanup
       CLEANUP
     end_unwind_protect

Where BODY and CLEANUP are both optional and may contain any Octave
expressions or commands.  The statements in CLEANUP are guaranteed to
be executed regardless of how control exits BODY.

   This is useful to protect temporary changes to global variables from
possible errors.  For example, the following code will always restore
the original value of the built-in variable `do_fortran_indexing' even
if an error occurs while performing the indexing operation.

     save_do_fortran_indexing = do_fortran_indexing;
     unwind_protect
       do_fortran_indexing = "true";
       elt = a (idx)
     unwind_protect_cleanup
       do_fortran_indexing = save_do_fortran_indexing;
     end_unwind_protect

   Without `unwind_protect', the value of DO_FORTRAN_INDEXING would not
be restored if an error occurs while performing the indexing operation
because evaluation would stop at the point of the error and the
statement to restore the value would not be executed.


File: octave,  Node: The try Statement,  Next: Continuation Lines,  Prev: The unwind_protect Statement,  Up: Statements

The `try' Statement
===================

   In addition to unwind_protect, Octave supports another limited form
of exception handling.

   The general form of a `try' block looks like this:

     try
       BODY
     catch
       CLEANUP
     end_try_catch

   Where BODY and CLEANUP are both optional and may contain any Octave
expressions or commands.  The statements in CLEANUP are only executed
if an error occurs in BODY.

   No warnings or error messages are printed while BODY is executing.
If an error does occur during the execution of BODY, CLEANUP can access
the text of the message that would have been printed in the builtin
constant `__error_text__'.  This is the same as `eval (TRY, CATCH)'
(which may now also use `__error_text__') but it is more efficient
since the commands do not need to be parsed each time the TRY and CATCH
statements are evaluated.

   Octave's TRY block is a very limited variation on the Lisp
condition-case form (limited because it cannot handle different classes
of errors separately).  Perhaps at some point Octave can have some sort
of classification of errors and try-catch can be improved to be as
powerful as condition-case in Lisp.


File: octave,  Node: Continuation Lines,  Prev: The try Statement,  Up: Statements

Continuation Lines
==================

   In the Octave language, most statements end with a newline character
and you must tell Octave to ignore the newline character in order to
continue a statement from one line to the next.  Lines that end with the
characters `...' or `\' are joined with the following line before they
are divided into tokens by Octave's parser.  For example, the lines

     x = long_variable_name ...
         + longer_variable_name \
         - 42

form a single statement.  The backslash character on the second line
above is interpreted a continuation character, *not* as a division
operator.

   For continuation lines that do not occur inside string constants,
whitespace and comments may appear between the continuation marker and
the newline character.  For example, the statement

     x = long_variable_name ...     % comment one
         + longer_variable_name \   % comment two
         - 42                       % last comment

is equivalent to the one shown above.

   In some cases, Octave will allow you to continue lines without
having to specify continuation characters.  For example, it is possible
to write statements like

     if (big_long_variable_name == other_long_variable_name
         || not_so_short_variable_name > 4
         && y > x)
       some (code, here);
     endif

without having to clutter up the if statement with continuation
characters.


File: octave,  Node: Functions and Scripts,  Next: Built-in Variables,  Prev: Statements,  Up: Top

Functions and Script Files
**************************

   Complicated Octave programs can often be simplified by defining
functions.  Functions can be defined directly on the command line during
interactive Octave sessions, or in external files, and can be called
just like built-in ones.

* Menu:

* Defining Functions::
* Multiple Return Values::
* Variable-length Argument Lists::
* Variable-length Return Lists::
* Returning From a Function::
* Function Files::
* Script Files::
* Dynamically Linked Functions::
* Organization of Functions::


File: octave,  Node: Defining Functions,  Next: Multiple Return Values,  Prev: Functions and Scripts,  Up: Functions and Scripts

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

   In its simplest form, the definition of a function named NAME looks
like this:

     function NAME
       BODY
     endfunction

A valid function name is like a valid variable name: a sequence of
letters, digits and underscores, not starting with a digit.  Functions
share the same pool of names as variables.

   The function BODY consists of Octave statements.  It is the most
important part of the definition, because it says what the function
should actually *do*.

   For example, here is a function that, when executed, will ring the
bell on your terminal (assuming that it is possible to do so):

     function wakeup
       printf ("\a");
     endfunction

   The `printf' statement (*note Input and Output::.) simply tells
Octave to print the string `"\a"'.  The special character `\a' stands
for the alert character (ASCII 7).  *Note String Constants::.

   Once this function is defined, you can ask Octave to evaluate it by
typing the name of the function.

   Normally, you will want to pass some information to the functions you
define.  The syntax for passing parameters to a function in Octave is

     function NAME (ARG-LIST)
       BODY
     endfunction

where ARG-LIST is a comma-separated list of the function's arguments.
When the function is called, the argument names are used to hold the
argument values given in the call.  The list of arguments may be empty,
in which case this form is equivalent to the one shown above.

   To print a message along with ringing the bell, you might modify the
`beep' to look like this:

     function wakeup (message)
       printf ("\a%s\n", message);
     endfunction

   Calling this function using a statement like this

     wakeup ("Rise and shine!");

will cause Octave to ring your terminal's bell and print the message
`Rise and shine!', followed by a newline character (the `\n' in the
first argument to the `printf' statement).

   In most cases, you will also want to get some information back from
the functions you define.  Here is the syntax for writing a function
that returns a single value:

     function RET-VAR = NAME (ARG-LIST)
       BODY
     endfunction

The symbol RET-VAR is the name of the variable that will hold the value
to be returned by the function.  This variable must be defined before
the end of the function body in order for the function to return a
value.

   For example, here is a function that computes the average of the
elements of a vector:

     function retval = avg (v)
       retval = sum (v) / length (v);
     endfunction

   If we had written `avg' like this instead,

     function retval = avg (v)
       if (is_vector (v))
         retval = sum (v) / length (v);
       endif
     endfunction

and then called the function with a matrix instead of a vector as the
argument, Octave would have printed an error message like this:

     error: `retval' undefined near line 1 column 10
     error: evaluating index expression near line 7, column 1

because the body of the `if' statement was never executed, and `retval'
was never defined.  To prevent obscure errors like this, it is a good
idea to always make sure that the return variables will always have
values, and to produce meaningful error messages when problems are
encountered.  For example, `avg' could have been written like this:

     function retval = avg (v)
       retval = 0;
       if (is_vector (v))
         retval = sum (v) / length (v);
       else
         error ("avg: expecting vector argument");
       endif
     endfunction

   There is still one additional problem with this function.  What if
it is called without an argument?  Without additional error checking,
Octave will probably print an error message that won't really help you
track down the source of the error.  To allow you to catch errors like
this, Octave provides each function with an automatic variable called
`nargin'.  Each time a function is called, `nargin' is automatically
initialized to the number of arguments that have actually been passed
to the function.  For example, we might rewrite the `avg' function like
this:

     function retval = avg (v)
       retval = 0;
       if (nargin != 1)
         error ("usage: avg (vector)");
       endif
       if (is_vector (v))
         retval = sum (v) / length (v);
       else
         error ("avg: expecting vector argument");
       endif
     endfunction

   Although Octave does not automatically report an error if you call a
function with more arguments than expected, doing so probably indicates
that something is wrong.  Octave also does not automatically report an
error if a function is called with too few arguments, but any attempt to
use a variable that has not been given a value will result in an error.
To avoid such problems and to provide useful messages, we check for both
possibilities and issue our own error message.

 - Automatic Variable: nargin
     When a function is called, this local variable is automatically
     initialized to the number of arguments passed to the function.  At
     the top level, it holds the number of command line arguments that
     were passed to Octave.

 - Automatic Variable: nargout
     When a function is called, this local variable is automatically
     initialized to the number of arguments expected to be returned.
     For example,

          f ()           # nargout is 0
          [s, t] = f ()  # nargout is 2

 - Built-in Variable: silent_functions
     If the value of `silent_functions' is nonzero, internal output
     from a function is suppressed.  Otherwise, the results of
     expressions within a function body that are not terminated with a
     semicolon will have their values printed.  The default value is 0.

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

 - Built-in Variable: warn_missing_semicolon
     If the value of this variable is nonzero, Octave will warn when
     statements in function definitions don't end in semicolons.  The
     default value is 0.


File: octave,  Node: Multiple Return Values,  Next: Variable-length Argument Lists,  Prev: Defining Functions,  Up: Functions and Scripts

Multiple Return Values
======================

   Unlike many other computer languages, Octave allows you to define
functions that return more than one value.  The syntax for defining
functions that return multiple values is

     function [RET-LIST] = NAME (ARG-LIST)
       BODY
     endfunction

where NAME, ARG-LIST, and BODY have the same meaning as before, and
RET-LIST is a comma-separated list of variable names that will hold the
values returned from the function.  The list of return values must have
at least one element.  If RET-LIST has only one element, this form of
the `function' statement is equivalent to the form described in the
previous section.

   Here is an example of a function that returns two values, the maximum
element of a vector and the index of its first occurrence in the vector.

     function [max, idx] = vmax (v)
       idx = 1;
       max = v (idx);
       for i = 2:length (v)
         if (v (i) > max)
           max = v (i);
           idx = i;
         endif
       endfor
     endfunction

   In this particular case, the two values could have been returned as
elements of a single array, but that is not always possible or
convenient.  The values to be returned may not have compatible
dimensions, and it is often desirable to give the individual return
values distinct names.

   In addition to setting `nargin' each time a function is called,
Octave also automatically initializes `nargout' to the number of values
that are expected to be returned.  This allows you to write functions
that behave differently depending on the number of values that the user
of the function has requested.  The implicit assignment to the built-in
variable `ans' does not figure in the count of output arguments, so the
value of `nargout' may be zero.

   The `svd' and `lu' functions are examples of built-in functions that
behave differently depending on the value of `nargout'.

   It is possible to write functions that only set some return values.
For example, calling the function

     function [x, y, z] = f ()
       x = 1;
       z = 2;
     endfunction

as

     [a, b, c] = f ()

produces:

     a = 1
     
     b = [](0x0)
     
     c = 2

provided that the built-in variable `define_all_return_values' is
nonzero.  *Note Built-in Variables::.

 - Built-in Variable: default_return_value
     The value given to otherwise unitialized return values if
     `define_all_return_values' is nonzero.  The default value is `[]'.

 - Built-in Variable: define_all_return_values
     If the value of `define_all_return_values' is nonzero, Octave will
     substitute the value specified by `default_return_value' for any
     return values that remain undefined when a function returns.  The
     default value is 0.


File: octave,  Node: Variable-length Argument Lists,  Next: Variable-length Return Lists,  Prev: Multiple Return Values,  Up: Functions and Scripts

Variable-length Argument Lists
==============================

   Octave has a real mechanism for handling functions that take an
unspecified number of arguments, so it is not necessary to place an
upper bound on the number of optional arguments that a function can
accept.

   Here is an example of a function that uses the new syntax to print a
header followed by an unspecified number of values:

     function foo (heading, ...)
       disp (heading);
       va_start ();
       while (--nargin)
         disp (va_arg ());
       endwhile
     endfunction

   The ellipsis that marks the variable argument list may only appear
once and must be the last element in the list of arguments.

 - Built-in Function:  va_start ()
     Position an internal pointer to the first unnamed argument and
     allows you to cycle through the arguments more than once.  It is
     not necessary to call `va_start()' if you do not plan to cycle
     through the arguments more than once.  This function may only be
     called inside functions that have been declared to accept a
     variable number of input arguments.

 - Built-in Function:  va_arg ()
     Return the value of the next available argument and moves the
     internal pointer to the next argument.  It is an error to call
     `va_arg()' when there are no more arguments available.

   Sometimes it is useful to be able to pass all unnamed arguments to
another function.  The keyword ALL_VA_ARGS makes this very easy to do.
For example, given the functions

     function f (...)
       while (nargin--)
         disp (va_arg ())
       endwhile
     endfunction
     function g (...)
       f ("begin", all_va_args, "end")
     endfunction

the statement

     g (1, 2, 3)

prints

     begin
     1
     2
     3
     end

 - Keyword: all_va_args
     This keyword stands for the entire list of optional argument, so
     it is possible to use it more than once within the same function
     without having to call `va_start ()'.  It can only be used within
     functions that take a variable number of arguments.  It is an
     error to use it in other contexts.


File: octave,  Node: Variable-length Return Lists,  Next: Returning From a Function,  Prev: Variable-length Argument Lists,  Up: Functions and Scripts

Variable-length Return Lists
============================

   Octave also has a real mechanism for handling functions that return
an unspecified number of values, so it is no longer necessary to place
an upper bound on the number of outputs that a function can produce.

   Here is an example of a function that uses the new syntax to produce
N values:

     function [...] = foo (n, x)
       for i = 1:n
         vr_val (i * x);
       endfor
     endfunction

   As with variable argument lists, the ellipsis that marks the variable
return list may only appear once and must be the last element in the
list of returned values.

 - Built-in Function:  vr_val (VAL)
     Each time this function is called, it places the value of its
     argument at the end of the list of values to return from the
     current function.  Once `vr_val()' has been called, there is no
     way to go back to the beginning of the list and rewrite any of the
     return values.  This function may only be called within functions
     that have been declared to return an unspecified number of output
     arguments (by using the special ellipsis notation described above).


File: octave,  Node: Returning From a Function,  Next: Function Files,  Prev: Variable-length Return Lists,  Up: Functions and Scripts

Returning From a Function
=========================

   The body of a user-defined function can contain a `return' statement.
This statement returns control to the rest of the Octave program.  It
looks like this:

     return

   Unlike the `return' statement in C, Octave's `return' statement
cannot be used to return a value from a function.  Instead, you must
assign values to the list of return variables that are part of the
`function' statement.  The `return' statement simply makes it easier to
exit a function from a deeply nested loop or conditional statement.

   Here is an example of a function that checks to see if any elements
of a vector are nonzero.

     function retval = any_nonzero (v)
       retval = 0;
       for i = 1:length (v)
         if (v (i) != 0)
           retval = 1;
           return;
         endif
       endfor
       printf ("no nonzero elements found\n");
     endfunction

   Note that this function could not have been written using the
`break' statement to exit the loop once a nonzero value is found
without adding extra logic to avoid printing the message if the vector
does contain a nonzero element.

 - Keyword: return
     When Octave encounters the keyword return, it returns control to be
     calling function immediately.  It is only valid within a function
     and will result in an error if used at the top level.  A `return'
     statement is assumed at the end of every function definition.

 - Built-in Variable: 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 0.

     For example, the function

          function f ()
            2 + 2;
          endfunction

     will either return nothing, if `return_last_computed_value' is 0,
     or 4, if it is nonzero.


File: octave,  Node: Function Files,  Next: Script Files,  Prev: Returning From a Function,  Up: Functions and Scripts

Function Files
==============

   Except for simple one-shot programs, it is not practical to have to
define all the functions you need each time you need them.  Instead, you
will normally want to save them in a file so that you can easily edit
them, and save them for use at a later time.

   Octave does not require you to load function definitions from files
before using them.  You simply need to put the function definitions in a
place where Octave can find them.

   When Octave encounters an identifier that is undefined, it first
looks for variables or functions that are already compiled and currently
listed in its symbol table.  If it fails to find a definition there, it
searches the list of directories specified by the built-in variable
`LOADPATH' for files ending in `.m' that have the same base name as the
undefined identifier.(1)  Once Octave finds a file with a name that
matches, the contents of the file are read.  If it defines a *single*
function, it is compiled and executed.  *Note Script Files::, for more
information about how you can define more than one function in a single
file.

   When Octave defines a function from a function file, it saves the
full name of the file it read and the time stamp on the file.  After
that, it checks the time stamp on the file every time it needs the
function.  If the time stamp indicates that the file has changed since
the last time it was read, Octave reads it again.

   Checking the time stamp allows you to edit the definition of a
function while Octave is running, and automatically use the new function
definition without having to restart your Octave session.  Checking the
time stamp every time a function is used is rather inefficient, but it
has to be done to ensure that the correct function definition is used.

   Octave assumes that function files in the
`i:/apps/octave-1.90/share/octave/1.91/m' directory tree will not
change, so it doesn't have to check their time stamps every time the
functions defined in those files are used.  This is normally a very
good assumption and provides a significant improvement in performance
for the function files that are distributed with Octave.

   If you know that your own function files will not change while you
are running Octave, you can improve performance by setting the variable
`ignore_function_time_stamp' to `"all"', so that Octave will ignore the
time stamps for all function files.  Setting it to `"system"' gives the
default behavior.  If you set it to anything else, Octave will check
the time stamps on all function files.

 - Built-in Variable: LOADPATH
     A colon separated list of directories in which to search for
     function files.  *Note Functions and Scripts::.  The value of
     `LOADPATH' overrides the environment variable `OCTAVE_PATH'.
     *Note Installation::.

     `LOADPATH' is now handled in the same way as TeX handles
     `TEXINPUTS'.  If the path starts with `:', the standard path is
     prepended to the value of `LOADPATH'.  If it ends with `:' the
     standard path is appended to the value of `LOADPATH'.

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

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

     *Note Organization of Functions:: for a description of the
     function file directories that are distributed with Octave.

 - Built-in Variable: ignore_function_time_stamp
     This variable can be used to prevent Octave from making the system
     call `stat()' each time it looks up functions defined in function
     files.  If `ignore_function_time_stamp' to `"system"', Octave will
     not automatically recompile function files in subdirectories of
     `i:/apps/octave-1.90/lib/1.91' if they have changed since they
     were last compiled, but will recompile other function files in the
     `LOADPATH' if they change.  If set to `"all"', Octave will not
     recompile any function files unless their definitions are removed
     with `clear'.  For any other value of `ignore_function_time_stamp',
     Octave will always check to see if functions defined in function
     files need to recompiled.  The default value of
     `ignore_function_time_stamp' is `"system"'.

 - Built-in Variable: warn_function_name_clash
     If the value of `warn_function_name_clash' is nonzero, a warning
     is issued when Octave finds that the name of a function defined in
     a function file differs from the name of the file.  If the value is
     0, the warning is omitted.  The default value is 1.

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

   (1)  The `.m' suffix was chosen for compatibility with MATLAB.


File: octave,  Node: Script Files,  Next: Dynamically Linked Functions,  Prev: Function Files,  Up: Functions and Scripts

Script Files
============

   A script file is a file containing (almost) any sequence of Octave
commands.  It is read and evaluated just as if you had typed each
command at the Octave prompt, and provides a convenient way to perform a
sequence of commands that do not logically belong inside a function.

   Unlike a function file, a script file must *not* begin with the
keyword `function'.  If it does, Octave will assume that it is a
function file, and that it defines a single function that should be
evaluated as soon as it is defined.

   A script file also differs from a function file in that the variables
named in a script file are not local variables, but are in the same
scope as the other variables that are visible on the command line.

   Even though a script file may not begin with the `function' keyword,
it is possible to define more than one function in a single script file
and load (but not execute) all of them at once.  To do this, the first
token in the file (ignoring comments and other white space) must be
something other than `function'.  If you have no other statements to
evaluate, you can use a statement that has no effect, like this:

     # Prevent Octave from thinking that this
     # is a function file:
     
     1;
     
     # Define function one:
     
     function one ()
       ...

   To have Octave read and compile these functions into an internal
form, you need to make sure that the file is in Octave's `LOADPATH',
then simply type the base name of the file that contains the commands.
(Octave uses the same rules to search for script files as it does to
search for function files.)

   If the first token in a file (ignoring comments) is `function',
Octave will compile the function and try to execute it, printing a
message warning about any non-whitespace characters that appear after
the function definition.

   Note that Octave does not try to lookup the definition of any
identifier until it needs to evaluate it.  This means that Octave will
compile the following statements if they appear in a script file, or
are typed at the command line,

     # not a function file:
     1;
     function foo ()
       do_something ();
     endfunction
     function do_something ()
       do_something_else ();
     endfunction

even though the function `do_something' is not defined before it is
referenced in the function `foo'.  This is not an error because the
Octave does not need to resolve all symbols that are referenced by a
function until the function is actually evaluated.

   Since Octave doesn't look for definitions until they are needed, the
following code will always print `bar = 3' whether it is typed directly
on the command line, read from a script file, or is part of a function
body, even if there is a function or script file called `bar.m' in
Octave's `LOADPATH'.

     eval ("bar = 3");
     bar

   Code like this appearing within a function body could fool Octave if
definitions were resolved as the function was being compiled.  It would
be virtually impossible to make Octave clever enough to evaluate this
code in a consistent fashion.  The parser would have to be able to
perform the `eval ()' statement at compile time, and that would be
impossible unless all the references in the string to be evaluated could
also be resolved, and requiring that would be too restrictive (the
string might come from user input, or depend on things that are not
known until the function is evaluated).

 - Built-in Function:  source (FILE)
     Parse and execute the contents of FILE.  This is equivalent to
     executing commands from a script file, but without requiring the
     file ot be name FILE.m.


File: octave,  Node: Dynamically Linked Functions,  Next: Organization of Functions,  Prev: Script Files,  Up: Functions and Scripts

Dynamically Linked Functions
============================

   On some systems, Octave can dynamically load and execute functions
written in C++ or other compiled languages.  This currently only works
on systems that have a working version of the GNU dynamic linker,
`dld'. Unfortunately, `dld' does not work on very many systems, but
someone is working on making `dld' use the GNU Binary File Descriptor
library, `BFD', so that may soon change.  In any case, it should not be
too hard to make Octave's dynamic linking features work on other
systems using system-specific dynamic linking facilities.

   Here is an example of how to write a C++ function that Octave can
load.

     #include <iostream.h>
     
     #include "defun-dld.h"
     #include "tree-const.h"
     
     DEFUN_DLD ("hello", Fhello, Shello, -1, -1,
       "hello (...)\n\
     \n\
     Print greeting followed by the values of all the arguments passed.\n\
     Returns all the arguments passed.")
     {
       Octave_object retval;
       cerr << "Hello, world!\n";
       int nargin = args.length ();
       for (int i = 1; i < nargin; i++)
         retval (nargin-i-1) = args(i).eval (1);
       return retval;
     }

   Octave's dynamic linking features currently have the following
limitations.

   * Dynamic linking only works on systems that support the GNU dynamic
     linker, `dld'.

   * Clearing dynamically linked functions doesn't work.

   * Configuring Octave with `--enable-lite-kernel' seems to mostly work
     to make nonessential built-in functions dynamically loaded, but
     there also seem to be some problems.  For example, fsolve seems to
     always return `info == 3'.  This is difficult to debug since `gdb'
     won't seem to allow breakpoints to be set inside dynamically loaded
     functions.

   * Octave uses a lot of memory if the dynamically linked functions are
     compiled to include debugging symbols.  This appears to be a
     limitation with `dld', and can be avoided by not using `-g' to
     compile functions that will be linked dynamically.

   If you would like to volunteer to help improve Octave's ability to
dynamically link externally compiled functions, please contact
`bug-octave@bevo.che.wisc.edu'.


File: octave,  Node: Organization of Functions,  Prev: Dynamically Linked Functions,  Up: Functions and Scripts

Organization of Functions Distributed with Octave
=================================================

   Many of Octave's standard functions are distributed as function
files.  They are loosely organized by topic, in subdirectories of
`OCTAVE_HOME/lib/octave/VERSION/m', to make it easier to find them.

   The following is a list of all the function file subdirectories, and
the types of functions you will find there.

`control'
     Functions for design and simulation of automatic control systems.

`elfun'
     Elementary functions.

`general'
     Miscellaneous matrix manipulations, like `flipud', `rot90', and
     `triu', as well as other basic functions, like `is_matrix',
     `nargchk', etc.

`image'
     Image processing tools.  These functions require the X Window
     System.

`linear-algebra'
     Functions for linear algebra.

`miscellaneous'
     Functions that don't really belong anywhere else.

`plot'
     A set of functions that implement the MATLAB-like plotting
     functions.

`polynomial'
     Functions for manipulating polynomials.

`set'
     Functions for creating and manipulating sets of unique values.

`signal'
     Functions for signal processing applications.

`specfun'
     Special functions.

`special-matrix'
     Functions that create special matrix forms.

`startup'
     Octave's system-wide startup file.

`statistics'
     Statistical functions.

`strings'
     Miscellaneous string-handling functions.


File: octave,  Node: Built-in Variables,  Next: Arithmetic,  Prev: Functions and Scripts,  Up: Top

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

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

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

   This chapter documents the built-in variables of Octave that don't
seem to belong anywhere else.  Many more of Octave's built-in variables
are documented in the chapters that describe functions that use them,
or are affected by their values.

* Menu:

* Miscellaneous Built-in Variables::
* Summary of Preference Variables::


File: octave,  Node: Miscellaneous Built-in Variables,  Next: Summary of Preference Variables,  Prev: Built-in Variables,  Up: Built-in Variables

Miscellaneous Built-in Variables
================================

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

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

 - Built-in Variable: OCTAVE_VERSION
     The version number of Octave, as a string.

 - Built-in Variable: 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.

    `\H'
          The hostname, up to the first `.'.

    `\#'
          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 of `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.kgb.su'.  Note that two
     backslashes are required to enter a backslash into a string.
     *Note String Constants::.

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

 - Built-in Variable: PS4
     If Octave is invoked with the `--echo-input' option, the value of
     `PS4' is printed before each line of input that is echoed.  Octave
     allows `PS4' to be customized in the same way as `PS1'.  The
     default value of `PS4' is `"+ "'.  *Note Invoking Octave::, for a
     description of `--echo-input'.

 - Built-in Variable: ans
     This variable holds the most recently computed result that was not
     explicitly assigned to a variable.  For example, after the
     expression

          3^2 + 4^2

     is evaluated, the value of `ans' is `25'.

 - Built-in Variable: completion_append_char
     The value of `completion_append_char' is used as the character to
     append to successful command-line completion attempts.  The default
     value is `" "' (a single space).

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

 - Built-in Variable: print_answer_id_name
     If the value of `print_answer_id_name' is nonzero, variable names
     are printed along with the result.  Otherwise, only the result
     values are printed.  The default value is 1.

 - Built-in Variable: propagate_empty_matrices
     If the value of `propagate_empty_matrices' is nonzero, functions
     like `inverse' and `svd' will return an empty matrix if they are
     given one as an argument.  The default value is 1.  *Note Empty
     Matrices::.

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

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


File: octave,  Node: Summary of Preference Variables,  Prev: Miscellaneous Built-in Variables,  Up: Built-in Variables

Summary of Preference Variables
===============================

   Here is a summary of all of Octave's preference variables and their
default values.  In the following table `OCT_HOME' stands for the root
directory where Octave is installed, `VERSION' stands for the Octave
version number, and `SYS' stands for the type of system for which
Octave was compiled (for example, `alpha-dec-osf3.2').

     EDITOR                        "vi"
     EXEC_PATH                     ":$PATH"
     INFO_FILE                     "OCT_HOME/info/octave.info"
     INFO_PROGRAM                  "OCT_HOME/libexec/octave/VERSION/exec/SYS/info"
     LOADPATH                      ".:OCT_HOME/lib/VERSION"
     PAGER                         "less", or "more"
     PS1                           "\s:\#> "
     PS2                           "> "
     PS4                           "+ "
     automatic_replot              0
     beep_on_error                 0
     completion_append_char        " "
     default_return_value          []
     do_fortran_indexing           0
     define_all_return_values      0
     empty_list_elements_ok        "warn"
     gnuplot_binary                "gnuplot"
     history_file                  "~/.octave_hist"
     history_size                  1024
     ignore_function_time_stamp    "system"
     implicit_str_to_num_ok        0
     ok_to_lose_imaginary_part     "warn"
     output_max_field_width        10
     output_precision              5
     page_screen_output            1
     prefer_column_vectors         0
     prefer_zero_one_indexing      0
     print_answer_id_name          1
     print_empty_dimensions        1
     resize_on_range_error         1
     return_last_computed_value    0
     save_precision                17
     saving_history                1
     silent_functions              0
     split_long_rows               1
     struct_levels_to_print        2
     suppress_verbose_help_message 1
     treat_neg_dim_as_zero         0
     warn_assign_as_truth_value    1
     warn_comma_in_global_decl     1
     warn_divide_by_zero           1
     warn_function_name_clash      1
     whitespace_in_literal_matrix  ""

   The following variables may be set from the environment or by a
command line option.

     Variable        Environment Variable        Option
     --------        --------------------        ------
     EDITOR          EDITOR
     EXEC_PATH       OCTAVE_EXEC_PATH            --exec-path PATH
     LOADPATH        OCTAVE_PATH                 --path PATH
     INFO_FILE       OCTAVE_INFO_FILE            --info-file FILE
     INFO_PROGRAM    OCTAVE_INFO_PROGRAM         --info-program PROGRAM
     history_size    OCTAVE_HISTSIZE
     history_file    OCTAVE_HISTFILE


File: octave,  Node: Arithmetic,  Next: Linear Algebra,  Prev: Built-in Variables,  Up: Top

Arithmetic
**********

   Unless otherwise noted, all of the functions described in this
chapter will work for real and complex scalar or matrix arguments.

* Menu:

* Utility Functions::
* Complex Arithmetic::
* Trigonometry::
* Sums and Products::
* Special Functions::
* Mathematical Constants::

