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: Top,  Next: Preface,  Prev: (dir),  Up: (dir)



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

* Menu:

* Preface::
* Introduction::                A brief introduction to Octave.
* Invoking Octave::             Command options supported by Octave.
* Expressions::                 Expressions.
* Statements::                  Looping and program flow control.
* Functions and Scripts::
* Built-in Variables::          Descriptions of all built-in variables.
* Arithmetic::
* Linear Algebra::
* Polynomial Manipulations::
* Nonlinear Equations::
* Differential Equations::
* Optimization::
* Quadrature::
* Control Theory::
* Signal Processing::
* Sets::
* Statistics::
* Plotting::
* Image Processing::
* Audio Processing::
* Input and Output::
* Special Matrices::
* Matrix Manipulation::
* String Functions::
* System Utilities::
* Command History Functions::
* Help::
* Programming Utilities::
* Amusements::
* Emacs::
* Installation::                How to configure, compile and install Octave.
* Trouble::                     If you have trouble installing Octave.
* Command Line Editing::        Command history and editing.
* Using Info::
* Copying::                     The GNU General Public License.
* Concept Index::               An item for each concept.
* Variable Index::              An item for each documented variable.
* Function Index::              An item for each documented function.
* Operator Index::              An item for each documented operator.
* Readline Index::              An index for readline commands.
* Info Index::                  An index for info commands.


 -- The Detailed Node Listing --

A Brief Introduction to Octave

* Running Octave::
* Simple Examples::
* Comments::
* Executable Octave Programs::
* Errors::

Invoking Octave

* Command Line Options::
* Startup Files::

Expressions

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

Constant Expressions

* Numeric Constants::
* String Constants::

Matrices

* Empty Matrices::

Calling Functions

* Call by Value::
* Recursion::

Boolean Expressions

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

Statements

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

The `for' Statement

* Looping Over Structure Elements::

Functions and Script Files

* 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::

Built-in Variables

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

Arithmetic

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

Linear Algebra

* Basic Matrix Functions::
* Matrix Factorizations::
* Functions of a Matrix::

Differential Equations

* Ordinary Differential Equations::
* Differential-Algebraic Equations::

Optimization

* Quadratic Programming::
* Nonlinear Programming::
* Linear Least Squares::

Quadrature

* Functions of one Variable::
* Orthogonal Collocation::

Plotting

* Two-Dimensional Plotting::
* Three-Dimensional Plotting::
* Miscellaneous Plotting Functions::

Input and Output

* Basic Input and Output::
* C-Style I/O Functions::

Basic Input and Output

* Terminal Output::
* Terminal Input::
* Simple File I/O::

C-Style I/O Functions

* Opening and Closing Files::
* Formatted Output::
* Output Conversion Syntax::
* Table of Output Conversions::
* Integer Conversions::
* Floating-Point Conversions::
* Other Output Conversions::
* Formatted Input::
* Input Conversion Syntax::
* Table of Input Conversions::
* Numeric Input Conversions::
* String Input Conversions::
* Binary I/O::
* Other I/O Functions::

Special Matrices

* Special Utility Matrices::
* Famous Matrices::

Matrix Manipulation

* Finding Elements and Checking Conditions::
* Rearranging Matrices::

System Utilities

* Timing Utilities::
* Filesystem Utilities::
* Interacting with the OS::
* Password Database Functions::
* Group Database Functions::
* System Information::
* Other Functions::

Programming Utilities

* Evaluating Strings as Commands::
* Miscellaneous Utilities::

Using Emacs With Octave

* Setting Up Octave Mode::
* Using Octave Mode::
* Running Octave From Within Emacs::
* Using the Emacs Info Reader for Octave::

Installing Octave

* Installation Problems::
* Binary Distributions::

Binary Distributions

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

Known Causes of Trouble with Octave

* Actual Bugs::                 Bugs we will fix later.
* Reporting Bugs::
* Bug Criteria::
* Bug Lists::
* Bug Reporting::
* Sending Patches::
* Service::

Reporting Bugs

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

Command Line Editing

* Introduction and Notation::   Notation used in this text.
* Readline Interaction::        The minimum set of commands for editing a line.
* Readline Bare Essentials::
* Readline Movement Commands::
* Readline Killing Commands::
* Readline Arguments::
* Readline Init File::          Customizing Readline from a user's view.
* Readline Init Syntax::
* Readline Vi Mode::

Readline Interaction

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

Readline Init File

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

Readline Init Syntax

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

Using Info

* Cursor Commands::
* Scrolling Commands::
* Node Commands::
* Searching Commands::
* Xref Commands::
* Window Commands::
* Printing Nodes::
* Other Info Commands::
* Info Variables::

Using Info

* Cursor Commands::         Commands which move the cursor within a node.
* Scrolling Commands::      Commands for moving the node around in a window.
* Node Commands::           Commands for selecting a new node.
* Searching Commands::      Commands for searching an info file.
* Xref Commands::           Commands for selecting cross references.
* Window Commands::         Commands which manipulate multiple windows.
* Printing Nodes::          How to print out the contents of a node.
* Other Info Commands::     A few commands that defy categories.
* Info Variables::          How to change the default behavior of Info.

Selecting Cross References

* Parts of an Xref::            What a cross reference is made of.
* Selecting Xrefs::             Commands for selecting menu or note items.

Manipulating Multiple Windows

* The Mode Line::               What appears in the mode line?
* Basic Windows::               Manipulating windows in Info.
* The Echo Area::               Used for displaying errors and reading input.


File: octave,  Node: Preface,  Next: Introduction,  Prev: Top,  Up: Top

Preface
*******

   Octave was originally intended to be companion software for an
undergraduate-level textbook on chemical reactor design being written by
James B. Rawlings of the University of Wisconsin-Madison and John G.
Ekerdt of the University of Texas.

   Clearly, Octave is now much more than just another `courseware'
