This is octave.info, produced by makeinfo version 6.8 from octave.texi.

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

Copyright © 1996-2023 The Octave Project Developers

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

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

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


File: octave.info,  Node: Using Packages,  Next: Administrating Packages,  Prev: Installing and Removing Packages,  Up: Packages

37.2 Using Packages
===================

By default installed packages are not available from the Octave prompt,
but it is possible to control this using the ‘pkg load’ and ‘pkg unload’
commands.  The functions from a package can be added to the Octave path
by typing

     pkg load package_name

where ‘package_name’ is the name of the package to be added to the path.

   In much the same way a package can be removed from the Octave path by
typing

     pkg unload package_name


File: octave.info,  Node: Administrating Packages,  Next: Creating Packages,  Prev: Using Packages,  Up: Packages

37.3 Administrating Packages
============================

It is possible to make both per-user (local) and system-wide (global)
installations of a package.  If the user performing the installation is
‘root’ (or Administrator with elevated privileges on Windows), the
packages by default install in a system-wide directory that defaults to
‘OCTAVE_HOME/share/octave/packages/’.  If the user is not ‘root’ (or
Octave is running without elevated privileges), packages are installed
locally.  The default installation directory for local packages is
‘USER_DATA_DIR/octave/OCTAVE_API_VERSION/packages’.  Packages will be
installed in a subdirectory of the installation directory that will be
named after the package.  It is possible to change the installation
directory by using the ‘pkg prefix’ command:

     pkg prefix new_installation_directory

The current installation directory can be retrieved by typing

     current_installation_directory = pkg ("prefix")

   The package manager stores some information about the installed
packages in configuration files.  For per-user (local) packages, this
information is stored in the file
‘USER_CONFIG_DIR/octave/OCTAVE_API_VERSION/octave_packages’ by default.
For system-wide (global) installations, it is stored in
‘OCTAVE_HOME/share/octave/octave_packages’.  The path to the per-user
file can be changed with the ‘pkg local_list’ command:

     pkg local_list /path/to/new_file

For system-wide installations, this can be changed in the same way using
the ‘pkg global_list’ command.  If these commands are called without a
new path, the current path will be returned.  To retain these settings
between sessions, they can be set in one of the startup files, see *note
Startup Files::.


File: octave.info,  Node: Creating Packages,  Prev: Administrating Packages,  Up: Packages

37.4 Creating Packages
======================

Internally a package is simply a gzipped tar file that contains a top
level directory of any given name.  This directory will in the following
be referred to as ‘package’ and may contain the following files:

‘package/CITATION’
     This is am optional file describing instructions on how to cite the
     package for publication.  It will be displayed verbatim by the
     function ‘citation’.

‘package/COPYING’
     This is a required file containing the license of the package.  No
     restrictions is made on the license in general.  If however the
     package contains dynamically linked functions the license must be
     compatible with the GNU General Public License.

‘package/DESCRIPTION’
     This is a required file containing information about the package.
     *Note The DESCRIPTION File::, for details on this file.

‘package/ChangeLog’
     This is an optional file describing all the changes made to the
     package source files.

‘package/INDEX’
     This is an optional file describing the functions provided by the
     package.  If this file is not given then one with be created
     automatically from the functions in the package and the
     ‘Categories’ keyword in the ‘DESCRIPTION’ file.  *Note The INDEX
     File::, for details on this file.

‘package/NEWS’
     This is an optional file describing all user-visible changes worth
     mentioning.  As this file increases on size, old entries can be
     moved into ‘package/ONEWS’.

‘package/ONEWS’
     This is an optional file describing old entries from the ‘NEWS’
     file.

‘package/PKG_ADD’
     An optional file that includes commands that are run when the
     package is added to the users path.  Note that ‘PKG_ADD’ directives
     in the source code of the package will also be added to this file
     by the Octave package manager.  Note that symbolic links are to be
     avoided in packages, as symbolic links do not exist on some file
     systems, and so a typical use for this file is the replacement of
     the symbolic link

          ln -s foo.oct bar.oct

     with an autoload directive like

          autoload ('bar', which ('foo'));

     *Note PKG_ADD and PKG_DEL Directives::, for details on ‘PKG_ADD’
     directives.

‘package/PKG_DEL’
     An optional file that includes commands that are run when the
     package is removed from the users path.  Note that ‘PKG_DEL’
     directives in the source code of the package will also be added to
     this file by the Octave package manager.  *Note PKG_ADD and PKG_DEL
     Directives::, for details on ‘PKG_DEL’ directives.

‘package/pre_install.m’
     This is an optional function that is run prior to the installation
     of a package.  This function is called with a single argument, a
     struct with fields names after the data in the ‘DESCRIPTION’, and
     the paths where the package functions will be installed.

‘package/post_install.m’
     This is an optional function that is run after the installation of
     a package.  This function is called with a single argument, a
     struct with fields names after the data in the ‘DESCRIPTION’, and
     the paths where the package functions were installed.

‘package/on_uninstall.m’
     This is an optional function that is run prior to the removal of a
     package.  This function is called with a single argument, a struct
     with fields names after the data in the ‘DESCRIPTION’, the paths
     where the package functions are installed, and whether the package
     is currently loaded.

   Besides the above mentioned files, a package can also contain one or
more of the following directories:

‘package/inst’
     An optional directory containing any files that are directly
     installed by the package.  Typically this will include any
     ‘m’-files.

‘package/src’
     An optional directory containing code that must be built prior to
     the packages installation.  The Octave package manager will execute
     ‘./configure’ in this directory if this script exists, and will
     then call ‘make’ if a file ‘Makefile’ exists in this directory.
     ‘make install’ will however not be called.  The environment
     variables ‘MKOCTFILE’, ‘OCTAVE_CONFIG’, and ‘OCTAVE’ will be set to
     the full paths of the programs ‘mkoctfile’, ‘octave-config’, and
     ‘octave’, respectively, of the correct version when ‘configure’ and
     ‘make’ are called.  If a file called ‘FILES’ exists all files
     listed there will be copied to the ‘inst’ directory, so they also
     will be installed.  If the ‘FILES’ file doesn’t exist, ‘src/*.m’
     and ‘src/*.oct’ will be copied to the ‘inst’ directory.

‘package/doc’
     An optional directory containing documentation for the package.
     The files in this directory will be directly installed in a
     sub-directory of the installed package for future reference.

‘package/bin’
     An optional directory containing files that will be added to the
     Octave ‘EXEC_PATH’ when the package is loaded.  This might contain
     external scripts, etc., called by functions within the package.

* Menu:

* The DESCRIPTION File::
* The INDEX File::
* PKG_ADD and PKG_DEL Directives::
* Missing Components::


File: octave.info,  Node: The DESCRIPTION File,  Next: The INDEX File,  Up: Creating Packages

37.4.1 The DESCRIPTION File
---------------------------

The ‘DESCRIPTION’ file contains various information about the package,
such as its name, author, and version.  This file has a very simple
format

   • Lines starting with ‘#’ are comments.

   • Lines starting with a blank character are continuations from the
     previous line.

   • Everything else is of the form ‘NameOfOption: ValueOfOption’.

The following is a simple example of a ‘DESCRIPTION’ file

     Name: The name of my package
     Version: 1.0.0
     Date: 2007-18-04
     Author: The name (and possibly email) of the package author.
     Maintainer: The name (and possibly email) of the current
      package maintainer.
     Title: The title of the package
     Description: A short description of the package.  If this
      description gets too long for one line it can continue
      on the next by adding a space to the beginning of the
      following lines.
     License: GPLv3+

   The package manager currently recognizes the following keywords

‘Name’
     Name of the package.

‘Version’
     Version of the package.  A package version is typically digits
     separated by dots but may also contain ‘+’, ‘-’, ‘~’, and
     alphanumeric characters (in the "C" locale).  For example, "2.1.0+"
     could indicate a development version of a package.  Versions are
     compared using *note compare_versions: XREFcompare_versions.

‘Date’
     Date of last update.

‘Author’
     Original author of the package.

‘Maintainer’
     Maintainer of the package.

‘Title’
     A one line description of the package.

‘Description’
     A one paragraph description of the package.

‘Categories’
     Optional keyword describing the package (if no ‘INDEX’ file is
     given this is mandatory).

‘Problems’
     Optional list of known problems.

‘Url’
     Optional list of homepages related to the package.

‘Depends’
     A list of other Octave packages that this package depends on.  This
     can include dependencies on particular versions, with the following
     format:

          Depends: package (>= 1.0.0)

     Possible operators are ‘<’, ‘<=’, ‘==’, ‘>=’ or ‘>’.  If the part
     of the dependency in ‘()’ is missing, any version of the package is
     acceptable.  Multiple dependencies can be defined as a comma
     separated list.  This can be used to define a range of versions of
     a particular package:

          Depends: package (>= 1.0.0), package (< 1.5.0)

     It is also possible to depend on particular versions of Octave
     core:

          Depends: octave (>= 3.8.0)

‘License’
     An optional short description of the used license (e.g., GPL
     version 3 or newer).  This is optional since the file ‘COPYING’ is
     mandatory.

‘SystemRequirements’
     These are the external install dependencies of the package and are
     not checked by the package manager.  This is here as a hint to the
     distribution packager.  They follow the same conventions as the
     ‘Depends’ keyword.

‘BuildRequires’
     These are the external build dependencies of the package and are
     not checked by the package manager.  This is here as a hint to the
     distribution packager.  They follow the same conventions as the
     ‘Depends’ keyword.  Note that in general, packaging systems such as
     ‘rpm’ or ‘deb’ autoprobe the install dependencies from the build
     dependencies, and therefore a ‘BuildRequires’ dependency usually
     removes the need for a ‘SystemRequirements’ dependency.

The developer is free to add additional arguments to the ‘DESCRIPTION’
file for their own purposes.  One further detail to aid the packager is
that the ‘SystemRequirements’ and ‘BuildRequires’ keywords can have a
distribution dependent section, and the automatic build process will use
these.  An example of the format of this is

     BuildRequires: libtermcap-devel [Mandriva] libtermcap2-devel

where the first package name will be used as a default and if the RPMs
are built on a Mandriva distribution, then the second package name will
be used instead.


File: octave.info,  Node: The INDEX File,  Next: PKG_ADD and PKG_DEL Directives,  Prev: The DESCRIPTION File,  Up: Creating Packages

37.4.2 The INDEX File
---------------------

The optional ‘INDEX’ file provides a categorical view of the functions
in the package.  This file has a very simple format

   • Lines beginning with ‘#’ are comments.

   • The first non-comment line should look like this

          toolbox >> Toolbox name

   • Lines beginning with an alphabetical character indicates a new
     category of functions.

   • Lines starting with a white space character indicate that the
     function names on the line belong to the last mentioned category.

The format can be summarized with the following example:

     # A comment
     toolbox >> Toolbox name
     Category Name 1
      function1 function2 function3
      function4
     Category Name 2
      function2 function5

   If you wish to refer to a function that users might expect to find in
your package but is not there, providing a work around or pointing out
that the function is available elsewhere, you can use:

     fn = workaround description

This workaround description will not appear when listing functions in
the package with ‘pkg describe’ but they will be published in the HTML
documentation online.  Workaround descriptions can use any HTML markup,
but keep in mind that it will be enclosed in a bold-italic environment.
For the special case of:

     fn = use <code>alternate expression</code>

the bold-italic is automatically suppressed.  You will need to use
‘<code>’ even in references:

     fn = use <a href="someothersite.html"><code>fn</code></a>

Sometimes functions are only partially compatible, in which case you can
list the non-compatible cases separately.  To refer to another function
in the package, use ‘<f>fn</f>’.  For example:

     eig (a, b) = use <f>qz</f>

Since sites may have many missing functions, you can define a macro
rather than typing the same link over and again.

     $id = expansion

defines the macro id.  You can use ‘$id’ anywhere in the description and
it will be expanded.  For example:

     $TSA = see <a href="link_to_spctools">SPC Tools</a>
     arcov = $TSA <code>armcv</code>

id is any string of letters, numbers and ‘_’.


File: octave.info,  Node: PKG_ADD and PKG_DEL Directives,  Next: Missing Components,  Prev: The INDEX File,  Up: Creating Packages

37.4.3 PKG_ADD and PKG_DEL Directives
-------------------------------------

If the package contains files called ‘PKG_ADD’ or ‘PKG_DEL’ the commands
in these files will be executed when the package is added or removed
from the users path.  In some situations such files are a bit cumbersome
to maintain, so the package manager supports automatic creation of such
files.  If a source file in the package contains a ‘PKG_ADD’ or
‘PKG_DEL’ directive they will be added to either the ‘PKG_ADD’ or
‘PKG_DEL’ files.

   In ‘m’-files a ‘PKG_ADD’ directive looks like this

     ## PKG_ADD: some_octave_command

Such lines should be added before the ‘function’ keyword.  In C++ files
a ‘PKG_ADD’ directive looks like this

     // PKG_ADD: some_octave_command

In both cases ‘some_octave_command’ should be replaced by the command
that should be placed in the ‘PKG_ADD’ file.  ‘PKG_DEL’ directives work
in the same way, except the ‘PKG_ADD’ keyword is replaced with ‘PKG_DEL’
and the commands get added to the ‘PKG_DEL’ file.


File: octave.info,  Node: Missing Components,  Prev: PKG_ADD and PKG_DEL Directives,  Up: Creating Packages

37.4.4 Missing Components
-------------------------

If a package relies on a component, such as another Octave package, that
may not be present it may be useful to install a function which informs
users what to do when a particular component is missing.  The function
must be written by the package maintainer and registered with Octave
using ‘missing_component_hook’.

 -- : VAL = missing_component_hook ()
 -- : OLD_VAL = missing_component_hook (NEW_VAL)
 -- : OLD_VAL = missing_component_hook (NEW_VAL, "local")
     Query or set the internal variable that specifies the function to
     call when a component of Octave is missing.

     This can be useful for packagers that may split the Octave
     installation into multiple sub-packages, for example, to provide a
     hint to users for how to install the missing components.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     The hook function is expected to be of the form

          FCN (COMPONENT)

     Octave will call FCN with the name of the function that requires
     the component and a string describing the missing component.  The
     hook function should return an error message to be displayed.

     See also: *note missing_function_hook: XREFmissing_function_hook.


File: octave.info,  Node: External Code Interface,  Next: Test and Demo Functions,  Prev: Packages,  Up: Top

Appendix A External Code Interface
**********************************

"The sum of human wisdom is not contained in any one language"

   — Ezra Pound

   Octave is a fantastic language for solving many problems in science
and engineering.  However, it is not the only computer language and
there are times when you may want to use code written in other
languages.  Good reasons for doing so include: 1) not re-inventing the
wheel; existing function libraries which have been thoroughly tested and
debugged or large scale simulation codebases are a good example, 2)
accessing unique capabilities of a different language; for example the
well-known regular expression functions of Perl (but don’t do that
because ‘regexp’ already exists in Octave).

   Performance should generally *not* be a reason for using compiled
extensions.  Although compiled extensions can run faster, particularly
if they replace a loop in Octave code, this is almost never the best
path to take.  First, there are many techniques to speed up Octave
performance while remaining within the language.  Second, Octave is a
high-level language that makes it easy to perform common mathematical
tasks.  Giving that up means shifting the focus from solving the real
problem to solving a computer programming problem.  It means returning
to low-level constructs such as pointers, memory management,
mathematical overflow/underflow, etc.  Because of the low level nature,
and the fact that the compiled code is executed outside of Octave, there
is the very real possibility of crashing the interpreter and losing
work.

   Before going further, you should first determine if you really need
to bother writing code outside of Octave.

   • Can I get the same functionality using the Octave scripting
     language alone?

     Even when a function already exists outside the language, it may be
     better to simply reproduce the behavior in an m-file rather than
     attempt to interface to the outside code.

   • Is the code thoroughly optimized for Octave?

     If performance is an issue you should always start with the
     in-language techniques for getting better performance.  Chief among
     these is vectorization (*note Vectorization and Faster Code
     Execution::) which not only makes the code concise and more
     understandable but improves performance (10X-100X). If loops must
     be used, make sure that the allocation of space for variables takes
     place outside the loops using an assignment to a matrix of the
     right size, or zeros.

   • Does the code make as much use as possible of existing built-in
     library routines?

     These routines are highly optimized and many do not carry the
     overhead of being interpreted.

   • Does writing a dynamically linked function represent a useful
     investment of your time, relative to staying in Octave?

     It will take time to learn Octave’s interface for external code and
     there will inevitably be issues with tools such as compilers.

   With that said, Octave offers a versatile interface for including
chunks of compiled code as dynamically linked extensions.  These
dynamically linked functions can be called from the interpreter in the
same manner as any ordinary function.  The interface is bi-directional
and external code can call Octave functions (like ‘plot’) which
otherwise might be very difficult to develop.

   The interface is centered around supporting the languages C++, C, and
Fortran.  Octave itself is written in C++ and can call external C++/C
code through its native oct-file interface.  The C language is also
supported through the mex-file interface for compatibility with MATLAB.
Fortran code is easiest to reach through the oct-file interface.

   Because many other languages provide C or C++ APIs it is relatively
simple to build bridges between Octave and other languages.  This is
also a way to bridge to hardware resources which often have device
drivers written in C.

* Menu:

* Oct-Files::
* Mex-Files::
* Standalone Programs::
* Java Interface::


File: octave.info,  Node: Oct-Files,  Next: Mex-Files,  Up: External Code Interface

A.1 Oct-Files
=============

* Menu:

* Getting Started with Oct-Files::
* Matrices and Arrays in Oct-Files::
* Character Strings in Oct-Files::
* Cell Arrays in Oct-Files::
* Structures in Oct-Files::
* Sparse Matrices in Oct-Files::
* Accessing Global Variables in Oct-Files::
* Calling Octave Functions from Oct-Files::
* Calling External Code from Oct-Files::
* Allocating Local Memory in Oct-Files::
* Input Parameter Checking in Oct-Files::
* Exception and Error Handling in Oct-Files::
* Documentation and Testing of Oct-Files::


File: octave.info,  Node: Getting Started with Oct-Files,  Next: Matrices and Arrays in Oct-Files,  Up: Oct-Files

A.1.1 Getting Started with Oct-Files
------------------------------------

Oct-files are pieces of C++ code that have been compiled with the Octave
API into a dynamically loadable object.  They take their name from the
file which contains the object which has the extension ‘.oct’.

   Finding a C++ compiler, using the correct switches, adding the right
include paths for header files, etc. is a difficult task.  Octave
automates this by providing the ‘mkoctfile’ command with which to build
oct-files.  The command is available from within Octave or at the shell
command line.

 -- : mkoctfile [-options] file ...
 -- : [OUTPUT, STATUS] = mkoctfile (...)

     The ‘mkoctfile’ function compiles source code written in C, C++, or
     Fortran.  Depending on the options used with ‘mkoctfile’, the
     compiled code can be called within Octave or can be used as a
     stand-alone application.

     ‘mkoctfile’ can be called from the shell prompt or from the Octave
     prompt.  Calling it from the Octave prompt simply delegates the
     call to the shell prompt.  Any output is stored in the OUTPUT
     variable and the exit status in the STATUS variable.  If called
     with no outputs and the compilation fails then Octave will emit an
     error.  If the programmer requests OUTPUT or STATUS, however,
     Octave will merely issue a warning and it is the programmer’s
     responsibility to verify the command was successful.

     ‘mkoctfile’ accepts the following options, all of which are
     optional except for the filename of the code you wish to compile:

     ‘-I DIR’
          Add the include directory DIR to compile commands.

     ‘-D DEF’
          Add the definition DEF to the compiler call.

     ‘-l LIB’
          Add the library LIB to the link command.

     ‘-L DIR’
          Add the library directory DIR to the link command.

     ‘-M’
     ‘--depend’
          Generate dependency files (.d) for C and C++ source files.

     ‘-R DIR’
          Add the run-time path to the link command.

     ‘-Wl,...’
          Pass options to the linker like "-Wl,-rpath=...".  The quotes
          are needed since commas are interpreted as command separators.

     ‘-W...’
          Pass options to the assembler like "-Wa,OPTION".

     ‘-c’
          Compile but do not link.

     ‘-g’
          Enable debugging options for compilers.

     ‘-o FILE’
     ‘--output FILE’
          Output filename.  Default extension is ‘.oct’ (or ‘.mex’ if
          ‘--mex’ is specified) unless linking a stand-alone executable.

     ‘-p VAR’
     ‘--print VAR’
          Print configuration variable VAR.  There are three categories
          of variables:

          Octave configuration variables that users may override with
          environment variables.  These are used in commands that
          ‘mkoctfile’ executes.

                  ALL_CFLAGS                  INCLUDEDIR
                  ALL_CXXFLAGS                LAPACK_LIBS
                  ALL_FFLAGS                  LDFLAGS
                  ALL_LDFLAGS                 LD_STATIC_FLAG
                  BLAS_LIBS                   LFLAGS
                  CC                          LIBDIR
                  CFLAGS                      LIBOCTAVE
                  CPICFLAG                    LIBOCTINTERP
                  CPPFLAGS                    OCTAVE_LINK_OPTS
                  CXX                         OCTINCLUDEDIR
                  CXXFLAGS                    OCTAVE_LIBS
                  CXXLD                       OCTAVE_LINK_DEPS
                  CXXPICFLAG                  OCTLIBDIR
                  DL_LDFLAGS                  OCT_LINK_DEPS
                  F77                         OCT_LINK_OPTS
                  F77_INTEGER8_FLAG           RDYNAMIC_FLAG
                  FFLAGS                      SPECIAL_MATH_LIB
                  FPICFLAG                    XTRA_CFLAGS
                  INCFLAGS                    XTRA_CXXFLAGS

          Octave configuration variables as above, but currently unused
          by ‘mkoctfile’.

                  AR
                  DEPEND_EXTRA_SED_PATTERN
                  DEPEND_FLAGS
                  FFTW3F_LDFLAGS
                  FFTW3F_LIBS
                  FFTW3_LDFLAGS
                  FFTW3_LIBS
                  FFTW_LIBS
                  FLIBS
                  LIBS
                  RANLIB
                  READLINE_LIBS

          Octave configuration variables that are provided for
          informational purposes only.  Except for ‘OCTAVE_HOME’ and
          ‘OCTAVE_EXEC_HOME’, users may not override these variables.

          If ‘OCTAVE_HOME’ or ‘OCTAVE_EXEC_HOME’ are set in the
          environment, then other variables are adjusted accordingly
          with ‘OCTAVE_HOME’ or ‘OCTAVE_EXEC_HOME’ substituted for the
          original value of the directory specified by the ‘--prefix’ or
          ‘--exec-prefix’ options that were used when Octave was
          configured.

                  API_VERSION                 LOCALFCNFILEDIR
                  ARCHLIBDIR                  LOCALOCTFILEDIR
                  BINDIR                      LOCALSTARTUPFILEDIR
                  CANONICAL_HOST_TYPE         LOCALVERARCHLIBDIR
                  DATADIR                     LOCALVERFCNFILEDIR
                  DATAROOTDIR                 LOCALVEROCTFILEDIR
                  DEFAULT_PAGER               MAN1DIR
                  EXEC_PREFIX                 MAN1EXT
                  EXEEXT                      MANDIR
                  FCNFILEDIR                  OCTAVE_EXEC_HOME
                  IMAGEDIR                    OCTAVE_HOME
                  INFODIR                     OCTAVE_VERSION
                  INFOFILE                    OCTDATADIR
                  LIBEXECDIR                  OCTDOCDIR
                  LOCALAPIARCHLIBDIR          OCTFILEDIR
                  LOCALAPIFCNFILEDIR          OCTFONTSDIR
                  LOCALAPIOCTFILEDIR          STARTUPFILEDIR
                  LOCALARCHLIBDIR

     ‘--link-stand-alone’
          Link a stand-alone executable file.

     ‘--mex’
          Assume creation of a MEX file.  Set the default output
          extension to ‘.mex’.

     ‘-s’
     ‘--strip’
          Strip the output file.

     ‘-v’
     ‘--verbose’
          Echo commands as they are executed.

     ‘file’
          The file to compile or link.  Recognized file types are:

                  .c    C source
                  .cc   C++ source
                  .cp   C++ source
                  .cpp  C++ source
                  .CPP  C++ source
                  .cxx  C++ source
                  .c++  C++ source
                  .C    C++ source
                  .f    Fortran source (fixed form)
                  .F    Fortran source (fixed form)
                  .f90  Fortran source (free form)
                  .F90  Fortran source (free form)
                  .o    object file
                  .a    library file

   Consider the following short example which introduces the basics of
writing a C++ function that can be linked to Octave.

     #include <octave/oct.h>
     
     DEFUN_DLD (helloworld, args, nargout,
                "Hello World Help String")
     {
       octave_stdout << "Hello World has "
                     << args.length () << " input arguments and "
                     << nargout << " output arguments.\n";
     
       // Return empty matrices for any outputs
       octave_value_list retval (nargout);
       for (int i = 0; i < nargout; i++)
         retval(i) = octave_value (Matrix ());
     
       return retval;
     }

   The first critical line is ‘#include <octave/oct.h>’ which makes
available most of the definitions necessary for a C++ oct-file.  Note
that ‘octave/oct.h’ is a C++ header and cannot be directly ‘#include’’ed
in a C source file, nor any other language.

   Included by ‘oct.h’ is a definition for the macro ‘DEFUN_DLD’ which
creates a dynamically loaded function.  This macro takes four arguments:

  1. The function name as it will be seen in Octave,

  2. The list of arguments to the function of type ‘octave_value_list’,

  3. The number of output arguments, which can be—and often is—omitted
     if not used, and

  4. The string to use for the help text of the function.

   The return type of functions defined with ‘DEFUN_DLD’ is always
‘octave_value_list’.

   There are a couple of important considerations in the choice of
function name.  First, it must be a valid Octave function name and so
must be a sequence of letters, digits, and underscores not starting with
a digit.  Second, as Octave uses the function name to define the
filename it attempts to find the function in, the function name in the
‘DEFUN_DLD’ macro must match the filename of the oct-file.  Therefore,
the above function should be in a file ‘helloworld.cc’, and would be
compiled to an oct-file using the command

     mkoctfile helloworld.cc

   This will create a file called ‘helloworld.oct’ that is the compiled
version of the function.  It should be noted that it is perfectly
acceptable to have more than one ‘DEFUN_DLD’ function in a source file.
However, there must either be a symbolic link to the oct-file for each
of the functions defined in the source code with the ‘DEFUN_DLD’ macro
or the ‘autoload’ (*note Function Files::) function should be used.

   The rest of the function shows how to find the number of input
arguments, how to print through the Octave pager, and how to return from
the function.  After compiling this function as above, an example of its
use is

     helloworld (1, 2, 3)
     ⊣ Hello World has 3 input arguments and 0 output arguments.

   Subsequent sections show how to use specific classes from Octave’s
core internals.  Base classes like ‘dMatrix’ (a matrix of double values)
are found in the directory ‘liboctave/array’.  The definitive reference
for how to use a particular class is the header file itself.  However,
it is often enough simply to study the examples in the manual in order
to be able to use a class.


File: octave.info,  Node: Matrices and Arrays in Oct-Files,  Next: Character Strings in Oct-Files,  Prev: Getting Started with Oct-Files,  Up: Oct-Files

A.1.2 Matrices and Arrays in Oct-Files
--------------------------------------

Octave supports a number of different array and matrix classes, the
majority of which are based on the ‘Array’ class.  The exception are the
sparse matrix types discussed separately below.  There are three basic
matrix types:

‘Matrix’
     A double precision matrix class defined in ‘dMatrix.h’

‘ComplexMatrix’
     A complex matrix class defined in ‘CMatrix.h’

‘BoolMatrix’
     A boolean matrix class defined in ‘boolMatrix.h’

   These are the basic two-dimensional matrix types of Octave.  In
addition there are a number of multi-dimensional array types including

‘NDArray’
     A double precision array class defined in ‘dNDArray.h’

‘ComplexNDarray’
     A complex array class defined in ‘CNDArray.h’

‘boolNDArray’
     A boolean array class defined in ‘boolNDArray.h’

‘int8NDArray’
‘int16NDArray’
‘int32NDArray’
‘int64NDArray’
     8, 16, 32, and 64-bit signed array classes defined in
     ‘int8NDArray.h’, ‘int16NDArray.h’, etc.

‘uint8NDArray’
‘uint16NDArray’
‘uint32NDArray’
‘uint64NDArray’
     8, 16, 32, and 64-bit unsigned array classes defined in
     ‘uint8NDArray.h’, ‘uint16NDArray.h’, etc.

   There are several basic ways of constructing matrices or
multi-dimensional arrays.  Using the class ‘Matrix’ as an example one
can

   • Create an empty matrix or array with the empty constructor.  For
     example:

          Matrix a;

     This can be used for all matrix and array types.

   • Define the dimensions of the matrix or array with a dim_vector
     which has the same characteristics as the vector returned from
     ‘size’.  For example:

          dim_vector dv (2, 3);  // 2 rows, 3 columns
          Matrix a (dv);

     This can be used for all matrix and array types.

   • Define the number of rows and columns in the matrix.  For example:

          Matrix a (2, 2)

     This constructor can *only* be used with matrix types.

   These types all share a number of basic methods and operators.  Many
bear a resemblance to functions that exist in the interpreter.  A
selection of useful methods include

 -- Method: T& operator () (octave_idx_type)
 -- Method: T& elem (octave_idx_type)
     The ‘()’ operator or ‘elem’ method allow the values of the matrix
     or array to be read or set.  These methods take a single argument,
     which is of type ‘octave_idx_type’, that is the index into the
     matrix or array.  Additionally, the matrix type allows two argument
     versions of the ‘()’ operator and ‘elem’ method, giving the row and
     column index of the value to get or set.

   Note that these functions do significant error checking and so in
some circumstances the user might prefer to access the data of the array
or matrix directly through the ‘fortran_vec’ method discussed below.

 -- Method: octave_idx_type numel (void) const
     The total number of elements in the matrix or array.

 -- Method: size_t byte_size (void) const
     The number of bytes used to store the matrix or array.

 -- Method: dim_vector dims (void) const
     The dimensions of the matrix or array in value of type
     ‘dim_vector’.

 -- Method: int ndims (void) const
     The number of dimensions of the matrix or array.  Matrices are
     always 2-D, but arrays can be N-dimensional.

 -- Method: void resize (const dim_vector&)
 -- Method: void resize (nrows, ncols)
     A method taking either an argument of type ‘dim_vector’, or, in the
     case of a matrix, two arguments of type ‘octave_idx_type’ defining
     the number of rows and columns in the matrix.

 -- Method: T* fortran_vec (void)
     This method returns a pointer to the underlying data of the matrix
     or array so that it can be manipulated directly, either within
     Octave or by an external library.

   Operators such as ‘+’, ‘-’, or ‘*’ can be used on the majority of the
matrix and array types.  In addition there are a number of methods that
are of interest only for matrices such as ‘transpose’, ‘hermitian’,
‘solve’, etc.

   The typical way to extract a matrix or array from the input arguments
of ‘DEFUN_DLD’ function is as follows

     #include <octave/oct.h>
     
     DEFUN_DLD (addtwomatrices, args, , "Add A to B")
     {
       if (args.length () != 2)
         print_usage ();
     
       NDArray A = args(0).array_value ();
       NDArray B = args(1).array_value ();
     
       return octave_value (A + B);
     }

   To avoid segmentation faults causing Octave to abort, this function
explicitly checks that there are sufficient arguments available before
accessing these arguments.  It then obtains two multi-dimensional arrays
of type ‘NDArray’ and adds these together.  Note that the ‘array_value’
method is called without using the ‘is_matrix_type’ method.  If an error
occurs when attempting to extract the value, Octave will print a message
and throw an exception.  The reason to prefer this coding structure is
that the arguments might be a type which is not an ‘NDArray’, but for
which it would make sense to convert them to one.  The ‘array_value’
method allows this conversion to be performed transparently when
possible.  If you need to catch errors like this, and perform some kind
of cleanup or other operation, you can catch the
‘octave_execution_error’ exception.

   ‘A + B’, operating on two ‘NDArray’ objects returns an ‘NDArray’,
which is cast to an ‘octave_value’ on the return from the function.  An
example of the use of this demonstration function is

     addtwomatrices (ones (2, 2), eye (2, 2))
           ⇒  2  1
               1  2

   A list of the basic ‘Matrix’ and ‘Array’ types, the methods to
extract these from an ‘octave_value’, and the associated header file is
listed below.

Type                   Function                      Source Code
----------------------------------------------------------------------------
‘RowVector’            ‘row_vector_value’            ‘dRowVector.h’
‘ComplexRowVector’     ‘complex_row_vector_value’    ‘CRowVector.h’
‘ColumnVector’         ‘column_vector_value’         ‘dColVector.h’
‘ComplexColumnVector’  ‘complex_column_vector_value’ ‘CColVector.h’
‘Matrix’               ‘matrix_value’                ‘dMatrix.h’
‘ComplexMatrix’        ‘complex_matrix_value’        ‘CMatrix.h’
‘boolMatrix’           ‘bool_matrix_value’           ‘boolMatrix.h’
‘charMatrix’           ‘char_matrix_value’           ‘chMatrix.h’
‘NDArray’              ‘array_value’                 ‘dNDArray.h’
‘ComplexNDArray’       ‘complex_array_value’         ‘CNDArray.h’
‘boolNDArray’          ‘bool_array_value’            ‘boolNDArray.h’
‘charNDArray’          ‘char_array_value’            ‘charNDArray.h’
‘int8NDArray’          ‘int8_array_value’            ‘int8NDArray.h’
‘int16NDArray’         ‘int16_array_value’           ‘int16NDArray.h’
‘int32NDArray’         ‘int32_array_value’           ‘int32NDArray.h’
‘int64NDArray’         ‘int64_array_value’           ‘int64NDArray.h’
‘uint8NDArray’         ‘uint8_array_value’           ‘uint8NDArray.h’
‘uint16NDArray’        ‘uint16_array_value’          ‘uint16NDArray.h’
‘uint32NDArray’        ‘uint32_array_value’          ‘uint32NDArray.h’
‘uint64NDArray’        ‘uint64_array_value’          ‘uint64NDArray.h’


File: octave.info,  Node: Character Strings in Oct-Files,  Next: Cell Arrays in Oct-Files,  Prev: Matrices and Arrays in Oct-Files,  Up: Oct-Files

A.1.3 Character Strings in Oct-Files
------------------------------------

A character string in Octave is just a special ‘Array’ class.  Consider
the example:

     #include <octave/oct.h>
     
     DEFUN_DLD (stringdemo, args, , "String Demo")
     {
       if (args.length () != 1)
         print_usage ();
     
       octave_value_list retval;
     
       charMatrix ch = args(0).char_matrix_value ();
     
       retval(1) = octave_value (ch, '\'');  // Single Quote String
     
       octave_idx_type nr = ch.rows ();
     
       for (octave_idx_type i = 0; i < nr / 2; i++)
         {
           std::string tmp = ch.row_as_string (i);
     
           ch.insert (ch.row_as_string (nr-i-1).c_str (), i, 0);
           ch.insert (tmp.c_str (), nr-i-1, 0);
         }
     
       retval(0) = octave_value (ch, '"');  // Double Quote String
     
       return retval;
     }

   An example of the use of this function is

     s0 = ["First String"; "Second String"];
     [s1,s2] = stringdemo (s0)
     ⇒ s1 = Second String
             First String

     ⇒ s2 = First String
             Second String

     typeinfo (s2)
     ⇒ sq_string
     typeinfo (s1)
     ⇒ string

   One additional complication of strings in Octave is the difference
between single quoted and double quoted strings.  To find out if an
‘octave_value’ contains a single or double quoted string use one of the
predicate tests shown below.

     if (args(0).is_sq_string ())
       octave_stdout << "First argument is a single quoted string\n";
     else if (args(0).is_dq_string ())
       octave_stdout << "First argument is a double quoted string\n";

   Note, however, that both types of strings are represented by the
‘charNDArray’ type, and so when assigning to an ‘octave_value’, the type
of string should be specified.  For example:

     octave_value_list retval;
     charNDArray ch;
     ...
     // Create single quoted string
     retval(1) = octave_value (ch);   // default constructor is sq_string
                OR
     retval(1) = octave_value (ch, '\'');  // explicitly create sq_string

     // Create a double quoted string
     retval(0) = octave_value (ch, '"');


File: octave.info,  Node: Cell Arrays in Oct-Files,  Next: Structures in Oct-Files,  Prev: Character Strings in Oct-Files,  Up: Oct-Files

A.1.4 Cell Arrays in Oct-Files
------------------------------

Octave’s cell type is also available from within oct-files.  A cell
array is just an ‘Array’ of ‘octave_value’s, and thus each element of
the cell array can be treated like any other ‘octave_value’.  A simple
example is

     #include <octave/oct.h>
     #include <octave/Cell.h>
     
     DEFUN_DLD (celldemo, args, , "Cell Demo")
     {
       if (args.length () != 1)
         print_usage ();
     
       Cell c = args(0).cell_value ();
     
       octave_value_list retval;
       retval.resize (c.numel ());    // faster code by pre-declaring size
     
       for (octave_idx_type i = 0; i < c.numel (); i++)
         {
           retval(i) = c(i);          // using operator syntax
           //retval(i) = c.elem (i);  // using method syntax
         }
     
       return retval;
     }

   Note that cell arrays are used less often in standard oct-files and
so the ‘Cell.h’ header file must be explicitly included.  The rest of
the example extracts the ‘octave_value’s one by one from the cell array
and returns them as individual output arguments.  For example:

     [b1, b2, b3] = celldemo ({1, [1, 2], "test"})
     ⇒
     b1 =  1
     b2 =

        1   2

     b3 = test


File: octave.info,  Node: Structures in Oct-Files,  Next: Sparse Matrices in Oct-Files,  Prev: Cell Arrays in Oct-Files,  Up: Oct-Files

A.1.5 Structures in Oct-Files
-----------------------------

A structure in Octave is a map between a number of fields represented
and their values.  The Standard Template Library ‘map’ class is used,
with the pair consisting of a ‘std::string’ and an Octave ‘Cell’
variable.

   A simple example demonstrating the use of structures within oct-files
is

     #include <octave/oct.h>
     #include <octave/ov-struct.h>
     
     DEFUN_DLD (structdemo, args, , "Struct Demo")
     {
       if (args.length () != 2)
         print_usage ();
     
       if (! args(0).isstruct ())
         error ("structdemo: ARG1 must be a struct");
     
       octave_scalar_map arg0 = args(0).scalar_map_value ();
       //octave_map arg0 = args(0).map_value ();
     
       if (! args(1).is_string ())
         error ("structdemo: ARG2 must be a character string");
     
       std::string arg1 = args(1).string_value ();
     
       octave_value tmp = arg0.contents (arg1);
       //octave_value tmp = arg0.contents (arg1)(0);
     
       if (! tmp.is_defined ())
         error ("structdemo: struct does not have a field named '%s'\n",
                arg1.c_str ());
     
       octave_scalar_map st;
     
       st.assign ("selected", tmp);
     
       return octave_value (st);
     }

   An example of its use is

     x.a = 1; x.b = "test"; x.c = [1, 2];
     structdemo (x, "b")
     ⇒ selected = test

   The example above specifically uses the ‘octave_scalar_map’ class
which is for representing a single struct.  For structure arrays, the
‘octave_map’ class is used instead.  The commented code shows how the
demo could be modified to handle a structure array.  In that case, the
‘contents’ method returns a ‘Cell’ which may have more than one element.
Therefore, to obtain the underlying ‘octave_value’ in the single struct
example we would write

     octave_value tmp = arg0.contents (arg1)(0);

where the trailing ‘(0)’ is the ‘()’ operator on the ‘Cell’ object.  If
this were a true structure array with multiple elements we could iterate
over the elements using the ‘()’ operator.

   Structures are a relatively complex data container and there are more
functions available in ‘oct-map.h’ which make coding with them easier
than relying on just ‘contents’.


File: octave.info,  Node: Sparse Matrices in Oct-Files,  Next: Accessing Global Variables in Oct-Files,  Prev: Structures in Oct-Files,  Up: Oct-Files

A.1.6 Sparse Matrices in Oct-Files
----------------------------------

There are three classes of sparse objects that are of interest to the
user.

‘SparseMatrix’
     A double precision sparse matrix class

‘SparseComplexMatrix’
     A complex sparse matrix class

‘SparseBoolMatrix’
     A boolean sparse matrix class

   All of these classes inherit from the ‘Sparse<T>’ template class, and
so all have similar capabilities and usage.  The ‘Sparse<T>’ class was
based on Octave’s ‘Array<T>’ class and users familiar with Octave’s
‘Array’ classes will be comfortable with the use of the sparse classes.

   The sparse classes will not be entirely described in this section,
due to their similarity with the existing ‘Array’ classes.  However,
there are a few differences due the nature of sparse objects, and these
will be described.  First, although it is fundamentally possible to have
N-dimensional sparse objects, the Octave sparse classes do not allow
them at this time; All instances of the sparse classes *must* be
2-dimensional.  This means that ‘SparseMatrix’ is actually more similar
to Octave’s ‘Matrix’ class than it is to the ‘NDArray’ class.

* Menu:

* Array and Sparse Class Differences::
* Creating Sparse Matrices in Oct-Files::
* Using Sparse Matrices in Oct-Files::


File: octave.info,  Node: Array and Sparse Class Differences,  Next: Creating Sparse Matrices in Oct-Files,  Up: Sparse Matrices in Oct-Files

A.1.6.1 Array and Sparse Class Differences
..........................................

The number of elements in a sparse matrix is considered to be the number
of nonzero elements, rather than the product of the dimensions.
Therefore,

     SparseMatrix sm;
     ...
     int nnz = sm.nelem ();

returns the number of nonzero elements (like the interpreter function
‘nnz’).  If the user really requires the number of elements in the
matrix, including the nonzero elements, they should use ‘numel’ rather
than ‘nelem’.  Note that for very large matrices, where the product of
the two dimensions is larger than the representation of an unsigned int,
‘numel’ can overflow.  An example is ‘speye (1e6)’ which will create a
matrix with a million rows and columns, but only a million nonzero
elements.  In this case, the number of rows multiplied by the number of
columns is more than two hundred times the maximum value that can be
represented by an unsigned 32-bit int.  The use of ‘numel’ should,
therefore, be avoided unless it is known that it will not overflow.

   Extreme care is also required when using the ‘elem’ method or the
‘()’ operator which perform essentially the same function.  The reason
is that if a sparse object is non-const, then Octave will assume that a
request for a zero element in a sparse matrix is in fact a request to
create this element so it can be filled.  Therefore, a piece of code
like

     SparseMatrix sm;
     ...
     for (int j = 0; j < nc; j++)
       for (int i = 0; i < nr; i++)
         std::cerr << " (" << i << "," << j << "): " << sm(i,j) << "\n";

is a great way of turning a sparse matrix into a dense one, and a very
slow way at that since it reallocates the sparse object for each zero
element in the matrix.

   A simple way of preventing the above from happening is to create a
temporary constant version of the sparse matrix.  Note that only the
container for the sparse matrix will be copied, while the actual
representation of the data will be shared between the two versions of
the sparse matrix; This is not a costly operation.  The example above,
re-written to prevent sparse-to-dense conversion, is

     SparseMatrix sm;
     ...
     const SparseMatrix tmp (sm);
     for (int j = 0; j < nc; j++)
       for (int i = 0; i < nr; i++)
         std::cerr << " (" << i << "," << j << "): " << tmp(i,j) << "\n";

   Finally, because the sparse types aren’t represented by a contiguous
block of memory, the ‘fortran_vec’ method of ‘Array<T>’ is not
available.  It is, however, replaced by three separate methods ‘ridx’,
‘cidx’, and ‘data’, that access the raw compressed column format that
Octave sparse matrices are stored in.  These methods can be used in a
manner similar to ‘elem’ to allow the matrix to be accessed or filled.
However, it is up to the user to respect the sparse matrix compressed
column format or the matrix will become corrupted.


File: octave.info,  Node: Creating Sparse Matrices in Oct-Files,  Next: Using Sparse Matrices in Oct-Files,  Prev: Array and Sparse Class Differences,  Up: Sparse Matrices in Oct-Files

A.1.6.2 Creating Sparse Matrices in Oct-Files
.............................................

There are two useful strategies for creating a sparse matrix.  The first
is to create three vectors representing the row index, column index, and
data values, and from these create the matrix.  The second alternative
is to create a sparse matrix with the appropriate amount of space, and
then fill in the values.  Both techniques have their advantages and
disadvantages.

   Below is an example of creating a small sparse matrix using the first
technique

     int nz, nr, nc;
     nz = 4, nr = 3, nc = 4;

     ColumnVector ridx (nz);
     ColumnVector cidx (nz);
     ColumnVector data (nz);

     ridx(0) = 1; cidx(0) = 1; data(0) = 1;
     ridx(1) = 2; cidx(1) = 2; data(1) = 2;
     ridx(2) = 2; cidx(2) = 4; data(2) = 3;
     ridx(3) = 3; cidx(3) = 4; data(3) = 4;
     SparseMatrix sm (data, ridx, cidx, nr, nc);

which creates the matrix given in section *note Storage of Sparse
Matrices::.  Note that the compressed matrix format is not used at the
time of the creation of the matrix itself, but is used internally.

   As discussed in the chapter on Sparse Matrices, the values of the
sparse matrix are stored in increasing column-major ordering.  Although
the data passed by the user need not respect this requirement,
pre-sorting the data will significantly speed up creation of the sparse
matrix.

   The disadvantage of this technique for creating a sparse matrix is
that there is a brief time when two copies of the data exist.  For
extremely memory constrained problems this may not be the best technique
for creating a sparse matrix.

   The alternative is to first create a sparse matrix with the desired
number of nonzero elements and then later fill those elements in.
Sample code:

     int nz, nr, nc;
     nz = 4, nr = 3, nc = 4;
     SparseMatrix sm (nr, nc, nz);
     sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4;

   This creates the same matrix as previously.  Again, although not
strictly necessary, it is significantly faster if the sparse matrix is
created and the elements are added in column-major ordering.  The reason
for this is that when elements are inserted at the end of the current
list of known elements then no element in the matrix needs to be moved
to allow the new element to be inserted; Only the column indices need to
be updated.

   There are a few further points to note about this method of creating
a sparse matrix.  First, it is possible to create a sparse matrix with
fewer elements than are actually inserted in the matrix.  Therefore,

     int nr, nc;
     nr = 3, nc = 4;
     SparseMatrix sm (nr, nc, 0);
     sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4;

is perfectly valid.  However, it is a very bad idea because as each new
element is added to the sparse matrix the matrix needs to request more
space and reallocate memory.  This is an expensive operation that will
significantly slow this means of creating a sparse matrix.  It is
possible to create a sparse matrix with excess storage, so having NZ
greater than 4 in this example is also valid.  The disadvantage is that
the matrix occupies more memory than strictly needed.

   Of course, it is not always possible to know the number of nonzero
elements prior to filling a matrix.  For this reason the additional
unused storage of a sparse matrix can be removed after its creation with
the ‘maybe_compress’ function.  In addition to deallocating unused
storage, ‘maybe_compress’ can also remove zero elements from the matrix.
The removal of zero elements from the matrix is controlled by setting
the argument of the ‘maybe_compress’ function to be ‘true’.  However,
the cost of removing the zeros is high because it implies re-sorting the
elements.  If possible, it is better for the user to avoid adding the
unnecessary zeros in the first place.  An example of the use of
‘maybe_compress’ is

     int nz, nr, nc;
     nz = 6, nr = 3, nc = 4;

     SparseMatrix sm1 (nr, nc, nz);
     sm1(0,0) = 1; sm1(0,1) = 2; sm1(1,3) = 3; sm1(2,3) = 4;
     sm1.maybe_compress ();   // No zero elements were added

     SparseMatrix sm2 (nr, nc, nz);
     sm2(0,0) = 1; sm2(0,1) = 2; sm(0,2) = 0; sm(1,2) = 0;
     sm1(1,3) = 3; sm1(2,3) = 4;
     sm2.maybe_compress (true);  // Zero elements were added

   The use of the ‘maybe_compress’ function should be avoided if
possible as it will slow the creation of the matrix.

   A third means of creating a sparse matrix is to work directly with
the data in compressed row format.  An example of this advanced
technique might be

     octave_value arg;
     ...
     int nz, nr, nc;
     nz = 6, nr = 3, nc = 4;   // Assume we know the max # nz
     SparseMatrix sm (nr, nc, nz);
     Matrix m = arg.matrix_value ();

     int ii = 0;
     sm.cidx (0) = 0;
     for (int j = 1; j < nc; j++)
       {
         for (int i = 0; i < nr; i++)
           {
             double tmp = m(i,j);
             if (tmp != 0.)
               {
                 sm.data(ii) = tmp;
                 sm.ridx(ii) = i;
                 ii++;
               }
           }
         sm.cidx(j+1) = ii;
      }
     sm.maybe_compress ();  // If don't know a priori the final # of nz.

which is probably the most efficient means of creating a sparse matrix.

   Finally, it may sometimes arise that the amount of storage initially
created is insufficient to completely store the sparse matrix.
Therefore, the method ‘change_capacity’ exists to reallocate the sparse
memory.  The above example would then be modified as

     octave_value arg;
     ...
     int nz, nr, nc;
     nz = 6, nr = 3, nc = 4;   // Guess the number of nz elements
     SparseMatrix sm (nr, nc, nz);
     Matrix m = arg.matrix_value ();

     int ii = 0;
     sm.cidx (0) = 0;
     for (int j = 1; j < nc; j++)
       {
         for (int i = 0; i < nr; i++)
           {
             double tmp = m(i,j);
             if (tmp != 0.)
               {
                 if (ii == nz)
                   {
                     nz += 2;   // Add 2 more elements
                     sm.change_capacity (nz);
                   }
                 sm.data(ii) = tmp;
                 sm.ridx(ii) = i;
                 ii++;
               }
           }
         sm.cidx(j+1) = ii;
      }
     sm.maybe_compress ();  // If don't know a priori the final # of nz.

   Note that both increasing and decreasing the number of nonzero
elements in a sparse matrix is expensive as it involves memory
reallocation.  Also because parts of the matrix, though not its
entirety, exist as old and new copies at the same time, additional
memory is needed.  Therefore, if possible avoid changing capacity.


File: octave.info,  Node: Using Sparse Matrices in Oct-Files,  Prev: Creating Sparse Matrices in Oct-Files,  Up: Sparse Matrices in Oct-Files

A.1.6.3 Using Sparse Matrices in Oct-Files
..........................................

Most of the same operators and functions for sparse matrices that are
available from the Octave interpreter are also available within
oct-files.  The basic means of extracting a sparse matrix from an
‘octave_value’, and returning it as an ‘octave_value’, can be seen in
the following example.

     octave_value_list retval;

     SparseMatrix sm = args(0).sparse_matrix_value ();
     SparseComplexMatrix scm = args(1).sparse_complex_matrix_value ();
     SparseBoolMatrix sbm = args(2).sparse_bool_matrix_value ();
     ...
     retval(2) = sbm;
     retval(1) = scm;
     retval(0) = sm;

   The conversion to an ‘octave_value’ is handled by the sparse
‘octave_value’ constructors, and so no special care is needed.


File: octave.info,  Node: Accessing Global Variables in Oct-Files,  Next: Calling Octave Functions from Oct-Files,  Prev: Sparse Matrices in Oct-Files,  Up: Oct-Files

A.1.7 Accessing Global Variables in Oct-Files
---------------------------------------------

Global variables allow variables in the global scope to be accessed.
Global variables can be accessed within oct-files by using the support
functions ‘global_varval’ and ‘global_assign’ from the current
interpreter’s symbol table.  Both functions take as first argument a
string representing the variable name to be obtained or assigned.  The
second argument of ‘global_assign’ is the value to be assigned.  An
example of the use of these two functions is

     #include <octave/oct.h>
     #include <octave/interpreter.h>
     
     DEFMETHOD_DLD (globaldemo, interp, args, , "Global Demo")
     {
       if (args.length () != 1)
         print_usage ();
     
       octave_value retval;
     
       std::string s = args(0).string_value ();
     
       octave::symbol_table& symtab = interp.get_symbol_table ();
     
       octave_value tmp = symtab.global_varval (s);
     
       if (tmp.is_defined ())
         retval = tmp;
       else
         retval = "Global variable not found";
     
       symtab.global_assign ("a", 42.0);
     
       return retval;
     }

   An example of its use is

     global a b
     b = 10;
     globaldemo ("b")
     ⇒ 10
     globaldemo ("c")
     ⇒ "Global variable not found"
     num2str (a)
     ⇒ 42


File: octave.info,  Node: Calling Octave Functions from Oct-Files,  Next: Calling External Code from Oct-Files,  Prev: Accessing Global Variables in Oct-Files,  Up: Oct-Files

A.1.8 Calling Octave Functions from Oct-Files
---------------------------------------------

There is often a need to be able to call another Octave function from
within an oct-file, and there are many examples of such within Octave
itself.  For example, the ‘quad’ function is an oct-file that calculates
the definite integral by quadrature over a user-supplied function.

   There are also many ways in which a function could be given as input.
It might be passed as one of

  1. Function Handle

  2. Anonymous Function Handle

  3. String

   The code below demonstrates all four methods of passing a function to
an oct-file.

     #include <octave/oct.h>
     #include <octave/parse.h>
     
     DEFMETHOD_DLD (funcdemo, interp, args, nargout, "Function Demo")
     {
       int nargin = args.length ();
     
       if (nargin < 2)
         print_usage ();
     
       octave_value_list newargs;
     
       for (octave_idx_type i = nargin - 1; i > 0; i--)
         newargs(i-1) = args(i);
     
       octave_value_list retval;
     
       if (args(0).is_function_handle () || args(0).is_inline_function ()
           || args(0).is_string ())
         retval = interp.feval (args(0), newargs, nargout);
       else
         error ("funcdemo: INPUT must be string, inline, or function handle");
     
       return retval;
     }

   The first input to the demonstration code is a user-supplied function
and the remaining arguments are all passed to the function.

     funcdemo (@sin, 1)
     ⇒ 0.84147
     funcdemo (@(x) sin (x), 1)
     ⇒ 0.84147
     funcdemo ("sin", 1)
     ⇒ 0.84147
     funcdemo (@atan2, 1, 1)
     ⇒ 0.78540

   When the user function is passed as a string the treatment of the
function is different.  In some cases it is necessary to have the user
supplied function as an ‘octave_function’ object.  In that case the
string argument can be used to create a temporary function as
demonstrated below.

     std::octave fcn_name = unique_symbol_name ("__fcn__");
     std::string fcode = "function y = ";
     fcode.append (fcn_name);
     fcode.append ("(x) y = ");
     fcn = extract_function (args(0), "funcdemo", fcn_name,
                             fcode, "; endfunction");
     ...
     if (fcn_name.length ())
       clear_function (fcn_name);

   There are two important things to know in this case.  First, the
number of input arguments to the user function is fixed, and in the
above example is a single argument.  Second, to avoid leaving the
temporary function in the Octave symbol table it should be cleared after
use.  Also, by convention all internal function names begin and end with
the character sequence ‘__’.


File: octave.info,  Node: Calling External Code from Oct-Files,  Next: Allocating Local Memory in Oct-Files,  Prev: Calling Octave Functions from Oct-Files,  Up: Oct-Files

A.1.9 Calling External Code from Oct-Files
------------------------------------------

Linking external C code to Octave is relatively simple, as the C
functions can easily be called directly from C++.  One possible issue is
that the declarations of the external C functions may need to be
explicitly defined as C functions to the compiler.  If the declarations
of the external C functions are in the header ‘foo.h’, then the tactic
to ensure that the C++ compiler treats these declarations as C code is

     #ifdef __cplusplus
     extern "C"
     {
     #endif
     #include "foo.h"
     #ifdef __cplusplus
     }  /* end extern "C" */
     #endif

   Calling Fortran code, however, can pose more difficulties.  This is
