@c Copyright (C) 2007-2019 John W. Eaton and David Bateman
@c Copyright (C) 2010 Martin Hepperle
@c Copyright (C) 2007 Paul Thomas and Christoph Spiel
@c
@c This file is part of Octave.
@c
@c Octave is free software: you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <https://www.gnu.org/licenses/>.

@node External Code Interface
@appendix External Code Interface
@cindex dynamic-linking
@cindex Dynamically Linked Functions
@cindex Octave API

"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 @code{regexp} already exists in Octave).

Performance should generally @strong{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.

@itemize @bullet
@item
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.

@item
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
(@pxref{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.

@item
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.

@item
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.
@end itemize

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 @code{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 @sc{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::
@end menu

@node Oct-Files
@section Oct-Files
@cindex oct-files
@cindex mkoctfile
@cindex oct

@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::
@c * Application Programming Interface for Oct-Files::
@end menu

@node Getting Started with Oct-Files
@subsection 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 @file{.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 @code{mkoctfile} command with which to build oct-files.  The
command is available from within Octave or at the shell command line.

@DOCSTRING(mkoctfile)

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

@example
@group
@EXAMPLEFILE(helloworld.cc)
@end group
@end example

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

Included by @file{oct.h} is a definition for the macro @w{@code{DEFUN_DLD}}
which creates a dynamically loaded function.  This macro takes four arguments:

@enumerate 1
@item The function name as it will be seen in Octave,

@item The list of arguments to the function of type @code{octave_value_list},

@item The number of output arguments, which can be---and often is---omitted if
not used, and

@item The string to use for the help text of the function.
@end enumerate

The return type of functions defined with @w{@code{DEFUN_DLD}} is always
@code{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 @w{@code{DEFUN_DLD}} macro must match the filename
of the oct-file.  Therefore, the above function should be in a file
@file{helloworld.cc}, and would be compiled to an oct-file using the command

@example
mkoctfile helloworld.cc
@end example

This will create a file called @file{helloworld.oct} that is the compiled
version of the function.  It should be noted that it is perfectly acceptable to
have more than one @w{@code{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 @w{@code{DEFUN_DLD}} macro or the
@code{autoload} (@ref{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

@example
@group
helloworld (1, 2, 3)
@print{} Hello World has 3 input arguments and 0 output arguments.
@end group
@end example

Subsequent sections show how to use specific classes from Octave's core
internals.  Base classes like @code{dMatrix} (a matrix of double values) are
found in the directory @file{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.

@node Matrices and Arrays in Oct-Files
@subsection Matrices and Arrays in Oct-Files

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

@table @code
@item Matrix
A double precision matrix class defined in @file{dMatrix.h}

@item ComplexMatrix
A complex matrix class defined in @file{CMatrix.h}

@item BoolMatrix
A boolean matrix class defined in @file{boolMatrix.h}
@end table

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

@table @code
@item NDArray
A double precision array class defined in @file{dNDArray.h}

@item ComplexNDarray
A complex array class defined in @file{CNDArray.h}

@item boolNDArray
A boolean array class defined in @file{boolNDArray.h}

@item  int8NDArray
@itemx int16NDArray
@itemx int32NDArray
@itemx int64NDArray
8, 16, 32, and 64-bit signed array classes defined in
@file{int8NDArray.h}, @file{int16NDArray.h}, etc.

@item  uint8NDArray
@itemx uint16NDArray
@itemx uint32NDArray
@itemx uint64NDArray
8, 16, 32, and 64-bit unsigned array classes defined in
@file{uint8NDArray.h}, @file{uint16NDArray.h}, etc.
@end table

There are several basic ways of constructing matrices or multi-dimensional
arrays.  Using the class @code{Matrix} as an example one can

@itemize @bullet
@item
Create an empty matrix or array with the empty constructor.  For example:

@example
Matrix a;
@end example

This can be used for all matrix and array types.

@item
Define the dimensions of the matrix or array with a dim_vector which has the
same characteristics as the vector returned from @code{size}.  For example:

@example
@group
dim_vector dv (2, 3);  // 2 rows, 3 columns
Matrix a (dv);
@end group
@end example

This can be used for all matrix and array types.

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

@example
Matrix a (2, 2)
@end example

This constructor can @strong{only} be used with matrix types.
@end itemize

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

@deftypefn  {Method} {T&} operator () (octave_idx_type)
@deftypefnx {Method} {T&} elem (octave_idx_type)
The @code{()} operator or @code{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 @code{octave_idx_type}, that is the index into the matrix or array.
Additionally, the matrix type allows two argument versions of the @code{()}
operator and @code{elem} method, giving the row and column index of the value
to get or set.
@end deftypefn

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 @code{fortran_vec} method discussed below.

@deftypefn {Method} {octave_idx_type} numel (void) const
The total number of elements in the matrix or array.
@end deftypefn

@deftypefn {Method} {size_t} byte_size (void) const
The number of bytes used to store the matrix or array.
@end deftypefn

@deftypefn {Method} {dim_vector} dims (void) const
The dimensions of the matrix or array in value of type @code{dim_vector}.
@end deftypefn

@deftypefn {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.
@end deftypefn

@deftypefn  {Method} {void} resize (const dim_vector&)
@deftypefnx {Method} {void} resize (nrows, ncols)
A method taking either an argument of type @code{dim_vector}, or, in the case
of a matrix, two arguments of type @code{octave_idx_type} defining the number
of rows and columns in the matrix.
@end deftypefn

@deftypefn {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.
@end deftypefn

Operators such as @code{+}, @code{-}, or @code{*} 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 @code{transpose}, @code{hermitian},
@code{solve}, etc.

The typical way to extract a matrix or array from the input arguments of
@w{@code{DEFUN_DLD}} function is as follows

@example
@group
@EXAMPLEFILE(addtwomatrices.cc)
@end group
@end example

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 @code{NDArray}
and adds these together.  Note that the @code{array_value} method is called
without using the @code{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 @code{NDArray}, but for which it would make
sense to convert them to one.  The @code{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 @code{octave_execution_error} exception.

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

@example
@group
addtwomatrices (ones (2, 2), eye (2, 2))
      @result{}  2  1
          1  2
@end group
@end example

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

@multitable @columnfractions .3 .4 .3
@headitem Type @tab Function @tab Source Code
@item @code{RowVector} @tab @code{row_vector_value} @tab @file{dRowVector.h}
@item @code{ComplexRowVector} @tab @code{complex_row_vector_value} @tab @file{CRowVector.h}
@item @code{ColumnVector} @tab @code{column_vector_value} @tab @file{dColVector.h}
@item @code{ComplexColumnVector} @tab @code{complex_column_vector_value} @tab @file{CColVector.h}
@item @code{Matrix} @tab @code{matrix_value} @tab @file{dMatrix.h}
@item @code{ComplexMatrix} @tab @code{complex_matrix_value} @tab @file{CMatrix.h}
@item @code{boolMatrix} @tab @code{bool_matrix_value} @tab @file{boolMatrix.h}
@item @code{charMatrix} @tab @code{char_matrix_value} @tab @file{chMatrix.h}
@item @code{NDArray} @tab @code{array_value} @tab @file{dNDArray.h}
@item @code{ComplexNDArray} @tab @code{complex_array_value} @tab @file{CNDArray.h}
@item @code{boolNDArray} @tab @code{bool_array_value} @tab @file{boolNDArray.h}
@item @code{charNDArray} @tab @code{char_array_value} @tab @file{charNDArray.h}
@item @code{int8NDArray} @tab @code{int8_array_value} @tab @file{int8NDArray.h}
@item @code{int16NDArray} @tab @code{int16_array_value} @tab @file{int16NDArray.h}
@item @code{int32NDArray} @tab @code{int32_array_value} @tab @file{int32NDArray.h}
@item @code{int64NDArray} @tab @code{int64_array_value} @tab @file{int64NDArray.h}
@item @code{uint8NDArray} @tab @code{uint8_array_value} @tab @file{uint8NDArray.h}
@item @code{uint16NDArray} @tab @code{uint16_array_value} @tab @file{uint16NDArray.h}
@item @code{uint32NDArray} @tab @code{uint32_array_value} @tab @file{uint32NDArray.h}
@item @code{uint64NDArray} @tab @code{uint64_array_value} @tab @file{uint64NDArray.h}
@end multitable

@node Character Strings in Oct-Files
@subsection Character Strings in Oct-Files

A character string in Octave is just a special @code{Array} class.  Consider
the example:

@example
@EXAMPLEFILE(stringdemo.cc)
@end example

An example of the use of this function is

@example
@group
s0 = ["First String"; "Second String"];
[s1,s2] = stringdemo (s0)
@result{} s1 = Second String
        First String

@result{} s2 = First String
        Second String

typeinfo (s2)
@result{} sq_string
typeinfo (s1)
@result{} string
@end group
@end example

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

@example
@group
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";
@end group
@end example

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

@example
@group
octave_value_list retval;
charNDArray ch;
@dots{}
// 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, '"');
@end group
@end example

@node Cell Arrays in Oct-Files
@subsection Cell Arrays in Oct-Files

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

@example
@EXAMPLEFILE(celldemo.cc)
@end example

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

@example
@group
[b1, b2, b3] = celldemo (@{1, [1, 2], "test"@})
@result{}
b1 =  1
b2 =

   1   2

b3 = test
@end group
@end example

@node Structures in Oct-Files
@subsection Structures in Oct-Files

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

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

@example
@EXAMPLEFILE(structdemo.cc)
@end example

An example of its use is

@example
@group
x.a = 1; x.b = "test"; x.c = [1, 2];
structdemo (x, "b")
@result{} selected = test
@end group
@end example

The example above specifically uses the @code{octave_scalar_map} class which is
for representing a single struct.  For structure arrays, the @code{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 @code{contents} method returns
a @code{Cell} which may have more than one element.  Therefore, to obtain the
underlying @code{octave_value} in the single struct example we would write

@example
octave_value tmp = arg0.contents (arg1)(0);
@end example

@noindent
where the trailing @code{(0)} is the @code{()} operator on the @code{Cell}
object.  If this were a true structure array with multiple elements we could
iterate over the elements using the @code{()} operator.

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

@node Sparse Matrices in Oct-Files
@subsection Sparse Matrices in Oct-Files

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

@table @code
@item SparseMatrix
A double precision sparse matrix class

@item SparseComplexMatrix
A complex sparse matrix class

@item SparseBoolMatrix
A boolean sparse matrix class
@end table

All of these classes inherit from the @code{Sparse<T>} template class, and so
all have similar capabilities and usage.  The @code{Sparse<T>} class was based
on Octave's @code{Array<T>} class and users familiar with Octave's
@code{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 @code{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 @strong{must} be 2-dimensional.  This means
that @code{SparseMatrix} is actually more similar to Octave's @code{Matrix}
class than it is to the @code{NDArray} class.

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

@node Array and Sparse Class Differences
@subsubsection 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,

@example
@group
SparseMatrix sm;
@dots{}
int nnz = sm.nelem ();
@end group
@end example

@noindent
returns the number of nonzero elements (like the interpreter function
@code{nnz}).  If the user really requires the number of elements in the matrix,
including the nonzero elements, they should use @code{numel} rather than
@code{nelem}.  Note that for very large matrices, where the product of the two
dimensions is larger than the representation of an unsigned int, @code{numel}
can overflow.  An example is @code{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 @code{numel} should, therefore, be avoided unless it is known that it
will not overflow.

Extreme care is also required when using the @code{elem} method or the
@code{()} 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

@example
@group
SparseMatrix sm;
@dots{}
for (int j = 0; j < nc; j++)
  for (int i = 0; i < nr; i++)
    std::cerr << " (" << i << "," << j << "): " << sm(i,j) << "\n";
@end group
@end example

@noindent
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

@example
@group
SparseMatrix sm;
@dots{}
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";
@end group
@end example

Finally, because the sparse types aren't represented by a contiguous block of
memory, the @nospell{@code{fortran_vec}} method of @code{Array<T>} is not
available.  It is, however, replaced by three separate methods @code{ridx},
@code{cidx}, and @code{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 @code{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.

@node Creating Sparse Matrices in Oct-Files
@subsubsection 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

@example
@group
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);
@end group
@end example

@noindent
which creates the matrix given in section @ref{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:

@example
@group
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;
@end group
@end example

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,

@example
@group
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;
@end group
@end example

@noindent
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 @var{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 @code{maybe_compress}
function.  In addition to deallocating unused storage, @code{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
@code{maybe_compress} function to be @code{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 @code{maybe_compress} is

@example
@group
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
@end group
@end example

The use of the @code{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

@example
octave_value arg;
@dots{}
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.
@end example

@noindent
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
@code{change_capacity} exists to reallocate the sparse memory.  The above
example would then be modified as

@example
octave_value arg;
@dots{}
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.
@end example

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.

@node Using Sparse Matrices in Oct-Files
@subsubsection 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 @code{octave_value}, and returning
it as an @code{octave_value}, can be seen in the following example.

@example
@group
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 ();
@dots{}
retval(2) = sbm;
retval(1) = scm;
retval(0) = sm;
@end group
@end example

The conversion to an @code{octave_value} is handled by the sparse
@code{octave_value} constructors, and so no special care is needed.

@node Accessing Global Variables in Oct-Files
@subsection 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
@w{@code{global_varval}} and @w{@code{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 @w{@code{global_assign}} is the value to be assigned.  An
example of the use of these two functions is

@example
@EXAMPLEFILE(globaldemo.cc)
@end example

An example of its use is

@example
@group
global a b
b = 10;
globaldemo ("b")
@result{} 10
globaldemo ("c")
@result{} "Global variable not found"
num2str (a)
@result{} 42
@end group
@end example

@node Calling Octave Functions from Oct-Files
@subsection 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 @code{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

@enumerate 1
@item Function Handle

@item Anonymous Function Handle

@item String
@end enumerate

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

@example
@EXAMPLEFILE(funcdemo.cc)
@end example

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

@example
@group
funcdemo (@@sin, 1)
@result{} 0.84147
funcdemo (@@(x) sin (x), 1)
@result{} 0.84147
funcdemo ("sin", 1)
@result{} 0.84147
funcdemo (@@atan2, 1, 1)
@result{} 0.78540
@end group
@end example

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 @code{octave_function} object.  In that case the string argument can be used
to create a temporary function as demonstrated below.

@example
@group
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");
@dots{}
if (fcn_name.length ())
  clear_function (fcn_name);
@end group
@end example

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 @samp{__}.

@node Calling External Code from Oct-Files
@subsection 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 @file{foo.h}, then the tactic to ensure that the C++ compiler
treats these declarations as C code is

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

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 @code{XSTOPX} function to replace
the Fortran @code{STOP} function.  @code{XSTOPX} uses the Octave exception
handler to treat failing cases in the Fortran code explicitly.  Note that
Octave supplies its own replacement @sc{blas} @code{XERBLA} function, which
uses @code{XSTOPX}.

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

There is no great harm in using @w{@code{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 @w{@code{F77_FCN}}
is used with code that calls @code{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

@example
@EXAMPLEFILE(fortrandemo.cc)
@end example

@noindent
and the Fortran function is

@example
@EXAMPLEFILE(fortransub.f)
@end example

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.

@example
@group
mkoctfile fortrandemo.cc fortransub.f
[b, s] = fortrandemo (1:3)
@result{}
  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
@end group
@end example

@node Allocating Local Memory in Oct-Files
@subsection 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 @w{@code{OCTAVE_LOCAL_BUFFER}} macro.  An example of its use is

@example
OCTAVE_LOCAL_BUFFER (double, tmp, len)
@end example

@noindent
that returns a pointer @code{tmp} of type @code{double *} of length @code{len}.

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

@node Input Parameter Checking in Oct-Files
@subsection 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 @code{octave_value}
class like @code{is_real_matrix}, @code{is_numeric_type}, etc. (see
@file{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.

@example
@EXAMPLEFILE(paramdemo.cc)
@end example

@noindent
An example of its use is:

@example
@group
paramdemo ([1, 2, NaN, Inf])
@result{} Properties of input array:
     includes Inf or NaN values
     includes other values than 1 and 0
     includes only int, Inf or NaN values
@end group
@end example

@node Exception and Error Handling in Oct-Files
@subsection Exception and Error Handling in Oct-Files

Another important feature of Octave is its ability to react to the user typing
@key{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
@w{@code{OCTAVE_QUIT}}, in order to allow Octave to check and possibly respond
to a user typing @key{Control-C}.  For example:

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

The presence of the @w{@code{OCTAVE_QUIT}} macro in the inner loop allows
Octave to detect and acknowledge a @key{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 @key{Control-C} three times
which will force Octave to exit completely.

The @w{@code{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
@w{@code{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 @w{@code{OCTAVE_QUIT}} macro in this case.  The
alternative code in this case is

@example
@group
BEGIN_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
@dots{}  some code that calls a "foreign" function @dots{}
END_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
@end group
@end example

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 @nospell{@code{fortran_vec}}
method or the @w{@code{OCTAVE_LOCAL_BUFFER}} macro.

The Octave @code{unwind_protect} mechanism (@ref{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

@example
@EXAMPLEFILE(unwinddemo.cc)
@end example

As can be seen in the example:

@example
@group
unwinddemo (1, 0)
@result{} Inf
1 / 0
@result{} warning: division by zero
   Inf
@end group
@end example

The warning for division by zero (and in fact all warnings) are disabled in the
@code{unwinddemo} function.

@node Documentation and Testing of Oct-Files
@subsection Documentation and Testing of Oct-Files

The documentation for an oct-file is contained in the fourth string parameter
of the @w{@code{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,

@example
@group
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")
@{
@dots{}
@}
@end group
@end example

@noindent
where each line of text is terminated by @code{\n\} which is an embedded
newline in the string together with a C++ string continuation character.  Note
that the final @code{\} 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 (@pxref{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 @code{%!} 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

@example
@group
/*
%!assert (sin ([1,2]), [sin(1),sin(2)])
%!error (sin ())
%!error (sin (1,1))
*/
@end group
@end example

@c @node Application Programming Interface for Oct-Files
@c @subsection Application Programming Interface for Oct-Files
@c
@c WRITE ME, using Coda section 1.3 as a starting point.

@node Mex-Files
@section Mex-Files
@cindex mex-files
@cindex mex

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 @sc{matlab} users.  However, as mex-files expose @sc{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::
@c * Application Programming Interface for Mex-Files::
@end menu

@node Getting Started with Mex-Files
@subsection Getting Started with Mex-Files

The basic command to build a mex-file is either @code{mkoctfile --mex} or
@code{mex}.  The first command can be used either from within Octave or from
the command line.  To avoid issues with @sc{matlab}'s own @code{mex} command,
the use of the command @code{mex} is limited to within Octave.  Compiled
mex-files have the extension @file{.mex}.

@DOCSTRING(mex)

@DOCSTRING(mexext)

Consider the following short example:

@example
@group
@EXAMPLEFILE(myhello.c)
@end group
@end example

The first line @code{#include "mex.h"} makes available all of the definitions
necessary for a mex-file.  One important difference between Octave and
@sc{matlab} is that the header file @qcode{"matrix.h"} is implicitly included
through the inclusion of @qcode{"mex.h"}.  This is necessary to avoid a
conflict with the Octave file @qcode{"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 @code{mexFunction}.  The
function takes four arguments:

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

@item An array of pointers to return arguments.

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

@item An array of pointers to input arguments.
@end enumerate

Note that the function name definition is not explicitly included in
@code{mexFunction} and so there can only be a single @code{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 @file{myhello.c}, it can be compiled with

@example
mkoctfile --mex myhello.c
@end example

@noindent
which creates a file @file{myhello.mex}.  The function can then be run from
Octave as

@example
@group
myhello (1,2,3)
@result{} Hello, World!
@result{} I have 3 inputs and 0 outputs
@end group
@end example

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
@file{myhello.m} which might contain the text

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

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 @code{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

@example
@group
@EXAMPLEFILE(myfunc.c)
@end group
@end example

@noindent
is in the file @file{myfunc.c}, and is compiled with

@example
@group
mkoctfile --mex myfunc.c
ln -s myfunc.mex myfunc2.mex
@end group
@end example

@noindent
then as can be seen by

@example
@group
myfunc ()
@result{} You called function: myfunc
    This is the principal function
myfunc2 ()
@result{} You called function: myfunc2
@end group
@end example

@noindent
the behavior of the mex-file can be altered depending on the function's name.

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

@node Working with Matrices and Arrays in Mex-Files
@subsection Working with Matrices and Arrays in Mex-Files

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

The @code{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 @code{mxArray}.  There are a number of functions to create
@code{mxArray} structures, including @code{mxCreateDoubleMatrix},
@code{mxCreateCellArray}, @code{mxCreateSparse}, and the generic
@code{mxCreateNumericArray}.

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

@example
@group
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);
@end group
@end example

There are also the functions @code{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 @code{mxSetPr}.

Note the type @code{mwSize} used above, and also @code{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.  @code{mwSize} is used to define array dimensions and the maximum
number or elements, while @code{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 @file{mypow2.c} shown below.

@example
@EXAMPLEFILE(mypow2.c)
@end example

@noindent
An example of its use is

@example
@group
b = randn (4,1) + 1i * randn (4,1);
all (b.^2 == mypow2 (b))
@result{} 1
@end group
@end example

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

@node Character Strings in Mex-Files
@subsection 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 @file{stringdemo.cc} is given in the file @file{mystring.c}, as shown
below.

@example
@EXAMPLEFILE(mystring.c)
@end example

@noindent
An example of its expected output is

@example
@group
mystring (["First String"; "Second String"])
@result{} Second String
   First String
@end group
@end example

Other functions in the mex interface for handling character strings are
@code{mxCreateString}, @code{mxArrayToString}, and
@code{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 @code{mxArray} for the matrix is consecutive in
any case.

@node Cell Arrays with Mex-Files
@subsection 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 @file{celldemo.cc}
oct-file in a mex-file is given by @file{mycell.c} as shown below.

@example
@EXAMPLEFILE(mycell.c)
@end example

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

@example
@group
[b1, b2, b3] = mycell (@{1, [1, 2], "test"@})
@result{}
b1 =  1
b2 =

   1   2

b3 = test
@end group
@end example

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

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

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

@example
@group
mxArray *mxCreateCellArray (int ndims, const int *dims);
mxArray *mxCreateCellMatrix (int m, int n);
@end group
@end example

@node Structures with Mex-Files
@subsection Structures with Mex-Files

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

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

Accessing the fields of the structure can then be performed with
@code{mxGetField} and @code{mxSetField} or alternatively with the
@code{mxGetFieldByNumber} and @code{mxSetFieldByNumber} functions.

@example
@group
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);
@end group
@end example

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 @code{index} over the elements of the arrays of elements per
@code{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 @file{mystruct.c} shown below.

@example
@EXAMPLEFILE(mystruct.c)
@end example

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

@example
@group
a(1).f1 = "f11"; a(1).f2 = "f12";
a(2).f1 = "f21"; a(2).f2 = "f22";
b = mystruct (a);
@result{}  field f1(0) = f11
    field f1(1) = f21
    field f2(0) = f12
    field f2(1) = f22
b
@result{} 2x2 struct array containing the fields:

     this
     that

b(3)
@result{} scalar structure containing the fields:

     this = this3
     that = that3
@end group
@end example

@node Sparse Matrices with Mex-Files
@subsection 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 @code{mxGetM}, @code{mxGetN},
@code{mxSetM}, @code{mxSetN}, @code{mxGetPr}, @code{mxGetPi}, @code{mxSetPr},
and @code{mxSetPi}, also supplies the following functions.

@example
@group
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);
@end group
@end example

@noindent
@code{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.  @code{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 @code{mxGetJc} define the number of nonzero
elements in each column of the sparse matrix.  Therefore,

@example
@group
mwSize nz, n;
mwIndex *Jc;
mxArray *m;
@dots{}
n = mxGetN (m);
Jc = mxGetJc (m);
nz = Jc[n];
@end group
@end example

@noindent
returns the actual number of nonzero elements stored in the matrix in
@code{nz}.  As the arrays returned by @code{mxGetPr} and @code{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 @code{mxGetIr}.  A complete example
of the use of sparse matrices in mex-files is given by the file
@file{mysparse.c} shown below.

@example
@EXAMPLEFILE(mysparse.c)
@end example

A sample usage of @code{mysparse} is

@example
@group
sm = sparse ([1, 0; 0, pi]);
mysparse (sm)
@result{}
Matrix is 2-by-2 real sparse matrix with 2 elements
last nonzero element (2, 2) = 3.14159
@end group
@end example

@node Calling Other Functions in Mex-Files
@subsection Calling Other Functions in Mex-Files

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

@example
@EXAMPLEFILE(myfeval.c)
@end example

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

@example
@group
a = myfeval ("sin", 1)
@result{} Starting file myfeval.mex
   I have 2 inputs and 1 outputs
   I'm going to call the interpreter function sin
   a =  0.84147
@end group
@end example

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

@c @node Application Programming Interface for Mex-Files
@c @subsection Application Programming Interface for Mex-Files
@c
@c WRITE ME, refer to mex.h and mexproto.h

@node Standalone Programs
@section 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 @file{liboctave.a} or @file{liboctave.so}.

@example
@EXAMPLEFILE(standalone.cc)
@end example

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

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

Note that the application @code{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

@example
@EXAMPLEFILE(embedded.cc)
@end example

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

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

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 @code{function_name} in
the interpreter, there will be a C++ function named @code{Ffunction_name} (note
the prepended capital @code{F}) accessible in the C++ API@.  The declarations
for all built-in functions are collected in the header file
@code{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 @file{.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

@example
@EXAMPLEFILE(standalonebuiltin.cc)
@end example

@noindent
which is compiled and run as a standalone application with

@example
@group
$ 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
$
@end group
@end example

@node Java Interface
@section Java Interface

@cindex using Octave with Java
@cindex Java, using with Octave
@cindex calling Java from Octave
@cindex Java, calling from Octave
@cindex calling Octave from Java
@cindex Octave, calling from Java

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 @code{joPas} (@url{http://jopas.sourceforge.net}).

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


@node Making Java Classes Available
@subsection Making Java Classes Available

@c - index -
@cindex classpath, setting
@cindex classpath, difference between static and dynamic
@cindex static classpath
@cindex dynamic classpath
@cindex @file{javaclasspath.txt}
@cindex @file{classpath.txt}
@cindex classes, making available to Octave
@c - index -

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

@itemize
@item the @var{static classpath} is initialized once at startup of the JVM, and

@item the @var{dynamic classpath} which can be modified at runtime.
@end itemize

Octave searches the @var{static classpath} first, and then the
@var{dynamic classpath}.  Classes appearing in the @var{static classpath}, as
well as in the @var{dynamic classpath}, will therefore be found in the
@var{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
@var{static classpath}.  The @var{static classpath} is populated once from the
contents of a plain text file named @file{javaclasspath.txt} (or
@file{classpath.txt} historically) when the Java Virtual Machine starts.  This
file contains one line for each individual classpath to be added to the
@var{static classpath}.  These lines can identify directories containing class
files, or Java archives with complete class file hierarchies.  Comment lines
starting with a @samp{#} or a @samp{%} character are ignored.

The search rules for the file @file{javaclasspath.txt} (or
@file{classpath.txt}) are:

@itemize
@item
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
@var{static classpath}.  Thus, it is possible to define a static classpath on a
'per Octave invocation' basis.

@item
Next, Octave searches in the user's home directory.  If a file
@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 @nospell{'per user'} basis.

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

@example
which javaclasspath
@end example

If this file exists here, its contents are also appended to the
@var{static classpath}.  Note that the archives and class directories defined
in this last step will affect all users.
@end itemize

Classes which are used only by a specific script should be placed in the
@var{dynamic classpath}.  This portion of the classpath can be modified at
runtime using the @code{javaaddpath} and @code{javarmpath} functions.

Example:

@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.
@end example

Another way to add files to the @var{dynamic classpath} exclusively for your
user account is to use the file @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 @file{octave}
to Octave's search path and the archive @file{myclasses.jar} in this directory
to the Java search path.

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

@c ------------------------------------------------------------------------
@node How to use Java from within Octave
@subsection How to use Java from within Octave

The function @ref{XREFjavaObject,javaObject,javaObject} 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
@code{BigDecimal(double)} and @code{BigDecimal(String)} of the builtin Java
class @code{java.math.BigDecimal}.

@example
@group
javaObject ("java.math.BigDecimal",  1.001 );
javaObject ("java.math.BigDecimal", "1.001");
@end group
@end example

Note that parameters of the Octave type @code{double} are implicitly converted
into the Java type @code{double} and the Octave type (array of) @code{char} is
converted into the java type @code{String}.  A Java object created by
@ref{XREFjavaObject,javaObject,javaObject} is never automatically converted
into an Octave type but remains a Java object.  It can be assigned to an
Octave variable.

@example
@group
a = 1.001;
b = javaObject ("java.math.BigDecimal", a);
@end group
@end example

Using @ref{XREFisjava,isjava,isjava}, 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:

@example
@group
isjava (a)
@result{} ans = 0
class (a)
@result{} ans = double
isjava (b)
@result{} ans = 1
class (b)
@result{} ans = java.math.BigDecimal
@end group
@end example

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

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

isjava (a)
@result{} ans = 1
class (a)
@result{} ans = java.lang.Double
isjava (b)
@result{} ans = 1
class (b)
@result{} ans = java.math.BigDecimal
@end group
@end example

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


Via @ref{XREFjavaObject,javaObject,javaObject} one may create all kinds of
Java objects but arrays.  The latter are created through
@ref{XREFjavaArray,javaArray,javaArray}.

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

@example
@group
a.toString
@result{} ans = 1.001
b.toString
@result{} ans = 1.000999999999999889865...
@end group
@end example

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

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

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

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:

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

Accordingly, with @ref{XREFjava_set,java_set,java_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 @code{[]}
represent Java's @code{null} value and how Java exceptions are represented.

@example
@group
javaObject ("java.math.BigDecimal", []);
@result{} error: [java] java.lang.NullPointerException
@end group
@end example

It is not recommended to represent Java's @code{null} value by empty brackets
@code{[]}, because @code{null} has no type whereas @code{[]} has type
@code{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.

@example
@group
fieldnames (<Java object>)
methods (<Java object>)
@end group
@end example

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

@example
@group
debug_java (true)  # use "false" to omit display of stack trace
debug_java ()
@result{} ans = 1
javaObject ("java.math.BigDecimal", "1") ...
  .divide (javaObject ("java.math.BigDecimal", "0"))
@end group
@end example



@node Set up the JVM
@subsection Set up the JVM
@cindex memory, limitations on JVM
@cindex select JVM version

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
@file{HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\JRE} or
@file{HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime Environment} on
Windows.  The default path to the JVM can be overridden by setting the
environment variable @w{@env{JAVA_HOME}} to the path where the JVM is
installed.  On Windows that might be, for example,
@file{C:\Program Files\Java\jre-10.0.2}.  Make sure that you select a directory
that contains the JVM with a @nospell{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 @code{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
(@pxref{XREFjavamem,,javamem}).  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
@file{java.opts}.  This is a text file where enter you enter lines containing
@option{-X} and @option{-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 @w{@env{OCTAVE_JAVA_DIR}}.  If unset the directory where
@file{javaclasspath.m} resides is used instead (typically
@file{@w{@env{OCTAVE_HOME}}/share/octave/@w{@env{OCTAVE_VERSION}}/m/java/}).
You can find this directory by executing

@example
which javaclasspath
@end example

The @option{-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 @file{java.opts} file:

@example
-Xmx256m
@end example

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 @file{java.opts} file starts the JVM with 64
Megabytes of initial memory:

@example
-Xms64m
@end example

For more details on the available @option{-X} options of your Java Virtual
Machine issue the command @samp{java -X} at the operating system command prompt
and consult the Java documentation.

The @option{-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 @code{getProperty()} methods of the @code{java.lang.System} class.
The following example line defines the property @var{MyProperty} and assigns it
the string @code{12.34}.

@example
-DMyProperty=12.34
@end example

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

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

@seealso{javamem}



@node Java Interface Functions
@subsection 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.

@cindex object, creating a Java object
@cindex instance, creating a Java instance
@DOCSTRING(javaObject)

@cindex array, creating a Java array
@DOCSTRING(javaArray)

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

@DOCSTRING(isjava)

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.

@cindex fields, displaying available fields of a Java object
In Octave the @code{fieldnames} function for structures has been overloaded
to return the fields of a Java object.  For example:

@example
@group
dobj = javaObject ("java.lang.Double", pi);
fieldnames (dobj)
@result{}
@{
  [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
@}
@end group
@end example

@cindex field, returning value of Java object field
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 @samp{.}
operator from structures.  This is the preferred method for reading fields, but
Octave also provides a function interface to read fields with @code{java_get}.
An example of both styles is shown below.

@example
@group
dobj = javaObject ("java.lang.Double", pi);
dobj.MAX_VALUE
@result{}  1.7977e+308
java_get ("java.lang.Float", "MAX_VALUE")
@result{}  3.4028e+38
@end group
@end example

@DOCSTRING(java_get)

@cindex field, setting value of Java object field
@DOCSTRING(java_set)

@cindex methods, displaying available methods of a Java object
To see what functions can be called with an object use @code{methods}.  For
example, using the previously created @var{dobj}:

@example
@group
methods (dobj)
@result{}
Methods for class java.lang.Double:
boolean equals(java.lang.Object)
java.lang.String toString(double)
java.lang.String toString()
@dots{}
@end group
@end example

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

@example
@group
dobj = javaObject ("java.lang.Double", pi);
dobj.equals (3)
@result{}  0
javaMethod ("equals", dobj, pi)
@result{}  1
@end group
@end example

@cindex method, invoking a method of a Java object
@DOCSTRING(javaMethod)

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
@env{PATH} variable and is used by the JVM to find the correct code to execute.

@cindex classpath, displaying
@cindex classpath, dynamic
@cindex dynamic classpath
@cindex classpath, static
@cindex static classpath
@DOCSTRING(javaclasspath)

@findex javaaddpath
@cindex classpath, adding new path
@cindex path, adding to classpath
@cindex classpath, dynamic
@cindex dynamic classpath, adding new path
@DOCSTRING(javaaddpath)

@cindex classpath, removing path
@cindex path, removing from classpath
@DOCSTRING(javarmpath)

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

@DOCSTRING(javachk)

@DOCSTRING(usejava)

@cindex memory, displaying Java memory status
@DOCSTRING(javamem)

@DOCSTRING(java_matrix_autoconversion)

@DOCSTRING(java_unsigned_autoconversion)

@DOCSTRING(debug_java)