package with limited utility beyond the classroom.  Although our
initial goals were somewhat vague, we knew that we wanted to create
something that would enable students to solve realistic problems, and
that they could use for many things other than chemical reactor design
problems.

   There are those who would say that we should be teaching the students
Fortran instead, because that is the computer language of engineering,
but every time we have tried that, the students have spent far too much
time trying to figure out why their Fortran code crashes and not enough
time learning about chemical engineering.  With Octave, most students
pick up the basics quickly, and are using it confidently in just a few
hours.

   Although it was originally intended to be used to teach reactor
design, it has been used in several other undergraduate and graduate
courses in the Chemical Engineering Department at the University of
Texas, and the math department at the University of Texas has been using
it for teaching differential equations and linear algebra as well.  If
you find it useful, please let us know.  We are always interested to
find out how Octave is being used in other places.

   Virtually everyone thinks that the name Octave has something to do
with music, but it is actually the name of a former professor of mine
who wrote a famous textbook on chemical reaction engineering, and who
was also well known for his ability to do quick `back of the envelope'
calculations.  We hope that this software will make it possible for many
people to do more ambitious computations just as easily.

   Everyone is encouraged to share this software with others under the
terms of the GNU General Public License (*note Copying::.) as described
at the beginning of this manual.  You are also encouraged to help make
Octave more useful by writing and contributing additional functions for
it, and by reporting any problems you may have.

   Many people have already contributed to Octave's development.  In
addition to John W. Eaton, the following people have helped write parts
of Octave or helped out in various other ways.

   * Thomas Baier (baier@ci.tuwien.ac.at) wrote the original versions of
     `popen', `pclose', `execute', `sync_system', and `async_system'.

   * Karl Berry (karl@cs.umb.edu) wrote the `kpathsea' library that
     allows Octave to recursively search directory paths for function
     and script files.

   * Georg Beyerle (gbeyerle@awi-potsdam.de) contributed code to save
     values in MATLAB's `.mat'-file format, and has provided many
     useful bug reports and suggestions.

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

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

   * Klaus Gebhardt <gebhardt@crunch.ikp.physik.th-darmstadt.de> ported
     Octave to OS/2.

   * A. Scottedward Hodel (scotte@eng.auburn.edu) contributed a number
     of functions including `expm', `qzval', `qzhess', `syl', `lyap',
     and `balance'.

   * Kurt Hornik (Kurt.Hornik@ci.tuwien.ac.at) provided the `corrcoef',
     `cov', `fftconv', `fftfilt', `gcd', `lcd', `kurtosis', `null',
     `orth', `poly', `polyfit', `roots', and `skewness' functions,
     supplied documentation for these and numerous other functions,
     rewrote the Emacs mode for editing Octave code and provided its
     documentation, and has helped tremendously with testing.  He has
     also been a constant source of new ideas for improving Octave.

   * Phil Johnson (johnsonp@nicco.sscnet.ucla.edu) has helped to make
     Linux releases available.

   * Michel Juillard <juillard@msh-paris.fr> ported Octave to DOS
     systems.

   * Friedrich Leisch (leisch@ci.tuwien.ac.at) provided the
     `mahalanobis' function.

   * Ken Neighbors (wkn@leland.stanford.edu) has provided many useful
     bug reports and comments on MATLAB compatibility.

   * Rick Niles (niles@axp745.gsfc.nasa.gov) rewrote Octave's plotting
     functions to add line styles and the ability to specify an
     unlimited number of lines in a single call.  He also continues to
     track down odd incompatibilities and bugs.

   * Mark Odegard (meo@sugarland.unocal.com) provided the initial
     implementation of `fread', `fwrite', `feof', and `ferror'.

   * Tony Richardson (tony@guts.biomed.uakron.edu) wrote Octave's image
     processing functions as well as most of the original polynomial
     functions.

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

   * Teresa Twaroch (twaroch@ci.tuwien.ac.at) provided the functions
     `gls' and `ols'.

   * Andreas Weingessel (Andreas.Weingessel@ci.tuwien.ac.at) wrote the
     audio functions `lin2mu', `loadaudio', `mu2lin', `playaudio',
     `record', `saveaudio', and `setaudio'.

   * Fook Fah Yap (ffy@eng.cam.ac.uk) provided the `fft' and `ifft'
     functions and valuable bug reports for early versions.

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

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

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

   * International Business Machines, Inc., for providing equipment as
     part of a grant to the University of Texas College of Engineering.

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

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

   * The State of Texas, for providing funding through the Texas
     Advanced Technology Program under Grant No. 003658-078.

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

   * James B. Rawlings, Professor, University of Wisconsin-Madison,
     Department of Chemical Engineering.

   * Richard Stallman, for writing GNU.

   Portions of this document have been adapted from the `gawk',
`readline', `gcc', and C library manuals, published by the Free
Software Foundation, 59 Temple Place--Suite 330, Boston, MA 02111-1307,
USA.

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