due to differences in the manner in which compilers treat the linking of
Fortran code with C or C++ code.  Octave supplies several macros that
allow consistent behavior across a number of compilers.

   The underlying Fortran code should use the ‘XSTOPX’ function to
replace the Fortran ‘STOP’ function.  ‘XSTOPX’ uses the Octave exception
handler to treat failing cases in the Fortran code explicitly.  Note
that Octave supplies its own replacement BLAS ‘XERBLA’ function, which
uses ‘XSTOPX’.

   If the code calls ‘XSTOPX’, then the ‘F77_XFCN’ macro should be used
to call the underlying Fortran function.  The Fortran exception state
can then be checked with the global variable
‘f77_exception_encountered’.  If ‘XSTOPX’ will not be called, then the
‘F77_FCN’ macro should be used instead to call the Fortran code.

   There is no great harm in using ‘F77_XFCN’ in all cases, except that
for Fortran code that is short running and executes a large number of
times, there is potentially an overhead in doing so.  However, if
‘F77_FCN’ is used with code that calls ‘XSTOP’, Octave can generate a
segmentation fault.

   An example of the inclusion of a Fortran function in an oct-file is
given in the following example, where the C++ wrapper is

     #include <octave/oct.h>
     #include <octave/f77-fcn.h>
     
     extern "C"
     {
       F77_RET_T
       F77_FUNC (fortransub, FORTSUB)
         (const F77_INT&, F77_DBLE*, F77_CHAR_ARG_DECL F77_CHAR_ARG_LEN_DECL);
     }
     
     DEFUN_DLD (fortrandemo, args, , "Fortran Demo")
     {
       if (args.length () != 1)
         print_usage ();
     
       NDArray a = args(0).array_value ();
     
       double *av = a.fortran_vec ();
       octave_idx_type na = a.numel ();
     
       OCTAVE_LOCAL_BUFFER (char, ctmp, 128);
     
       F77_XFCN (fortransub, FORTSUB,
                 (na, av, ctmp F77_CHAR_ARG_LEN (128)));
     
       return ovl (a, std::string (ctmp));
     }

and the Fortran function is

           subroutine fortransub (n, a, s)
           implicit none
           character*(*) s
           real*8 a(*)
           integer*4 i, n, ioerr
           do i = 1, n
             if (a(i) .eq. 0d0) then
               call xstopx ('fortransub: divide by zero')
             else
               a(i) = 1d0 / a(i)
             endif
           enddo
           write (unit = s, fmt = '(a,i3,a,a)', iostat = ioerr)
          $       'There are ', n,
          $       ' values in the input vector', char(0)
           if (ioerr .ne. 0) then
             call xstopx ('fortransub: error writing string')
           endif
           return
           end

   This example demonstrates most of the features needed to link to an
external Fortran function, including passing arrays and strings, as well
as exception handling.  Both the Fortran and C++ files need to be
compiled in order for the example to work.

     mkoctfile fortrandemo.cc fortransub.f
     [b, s] = fortrandemo (1:3)
     ⇒
       b = 1.00000   0.50000   0.33333
       s = There are   3 values in the input vector
     [b, s] = fortrandemo (0:3)
     error: fortrandemo: fortransub: divide by zero


File: octave.info,  Node: Allocating Local Memory in Oct-Files,  Next: Input Parameter Checking in Oct-Files,  Prev: Calling External Code from Oct-Files,  Up: Oct-Files

A.1.10 Allocating Local Memory in Oct-Files
-------------------------------------------

Allocating memory within an oct-file might seem easy, as the C++
new/delete operators can be used.  However, in that case great care must
be taken to avoid memory leaks.  The preferred manner in which to
allocate memory for use locally is to use the ‘OCTAVE_LOCAL_BUFFER’
macro.  An example of its use is

     OCTAVE_LOCAL_BUFFER (double, tmp, len)

that returns a pointer ‘tmp’ of type ‘double *’ of length ‘len’.

   In this case, Octave itself will worry about reference counting and
variable scope and will properly free memory without programmer
intervention.


File: octave.info,  Node: Input Parameter Checking in Oct-Files,  Next: Exception and Error Handling in Oct-Files,  Prev: Allocating Local Memory in Oct-Files,  Up: Oct-Files

A.1.11 Input Parameter Checking in Oct-Files
--------------------------------------------

Because oct-files are compiled functions they open up the possibility of
crashing Octave through careless function calls or memory faults.  It is
quite important that each and every function have a sufficient level of
parameter checking to ensure that Octave behaves well.

   The minimum requirement, as previously discussed, is to check the
number of input arguments before using them to avoid referencing a
nonexistent argument.  However, in some cases this might not be
sufficient as the underlying code imposes further constraints.  For
example, an external function call might be undefined if the input
arguments are not integers, or if one of the arguments is zero, or if
the input is complex and a real value was expected.  Therefore,
oct-files often need additional input parameter checking.

   There are several functions within Octave that can be useful for the
purposes of parameter checking.  These include the methods of the
‘octave_value’ class like ‘is_real_matrix’, ‘is_numeric_type’, etc.
(see ‘ov.h’).  Often, with a knowledge of the Octave m-file language,
you can guess at what the corresponding C++ routine will.  In addition
there are some more specialized input validation functions of which a
few are demonstrated below.

     #include <octave/oct.h>
     
     DEFUN_DLD (paramdemo, args, nargout, "Parameter Check Demo")
     {
       if (args.length () != 1)
         print_usage ();
     
       NDArray m = args(0).array_value ();
     
       double min_val = -10.0;
       double max_val = 10.0;
     
       octave_stdout << "Properties of input array:\n";
     
       if (m.any_element_is_negative ())
         octave_stdout << "  includes negative values\n";
     
       if (m.any_element_is_inf_or_nan ())
         octave_stdout << "  includes Inf or NaN values\n";
     
       if (m.any_element_not_one_or_zero ())
         octave_stdout << "  includes other values than 1 and 0\n";
     
       if (m.all_elements_are_int_or_inf_or_nan ())
         octave_stdout << "  includes only int, Inf or NaN values\n";
     
       if (m.all_integers (min_val, max_val))
         octave_stdout << "  includes only integers in [-10,10]\n";
     
       return octave_value_list ();
     }

An example of its use is:

     paramdemo ([1, 2, NaN, Inf])
     ⇒ Properties of input array:
          includes Inf or NaN values
          includes other values than 1 and 0
          includes only int, Inf or NaN values


File: octave.info,  Node: Exception and Error Handling in Oct-Files,  Next: Documentation and Testing of Oct-Files,  Prev: Input Parameter Checking in Oct-Files,  Up: Oct-Files

A.1.12 Exception and Error Handling in Oct-Files
------------------------------------------------

Another important feature of Octave is its ability to react to the user
typing <Control-C> during extended calculations.  This ability is based
on the C++ exception handler, where memory allocated by the C++
new/delete methods is automatically released when the exception is
treated.  When writing an oct-file which may run for a long time the
programmer must periodically use the macro ‘OCTAVE_QUIT’, in order to
allow Octave to check and possibly respond to a user typing <Control-C>.
For example:

     for (octave_idx_type i = 0; i < a.nelem (); i++)
       {
         OCTAVE_QUIT;
         b.elem (i) = 2. * a.elem (i);
       }

   The presence of the ‘OCTAVE_QUIT’ macro in the inner loop allows
Octave to detect and acknowledge a <Control-C> key sequence.  Without
this macro, the user must either wait for the oct-file function to
return before the interrupt is processed, or the user must press
<Control-C> three times which will force Octave to exit completely.

   The ‘OCTAVE_QUIT’ macro does impose a very small performance penalty;
For loops that are known to be small it may not make sense to include
‘OCTAVE_QUIT’.

   When creating an oct-file that uses an external library, the function
might spend a significant portion of its time in the external library.
It is not generally possible to use the ‘OCTAVE_QUIT’ macro in this
case.  The alternative code in this case is

     BEGIN_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
     ...  some code that calls a "foreign" function ...
     END_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;

   The disadvantage of this is that if the foreign code allocates any
memory internally, then this memory might be lost during an interrupt,
without being deallocated.  Therefore, ideally Octave itself should
allocate any memory that is needed by the foreign code, with either the
‘fortran_vec’ method or the ‘OCTAVE_LOCAL_BUFFER’ macro.

   The Octave ‘unwind_protect’ mechanism (*note The unwind_protect
Statement::) can also be used in oct-files.  In conjunction with the
exception handling of Octave, it ensures that certain recovery code is
always run even if an exception occurs.  An example of the use of this
mechanism is

     #include <octave/oct.h>
     #include <octave/unwind-prot.h>
     
     void
     my_err_handler (const char *fmt, ...)
     {
       // Do nothing!!
     }
     
     void
     my_err_with_id_handler (const char *id, const char *fmt, ...)
     {
       // Do nothing!!
     }
     
     DEFUN_DLD (unwinddemo, args, nargout, "Unwind Demo")
     {
       if (args.length () < 2)
         print_usage ();
     
       NDArray a = args(0).array_value ();
       NDArray b = args(1).array_value ();
     
       // Create unwind_action objects.  At the end of the enclosing scope,
       // destructors for these objects will call the given functions with
       // the specified arguments.
     
       octave::unwind_action restore_warning_handler
         (set_liboctave_warning_handler, current_liboctave_warning_handler);
     
       octave::unwind_action restore_warning_with_id_handler
         (set_liboctave_warning_with_id_handler,
          current_liboctave_warning_with_id_handler);
     
       set_liboctave_warning_handler (my_err_handler);
       set_liboctave_warning_with_id_handler (my_err_with_id_handler);
     
       return octave_value (quotient (a, b));
     }

   As can be seen in the example:

     unwinddemo (1, 0)
     ⇒ Inf
     1 / 0
     ⇒ warning: division by zero
        Inf

   The warning for division by zero (and in fact all warnings) are
disabled in the ‘unwinddemo’ function.


File: octave.info,  Node: Documentation and Testing of Oct-Files,  Prev: Exception and Error Handling in Oct-Files,  Up: Oct-Files

A.1.13 Documentation and Testing of Oct-Files
---------------------------------------------