File: octave,  Node: Introduction,  Next: Invoking Octave,  Prev: Preface,  Up: Top

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

   This manual documents how to run, install and port Octave, and how
to report bugs.

   Octave is a high-level language, primarily intended for numerical
computations.  It provides a convenient command line interface for
solving linear and nonlinear problems numerically, and for performing
other numerical experiments.  It may also be used as a batch-oriented
language.

   Octave is also freely redistributable software.  You may
redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation.  The GPL
is included in this manual in *Note Copying::.

   This document corresponds to Octave version 1.91.

* Menu:

* Running Octave::
* Simple Examples::
* Comments::
* Executable Octave Programs::
* Errors::


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

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

   On most systems, the way to invoke Octave is with the shell command
`octave'.  Octave displays an initial message and then a prompt
indicating it is ready to accept input.  You can begin typing Octave
commands immediately afterward.

   If you get into trouble, you can usually interrupt Octave by typing
`Control-C' (usually written `C-c' for short).  `C-c' gets its name
from the fact that you type it by holding down the `CTRL' key and then
pressing `c'.  Doing this will normally return you to Octave's prompt.

   To exit Octave, type `quit', or `exit' at the Octave prompt.

 - Built-in Function:  exit (STATUS)
 - Built-in Function:  quit (STATUS)
     Exit the current Octave session.  If the optional integer value
     STATUS is supplied, pass that value to the operating system as the
     Octave's exit status.

   On systems that support job control, you can suspend Octave by
sending it a `SIGTSTP' signal, usually by typing `C-z'.


File: octave,  Node: Simple Examples,  Next: Comments,  Prev: Running Octave,  Up: Introduction

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

   The following chapters describe all of Octave's features in detail,
but before doing that, it might be helpful to give a sampling of some
of its capabilities.

   If you are new to Octave, I recommend that you try these examples to
begin learning Octave by using it.  Lines marked with `octave:13>' are
lines you type, ending each with a carriage return.  Octave will
respond with an answer, or by displaying a graph.

Creating a Matrix
-----------------

   To create a new matrix and store it in a variable so that it you can
refer to it later, type the command

     octave:1> a = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ]

Octave will respond by printing the matrix in neatly aligned columns.
Ending a command with a semicolon tells Octave to not print the result
of a command.  For example

     octave:2> b = rand (3, 2);

will create a 3 row, 2 column matrix with each element set to a random
value between zero and one.

   To display the value of any variable, simply type the name of the
variable.  For example, to display the value stored in the matrix `b',
type the command

     octave:3> b

Matrix Arithmetic
-----------------

   Octave has a convenient operator notation for performing matrix
arithmetic.  For example, to multiply the matrix A by a scalar value,
type the command

     octave:4> 2 * a

   To multiply the two matrices A and B, type the command

     octave:5> a * b

   To form the matrix product  `transpose (a) * a', type the command

     octave:6> a' * a

Solving Linear Equations
------------------------

   To solve the set of linear equations `Ax = b', use the left division
operator, `\':

     octave:7> a \ b

This is conceptually equivalent to inv (A) * b, but avoids computing
the inverse of a matrix directly.

   If the coefficient matrix is singular, Octave will print a warning
message and compute a minimum norm solution.

Integrating Differential Equations
----------------------------------

   Octave has built-in functions for solving nonlinear differential
equations of the form

     dx
     -- = f (x, t)
     dt

with the initial condition

     x(t = t0) = x0

For Octave to integrate equations of this form, you must first provide a
definition of the function `f(x,t)'.  This is straightforward, and may
be accomplished by entering the function body directly on the command
line.  For example, the following commands define the right hand side
function for an interesting pair of nonlinear differential equations.
Note that while you are entering a function, Octave responds with a
different prompt, to indicate that it is waiting for you to complete
your input.

     octave:8> function xdot = f (x, t)
     >
     >  r = 0.25;
     >  k = 1.4;
     >  a = 1.5;
     >  b = 0.16;
     >  c = 0.9;
     >  d = 0.8;
     >
     >  xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1));
     >  xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2);
     >
     > endfunction

Given the initial condition

     x0 = [1; 2];

and the set of output times as a column vector (note that the first
output time corresponds to the initial condition given above)

     t = linspace (0, 50, 200)';

it is easy to integrate the set of differential equations:

     x = lsode ("f", x0, t);

The function `lsode' uses the Livermore Solver for Ordinary
Differential Equations, described in A. C. Hindmarsh, `ODEPACK, a
Systematized Collection of ODE Solvers', in: Scientific Computing, R. S.
Stepleman et al. (Eds.), North-Holland, Amsterdam, 1983, pages 55-64.

Producing Graphical Output
--------------------------

   To display the solution of the previous example graphically, use the
command

     plot (t, x)

   If you are using the X Window System, Octave will automatically
create a separate window to display the plot.  If you are using a
terminal that supports some other graphics commands, you will need to
tell Octave what kind of terminal you have.  Type the command

     set term

to see a list of the supported terminal types.  Octave uses `gnuplot'
to display graphics, and can display graphics on any terminal that is
supported by `gnuplot'.

   To capture the output of the plot command in a file rather than
sending the output directly to your terminal, you can use a set of
commands like this

     set term postscript
     set output "foo.ps"
     replot

This will work for other types of output devices as well.  Octave's
`set' command is really just piped to the `gnuplot' subprocess, so that
once you have a plot on the screen that you like, you should be able to
do something like this to create an output file suitable for your
graphics printer.

   Or, you can eliminate the intermediate file by using commands like
this

     set term postscript
     set output "|lpr -Pname_of_your_graphics_printer"
     replot

Editing What You Have Typed
---------------------------

   At the Octave prompt, you can recall, edit, and reissue previous
commands using Emacs- or vi-style editing commands.  The default
keybindings use Emacs-style commands.  For example, to recall the
previous command, type `Control-P' (usually written `C-p' for short).
`C-p' gets  its name from the fact that you type it by holding down the
`CTRL' key and then pressing `p'.  Doing this will normally bring back
the previous line of input.  `C-n' will bring up the next line of
input, `C-b' will move the cursor backward on the line, `C-f' will move
the cursor forward on the line, etc.

   A complete description of the command line editing capability is
given in this manual in *Note Command Line Editing::.

Getting Help
------------

   Octave has an extensive help facility.  The same documentation that
is available in printed form is also available from the Octave prompt,
because both forms of the documentation are created from the same input
file.

   In order to get good help you first need to know the name of the