The documentation for an oct-file is contained in the fourth string
parameter of the ‘DEFUN_DLD’ macro.  This string can be formatted in the
same manner as the help strings for user functions, however there are
some issues that are particular to the formatting of help strings within
oct-files.

   The major issue is that the help string will typically be longer than
a single line of text, and so the formatting of long multi-line help
strings needs to be taken into account.  There are several possible
solutions, but the most common is illustrated in the following example,

     DEFUN_DLD (do_what_i_want, args, nargout,
       "-*- texinfo -*-\n\
     @deftypefn {} {} do_what_i_say (@var{n})\n\
     A function that does what the user actually wants rather\n\
     than what they requested.\n\
     @end deftypefn")
     {
     ...
     }

where each line of text is terminated by ‘\n\’ which is an embedded
newline in the string together with a C++ string continuation character.
Note that the final ‘\’ must be the last character on the line.

   Octave also includes the ability to embed test and demonstration code
for a function within the code itself (*note Test and Demo Functions::).
This can be used from within oct-files (or in fact any file) with
certain provisos.  First, the test and demo functions of Octave look for
‘%!’ as the first two characters of a line to identify test and
demonstration code.  This is a requirement for oct-files as well.  In
addition, the test and demonstration code must be wrapped in a comment
block to avoid it being interpreted by the compiler.  Finally, the
Octave test and demonstration code must have access to the original
source code of the oct-file—not just the compiled code—as the tests are
stripped from the compiled code.  An example in an oct-file might be

     /*
     %!assert (sin ([1,2]), [sin(1),sin(2)])
     %!error (sin ())
     %!error (sin (1,1))
     */


File: octave.info,  Node: Mex-Files,  Next: Standalone Programs,  Prev: Oct-Files,  Up: External Code Interface

A.2 Mex-Files
=============

Octave includes an interface to allow legacy mex-files to be compiled
and used with Octave.  This interface can also be used to share compiled
code between Octave and MATLAB users.  However, as mex-files expose
MATLAB’s internal API, and the internal structure of Octave is
different, a mex-file can never have the same performance in Octave as
the equivalent oct-file.  In particular, to support the manner in which
variables are passed to mex functions there are a significant number of
additional copies of memory blocks when invoking or returning from a
mex-file function.  For this reason, it is recommended that any new code
be written with the oct-file interface previously discussed.

* Menu:

* Getting Started with Mex-Files::
* Working with Matrices and Arrays in Mex-Files::
* Character Strings in Mex-Files::
* Cell Arrays with Mex-Files::
* Structures with Mex-Files::
* Sparse Matrices with Mex-Files::
* Calling Other Functions in Mex-Files::


File: octave.info,  Node: Getting Started with Mex-Files,  Next: Working with Matrices and Arrays in Mex-Files,  Up: Mex-Files

A.2.1 Getting Started with Mex-Files
------------------------------------

The basic command to build a mex-file is either ‘mkoctfile --mex’ or
‘mex’.  The first command can be used either from within Octave or from
the command line.  To avoid issues with MATLAB’s own ‘mex’ command, the
use of the command ‘mex’ is limited to within Octave.  Compiled
mex-files have the extension ‘.mex’.

 -- : mex [-options] file ...
 -- : status = mex (...)
     Compile source code written in C, C++, or Fortran, to a MEX file.

     STATUS is the return status of the ‘mkoctfile’ function.

     If the compilation fails, and the output argument is not requested,
     an error is raised.  If the programmer requests STATUS, however,
     Octave will merely issue a warning and it is the programmer’s
     responsibility to verify the command was successful.

     This is equivalent to ‘mkoctfile --mex [-options] file’.

     See also: *note mkoctfile: XREFmkoctfile, *note mexext: XREFmexext.

 -- : EXT = mexext ()
     Return the filename extension used for MEX files.

     Programming Note: Octave uses the extension ‘mex’ for all MEX files
     regardless of the operating system (Linux, Windows, Apple) or the
     bit-width (32-bit or 64-bit) of the hardware.

     See also: *note mex: XREFmex.

   Consider the following short example:

     #include "mex.h"
     
     void
     mexFunction (int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[])
     {
       mexPrintf ("Hello, World!\n");
     
       mexPrintf ("I have %d inputs and %d outputs\n", nrhs, nlhs);
     
       /* Return empty matrices for any outputs */
       int i;
       for (i = 0; i < nlhs; i++)
         plhs[i] = mxCreateDoubleMatrix (0, 0, mxREAL);
     }

   The first line ‘#include "mex.h"’ makes available all of the
definitions necessary for a mex-file.  One important difference between
Octave and MATLAB is that the header file "matrix.h" is implicitly
included through the inclusion of "mex.h".  This is necessary to avoid a
conflict with the Octave file "Matrix.h" for operating systems and
compilers that don’t distinguish between filenames in upper and lower
case.

   The entry point into the mex-file is defined by ‘mexFunction’.  The