command that you want to use.  This name of the function may not always
be obvious, but a good place to start is to just type `help'.  This
will show you all the operators, reserved words, functions, built-in
variables, and function files.  You can then get more help on anything
that is listed by simply including the name as an argument to help.
For example,

     help plot

will display the help text for the `plot' function.

   Octave sends output that is too long to fit on one screen through a
pager like `less' or `more'.  Type a carriage return to advance one
line, a space character to advance one page, and `q' to exit the pager.

Help via Info
.............

   The part of Octave's help facility that allows you to read the
complete text of the printed manual from within Octave uses a program
called Info.  When you invoke Info you will be put into a menu driven
program that contains the entire Octave manual.  Help for using Info is
provided in this manual in *Note Using Info::.


File: octave,  Node: Comments,  Next: Executable Octave Programs,  Prev: Simple Examples,  Up: Introduction

Comments in Octave Programs
===========================

   A "comment" is some text that is included in a program for the sake
of human readers, and that is not really part of the program.  Comments
can explain what the program does, and how it works.  Nearly all
programming languages have provisions for comments, because programs are
typically hard to understand without them.

   In the Octave language, a comment starts with either the sharp sign
character, `#', or the percent symbol `%' and continues to the end of
the line.  The Octave interpreter ignores the rest of a line following
a sharp sign or percent symbol.  For example, we could have put the
following into the function `f':

     function xdot = f (x, t)
     
     # usage: f (x, t)
     #
     # This function defines the right-hand-side functions for a set of
     # nonlinear differential equations.
     
       r = 0.25
     
       and so on...
     
     endfunction

   The `help' command (*note Help::.) is able to find the first block
of comments in a function (even those that are composed directly on the
command line).  This means that users of Octave can use the same
commands to get help for built-in functions, and for functions that you
have defined.  For example, after defining the function `f' above, the
command

     help f

produces the output

      usage: f (x, t)
     
      This function defines the right-hand-side functions for a set of
      nonlinear differential equations.

   Although it is possible to put comment lines into keyboard-composed
throw-away Octave programs, it usually isn't very useful, because the
purpose of a comment is to help you or another person understand the
program at a later time.


File: octave,  Node: Executable Octave Programs,  Next: Errors,  Prev: Comments,  Up: Introduction

Executable Octave Programs
==========================

   Once you have learned Octave, you may want to write self-contained
Octave scripts, using the `#!' script mechanism.  You can do this on
GNU systems and on many Unix systems (1)

   For example, you could create a text file named `hello', containing
the following lines:

     #! i:/apps/octave-1.90/bin/octave -qf
     
     # a sample Octave program
     printf ("Hello, world!\n");

After making this file executable (with the `chmod' command), you can
simply type:

     hello

at the shell, and the system will arrange to run Octave (2) as if you
had typed:

     octave hello

Self-contained Octave scripts are useful when you want to write a
program which users can invoke without knowing that the program is
written in the Octave language.

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

   (1)  The `#!' mechanism works on Unix systems derived from Berkeley
Unix, System V Release 4, and some System V Release 3 systems.

   (2)  The line beginning with `#!' lists the full file name of an
interpreter to be run, and an optional initial command line argument to
pass to that interpreter.  The operating system then runs the
interpreter with the given argument and the full argument list of the
executed program.  The first argument in the list is the full file name
of the Octave program.  The rest of the argument list will either be
options to Octave, or data files, or both.  The `-qf' option is usually
specified in stand-alone Octave programs to prevent them from printing
the normal startup message, and to keep them from behaving differently
depending on the contents of a particular user's `~/.octaverc' file.
*Note Invoking Octave::.


File: octave,  Node: Errors,  Prev: Executable Octave Programs,  Up: Introduction

Errors
======

   There are two classes of errors that Octave produces when it
encounters input that it is unable to understand, or when it is unable
to perform an action.

   A "parse error" occurs if Octave cannot understand something you
have typed.  For example, if you misspell a keyword,

     octave:13> functon y = f (x) y = x^2; endfunction

Octave will respond immediately with a message like this:

     parse error:
     
       functon y = f (x) y = x^2; endfunction
               ^

For most parse errors, Octave uses a caret (`^') to mark the point on
the line where it was unable to make sense of your input.  In this
case, Octave generated an error message because the keyword `function'
was misspelled.  Instead of seeing `function f', Octave saw two
consecutive variable names, which is invalid in this context.  It
marked the error at the `y' because the first name by itself was
accepted as valid input.

   Another class of error message occurs occurs at evaluation time.
These errors are called "run-time errors", or sometimes "evaluation
errors" because they occur when your program is being "run", or
"evaluated".  For example, if after correcting the mistake in the
previous function definition, you type

     octave:13> f ()

Octave will respond with

     error: `x' undefined near line 1 column 24
     error: evaluating expression near line 1, column 24
     error: evaluating assignment expression near line 1, column 22
     error: called from `f'

   This error message has several parts, and gives you quite a bit of
information to help you locate the source of the error.  The messages
are generated from the point of the innermost error, and provide a
traceback of enclosing expressions and function calls.

   In the example above, the first line indicates that a variable named
`x' was found to be undefined near line 1 and column 24 of some
function or expression.  For errors occurring within functions, lines
from the beginning of the file containing the function definition.  For
errors occurring at the top level, the line number indicates the input
line number, which is usually displayed in the prompt string.

   The second and third lines in the example indicate that the error
occurred within an assignment expression, and the last line of the error
message indicates that the error occurred within the function `f'.  If
the function `f' had been called from another function, for example,
`g', the list of errors would have ended with one more line:

     error: called from `g'

   These lists of function calls usually make it fairly easy to trace
the path your program took before the error occurred, and to correct the
error before trying again.


File: octave,  Node: Invoking Octave,  Next: Expressions,  Prev: Introduction,  Up: Top

Invoking Octave
***************

   Normally, Octave is used interactively by running the program
`octave' without any arguments.  Once started, Octave reads commands
from the terminal until you tell it to exit.

   You can also specify the name of a file on the command line, and
Octave will read and execute the commands from the named file and then
exit when it is finished.

   You can further control how Octave starts up by using the
command-line options described in the next section, and Octave itself
can remind you of the options available.  Type

     octave --help

to display all available options and briefly describe their use
(`octave -h' is a shorter equivalent).

* Menu:

* Command Line Options::
* Startup Files::


File: octave,  Node: Command Line Options,  Next: Startup Files,  Prev: Invoking Octave,  Up: Invoking Octave

Command Line Options
====================

`--debug'
`-d'
     Enter parser debugging mode.  Using this option will cause Octave's
     parser to print a lot of information about the commands it reads,
     and is probably only useful if you are actually trying to debug
     the parser.

`--echo-commands'
`-x'
     Echo commands as they are executed.

`--exec-path PATH'
     Specify the path to search for programs to run.  The value of PATH
     specified on the command line will override any value of
     `OCTAVE_EXEC_PATH' found in the environment, but not any
     `EXEC_PATH = "path"' commands found in the system or user startup
     files.

`--help'
`-h'
`-?'
     Print short help message and exit.

`--info-file FILENAME'
     Specify the name of the info file to use.  The value of FILENAME
     specified on the command line will override any value of
     `OCTAVE_INFO_FILE' found in the environment, but not any
     `INFO_FILE = "filename"' commands found in the system or user
     startup files.

`--info-program PROGRAM'
     Specify the name of the info program to use.  The value of PROGRAM
     specified on the command line will override any value of
     `OCTAVE_INFO_PROGRAM' found in the environment, but not any
     `INFO_PROGRAM = "program"' commands found in the system or user
     startup files.

`--interactive'
`-i'
     Force interactive behavior.

`--no-init-file'
     Don't read the `~/.octaverc' or `.octaverc' files.

`--no-line-editing'
     Disable command-line editing and history.

`--no-site-file'
     Don't read the site-wide `octaverc' file.

`--norc'
`-f'
     Don't read any of the system or user initialization files at
     startup.  This is equivalent to using both of the options
     `--no-init-file' and `--no-site-file'.

`--path PATH'
`-p PATH'
     Specify the path to search for function files.  The value of PATH
     specified on the command line will override any value of
     `OCTAVE_PATH' found in the environment, but not any `LOADPATH =
     "path"' commands found in the system or user startup files.

`--silent'
`--quiet'
`-q'
     Don't print message at startup.

`--traditional'
`--braindead'
     Set initial values for user-preference variables to the following
     values for compatibility with MATLAB.

          PS1                           = ">> "
          PS2                           = ""
          beep_on_error                 = 1
          default_save_format           = "mat-binary"
          define_all_return_values      = 1
          do_fortran_indexing           = 1
          empty_list_elements_ok        = 1
          implicit_str_to_num_ok        = 1
          ok_to_lose_imaginary_part     = 1
          page_screen_output            = 0
          prefer_column_vectors         = 0
          prefer_zero_one_indexing      = 1
          print_empty_dimensions        = 0
          treat_neg_dim_as_zero         = 1
          warn_function_name_clash      = 0
          whitespace_in_literal_matrix  = "traditional"

`--verbose'
`-V'
     Turn on verbose output.

`--version'
`-v'
     Print the program version number and exit.

`FILE'
     Execute commands from FILE.

 - Built-in Variable: argv
     The command line arguments passed to Octave are available in this
     variable.  For example, if you invoked Octave using the command

          octave --no-line-editing --silent

     `argv' would be a string vector with the elements
     `--no-line-editing' and `--silent'.

 - Built-in Variable: nargin
     At the top level, this variable is defined as the number of
     command line arguments that were passed to Octave.

 - Built-in Variable: program_invocation_name
 - Built-in Variable: program_name
     When Octave starts, the value of `program_invocation_name' is
     automatically set to the name that was typed at the shell prompt
     to run Octave, and the value of `program_name' is automatically
     set to the final component of `program_invocation_name'.  For
     example, if you typed `i:/apps/octave-1.90/bin/octave' to start
     Octave, `program_invocation_name' would have the value
     `i:/apps/octave-1.90/bin/octave', and `program_name' would have the
     value `octave'.

     If executing a script from the command line (e.g., `octave foo.m'
     or using an executable Octave script, the program name is set to
     the name of the script.  *Note Executable Octave Programs:: for an
     example of how to create an executable Octave script.

   Here is an example of using these variables to reproduce Octave's
command line.

     printf ("%s", program_name);
     for i = 1:nargin
       printf (" %s", i, argv(i,:));
     endfor
     printf ("\n");

*Note Index Expressions:: for an explanation of how to properly index
arrays of strings and substrings in Octave.


File: octave,  Node: Startup Files,  Prev: Command Line Options,  Up: Invoking Octave

Startup Files
=============

   When Octave starts, it looks for commands to execute from the
following files:

`OCTAVE_HOME/share/octave/site/m/startup/octaverc'
     Where `OCTAVE_HOME' is the directory in which all of Octave is
     installed (the default is `/usr/local').  This file is provided so
     that changes to the default Octave environment can be made
     globally for all users at your site for all versions of Octave you
     have installed.  Some care should be taken when making changes to
     this file, since all users of Octave at your site will be affected.

`OCTAVE_HOME/share/octave/VERSION/m/startup/octaverc'
     Where `OCTAVE_HOME' is the directory in which all of Octave is
     installed (the default is `/usr/local'), and `VERSION' is the
     version number of Octave.  This file is provided so that changes
     to the default Octave environment can be made globally for all
     users for a particular version of Octave.  Some care should be
     taken when making changes to this file, since all users of Octave
     at your site will be affected.

`~/.octaverc'
     This file is normally used to make personal changes to the default
     Octave environment.

`.octaverc'
     This file can be used to make changes to the default Octave
     environment for a particular project.  Octave searches for this
     file in the current directory after it reads `~/.octaverc'.  Any
     use of the `cd' command in the `~/.octaverc' file will affect the
     directory that Octave searches for the file `.octaverc'.

     If you start Octave in your home directory, commands from from the
     file `~/.octaverc' will only be executed once.

   A message will be displayed as each of the startup files is read if
you invoke Octave with the `--verbose' option but without the
`--silent' option.

   Startup files may contain any valid Octave commands, including
multiple function definitions.


File: octave,  Node: Expressions,  Next: Statements,  Prev: Invoking Octave,  Up: Top

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

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

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

* Menu:

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


File: octave,  Node: Constant Expressions,  Next: Matrices,  Prev: Expressions,  Up: Expressions

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

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

* Menu:

* Numeric Constants::
* String Constants::


File: octave,  Node: Numeric Constants,  Next: String Constants,  Prev: Constant Expressions,  Up: Constant Expressions

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

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

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

     105
     1.05e+2
     1050e-1

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

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

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

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

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

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


File: octave,  Node: String Constants,  Prev: Numeric Constants,  Up: Constant Expressions

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

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

     "parrot"
     'parrot'

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

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

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

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

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

   Here is a table of all the escape sequences used in Octave.  They are
the same as those used in the C programming langauge.

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

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

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

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

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

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

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

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

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

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

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

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

produces the string whose contents are `foobarbaz'.  The next section
explains more about how to create matrices.


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

Matrices
========

   It is easy to define a matrix of values in Octave.  The size of the
matrix is determined automatically, so it is not necessary to explicitly
state the dimensions.  The expression

     a = [1, 2; 3, 4]

results in the matrix


             /      \
             | 1  2 |
       a  =  |      |
             | 3  4 |
             \      /

   Elements of a matrix may be arbitrary expressions, provided that the
dimensions all make sense when combining the various pieces.  For
example, given the above matrix, the expression

     [ a, a ]

produces the matrix

     ans =
     
       1  2  1  2
       3  4  3  4

but the expression

     [ a, 1 ]

produces the error

     error: number of rows must match near line 13, column 6

(assuming that this expression was entered as the first thing on line
13, of course).

   Commas and semicolons are not always required to separate matrix
elements and rows.  The expression

     a = [ 1 2
           3 4 ]

is equivalent to the one above.

   Inside the square brackets that delimit a matrix expression, Octave
looks at the surrounding context to determine whether spaces and newline
characters should be converted into element and row separators, or
simply ignored, so commands like

     [ linspace (1, 2) ]

and

     octave:13> a = [ 1 2
     > 3 4 ]

will work.  However, some possible sources of confusion remain.  For
example, in the expression

     [ 1 - 1 ]

the `-' is treated as a binary operator and the result is the scalar 0,
but in the expression

     [ 1 -1 ]

the `-' is treated as a unary operator and the result is the vector `[
1 -1 ]'.

   Given `a = 1', the expression

     [ 1 a' ]

results in the single quote character `'' being treated as a transpose
operator and the result is the vector `[ 1 1 ]', but the expression

     [ 1 a ' ]

produces the error message

     error: unterminated string constant

because to not do so would make it impossible to correctly parse the
valid expression

     [ a 'foo' ]

   For clarity, it is probably best to always use commas and semicolons
to separate matrix elements and rows.  It is possible to enforce this
style by setting the built-in variable `whitespace_in_literal_matrix' to
`"ignore"'.

 - Built-in Variable: whitespace_in_literal_matrix
     This variable allows some control over how Octave decides to
     convert spaces to commas and semicolons in matrix expressions like
     `[m (1)]' or

          [ 1, 2,
            3, 4 ]

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

          [ 1, 2,
            3, 4 ]

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

     If the value of `whitespace_in_literal_matrix' is `"traditional"',
     Octave will convert spaces to a comma between identifiers and `('.
     For example, given the matrix

          m = [3 2]

     the expression

          [m (1)]

     will be parsed as

          [m, (1)]

     and will result in

          [3 2 1]

     and the expression

          [ 1, 2,
            3, 4 ]

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

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

          [m (1)]

     will produce `3'.  This is the way Octave has always behaved.

   When you type a matrix or the name of a variable whose value is a
matrix, Octave responds by printing the matrix in with neatly aligned
rows and columns.  If the rows of the matrix are too large to fit on the
screen, Octave splits the matrix and displays a header before each
section to indicate which columns are being displayed.

You can use the following variables to control the format of the output.

 - Built-in Variable: output_max_field_width
     This variable specifies the maximum width of a numeric output
     field.  The default value is 10.

 - Built-in Variable: output_precision
     This variable specifies the minimum number of significant figures
     to display for numeric output.  The default value is 5.

   It is possible to achieve a wide range of output styles by using
different values of `output_precision' and `output_max_field_width'.
Reasonable combinations can be set using the `format' function.  *Note
Basic Input and Output::.

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

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

          octave:13> rand (2,10)
          ans =
          
           Columns 1 through 6:
          
            0.75883  0.93290  0.40064  0.43818  0.94958  0.16467
            0.75697  0.51942  0.40031  0.61784  0.92309  0.40201
          
           Columns 7 through 10:
          
            0.90174  0.11854  0.72313  0.73326
            0.44672  0.94303  0.56564  0.82150

     The default value of `split_long_rows' is nonzero.

* Menu:

* Empty Matrices::