function takes four arguments:

  1. The number of return arguments (# of left-hand side args).

  2. An array of pointers to return arguments.

  3. The number of input arguments (# of right-hand side args).

  4. An array of pointers to input arguments.

   Note that the function name definition is not explicitly included in
‘mexFunction’ and so there can only be a single ‘mexFunction’ entry
point per file.  Instead, the name of the function as seen in Octave is
determined by the name of the mex-file itself minus the extension.  If
the above function is in the file ‘myhello.c’, it can be compiled with

     mkoctfile --mex myhello.c

which creates a file ‘myhello.mex’.  The function can then be run from
Octave as

     myhello (1,2,3)
     ⇒ Hello, World!
     ⇒ I have 3 inputs and 0 outputs

   It should be noted that the mex-file contains no help string.  To
document mex-files, there should exist an m-file in the same directory
as the mex-file itself.  Taking the above as an example, there would
need to be a file ‘myhello.m’ which might contain the text

     %MYHELLO Simple test of the functionality of a mex-file.

   In this case, the function that will be executed within Octave will
be given by the mex-file, while the help string will come from the
m-file.  This can also be useful to allow a sample implementation of the
mex-file within the Octave language itself for testing purposes.

   Although there cannot be multiple entry points in a single mex-file,
one can use the ‘mexFunctionName’ function to determine what name the
mex-file was called with.  This can be used to alter the behavior of the
mex-file based on the function name.  For example, if

     #include "mex.h"
     
     void
     mexFunction (int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[])
     {
       const char *nm;
     
       nm = mexFunctionName ();
       mexPrintf ("You called function: %s\n", nm);
       if (strcmp (nm, "myfunc") == 0)
         mexPrintf ("This is the principal function\n", nm);
     
       return;
     }

is in the file ‘myfunc.c’, and is compiled with

     mkoctfile --mex myfunc.c
     ln -s myfunc.mex myfunc2.mex

then as can be seen by

     myfunc ()
     ⇒ You called function: myfunc
         This is the principal function
     myfunc2 ()
     ⇒ You called function: myfunc2

the behavior of the mex-file can be altered depending on the function’s
name.

   Although the user should only include ‘mex.h’ in their code, Octave
declares additional functions, typedefs, etc., available to the user to
write mex-files in the headers ‘mexproto.h’ and ‘mxarray.h’.


File: octave.info,  Node: Working with Matrices and Arrays in Mex-Files,  Next: Character Strings in Mex-Files,  Prev: Getting Started with Mex-Files,  Up: Mex-Files

A.2.2 Working with Matrices and Arrays in Mex-Files
---------------------------------------------------

The basic mex type of all variables is ‘mxArray’.  Any object, such as a
matrix, cell array, or structure, is stored in this basic type.
‘mxArray’ serves essentially the same purpose as the ‘octave_value’
class in oct-files in that it acts as a container for all the more
specialized types.

   The ‘mxArray’ structure contains at a minimum, the name of the
variable it represents, its dimensions, its type, and whether the
variable is real or complex.  It can also contain a number of additional
fields depending on the type of the ‘mxArray’.  There are a number of
functions to create ‘mxArray’ structures, including
‘mxCreateDoubleMatrix’, ‘mxCreateCellArray’, ‘mxCreateSparse’, and the
generic ‘mxCreateNumericArray’.

   The basic function to access the data in an array is ‘mxGetPr’.
Because the mex interface assumes that real and imaginary parts of a
complex array are stored separately, there is an equivalent function
‘mxGetPi’ that gets the imaginary part.  Both of these functions are
only for use with double precision matrices.  The generic functions
‘mxGetData’ and ‘mxGetImagData’ perform the same operation for all
matrix types.  For example:

     mxArray *m;
     mwSize *dims;
     UINT32_T *pr;

     dims = (mwSize *) mxMalloc (2 * sizeof (mwSize));
     dims[0] = 2; dims[1] = 2;
     m = mxCreateNumericArray (2, dims, mxUINT32_CLASS, mxREAL);
     pr = (UINT32_T *) mxGetData (m);

   There are also the functions ‘mxSetPr’, etc., that perform the
inverse, and set the data of an array to use the block of memory pointed
to by the argument of ‘mxSetPr’.

   Note the type ‘mwSize’ used above, and also ‘mwIndex’, are defined as
the native precision of the indexing in Octave on the platform on which
the mex-file is built.  This allows both 32- and 64-bit platforms to
support mex-files.  ‘mwSize’ is used to define array dimensions and the
maximum number or elements, while ‘mwIndex’ is used to define indexing
into arrays.

   An example that demonstrates how to work with arbitrary real or
complex double precision arrays is given by the file ‘mypow2.c’ shown
below.

     #include "mex.h"
     
     void
     mexFunction (int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[])
     {
       mwSize n;
       mwIndex i;
       double *vri, *vro;
     
       if (nrhs != 1 || ! mxIsDouble (prhs[0]))
         mexErrMsgTxt ("ARG1 must be a double matrix");
     
       n = mxGetNumberOfElements (prhs[0]);
       plhs[0] = mxCreateNumericArray (mxGetNumberOfDimensions (prhs[0]),
                                       mxGetDimensions (prhs[0]),
                                       mxGetClassID (prhs[0]),
                                       mxIsComplex (prhs[0]));
       vri = mxGetPr (prhs[0]);
       vro = mxGetPr (plhs[0]);
     
       if (mxIsComplex (prhs[0]))
         {
           double *vii, *vio;
           vii = mxGetPi (prhs[0]);
           vio = mxGetPi (plhs[0]);
     
           for (i = 0; i < n; i++)
             {
               vro[i] = vri[i] * vri[i] - vii[i] * vii[i];
               vio[i] = 2 * vri[i] * vii[i];
             }
         }
       else
         {
           for (i = 0; i < n; i++)
             vro[i] = vri[i] * vri[i];
         }
     }

An example of its use is

     b = randn (4,1) + 1i * randn (4,1);
     all (b.^2 == mypow2 (b))
     ⇒ 1

   The example above uses the functions ‘mxGetDimensions’,
‘mxGetNumberOfElements’, and ‘mxGetNumberOfDimensions’ to work with the
dimensions of multi-dimensional arrays.  The functions ‘mxGetM’, and
‘mxGetN’ are also available to find the number of rows and columns in a
2-D matrix (MxN matrix).


File: octave.info,  Node: Character Strings in Mex-Files,  Next: Cell Arrays with Mex-Files,  Prev: Working with Matrices and Arrays in Mex-Files,  Up: Mex-Files

A.2.3 Character Strings in Mex-Files
------------------------------------

As mex-files do not make the distinction between single and double
quoted strings that Octave does, there is perhaps less complexity in the
use of strings and character matrices.  An example of their use that
parallels the demo in ‘stringdemo.cc’ is given in the file ‘mystring.c’,
as shown below.

     #include <string.h>
     #include "mex.h"
     
     void
     mexFunction (int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[])
     {
       mwSize m, n;
       mwIndex i, j;
       mxChar *pi, *po;
     
       if (nrhs != 1 || ! mxIsChar (prhs[0])
           || mxGetNumberOfDimensions (prhs[0]) > 2)
         mexErrMsgTxt ("ARG1 must be a char matrix");
     
       m = mxGetM (prhs[0]);
       n = mxGetN (prhs[0]);
       pi = mxGetChars (prhs[0]);
       plhs[0] = mxCreateNumericMatrix (m, n, mxCHAR_CLASS, mxREAL);
       po = mxGetChars (plhs[0]);
     
       for (j = 0; j < n; j++)
         for (i = 0; i < m; i++)
           po[j*m + m - 1 - i] = pi[j*m + i];
     }

An example of its expected output is

     mystring (["First String"; "Second String"])
     ⇒ Second String
        First String

   Other functions in the mex interface for handling character strings
are ‘mxCreateString’, ‘mxArrayToString’, and
‘mxCreateCharMatrixFromStrings’.  In a mex-file, a character string is
considered to be a vector rather than a matrix.  This is perhaps an
arbitrary distinction as the data in the ‘mxArray’ for the matrix is
consecutive in any case.


File: octave.info,  Node: Cell Arrays with Mex-Files,  Next: Structures with Mex-Files,  Prev: Character Strings in Mex-Files,  Up: Mex-Files

A.2.4 Cell Arrays with Mex-Files
--------------------------------

One can perform exactly the same operations on Cell arrays in mex-files
as in oct-files.  An example that duplicates the function of the
‘celldemo.cc’ oct-file in a mex-file is given by ‘mycell.c’ as shown
below.

     #include "mex.h"
     
     void
     mexFunction (int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[])
     {
       mwSize n;
       mwIndex i;
     
       if (nrhs != 1 || ! mxIsCell (prhs[0]))
         mexErrMsgTxt ("ARG1 must be a cell");
     
       n = mxGetNumberOfElements (prhs[0]);
       n = (n > nlhs ? nlhs : n);
     
       for (i = 0; i < n; i++)
         plhs[i] = mxDuplicateArray (mxGetCell (prhs[0], i));
     }

The output is identical to the oct-file version as well.

     [b1, b2, b3] = mycell ({1, [1, 2], "test"})
     ⇒
     b1 =  1
     b2 =

        1   2

     b3 = test

   Note in the example the use of the ‘mxDuplicateArray’ function.  This
is needed as the ‘mxArray’ pointer returned by ‘mxGetCell’ might be
deallocated.  The inverse function to ‘mxGetCell’, used for setting Cell
values, is ‘mxSetCell’ and is defined as

     void mxSetCell (mxArray *ptr, int idx, mxArray *val);

   Finally, to create a cell array or matrix, the appropriate functions
are

     mxArray *mxCreateCellArray (int ndims, const int *dims);
     mxArray *mxCreateCellMatrix (int m, int n);


File: octave.info,  Node: Structures with Mex-Files,  Next: Sparse Matrices with Mex-Files,  Prev: Cell Arrays with Mex-Files,  Up: Mex-Files

A.2.5 Structures with Mex-Files
-------------------------------

The basic function to create a structure in a mex-file is
‘mxCreateStructMatrix’ which creates a structure array with a two
dimensional matrix, or ‘mxCreateStructArray’.

     mxArray *mxCreateStructArray (int ndims, int *dims,
                                   int num_keys,
                                   const char **keys);
     mxArray *mxCreateStructMatrix (int rows, int cols,
                                    int num_keys,
                                    const char **keys);

   Accessing the fields of the structure can then be performed with
‘mxGetField’ and ‘mxSetField’ or alternatively with the
‘mxGetFieldByNumber’ and ‘mxSetFieldByNumber’ functions.

     mxArray *mxGetField (const mxArray *ptr, mwIndex index,
                          const char *key);
     mxArray *mxGetFieldByNumber (const mxArray *ptr,
                                  mwIndex index, int key_num);
     void mxSetField (mxArray *ptr, mwIndex index,
                      const char *key, mxArray *val);
     void mxSetFieldByNumber (mxArray *ptr, mwIndex index,
                              int key_num, mxArray *val);

   A difference between the oct-file interface to structures and the
mex-file version is that the functions to operate on structures in
mex-files directly include an ‘index’ over the elements of the arrays of
elements per ‘field’; Whereas, the oct-file structure includes a Cell
Array per field of the structure.

   An example that demonstrates the use of structures in a mex-file can
be found in the file ‘mystruct.c’ shown below.

     #include "mex.h"
     
     void
     mexFunction (int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[])
     {
       int i;
       mwIndex j;
       mxArray *v;
       const char *keys[] = { "this", "that" };
     
       if (nrhs != 1 || ! mxIsStruct (prhs[0]))
         mexErrMsgTxt ("ARG1 must be a struct");
     
       for (i = 0; i < mxGetNumberOfFields (prhs[0]); i++)
         for (j = 0; j < mxGetNumberOfElements (prhs[0]); j++)
           {
             mexPrintf ("field %s(%d) = ", mxGetFieldNameByNumber (prhs[0], i), j);
             v = mxGetFieldByNumber (prhs[0], j, i);
             mexCallMATLAB (0, NULL, 1, &v, "disp");
           }
     
       v = mxCreateStructMatrix (2, 2, 2, keys);
     
       mxSetFieldByNumber (v, 0, 0, mxCreateString ("this1"));
       mxSetFieldByNumber (v, 0, 1, mxCreateString ("that1"));
       mxSetFieldByNumber (v, 1, 0, mxCreateString ("this2"));
       mxSetFieldByNumber (v, 1, 1, mxCreateString ("that2"));
       mxSetFieldByNumber (v, 2, 0, mxCreateString ("this3"));
       mxSetFieldByNumber (v, 2, 1, mxCreateString ("that3"));
       mxSetFieldByNumber (v, 3, 0, mxCreateString ("this4"));
       mxSetFieldByNumber (v, 3, 1, mxCreateString ("that4"));
     
       if (nlhs)
         plhs[0] = v;
     }

   An example of the behavior of this function within Octave is then

     a(1).f1 = "f11"; a(1).f2 = "f12";
     a(2).f1 = "f21"; a(2).f2 = "f22";
     b = mystruct (a);
     ⇒  field f1(0) = f11
         field f1(1) = f21
         field f2(0) = f12
         field f2(1) = f22
     b
     ⇒ 2x2 struct array containing the fields:

          this
          that

     b(3)
     ⇒ scalar structure containing the fields:

          this = this3
          that = that3


File: octave.info,  Node: Sparse Matrices with Mex-Files,  Next: Calling Other Functions in Mex-Files,  Prev: Structures with Mex-Files,  Up: Mex-Files

A.2.6 Sparse Matrices with Mex-Files
------------------------------------

The Octave format for sparse matrices is identical to the mex format in
that it is a compressed column sparse format.  Also, in both
implementations sparse matrices are required to be two-dimensional.  The
only difference of importance to the programmer is that the real and
imaginary parts of the matrix are stored separately.

   The mex-file interface, in addition to using ‘mxGetM’, ‘mxGetN’,
‘mxSetM’, ‘mxSetN’, ‘mxGetPr’, ‘mxGetPi’, ‘mxSetPr’, and ‘mxSetPi’, also
supplies the following functions.

     mwIndex *mxGetIr (const mxArray *ptr);
     mwIndex *mxGetJc (const mxArray *ptr);
     mwSize mxGetNzmax (const mxArray *ptr);

     void mxSetIr (mxArray *ptr, mwIndex *ir);
     void mxSetJc (mxArray *ptr, mwIndex *jc);
     void mxSetNzmax (mxArray *ptr, mwSize nzmax);

‘mxGetNzmax’ gets the maximum number of elements that can be stored in
the sparse matrix.  This is not necessarily the number of nonzero
elements in the sparse matrix.  ‘mxGetJc’ returns an array with one
additional value than the number of columns in the sparse matrix.  The
difference between consecutive values of the array returned by ‘mxGetJc’
define the number of nonzero elements in each column of the sparse
matrix.  Therefore,

     mwSize nz, n;
     mwIndex *Jc;
     mxArray *m;
     ...
     n = mxGetN (m);
     Jc = mxGetJc (m);
     nz = Jc[n];

returns the actual number of nonzero elements stored in the matrix in
‘nz’.  As the arrays returned by ‘mxGetPr’ and ‘mxGetPi’ only contain
the nonzero values of the matrix, we also need a pointer to the rows of
the nonzero elements, and this is given by ‘mxGetIr’.  A complete
example of the use of sparse matrices in mex-files is given by the file
‘mysparse.c’ shown below.

     #include "mex.h"
     
     void
     mexFunction (int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[])
     {
       mwSize m, n, nz;
       mxArray *v;
       mwIndex i;
       double *pr, *pi;
       double *pr2, *pi2;
       mwIndex *ir, *jc;
       mwIndex *ir2, *jc2;
     
       if (nrhs != 1 || ! mxIsSparse (prhs[0]))
         mexErrMsgTxt ("ARG1 must be a sparse matrix");
     
       m = mxGetM (prhs[0]);
       n = mxGetN (prhs[0]);
       nz = mxGetNzmax (prhs[0]);
     
       if (mxIsComplex (prhs[0]))
         {
           mexPrintf ("Matrix is %d-by-%d complex sparse matrix", m, n);
           mexPrintf (" with %d elements\n", nz);
     
           pr = mxGetPr (prhs[0]);
           pi = mxGetPi (prhs[0]);
           ir = mxGetIr (prhs[0]);
           jc = mxGetJc (prhs[0]);
     
           i = n;
           while (jc[i] == jc[i-1] && i != 0) i--;
     
           mexPrintf ("last nonzero element (%d, %d) = (%g, %g)\n",
                      ir[nz-1]+ 1, i, pr[nz-1], pi[nz-1]);
     
           v = mxCreateSparse (m, n, nz, mxCOMPLEX);
           pr2 = mxGetPr (v);
           pi2 = mxGetPi (v);
           ir2 = mxGetIr (v);
           jc2 = mxGetJc (v);
     
           for (i = 0; i < nz; i++)
             {
               pr2[i] = 2 * pr[i];
               pi2[i] = 2 * pi[i];
               ir2[i] = ir[i];
             }
           for (i = 0; i < n + 1; i++)
             jc2[i] = jc[i];
     
           if (nlhs > 0)
             plhs[0] = v;
         }
       else if (mxIsLogical (prhs[0]))
         {
           mxLogical *pbr, *pbr2;
           mexPrintf ("Matrix is %d-by-%d logical sparse matrix", m, n);
           mexPrintf (" with %d elements\n", nz);
     
           pbr = mxGetLogicals (prhs[0]);
           ir = mxGetIr (prhs[0]);
           jc = mxGetJc (prhs[0]);
     
           i = n;
           while (jc[i] == jc[i-1] && i != 0) i--;
           mexPrintf ("last nonzero element (%d, %d) = %d\n",
                      ir[nz-1]+ 1, i, pbr[nz-1]);
     
           v = mxCreateSparseLogicalMatrix (m, n, nz);
           pbr2 = mxGetLogicals (v);
           ir2 = mxGetIr (v);
           jc2 = mxGetJc (v);
     
           for (i = 0; i < nz; i++)
             {
               pbr2[i] = pbr[i];
               ir2[i] = ir[i];
             }
           for (i = 0; i < n + 1; i++)
             jc2[i] = jc[i];
     
           if (nlhs > 0)
             plhs[0] = v;
         }
       else
         {
           mexPrintf ("Matrix is %d-by-%d real sparse matrix", m, n);
           mexPrintf (" with %d elements\n", nz);
     
           pr = mxGetPr (prhs[0]);
           ir = mxGetIr (prhs[0]);
           jc = mxGetJc (prhs[0]);
     
           i = n;
           while (jc[i] == jc[i-1] && i != 0) i--;
           mexPrintf ("last nonzero element (%d, %d) = %g\n",
                      ir[nz-1]+ 1, i, pr[nz-1]);
     
           v = mxCreateSparse (m, n, nz, mxREAL);
           pr2 = mxGetPr (v);
           ir2 = mxGetIr (v);
           jc2 = mxGetJc (v);
     
           for (i = 0; i < nz; i++)
             {
               pr2[i] = 2 * pr[i];
               ir2[i] = ir[i];
             }
           for (i = 0; i < n + 1; i++)
             jc2[i] = jc[i];
     
           if (nlhs > 0)
             plhs[0] = v;
         }
     }

   A sample usage of ‘mysparse’ is

     sm = sparse ([1, 0; 0, pi]);
     mysparse (sm)
     ⇒
     Matrix is 2-by-2 real sparse matrix with 2 elements
     last nonzero element (2, 2) = 3.14159


File: octave.info,  Node: Calling Other Functions in Mex-Files,  Prev: Sparse Matrices with Mex-Files,  Up: Mex-Files

A.2.7 Calling Other Functions in Mex-Files
------------------------------------------

It is possible to call other Octave functions from within a mex-file
using ‘mexCallMATLAB’.  An example of the use of ‘mexCallMATLAB’ can be
see in the example below.

     #include "mex.h"
     
     void
     mexFunction (int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[])
     {
       char *str;
     
       mexPrintf ("Starting file myfeval.mex\n");
     
       mexPrintf ("I have %d inputs and %d outputs\n", nrhs, nlhs);
     
       if (nrhs < 1 || ! mxIsChar (prhs[0]))
         mexErrMsgTxt ("ARG1 must be a function name");
     
       str = mxArrayToString (prhs[0]);
     
       mexPrintf ("I'm going to call the function %s\n", str);
     
       if (nlhs == 0)
         nlhs = 1;  // Octave's automatic 'ans' variable
     
       /* Cast prhs just to get rid of 'const' qualifier and stop compile warning */
       mexCallMATLAB (nlhs, plhs, nrhs-1, (mxArray**)prhs+1, str);
     
       mxFree (str);
     }

   If this code is in the file ‘myfeval.c’, and is compiled to
‘myfeval.mex’, then an example of its use is

     a = myfeval ("sin", 1)
     ⇒ Starting file myfeval.mex
        I have 2 inputs and 1 outputs
        I'm going to call the interpreter function sin
        a =  0.84147

   Note that it is not possible to use function handles within a
mex-file.


File: octave.info,  Node: Standalone Programs,  Next: Java Interface,  Prev: Mex-Files,  Up: External Code Interface

A.3 Standalone Programs
=======================

The libraries Octave uses itself can be utilized in standalone
applications.  These applications then have access, for example, to the
array and matrix classes, as well as to all of the Octave algorithms.
The following C++ program, uses class Matrix from ‘liboctave.a’ or
‘liboctave.so’.

     #include <iostream>
     #include <octave/oct.h>
     
     int
     main (void)
     {
       std::cout << "Hello Octave world!\n";
     
       int n = 2;
       Matrix a_matrix = Matrix (n, n);
     
       for (octave_idx_type i = 0; i < n; i++)
         for (octave_idx_type j = 0; j < n; j++)
           a_matrix(i,j) = (i + 1) * 10 + (j + 1);
     
       std::cout << a_matrix;
     
       return 0;
     }

mkoctfile can be used to build a standalone application with a command
like

     $ mkoctfile --link-stand-alone standalone.cc -o standalone
     $ ./standalone
     Hello Octave world!
       11 12
       21 22
     $

   Note that the application ‘standalone’ will be dynamically linked
against the Octave libraries and any Octave support libraries.  The
above allows the Octave math libraries to be used by an application.  It
does not, however, allow the script files, oct-files, or built-in
functions of Octave to be used by the application.  To do that, the
Octave interpreter needs to be initialized first.  An example of how to
do this can then be seen in the code

     #include <iostream>
     #include <octave/oct.h>
     #include <octave/octave.h>
     #include <octave/parse.h>
     #include <octave/interpreter.h>
     
     int
     main (void)
     {
       // Create interpreter.
     
       octave::interpreter interpreter;
     
       try
         {
           // Inhibit reading history file by calling
           //
           //   interpreter.initialize_history (false);
     
           // Set custom load path here if you wish by calling
           //
           //   interpreter.initialize_load_path (false);
     
           // Perform final initialization of interpreter, including
           // executing commands from startup files by calling
           //
           //   interpreter.initialize ();
           //
           //   if (! interpreter.initialized ())
           //     {
           //       std::cerr << "Octave interpreter initialization failed!"
           //                 << std::endl;
           //       exit (status);
           //     }
           //
           // You may skip this step if you don't need to do anything
           // between reading the startup files and telling the interpreter
           // that you are ready to execute commands.
     
           // Tell the interpreter that we're ready to execute commands:
     
           int status = interpreter.execute ();
     
           if (status != 0)
             {
               std::cerr << "creating embedded Octave interpreter failed!"
                         << std::endl;
               return status;
             }
     
           octave_idx_type n = 2;
           octave_value_list in;
     
           for (octave_idx_type i = 0; i < n; i++)
             in(i) = octave_value (5 * (i + 2));
     
           octave_value_list out = octave::feval ("gcd", in, 1);
     
           if (out.length () > 0)
             std::cout << "GCD of ["
                       << in(0).int_value ()
                       << ", "
                       << in(1).int_value ()
                       << "] is " << out(0).int_value ()
                       << std::endl;
           else
             std::cout << "invalid\n";
         }
       catch (const octave::exit_exception& ex)
         {
           std::cerr << "Octave interpreter exited with status = "
                     << ex.exit_status () << std::endl;
         }
       catch (const octave::execution_exception&)
         {
           std::cerr << "error encountered in Octave evaluator!" << std::endl;
         }
     
       return 0;
     }

which, as before, is compiled and run as a standalone application with

     $ mkoctfile --link-stand-alone embedded.cc -o embedded
     $ ./embedded
     GCD of [10, 15] is 5
     $

   It is worth re-iterating that, if only built-in functions are to be
called from a C++ standalone program then it does not need to initialize
the interpreter.  The general rule is that for a built-in function named
‘function_name’ in the interpreter, there will be a C++ function named
‘Ffunction_name’ (note the prepended capital ‘F’) accessible in the C++
API.  The declarations for all built-in functions are collected in the
header file ‘builtin-defun-decls.h’.  This feature should be used with
care as the list of built-in functions can change.  No guarantees can be
made that a function that is currently a built-in won’t be implemented
as a ‘.m’ file or as a dynamically linked function in the future.  An
example of how to call built-in functions from C++ can be seen in the
code

     #include <iostream>
     #include <octave/oct.h>
     #include <octave/builtin-defun-decls.h>
     
     int
     main (void)
     {
       int n = 2;
       Matrix a_matrix = Matrix (n, n);
     
       for (octave_idx_type i = 0; i < n; i++)
         for (octave_idx_type j = 0; j < n; j++)
           a_matrix(i,j) = (i + 1) * 10 + (j + 1);
     
       std::cout << "This is a matrix:" << std::endl
                 << a_matrix            << std::endl;
     
       octave_value_list in;
       in(0) = a_matrix;
     
       octave_value_list out = Fnorm (in, 1);
       double norm_of_the_matrix = out(0).double_value ();
     
       std::cout << "This is the norm of the matrix:" << std::endl
                 << norm_of_the_matrix                << std::endl;
     
       return 0;
     }

which is compiled and run as a standalone application with

     $ mkoctfile --link-stand-alone standalonebuiltin.cc -o standalonebuiltin
     $ ./standalonebuiltin
     This is a matrix:
      11 12
      21 22

     This is the norm of the matrix:
     34.4952
     $


File: octave.info,  Node: Java Interface,  Prev: Standalone Programs,  Up: External Code Interface

A.4 Java Interface
==================

The Java Interface is designed for calling Java functions from within
Octave.  If you want to do the reverse, and call Octave from within
Java, try a library like ‘joPas’ (<http://jopas.sourceforge.net>).

* Menu:

* Making Java Classes Available::
* How to use Java from within Octave::
* Set up the JVM::
* Java Interface Functions::


File: octave.info,  Node: Making Java Classes Available,  Next: How to use Java from within Octave,  Up: Java Interface

A.4.1 Making Java Classes Available
-----------------------------------

Java finds classes by searching a CLASSPATH which is a list of Java
archive files and/or directories containing class files.  In Octave the
CLASSPATH is composed of two parts:

   • the STATIC CLASSPATH is initialized once at startup of the JVM, and

   • the DYNAMIC CLASSPATH which can be modified at runtime.

   Octave searches the STATIC CLASSPATH first, and then the DYNAMIC
CLASSPATH.  Classes appearing in the STATIC CLASSPATH, as well as in the
DYNAMIC CLASSPATH, will therefore be found in the STATIC CLASSPATH and
loaded from this location.  Classes which will be used frequently, or
must be available to all users, should be added to the STATIC CLASSPATH.
The STATIC CLASSPATH is populated once from the contents of a plain text
file named ‘javaclasspath.txt’ (or ‘classpath.txt’ historically) when
the Java Virtual Machine starts.  This file contains one line for each
individual classpath to be added to the STATIC CLASSPATH.  These lines
can identify directories containing class files, or Java archives with
complete class file hierarchies.  Comment lines starting with a ‘#’ or a
‘%’ character are ignored.

   The search rules for the file ‘javaclasspath.txt’ (or
‘classpath.txt’) are:

   • First, Octave tries to locate it in the current directory (where
     Octave was started from).  If such a file is found, it is read and
     defines the initial STATIC CLASSPATH.  Thus, it is possible to
     define a static classpath on a ’per Octave invocation’ basis.

   • Next, Octave searches in the user’s home directory.  If a file
     ‘javaclasspath.txt’ exists here, its contents are appended to the
     static classpath (if any).  Thus, it is possible to build an
     initial static classpath on a ’per user’ basis.

   • Finally, Octave looks for a ‘javaclasspath.txt’ in the m-file
     directory where Octave Java functions live.  This is where the
     function ‘javaclasspath.m’ resides, usually something like
     ‘OCTAVE_HOME/share/octave/OCTAVE_VERSION/m/java/’.  You can find
     this directory by executing the command

          which javaclasspath

     If this file exists here, its contents are also appended to the
     STATIC CLASSPATH.  Note that the archives and class directories
     defined in this last step will affect all users.

   Classes which are used only by a specific script should be placed in
the DYNAMIC CLASSPATH.  This portion of the classpath can be modified at
runtime using the ‘javaaddpath’ and ‘javarmpath’ functions.

   Example:

     octave> base_path = "C:/Octave/java_files";

     octave> # add two JAR archives to the dynamic classpath
     octave> javaaddpath ([base_path, "/someclasses.jar"]);
     octave> javaaddpath ([base_path, "/moreclasses.jar"]);

     octave> # check the dynamic classpath
     octave> p = javaclasspath;
     octave> disp (p{1});
     C:/Octave/java_files/someclasses.jar
     octave> disp (p{2});
     C:/Octave/java_files/moreclasses.jar

     octave> # remove the first element from the classpath
     octave> javarmpath ([base_path, "/someclasses.jar"]);
     octave> p = javaclasspath;
     octave> disp (p{1});
     C:/Octave/java_files/moreclasses.jar

     octave> # provoke an error
     octave> disp (p{2});
     error: A(I): Index exceeds matrix dimension.

   Another way to add files to the DYNAMIC CLASSPATH exclusively for
your user account is to use the file ‘.octaverc’ which is stored in your
home directory.  All Octave commands in this file are executed each time
you start a new instance of Octave.  The following example adds the
directory ‘octave’ to Octave’s search path and the archive
‘myclasses.jar’ in this directory to the Java search path.

     # contents of .octaverc:
     addpath ("~/octave");
     javaaddpath ("~/octave/myclasses.jar");


File: octave.info,  Node: How to use Java from within Octave,  Next: Set up the JVM,  Prev: Making Java Classes Available,  Up: Java Interface

A.4.2 How to use Java from within Octave
----------------------------------------

The function *note javaObject: XREFjavaObject. creates Java objects.  In
fact it invokes the public constructor of the class with the given name
and with the given parameters.

   The following example shows how to invoke the constructors
‘BigDecimal(double)’ and ‘BigDecimal(String)’ of the builtin Java class
‘java.math.BigDecimal’.

     javaObject ("java.math.BigDecimal",  1.001 );
     javaObject ("java.math.BigDecimal", "1.001");

   Note that parameters of the Octave type ‘double’ are implicitly
converted into the Java type ‘double’ and the Octave type (array of)
‘char’ is converted into the java type ‘String’.  A Java object created
by *note javaObject: XREFjavaObject. is never automatically converted
into an Octave type but remains a Java object.  It can be assigned to an
Octave variable.

     a = 1.001;
     b = javaObject ("java.math.BigDecimal", a);

   Using *note isjava: XREFisjava, it is possible to check whether a
variable is a Java object and its class can be determined as well.  In
addition to the previous example:

     isjava (a)
     ⇒ ans = 0
     class (a)
     ⇒ ans = double
     isjava (b)
     ⇒ ans = 1
     class (b)
     ⇒ ans = java.math.BigDecimal

   The example above can be carried out using only Java objects:

     a = javaObject ("java.lang.Double", 1.001);
     b = javaObject ("java.math.BigDecimal", a);

     isjava (a)
     ⇒ ans = 1
     class (a)
     ⇒ ans = java.lang.Double
     isjava (b)
     ⇒ ans = 1
     class (b)
     ⇒ ans = java.math.BigDecimal

   One can see, that even a ‘java.lang.Double’ is not converted to an
Octave ‘double’, when created by *note javaObject: XREFjavaObject.  But
ambiguities might arise, if the Java classes ‘java.lang.Double’ or
‘double’ are parameters of a method (or a constructor).  In this case
they can be converted into one another, depending on the context.

   Via *note javaObject: XREFjavaObject. one may create all kinds of
Java objects but arrays.  The latter are created through *note
javaArray: XREFjavaArray.

   It is possible to invoke public member methods on Java objects in
Java syntax:

     a.toString
     ⇒ ans = 1.001
     b.toString
     ⇒ ans = 1.000999999999999889865...

   The second result may be surprising, but simply comes from the fact,
that ‘1.001’ cannot exactly be represented as ‘double’, due to rounding.
Note that unlike in Java, in Octave methods without arguments can be
invoked with and without parentheses ‘()’.

   Currently it is not possible to invoke static methods with a Java
like syntax from within Octave.  Instead, one has to use the function
*note javaMethod: XREFjavaMethod. as in the following example:

     java.math.BigDecimal.valueOf(1.001);                    # does not work
     javaMethod ("valueOf", "java.math.BigDecimal", 1.001);  # workaround

   As mentioned before, method and constructor parameters are converted
automatically between Octave and Java types, if appropriate.  For
functions this is also true with return values, whereas for constructors
this is not.

   It is also possible to access public fields of Java objects from
within Octave using Java syntax, with the limitation of static fields:

     java.math.BigDecimal.ONE;                  # does not work
     java_get ("java.math.BigDecimal", "ONE");  # workaround

   Accordingly, with *note java_set: XREFjava_set. the value of a field
can be set.  Note that only public Java fields are accessible from
within Octave.

   The following example indicates that in Octave empty brackets ‘[]’
represent Java’s ‘null’ value and how Java exceptions are represented.

     javaObject ("java.math.BigDecimal", []);
     ⇒ error: [java] java.lang.NullPointerException

   It is not recommended to represent Java’s ‘null’ value by empty
brackets ‘[]’, because ‘null’ has no type whereas ‘[]’ has type
‘double’.

   In Octave it is possible to provide limited Java reflection by
listing the public fields and methods of a Java object, both static or
not.

     fieldnames (<Java object>)
     methods (<Java object>)

   Finally, an examples is shown how to access the stack trace from
within Octave, where the function *note debug_java: XREFdebug_java. is
used to set and to get the current debug state.  In debug mode, the Java
error and the stack trace are displayed.

     debug_java (true)  # use "false" to omit display of stack trace
     debug_java ()
     ⇒ ans = 1
     javaObject ("java.math.BigDecimal", "1") ...
       .divide (javaObject ("java.math.BigDecimal", "0"))


File: octave.info,  Node: Set up the JVM,  Next: Java Interface Functions,  Prev: How to use Java from within Octave,  Up: Java Interface

A.4.3 Set up the JVM
--------------------

In order to execute Java code Octave creates a Java Virtual Machine
(JVM). By default the version of the JVM is used that was detected
during configuration on Unix-like systems or that is pointed to from the
registry keys at ‘HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\JRE’ or
‘HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime Environment’ on
Windows.  The default path to the JVM can be overridden by setting the
environment variable ‘JAVA_HOME’ to the path where the JVM is installed.
On Windows that might be, for example, ‘C:\Program
Files\Java\jre-10.0.2’.  Make sure that you select a directory that
contains the JVM with a bit-ness that matches Octave’s.

   The JVM is only loaded once per Octave session.  Thus, to change the
used version of the JVM, you might have to re-start Octave.  To check
which version of the JVM is currently being used, run ‘version -java’.

   The JVM allocates a fixed amount of initial memory and may expand
this pool up to a fixed maximum memory limit.  The default values depend
on the Java version (*note javamem: XREFjavamem.).  The memory pool is
shared by all Java objects running in the JVM.  This strict memory limit
is intended mainly to avoid runaway applications inside web browsers or
in enterprise servers which can consume all memory and crash the system.
When the maximum memory limit is hit, Java code will throw exceptions so
that applications will fail or behave unexpectedly.

   You can specify options for the creation of the JVM inside a file
named ‘java.opts’.  This is a text file where enter you enter lines
containing ‘-X’ and ‘-D’ options that are then passed to the JVM during
initialization.

   The directory where the Java options file is located is specified by
the environment variable ‘OCTAVE_JAVA_DIR’.  If unset the directory
where ‘javaclasspath.m’ resides is used instead (typically
‘OCTAVE_HOME/share/octave/OCTAVE_VERSION/m/java/’).  You can find this
directory by executing

     which javaclasspath

   The ‘-X’ options allow you to increase the maximum amount of memory
available to the JVM.  The following example allows up to 256 Megabytes
to be used by adding the following line to the ‘java.opts’ file:

     -Xmx256m

   The maximum possible amount of memory depends on your system.  On a
Windows system with 2 Gigabytes main memory you should be able to set
this maximum to about 1 Gigabyte.

   If your application requires a large amount of memory from the
beginning, you can also specify the initial amount of memory allocated
to the JVM.  Adding the following line to the ‘java.opts’ file starts
the JVM with 64 Megabytes of initial memory:

     -Xms64m

   For more details on the available ‘-X’ options of your Java Virtual
Machine issue the command ‘java -X’ at the operating system command
prompt and consult the Java documentation.

   The ‘-D’ options can be used to define system properties which can
then be used by Java classes inside Octave.  System properties can be
retrieved by using the ‘getProperty()’ methods of the ‘java.lang.System’
class.  The following example line defines the property MYPROPERTY and
assigns it the string ‘12.34’.

     -DMyProperty=12.34

   The value of this property can then be retrieved as a string by a
Java object or in Octave:

     octave> javaMethod ("getProperty", "java.lang.System", "MyProperty");
     ans = 12.34


File: octave.info,  Node: Java Interface Functions,  Prev: Set up the JVM,  Up: Java Interface

A.4.4 Java Interface Functions
------------------------------

The following functions are the core of the Java Interface.  They
provide a way to create a Java object, get and set its data fields, and
call Java methods which return results to Octave.

 -- : JOBJ = javaObject (CLASSNAME)
 -- : JOBJ = javaObject (CLASSNAME, ARG1, ...)
     Create a Java object of class CLASSSNAME, by calling the class
     constructor with the arguments ARG1, ...

     The first example below creates an uninitialized object, while the
     second example supplies an initial argument to the constructor.

          x = javaObject ("java.lang.StringBuffer")
          x = javaObject ("java.lang.StringBuffer", "Initial string")

     See also: *note javaMethod: XREFjavaMethod, *note javaArray:
     XREFjavaArray.

 -- : JARY = javaArray (CLASSNAME, SZ)
 -- : JARY = javaArray (CLASSNAME, M, N, ...)

     Create a Java array of size SZ with elements of class CLASSNAME.

     CLASSNAME may be a Java object representing a class or a string
     containing the fully qualified class name.  The size of the object
     may also be specified with individual integer arguments M, N, etc.

     The generated array is uninitialized.  All elements are set to null
     if CLASSNAME is a reference type, or to a default value (usually 0)
     if CLASSNAME is a primitive type.

     Sample code:

          jary = javaArray ("java.lang.String", 2, 2);
          jary(1,1) = "Hello";

     See also: *note javaObject: XREFjavaObject.

   There are many different variable types in Octave, but only ones
created through ‘javaObject’ can use Java functions.  Before using Java
with an unknown object the type can be checked with ‘isjava’.

 -- : TF = isjava (X)
     Return true if X is a Java object.

     See also: *note class: XREFclass, *note typeinfo: XREFtypeinfo,
     *note isa: XREFisa, *note javaObject: XREFjavaObject.

   Once an object has been created it is natural to find out what fields
the object has, and to read (get) and write (set) them.

   In Octave the ‘fieldnames’ function for structures has been
overloaded to return the fields of a Java object.  For example:

     dobj = javaObject ("java.lang.Double", pi);
     fieldnames (dobj)
     ⇒
     {
       [1,1] = public static final double java.lang.Double.POSITIVE_INFINITY
       [1,2] = public static final double java.lang.Double.NEGATIVE_INFINITY
       [1,3] = public static final double java.lang.Double.NaN
       [1,4] = public static final double java.lang.Double.MAX_VALUE
       [1,5] = public static final double java.lang.Double.MIN_NORMAL
       [1,6] = public static final double java.lang.Double.MIN_VALUE
       [1,7] = public static final int java.lang.Double.MAX_EXPONENT
       [1,8] = public static final int java.lang.Double.MIN_EXPONENT
       [1,9] = public static final int java.lang.Double.SIZE
       [1,10] = public static final java.lang.Class java.lang.Double.TYPE
     }

   The analogy of objects with structures is carried over into reading
and writing object fields.  To read a field the object is indexed with
the ‘.’ operator from structures.  This is the preferred method for
reading fields, but Octave also provides a function interface to read
fields with ‘java_get’.  An example of both styles is shown below.

     dobj = javaObject ("java.lang.Double", pi);
     dobj.MAX_VALUE
     ⇒  1.7977e+308
     java_get ("java.lang.Float", "MAX_VALUE")
     ⇒  3.4028e+38

 -- : VAL = java_get (OBJ, NAME)
     Get the value of the field NAME of the Java object OBJ.

     For static fields, OBJ can be a string representing the fully
     qualified name of the corresponding class.

     When OBJ is a regular Java object, structure-like indexing can be
     used as a shortcut syntax.  For instance, the following two
     statements are equivalent

            java_get (x, "field1")
            x.field1

     See also: *note java_set: XREFjava_set, *note javaMethod:
     XREFjavaMethod, *note javaObject: XREFjavaObject.

 -- : OBJ = java_set (OBJ, NAME, VAL)
     Set the value of the field NAME of the Java object OBJ to VAL.

     For static fields, OBJ can be a string representing the fully
     qualified named of the corresponding Java class.

     When OBJ is a regular Java object, structure-like indexing can be
     used as a shortcut syntax.  For instance, the following two
     statements are equivalent

            java_set (x, "field1", val)
            x.field1 = val

     See also: *note java_get: XREFjava_get, *note javaMethod:
     XREFjavaMethod, *note javaObject: XREFjavaObject.

   To see what functions can be called with an object use ‘methods’.
For example, using the previously created DOBJ:

     methods (dobj)
     ⇒
     Methods for class java.lang.Double:
     boolean equals(java.lang.Object)
     java.lang.String toString(double)
     java.lang.String toString()
     ...

   To call a method of an object the same structure indexing operator
‘.’ is used.  Octave also provides a functional interface to calling the
methods of an object through ‘javaMethod’.  An example showing both
styles is shown below.

     dobj = javaObject ("java.lang.Double", pi);
     dobj.equals (3)
     ⇒  0
     javaMethod ("equals", dobj, pi)
     ⇒  1

 -- : RET = javaMethod (METHODNAME, OBJ)
 -- : RET = javaMethod (METHODNAME, OBJ, ARG1, ...)
     Invoke the method METHODNAME on the Java object OBJ with the
     arguments ARG1, ....

     For static methods, OBJ can be a string representing the fully
     qualified name of the corresponding class.

     When OBJ is a regular Java object, structure-like indexing can be
     used as a shortcut syntax.  For instance, the two following
     statements are equivalent

            ret = javaMethod ("method1", x, 1.0, "a string")
            ret = x.method1 (1.0, "a string")

     ‘javaMethod’ returns the result of the method invocation.

     See also: *note methods: XREFmethods, *note javaObject:
     XREFjavaObject.

   The following three functions are used to display and modify the
class path used by the Java Virtual Machine.  This is entirely separate
from Octave’s ‘PATH’ variable and is used by the JVM to find the correct
code to execute.

 -- : javaclasspath ()
 -- : DPATH = javaclasspath ()
 -- : [DPATH, SPATH] = javaclasspath ()
 -- : CLSPATH = javaclasspath (WHAT)
     Return the class path of the Java virtual machine in the form of a
     cell array of strings.

     If called with no inputs:

        • If no output is requested, the dynamic and static classpaths
          are printed to the standard output.

        • If one output value DPATH is requested, the result is the
          dynamic classpath.

        • If two output valuesDPATH and SPATH are requested, the first
          variable will contain the dynamic classpath and the second
          will contain the static classpath.

     If called with a single input parameter WHAT:

     "-dynamic"
          Return the dynamic classpath.

     "-static"
          Return the static classpath.

     "-all"
          Return both the static and dynamic classpath in a single
          cellstr.

     See also: *note javaaddpath: XREFjavaaddpath, *note javarmpath:
     XREFjavarmpath.

 -- : javaaddpath (CLSPATH)
 -- : javaaddpath (CLSPATH1, ...)
 -- : javaaddpath ({CLSPATH1, ...})
 -- : javaaddpath (..., "-end")
     Add CLSPATH to the beginning of the dynamic class path of the Java
     virtual machine.

     CLSPATH may either be a directory where ‘.class’ files are found,
     or a ‘.jar’ file containing Java classes.  Multiple paths may be
     added at once by specifying additional arguments, or by using a
     cell array of strings.

     If the final argument is "-end", append the new element to the end
     of the current classpath.

     See also: *note javarmpath: XREFjavarmpath, *note javaclasspath:
     XREFjavaclasspath.

 -- : javarmpath (CLSPATH)
 -- : javarmpath (CLSPATH1, ...)
 -- : javarmpath ({CLSPATH1, ...})
     Remove CLSPATH from the dynamic class path of the Java virtual
     machine.

     CLSPATH may either be a directory where ‘.class’ files are found,
     or a ‘.jar’ file containing Java classes.  Multiple paths may be
     removed at once by specifying additional arguments, or by using a
     cell array of strings.

     See also: *note javaaddpath: XREFjavaaddpath, *note javaclasspath:
     XREFjavaclasspath.

   The following functions provide information and control over the
interface between Octave and the Java Virtual Machine.

 -- : MSG = javachk (FEATURE)
 -- : MSG = javachk (FEATURE, CALLER)
     Check for the presence of the Java FEATURE in the current session.
     Return an error structure if FEATURE is not available, not enabled,
     or not recognized.

     Possible recognized features are:

     "awt"
          Abstract Window Toolkit for GUIs.

     "desktop"
          Interactive desktop is running.

     "jvm"
          Java Virtual Machine.

     "swing"
          Swing components for lightweight GUIs.

     If FEATURE is not supported, a scalar struct with field "message"
     and "identifier" is returned.  The field "message" contains an
     error message mentioning FEATURE as well as the optional
     user-specified CALLER.  This structure is suitable for passing in
     to the ‘error’ function.

     If FEATURE is supported and available, an empty struct array is
     returned with fields "message" and "identifier".

     ‘javachk’ determines if specific Java features are available in an
     Octave session.  This function is provided for scripts which may
     alter their behavior based on the availability of Java or specific
     Java runtime features.

     Compatibility Note: The feature "desktop" is never available since
     Octave has no Java-based desktop.

     See also: *note usejava: XREFusejava, *note error: XREFerror.

 -- : TF = usejava (FEATURE)
     Return true if the Java element FEATURE is available.

     Possible features are:

     "awt"
          Abstract Window Toolkit for GUIs.

     "desktop"
          Interactive desktop is running.

     "jvm"
          Java Virtual Machine.

     "swing"
          Swing components for lightweight GUIs.

     ‘usejava’ determines if specific Java features are available in an
     Octave session.  This function is provided for scripts which may
     alter their behavior based on the availability of Java.  The
     feature "desktop" always returns ‘false’ as Octave has no
     Java-based desktop.  Other features may be available if Octave was
     compiled with the Java Interface and Java is installed.

     See also: *note javachk: XREFjavachk.

 -- : javamem ()
 -- : JMEM = javamem ()
     Show the current memory usage of the Java virtual machine (JVM) and
     run the garbage collector.

     When no return argument is given the info is printed to the screen.
     Otherwise, the output cell array JMEM contains Maximum, Total, and
     Free memory (in bytes).

     All Java-based routines are run in the JVM’s shared memory pool, a
     dedicated and separate part of memory claimed by the JVM from your
     computer’s total memory (which comprises physical RAM and virtual
     memory / swap space on hard disk).

     The maximum allowable memory usage can be configured using the file
     ‘java.opts’.  The directory where this file resides is determined
     by the environment variable ‘OCTAVE_JAVA_DIR’.  If unset, the
     directory where ‘javaaddpath.m’ resides is used instead (typically
     ‘OCTAVE_HOME/share/octave/OCTAVE_VERSION/m/java/’).

     ‘java.opts’ is a plain text file with one option per line.  The
     default initial memory size and default maximum memory size (which
     are both system dependent) can be overridden like so:

     -Xms64m

     -Xmx512m

     (in megabytes in this example).  You can adapt these values to your
     own requirements if your system has limited available physical
     memory or if you get Java memory errors.

     "Total memory" is what the operating system has currently assigned
     to the JVM and depends on actual and active memory usage.  "Free
     memory" is self-explanatory.  During operation of Java-based Octave
     functions the amount of Total and Free memory will vary, due to
     Java’s own cleaning up and your operating system’s memory
     management.

 -- : VAL = java_matrix_autoconversion ()
 -- : OLD_VAL = java_matrix_autoconversion (NEW_VAL)
 -- : OLD_VAL = java_matrix_autoconversion (NEW_VAL, "local")
     Query or set the internal variable that controls whether Java
     arrays are automatically converted to Octave matrices.

     The default value is false.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note java_unsigned_autoconversion:
     XREFjava_unsigned_autoconversion, *note debug_java: XREFdebug_java.

 -- : VAL = java_unsigned_autoconversion ()
 -- : OLD_VAL = java_unsigned_autoconversion (NEW_VAL)
 -- : OLD_VAL = java_unsigned_autoconversion (NEW_VAL, "local")
     Query or set the internal variable that controls how integer
     classes are converted when ‘java_matrix_autoconversion’ is enabled.

     When enabled, Java arrays of class Byte or Integer are converted to
     matrices of class uint8 or uint32 respectively.  The default value
     is true.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note java_matrix_autoconversion:
     XREFjava_matrix_autoconversion, *note debug_java: XREFdebug_java.

 -- : VAL = debug_java ()
 -- : OLD_VAL = debug_java (NEW_VAL)
 -- : OLD_VAL = debug_java (NEW_VAL, "local")
     Query or set the internal variable that determines whether extra
     debugging information regarding the initialization of the JVM and
     any Java exceptions is printed.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note java_matrix_autoconversion:
     XREFjava_matrix_autoconversion, *note java_unsigned_autoconversion:
     XREFjava_unsigned_autoconversion.


File: octave.info,  Node: Test and Demo Functions,  Next: Obsolete Functions,  Prev: External Code Interface,  Up: Top

Appendix B Test and Demo Functions
**********************************

Octave includes a number of functions to allow the integration of
testing and demonstration code in the source code of the functions
themselves.

* Menu:

* Test Functions::
* Demonstration Functions::


File: octave.info,  Node: Test Functions,  Next: Demonstration Functions,  Up: Test and Demo Functions

B.1 Test Functions
==================

 -- : test NAME
 -- : test NAME quiet|normal|verbose
 -- : test ("NAME", "quiet|normal|verbose", FID)
 -- : test ("NAME", "quiet|normal|verbose", FNAME)
 -- : SUCCESS = test (...)
 -- : [N, NMAX, NXFAIL, NBUG, NSKIP, NRTSKIP, NREGRESSION] = test (...)
 -- : [CODE, IDX] = test ("NAME", "grabdemo")
 -- : test ([], "explain", FID)
 -- : test ([], "explain", FNAME)

     Perform built-in self-tests from the first file in the loadpath
     matching NAME.

     ‘test’ can be called in either command or functional form.  The
     exact operation of test is determined by a combination of mode
     (interactive or batch), reporting level ("quiet", "normal",
     "verbose"), and whether a logfile or summary output variable is
     used.

     The default mode when ‘test’ is called from the command line is
     interactive.  In this mode, tests will be run until the first error
     is encountered, or all tests complete successfully.  In batch mode,
     all tests are run regardless of any failures, and the results are
     collected for reporting.  Tests which require user interaction,
     i.e., demo blocks, are never run in batch mode.

     Batch mode is enabled by either 1) specifying a logfile using the
     third argument FNAME or FID, or 2) requesting an output argument
     such as SUCCESS, N, etc.

     The optional second argument determines the amount of output to
     generate and which types of tests to run.  The default value is
     "normal".  Requesting an output argument will suppress printing the
     final summary message and any intermediate warnings, unless verbose
     reporting is enabled.

     "quiet"
          Print a summary message when all tests pass, or print an error
          with the results of the first bad test when a failure occurs.
          Don’t run tests which require user interaction.

     "normal"
          Display warning messages about skipped tests or failing xtests
          during test execution.  Print a summary message when all tests
          pass, or print an error with the results of the first bad test
          when a failure occurs.  Don’t run tests which require user
          interaction.

     "verbose"
          Display tests before execution.  Print all warning messages.
          In interactive mode, run all tests including those which
          require user interaction.

     The optional third input argument specifies a logfile where results
     of the tests should be written.  The logfile may be a character
     string (FNAME) or an open file descriptor ID (FID).  To enable
     batch processing, but still print the results to the screen, use
     ‘stdout’ for FID.

     When called with just a single output argument SUCCESS, ‘test’
     returns true if all of the tests were successful.  If called with
     more than one output argument then the number of successful tests
     (N), the total number of tests in the file (NMAX), the number of
     xtest failures (NXFAIL), the number of tests failed due known bugs
     (NBUG), the number of tests skipped due to missing features
     (NSKIP), the number of tests skipped due to run-time conditions
     (NRTSKIP), and the number of regressions (NREGRESSION) are
     returned.

     Example

          test sind
          ⇒
          PASSES 5 out of 5 tests

          [n, nmax] = test ("sind")
          ⇒
          n =  5
          nmax =  5

     Additional Calling Syntaxes

     If the second argument is the string "grabdemo", the contents of
     any built-in demo blocks are extracted but not executed.  The text
     for all code blocks is concatenated and returned as CODE with IDX
     being a vector of positions of the ends of each demo block.  For an
     easier way to extract demo blocks from files, *Note ‘example’:
     XREFexample.

     If the second argument is "explain" then NAME is ignored and an
     explanation of the line markers used in ‘test’ output reports is
     written to the file specified by FNAME or FID.

     See also: *note assert: XREFassert, *note fail: XREFfail, *note
     demo: XREFdemo, *note example: XREFexample, *note error: XREFerror.

   ‘test’ scans the named script file looking for lines which start with
the identifier ‘%!’.  The prefix is stripped off and the rest of the
line is processed through the Octave interpreter.  If the code generates
an error, then the test is said to fail.

   Since ‘eval()’ will stop at the first error it encounters, you must
divide your tests up into blocks, with anything in a separate block
evaluated separately.  Blocks are introduced by valid keywords like
‘test’, ‘function’, or ‘assert’ immediately following ‘%!’.  A block is
defined by indentation as in Python.  Lines beginning with
‘%!<whitespace>’ are part of the preceding block.

   For example:

     %!test error ("this test fails!")
     %!test "test doesn't fail.  it doesn't generate an error"

   When a test fails, you will see something like:

       ***** test error ("this test fails!")
     !!!!! test failed
     this test fails!

   Generally, to test if something works, you want to assert that it
produces a correct value.  A real test might look something like

     %!test
     %! A = [1, 2, 3; 4, 5, 6]; B = [1; 2];
     %! expect = [ A ; 2*A ];
     %! get = kron (B, A);
     %! if (any (size (expect) != size (get)))
     %!   error ("wrong size: expected %d,%d but got %d,%d",
     %!          size (expect), size (get));
     %! elseif (any (any (expect != get)))
     %!   error ("didn't get what was expected.");
     %! endif

   To make the process easier, use the ‘assert’ function.  For example,
with ‘assert’ the previous test is reduced to:

     %!test
     %! A = [1, 2, 3; 4, 5, 6]; B = [1; 2];
     %! assert (kron (B, A), [ A; 2*A ]);

   ‘assert’ can accept a tolerance so that you can compare results
absolutely or relatively.  For example, the following all succeed:

     %!test assert (1+eps, 1, 2*eps)           # absolute error
     %!test assert (100+100*eps, 100, -2*eps)  # relative error

   You can also do the comparison yourself, but still have assert
generate the error:

     %!test assert (isempty ([]))
     %!test assert ([1, 2; 3, 4] > 0)

   Because ‘assert’ is so frequently used alone in a test block, there
is a shorthand form:

     %!assert (...)

which is equivalent to:

     %!test assert (...)

   Occasionally a block of tests will depend on having optional
functionality in Octave.  Before testing such blocks the availability of
the required functionality must be checked.  A ‘%!testif HAVE_XXX’ block
will only be run if Octave was compiled with functionality ‘HAVE_XXX’.
For example, the sparse single value decomposition, ‘svds()’, depends on
having the ARPACK library.  All of the tests for ‘svds’ begin with

     %!testif HAVE_ARPACK

Review ‘config.h’ or ‘__octave_config_info__ ("build_features")’ to see
some of the possible values to check.

   Sometimes during development there is a test that should work but is
known to fail.  You still want to leave the test in because when the
final code is ready the test should pass, but you may not be able to fix
it immediately.  To avoid unnecessary bug reports for these known
failures, mark the block with ‘xtest’ rather than ‘test’:

     %!xtest assert (1==0)
     %!xtest fail ("success=1", "error")

In this case, the test will run and any failure will be reported.
However, testing is not aborted and subsequent test blocks will be
processed normally.  Another use of ‘xtest’ is for statistical tests
which should pass most of the time but are known to fail occasionally.

   Each block is evaluated in its own function environment, which means
that variables defined in one block are not automatically shared with
other blocks.  If you do want to share variables, then you must declare
them as ‘shared’ before you use them.  For example, the following
declares the variable A, gives it an initial value (default is empty),
and then uses it in several subsequent tests.

     %!shared A
     %! A = [1, 2, 3; 4, 5, 6];
     %!assert (kron ([1; 2], A), [ A; 2*A ])
     %!assert (kron ([1, 2], A), [ A, 2*A ])
     %!assert (kron ([1,2; 3,4], A), [ A,2*A; 3*A,4*A ])

   You can share several variables at the same time:

     %!shared A, B

   You can also share test functions:

     %!function A = fn (B)
     %!  A = 2*B;
     %!endfunction
     %!assert (fn(2), 4)

   Note that all previous variables and values are lost when a new
shared block is declared.

   Remember that ‘%!function’ begins a new block and that
‘%!endfunction’ ends this block.  Be aware that until a new block is
started, lines starting with ‘%!<space>’ will be discarded as comments.
The following is nearly identical to the example above, but does
nothing.

     %!function A = fn (B)
     %!  A = 2*B;
     %!endfunction
     %! assert (fn(2), 4)

Because there is a space after ‘%!’ the ‘assert’ statement does not
begin a new block and this line is treated as a comment.

   Error and warning blocks are like test blocks, but they only succeed
if the code generates an error.  You can check the text of the error is
correct using an optional regular expression ‘<pattern>’.  For example:

     %!error <passes!> error ("this test passes!")

   If the code doesn’t generate an error, the test fails.  For example:

     %!error "this is an error because it succeeds."

produces

       ***** error "this is an error because it succeeds."
     !!!!! test failed: no error

   It is important to automate the tests as much as possible, however
some tests require user interaction.  These can be isolated into demo
blocks, which if you are in batch mode, are only run when called with
‘demo’ or the ‘verbose’ option to ‘test’.  The code is displayed before
it is executed.  For example,

     %!demo
     %! T = [0:0.01:2*pi]; X = sin (T);
     %! plot (T, X);
     %! # you should now see a sine wave in your figure window

produces

     funcname example 1:
      T = [0:0.01:2*pi]; X = sin (T);
      plot (T, X);
      # you should now see a sine wave in your figure window

     Press <enter> to continue:

   Note that demo blocks cannot use any shared variables.  This is so
that they can be executed by themselves, ignoring all other tests.

   If you want to temporarily disable a test block, put ‘#’ in place of
the block type.  This creates a comment block which is echoed in the log
file but not executed.  For example:

     %!#demo
     %! T = [0:0.01:2*pi]; X = sin (T);
     %! plot (T, X);
     %! # you should now see a sine wave in your figure window

The following trivial code snippet provides examples for the use of
fail, assert, error, and xtest:

     function OUTPUT = must_be_zero (INPUT)
       if (INPUT != 0)
         error ("Nonzero input!")
       endif
       OUTPUT = INPUT;
     endfunction

     %!fail ("must_be_zero (1)")
     %!assert (must_be_zero (0), 0)
     %!error <Nonzero> must_be_zero (1)
     %!xtest error ("This code generates an error")

When putting this in a file ‘must_be_zero.m’, and running the test, we
see

     test must_be_zero verbose

     ⇒
     >>>>> /path/to/must_be_zero.m
     ***** fail ("must_be_zero (1)")
     ***** assert (must_be_zero (0), 0)
     ***** error <Nonzero> must_be_zero (1)
     ***** xtest error ("This code generates an error")
     !!!!! known failure
     This code generates an error
     PASSES 3 out of 4 tests (1 expected failure)

Block type summary:
...................

‘%!test’
‘%!test <MESSAGE>’
     Check that entire block is correct.  If ‘<MESSAGE>’ is present, the
     test block is interpreted as for ‘xtest’.

‘%!testif HAVE_XXX’
‘%!testif HAVE_XXX, HAVE_YYY, ...’
‘%!testif HAVE_XXX, HAVE_YYY ...; RUNTIME_COND’
‘%!testif ... <MESSAGE>’
     Check block only if Octave was compiled with feature ‘HAVE_XXX’.
     ‘RUNTIME_COND’ is an optional expression to evaluate to check
     whether some condition is met when the test is executed.  If
     ‘RUNTIME_COND’ is false, the test is skipped.  If ‘<MESSAGE>’ is
     present, the test block is interpreted as for ‘xtest’.

‘%!xtest’
‘%!xtest <MESSAGE>’
     Check block, report a test failure but do not abort testing.  If
     ‘<MESSAGE>’ is present, then the text of the message is displayed
     if the test fails, like this:

          !!!!! known bug:  MESSAGE

     If the message is an integer, it is interpreted as a bug ID for the
     Octave bug tracker and reported as

          !!!!! known bug: https://octave.org/testfailure/?BUG-ID

     in which BUG-ID is the integer bug number.  The intent is to allow
     clearer documentation of known problems.

     If ‘MESSAGE’ is an integer preceeded by an asterisk (e.g.,
     ‘*12345’), it is interpreted as the id for a bug report that has
     been closed.  That usually means that the issue probed in this test
     has been resolved.  If such tests are failing, they are reported as
     regressions by the ‘test’ function:

          !!!!! regression: https://octave.org/testfailure/?BUG-ID

‘%!error’
‘%!error <MESSAGE>’
‘%!warning’
‘%!warning <MESSAGE>’
     Check for correct error or warning message.  If ‘<MESSAGE>’ is
     supplied it is interpreted as a regular expression pattern that is
     expected to match the error or warning message.

‘%!demo’
     Demo only executes in interactive mode.

‘%!#’
     Comment.  Ignore everything within the block

‘%!shared x,y,z’
     Declare variables for use in multiple tests.

‘%!function’
     Define a function for use in multiple tests.

‘%!endfunction’
     Close a function definition.

‘%!assert (x, y, tol)’

‘%!assert <MESSAGE> (x, y, tol)’

‘%!fail (CODE, PATTERN)’

‘%!fail <MESSAGE> (CODE, PATTERN)’
     Shorthand for ‘%!test assert (x, y, tol)’ or ‘%!test fail (CODE,
     PATTERN)’.  If ‘<MESSAGE>’ is present, the test block is
     interpreted as for ‘xtest’.

   When coding tests the Octave convention is that lines that begin with
a block type do not have a semicolon at the end.  Any code that is
within a block, however, is normal Octave code and usually will have a
trailing semicolon.  For example,

     ## bare block instantiation
     %!assert (sin (0), 0)

but

     ## test block with normal Octave code
     %!test
     %! assert (sin (0), 0);

   You can also create test scripts for built-in functions and your own
C++ functions.  To do so, put a file with the bare function name (no .m
extension) in a directory in the load path and it will be discovered by
the ‘test’ function.  Alternatively, you can embed tests directly in
your C++ code:

     /*
     %!test disp ("this is a test")
     */

or

     #if 0
     %!test disp ("this is a test")
     #endif

However, in this case the raw source code will need to be on the load
path and the user will have to remember to type ‘test ("funcname.cc")’.

 -- : assert (COND)
 -- : assert (COND, ERRMSG)
 -- : assert (COND, ERRMSG, ...)
 -- : assert (COND, MSG_ID, ERRMSG, ...)
 -- : assert (OBSERVED, EXPECTED)
 -- : assert (OBSERVED, EXPECTED, TOL)

     Produce an error if the specified condition is not met.

     ‘assert’ can be called in three different ways.

     ‘assert (COND)’
     ‘assert (COND, ERRMSG)’
     ‘assert (COND, ERRMSG, ...)’
     ‘assert (COND, MSG_ID, ERRMSG, ...)’
          Called with a single argument COND, ‘assert’ produces an error
          if COND is false (numeric zero).

          Any additional arguments are passed to the ‘error’ function
          for processing.

     ‘assert (OBSERVED, EXPECTED)’
          Produce an error if observed is not the same as expected.

          Note that OBSERVED and EXPECTED can be scalars, vectors,
          matrices, strings, cell arrays, or structures.

     ‘assert (OBSERVED, EXPECTED, TOL)’
          Produce an error if observed is not the same as expected but
          equality comparison for numeric data uses a tolerance TOL.

          If TOL is positive then it is an absolute tolerance which will
          produce an error if ‘abs (OBSERVED - EXPECTED) > abs (TOL)’.

          If TOL is negative then it is a relative tolerance which will
          produce an error if ‘abs (OBSERVED - EXPECTED) > abs (TOL *
          EXPECTED)’.

          If EXPECTED is zero TOL will always be interpreted as an
          absolute tolerance.

          If TOL is not scalar its dimensions must agree with those of
          OBSERVED and EXPECTED and tests are performed on an
          element-by-element basis.

     See also: *note fail: XREFfail, *note test: XREFtest, *note error:
     XREFerror, *note isequal: XREFisequal.

 -- : STATUS = fail (CODE)
 -- : STATUS = fail (CODE, PATTERN)
 -- : STATUS = fail (CODE, "warning")
 -- : STATUS = fail (CODE, "warning", PATTERN)

     Return true if CODE fails with an error message matching PATTERN,
     otherwise produce an error.

     CODE must be in the form of a string that is passed to the Octave
     interpreter via the ‘evalin’ function, i.e., a (quoted) string
     constant or a string variable.

     Note that if CODE runs successfully, rather than failing, the error
     printed is:

                    expected error <.> but got none

     If called with two arguments, the return value will be true only if
     CODE fails with an error message containing PATTERN (case
     sensitive).  If the code fails with a different error than the one
     specified in PATTERN then the message produced is:

                    expected <PATTERN>
                    but got <text of actual error>

     The angle brackets are not part of the output.

     When called with the "warning" option ‘fail’ will produce an error
     if executing the code produces no warning.

     See also: *note assert: XREFassert, *note error: XREFerror.


File: octave.info,  Node: Demonstration Functions,  Prev: Test Functions,  Up: Test and Demo Functions

B.2 Demonstration Functions
===========================

 -- : demo NAME
 -- : demo NAME N
 -- : demo ("NAME")
 -- : demo ("NAME", N)

     Run example code block N associated with the function NAME.

     If N is not specified, all examples are run.

     The preferred location for example code blocks is embedded within
     the script m-file immediately following the code that it exercises.
     Alternatively, the examples may be stored in a file with the same
     name but no extension located on Octave’s load path.  To separate
     examples from regular script code all lines are prefixed by ‘%!’.
     Each example must also be introduced by the keyword "demo" flush
     left to the prefix with no intervening spaces.  The remainder of
     the example can contain arbitrary Octave code.  For example:

          %!demo
          %! t = 0:0.01:2*pi;
          %! x = sin (t);
          %! plot (t, x);
          %! title ("one cycle of a sine wave");
          %! #-------------------------------------------------
          %! # the figure window shows one cycle of a sine wave

     Note that the code is displayed before it is executed so that a
     simple comment at the end suffices for labeling what is being
     shown.  For plots, labeling can also be done with ‘title’ or
     ‘text’.  It is generally *not* necessary to use ‘disp’ or ‘printf’
     within the demo.

     Demos are run in a stand-alone function environment with no access
     to external variables.  This means that every demo must have
     separate initialization code.  Alternatively, all demos can be
     combined into a single large demo with the code

          %! input ("Press <enter> to continue: ", "s");

     between the sections, but this usage is discouraged.  Other
     techniques to avoid multiple initialization blocks include using
     multiple plots with a new ‘figure’ command between each plot, or
     using ‘subplot’ to put multiple plots in the same window.

     Finally, because ‘demo’ evaluates within a function context it is
     not possible to define new functions within the code.  Anonymous
     functions make a good substitute in most instances.  If function
     blocks *must* be used then the code ‘eval (example ("function",
     n))’ will allow Octave to see them.  This has its own problems,
     however, as ‘eval’ only evaluates one line or statement at a time.
     In this case the function declaration must be wrapped with "if 1
     <demo stuff> endif" where "if" is on the same line as "demo".  For
     example:

          %!demo if 1
          %!  function y = f(x)
          %!    y = x;
          %!  endfunction
          %!  f(3)
          %! endif

     See also: *note rundemos: XREFrundemos, *note example: XREFexample,
     *note test: XREFtest.

 -- : example NAME
 -- : example NAME N
 -- : example ("NAME")
 -- : example ("NAME", N)
 -- : [CODESTR, CODEIDX] = example (...)

     Display the code for example N associated with the function NAME,
     but do not run it.

     If N is not specified, all examples are displayed.

     When called with output arguments, the examples are returned in the
     form of a string CODESTR, with CODEIDX indicating the ending
     position of the various examples.

     For a complete explanation *note ‘demo’: XREFdemo.

     See also: *note demo: XREFdemo, *note test: XREFtest.

 -- : oruntests ()
 -- : oruntests (DIRECTORY)
     Execute built-in tests for all m-files in the specified DIRECTORY.

     Test blocks in any C++ source files (‘*.cc’) will also be executed
     for use with dynamically linked oct-file functions.

     If no directory is specified, operate on all directories in
     Octave’s search path for functions.

     See also: *note rundemos: XREFrundemos, *note test: XREFtest, *note
     path: XREFpath.

 -- : rundemos ()
 -- : rundemos (DIRECTORY)
     Execute built-in demos for all m-files in the specified DIRECTORY.

     Demo blocks in any C++ source files (‘*.cc’) will also be executed
     for use with dynamically linked oct-file functions.

     If no directory is specified, operate on all directories in
     Octave’s search path for functions.

     See also: *note demo: XREFdemo, *note oruntests: XREForuntests,
     *note path: XREFpath.

 -- : speed (F, INIT, MAX_N, F2, TOL)
 -- : [ORDER, N, T_F, T_F2] = speed (...)

     Determine the execution time of an expression (F) for various input
     values (N).

     The N are log-spaced from 1 to MAX_N.  For each N, an
     initialization expression (INIT) is computed to create any data
     needed for the test.  If a second expression (F2) is given then the
     execution times of the two expressions are compared.  When called
     without output arguments the results are printed to stdout and
     displayed graphically.

     ‘F’
          The code expression to evaluate.

     ‘MAX_N’
          The maximum test length to run.  The default value is 100.
          Alternatively, use ‘[min_n, max_n]’ or specify the N exactly
          with ‘[n1, n2, ..., nk]’.

     ‘INIT’
          Initialization expression for function argument values.  Use K
          for the test number and N for the size of the test.  This
          should compute values for all variables used by F.  Note that
          INIT will be evaluated first for k = 0, so things which are
          constant throughout the test series can be computed once.  The
          default value is ‘X = randn (N, 1)’.

     ‘F2’
          An alternative expression to evaluate, so that the speed of
          two expressions can be directly compared.  The default is
          ‘[]’.

     ‘TOL’
          Tolerance used to compare the results of expression F and
          expression F2.  If TOL is positive, the tolerance is an
          absolute one.  If TOL is negative, the tolerance is a relative
          one.  The default is ‘eps’.  If TOL is ‘Inf’, then no
          comparison will be made.

     ‘ORDER’
          The time complexity of the expression O(a*n^p).  This is a
          structure with fields ‘a’ and ‘p’.

     ‘N’
          The values N for which the expression was calculated *AND* the
          execution time was greater than zero.

     ‘T_F’
          The nonzero execution times recorded for the expression F in
          seconds.

     ‘T_F2’
          The nonzero execution times recorded for the expression F2 in
          seconds.  If required, the mean time ratio is simply ‘mean
          (T_f ./ T_f2)’.

     The slope of the execution time graph shows the approximate power
     of the asymptotic running time O(n^p).  This power is plotted for
     the region over which it is approximated (the latter half of the
     graph).  The estimated power is not very accurate, but should be
     sufficient to determine the general order of an algorithm.  It
     should indicate if, for example, the implementation is unexpectedly
     O(n^2) rather than O(n) because it extends a vector each time
     through the loop rather than pre-allocating storage.  In the
     current version of Octave, the following is not the expected O(n).

          speed ("for i = 1:n, y{i} = x(i); endfor", "", [1000, 10000])

     But it is if you preallocate the cell array ‘y’:

          speed ("for i = 1:n, y{i} = x(i); endfor", ...
                 "x = rand (n, 1); y = cell (size (x));", [1000, 10000])

     An attempt is made to approximate the cost of individual
     operations, but it is wildly inaccurate.  You can improve the
     stability somewhat by doing more work for each ‘n’.  For example:

          speed ("airy(x)", "x = rand (n, 10)", [10000, 100000])

     When comparing two different expressions (F, F2), the slope of the
     line on the speedup ratio graph should be larger than 1 if the new
     expression is faster.  Better algorithms have a shallow slope.
     Generally, vectorizing an algorithm will not change the slope of
     the execution time graph, but will shift it relative to the
     original.  For example:

          speed ("sum (x)", "", [10000, 100000], ...
                 "v = 0; for i = 1:length (x), v += x(i); endfor")

     The following is a more complex example.  If there was an original
     version of ‘xcorr’ using for loops and a second version using an
     FFT, then one could compare the run speed for various lags as
     follows, or for a fixed lag with varying vector lengths as follows:

          speed ("xcorr (x, n)", "x = rand (128, 1);", 100,
                 "xcorr_orig (x, n)", -100*eps)
          speed ("xcorr (x, 15)", "x = rand (20+n, 1);", 100,
                 "xcorr_orig (x, n)", -100*eps)

     Assuming one of the two versions is in xcorr_orig, this would
     compare their speed and their output values.  Note that the FFT
     version is not exact, so one must specify an acceptable tolerance
     on the comparison ‘100*eps’.  In this case, the comparison should
     be computed relatively, as ‘abs ((X - Y) ./ Y)’ rather than
     absolutely as ‘abs (X - Y)’.

     Type ‘example ("speed")’ to see some real examples or ‘demo
     ("speed")’ to run them.


File: octave.info,  Node: Obsolete Functions,  Next: Trouble,  Prev: Test and Demo Functions,  Up: Top

Appendix C Obsolete Functions
*****************************

After being marked as deprecated for two major releases, the following
functions have been removed from Octave.  The third column of the table
shows the version of Octave in which the function was removed.  Prior to
removal, each function in the list was marked as deprecated for at least
two major releases.  All deprecated functions issue warnings explaining
that they will be removed in a future version of Octave, and which
function should be used instead.

   Replacement functions do not always accept precisely the same
arguments as the obsolete function, but should provide equivalent
functionality.

Obsolete Function      Replacement            Version
----------------------------------------------------------
‘beta_cdf’             ‘betacdf’ in Octave    3.4.0
                       Forge statistics pkg
‘beta_inv’             ‘betainv’ in Octave    3.4.0
                       Forge statistics pkg
‘beta_pdf’             ‘betapdf’ in Octave    3.4.0
                       Forge statistics pkg
‘beta_rnd’             ‘betarnd’ in Octave    3.4.0
                       Forge statistics pkg
‘binomial_cdf’         ‘binocdf’ in Octave    3.4.0
                       Forge statistics pkg
‘binomial_inv’         ‘binoinv’ in Octave    3.4.0
                       Forge statistics pkg
‘binomial_pdf’         ‘binopdf’ in Octave    3.4.0
                       Forge statistics pkg
‘binomial_rnd’         ‘binornd’ in Octave    3.4.0
                       Forge statistics pkg
‘chisquare_cdf’        ‘chi2cdf’ in Octave    3.4.0
                       Forge statistics pkg
‘chisquare_inv’        ‘chi2inv’ in Octave    3.4.0
                       Forge statistics pkg
‘chisquare_pdf’        ‘chi2pdf’ in Octave    3.4.0
                       Forge statistics pkg
‘chisquare_rnd’        ‘chi2rnd’ in Octave    3.4.0
                       Forge statistics pkg
‘clearplot’            ‘clf’                  3.4.0
‘com2str’              ‘num2str’              3.4.0
‘exponential_cdf’      ‘expcdf’ in Octave     3.4.0
                       Forge statistics pkg
‘exponential_inv’      ‘expinv’ in Octave     3.4.0
                       Forge statistics pkg
‘exponential_pdf’      ‘exppdf’ in Octave     3.4.0
                       Forge statistics pkg
‘exponential_rnd’      ‘exprnd’ in Octave     3.4.0
                       Forge statistics pkg
‘f_cdf’                ‘fcdf’ in Octave       3.4.0
                       Forge statistics pkg
‘f_inv’                ‘finv’ in Octave       3.4.0
                       Forge statistics pkg
‘f_pdf’                ‘fpdf’ in Octave       3.4.0
                       Forge statistics pkg
‘f_rnd’                ‘frnd’ in Octave       3.4.0
                       Forge statistics pkg
‘gamma_cdf’            ‘gamcdf’ in Octave     3.4.0
                       Forge statistics pkg
‘gamma_inv’            ‘gaminv’ in Octave     3.4.0
                       Forge statistics pkg
‘gamma_pdf’            ‘gampdf’ in Octave     3.4.0
                       Forge statistics pkg
‘gamma_rnd’            ‘gamrnd’ in Octave     3.4.0
                       Forge statistics pkg
‘geometric_cdf’        ‘geocdf’ in Octave     3.4.0
                       Forge statistics pkg
‘geometric_inv’        ‘geoinv’ in Octave     3.4.0
                       Forge statistics pkg
‘geometric_pdf’        ‘geopdf’ in Octave     3.4.0
                       Forge statistics pkg
‘geometric_rnd’        ‘geornd’ in Octave     3.4.0
                       Forge statistics pkg
‘hypergeometric_cdf’   ‘hygecdf’ in Octave    3.4.0
                       Forge statistics pkg
‘hypergeometric_inv’   ‘hygeinv’ in Octave    3.4.0
                       Forge statistics pkg
‘hypergeometric_pdf’   ‘hygepdf’ in Octave    3.4.0
                       Forge statistics pkg
‘hypergeometric_rnd’   ‘hygernd’ in Octave    3.4.0
                       Forge statistics pkg
‘intersection’         ‘intersect’            3.4.0
‘is_bool’              ‘isbool’               3.4.0
‘is_complex’           ‘iscomplex’            3.4.0
‘is_list’              None                   3.4.0
‘is_matrix’            ‘ismatrix’             3.4.0
‘is_scalar’            ‘isscalar’             3.4.0
‘is_square’            ‘issquare’             3.4.0
‘is_stream’            None                   3.4.0
‘is_struct’            ‘isstruct’             3.4.0
‘is_symmetric’         ‘issymmetric’          3.4.0
‘is_vector’            ‘isvector’             3.4.0
‘lognormal_cdf’        ‘logncdf’ in Octave    3.4.0
                       Forge statistics pkg
‘lognormal_inv’        ‘logninv’ in Octave    3.4.0
                       Forge statistics pkg
‘lognormal_pdf’        ‘lognpdf’ in Octave    3.4.0
                       Forge statistics pkg
‘lognormal_rnd’        ‘lognrnd’ in Octave    3.4.0
                       Forge statistics pkg
‘meshdom’              ‘meshgrid’             3.4.0
‘normal_cdf’           ‘normcdf’ in Octave    3.4.0
                       Forge statistics pkg
‘normal_inv’           ‘norminv’ in Octave    3.4.0
                       Forge statistics pkg
‘normal_pdf’           ‘normpdf’ in Octave    3.4.0
                       Forge statistics pkg
‘normal_rnd’           ‘normrnd’ in Octave    3.4.0
                       Forge statistics pkg
‘pascal_cdf’           ‘nbincdf’ in Octave    3.4.0
                       Forge statistics pkg
‘pascal_inv’           ‘nbininv’ in Octave    3.4.0
                       Forge statistics pkg
‘pascal_pdf’           ‘nbinpdf’ in Octave    3.4.0
                       Forge statistics pkg
‘pascal_rnd’           ‘nbinrnd’ in Octave    3.4.0
                       Forge statistics pkg
‘poisson_cdf’          ‘poisscdf’ in Octave   3.4.0
                       Forge statistics pkg
‘poisson_inv’          ‘poissinv’ in Octave   3.4.0
                       Forge statistics pkg
‘poisson_pdf’          ‘poisspdf’ in Octave   3.4.0
                       Forge statistics pkg
‘poisson_rnd’          ‘poissrnd’ in Octave   3.4.0
                       Forge statistics pkg
‘polyinteg’            ‘polyint’              3.4.0
‘struct_contains’      ‘isfield’              3.4.0
‘struct_elements’      ‘fieldnames’           3.4.0
‘t_cdf’                ‘tcdf’ in Octave       3.4.0
                       Forge statistics pkg
‘t_inv’                ‘tinv’ in Octave       3.4.0
                       Forge statistics pkg
‘t_pdf’                ‘tpdf’ in Octave       3.4.0
                       Forge statistics pkg
‘t_rnd’                ‘trnd’ in Octave       3.4.0
                       Forge statistics pkg
‘uniform_cdf’          ‘unifcdf’ in Octave    3.4.0
                       Forge statistics pkg
‘uniform_inv’          ‘unifinv’ in Octave    3.4.0
                       Forge statistics pkg
‘uniform_pdf’          ‘unifpdf’ in Octave    3.4.0
                       Forge statistics pkg
‘uniform_rnd’          ‘unifrnd’ in Octave    3.4.0
                       Forge statistics pkg
‘weibull_cdf’          ‘wblcdf’ in Octave     3.4.0
                       Forge statistics pkg
‘weibull_inv’          ‘wblinv’ in Octave     3.4.0
                       Forge statistics pkg
‘weibull_pdf’          ‘wblpdf’ in Octave     3.4.0
                       Forge statistics pkg
‘weibull_rnd’          ‘wblrnd’ in Octave     3.4.0
                       Forge statistics pkg
‘wiener_rnd’           ‘wienrnd’ in Octave    3.4.0
                       Forge statistics pkg
‘create_set’           ‘unique’               3.6.0
‘dmult’                ‘diag (A) * B’         3.6.0
‘iscommand’            None                   3.6.0
‘israwcommand’         None                   3.6.0
‘lchol’                ‘chol (...,            3.6.0
                       "lower")’
‘loadimage’            ‘load’ or ‘imread’     3.6.0
‘mark_as_command’      None                   3.6.0
‘mark_as_rawcommand’   None                   3.6.0
‘spatan2’              ‘atan2’                3.6.0
‘spchol’               ‘chol’                 3.6.0
‘spchol2inv’           ‘chol2inv’             3.6.0
‘spcholinv’            ‘cholinv’              3.6.0
‘spcumprod’            ‘cumprod’              3.6.0
‘spcumsum’             ‘cumsum’               3.6.0
‘spdet’                ‘det’                  3.6.0
‘spdiag’               ‘sparse (diag          3.6.0
                       (...))’
‘spfind’               ‘find’                 3.6.0
‘sphcat’               ‘horzcat’              3.6.0
‘spinv’                ‘inv’                  3.6.0
‘spkron’               ‘kron’                 3.6.0
‘splchol’              ‘chol (...,            3.6.0
                       "lower")’
‘split’                ‘char (strsplit (s,    3.6.0
                       t))’
‘splu’                 ‘lu’                   3.6.0
‘spmax’                ‘max’                  3.6.0
‘spmin’                ‘min’                  3.6.0
‘spprod’               ‘prod’                 3.6.0
‘spqr’                 ‘qr’                   3.6.0
‘spsum’                ‘sum’                  3.6.0
‘spsumsq’              ‘sumsq’                3.6.0
‘spvcat’               ‘vertcat’              3.6.0
‘str2mat’              ‘char’                 3.6.0
‘unmark_command’       None                   3.6.0
‘unmark_rawcommand’    None                   3.6.0
‘autocor’              ‘xcorr’ in Octave      3.8.0
                       Forge signal pkg
‘autocov’              ‘xcov’ in Octave       3.8.0
                       Forge signal pkg
‘betai’                ‘betainc’              3.8.0
‘cellidx’              ‘ismember’             3.8.0
‘cquad’                ‘quadcc’               3.8.0
‘dispatch’             None                   3.8.0
‘fstat’                ‘stat’                 3.8.0
‘gammai’               ‘gammainc’             3.8.0
‘glpkmex’              ‘glpk’                 3.8.0
‘is_duplicate_entry’   ‘unique’               3.8.0
‘is_global’            ‘isglobal’             3.8.0
‘krylovb’              ‘[Uret, ~, Ucols] =    3.8.0
                       krylov (...)’
‘perror’               None                   3.8.0
‘replot’               ‘refresh’              3.8.0
‘saveimage’            ‘imwrite’              3.8.0
‘setstr’               ‘char’                 3.8.0
‘strerror’             None                   3.8.0
‘values’               ‘unique’               3.8.0
‘cut’                  ‘histc’                4.0.0
‘cor’                  ‘corr’                 4.0.0
‘corrcoef’             ‘corr’                 4.0.0
‘__error_text__’       ‘lasterr’              4.0.0
‘error_text’           ‘lasterr’              4.0.0
‘polyderiv’            ‘polyder’              4.0.0
‘shell_cmd’            ‘system’               4.0.0
‘studentize’           ‘zscore’               4.0.0
‘sylvester_matrix’     ‘hadamard (2^k)’       4.0.0
‘default_save_options’ ‘save_default_options’ 4.2.0
‘gen_doc_cache’        ‘doc_cache_create’     4.2.0
‘interp1q’             ‘interp1’              4.2.0
‘isequalwithequalnans’ ‘isequaln’             4.2.0
‘java_convert_matrix’  ‘java_matrix_autoconversion’4.2.0
‘java_debug’           ‘debug_java’           4.2.0
‘java_invoke’          ‘javaMethod’           4.2.0
‘java_new’             ‘javaObject’           4.2.0
‘java_unsigned_conversion’‘java_unsigned_autoconversion’4.2.0
‘javafields’           ‘fieldnames’           4.2.0
‘javamethods’          ‘methods’              4.2.0
‘re_read_readline_init_file’‘readline_re_read_init_file’4.2.0
‘read_readline_init_file’‘readline_read_init_file’4.2.0
‘saving_history’       ‘history_save’         4.2.0
‘allow_noninteger_range_as_index’None         4.4.0
‘bicubic’              ‘interp2’              4.4.0
‘delaunay3’            ‘delaunay’             4.4.0
‘do_braindead_shortcircuit_evaluation’None    4.4.0
‘dump_prefs’           ‘’ None 4.4.0
‘find_dir_in_path’     ‘dir_in_loadpath’      4.4.0
‘finite’               ‘isfinite’             4.4.0
‘fmod’                 ‘rem’                  4.4.0
‘fnmatch’              ‘glob’ or ‘regexp’     4.4.0
‘gmap40’               None                   4.4.0
‘loadaudio’            ‘audioread’            4.4.0
‘luinc’                ‘ichol’ or ‘ilu’       4.4.0
‘mouse_wheel_zoom’     ‘mousehweelzoom’       4.4.0
                       property
‘nfields’              ‘numfields’            4.4.0
‘octave_tmp_file_name’ ‘tempname’             4.4.0
‘playaudio’            ‘audioplayer’          4.4.0
‘saveaudio’            ‘audiowrite’           4.4.0
‘setaudio’             None                   4.4.0
‘syl’                  ‘sylvester’            4.4.0
‘usage’                ‘print_usage’          4.4.0
‘bitmax’               ‘flintmax’             5.1.0
‘mahalanobis’          ‘mahal’ in Octave      5.1.0
                       Forge statistics pkg
‘md5sum’               ‘hash’                 5.1.0
‘octave_config_info’   ‘__octave_config_info__’5.1.0
‘onenormest’           ‘normest1’             5.1.0
‘sleep’                ‘pause’                5.1.0
‘usleep’               ‘pause’                5.1.0
‘wavread’              ‘audioread’            5.1.0
‘wavwrite’             ‘audiowrite’           5.1.0


File: octave.info,  Node: Trouble,  Next: Installation,  Prev: Obsolete Functions,  Up: Top

Appendix D Known Causes of Trouble
**********************************

This section describes known problems that affect users of Octave.  Most
of these are not Octave bugs per se—if they were, we would fix them.
But the result for a user may be like the result of a bug.

   Some of these problems are due to bugs in other software, some are
missing features that are too much work to add, and some are places
where people’s opinions differ as to what is best.

* Menu:

* Actual Bugs::                 Bugs we will fix later.
* Reporting Bugs::
* How To Get Help with Octave::
* How to Distinguish Between Octave and Matlab::


File: octave.info,  Node: Actual Bugs,  Next: Reporting Bugs,  Up: Trouble

D.1 Actual Bugs We Haven’t Fixed Yet
====================================

   • Output that comes directly from Fortran functions is not sent
     through the pager and may appear out of sequence with other output
     that is sent through the pager.  One way to avoid this is to force
     pending output to be flushed before calling a function that will
     produce output from within Fortran functions.  To do this, use the
     command

          fflush (stdout)

     Another possible workaround is to use the command

          page_screen_output (false);

     to turn the pager off.

   A list of ideas for future enhancements is distributed with Octave.
See the file ‘PROJECTS’ in the top level directory in the source
distribution.


File: octave.info,  Node: Reporting Bugs,  Next: How To Get Help with Octave,  Prev: Actual Bugs,  Up: Trouble

D.2 Reporting Bugs
==================

Your bug reports play an essential role in making Octave reliable.

   When you encounter a problem, the first thing to do is to see if it
is already known.  *Note Trouble::.  If it isn’t known, then you should
report the problem.

   Reporting a bug may help you by bringing a solution to your problem,
or it may not.  In any case, the principal function of a bug report is
to help the entire community by making the next version of Octave work
better.  Bug reports are your contribution to the maintenance of Octave.

   In order for a bug report to serve its purpose, you must include the
information that makes it possible to fix the bug.

* Menu:

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


File: octave.info,  Node: Bug Criteria,  Next: Bug Tracker,  Up: Reporting Bugs

D.2.1 Have You Found a Bug?
---------------------------

If you are not sure whether you have found a bug, here are some
guidelines:

   • If Octave gets a fatal signal, for any input whatever, that is a
     bug.  Reliable interpreters never crash.

   • If Octave produces incorrect results, for any input whatever, that
     is a bug.

   • Some output may appear to be incorrect when it is in fact due to a
     program whose behavior is undefined, which happened by chance to
     give the desired results on another system.  For example, the range
     operator may produce different results because of differences in
     the way floating point arithmetic is handled on various systems.

   • If Octave produces an error message for valid input, that is a bug.

   • If Octave does not produce an error message for invalid input, that
     is a bug.  However, you should note that your idea of “invalid
     input” might be my idea of “an extension” or “support for
     traditional practice”.

   • If you are an experienced user of programs like Octave, your
     suggestions for improvement are welcome in any case.


File: octave.info,  Node: Bug Tracker,  Next: Bug Reporting,  Prev: Bug Criteria,  Up: Reporting Bugs

D.2.2 Where to Report Bugs
--------------------------

To report a bug in Octave, submit a bug report to the Octave bug tracker
<https://bugs.octave.org>.

   *Do not send bug reports to ‘help-octave’*.  Most users of Octave do
not want to receive bug reports.


File: octave.info,  Node: Bug Reporting,  Next: Sending Patches,  Prev: Bug Tracker,  Up: Reporting Bugs

D.2.3 How to Report Bugs
------------------------

Submit bug reports for Octave to the Octave bug tracker
<https://bugs.octave.org>.

   The fundamental principle of reporting bugs usefully is this: *report
all the facts*.  If you are not sure whether to state a fact or leave it
out, state it!

   Often people omit facts because they think they know what causes the
problem and they conclude that some details don’t matter.  Thus, you
might assume that the name of the variable you use in an example does
not matter.  Well, probably it doesn’t, but one cannot be sure.  Perhaps
the bug is a stray memory reference which happens to fetch from the
location where that name is stored in memory; perhaps, if the name were
different, the contents of that location would fool the interpreter into
doing the right thing despite the bug.  Play it safe and give a
specific, complete example.

   Keep in mind that the purpose of a bug report is to enable someone to
fix the bug if it is not known.  Always write your bug reports on the
assumption that the bug is not known.

   Sometimes people give a few sketchy facts and ask, “Does this ring a
bell?” This cannot help us fix a bug.  It is better to send a complete
bug report to begin with.

   Try to make your bug report self-contained.  If we have to ask you
for more information, it is best if you include all the previous
information in your response, as well as the information that was
missing.

   To enable someone to investigate the bug, you should include all
these things:

   • The version of Octave.  You can get this by noting the version
     number that is printed when Octave starts, or running it with the
     ‘-v’ option.

   • A complete input file that will reproduce the bug.

     A single statement may not be enough of an example—the bug might
     depend on other details that are missing from the single statement
     where the error finally occurs.

   • The command arguments you gave Octave to execute that example and
     observe the bug.  To guarantee you won’t omit something important,
     list all the options.

     If we were to try to guess the arguments, we would probably guess
     wrong and then we would not encounter the bug.

   • The type of machine you are using, and the operating system name
     and version number.

   • The command-line arguments you gave to the ‘configure’ command when
     you installed the interpreter.

   • A complete list of any modifications you have made to the
     interpreter source.

     Be precise about these changes—show a context diff for them.

   • Details of any other deviations from the standard procedure for
     installing Octave.

   • A description of what behavior you observe that you believe is
     incorrect.  For example, "The interpreter gets a fatal signal," or,
     "The output produced at line 208 is incorrect."

     Of course, if the bug is that the interpreter gets a fatal signal,
     then one can’t miss it.  But if the bug is incorrect output, we
     might not notice unless it is glaringly wrong.

     Even if the problem you experience is a fatal signal, you should
     still say so explicitly.  Suppose something strange is going on,
     such as, your copy of the interpreter is out of sync, or you have
     encountered a bug in the C library on your system.  Your copy might
     crash and the copy here would not.  If you said to expect a crash,
     then when the interpreter here fails to crash, we would know that
     the bug was not happening.  If you don’t say to expect a crash,
     then we would not know whether the bug was happening.  We would not
     be able to draw any conclusion from our observations.

     Often the observed symptom is incorrect output when your program is
     run.  Unfortunately, this is not enough information unless the
     program is short and simple.  It is very helpful if you can include
     an explanation of the expected output, and why the actual output is
     incorrect.

   • If you wish to suggest changes to the Octave source, send them as
     context diffs.  If you even discuss something in the Octave source,
     refer to it by context, not by line number, because the line
     numbers in the development sources probably won’t match those in
     your sources.

   Here are some things that are not necessary:

   • A description of the envelope of the bug.

     Often people who encounter a bug spend a lot of time investigating
     which changes to the input file will make the bug go away and which
     changes will not affect it.  Such information is usually not
     necessary to enable us to fix bugs in Octave, but if you can find a
     simpler example to report _instead_ of the original one, that is a
     convenience.  Errors in the output will be easier to spot, running
     under the debugger will take less time, etc.  Most Octave bugs
     involve just one function, so the most straightforward way to
     simplify an example is to delete all the function definitions
     except the one in which the bug occurs.

     However, simplification is not vital; if you don’t want to do this,
     report the bug anyway and send the entire test case you used.

   • A patch for the bug.  Patches can be helpful, but if you find a
     bug, you should report it, even if you cannot send a fix for the
     problem.


File: octave.info,  Node: Sending Patches,  Prev: Bug Reporting,  Up: Reporting Bugs

D.2.4 Sending Patches for Octave
--------------------------------

If you would like to write bug fixes or improvements for Octave, that is
very helpful.  When you send your changes, please follow these
guidelines to avoid causing extra work for us in studying the patches.

   If you don’t follow these guidelines, your information might still be
useful, but using it will take extra work.  Maintaining Octave is a lot
of work in the best of circumstances, and we can’t keep up unless you do
your best to help.

   • Send an explanation with your changes of what problem they fix or
     what improvement they bring about.  For a bug fix, just include a
     copy of the bug report, and explain why the change fixes the bug.

   • Always include a proper bug report for the problem you think you
     have fixed.  We need to convince ourselves that the change is right
     before installing it.  Even if it is right, we might have trouble
     judging it if we don’t have a way to reproduce the problem.

   • Include all the comments that are appropriate to help people
     reading the source in the future understand why this change was
     needed.

   • Don’t mix together changes made for different reasons.  Send them
     _individually_.

     If you make two changes for separate reasons, then we might not
     want to install them both.  We might want to install just one.

   • Use ‘diff -c’ to make your diffs.  Diffs without context are hard
     for us to install reliably.  More than that, they make it hard for
     us to study the diffs to decide whether we want to install them.
     Unified diff format is better than contextless diffs, but not as
     easy to read as ‘-c’ format.

     If you have GNU diff, use ‘diff -cp’, which shows the name of the
     function that each change occurs in.

   • Write the change log entries for your changes.

     Read the ‘ChangeLog’ file to see what sorts of information to put
     in, and to learn the style that we use.  The purpose of the change
     log is to show people where to find what was changed.  So you need
     to be specific about what functions you changed; in large
     functions, it’s often helpful to indicate where within the function
     the change was made.

     On the other hand, once you have shown people where to find the
     change, you need not explain its purpose.  Thus, if you add a new
     function, all you need to say about it is that it is new.  If you
     feel that the purpose needs explaining, it probably does—but the
     explanation will be much more useful if you put it in comments in
     the code.

     If you would like your name to appear in the header line for who
     made the change, send us the header line.


File: octave.info,  Node: How To Get Help with Octave,  Next: How to Distinguish Between Octave and Matlab,  Prev: Reporting Bugs,  Up: Trouble

D.3 How To Get Help with Octave
===============================

The mailing list <help@octave.org> exists for the discussion of matters
related to using and installing Octave.  If would like to join the
discussion, please send a short note to <help-request@octave.org>.

   *Please do not* send requests to be added or removed from the mailing
list, or other administrative trivia to the list itself.

   If you think you have found a bug in Octave or in the installation
procedure, however, you should submit a complete bug report to the
Octave bug tracker at <https://bugs.octave.org>.  But before you submit
a bug report, please read <https://www.octave.org/bugs.html> to learn
how to submit a useful bug report.


File: octave.info,  Node: How to Distinguish Between Octave and Matlab,  Prev: How To Get Help with Octave,  Up: Trouble

D.4 How to Distinguish Between Octave and Matlab
================================================

Octave and MATLAB are very similar, but handle Java slightly different.
Therefore it may be necessary to detect the environment and use the
appropriate functions.  The following function can be used to detect the
environment.  Due to the persistent variable it can be called repeatedly
without a heavy performance hit.

   Example:

     %%
     %% Return: true if the environment is Octave.
     %%
     function retval = isOctave
       persistent cacheval;  % speeds up repeated calls

       if isempty (cacheval)
         cacheval = (exist ("OCTAVE_VERSION", "builtin") > 0);
       end

       retval = cacheval;
     end


File: octave.info,  Node: Installation,  Next: Grammar and Parser,  Prev: Trouble,  Up: Top

Appendix E Installing Octave
****************************

The procedure for installing Octave from source on a Unix-like system is
described next.  Building on other platforms will follow similar steps.
Note that this description applies to Octave releases.  Building the
development sources from the Mercurial archive requires additional steps
as described in the development source itself.

* Menu:

* Build Dependencies::
* Running Configure and Make::
* Compiling Octave with 64-bit Indexing::
* Installation Problems::


File: octave.info,  Node: Build Dependencies,  Next: Running Configure and Make,  Up: Installation

E.1 Build Dependencies
======================

Octave is a fairly large program with many build dependencies.  You may
be able to find pre-packaged versions of the dependencies distributed as
part of your system, or you may have to build some or all of them
yourself.

* Menu:

* Obtaining the Dependencies Automatically::
* Build Tools::
* External Packages::


File: octave.info,  Node: Obtaining the Dependencies Automatically,  Next: Build Tools,  Up: Build Dependencies

E.1.1 Obtaining the Dependencies Automatically
----------------------------------------------

On some systems you can obtain many of Octave’s build dependencies
automatically.  The commands for doing this vary by system.  Similarly,
the names of pre-compiled packages vary by system and do not always
match exactly the names listed in *note Build Tools:: and *note External
Packages::.

   You will usually need the development version of an external
dependency so that you get the libraries and header files for building
software, not just for running already compiled programs.  These
packages typically have names that end with the suffix ‘-dev’ or
‘-devel’.

   On systems with ‘apt-get’ (Debian, Ubuntu, etc.), you may be able to
install most of the tools and external packages using a command similar
to

     apt-get build-dep octave

The specific package name may be ‘octave3.2’ or ‘octave3.4’.  The set of
required tools and external dependencies does not change frequently, so
it is not important that the version match exactly, but you should use
the most recent one available.

   On systems with ‘yum’ (Fedora, Red Hat, etc.), you may be able to
install most of the tools and external packages using a command similar
to

     yum-builddep octave

The ‘yum-builddep’ utility is part of the ‘yum-utils’ package.

   For either type of system, the package name may include a version
number.  The set of required tools and external dependencies does not
change frequently, so it is not important that the version exactly match
the version you are installing, but you should use the most recent one
available.


File: octave.info,  Node: Build Tools,  Next: External Packages,  Prev: Obtaining the Dependencies Automatically,  Up: Build Dependencies

E.1.2 Build Tools
-----------------

The following tools are required:

C++, C, and Fortran compilers
     The Octave sources are primarily written in C++, but some portions
     are also written in C and Fortran.  The Octave sources are intended
     to be portable.  Recent versions of the GNU compiler collection
     (GCC) should work (<https://gcc.gnu.org>).  If you use GCC, you
     should avoid mixing versions.  For example, be sure that you are
     not using the obsolete ‘g77’ Fortran compiler with modern versions
     of ‘gcc’ and ‘g++’.

GNU Make
     Tool for building software (<https://www.gnu.org/software/make>).
     Octave’s build system requires GNU Make.  Other versions of Make
     will not work.  Fortunately, GNU Make is highly portable and easy
     to install.

AWK, sed, and other Unix utilities
     Basic Unix system utilities are required for building Octave.  All
     will be available with any modern Unix system and also on Windows
     with either Cygwin or MinGW and MSYS.

   Additionally, the following tools may be needed:

Bison
     Parser generator (<https://www.gnu.org/software/bison>).  You will
     need Bison if you modify the ‘oct-parse.yy’ source file or if you
     delete the files that are generated from it.

Flex
     Lexer analyzer (<https://www.gnu.org/software/flex>).  You will
     need Flex if you modify the ‘lex.ll’ source file or if you delete
     the files that are generated from it.

Autoconf
     Package for software configuration
     (<https://www.gnu.org/software/autoconf>).  Autoconf is required if
     you modify Octave’s ‘configure.ac’ file or other files that it
     requires.

Automake
     Package for Makefile generation
     (<https://www.gnu.org/software/automake>).  Automake is required if
     you modify Octave’s ‘Makefile.am’ files or other files that they
     depend on.

Libtool
     Package for building software libraries
     (<https://www.gnu.org/software/libtool>).  Libtool is required by
     Automake.

gperf
     Perfect hash function generator
     (<https://www.gnu.org/software/gperf>).  You will need gperf if you
     modify the ‘octave.gperf’ file or if you delete the file that is
     generated from it.

Texinfo
     Package for generating online and print documentation
     (<https://www.gnu.org/software/texinfo>).  You will need Texinfo to
     build Octave’s documentation or if you modify the documentation
     source files or the docstring of any Octave function.


File: octave.info,  Node: External Packages,  Prev: Build Tools,  Up: Build Dependencies

E.1.3 External Packages
-----------------------

The following external packages are required:

BLAS
     Basic Linear Algebra Subroutine library.  Accelerated BLAS
     libraries such as OpenBLAS (<https://www.openblas.net/>) or ATLAS
     (<http://math-atlas.sourceforge.net>) are recommended for best
     performance.  The reference implementation
     (<http://www.netlib.org/blas>) is slow and suffers from certain
     bugs in corner case inputs.

LAPACK
     Linear Algebra Package (<http://www.netlib.org/lapack>).

PCRE
     The Perl Compatible Regular Expression library
     (<https://www.pcre.org>).

   The following external package is optional but strongly recommended:

GNU Readline
     Command-line editing library (<https://www.gnu.org/s/readline>).

   If you wish to build Octave without GNU readline installed, you must
use the ‘--disable-readline’ option when running the configure script.

   The following external software packages are optional.  Octave can be
built without them but certain features might be missing:

ARPACK
     Library for the solution of large-scale eigenvalue problems
     (<https://forge.scilab.org/index.php/p/arpack-ng>).  ARPACK is
     required to provide the functions ‘eigs’ and ‘svds’.

cURL
     Library for transferring data with URL syntax
     (<https://curl.haxx.se>).  cURL is required to provide the
     ‘urlread’ and ‘urlwrite’ functions and the ‘ftp’ class.

FFTW3
     Library for computing discrete Fourier transforms
     (<http://www.fftw.org>).  FFTW3 is used to provide better
     performance for functions that compute discrete Fourier transforms
     (‘fft’, ‘ifft’, ‘fft2’, etc.)

FLTK
     Portable GUI toolkit (<http://www.fltk.org>).  FLTK can be used to
     provide windows for Octave’s OpenGL-based graphics functions.

fontconfig
     Library for configuring and customizing font access
     (<https://www.freedesktop.org/wiki/Software/fontconfig>).
     Fontconfig is used to manage fonts for Octave’s OpenGL-based
     graphics functions.

FreeType
     Portable font engine (<https://www.freetype.org>).  FreeType is
     used to perform font rendering for Octave’s OpenGL-based graphics
     functions.

GLPK
     GNU Linear Programming Kit (<https://www.gnu.org/software/glpk>).
     GPLK is required for the function ‘glpk’.

gl2ps
     OpenGL to PostScript printing library
     (<https://www.geuz.org/gl2ps/>).  gl2ps is required for printing
     when using OpenGL-based graphics toolkits (currently either FLTK or
     Qt).

gnuplot
     Interactive graphics program (<http://www.gnuplot.info>).  gnuplot
     can be used as a graphics renderer for Octave; prior to Octave 4.0,
     gnuplot was the default graphics renderer.

GraphicsMagick++
     Image processing library (<http://www.graphicsmagick.org>).
     GraphicsMagick++ is used to provide the ‘imread’ and ‘imwrite’
     functions.

HDF5
     Library for manipulating portable data files
     (<https://www.hdfgroup.org/HDF5>).  HDF5 is required for Octave’s
     ‘load’ and ‘save’ commands to read and write HDF data files.

Java Development Kit
     Java programming language compiler and libraries.  The OpenJDK free
     software implementation is recommended
     (<http://openjdk.java.net/>), although other JDK implementations
     may work.  Java is required to be able to call Java functions from
     within Octave.

OpenGL
     API for portable 2-D and 3-D graphics (<https://www.opengl.org>).
     An OpenGL implementation can be used to provide a renderer for
     Octave’s graphics functions.  Octave’s OpenGL-based graphics
     functions usually outperform the gnuplot-based graphics functions
     because plot data can be rendered directly instead of sending data
     and commands to gnuplot for interpretation and rendering.  Since
     Octave 4.0, the default graphics renderer ("qt") has been
     OpenGL-based.

PortAudio
     PortAudio (<http://www.portaudio.com/>) provides a very simple API
     for recording and/or playing sound using a simple callback function
     or a blocking read/write interface.  It is required for the audio
     processing functions ‘audioplayer’, ‘audiorecorder’, and
     ‘audiodevinfo’.

Qhull
     Computational geometry library (<http://www.qhull.org>).  Qhull is
     required to provide the functions ‘convhull’, ‘convhulln’,
     ‘delaunay’, ‘delaunayn’, ‘voronoi’, and ‘voronoin’.

QRUPDATE
     QR factorization updating library
     (<https://sourceforge.net/projects/qrupdate>).  QRUPDATE is used to
     provide improved performance for the functions ‘qrdelete’,
     ‘qrinsert’, ‘qrshift’, and ‘qrupdate’.

QScintilla
     Source code highlighter and manipulator; a Qt port of Scintilla
     (<http://www.riverbankcomputing.co.uk/software/qscintilla>).
     QScintilla is used for syntax highlighting and code completion in
     the GUI.

Qt
     GUI and utility libraries (<https://www.qt.io>).  Qt is required
     for building the GUI.  It is a large framework, but the only
     components required are the GUI, core, and network modules.  Since
     Octave 4.0, the default graphics renderer ("qt") has been Qt-based,
     which has been OpenGL-based.

RapidJSON
     A fast JSON parser/generator for C++ with both SAX/DOM style API
     (<https://rapidjson.org/>).  RapidJSON is required to read or write
     from or to JSON files with the functions ‘jsondecode’ and
     ‘jsonencode’.

SuiteSparse
     Sparse matrix factorization library
     (<http://faculty.cse.tamu.edu/davis/suitesparse.html>).
     SuiteSparse is required to provide sparse matrix factorizations and
     solution of linear equations for sparse systems.

SUNDIALS
     The SUite of Nonlinear and DIfferential/ALgebraic Equation Solvers
     (<https://computation.llnl.gov/projects/sundials>) is required for
     the Ordinary Differential Equations (ODE) solvers ‘ode15i’ and
     ‘ode15s’.

zlib
     Data compression library (<https://zlib.net>).  The zlib library is
     required for Octave’s ‘load’ and ‘save’ commands to handle
     compressed data, including MATLAB v5 MAT files.


File: octave.info,  Node: Running Configure and Make,  Next: Compiling Octave with 64-bit Indexing,  Prev: Build Dependencies,  Up: Installation

E.2 Running Configure and Make
==============================

   • Run the shell script ‘configure’.  This will determine the features
     your system has (or doesn’t have) and create a file named
     ‘Makefile’ from each of the files named ‘Makefile.in’.

     For a complete list of configure options, run ‘configure --help’.
     Here is a summary of the configure options that are most frequently
     used when building Octave:

     ‘--help’
          Print a summary of the options recognized by the configure
          script.

     ‘--prefix=PREFIX’
          Install Octave in subdirectories below PREFIX.  The default
          value of PREFIX is ‘/usr/local’.

     ‘--srcdir=DIR’
          Look for Octave sources in the directory DIR.

     ‘--disable-64’
          Disable using 64-bit integers for indexing arrays and use
          32-bit integers instead.  On systems with 32-bit pointers,
          this option is always disabled.  If the configure script
          determines that your BLAS library uses 32-bit integers, then
          operations using the following libraries are limited to arrays
          with dimensions that are smaller than 2^{31} elements:

             • BLAS

             • LAPACK

             • QRUPDATE

             • SuiteSparse

             • ARPACK

          Additionally, the following libraries use ‘int’ internally, so
          maximum problem sizes are always limited:

             • GLPK

             • Qhull

          *Note Compiling Octave with 64-bit Indexing::, for more
          details about building Octave with more complete support for
          large arrays.

     ‘--enable-address-sanitizer-flags’
          Enable compiler options ‘-fsanitize=address’ and
          ‘-fomit-frame-pointer’ for memory access checking.  This
          option is primarily used for debugging Octave.  Building
          Octave with this option has a negative impact on performance
          and is not recommended for general use.  It may also interfere
          with proper functioning of the GUI.

     ‘--disable-docs’
          Disable building all forms of the documentation (Info, PDF,
          HTML). The default is to build documentation, but your system
          will need functioning Texinfo and TeX installs for this to
          succeed.

     ‘--enable-float-truncate’
          This option allows for truncation of intermediate floating
          point results in calculations.  It is only necessary for
          certain platforms.

     ‘--enable-readline’
          Use the readline library to provide for editing of the command
          line in terminal environments.  This option is on by default.

     ‘--enable-shared’
          Create shared libraries (this is the default).  If you are
          planning to use the dynamic loading features, you will
          probably want to use this option.  It will make your ‘.oct’
          files much smaller and on some systems it may be necessary to
          build shared libraries in order to use dynamically linked
          functions.

          You may also want to build a shared version of ‘libstdc++’, if
          your system doesn’t already have one.

     ‘--with-blas=<lib>’
          By default, configure looks for the best BLAS matrix libraries
          on your system, including optimized implementations such as
          the free ATLAS 3.0, as well as vendor-tuned libraries.  (The
          use of an optimized BLAS will generally result in
          several-times faster matrix operations.)  Use this option to
          specify a particular BLAS library that Octave should use.

     ‘--with-lapack=<lib>’
          By default, configure looks for the best LAPACK matrix
          libraries on your system, including optimized implementations
          such as the free ATLAS 3.0, as well as vendor-tuned libraries.
          (The use of an optimized LAPACK will generally result in
          several-times faster matrix operations.)  Use this option to
          specify a particular LAPACK library that Octave should use.

     ‘--with-magick=<lib>’
          Select the Magick++ library to use for image I/O.  For many
          distributions, possible values are "GraphicsMagick++"
          (default) or "ImageMagick++".

     ‘--with-sepchar=<char>’
          Use <char> as the path separation character.  This option can
          help when running Octave on non-Unix systems.

     ‘--without-amd’
          Don’t use AMD, disable some sparse matrix functionality.

     ‘--without-camd’
          Don’t use CAMD, disable some sparse matrix functionality.

     ‘--without-colamd’
          Don’t use COLAMD, disable some sparse matrix functionality.

     ‘--without-ccolamd’
          Don’t use CCOLAMD, disable some sparse matrix functionality.

     ‘--without-cholmod’
          Don’t use CHOLMOD, disable some sparse matrix functionality.

     ‘--without-curl’
          Don’t use the cURL library, disable the ftp objects, ‘urlread’
          and ‘urlwrite’ functions.

     ‘--without-cxsparse’
          Don’t use CXSPARSE, disable some sparse matrix functionality.

     ‘--without-fftw3’
          Use the included FFTPACK library for computing Fast Fourier
          Transforms instead of the FFTW3 library.

     ‘--without-fftw3f’
          Use the included FFTPACK library for computing Fast Fourier
          Transforms instead of the FFTW3 library when operating on
          single precision (float) values.

     ‘--without-glpk’
          Don’t use the GLPK library for linear programming.

     ‘--without-hdf5’
          Don’t use the HDF5 library, disable reading and writing of
          HDF5 files.

     ‘--without-opengl’
          Don’t use OpenGL, disable native graphics toolkit for
          plotting.  You will need ‘gnuplot’ installed in order to make
          plots.

     ‘--without-qhull_r’
          Don’t use (re-entrant) Qhull, disable ‘delaunay’, ‘convhull’,
          and related functions.

     ‘--without-qrupdate’
          Don’t use QRUPDATE, disable QR and Cholesky update functions.

     ‘--without-umfpack’
          Don’t use UMFPACK, disable some sparse matrix functionality.

     ‘--without-z’
          Don’t use the zlib library, disable data file compression and
          support for recent MAT file formats.

     ‘--without-framework-carbon’
          Don’t use framework Carbon headers, libraries, or specific
          source code even if the configure test succeeds (the default
          is to use Carbon framework if available).  This is a platform
          specific configure option for Mac systems.

     ‘--without-framework-opengl’
          Don’t use framework OpenGL headers, libraries, or specific
          source code even if the configure test succeeds.  If this
          option is given then OpenGL headers and libraries in standard
          system locations are tested (the default value is
          ‘--with-framework-opengl’).  This is a platform specific
          configure option for Mac systems.

     See the file ‘INSTALL’ for more general information about the
     command line options used by configure.  That file also contains
     instructions for compiling in a directory other than the one where
     the source is located.

   • Run make.

     You will need a recent version of GNU Make as Octave relies on
     certain features not generally available in all versions of make.
     Modifying Octave’s makefiles to work with other make programs is
     probably not worth your time; instead, we simply recommend
     installing GNU Make.

     There are currently three options for plotting in Octave: the
     external program gnuplot, the internal graphics engine using OpenGL
     coupled with either FLTK or Qt widgets.  Gnuplot is a
     command-driven interactive function plotting program.

     To compile Octave, you will need a recent version of ‘g++’ or other
     ANSI C++ compiler.  In addition, you will need a Fortran 77
     compiler or ‘f2c’.  If you use ‘f2c’, you will need a script like
     ‘fort77’ that works like a normal Fortran compiler by combining
     ‘f2c’ with your C compiler in a single script.

     If you plan to modify the parser you will also need GNU ‘bison’ and
     ‘flex’.  If you modify the documentation, you will need GNU
     Texinfo.

     GNU Make, ‘gcc’ (and ‘libstdc++’), ‘gnuplot’, ‘bison’, ‘flex’, and
     Texinfo are all available from many anonymous ftp archives.  The
     primary site is <ftp://ftp.gnu.org>, but it is often very busy.  A
     list of sites that mirror the software on <ftp://ftp.gnu.org> is
     available by anonymous ftp from
     <ftp://ftp.gnu.org/pub/gnu/GNUinfo/FTP>.

     Octave requires approximately 1.4 GB of disk storage to unpack and
     compile from source (significantly less, 400 MB, if you don’t
     compile with debugging symbols).  To compile without debugging
     symbols try the command

          make CFLAGS=-O CXXFLAGS=-O LDFLAGS=

     instead of just ‘make’.

   • If you encounter errors while compiling Octave, first see *note
     Installation Problems:: for a list of known problems and if there
     is a workaround or solution for your problem.  If not, see *note
     Trouble:: for information about how to report bugs.

   • Once you have successfully compiled Octave, run ‘make install’.

     This will install a copy of Octave, its libraries, and its
     documentation in the destination directory.  As distributed, Octave
     is installed in the following directories.  In the table below,
     PREFIX defaults to ‘/usr/local’, VERSION stands for the current
     version number of the interpreter, and ARCH is the type of computer
     on which Octave is installed (for example, ‘i586-unknown-gnu’).

     ‘PREFIX/bin’
          Octave and other binaries that people will want to run
          directly.

     ‘PREFIX/lib/octave-VERSION’
          Libraries like liboctave.a and liboctinterp.a.

     ‘PREFIX/include/octave-VERSION/octave’
          Include files distributed with Octave.

     ‘PREFIX/share’
          Architecture-independent data files.

     ‘PREFIX/share/man/man1’
          Unix-style man pages describing Octave.

     ‘PREFIX/share/info’
          Info files describing Octave.

     ‘PREFIX/share/octave/VERSION/m’
          Function files distributed with Octave.  This includes the
          Octave version, so that multiple versions of Octave may be
          installed at the same time.

     ‘PREFIX/libexec/octave/VERSION/exec/ARCH’
          Executables to be run by Octave rather than the user.

     ‘PREFIX/lib/octave/VERSION/oct/ARCH’
          Object files that will be dynamically loaded.

     ‘PREFIX/share/octave/VERSION/imagelib’
          Image files that are distributed with Octave.


File: octave.info,  Node: Compiling Octave with 64-bit Indexing,  Next: Installation Problems,  Prev: Running Configure and Make,  Up: Installation

E.3 Compiling Octave with 64-bit Indexing
=========================================

Note: the following only applies to systems that have 64-bit pointers.
Configuring Octave with ‘--enable-64’ cannot magically make a 32-bit
system have a 64-bit address space.

   On 64-bit systems, Octave uses 64-bit integers for indexing arrays by
default.  If the configure script determines that your BLAS library uses
32-bit integers, then operations using the following libraries are
limited to arrays with dimensions that are smaller than 2^{31} elements:

   • BLAS

   • LAPACK

   • QRUPDATE

   • SuiteSparse

   • SUNDIALS IDA

   • ARPACK

   Additionally, the following libraries use ‘int’ internally, so
maximum problem sizes are always limited:

   • GLPK

   • Qhull

   Except for GLPK and Qhull, these libraries may also be configured to
use 64-bit integers, but most systems do not provide packages built this
way.  If you wish to experiment with large arrays, the following
information may be helpful.

   To determine the integer size of the BLAS library used by Octave, the
following code can be executed:

     clear all;
     N = 2^31;
     ## The following line requires about 8 GB of RAM!
     a = b = ones (N, 1, "single");
     c = a' * b

   If the BLAS library uses 32-bit integers, an error will be thrown:

     error: integer dimension or index out of range for Fortran
     INTEGER type

   Otherwise, if the BLAS library uses 64-bit integers, the result is:

     c = 2^31 = 2147483648

   Note that the test case above usually requires twice the memory, if A
and B are not assigned by ‘a = b = ...’.  Note further, that the data
type ‘single’ has a precision of about 23 binary bits.  In this
particular example no rounding errors occur.

   Generally, it is best to have all of these libraries in versions that
support 32-bit indexing, or all of these libraries must support 64-bit
indexing.  Mixing libraries with 64-bit indexing with libraries with
32-bit indexing can cause unpredictable behavior including program
crashes with possible loss of data.

   The following instructions were tested with the development version
of Octave and GCC 4.3.4 on an x86_64 Debian system and may be out of
date now.  Please report any problems or corrections on the Octave bug
tracker.

   The versions listed below are the versions used for testing.  If
newer versions of these packages are available, you should try to use
them, although there may be some differences.

   All libraries and header files will be installed in subdirectories of
‘$prefix64’ (you must choose the location of this directory).

   • BLAS and LAPACK (<http://www.netlib.org/lapack>)

     Reference versions for both libraries are included in the reference
     LAPACK 3.2.1 distribution from <http://www.netlib.org/>.

        − Copy the file ‘make.inc.example’ and name it ‘make.inc’.  The
          options ‘-fdefault-integer-8’ and ‘-fPIC’ (on 64-bit CPU) have
          to be added to the variable ‘OPTS’ and ‘NOOPT’.

        − Once you have compiled this library make sure that you use it
          for compiling Suite Sparse and Octave.  In the following we
          assume that you installed the LAPACK library as
          $prefix64/lib/liblapack.a.

   • QRUPDATE (<https://sourceforge.net/projects/qrupdate>)

     In the ‘Makeconf’ file:

        − Add ‘-fdefault-integer-8’ to ‘FFLAGS’.

        − Adjust the BLAS and LAPACK variables as needed if your 64-bit
          aware BLAS and LAPACK libraries are in a non-standard
          location.

        − Set ‘PREFIX’ to the top-level directory of your install tree.

        − Run ‘make solib’ to make a shared library.

        − Run ‘make install’ to install the library.

   • SuiteSparse (<http://faculty.cse.tamu.edu/davis/suitesparse.html>)

     Pass the following options to ‘make’ to enable 64-bit integers for
     BLAS library calls.  On 64-bit Windows systems, use
     ‘-DLONGBLAS="long long"’ instead.

          CFLAGS='-DLONGBLAS=long'
          CXXFLAGS='-DLONGBLAS=long'

     The SuiteSparse makefiles don’t generate shared libraries.  On some
     systems, you can generate them by doing something as simple as

          top=$(pwd)
          for f in *.a; do
            mkdir tmp
            cd tmp
            ar vx ../$f
            gcc -shared -o ../${f%%.a}.so *.o
            cd $top
            rm -rf tmp
          done

     Other systems may require a different solution.

   • SUNDIALS IDA (<https://computing.llnl.gov/projects/sundials/ida>)

     When configuring with ‘cmake’ add the flag
     ‘-DSUNDIALS_INDEX_SIZE=64’.

   • ARPACK (<https://forge.scilab.org/index.php/p/arpack-ng/>)

        − Add ‘-fdefault-integer-8’ to ‘FFLAGS’ when running configure.

        − Run ‘make’ to build the library.

        − Run ‘make install’ to install the library.

   • ATLAS instead of reference BLAS and LAPACK

     Suggestions on how to compile ATLAS would be most welcome.

   • GLPK

   • Qhull (<http://www.qhull.org>)

     Both GLPK and Qhull use ‘int’ internally so maximum problem sizes
     may be limited.

   • Octave

     Octave’s 64-bit index support is activated with the configure
     option ‘--enable-64’.

          ./configure \
            LD_LIBRARY_PATH="$prefix64/lib" \
            CPPFLAGS="-I$prefix64/include" LDFLAGS="-L$prefix64/lib" \
            --enable-64

     You must ensure that all Fortran sources except those in the
     ‘liboctave/external/ranlib’ directory are compiled such that
     INTEGERS are 8-bytes wide.  If you are using gfortran, the
     configure script should automatically set the Makefile variable
     ‘F77_INTEGER_8_FLAG’ to ‘-fdefault-integer-8’.  If you are using
     another compiler, you must set this variable yourself.  You should
     NOT set this flag in ‘FFLAGS’, otherwise the files in
     ‘liboctave/external/ranlib’ will be miscompiled.

   • Other dependencies

     Probably nothing special needs to be done for the following
     dependencies.  If you discover that something does need to be done,
     please submit a bug report.

        − pcre

        − zlib

        − hdf5

        − fftw3

        − cURL

        − GraphicsMagick++

        − OpenGL

        − freetype

        − fontconfig

        − fltk


File: octave.info,  Node: Installation Problems,  Prev: Compiling Octave with 64-bit Indexing,  Up: Installation

E.4 Installation Problems
=========================

This section contains a list of problems (and some apparent problems
that don’t really mean anything is wrong) that may show up during
installation of Octave.

   • On some SCO systems, ‘info’ fails to compile if ‘HAVE_TERMIOS_H’ is
     defined in ‘config.h’.  Simply removing the definition from
     ‘info/config.h’ should allow it to compile.

   • If ‘configure’ finds ‘dlopen’, ‘dlsym’, ‘dlclose’, and ‘dlerror’,
     but not the header file ‘dlfcn.h’, you need to find the source for
     the header file and install it in the directory ‘usr/include’.
     This is reportedly a problem with Slackware 3.1.  For Linux/GNU
     systems, the source for ‘dlfcn.h’ is in the ‘ldso’ package.

   • Building ‘.oct’ files doesn’t work.

     You should probably have a shared version of ‘libstdc++’.  A patch
     is needed to build shared versions of version 2.7.2 of ‘libstdc++’
     on the HP-PA architecture.  You can find the patch at
     <ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix>.

   • On some DEC alpha systems there may be a problem with the ‘libdxml’
     library, resulting in floating point errors and/or segmentation
     faults in the linear algebra routines called by Octave.  If you
     encounter such problems, then you should modify the configure
     script so that ‘SPECIAL_MATH_LIB’ is not set to ‘-ldxml’.

   • On FreeBSD systems Octave may hang while initializing some internal
     constants.  The fix appears to be to use

          options      GPL_MATH_EMULATE

     rather than

          options      MATH_EMULATE

     in the kernel configuration files (typically found in the directory
     ‘/sys/i386/conf’).  After making this change, you’ll need to
     rebuild the kernel, install it, and reboot.

   • If you encounter errors like

          passing `void (*)()' as argument 2 of
            `octave_set_signal_handler(int, void (*)(int))'

     or

          warning: ANSI C++ prohibits conversion from `(int)'
                   to `(...)'

     while compiling ‘sighandlers.cc’, you may need to edit some files
     in the ‘gcc’ include subdirectory to add proper prototypes for
     functions there.  For example, Ultrix 4.2 needs proper declarations
     for the ‘signal’ function and the ‘SIG_IGN’ macro in the file
     ‘signal.h’.

     On some systems the ‘SIG_IGN’ macro is defined to be something like
     this:

          #define  SIG_IGN  (void (*)())1

     when it should really be something like:

          #define  SIG_IGN  (void (*)(int))1

     to match the prototype declaration for the ‘signal’ function.  This
     change should also be made for the ‘SIG_DFL’ and ‘SIG_ERR’ symbols.
     It may be necessary to change the definitions in ‘sys/signal.h’ as
     well.

     The ‘gcc’ ‘fixincludes’ and ‘fixproto’ scripts should probably fix
     these problems when ‘gcc’ installs its modified set of header
     files, but I don’t think that’s been done yet.

     *You should not change the files in ‘/usr/include’*.  You can find
     the ‘gcc’ include directory tree by running the command

          gcc -print-libgcc-file-name

     The directory of ‘gcc’ include files normally begins in the same
     directory that contains the file ‘libgcc.a’.

   • Some of the Fortran subroutines may fail to compile with older
     versions of the Sun Fortran compiler.  If you get errors like

          zgemm.f:
                  zgemm:
          warning: unexpected parent of complex expression subtree
          zgemm.f, line 245: warning: unexpected parent of complex
            expression subtree
          warning: unexpected parent of complex expression subtree
          zgemm.f, line 304: warning: unexpected parent of complex
            expression subtree
          warning: unexpected parent of complex expression subtree
          zgemm.f, line 327: warning: unexpected parent of complex
            expression subtree
          pcc_binval: missing IR_CONV in complex op
          make[2]: *** [zgemm.o] Error 1

     when compiling the Fortran subroutines in the ‘liboctave/external’
     subdirectory, you should either upgrade your compiler or try
     compiling with optimization turned off.

   • On NeXT systems, if you get errors like this:

          /usr/tmp/cc007458.s:unknown:Undefined local
                symbol LBB7656
          /usr/tmp/cc007458.s:unknown:Undefined local
                symbol LBE7656

     when compiling ‘Array.cc’ and ‘Matrix.cc’, try recompiling these
     files without ‘-g’.

   • Some people have reported that calls to system() and the pager do
     not work on SunOS systems.  This is apparently due to having
     ‘G_HAVE_SYS_WAIT’ defined to be 0 instead of 1 when compiling
     ‘libg++’.

   • On systems where the reference BLAS library is used the following
     matrix-by-vector multiplication incorrectly handles NaN values of
     the form ‘NaN * 0’.

          [NaN, 1; 0, 0] * [0; 1]
          ⇒
          [ 1
            0 ]

          correct result ⇒
          [ NaN
            0   ]

     Install a different BLAS library such as OpenBLAS or ATLAS to
     correct this issue.

   • On NeXT systems, linking to ‘libsys_s.a’ may fail to resolve the
     following functions

          _tcgetattr
          _tcsetattr
          _tcflow

     which are part of ‘libposix.a’.  Unfortunately, linking Octave with
     ‘-posix’ results in the following undefined symbols.

          .destructors_used
          .constructors_used
          _objc_msgSend
          _NXGetDefaultValue
          _NXRegisterDefaults
          .objc_class_name_NXStringTable
          .objc_class_name_NXBundle

     One kluge around this problem is to extract ‘termios.o’ from
     ‘libposix.a’, put it in Octave’s ‘src’ directory, and add it to the
     list of files to link together in the makefile.  Suggestions for
     better ways to solve this problem are welcome!

   • If Octave crashes immediately with a floating point exception, it
     is likely that it is failing to initialize the IEEE floating point
     values for infinity and NaN.

     If your system actually does support IEEE arithmetic, you should be
     able to fix this problem by modifying the function
     ‘octave_ieee_init’ in the file ‘lo-ieee.cc’ to correctly initialize
     Octave’s internal infinity and NaN variables.

     If your system does not support IEEE arithmetic but Octave’s
     configure script incorrectly determined that it does, you can work
     around the problem by editing the file ‘config.h’ to not define
     ‘HAVE_ISINF’, ‘HAVE_FINITE’, and ‘HAVE_ISNAN’.

     In any case, please report this as a bug since it might be possible
     to modify Octave’s configuration script to automatically determine
     the proper thing to do.

   • If Octave is unable to find a header file because it is installed
     in a location that is not normally searched by the compiler, you
     can add the directory to the include search path by specifying (for
     example) ‘CPPFLAGS=-I/some/nonstandard/directory’ as an argument to
     ‘configure’.  Other variables that can be specified this way are
     ‘CFLAGS’, ‘CXXFLAGS’, ‘FFLAGS’, and ‘LDFLAGS’.  Passing them as
     options to the configure script also records them in the
     ‘config.status’ file.  By default, ‘CPPFLAGS’ and ‘LDFLAGS’ are
     empty, ‘CFLAGS’ and ‘CXXFLAGS’ are set to "-g -O2" and ‘FFLAGS’ is
     set to "-O".


File: octave.info,  Node: Grammar and Parser,  Next: Copying,  Prev: Installation,  Up: Top

Appendix F Grammar and Parser
*****************************

This appendix will eventually contain a semi-formal description of
Octave’s language.

* Menu:

* Keywords::
* Parser::


File: octave.info,  Node: Keywords,  Next: Parser,  Up: Grammar and Parser

F.1 Keywords
============

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

‘__FILE__’               ‘__LINE__’               ‘break’
‘case’                   ‘catch’                  ‘classdef’
‘continue’               ‘do’                     ‘else’
‘elseif’                 ‘end’                    ‘end_try_catch’
‘end_unwind_protect’     ‘endclassdef’            ‘endenumeration’
‘endevents’              ‘endfor’                 ‘endfunction’
‘endif’                  ‘endmethods’             ‘endparfor’
‘endproperties’          ‘endswitch’              ‘endwhile’
‘enumeration’            ‘events’                 ‘for’
‘function’               ‘global’                 ‘if’
‘methods’                ‘otherwise’              ‘parfor’
‘persistent’             ‘properties’             ‘return’
‘switch’                 ‘try’                    ‘until’
‘unwind_protect’         ‘unwind_protect_cleanup’ ‘while’

   The function ‘iskeyword’ can be used to quickly check whether an
identifier is reserved by Octave.

 -- : iskeyword ()
 -- : iskeyword (NAME)
     Return true if NAME is an Octave keyword.

     If NAME is omitted, return a list of keywords.

     See also: *note isvarname: XREFisvarname, *note exist: XREFexist.


File: octave.info,  Node: Parser,  Prev: Keywords,  Up: Grammar and Parser

F.2 Parser
==========

The parser has a number of variables that affect its internal operation.
These variables are generally documented in the manual alongside the
code that they affect.

   In addition, there are three non-specific parser customization
functions.  ‘add_input_event_hook’ can be used to schedule a user
function for periodic evaluation.  ‘remove_input_event_hook’ will stop a
user function from being evaluated periodically.

 -- : ID = add_input_event_hook (FCN)
 -- : ID = add_input_event_hook (FCN, DATA)
     Add the named function or function handle FCN to the list of
     functions to call periodically when Octave is waiting for input.

     The function should have the form

          FCN (DATA)

     If DATA is omitted, Octave calls the function without any
     arguments.

     The returned identifier may be used to remove the function handle
     from the list of input hook functions.

     See also: *note remove_input_event_hook:
     XREFremove_input_event_hook.

 -- : remove_input_event_hook (NAME)
 -- : remove_input_event_hook (FCN_ID)
     Remove the named function or function handle with the given
     identifier from the list of functions to call periodically when
     Octave is waiting for input.

     See also: *note add_input_event_hook: XREFadd_input_event_hook.

   Finally, when the parser cannot identify an input token it calls a
particular function to handle this.  By default, this is the internal
function "__unimplemented__" which makes suggestions about possible
Octave substitutes for MATLAB functions.

 -- : VAL = missing_function_hook ()
 -- : OLD_VAL = missing_function_hook (NEW_VAL)
 -- : OLD_VAL = missing_function_hook (NEW_VAL, "local")
     Query or set the internal variable that specifies the function to
     call to provide extra information when an unknown identifier is
     referenced.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note missing_component_hook: XREFmissing_component_hook.


File: octave.info,  Node: Copying,  Next: Concept Index,  Prev: Grammar and Parser,  Up: Top

Appendix G GNU GENERAL PUBLIC LICENSE
*************************************

                        Version 3, 29 June 2007

     Copyright © 2007 Free Software Foundation, Inc. <https://fsf.org/>

     Everyone is permitted to copy and distribute verbatim copies of this
     license document, but changing it is not allowed.

Preamble
========

The GNU General Public License is a free, copyleft license for software
and other kinds of works.

   The licenses for most software and other practical works are designed
to take away your freedom to share and change the works.  By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program—to make sure it remains free
software for all its users.  We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors.  You can apply it to
your programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.

   To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights.  Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received.  You must make sure that they, too, receive
or can get the source code.  And you must show them these terms so they
know their rights.

   Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.

   For the developers’ and authors’ protection, the GPL clearly explains
that there is no warranty for this free software.  For both users’ and
authors’ sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.

   Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so.  This is fundamentally incompatible with the aim of
protecting users’ freedom to change the software.  The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable.  Therefore, we
have designed this version of the GPL to prohibit the practice for those
products.  If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.

   Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary.  To prevent this, the GPL assures that
patents cannot be used to render the program non-free.

   The precise terms and conditions for copying, distribution and
modification follow.

TERMS AND CONDITIONS
====================

  0. Definitions.

     “This License” refers to version 3 of the GNU General Public
     License.

     “Copyright” also means copyright-like laws that apply to other
     kinds of works, such as semiconductor masks.

     “The Program” refers to any copyrightable work licensed under this
     License.  Each licensee is addressed as “you”.  “Licensees” and
     “recipients” may be individuals or organizations.

     To “modify” a work means to copy from or adapt all or part of the
     work in a fashion requiring copyright permission, other than the
     making of an exact copy.  The resulting work is called a “modified
     version” of the earlier work or a work “based on” the earlier work.

     A “covered work” means either the unmodified Program or a work
     based on the Program.

     To “propagate” a work means to do anything with it that, without
     permission, would make you directly or secondarily liable for
     infringement under applicable copyright law, except executing it on
     a computer or modifying a private copy.  Propagation includes
     copying, distribution (with or without modification), making
     available to the public, and in some countries other activities as
     well.

     To “convey” a work means any kind of propagation that enables other
     parties to make or receive copies.  Mere interaction with a user
     through a computer network, with no transfer of a copy, is not
     conveying.

     An interactive user interface displays “Appropriate Legal Notices”
     to the extent that it includes a convenient and prominently visible
     feature that (1) displays an appropriate copyright notice, and (2)
     tells the user that there is no warranty for the work (except to
     the extent that warranties are provided), that licensees may convey
     the work under this License, and how to view a copy of this
     License.  If the interface presents a list of user commands or
     options, such as a menu, a prominent item in the list meets this
     criterion.

  1. Source Code.

     The “source code” for a work means the preferred form of the work
     for making modifications to it.  “Object code” means any non-source
     form of a work.

     A “Standard Interface” means an interface that either is an
     official standard defined by a recognized standards body, or, in
     the case of interfaces specified for a particular programming
     language, one that is widely used among developers working in that
     language.

     The “System Libraries” of an executable work include anything,
     other than the work as a whole, that (a) is included in the normal
     form of packaging a Major Component, but which is not part of that
     Major Component, and (b) serves only to enable use of the work with
     that Major Component, or to implement a Standard Interface for
     which an implementation is available to the public in source code
     form.  A “Major Component”, in this context, means a major
     essential component (kernel, window system, and so on) of the
     specific operating system (if any) on which the executable work
     runs, or a compiler used to produce the work, or an object code
     interpreter used to run it.

     The “Corresponding Source” for a work in object code form means all
     the source code needed to generate, install, and (for an executable
     work) run the object code and to modify the work, including scripts
     to control those activities.  However, it does not include the
     work’s System Libraries, or general-purpose tools or generally
     available free programs which are used unmodified in performing
     those activities but which are not part of the work.  For example,
     Corresponding Source includes interface definition files associated
     with source files for the work, and the source code for shared
     libraries and dynamically linked subprograms that the work is
     specifically designed to require, such as by intimate data
     communication or control flow between those subprograms and other
     parts of the work.

     The Corresponding Source need not include anything that users can
     regenerate automatically from other parts of the Corresponding
     Source.

     The Corresponding Source for a work in source code form is that
     same work.

  2. Basic Permissions.

     All rights granted under this License are granted for the term of
     copyright on the Program, and are irrevocable provided the stated
     conditions are met.  This License explicitly affirms your unlimited
     permission to run the unmodified Program.  The output from running
     a covered work is covered by this License only if the output, given
     its content, constitutes a covered work.  This License acknowledges
     your rights of fair use or other equivalent, as provided by
     copyright law.

     You may make, run and propagate covered works that you do not
     convey, without conditions so long as your license otherwise
     remains in force.  You may convey covered works to others for the
     sole purpose of having them make modifications exclusively for you,
     or provide you with facilities for running those works, provided
     that you comply with the terms of this License in conveying all
     material for which you do not control copyright.  Those thus making
     or running the covered works for you must do so exclusively on your
     behalf, under your direction and control, on terms that prohibit
     them from making any copies of your copyrighted material outside
     their relationship with you.

     Conveying under any other circumstances is permitted solely under
     the conditions stated below.  Sublicensing is not allowed; section
     10 makes it unnecessary.

  3. Protecting Users’ Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
     measure under any applicable law fulfilling obligations under
     article 11 of the WIPO copyright treaty adopted on 20 December
     1996, or similar laws prohibiting or restricting circumvention of
     such measures.

     When you convey a covered work, you waive any legal power to forbid
     circumvention of technological measures to the extent such
     circumvention is effected by exercising rights under this License
     with respect to the covered work, and you disclaim any intention to
     limit operation or modification of the work as a means of
     enforcing, against the work’s users, your or third parties’ legal
     rights to forbid circumvention of technological measures.

  4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program’s source code as you
     receive it, in any medium, provided that you conspicuously and
     appropriately publish on each copy an appropriate copyright notice;
     keep intact all notices stating that this License and any
     non-permissive terms added in accord with section 7 apply to the
     code; keep intact all notices of the absence of any warranty; and
     give all recipients a copy of this License along with the Program.

     You may charge any price or no price for each copy that you convey,
     and you may offer support or warranty protection for a fee.

  5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
     produce it from the Program, in the form of source code under the
     terms of section 4, provided that you also meet all of these
     conditions:

       a. The work must carry prominent notices stating that you
          modified it, and giving a relevant date.

       b. The work must carry prominent notices stating that it is
          released under this License and any conditions added under
          section 7.  This requirement modifies the requirement in
          section 4 to “keep intact all notices”.

       c. You must license the entire work, as a whole, under this
          License to anyone who comes into possession of a copy.  This
          License will therefore apply, along with any applicable
          section 7 additional terms, to the whole of the work, and all
          its parts, regardless of how they are packaged.  This License
          gives no permission to license the work in any other way, but
          it does not invalidate such permission if you have separately
          received it.

       d. If the work has interactive user interfaces, each must display
          Appropriate Legal Notices; however, if the Program has
          interactive interfaces that do not display Appropriate Legal
          Notices, your work need not make them do so.

     A compilation of a covered work with other separate and independent
     works, which are not by their nature extensions of the covered
     work, and which are not combined with it such as to form a larger
     program, in or on a volume of a storage or distribution medium, is
     called an “aggregate” if the compilation and its resulting
     copyright are not used to limit the access or legal rights of the
     compilation’s users beyond what the individual works permit.
     Inclusion of a covered work in an aggregate does not cause this
     License to apply to the other parts of the aggregate.

  6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
     of sections 4 and 5, provided that you also convey the
     machine-readable Corresponding Source under the terms of this
     License, in one of these ways:

       a. Convey the object code in, or embodied in, a physical product
          (including a physical distribution medium), accompanied by the
          Corresponding Source fixed on a durable physical medium
          customarily used for software interchange.

       b. Convey the object code in, or embodied in, a physical product
          (including a physical distribution medium), accompanied by a
          written offer, valid for at least three years and valid for as
          long as you offer spare parts or customer support for that
          product model, to give anyone who possesses the object code
          either (1) a copy of the Corresponding Source for all the
          software in the product that is covered by this License, on a
          durable physical medium customarily used for software
          interchange, for a price no more than your reasonable cost of
          physically performing this conveying of source, or (2) access
          to copy the Corresponding Source from a network server at no
          charge.

       c. Convey individual copies of the object code with a copy of the
          written offer to provide the Corresponding Source.  This
          alternative is allowed only occasionally and noncommercially,
          and only if you received the object code with such an offer,
          in accord with subsection 6b.

       d. Convey the object code by offering access from a designated
          place (gratis or for a charge), and offer equivalent access to
          the Corresponding Source in the same way through the same
          place at no further charge.  You need not require recipients
          to copy the Corresponding Source along with the object code.
          If the place to copy the object code is a network server, the
          Corresponding Source may be on a different server (operated by
          you or a third party) that supports equivalent copying
          facilities, provided you maintain clear directions next to the
          object code saying where to find the Corresponding Source.
          Regardless of what server hosts the Corresponding Source, you
          remain obligated to ensure that it is available for as long as
          needed to satisfy these requirements.

       e. Convey the object code using peer-to-peer transmission,
          provided you inform other peers where the object code and
          Corresponding Source of the work are being offered to the
          general public at no charge under subsection 6d.

     A separable portion of the object code, whose source code is
     excluded from the Corresponding Source as a System Library, need
     not be included in conveying the object code work.

     A “User Product” is either (1) a “consumer product”, which means
     any tangible personal property which is normally used for personal,
     family, or household purposes, or (2) anything designed or sold for
     incorporation into a dwelling.  In determining whether a product is
     a consumer product, doubtful cases shall be resolved in favor of
     coverage.  For a particular product received by a particular user,
     “normally used” refers to a typical or common use of that class of
     product, regardless of the status of the particular user or of the
     way in which the particular user actually uses, or expects or is
     expected to use, the product.  A product is a consumer product
     regardless of whether the product has substantial commercial,
     industrial or non-consumer uses, unless such uses represent the
     only significant mode of use of the product.

     “Installation Information” for a User Product means any methods,
     procedures, authorization keys, or other information required to
     install and execute modified versions of a covered work in that
     User Product from a modified version of its Corresponding Source.
     The information must suffice to ensure that the continued
     functioning of the modified object code is in no case prevented or
     interfered with solely because modification has been made.

     If you convey an object code work under this section in, or with,
     or specifically for use in, a User Product, and the conveying
     occurs as part of a transaction in which the right of possession
     and use of the User Product is transferred to the recipient in
     perpetuity or for a fixed term (regardless of how the transaction
     is characterized), the Corresponding Source conveyed under this
     section must be accompanied by the Installation Information.  But
     this requirement does not apply if neither you nor any third party
     retains the ability to install modified object code on the User
     Product (for example, the work has been installed in ROM).

     The requirement to provide Installation Information does not
     include a requirement to continue to provide support service,
     warranty, or updates for a work that has been modified or installed
     by the recipient, or for the User Product in which it has been
     modified or installed.  Access to a network may be denied when the
     modification itself materially and adversely affects the operation
     of the network or violates the rules and protocols for
     communication across the network.

     Corresponding Source conveyed, and Installation Information
     provided, in accord with this section must be in a format that is
     publicly documented (and with an implementation available to the
     public in source code form), and must require no special password
     or key for unpacking, reading or copying.

  7. Additional Terms.

     “Additional permissions” are terms that supplement the terms of
     this License by making exceptions from one or more of its
     conditions.  Additional permissions that are applicable to the
     entire Program shall be treated as though they were included in
     this License, to the extent that they are valid under applicable
     law.  If additional permissions apply only to part of the Program,
     that part may be used separately under those permissions, but the
     entire Program remains governed by this License without regard to
     the additional permissions.

     When you convey a copy of a covered work, you may at your option
     remove any additional permissions from that copy, or from any part
     of it.  (Additional permissions may be written to require their own
     removal in certain cases when you modify the work.)  You may place
     additional permissions on material, added by you to a covered work,
     for which you have or can give appropriate copyright permission.

     Notwithstanding any other provision of this License, for material
     you add to a covered work, you may (if authorized by the copyright
     holders of that material) supplement the terms of this License with
     terms:

       a. Disclaiming warranty or limiting liability differently from
          the terms of sections 15 and 16 of this License; or

       b. Requiring preservation of specified reasonable legal notices
          or author attributions in that material or in the Appropriate
          Legal Notices displayed by works containing it; or

       c. Prohibiting misrepresentation of the origin of that material,
          or requiring that modified versions of such material be marked
          in reasonable ways as different from the original version; or

       d. Limiting the use for publicity purposes of names of licensors
          or authors of the material; or

       e. Declining to grant rights under trademark law for use of some
          trade names, trademarks, or service marks; or

       f. Requiring indemnification of licensors and authors of that
          material by anyone who conveys the material (or modified
          versions of it) with contractual assumptions of liability to
          the recipient, for any liability that these contractual
          assumptions directly impose on those licensors and authors.

     All other non-permissive additional terms are considered “further
     restrictions” within the meaning of section 10.  If the Program as
     you received it, or any part of it, contains a notice stating that
     it is governed by this License along with a term that is a further
     restriction, you may remove that term.  If a license document
     contains a further restriction but permits relicensing or conveying
     under this License, you may add to a covered work material governed
     by the terms of that license document, provided that the further
     restriction does not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
     must place, in the relevant source files, a statement of the
     additional terms that apply to those files, or a notice indicating
     where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in
     the form of a separately written license, or stated as exceptions;
     the above requirements apply either way.

  8. Termination.

     You may not propagate or modify a covered work except as expressly
     provided under this License.  Any attempt otherwise to propagate or
     modify it is void, and will automatically terminate your rights
     under this License (including any patent licenses granted under the
     third paragraph of section 11).

     However, if you cease all violation of this License, then your
     license from a particular copyright holder is reinstated (a)
     provisionally, unless and until the copyright holder explicitly and
     finally terminates your license, and (b) permanently, if the
     copyright holder fails to notify you of the violation by some
     reasonable means prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
     reinstated permanently if the copyright holder notifies you of the
     violation by some reasonable means, this is the first time you have
     received notice of violation of this License (for any work) from
     that copyright holder, and you cure the violation prior to 30 days
     after your receipt of the notice.

     Termination of your rights under this section does not terminate
     the licenses of parties who have received copies or rights from you
     under this License.  If your rights have been terminated and not
     permanently reinstated, you do not qualify to receive new licenses
     for the same material under section 10.

  9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
     run a copy of the Program.  Ancillary propagation of a covered work
     occurring solely as a consequence of using peer-to-peer
     transmission to receive a copy likewise does not require
     acceptance.  However, nothing other than this License grants you
     permission to propagate or modify any covered work.  These actions
     infringe copyright if you do not accept this License.  Therefore,
     by modifying or propagating a covered work, you indicate your
     acceptance of this License to do so.

  10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
     receives a license from the original licensors, to run, modify and
     propagate that work, subject to this License.  You are not
     responsible for enforcing compliance by third parties with this
     License.

     An “entity transaction” is a transaction transferring control of an
     organization, or substantially all assets of one, or subdividing an
     organization, or merging organizations.  If propagation of a
     covered work results from an entity transaction, each party to that
     transaction who receives a copy of the work also receives whatever
     licenses to the work the party’s predecessor in interest had or
     could give under the previous paragraph, plus a right to possession
     of the Corresponding Source of the work from the predecessor in
     interest, if the predecessor has it or can get it with reasonable
     efforts.

     You may not impose any further restrictions on the exercise of the
     rights granted or affirmed under this License.  For example, you
     may not impose a license fee, royalty, or other charge for exercise
     of rights granted under this License, and you may not initiate
     litigation (including a cross-claim or counterclaim in a lawsuit)
     alleging that any patent claim is infringed by making, using,
     selling, offering for sale, or importing the Program or any portion
     of it.

  11. Patents.

     A “contributor” is a copyright holder who authorizes use under this
     License of the Program or a work on which the Program is based.
     The work thus licensed is called the contributor’s “contributor
     version”.

     A contributor’s “essential patent claims” are all patent claims
     owned or controlled by the contributor, whether already acquired or
     hereafter acquired, that would be infringed by some manner,
     permitted by this License, of making, using, or selling its
     contributor version, but do not include claims that would be
     infringed only as a consequence of further modification of the
     contributor version.  For purposes of this definition, “control”
     includes the right to grant patent sublicenses in a manner
     consistent with the requirements of this License.

     Each contributor grants you a non-exclusive, worldwide,
     royalty-free patent license under the contributor’s essential
     patent claims, to make, use, sell, offer for sale, import and
     otherwise run, modify and propagate the contents of its contributor
     version.

     In the following three paragraphs, a “patent license” is any
     express agreement or commitment, however denominated, not to
     enforce a patent (such as an express permission to practice a
     patent or covenant not to sue for patent infringement).  To “grant”
     such a patent license to a party means to make such an agreement or
     commitment not to enforce a patent against the party.

     If you convey a covered work, knowingly relying on a patent
     license, and the Corresponding Source of the work is not available
     for anyone to copy, free of charge and under the terms of this
     License, through a publicly available network server or other
     readily accessible means, then you must either (1) cause the
     Corresponding Source to be so available, or (2) arrange to deprive
     yourself of the benefit of the patent license for this particular
     work, or (3) arrange, in a manner consistent with the requirements
     of this License, to extend the patent license to downstream
     recipients.  “Knowingly relying” means you have actual knowledge
     that, but for the patent license, your conveying the covered work
     in a country, or your recipient’s use of the covered work in a
     country, would infringe one or more identifiable patents in that
     country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
     arrangement, you convey, or propagate by procuring conveyance of, a
     covered work, and grant a patent license to some of the parties
     receiving the covered work authorizing them to use, propagate,
     modify or convey a specific copy of the covered work, then the
     patent license you grant is automatically extended to all
     recipients of the covered work and works based on it.

     A patent license is “discriminatory” if it does not include within
     the scope of its coverage, prohibits the exercise of, or is
     conditioned on the non-exercise of one or more of the rights that
     are specifically granted under this License.  You may not convey a
     covered work if you are a party to an arrangement with a third
     party that is in the business of distributing software, under which
     you make payment to the third party based on the extent of your
     activity of conveying the work, and under which the third party
     grants, to any of the parties who would receive the covered work
     from you, a discriminatory patent license (a) in connection with
     copies of the covered work conveyed by you (or copies made from
     those copies), or (b) primarily for and in connection with specific
     products or compilations that contain the covered work, unless you
     entered into that arrangement, or that patent license was granted,
     prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
     any implied license or other defenses to infringement that may
     otherwise be available to you under applicable patent law.

  12. No Surrender of Others’ Freedom.

     If conditions are imposed on you (whether by court order, agreement
     or otherwise) that contradict the conditions of this License, they
     do not excuse you from the conditions of this License.  If you
     cannot convey a covered work so as to satisfy simultaneously your
     obligations under this License and any other pertinent obligations,
     then as a consequence you may not convey it at all.  For example,
     if you agree to terms that obligate you to collect a royalty for
     further conveying from those to whom you convey the Program, the
     only way you could satisfy both those terms and this License would
     be to refrain entirely from conveying the Program.

  13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
     permission to link or combine any covered work with a work licensed
     under version 3 of the GNU Affero General Public License into a
     single combined work, and to convey the resulting work.  The terms
     of this License will continue to apply to the part which is the
     covered work, but the special requirements of the GNU Affero
     General Public License, section 13, concerning interaction through
     a network will apply to the combination as such.

  14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new
     versions of the GNU General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies that a certain numbered version of the GNU
     General Public License “or any later version” applies to it, you
     have the option of following the terms and conditions either of
     that numbered version or of any later version published by the Free
     Software Foundation.  If the Program does not specify a version
     number of the GNU General Public License, you may choose any
     version ever published by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
     versions of the GNU General Public License can be used, that
     proxy’s public statement of acceptance of a version permanently
     authorizes you to choose that version for the Program.

     Later license versions may give you additional or different
     permissions.  However, no additional obligations are imposed on any
     author or copyright holder as a result of your choosing to follow a
     later version.

  15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
     APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE
     COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS”
     WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
     INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
     MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE
     RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
     SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
     NECESSARY SERVICING, REPAIR OR CORRECTION.

  16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
     AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
     DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
     CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
     THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
     BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
     PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
     PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
     THE POSSIBILITY OF SUCH DAMAGES.

  17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
     above cannot be given local legal effect according to their terms,
     reviewing courts shall apply local law that most closely
     approximates an absolute waiver of all civil liability in
     connection with the Program, unless a warranty or assumption of
     liability accompanies a copy of the Program in return for a fee.

END OF TERMS AND CONDITIONS
===========================

How to Apply These Terms to Your New Programs
=============================================

If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least the
“copyright” line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
     Copyright (C) YEAR NAME OF AUTHOR

     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation, either version 3 of the License, or (at
     your option) any later version.

     This program is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program.  If not, see <https://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper
mail.

   If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:

     PROGRAM Copyright (C) YEAR NAME OF AUTHOR
     This program comes with ABSOLUTELY NO WARRANTY; for details type ‘show w’.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type ‘show c’ for details.

   The hypothetical commands ‘show w’ and ‘show c’ should show the
appropriate parts of the General Public License.  Of course, your
program’s commands might be different; for a GUI interface, you would
use an “about box”.

   You should also get your employer (if you work as a programmer) or
school, if any, to sign a “copyright disclaimer” for the program, if
necessary.  For more information on this, and how to apply and follow
the GNU GPL, see <https://www.gnu.org/licenses/>.

   The GNU General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Lesser General Public License instead of this License.  But first,
please read <https://www.gnu.org/licenses/why-not-lgpl.html>.


File: octave.info,  Node: Concept Index,  Next: Function Index,  Prev: Copying,  Up: Top

Concept Index
*************

[index]
* Menu:

* acknowledgements:                      Acknowledgements.    (line   6)
* addition:                              Arithmetic Ops.      (line   6)
* addition <1>:                          Operator Overloading.
                                                              (line   6)
* and operator:                          Boolean Expressions. (line   6)
* and operator <1>:                      Operator Overloading.
                                                              (line   6)
* anonymous functions:                   Function Handles and Anonymous Functions.
                                                              (line   6)
* ans:                                   Variables.           (line  44)
* answers, incorrect:                    Bug Criteria.        (line  12)
* answers, incorrect <1>:                Bug Reporting.       (line  70)
* application-defined data:              Application-defined Data.
                                                              (line   6)
* apply:                                 Function Application.
                                                              (line   6)
* area series:                           Area Series.         (line   6)
* arguments in function call:            Calling Functions.   (line  15)
* arithmetic operators:                  Arithmetic Ops.      (line   6)
* arithmetic operators <1>:              Operator Overloading.
                                                              (line   6)
* array, creating a Java array:          Java Interface Functions.
                                                              (line  24)
* assignment expressions:                Assignment Ops.      (line   6)
* assignment operators:                  Assignment Ops.      (line   6)
* axes graphics object:                  Graphics Objects.    (line  20)
* bar series:                            Bar Series.          (line   6)
* batch processing:                      Executable Octave Programs.
                                                              (line   6)
* block comments:                        Block Comments.      (line   6)
* body of a loop:                        The while Statement. (line   6)
* boolean expressions:                   Boolean Expressions. (line   6)
* boolean expressions <1>:               Operator Overloading.
                                                              (line   6)
* boolean operators:                     Boolean Expressions. (line   6)
* boolean operators <1>:                 Operator Overloading.
                                                              (line   6)
* break statement:                       The break Statement. (line   6)
* broadcast:                             Broadcasting.        (line   6)
* broadcasting:                          Broadcasting.        (line   6)
* BSX:                                   Broadcasting.        (line   6)
* bug criteria:                          Bug Criteria.        (line   6)
* bug tracker:                           Bug Tracker.         (line   6)
* bugs:                                  Reporting Bugs.      (line   6)
* bugs, investigating:                   Bug Reporting.       (line 102)
* bugs, known:                           Trouble.             (line   6)
* bugs, reporting:                       Bug Tracker.         (line   6)
* bugs, reporting <1>:                   Bug Reporting.       (line   6)
* built-in data types:                   Built-in Data Types. (line   6)
* callbacks:                             Callbacks.           (line   6)
* calling Java from Octave:              Java Interface.      (line   6)
* calling Octave from Java:              Java Interface.      (line   6)
* case statement:                        The switch Statement.
                                                              (line   6)
* catch:                                 The try Statement.   (line   6)
* cell arrays:                           Cell Array Objects.  (line   6)
* cell arrays <1>:                       Cell Arrays.         (line   6)
* character strings:                     String Objects.      (line   6)
* character strings <1>:                 Strings.             (line   6)
* Cholesky factorization:                Matrix Factorizations.
                                                              (line  12)
* Citations:                             Citing Octave in Publications.
                                                              (line   6)
* Citing Octave:                         Citing Octave in Publications.
                                                              (line   6)
* classes, making available to Octave:   Making Java Classes Available.
                                                              (line   6)
* classpath, adding new path:            Java Interface Functions.
                                                              (line 201)
* classpath, difference between static and dynamic: Making Java Classes Available.
                                                              (line   6)
* classpath, displaying:                 Java Interface Functions.
                                                              (line 167)
* classpath, dynamic:                    Java Interface Functions.
                                                              (line 167)
* classpath, dynamic <1>:                Java Interface Functions.
                                                              (line 201)
* classpath, removing path:              Java Interface Functions.
                                                              (line 219)
* classpath, setting:                    Making Java Classes Available.
                                                              (line   6)
* classpath, static:                     Java Interface Functions.
                                                              (line 167)
* classpath.txt:                         Making Java Classes Available.
                                                              (line   6)
* clearing the screen:                   Cursor Motion.       (line  56)
* code profiling:                        Profiling.           (line   6)
* colors, graphics:                      Colors.              (line   6)
* comma-separated lists:                 Comma-Separated Lists.
                                                              (line   6)
* command and output logs:               Diary and Echo Commands.
                                                              (line   6)
* command completion:                    Commands for Completion.
                                                              (line   6)
* command descriptions:                  A Sample Command Description.
                                                              (line   6)
* command echoing:                       Diary and Echo Commands.
                                                              (line   6)
* command history:                       Commands for History.
                                                              (line   6)
* command options:                       Command Line Options.
                                                              (line   6)
* command-line editing:                  Command Line Editing.
                                                              (line   6)
* commands functions:                    Command Syntax and Function Syntax.
                                                              (line   6)
* comments:                              Comments.            (line   6)
* comparison expressions:                Comparison Ops.      (line   6)
* comparison expressions <1>:            Operator Overloading.
                                                              (line   6)
* complex-conjugate transpose:           Arithmetic Ops.      (line   6)
* complex-conjugate transpose <1>:       Operator Overloading.
                                                              (line   6)
* containers:                            Data Containers.     (line   6)
* continuation lines:                    Continuation Lines.  (line   6)
* continue statement:                    The continue Statement.
                                                              (line   6)
* contour series:                        Contour Groups.      (line   6)
* contributing to Octave:                How You Can Contribute to Octave.
                                                              (line   6)
* contributors:                          Preface.             (line   6)
* conversion specifications (printf):    Formatted Output.    (line  82)
* conversion specifications (scanf):     Formatted Input.     (line  92)
* copy-on-write:                         Miscellaneous Techniques.
                                                              (line  16)
* copyright:                             Copying.             (line   6)
* core dump:                             Bug Criteria.        (line   9)
* COW:                                   Miscellaneous Techniques.
                                                              (line  16)
* creating graphics objects:             Graphics Objects.    (line  44)
* cs-lists:                              Comma-Separated Lists.
                                                              (line   6)
* customizing readline:                  Customizing readline.
                                                              (line   6)
* customizing the prompt:                Customizing the Prompt.
                                                              (line   6)
* DAE:                                   Differential Equations.
                                                              (line  14)
* data sources in object groups:         Data Sources in Object Groups.
                                                              (line   6)
* data structures:                       Data Structure Objects.
                                                              (line   6)
* data structures <1>:                   Structures.          (line   6)
* data types:                            Data Types.          (line   6)
* data types, built-in:                  Built-in Data Types. (line   6)
* data types, user-defined:              User-defined Data Types.
                                                              (line   6)
* decrement operator:                    Assignment Ops.      (line 170)
* default arguments:                     Default Arguments.   (line   6)
* default graphics properties:           Managing Default Properties.
                                                              (line   6)
* defining functions:                    Functions and Scripts.
                                                              (line   6)
* Degree Symbol:                         "tex" interpreter.   (line 104)
* deprecated functions:                  Obsolete Functions.  (line   6)
* description format:                    Format of Descriptions.
                                                              (line   6)
* diagonal and permutation matrices:     Diagonal and Permutation Matrices.
                                                              (line   6)
* diagonal matrix expressions:           Expressions Involving Diagonal Matrices.
                                                              (line   6)
* dialog, displaying a dialog for selecting directories: I/O Dialogs.
                                                              (line  10)
* dialog, displaying a dialog for selecting files: I/O Dialogs.
                                                              (line  26)
* dialog, displaying a dialog for storing files: I/O Dialogs. (line  85)
* dialog, displaying a font selection dialog: I/O Dialogs.    (line 444)
* dialog, displaying a help dialog:      I/O Dialogs.         (line 159)
* dialog, displaying a list dialog:      I/O Dialogs.         (line 240)
* dialog, displaying a message dialog:   I/O Dialogs.         (line 305)
* dialog, displaying a modal dialog:     I/O Dialogs.         (line 476)
* dialog, displaying a question dialog:  I/O Dialogs.         (line 372)
* dialog, displaying a warning dialog:   I/O Dialogs.         (line 412)
* dialog, displaying an error dialog:    I/O Dialogs.         (line 127)
* dialog, displaying an input dialog:    I/O Dialogs.         (line 186)
* diary of commands and output:          Diary and Echo Commands.
                                                              (line   6)
* differential equations:                Differential Equations.
                                                              (line  15)
* diffs, submitting:                     Sending Patches.     (line   6)
* distribution of Octave:                Distribution.        (line   6)
* division:                              Arithmetic Ops.      (line   6)
* division <1>:                          Operator Overloading.
                                                              (line   6)
* do-until statement:                    The do-until Statement.
                                                              (line   6)
* documentation fonts:                   Fonts.               (line   6)
* documentation notation:                Evaluation Notation. (line   6)
* documenting functions:                 Comments and the Help System.
                                                              (line   6)
* documenting Octave programs:           Comments.            (line   6)
* documenting user scripts:              Comments and the Help System.
                                                              (line   6)
* Dulmage-Mendelsohn decomposition:      Mathematical Considerations.
                                                              (line 369)
* dynamic classpath:                     Making Java Classes Available.
                                                              (line   6)
* dynamic classpath <1>:                 Java Interface Functions.
                                                              (line 167)
* dynamic classpath, adding new path:    Java Interface Functions.
                                                              (line 201)
* dynamic naming:                        Creating Structures. (line   6)
* dynamic-linking:                       External Code Interface.
                                                              (line   6)
* Dynamically Linked Functions:          External Code Interface.
                                                              (line   6)
* echoing executing commands:            Diary and Echo Commands.
                                                              (line   6)
* editing the command line:              Command Line Editing.
                                                              (line   6)
* element-by-element evaluation:         Element-by-element Boolean Operators.
                                                              (line   6)
* else statement:                        The if Statement.    (line   6)
* elseif statement:                      The if Statement.    (line   6)
* end statement:                         Statements.          (line  16)
* end, indexing:                         Index Expressions.   (line 128)
* end: and :end:                         Index Expressions.   (line 128)
* endfor statement:                      The for Statement.   (line   6)
* endfunction statement:                 Defining Functions.  (line   6)
* endif statement:                       The if Statement.    (line   6)
* endswitch statement:                   The switch Statement.
                                                              (line   6)
* endwhile statement:                    The while Statement. (line   6)
* end_try_catch:                         The try Statement.   (line   6)
* end_unwind_protect:                    The unwind_protect Statement.
                                                              (line   6)
* equality operator:                     Comparison Ops.      (line   6)
* equality operator <1>:                 Operator Overloading.
                                                              (line   6)
* equality, tests for:                   Comparison Ops.      (line   6)
* equality, tests for <1>:               Operator Overloading.
                                                              (line   6)
* equations, nonlinear:                  Nonlinear Equations. (line   6)
* erroneous messages:                    Bug Criteria.        (line  21)
* erroneous results:                     Bug Criteria.        (line  12)
* erroneous results <1>:                 Bug Reporting.       (line  70)
* error bar series:                      Error Bar Series.    (line   6)
* error ids:                             Catching Errors.     (line 127)
* error message notation:                Error Messages.      (line   6)
* error messages:                        Errors.              (line   6)
* error messages, incorrect:             Bug Criteria.        (line  21)
* escape sequence notation:              Escape Sequences in String Constants.
                                                              (line   6)
* evaluation notation:                   Evaluation Notation. (line   6)
* executable scripts:                    Executable Octave Programs.
                                                              (line   6)
* execution speed:                       Miscellaneous Techniques.
                                                              (line   6)
* exiting octave:                        Running Octave.      (line  20)
* exiting octave <1>:                    Quitting Octave.     (line   6)
* exponentiation:                        Arithmetic Ops.      (line   6)
* exponentiation <1>:                    Operator Overloading.
                                                              (line   6)
* expression, range:                     Ranges.              (line   6)
* expressions:                           Expressions.         (line   6)
* expressions, assignment:               Assignment Ops.      (line   6)
* expressions, boolean:                  Boolean Expressions. (line   6)
* expressions, boolean <1>:              Operator Overloading.
                                                              (line   6)
* expressions, comparison:               Comparison Ops.      (line   6)
* expressions, comparison <1>:           Operator Overloading.
                                                              (line   6)
* expressions, logical:                  Boolean Expressions. (line   6)
* expressions, logical <1>:              Operator Overloading.
                                                              (line   6)
* factorial function:                    Recursion.           (line   6)
* fatal signal:                          Bug Criteria.        (line   9)
* field, returning value of Java object field: Java Interface Functions.
                                                              (line  76)
* field, setting value of Java object field: Java Interface Functions.
                                                              (line 104)
* fields, displaying available fields of a Java object: Java Interface Functions.
                                                              (line  57)
* figure deletefcn:                      Access via Handle.   (line  18)
* figure graphics object:                Graphics Objects.    (line  17)
* finding minimums:                      Minimizers.          (line   6)
* finish.m:                              Quitting Octave.     (line   6)
* flag character (printf):               Output Conversion Syntax.
                                                              (line  28)
* flag character (scanf):                Input Conversion Syntax.
                                                              (line  34)
* for statement:                         The for Statement.   (line   6)
* Frobenius norm:                        Basic Matrix Functions.
                                                              (line 434)
* function application:                  Function Application.
                                                              (line   6)
* function descriptions:                 A Sample Function Description.
                                                              (line   6)
* function file:                         Function Files.      (line   6)
* function handle:                       Access via Handle.   (line   6)
* function statement:                    Defining Functions.  (line   6)
* functions, deprecated:                 Obsolete Functions.  (line   6)
* functions, obsolete:                   Obsolete Functions.  (line   6)
* functions, user-defined:               Functions and Scripts.
                                                              (line   6)
* funding Octave development:            How You Can Contribute to Octave.
                                                              (line   6)
* general p-norm:                        Basic Matrix Functions.
                                                              (line 437)
* global statement:                      Global Variables.    (line   6)
* global variables:                      Global Variables.    (line   6)
* GNUTERM:                               Customizing Toolkit Behavior.
                                                              (line  22)
* grammar rules:                         Grammar and Parser.  (line   6)
* graphics:                              Plotting.            (line   6)
* graphics colors:                       Colors.              (line   6)
* graphics data structures:              Graphics Data Structures.
                                                              (line   6)
* graphics line styles:                  Line Styles.         (line   6)
* graphics marker styles:                Marker Styles.       (line   6)
* graphics object properties:            Graphics Object Properties.
                                                              (line   6)
* graphics object, axes:                 Graphics Objects.    (line  20)
* graphics object, figure:               Graphics Objects.    (line  17)
* graphics object, image:                Graphics Objects.    (line  30)
* graphics object, light:                Graphics Objects.    (line  39)
* graphics object, line:                 Graphics Objects.    (line  24)
* graphics object, patch:                Graphics Objects.    (line  33)
* graphics object, root:                 Graphics Objects.    (line  12)
* graphics object, surface:              Graphics Objects.    (line  36)
* graphics object, text:                 Graphics Objects.    (line  27)
* graphics objects:                      Graphics Objects.    (line   6)
* graphics objects, saving:              Graphics Objects.    (line 616)
* graphics properties, default:          Managing Default Properties.
                                                              (line   6)
* graphics toolkits:                     Graphics Toolkits.   (line   6)
* greater than operator:                 Comparison Ops.      (line   6)
* greater than operator <1>:             Operator Overloading.
                                                              (line   6)
* group objects:                         Quiver Group.        (line   6)
* group objects <1>:                     Stair Group.         (line   6)
* group objects <2>:                     Surface Group.       (line   6)
* handle functions:                      Graphics Objects.    (line 271)
* handle, function handles:              Function Handles and Anonymous Functions.
                                                              (line   6)
* hash table:                            containers.Map.      (line   6)
* help, online:                          Getting Help.        (line   6)
* help, user-defined functions:          Comments and the Help System.
                                                              (line   6)
* help, where to find:                   How To Get Help with Octave.
                                                              (line   6)
* Hermitian operator:                    Arithmetic Ops.      (line   6)
* Hermitian operator <1>:                Operator Overloading.
                                                              (line   6)
* Hessenberg decomposition:              Matrix Factorizations.
                                                              (line 157)
* history:                               Preface.             (line   6)
* history of commands:                   Commands for History.
                                                              (line   6)
* if statement:                          The if Statement.    (line   6)
* image graphics object:                 Graphics Objects.    (line  30)
* improving Octave:                      Bug Criteria.        (line  28)
* improving Octave <1>:                  Sending Patches.     (line   6)
* incorrect error messages:              Bug Criteria.        (line  21)
* incorrect output:                      Bug Criteria.        (line  12)
* incorrect output <1>:                  Bug Reporting.       (line  70)
* incorrect results:                     Bug Criteria.        (line  12)
* incorrect results <1>:                 Bug Reporting.       (line  70)
* increment operator:                    Assignment Ops.      (line 170)
* indirect function call:                Access via Handle.   (line   6)
* infinity norm:                         Basic Matrix Functions.
                                                              (line 430)
* initialization:                        Startup Files.       (line   6)
* input conversions, for scanf:          Table of Input Conversions.
                                                              (line   6)
* input history:                         Commands for History.
                                                              (line   6)
* ~/.inputrc:                            Customizing readline.
                                                              (line   6)
* installation trouble:                  Trouble.             (line   6)
* installing Octave:                     Installation.        (line   6)
* instance, creating a Java instance:    Java Interface Functions.
                                                              (line  10)
* introduction:                          Introduction.        (line   6)
* introduction to graphics structures:   Introduction to Graphics Structures.
                                                              (line   6)
* invalid input:                         Bug Criteria.        (line  23)
* Java, calling from Octave:             Java Interface.      (line   6)
* Java, using with Octave:               Java Interface.      (line   6)
* javaclasspath.txt:                     Making Java Classes Available.
                                                              (line   6)
* Jupyter Notebooks:                     Jupyter Notebooks.   (line   6)
* Kendall’s Tau:                         Correlation and Regression Analysis.
                                                              (line 118)
* key/value store:                       containers.Map.      (line   6)
* keywords:                              Keywords.            (line   6)
* known causes of trouble:               Trouble.             (line   6)
* language definition:                   Grammar and Parser.  (line   6)
* less than operator:                    Comparison Ops.      (line   6)
* less than operator <1>:                Operator Overloading.
                                                              (line   6)
* light graphics object:                 Graphics Objects.    (line  39)
* line graphics object:                  Graphics Objects.    (line  24)
* line series:                           Line Series.         (line   6)
* line styles, graphics:                 Line Styles.         (line   6)
* linear algebra:                        Linear Algebra.      (line   6)
* linear algebra, techniques:            Techniques Used for Linear Algebra.
                                                              (line   6)
* loading data:                          Simple File I/O.     (line   6)
* local minimum:                         Minimizers.          (line   6)
* logging commands and output:           Diary and Echo Commands.
                                                              (line   6)
* logical expressions:                   Boolean Expressions. (line   6)
* logical expressions <1>:               Operator Overloading.
                                                              (line   6)
* logical operators:                     Boolean Expressions. (line   6)
* logical operators <1>:                 Operator Overloading.
                                                              (line   6)
* loop:                                  The while Statement. (line   6)
* looping over structure elements:       Looping Over Structure Elements.
                                                              (line   6)
* LP:                                    Optimization.        (line  18)
* LU decomposition:                      Matrix Factorizations.
                                                              (line 180)
* lvalue:                                Assignment Ops.      (line  33)
* Map:                                   containers.Map.      (line   6)
* map:                                   Function Application.
                                                              (line   6)
* marker styles, graphics:               Marker Styles.       (line   6)
* matching failure, in scanf:            Formatted Input.     (line 115)
* matrices:                              Matrices.            (line   6)
* matrices, diagonal and permutation:    Diagonal and Permutation Matrices.
                                                              (line   6)
* matrix factorizations:                 Matrix Factorizations.
                                                              (line   6)
* matrix functions, basic:               Basic Matrix Functions.
                                                              (line   6)
* matrix multiplication:                 Arithmetic Ops.      (line   6)
* matrix multiplication <1>:             Operator Overloading.
                                                              (line   6)
* matrix, functions of:                  Functions of a Matrix.
                                                              (line   6)
* matrix, permutation functions:         Permutation Matrix Functions.
                                                              (line   6)
* matrix, specialized solvers:           Specialized Solvers. (line   6)
* matrix, zero elements:                 Zeros Treatment.     (line   6)
* maximum field width (scanf):           Input Conversion Syntax.
                                                              (line  42)
* memory management:                     Miscellaneous Techniques.
                                                              (line  16)
* memory, displaying Java memory status: Java Interface Functions.
                                                              (line 301)
* memory, limitations on JVM:            Set up the JVM.      (line   6)
* messages, error:                       Errors.              (line   6)
* method, invoking a method of a Java object: Java Interface Functions.
                                                              (line 142)
* methods, displaying available methods of a Java object: Java Interface Functions.
                                                              (line 120)
* mex:                                   Mex-Files.           (line   6)
* mex-files:                             Mex-Files.           (line   6)
* minimum field width (printf):          Output Conversion Syntax.
                                                              (line  35)
* missing data:                          Missing Data.        (line   6)
* mkoctfile:                             Oct-Files.           (line   6)
* multi-line comments:                   Block Comments.      (line   6)
* multiplication:                        Arithmetic Ops.      (line   6)
* multiplication <1>:                    Operator Overloading.
                                                              (line   6)
* negation:                              Arithmetic Ops.      (line   6)
* negation <1>:                          Operator Overloading.
                                                              (line   6)
* NLP:                                   Optimization.        (line  17)
* nonlinear equations:                   Nonlinear Equations. (line   6)
* nonlinear programming:                 Optimization.        (line  18)
* not operator:                          Boolean Expressions. (line   6)
* not operator <1>:                      Operator Overloading.
                                                              (line   6)
* numeric constant:                      Numeric Objects.     (line   6)
* numeric constant <1>:                  Numeric Data Types.  (line   6)
* numeric value:                         Numeric Objects.     (line   6)
* numeric value <1>:                     Numeric Data Types.  (line   6)
* object groups:                         Object Groups.       (line   6)
* object, creating a Java object:        Java Interface Functions.
                                                              (line  10)
* obsolete functions:                    Obsolete Functions.  (line   6)
* oct:                                   Oct-Files.           (line   6)
* oct-files:                             Oct-Files.           (line   6)
* Octave and MATLAB, how to distinguish between: How to Distinguish Between Octave and Matlab.
                                                              (line   6)
* Octave API:                            External Code Interface.
                                                              (line   6)
* Octave command options:                Command Line Options.
                                                              (line   6)
* Octave, calling from Java:             Java Interface.      (line   6)
* .octaverc:                             Command Line Options.
                                                              (line  88)
* .octaverc <1>:                         Startup Files.       (line  40)
* ~/.octaverc:                           Command Line Options.
                                                              (line  88)
* ~/.octaverc <1>:                       Startup Files.       (line  36)
* ODE:                                   Differential Equations.
                                                              (line  15)
* online help:                           Getting Help.        (line   6)
* opengl rendering slow windows:         Hardware vs Software Rendering.
                                                              (line   6)
* opengl single precision date time:     Precision issues.    (line   6)
* operator precedence:                   Operator Precedence. (line   6)
* operators, arithmetic:                 Arithmetic Ops.      (line   6)
* operators, arithmetic <1>:             Operator Overloading.
                                                              (line   6)
* operators, assignment:                 Assignment Ops.      (line   6)
* operators, boolean:                    Boolean Expressions. (line   6)
* operators, boolean <1>:                Operator Overloading.
                                                              (line   6)
* operators, decrement:                  Assignment Ops.      (line 169)
* operators, increment:                  Assignment Ops.      (line 170)
* operators, logical:                    Boolean Expressions. (line   6)
* operators, logical <1>:                Operator Overloading.
                                                              (line   6)
* operators, relational:                 Comparison Ops.      (line   6)
* operators, relational <1>:             Operator Overloading.
                                                              (line   6)
* optimization:                          Miscellaneous Techniques.
                                                              (line   6)
* optimization <1>:                      Optimization.        (line  18)
* options, Octave command:               Command Line Options.
                                                              (line   6)
*   --braindead:                         Command Line Options.
                                                              (line 134)
*   --built-in-docstrings-file FILENAME: Command Line Options.
                                                              (line   9)
*   --debug:                             Command Line Options.
                                                              (line  15)
*   --doc-cache-file FILENAME:           Command Line Options.
                                                              (line  21)
*   --echo-commands:                     Command Line Options.
                                                              (line  29)
*   --eval CODE:                         Command Line Options.
                                                              (line  32)
*   --exec-path PATH:                    Command Line Options.
                                                              (line  36)
*   --gui:                               Command Line Options.
                                                              (line  43)
*   --help:                              Command Line Options.
                                                              (line  47)
*   --image-path PATH:                   Command Line Options.
                                                              (line  50)
*   --info-file FILENAME:                Command Line Options.
                                                              (line  57)
*   --info-program PROGRAM:              Command Line Options.
                                                              (line  64)
*   --interactive:                       Command Line Options.
                                                              (line  72)
*   --line-editing:                      Command Line Options.
                                                              (line  76)
*   --no-gui:                            Command Line Options.
                                                              (line  79)
*   --no-history:                        Command Line Options.
                                                              (line  85)
*   --no-init-file:                      Command Line Options.
                                                              (line  88)
*   --no-init-path:                      Command Line Options.
                                                              (line  91)
*   --no-line-editing:                   Command Line Options.
                                                              (line  95)
*   --no-site-file:                      Command Line Options.
                                                              (line  98)
*   --no-window-system:                  Command Line Options.
                                                              (line 102)
*   --norc:                              Command Line Options.
                                                              (line 107)
*   --path PATH:                         Command Line Options.
                                                              (line 113)
*   --persist:                           Command Line Options.
                                                              (line 120)
*   --quiet:                             Command Line Options.
                                                              (line 126)
*   --silent:                            Command Line Options.
                                                              (line 126)
*   --texi-macros-file FILENAME:         Command Line Options.
                                                              (line 129)
*   --traditional:                       Command Line Options.
                                                              (line 134)
*   --verbose:                           Command Line Options.
                                                              (line 168)
*   --version:                           Command Line Options.
                                                              (line 172)
*   -d:                                  Command Line Options.
                                                              (line  15)
*   -f:                                  Command Line Options.
                                                              (line 107)
*   -h:                                  Command Line Options.
                                                              (line  47)
*   -H:                                  Command Line Options.
                                                              (line  85)
*   -i:                                  Command Line Options.
                                                              (line  72)
*   -p PATH:                             Command Line Options.
                                                              (line 113)
*   -q:                                  Command Line Options.
                                                              (line 126)
*   -V:                                  Command Line Options.
                                                              (line 168)
*   -v:                                  Command Line Options.
                                                              (line 172)
*   -W:                                  Command Line Options.
                                                              (line 102)
*   -x:                                  Command Line Options.
                                                              (line  29)
* or operator:                           Boolean Expressions. (line   6)
* or operator <1>:                       Operator Overloading.
                                                              (line   6)
* oregonator:                            Ordinary Differential Equations.
                                                              (line 201)
* otherwise statement:                   The switch Statement.
                                                              (line   6)
* output conversions, for printf:        Table of Output Conversions.
                                                              (line   6)
* parser:                                Parser.              (line   6)
* patch graphics object:                 Graphics Objects.    (line  33)
* patches, submitting:                   Sending Patches.     (line   6)
* path, adding to classpath:             Java Interface Functions.
                                                              (line 201)
* path, removing from classpath:         Java Interface Functions.
                                                              (line 219)
* permutation matrix functions:          Permutation Matrix Functions.
                                                              (line   6)
* persistent statement:                  Persistent Variables.
                                                              (line   6)
* persistent variables:                  Persistent Variables.
                                                              (line   6)
* personal startup file:                 Startup Files.       (line  31)
* personal startup file <1>:             Startup Files.       (line  36)
* PKG_ADD:                               Creating Packages.   (line  45)
* PKG_DEL:                               Creating Packages.   (line  63)
* plotting:                              Plotting.            (line   6)
* plotting, high-level:                  High-Level Plotting. (line   6)
* plotting, multiple plot windows:       Multiple Plot Windows.
                                                              (line   6)
* plotting, multiple plots per figure:   Multiple Plots on One Page.
                                                              (line   6)
* plotting, object manipulation:         Manipulation of Plot Objects.
                                                              (line   6)
* plotting, saving and printing plots:   Printing and Saving Plots.
                                                              (line   6)
* plotting, three-dimensional:           Three-Dimensional Plots.
                                                              (line   6)
* plotting, two-dimensional functions:   Two-dimensional Function Plotting.
                                                              (line   6)
* plotting, window manipulation:         Manipulation of Plot Windows.
                                                              (line   6)
* precision (printf):                    Output Conversion Syntax.
                                                              (line  47)
* printing notation:                     Printing Notation.   (line   6)
* printing plots:                        Printing and Saving Plots.
                                                              (line   6)
* profiler:                              Profiling.           (line   6)
* program, self contained:               Executable Octave Programs.
                                                              (line   6)
* Progress Bar:                          Progress Bar.        (line   6)
* project startup file:                  Startup Files.       (line  40)
* prompt customization:                  Customizing the Prompt.
                                                              (line   6)
* pseudoinverse:                         Basic Matrix Functions.
                                                              (line 515)
* pseudoinverse <1>:                     Expressions Involving Diagonal Matrices.
                                                              (line  27)
* QP:                                    Optimization.        (line  18)
* QR factorization:                      Matrix Factorizations.
                                                              (line 290)
* quadratic programming:                 Optimization.        (line  18)
* quitting octave:                       Running Octave.      (line  20)
* quitting octave <1>:                   Quitting Octave.     (line   6)
* quiver group:                          Quiver Group.        (line   6)
* quotient:                              Arithmetic Ops.      (line   6)
* quotient <1>:                          Operator Overloading.
                                                              (line   6)
* range expressions:                     Ranges.              (line   6)
* readline customization:                Customizing readline.
                                                              (line   6)
* recycling:                             Broadcasting.        (line   6)
* relational operators:                  Comparison Ops.      (line   6)
* relational operators <1>:              Operator Overloading.
                                                              (line   6)
* reporting bugs:                        Reporting Bugs.      (line   6)
* reporting bugs <1>:                    Bug Tracker.         (line   6)
* results, incorrect:                    Bug Criteria.        (line  12)
* results, incorrect <1>:                Bug Reporting.       (line  70)
* root graphics object:                  Graphics Objects.    (line  12)
* saving data:                           Simple File I/O.     (line   6)
* saving graphics objects:               Graphics Objects.    (line 616)
* saving plots:                          Printing and Saving Plots.
                                                              (line   6)
* Schur decomposition:                   Matrix Factorizations.
                                                              (line 612)
* script files:                          Functions and Scripts.
                                                              (line   6)
* scripts:                               Executable Octave Programs.
                                                              (line   6)
* select JVM version:                    Set up the JVM.      (line   6)
* self contained programs:               Executable Octave Programs.
                                                              (line   6)
* series objects:                        Area Series.         (line   6)
* series objects <1>:                    Bar Series.          (line   6)
* series objects <2>:                    Contour Groups.      (line   6)
* series objects <3>:                    Error Bar Series.    (line   6)
* series objects <4>:                    Line Series.         (line   6)
* series objects <5>:                    Stem Series.         (line   6)
* short-circuit evaluation:              Short-circuit Boolean Operators.
                                                              (line   6)
* side effect:                           Assignment Ops.      (line  26)
* SIMD:                                  Broadcasting.        (line   6)
* singular value decomposition:          Matrix Factorizations.
                                                              (line 774)
* site exiting file:                     Quitting Octave.     (line   6)
* site startup file:                     Command Line Options.
                                                              (line  98)
* site startup file <1>:                 Startup Files.       (line  11)
* Spearman’s Rho:                        Correlation and Regression Analysis.
                                                              (line 103)
* speedups:                              Miscellaneous Techniques.
                                                              (line   6)
* stair group:                           Stair Group.         (line   6)
* startup:                               Startup Files.       (line   6)
* startup files:                         Startup Files.       (line  10)
* startup.m:                             Startup Files.       (line  50)
* statements:                            Statements.          (line   6)
* static classpath:                      Making Java Classes Available.
                                                              (line   6)
* static classpath <1>:                  Java Interface Functions.
                                                              (line 167)
* stem series:                           Stem Series.         (line   6)
* strings:                               String Objects.      (line   6)
* strings <1>:                           Strings.             (line   6)
* structural rank:                       Sparse Linear Algebra.
                                                              (line 312)
* structure elements, looping over:      Looping Over Structure Elements.
                                                              (line   6)
* structures:                            Data Structure Objects.
                                                              (line   6)
* structures <1>:                        Structures.          (line   6)
* submitting diffs:                      Sending Patches.     (line   6)
* submitting patches:                    Sending Patches.     (line   6)
* subtraction:                           Arithmetic Ops.      (line   6)
* subtraction <1>:                       Operator Overloading.
                                                              (line   6)
* suggestions:                           Bug Criteria.        (line  28)
* surface graphics object:               Graphics Objects.    (line  36)
* surface group:                         Surface Group.       (line   6)
* switch statement:                      The switch Statement.
                                                              (line   6)
* test functions:                        Test and Demo Functions.
                                                              (line   6)
* tests for equality:                    Comparison Ops.      (line   6)
* tests for equality <1>:                Operator Overloading.
                                                              (line   6)
* text graphics object:                  Graphics Objects.    (line  27)
* toolkit customization:                 Customizing Toolkit Behavior.
                                                              (line   6)
* toolkits, graphics:                    Graphics Toolkits.   (line   6)
* transform groups:                      Transform Groups.    (line   6)
* transpose:                             Arithmetic Ops.      (line   6)
* transpose <1>:                         Operator Overloading.
                                                              (line   6)
* transpose, complex-conjugate:          Arithmetic Ops.      (line   6)
* transpose, complex-conjugate <1>:      Operator Overloading.
                                                              (line   6)
* troubleshooting:                       Trouble.             (line   6)
* try statement:                         The try Statement.   (line   6)
* uitable properties:                    Uitable Properties.  (line   6)
* unary minus:                           Arithmetic Ops.      (line   6)
* unary minus <1>:                       Operator Overloading.
                                                              (line   6)
* undefined behavior:                    Bug Criteria.        (line  15)
* undefined function value:              Bug Criteria.        (line  15)
* unwind_protect statement:              The unwind_protect Statement.
                                                              (line   6)
* unwind_protect_cleanup:                The unwind_protect Statement.
                                                              (line   6)
* use of comments:                       Comments.            (line   6)
* user-defined data types:               User-defined Data Types.
                                                              (line   6)
* user-defined functions:                Functions and Scripts.
                                                              (line   6)
* user-defined variables:                Variables.           (line   6)
* using Octave with Java:                Java Interface.      (line   6)
* validating arguments:                  Validating Arguments.
                                                              (line   6)
* varargin:                              Variable-length Argument Lists.
                                                              (line   6)
* varargout:                             Variable-length Return Lists.
                                                              (line   6)
* variable-length argument lists:        Variable-length Argument Lists.
                                                              (line   6)
* variable-length return lists:          Variable-length Return Lists.
                                                              (line   6)
* variables, global:                     Global Variables.    (line   6)
* variables, persistent:                 Persistent Variables.
                                                              (line   6)
* variables, user-defined:               Variables.           (line   6)
* vectorization:                         Vectorization and Faster Code Execution.
                                                              (line   6)
* vectorize:                             Vectorization and Faster Code Execution.
                                                              (line   6)
* version startup file:                  Startup Files.       (line  21)
* warning ids:                           Issuing Warnings.    (line 158)
* warranty:                              Copying.             (line   6)
* while statement:                       The while Statement. (line   6)
* wrong answers:                         Bug Criteria.        (line  12)
* wrong answers <1>:                     Bug Reporting.       (line  70)

