### DO NOT EDIT!
###
### This file is generated automatically from the Octave sources.
### Edit those files instead and run make to update this file.

bitand
@c bitand src/bitfcns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} bitand (@var{x}, @var{y})
Return the bitwise AND of non-negative integers.
@var{x}, @var{y} must be in the range [0,bitmax]
@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax}
@end deftypefn
bitor
@c bitor src/bitfcns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} bitor (@var{x}, @var{y})
Return the bitwise OR of non-negative integers.
@var{x}, @var{y} must be in the range [0,bitmax]
@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax}
@end deftypefn
bitxor
@c bitxor src/bitfcns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} bitxor (@var{x}, @var{y})
Return the bitwise XOR of non-negative integers.
@var{x}, @var{y} must be in the range [0,bitmax]
@seealso{bitand, bitor, bitset, bitget, bitcmp, bitshift, bitmax}
@end deftypefn
bitshift
@c bitshift src/bitfcns.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} bitshift (@var{a}, @var{k})
@deftypefnx {Built-in Function} {} bitshift (@var{a}, @var{k}, @var{n})
Return a @var{k} bit shift of @var{n}-digit unsigned
integers in @var{a}.  A positive @var{k} leads to a left shift;
A negative value to a right shift.  If @var{n} is omitted it defaults
to log2(bitmax)+1.
@var{n} must be in the range [1,log2(bitmax)+1] usually [1,33].

@example
@group
bitshift (eye (3), 1)
@result{}
@group
2 0 0
0 2 0
0 0 2
@end group

bitshift (10, [-2, -1, 0, 1, 2])
@result{} 2   5  10  20  40
@c FIXME -- restore this example when third arg is allowed to be an array.
@c
@c
@c bitshift ([1, 10], 2, [3,4])
@c @result{} 4  8
@end group
@end example
@seealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, bitmax}
@end deftypefn
bitmax
@c bitmax src/bitfcns.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} bitmax ()
@deftypefnx {Built-in Function} {} bitmax ("double")
@deftypefnx {Built-in Function} {} bitmax ("single")
Return the largest integer that can be represented within a floating point
value.  The default class is "double", but "single" is a valid option.
On IEEE-754 compatible systems, @code{bitmax} is @w{@math{2^{53} - 1}}.
@end deftypefn
intmax
@c intmax src/bitfcns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} intmax (@var{type})
Return the largest integer that can be represented in an integer type.
The variable @var{type} can be

@table @code
@item int8
signed 8-bit integer.

@item int16
signed 16-bit integer.

@item int32
signed 32-bit integer.

@item int64
signed 64-bit integer.

@item uint8
unsigned 8-bit integer.

@item uint16
unsigned 16-bit integer.

@item uint32
unsigned 32-bit integer.

@item uint64
unsigned 64-bit integer.
@end table

The default for @var{type} is @code{uint32}.
@seealso{intmin, bitmax}
@end deftypefn
intmin
@c intmin src/bitfcns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} intmin (@var{type})
Return the smallest integer that can be represented in an integer type.
The variable @var{type} can be

@table @code
@item int8
signed 8-bit integer.

@item int16
signed 16-bit integer.

@item int32
signed 32-bit integer.

@item int64
signed 64-bit integer.

@item uint8
unsigned 8-bit integer.

@item uint16
unsigned 16-bit integer.

@item uint32
unsigned 32-bit integer.

@item uint64
unsigned 64-bit integer.
@end table

The default for @var{type} is @code{uint32}.
@seealso{intmax, bitmax}
@end deftypefn
sizemax
@c sizemax src/bitfcns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} sizemax ()
Return the largest value allowed for the size of an array.
If Octave is compiled with 64-bit indexing, the result is of class int64,
otherwise it is of class int32.  The maximum array size is slightly
smaller than the maximum value allowable for the relevant class as reported
by @code{intmax}.
@seealso{intmax}
@end deftypefn
all
@c all src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} all (@var{x})
@deftypefnx {Built-in Function} {} all (@var{x}, @var{dim})
For a vector argument, return true (logical 1) if all elements of the vector
are nonzero.

For a matrix argument, return a row vector of logical ones and
zeros with each element indicating whether all of the elements of the
corresponding column of the matrix are nonzero.  For example:

@example
@group
all ([2, 3; 1, 0]))
     @result{} [ 1, 0 ]
@end group
@end example

If the optional argument @var{dim} is supplied, work along dimension
@var{dim}.
@seealso{any}
@end deftypefn
any
@c any src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} any (@var{x})
@deftypefnx {Built-in Function} {} any (@var{x}, @var{dim})
For a vector argument, return true (logical 1) if any element of the vector
is nonzero.

For a matrix argument, return a row vector of logical ones and
zeros with each element indicating whether any of the elements of the
corresponding column of the matrix are nonzero.  For example:

@example
@group
any (eye (2, 4))
     @result{} [ 1, 1, 0, 0 ]
@end group
@end example

If the optional argument @var{dim} is supplied, work along dimension
@var{dim}.  For example:

@example
@group
any (eye (2, 4), 2)
     @result{} [ 1; 1 ]
@end group
@end example
@seealso{all}
@end deftypefn
atan2
@c atan2 src/data.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} atan2 (@var{y}, @var{x})
Compute atan (@var{y} / @var{x}) for corresponding elements of @var{y}
and @var{x}.  Signal an error if @var{y} and @var{x} do not match in size
and orientation.
@end deftypefn
hypot
@c hypot src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} hypot (@var{x}, @var{y})
@deftypefnx {Built-in Function} {} hypot (@var{x}, @var{y}, @var{z}, @dots{})
Compute the element-by-element square root of the sum of the squares of
@var{x} and @var{y}.  This is equivalent to
@code{sqrt (@var{x}.^2 + @var{y}.^2)}, but calculated in a manner that
avoids overflows for large values of @var{x} or @var{y}.
@code{hypot} can also be called with more than 2 arguments; in this case,
the arguments are accumulated from left to right:

@example
@group
  hypot (hypot (@var{x}, @var{y}), @var{z})
  hypot (hypot (hypot (@var{x}, @var{y}), @var{z}), @var{w}), etc.
@end group
@end example
@end deftypefn
log2
@c log2 src/data.cc
-*- texinfo -*-
@deftypefn  {Mapping Function} {} log2 (@var{x})
@deftypefnx {Mapping Function} {[@var{f}, @var{e}] =} log2 (@var{x})
Compute the base-2 logarithm of each element of @var{x}.

If called with two output arguments, split @var{x} into
binary mantissa and exponent so that
@tex
${1 \over 2} \le \left| f \right| < 1$
@end tex
@ifnottex
@code{1/2 <= abs(f) < 1}
@end ifnottex
and @var{e} is an integer.  If
@tex
$x = 0$, $f = e = 0$.
@end tex
@ifnottex
@code{x = 0}, @code{f = e = 0}.
@end ifnottex
@seealso{pow2, log, log10, exp}
@end deftypefn
rem
@c rem src/data.cc
-*- texinfo -*-
@deftypefn  {Mapping Function} {} rem (@var{x}, @var{y})
@deftypefnx {Mapping Function} {} fmod (@var{x}, @var{y})
Return the remainder of the division @code{@var{x} / @var{y}}, computed
using the expression

@example
x - y .* fix (x ./ y)
@end example

An error message is printed if the dimensions of the arguments do not
agree, or if either of the arguments is complex.
@seealso{mod}
@end deftypefn
mod
@c mod src/data.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} mod (@var{x}, @var{y})
Compute the modulo of @var{x} and @var{y}.  Conceptually this is given by

@example
x - y .* floor (x ./ y)
@end example

@noindent
and is written such that the correct modulus is returned for
integer types.  This function handles negative values correctly.  That
is, @code{mod (-1, 3)} is 2, not -1, as @code{rem (-1, 3)} returns.
@code{mod (@var{x}, 0)} returns @var{x}.

An error results if the dimensions of the arguments do not agree, or if
either of the arguments is complex.
@seealso{rem}
@end deftypefn
cumprod
@c cumprod src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} cumprod (@var{x})
@deftypefnx {Built-in Function} {} cumprod (@var{x}, @var{dim})
Cumulative product of elements along dimension @var{dim}.  If
@var{dim} is omitted, it defaults to the first non-singleton dimension.

@seealso{prod, cumsum}
@end deftypefn
cumsum
@c cumsum src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} cumsum (@var{x})
@deftypefnx {Built-in Function} {} cumsum (@var{x}, @var{dim})
@deftypefnx {Built-in Function} {} cumsum (@dots{}, 'native')
@deftypefnx {Built-in Function} {} cumsum (@dots{}, 'double')
@deftypefnx {Built-in Function} {} cumsum (@dots{}, 'extra')
Cumulative sum of elements along dimension @var{dim}.  If @var{dim}
is omitted, it defaults to the first non-singleton dimension.

See @code{sum} for an explanation of the optional parameters 'native',
'double', and 'extra'.
@seealso{sum, cumprod}
@end deftypefn
diag
@c diag src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{M} =} diag (@var{v})
@deftypefnx {Built-in Function} {@var{M} =} diag (@var{v}, @var{k})
@deftypefnx {Built-in Function} {@var{M} =} diag (@var{v}, @var{m}, @var{n})
@deftypefnx {Built-in Function} {@var{v} =} diag (@var{M})
@deftypefnx {Built-in Function} {@var{v} =} diag (@var{M}, @var{k})
Return a diagonal matrix with vector @var{v} on diagonal @var{k}.  The
second argument is optional.  If it is positive, the vector is placed on
the @var{k}-th super-diagonal.  If it is negative, it is placed on the
@var{-k}-th sub-diagonal.  The default value of @var{k} is 0, and the
vector is placed on the main diagonal.  For example:

@example
@group
diag ([1, 2, 3], 1)
     @result{}  0  1  0  0
         0  0  2  0
         0  0  0  3
         0  0  0  0
@end group
@end example

@noindent
The 3-input form returns a diagonal matrix with vector @var{v} on the main
diagonal and the resulting matrix being of size @var{m} rows x @var{n}
columns.

Given a matrix argument, instead of a vector, @code{diag} extracts the
@var{k}-th diagonal of the matrix.
@end deftypefn
prod
@c prod src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} prod (@var{x})
@deftypefnx {Built-in Function} {} prod (@var{x}, @var{dim})
Product of elements along dimension @var{dim}.  If @var{dim} is
omitted, it defaults to the first non-singleton dimension.
@seealso{cumprod, sum}
@end deftypefn
horzcat
@c horzcat src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} horzcat (@var{array1}, @var{array2}, @dots{}, @var{arrayN})
Return the horizontal concatenation of N-D array objects, @var{array1},
@var{array2}, @dots{}, @var{arrayN} along dimension 2.

Arrays may also be concatenated horizontally using the syntax for creating
new matrices.  For example:

@example
@var{hcat} = [ @var{array1}, @var{array2}, @dots{} ];
@end example
@seealso{cat, vertcat}
@end deftypefn
vertcat
@c vertcat src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} vertcat (@var{array1}, @var{array2}, @dots{}, @var{arrayN})
Return the vertical concatenation of N-D array objects, @var{array1},
@var{array2}, @dots{}, @var{arrayN} along dimension 1.

Arrays may also be concatenated vertically using the syntax for creating
new matrices.  For example:

@example
@var{vcat} = [ @var{array1}; @var{array2}; @dots{} ];
@end example
@seealso{cat, horzcat}
@end deftypefn
cat
@c cat src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} cat (@var{dim}, @var{array1}, @var{array2}, @dots{}, @var{arrayN})
Return the concatenation of N-D array objects, @var{array1},
@var{array2}, @dots{}, @var{arrayN} along dimension @var{dim}.

@example
@group
A = ones (2, 2);
B = zeros (2, 2);
cat (2, A, B)
    @result{} 1 1 0 0
       1 1 0 0
@end group
@end example

Alternatively, we can concatenate @var{A} and @var{B} along the
second dimension the following way:

@example
@group
[A, B].
@end group
@end example

@var{dim} can be larger than the dimensions of the N-D array objects
and the result will thus have @var{dim} dimensions as the
following example shows:

@example
@group
cat (4, ones (2, 2), zeros (2, 2))
    @result{} ans =

       ans(:,:,1,1) =

         1 1
         1 1

       ans(:,:,1,2) =
         0 0
         0 0
@end group
@end example
@seealso{horzcat, vertcat}
@end deftypefn
permute
@c permute src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} permute (@var{A}, @var{perm})
Return the generalized transpose for an N-D array object @var{A}.
The permutation vector @var{perm} must contain the elements
@code{1:ndims(A)} (in any order, but each element must appear only once).
@seealso{ipermute}
@end deftypefn
ipermute
@c ipermute src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} ipermute (@var{A}, @var{iperm})
The inverse of the @code{permute} function.  The expression

@example
ipermute (permute (A, perm), perm)
@end example

@noindent
returns the original array @var{A}.
@seealso{permute}
@end deftypefn
length
@c length src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} length (@var{a})
Return the "length" of the object @var{a}.  For matrix objects, the
length is the number of rows or columns, whichever is greater (this
odd definition is used for compatibility with @sc{matlab}).
@end deftypefn
ndims
@c ndims src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} ndims (@var{a})
Return the number of dimensions of @var{a}.
For any array, the result will always be larger than or equal to 2.
Trailing singleton dimensions are not counted.

@example
@group
  ndims (ones (4, 1, 2, 1))
     @result{} 3
@end group
@end example
@end deftypefn
numel
@c numel src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} numel (@var{a})
@deftypefnx {Built-in Function} {} numel (@var{a}, @var{idx1}, @var{idx2}, @dots{})
Return the number of elements in the object @var{a}.
Optionally, if indices @var{idx1}, @var{idx2}, @dots{} are supplied,
return the number of elements that would result from the indexing

@example
  @var{a}(@var{idx1}, @var{idx2}, @dots{})
@end example

Note that the indices do not have to be numerical.  For example,

@example
@group
  @var{a} = 1;
  @var{b} = ones (2, 3);
  numel (@var{a}, @var{b});
@end group
@end example

@noindent
will return 6, as this is the number of ways to index with @var{b}.

This method is also called when an object appears as lvalue with cs-list
indexing, i.e., @code{object@{@dots{}@}} or @code{object(@dots{}).field}.
@seealso{size}
@end deftypefn
size
@c size src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} size (@var{a})
@deftypefnx {Built-in Function} {} size (@var{a}, @var{dim})
Return the number of rows and columns of @var{a}.

With one input argument and one output argument, the result is returned
in a row vector.  If there are multiple output arguments, the number of
rows is assigned to the first, and the number of columns to the second,
etc.  For example:

@example
@group
size ([1, 2; 3, 4; 5, 6])
     @result{} [ 3, 2 ]

[nr, nc] = size ([1, 2; 3, 4; 5, 6])
     @result{} nr = 3
     @result{} nc = 2
@end group
@end example

If given a second argument, @code{size} will return the size of the
corresponding dimension.  For example,

@example
@group
size ([1, 2; 3, 4; 5, 6], 2)
     @result{} 2
@end group
@end example

@noindent
returns the number of columns in the given matrix.
@seealso{numel}
@end deftypefn
size_equal
@c size_equal src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} size_equal (@var{a}, @var{b}, @dots{})
Return true if the dimensions of all arguments agree.
Trailing singleton dimensions are ignored.
Called with a single or no argument, size_equal returns true.
@seealso{size, numel}
@end deftypefn
nnz
@c nnz src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {@var{scalar} =} nnz (@var{a})
Return the number of non zero elements in @var{a}.
@seealso{sparse}
@end deftypefn
nzmax
@c nzmax src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {@var{scalar} =} nzmax (@var{SM})
Return the amount of storage allocated to the sparse matrix @var{SM}.
Note that Octave tends to crop unused memory at the first opportunity
for sparse objects.  There are some cases of user created sparse objects
where the value returned by @dfn{nzmax} will not be the same as @dfn{nnz},
but in general they will give the same result.
@seealso{sparse, spalloc}
@end deftypefn
rows
@c rows src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} rows (@var{a})
Return the number of rows of @var{a}.
@seealso{columns, size, length, numel, isscalar, isvector, ismatrix}
@end deftypefn
columns
@c columns src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} columns (@var{a})
Return the number of columns of @var{a}.
@seealso{rows, size, length, numel, isscalar, isvector, ismatrix}
@end deftypefn
sum
@c sum src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} sum (@var{x})
@deftypefnx {Built-in Function} {} sum (@var{x}, @var{dim})
@deftypefnx {Built-in Function} {} sum (@dots{}, 'native')
@deftypefnx {Built-in Function} {} sum (@dots{}, 'double')
@deftypefnx {Built-in Function} {} sum (@dots{}, 'extra')
Sum of elements along dimension @var{dim}.  If @var{dim} is
omitted, it defaults to the first non-singleton dimension.

If the optional argument 'native' is given, then the sum is performed
in the same type as the original argument, rather than in the default
double type.  For example:

@example
@group
sum ([true, true])
  @result{} 2
sum ([true, true], 'native')
  @result{} true
@end group
@end example

On the contrary, if 'double' is given, the sum is performed in double
precision even for single precision inputs.

For double precision inputs, 'extra' indicates that a more accurate algorithm
than straightforward summation is to be used.  For single precision inputs,
'extra' is the same as 'double'.  Otherwise, 'extra' has no effect.
@seealso{cumsum, sumsq, prod}
@end deftypefn
sumsq
@c sumsq src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} sumsq (@var{x})
@deftypefnx {Built-in Function} {} sumsq (@var{x}, @var{dim})
Sum of squares of elements along dimension @var{dim}.  If @var{dim}
is omitted, it defaults to the first non-singleton dimension.

This function is conceptually equivalent to computing

@example
sum (x .* conj (x), dim)
@end example

@noindent
but it uses less memory and avoids calling @code{conj} if @var{x} is real.
@seealso{sum}
@end deftypefn
islogical
@c islogical src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} islogical (@var{x})
@deftypefnx {Built-in Function} {} isbool (@var{x})
Return true if @var{x} is a logical object.
@seealso{isfloat, isinteger, ischar, isnumeric, isa}
@end deftypefn
isinteger
@c isinteger src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isinteger (@var{x})
Return true if @var{x} is an integer object (int8, uint8, int16, etc.).
Note that @w{@code{isinteger (14)}} is false because numeric constants in
Octave are double precision floating point values.
@seealso{isfloat, ischar, islogical, isnumeric, isa}
@end deftypefn
iscomplex
@c iscomplex src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} iscomplex (@var{x})
Return true if @var{x} is a complex-valued numeric object.
@seealso{isreal, isnumeric}
@end deftypefn
isfloat
@c isfloat src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isfloat (@var{x})
Return true if @var{x} is a floating-point numeric object.
Objects of class double or single are floating-point objects.
@seealso{isinteger, ischar, islogical, isnumeric, isa}
@end deftypefn
complex
@c complex src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} complex (@var{x})
@deftypefnx {Built-in Function} {} complex (@var{re}, @var{im})
Return a complex result from real arguments.  With 1 real argument @var{x},
return the complex result @code{@var{x} + 0i}.  With 2 real arguments,
return the complex result @code{@var{re} + @var{im}}.  @code{complex} can
often be more convenient than expressions such as @code{a + i*b}.
For example:

@example
@group
complex ([1, 2], [3, 4])
@result{}
   1 + 3i   2 + 4i
@end group
@end example
@seealso{real, imag, iscomplex}
@end deftypefn
isreal
@c isreal src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isreal (@var{x})
Return true if @var{x} is a non-complex matrix or scalar.
For compatibility with @sc{matlab}, this includes logical and character
matrices.
@seealso{iscomplex, isnumeric}
@end deftypefn
isempty
@c isempty src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isempty (@var{a})
Return true if @var{a} is an empty matrix (any one of its dimensions is
zero).  Otherwise, return false.
@seealso{isnull}
@end deftypefn
isnumeric
@c isnumeric src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isnumeric (@var{x})
Return true if @var{x} is a numeric object, i.e., an integer, real, or
complex array.  Logical and character arrays are not considered to be
numeric.
@seealso{isinteger, isfloat, isreal, iscomplex, islogical, ischar, iscell, isstruct}
@end deftypefn
ismatrix
@c ismatrix src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} ismatrix (@var{a})
Return true if @var{a} is a numeric, logical, or character matrix.
Scalars (1x1 matrices) and vectors (@nospell{1xN} or @nospell{Nx1} matrices)
are subsets of the more general N-dimensional matrix and @code{ismatrix}
will return true for these objects as well.
@seealso{isscalar, isvector, iscell, isstruct, issparse}
@end deftypefn
ones
@c ones src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} ones (@var{n})
@deftypefnx {Built-in Function} {} ones (@var{m}, @var{n})
@deftypefnx {Built-in Function} {} ones (@var{m}, @var{n}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} ones ([@var{m} @var{n} @dots{}])
@deftypefnx {Built-in Function} {} ones (@dots{}, @var{class})
Return a matrix or N-dimensional array whose elements are all 1.
If invoked with a single scalar integer argument @var{n}, return a square
@nospell{NxN} matrix.  If invoked with two or more scalar
integer arguments, or a vector of integer values, return an array with
the given dimensions.

If you need to create a matrix whose values are all the same, you should
use an expression like

@example
val_matrix = val * ones (m, n)
@end example

The optional argument @var{class} specifies the class of the return array
and defaults to double.  For example:

@example
val = ones (m,n, "uint8")
@end example
@seealso{zeros}
@end deftypefn
zeros
@c zeros src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} zeros (@var{n})
@deftypefnx {Built-in Function} {} zeros (@var{m}, @var{n})
@deftypefnx {Built-in Function} {} zeros (@var{m}, @var{n}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} zeros ([@var{m} @var{n} @dots{}])
@deftypefnx {Built-in Function} {} zeros (@dots{}, @var{class})
Return a matrix or N-dimensional array whose elements are all 0.
If invoked with a single scalar integer argument, return a square
@nospell{NxN} matrix.  If invoked with two or more scalar
integer arguments, or a vector of integer values, return an array with
the given dimensions.

The optional argument @var{class} specifies the class of the return array
and defaults to double.  For example:

@example
val = zeros (m,n, "uint8")
@end example
@seealso{ones}
@end deftypefn
Inf
@c Inf src/data.cc
-*- texinfo -*-
@c List other form of function in documentation index
@findex inf

@deftypefn  {Built-in Function} {} Inf
@deftypefnx {Built-in Function} {} Inf (@var{n})
@deftypefnx {Built-in Function} {} Inf (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} Inf (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} Inf (@dots{}, @var{class})
Return a scalar, matrix or N-dimensional array whose elements are all equal
to the IEEE representation for positive infinity.

Infinity is produced when results are too large to be represented using the
the IEEE floating point format for numbers.  Two common examples which
produce infinity are division by zero and overflow.

@example
@group
[1/0 e^800]
@result{}
Inf   Inf
@end group
@end example

When called with no arguments, return a scalar with the value @samp{Inf}.
When called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either "double" or "single".
@seealso{isinf}
@end deftypefn
NaN
@c NaN src/data.cc
-*- texinfo -*-
@c List other form of function in documentation index
@findex nan

@deftypefn  {Built-in Function} {} NaN
@deftypefnx {Built-in Function} {} NaN (@var{n})
@deftypefnx {Built-in Function} {} NaN (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} NaN (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} NaN (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the IEEE symbol NaN (Not a Number).
NaN is the result of operations which do not produce a well defined numerical
result.  Common operations which produce a NaN are arithmetic with infinity
@tex
($\infty - \infty$), zero divided by zero ($0/0$),
@end tex
@ifnottex
(Inf - Inf), zero divided by zero (0/0),
@end ifnottex
and any operation involving another NaN value (5 + NaN).

Note that NaN always compares not equal to NaN (NaN != NaN).  This behavior
is specified by the IEEE standard for floating point arithmetic.  To
find NaN values, use the @code{isnan} function.

When called with no arguments, return a scalar with the value @samp{NaN}.
When called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either "double" or "single".
@seealso{isnan}
@end deftypefn
e
@c e src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} e
@deftypefnx {Built-in Function} {} e (@var{n})
@deftypefnx {Built-in Function} {} e (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} e (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} e (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the base of natural logarithms.  The constant
@tex
$e$ satisfies the equation $\log (e) = 1$.
@end tex
@ifnottex
@samp{e} satisfies the equation @code{log} (e) = 1.
@end ifnottex

When called with no arguments, return a scalar with the value @math{e}.  When
called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either "double" or "single".
@end deftypefn
eps
@c eps src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} eps
@deftypefnx {Built-in Function} {} eps (@var{x})
@deftypefnx {Built-in Function} {} eps (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} eps (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} eps (@dots{}, @var{class})
Return a scalar, matrix or N-dimensional array whose elements are all eps,
the machine precision.  More precisely, @code{eps} is the relative spacing
between any two adjacent numbers in the machine's floating point system.
This number is obviously system dependent.  On machines that support IEEE
floating point arithmetic, @code{eps} is approximately
@tex
$2.2204\times10^{-16}$ for double precision and $1.1921\times10^{-7}$
@end tex
@ifnottex
2.2204e-16 for double precision and 1.1921e-07
@end ifnottex
for single precision.

When called with no arguments, return a scalar with the value
@code{eps(1.0)}.
Given a single argument @var{x}, return the distance between @var{x} and
the next largest value.
When called with more than one argument the first two arguments are taken as
the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either "double" or "single".
@end deftypefn
pi
@c pi src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} pi
@deftypefnx {Built-in Function} {} pi (@var{n})
@deftypefnx {Built-in Function} {} pi (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} pi (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} pi (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the ratio of the circumference of a circle to its
@tex
diameter($\pi$).
@end tex
@ifnottex
diameter.
@end ifnottex
Internally, @code{pi} is computed as @samp{4.0 * atan (1.0)}.

When called with no arguments, return a scalar with the value of
@tex
$\pi$.
@end tex
@ifnottex
pi.
@end ifnottex
When called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either "double" or "single".
@end deftypefn
realmax
@c realmax src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} realmax
@deftypefnx {Built-in Function} {} realmax (@var{n})
@deftypefnx {Built-in Function} {} realmax (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} realmax (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} realmax (@dots{}, @var{class})
Return a scalar, matrix or N-dimensional array whose elements are all equal
to the largest floating point number that is representable.  The actual
value is system dependent.  On machines that support IEEE
floating point arithmetic, @code{realmax} is approximately
@tex
$1.7977\times10^{308}$ for double precision and $3.4028\times10^{38}$
@end tex
@ifnottex
1.7977e+308 for double precision and 3.4028e+38
@end ifnottex
for single precision.

When called with no arguments, return a scalar with the value
@code{realmax("double")}.
When called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either "double" or "single".
@seealso{realmin, intmax, bitmax}
@end deftypefn
realmin
@c realmin src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} realmin
@deftypefnx {Built-in Function} {} realmin (@var{n})
@deftypefnx {Built-in Function} {} realmin (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} realmin (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} realmin (@dots{}, @var{class})
Return a scalar, matrix or N-dimensional array whose elements are all equal
to the smallest normalized floating point number that is representable.
The actual value is system dependent.  On machines that support
IEEE floating point arithmetic, @code{realmin} is approximately
@tex
$2.2251\times10^{-308}$ for double precision and $1.1755\times10^{-38}$
@end tex
@ifnottex
2.2251e-308 for double precision and 1.1755e-38
@end ifnottex
for single precision.

When called with no arguments, return a scalar with the value
@code{realmin("double")}.
When called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either "double" or "single".
@seealso{realmax, intmin}
@end deftypefn
I
@c I src/data.cc
-*- texinfo -*-
@c List other forms of function in documentation index
@findex i
@findex j
@findex J

@deftypefn  {Built-in Function} {} I
@deftypefnx {Built-in Function} {} I (@var{n})
@deftypefnx {Built-in Function} {} I (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} I (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} I (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the pure imaginary unit, defined as
@tex
$\sqrt{-1}$.
@end tex
@ifnottex
@code{sqrt (-1)}.
@end ifnottex
 I, and its equivalents i, J, and j, are functions so any of the names may
be reused for other purposes (such as i for a counter variable).

When called with no arguments, return a scalar with the value @math{i}.  When
called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either "double" or "single".
@end deftypefn
NA
@c NA src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} NA
@deftypefnx {Built-in Function} {} NA (@var{n})
@deftypefnx {Built-in Function} {} NA (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} NA (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} NA (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the special constant used to designate missing values.

Note that NA always compares not equal to NA (NA != NA).
To find NA values, use the @code{isna} function.

When called with no arguments, return a scalar with the value @samp{NA}.
When called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either "double" or "single".
@seealso{isna}
@end deftypefn
false
@c false src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} false (@var{x})
@deftypefnx {Built-in Function} {} false (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} false (@var{n}, @var{m}, @var{k}, @dots{})
Return a matrix or N-dimensional array whose elements are all logical 0.
If invoked with a single scalar integer argument, return a square
matrix of the specified size.  If invoked with two or more scalar
integer arguments, or a vector of integer values, return an array with
given dimensions.
@seealso{true}
@end deftypefn
true
@c true src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} true (@var{x})
@deftypefnx {Built-in Function} {} true (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} true (@var{n}, @var{m}, @var{k}, @dots{})
Return a matrix or N-dimensional array whose elements are all logical 1.
If invoked with a single scalar integer argument, return a square
matrix of the specified size.  If invoked with two or more scalar
integer arguments, or a vector of integer values, return an array with
given dimensions.
@seealso{false}
@end deftypefn
eye
@c eye src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} eye (@var{n})
@deftypefnx {Built-in Function} {} eye (@var{m}, @var{n})
@deftypefnx {Built-in Function} {} eye ([@var{m} @var{n}])
@deftypefnx {Built-in Function} {} eye (@dots{}, @var{class})
Return an identity matrix.  If invoked with a single scalar argument @var{n},
return a square @nospell{NxN} identity matrix.  If
supplied two scalar arguments (@var{m}, @var{n}), @code{eye} takes them to be
the number of rows and columns.  If given a vector with two elements,
@code{eye} uses the values of the elements as the number of rows and columns,
respectively.  For example:

@example
@group
eye (3)
     @result{}  1  0  0
         0  1  0
         0  0  1
@end group
@end example

The following expressions all produce the same result:

@example
@group
eye (2)
@equiv{}
eye (2, 2)
@equiv{}
eye (size ([1, 2; 3, 4])
@end group
@end example

The optional argument @var{class}, allows @code{eye} to return an array of
the specified type, like

@example
val = zeros (n,m, "uint8")
@end example

Calling @code{eye} with no arguments is equivalent to calling it
with an argument of 1.  Any negative dimensions are treated as zero. 
These odd definitions are for compatibility with @sc{matlab}.
@seealso{speye}
@end deftypefn
linspace
@c linspace src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} linspace (@var{base}, @var{limit})
@deftypefnx {Built-in Function} {} linspace (@var{base}, @var{limit}, @var{n})
Return a row vector with @var{n} linearly spaced elements between
@var{base} and @var{limit}.  If the number of elements is greater than one,
then the endpoints @var{base} and @var{limit} are always included in
the range.  If @var{base} is greater than @var{limit}, the elements are
stored in decreasing order.  If the number of points is not specified, a
value of 100 is used.

The @code{linspace} function always returns a row vector if both
@var{base} and @var{limit} are scalars.  If one, or both, of them are column
vectors, @code{linspace} returns a matrix.

For compatibility with @sc{matlab}, return the second argument (@var{limit})
if fewer than two values are requested.
@end deftypefn
resize
@c resize src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} resize (@var{x}, @var{m})
@deftypefnx {Built-in Function} {} resize (@var{x}, @var{m}, @var{n}, @dots{})
@deftypefnx {Built-in Function} {} resize (@var{x}, [@var{m} @var{n} @dots{}])
Resize @var{x} cutting off elements as necessary.

In the result, element with certain indices is equal to the corresponding
element of @var{x} if the indices are within the bounds of @var{x};
otherwise, the element is set to zero.

In other words, the statement

@example
  y = resize (x, dv);
@end example

@noindent
is equivalent to the following code:

@example
@group
  y = zeros (dv, class (x));
  sz = min (dv, size (x));
  for i = 1:length (sz), idx@{i@} = 1:sz(i); endfor
  y(idx@{:@}) = x(idx@{:@});
@end group
@end example

@noindent
but is performed more efficiently.

If only @var{m} is supplied, and it is a scalar, the dimension of the
result is @var{m}-by-@var{m}.
If @var{m}, @var{n}, @dots{} are all scalars, then the dimensions of
the result are @var{m}-by-@var{n}-by-@dots{}.
If given a vector as input, then the
dimensions of the result are given by the elements of that vector.

An object can be resized to more dimensions than it has;
in such case the missing dimensions are assumed to be 1.
Resizing an object to fewer dimensions is not possible.
@seealso{reshape, postpad}
@end deftypefn
reshape
@c reshape src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} reshape (@var{A}, @var{m}, @var{n}, @dots{})
@deftypefnx {Built-in Function} {} reshape (@var{A}, [@var{m} @var{n} @dots{}])
@deftypefnx {Built-in Function} {} reshape (@var{A}, @dots{}, [], @dots{})
@deftypefnx {Built-in Function} {} reshape (@var{A}, @var{size})
Return a matrix with the specified dimensions (@var{m}, @var{n}, @dots{})
whose elements are taken from the matrix @var{A}.  The elements of the
matrix are accessed in column-major order (like Fortran arrays are stored).

The following code demonstrates reshaping a 1x4 row vector into a 2x2 square
matrix.

@example
@group
reshape ([1, 2, 3, 4], 2, 2)
     @result{}  1  3
         2  4
@end group
@end example

@noindent
Note that the total number of elements in the original
matrix (@code{prod (size (@var{A}))}) must match the total number of elements
in the new matrix (@code{prod ([@var{m} @var{n} @dots{}])}).

A single dimension of the return matrix may be left unspecified and Octave
will determine its size automatically.  An empty matrix ([]) is used to flag
the unspecified dimension.
@seealso{resize}
@end deftypefn
vec
@c vec src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{v} =} vec (@var{x})
@deftypefnx {Built-in Function} {@var{v} =} vec (@var{x}, @var{dim})
Return the vector obtained by stacking the columns of the matrix @var{x}
one above the other.  Without @var{dim} this is equivalent to
@code{@var{x}(:)}.  If @var{dim} is supplied, the dimensions of @var{v}
are set to @var{dim} with all elements along the last dimension.
This is equivalent to @code{shiftdim (@var{x}(:), 1-@var{dim})}.
@seealso{vech}
@end deftypefn
squeeze
@c squeeze src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} squeeze (@var{x})
Remove singleton dimensions from @var{x} and return the result.
Note that for compatibility with @sc{matlab}, all objects have
a minimum of two dimensions and row vectors are left unchanged.
@end deftypefn
full
@c full src/data.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{FM} =} full (@var{SM})
Return a full storage matrix from a sparse, diagonal, permutation matrix
or a range.
@seealso{sparse}
@end deftypefn
norm
@c norm src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} norm (@var{A})
@deftypefnx {Built-in Function} {} norm (@var{A}, @var{p})
@deftypefnx {Built-in Function} {} norm (@var{A}, @var{p}, @var{opt})
Compute the p-norm of the matrix @var{A}.  If the second argument is
missing, @code{p = 2} is assumed.

If @var{A} is a matrix (or sparse matrix):

@table @asis
@item @var{p} = @code{1}
1-norm, the largest column sum of the absolute values of @var{A}.

@item @var{p} = @code{2}
Largest singular value of @var{A}.

@item @var{p} = @code{Inf} or @code{"inf"}
@cindex infinity norm
Infinity norm, the largest row sum of the absolute values of @var{A}.

@item @var{p} = @code{"fro"}
@cindex Frobenius norm
Frobenius norm of @var{A}, @code{sqrt (sum (diag (@var{A}' * @var{A})))}.

@item other @var{p}, @code{@var{p} > 1}
@cindex general p-norm
maximum @code{norm (A*x, p)} such that @code{norm (x, p) == 1}
@end table

If @var{A} is a vector or a scalar:

@table @asis
@item @var{p} = @code{Inf} or @code{"inf"}
@code{max (abs (@var{A}))}.

@item @var{p} = @code{-Inf}
@code{min (abs (@var{A}))}.

@item @var{p} = @code{"fro"}
Frobenius norm of @var{A}, @code{sqrt (sumsq (abs (A)))}.

@item @var{p} = 0
Hamming norm - the number of nonzero elements.

@item other @var{p}, @code{@var{p} > 1}
p-norm of @var{A}, @code{(sum (abs (@var{A}) .^ @var{p})) ^ (1/@var{p})}.

@item other @var{p} @code{@var{p} < 1}
the p-pseudonorm defined as above.
@end table

If @var{opt} is the value @code{"rows"}, treat each row as a vector and
compute its norm.  The result is returned as a column vector.
Similarly, if @var{opt} is @code{"columns"} or @code{"cols"} then compute
the norms of each column and return a row vector.
@seealso{cond, svd}
@end deftypefn
not
@c not src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} not (@var{x})
Return the logical NOT of @var{x}.  This function is equivalent to
@code{! x}.
@seealso{and, or, xor}
@end deftypefn
uplus
@c uplus src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} uplus (@var{x})
This function and @w{@xcode{+ x}} are equivalent.
@end deftypefn
uminus
@c uminus src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} uminus (@var{x})
This function and @w{@xcode{- x}} are equivalent.
@end deftypefn
transpose
@c transpose src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} transpose (@var{x})
Return the transpose of @var{x}.
This function and @xcode{x.'} are equivalent.
@seealso{ctranspose}
@end deftypefn
ctranspose
@c ctranspose src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} ctranspose (@var{x})
Return the complex conjugate transpose of @var{x}.
This function and @xcode{x'} are equivalent.
@seealso{transpose}
@end deftypefn
plus
@c plus src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} plus (@var{x}, @var{y})
@deftypefnx {Built-in Function} {} plus (@var{x1}, @var{x2}, @dots{})
This function and @w{@xcode{x + y}} are equivalent.
If more arguments are given, the summation is applied
cumulatively from left to right:

@example
  (@dots{}((x1 + x2) + x3) + @dots{})
@end example

At least one argument is required.
@seealso{minus}
@end deftypefn
minus
@c minus src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} minus (@var{x}, @var{y})
This function and @w{@xcode{x - y}} are equivalent.
@seealso{plus}
@end deftypefn
mtimes
@c mtimes src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} mtimes (@var{x}, @var{y})
@deftypefnx {Built-in Function} {} mtimes (@var{x1}, @var{x2}, @dots{})
Return the matrix multiplication product of inputs.
This function and @w{@xcode{x * y}} are equivalent.
If more arguments are given, the multiplication is applied
cumulatively from left to right:

@example
  (@dots{}((x1 * x2) * x3) * @dots{})
@end example

At least one argument is required.
@seealso{times}
@end deftypefn
mrdivide
@c mrdivide src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} mrdivide (@var{x}, @var{y})
Return the matrix right division of @var{x} and @var{y}.
This function and @w{@xcode{x / y}} are equivalent.
@seealso{mldivide, rdivide}
@end deftypefn
mpower
@c mpower src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} mpower (@var{x}, @var{y})
Return the matrix power operation of @var{x} raised to the @var{y} power.
This function and @w{@xcode{x ^ y}} are equivalent.
@seealso{power}
@end deftypefn
mldivide
@c mldivide src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} mldivide (@var{x}, @var{y})
Return the matrix left division of @var{x} and @var{y}.
This function and @w{@xcode{x \ y}} are equivalent.
@seealso{mrdivide, ldivide}
@end deftypefn
lt
@c lt src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} lt (@var{x}, @var{y})
This function is equivalent to @w{@code{x < y}}.
@end deftypefn
le
@c le src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} le (@var{x}, @var{y})
This function is equivalent to @w{@code{x <= y}}.
@end deftypefn
eq
@c eq src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} eq (@var{x}, @var{y})
Return true if the two inputs are equal.
This function is equivalent to @w{@code{x == y}}.
@seealso{ne, isequal}
@end deftypefn
ge
@c ge src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} ge (@var{x}, @var{y})
This function is equivalent to @w{@code{x >= y}}.
@end deftypefn
gt
@c gt src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} gt (@var{x}, @var{y})
This function is equivalent to @w{@code{x > y}}.
@end deftypefn
ne
@c ne src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} ne (@var{x}, @var{y})
Return true if the two inputs are not equal.
This function is equivalent to @w{@code{x != y}}.
@seealso{eq, isequal}
@end deftypefn
times
@c times src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} times (@var{x}, @var{y})
@deftypefnx {Built-in Function} {} times (@var{x1}, @var{x2}, @dots{})
Return the element-by-element multiplication product of inputs.
This function and @w{@xcode{x .* y}} are equivalent.
If more arguments are given, the multiplication is applied
cumulatively from left to right:

@example
  (@dots{}((x1 .* x2) .* x3) .* @dots{})
@end example

At least one argument is required.
@seealso{mtimes}
@end deftypefn
rdivide
@c rdivide src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} rdivide (@var{x}, @var{y})
Return the element-by-element right division of @var{x} and @var{y}.
This function and @w{@xcode{x ./ y}} are equivalent.
@seealso{ldivide, mrdivide}
@end deftypefn
power
@c power src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} power (@var{x}, @var{y})
Return the element-by-element operation of @var{x} raised to the
@var{y} power.  If several complex results are possible,
returns the one with smallest non-negative argument (angle).  Use
@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a
real result is preferred.

This function and @w{@xcode{x .^ y}} are equivalent.
@seealso{mpower, realpow, realsqrt, cbrt, nthroot}
@end deftypefn
ldivide
@c ldivide src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} ldivide (@var{x}, @var{y})
Return the element-by-element left division of @var{x} and @var{y}.
This function and @w{@xcode{x .\ y}} are equivalent.
@seealso{rdivide, mldivide}
@end deftypefn
and
@c and src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} and (@var{x}, @var{y})
@deftypefnx {Built-in Function} {} and (@var{x1}, @var{x2}, @dots{})
Return the logical AND of @var{x} and @var{y}.
This function is equivalent to @w{@code{x & y}}.
If more arguments are given, the logical and is applied
cumulatively from left to right:

@example
  (@dots{}((x1 & x2) & x3) & @dots{})
@end example

At least one argument is required.
@seealso{or, not, xor}
@end deftypefn
or
@c or src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} or (@var{x}, @var{y})
@deftypefnx {Built-in Function} {} or (@var{x1}, @var{x2}, @dots{})
Return the logical OR of @var{x} and @var{y}.
This function is equivalent to @w{@code{x | y}}.
If more arguments are given, the logical or is applied
cumulatively from left to right:

@example
  (@dots{}((x1 | x2) | x3) | @dots{})
@end example

At least one argument is required.
@seealso{and, not, xor}
@end deftypefn
tic
@c tic src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} tic ()
@deftypefnx {Built-in Function} {} toc ()
Set or check a wall-clock timer.  Calling @code{tic} without an
output argument sets the timer.  Subsequent calls to @code{toc}
return the number of seconds since the timer was set.  For example,

@example
@group
tic ();
# many computations later@dots{}
elapsed_time = toc ();
@end group
@end example

@noindent
will set the variable @code{elapsed_time} to the number of seconds since
the most recent call to the function @code{tic}.

If called with one output argument then this function returns a scalar
of type @code{uint64} and the wall-clock timer is not started.

@example
@group
t = tic; sleep (5); (double (tic ()) - double (t)) * 1e-6
     @result{} 5
@end group
@end example

Nested timing with @code{tic} and @code{toc} is not supported.
Therefore @code{toc} will always return the elapsed time from the most
recent call to @code{tic}.

If you are more interested in the CPU time that your process used, you
should use the @code{cputime} function instead.  The @code{tic} and
@code{toc} functions report the actual wall clock time that elapsed
between the calls.  This may include time spent processing other jobs or
doing nothing at all.  For example:

@example
@group
tic (); sleep (5); toc ()
     @result{} 5
t = cputime (); sleep (5); cputime () - t
     @result{} 0
@end group
@end example

@noindent
(This example also illustrates that the CPU timer may have a fairly
coarse resolution.)
@end deftypefn
toc
@c toc src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} toc ()
See tic.
@end deftypefn
cputime
@c cputime src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{total}, @var{user}, @var{system}] =} cputime ();
Return the CPU time used by your Octave session.  The first output is
the total time spent executing your process and is equal to the sum of
second and third outputs, which are the number of CPU seconds spent
executing in user mode and the number of CPU seconds spent executing in
system mode, respectively.  If your system does not have a way to report
CPU time usage, @code{cputime} returns 0 for each of its output values.
Note that because Octave used some CPU time to start, it is reasonable
to check to see if @code{cputime} works by checking to see if the total
CPU time used is nonzero.
@end deftypefn
sort
@c sort src/data.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x})
@deftypefnx {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim})
@deftypefnx {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x}, @var{mode})
@deftypefnx {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim}, @var{mode})
Return a copy of @var{x} with the elements arranged in increasing
order.  For matrices, @code{sort} orders the elements within columns

For example:

@example
@group
sort ([1, 2; 2, 3; 3, 1])
     @result{}  1  1
         2  2
         3  3
@end group
@end example

If the optional argument @var{dim} is given, then the matrix is sorted
along the dimension defined by @var{dim}.  The optional argument @code{mode}
defines the order in which the values will be sorted.  Valid values of
@code{mode} are `ascend' or `descend'.

The @code{sort} function may also be used to produce a matrix
containing the original row indices of the elements in the sorted
matrix.  For example:

@example
@group
[s, i] = sort ([1, 2; 2, 3; 3, 1])
     @result{} s = 1  1
            2  2
            3  3
     @result{} i = 1  3
            2  1
            3  2
@end group
@end example

For equal elements, the indices are such that equal elements are listed
in the order in which they appeared in the original list.

Sorting of complex entries is done first by magnitude (@code{abs (@var{z})})
and for any ties by phase angle (@code{angle (z)}).  For example:

@example
@group
sort ([1+i; 1; 1-i])
     @result{} 1 + 0i
        1 - 1i
        1 + 1i
@end group
@end example

NaN values are treated as being greater than any other value and are sorted
to the end of the list.

The @code{sort} function may also be used to sort strings and cell arrays
of strings, in which case ASCII dictionary order (uppercase 'A' precedes
lowercase 'a') of the strings is used.

The algorithm used in @code{sort} is optimized for the sorting of partially
ordered lists.
@end deftypefn
__sort_rows_idx__
@c __sort_rows_idx__ src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __sort_rows_idx__ (@var{a}, @var{mode})
Undocumented internal function.
@end deftypefn

issorted
@c issorted src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} issorted (@var{a})
@deftypefnx {Built-in Function} {} issorted (@var{a}, @var{mode})
@deftypefnx {Built-in Function} {} issorted (@var{a}, "rows", @var{mode})
Return true if the array is sorted according to @var{mode}, which
may be either "ascending", "descending", or "either".  By default,
 @var{mode} is "ascending".  NaNs are treated in the same manner as
@code{sort}.

If the optional argument "rows" is supplied, check whether
the array is sorted by rows as output by the function @code{sortrows}
(with no options).

This function does not support sparse matrices.
@seealso{sort, sortrows}
@end deftypefn

nth_element
@c nth_element src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} nth_element (@var{x}, @var{n})
@deftypefnx {Built-in Function} {} nth_element (@var{x}, @var{n}, @var{dim})
Select the n-th smallest element of a vector, using the ordering defined by
@code{sort}.  In other words, the result is equivalent to
@code{sort(@var{x})(@var{n})}.
@var{n} can also be a contiguous range, either ascending @code{l:u}
or descending @code{u:-1:l}, in which case a range of elements is returned.
If @var{x} is an array, @code{nth_element} operates along the dimension
defined by @var{dim}, or the first non-singleton dimension if @var{dim} is
not given.

nth_element encapsulates the C++ standard library algorithms nth_element and
partial_sort.  On average, the complexity of the operation is O(M*log(K)),
where @w{@code{M = size (@var{x}, @var{dim})}} and
@w{@code{K = length (@var{n})}}.
This function is intended for cases where the ratio K/M is small; otherwise,
it may be better to use @code{sort}.
@seealso{sort, min, max}
@end deftypefn
__accumarray_sum__
@c __accumarray_sum__ src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __accumarray_sum__ (@var{idx}, @var{vals}, @var{n})
Undocumented internal function.
@end deftypefn
__accumarray_min__
@c __accumarray_min__ src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __accumarray_min__ (@var{idx}, @var{vals}, @var{zero}, @var{n})
Undocumented internal function.
@end deftypefn
__accumarray_max__
@c __accumarray_max__ src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __accumarray_max__ (@var{idx}, @var{vals}, @var{zero}, @var{n})
Undocumented internal function.
@end deftypefn
__accumdim_sum__
@c __accumdim_sum__ src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __accumdim_sum__ (@var{idx}, @var{vals}, @var{dim}, @var{n})
Undocumented internal function.
@end deftypefn
merge
@c merge src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} merge (@var{mask}, @var{tval}, @var{fval})
@deftypefnx {Built-in Function} {} ifelse (@var{mask}, @var{tval}, @var{fval})
Merge elements of @var{true_val} and @var{false_val}, depending on the
value of @var{mask}.  If @var{mask} is a logical scalar, the other two
arguments can be arbitrary values.  Otherwise, @var{mask} must be a logical
array, and @var{tval}, @var{fval} should be arrays of matching class, or
cell arrays.  In the scalar mask case, @var{tval} is returned if @var{mask}
is true, otherwise @var{fval} is returned.

In the array mask case, both @var{tval} and @var{fval} must be either
scalars or arrays with dimensions equal to @var{mask}.  The result is
constructed as follows:

@example
@group
result(mask) = tval(mask);
result(! mask) = fval(! mask);
@end group
@end example

@var{mask} can also be arbitrary numeric type, in which case
it is first converted to logical.
@seealso{logical}
@end deftypefn
diff
@c diff src/data.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} diff (@var{x})
@deftypefnx {Built-in Function} {} diff (@var{x}, @var{k})
@deftypefnx {Built-in Function} {} diff (@var{x}, @var{k}, @var{dim})
If @var{x} is a vector of length @math{n}, @code{diff (@var{x})} is the
vector of first differences
@tex
 $x_2 - x_1, \ldots{}, x_n - x_{n-1}$.
@end tex
@ifnottex
 @var{x}(2) - @var{x}(1), @dots{}, @var{x}(n) - @var{x}(n-1).
@end ifnottex

If @var{x} is a matrix, @code{diff (@var{x})} is the matrix of column
differences along the first non-singleton dimension.

The second argument is optional.  If supplied, @code{diff (@var{x},
@var{k})}, where @var{k} is a non-negative integer, returns the
@var{k}-th differences.  It is possible that @var{k} is larger than
the first non-singleton dimension of the matrix.  In this case,
@code{diff} continues to take the differences along the next
non-singleton dimension.

The dimension along which to take the difference can be explicitly
stated with the optional variable @var{dim}.  In this case the
@var{k}-th order differences are calculated along this dimension.
In the case where @var{k} exceeds @code{size (@var{x}, @var{dim})}
an empty matrix is returned.
@end deftypefn
repelems
@c repelems src/data.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} repelems (@var{x}, @var{r})
Construct a vector of repeated elements from @var{x}.  @var{r}
is a 2x@var{N} integer matrix specifying which elements to repeat and
how often to repeat each element.

Entries in the first row, @var{r}(1,j), select an element to repeat.
The corresponding entry in the second row, @var{r}(2,j), specifies
the repeat count.  If @var{x} is a matrix then the columns of @var{x} are
imagined to be stacked on top of each other for purposes of the selection
index.  A row vector is always returned.

Conceptually the result is calculated as follows:

@example
@group
y = [];
for i = 1:columns (@var{r})
  y = [y, @var{x}(@var{r}(1,i)*ones(1, @var{r}(2,i)))];
endfor
@end group
@end example
@seealso{repmat}
@end deftypefn
dbstop
@c dbstop src/debug.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{rline} =} dbstop ("@var{func}")
@deftypefnx {Loadable Function} {@var{rline} =} dbstop ("@var{func}", @var{line}, @dots{})
Set a breakpoint in function @var{func}.

Arguments are

@table @var
@item func
Function name as a string variable.  When already in debug
mode this should be left out and only the line should be given.

@item line
Line number where the breakpoint should be set.  Multiple
lines may be given as separate arguments or as a vector.
@end table

When called with a single argument @var{func}, the breakpoint
is set at the first executable line in the named function.

The optional output @var{rline} is the real line number where the
breakpoint was set.  This can differ from specified line if
the line is not executable.  For example, if a breakpoint attempted on a
blank line then Octave will set the real breakpoint at the
next executable line.
@seealso{dbclear, dbstatus, dbstep, debug_on_error, debug_on_warning, debug_on_interrupt}
@end deftypefn
dbclear
@c dbclear src/debug.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} dbclear ("@var{func}")
@deftypefnx {Loadable Function} {} dbclear ("@var{func}", @var{line}, @dots{})
Delete a breakpoint in the function @var{func}.

Arguments are

@table @var
@item func
Function name as a string variable.  When already in debug
mode this should be left out and only the line should be given.

@item line
Line number from which to remove a breakpoint.  Multiple
lines may be given as separate arguments or as a vector.
@end table

When called without a line number specification all breakpoints
in the named function are cleared.

If the requested line is not a breakpoint no action is performed.
@seealso{dbstop, dbstatus, dbwhere}
@end deftypefn
dbstatus
@c dbstatus src/debug.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} dbstatus ()
@deftypefnx {Loadable Function} {@var{brk_list} =} dbstatus ()
@deftypefnx {Loadable Function} {@var{brk_list} =} dbstatus ("@var{func}")
Report the location of active breakpoints.

When called with no input or output arguments, print the list of
all functions with breakpoints and the line numbers where those
breakpoints are set.
If a function name @var{func} is specified then only report breakpoints
for the named function.

The optional return argument @var{brk_list} is a struct array with the
following fields.

@table @asis
@item name
The name of the function with a breakpoint.

@item file
The name of the m-file where the function code is located.

@item line
A line number, or vector of line numbers, with a breakpoint.
@end table

@seealso{dbclear, dbwhere}
@end deftypefn
dbwhere
@c dbwhere src/debug.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} dbwhere ()
In debugging mode, report the current file and line number where
execution is stopped.
@seealso{dbstatus, dbcont, dbstep, dbup}
@end deftypefn
dbtype
@c dbtype src/debug.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} dbtype ()
@deftypefnx {Loadable Function} {} dbtype ("startl:endl")
@deftypefnx {Loadable Function} {} dbtype ("@var{func}")
@deftypefnx {Loadable Function} {} dbtype ("@var{func}", "startl:endl")
When in debugging mode and called with no arguments, list the script file
being debugged with line numbers.  An optional range specification,
specified as a string, can be used to list only a portion of the file.

When called with the name of a function, list that script file
with line numbers.
@seealso{dbstatus, dbstop}
@end deftypefn
dbstack
@c dbstack src/debug.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} dbstack ()
@deftypefnx {Loadable Function} {} dbstack (@var{n})
@deftypefnx {Loadable Function} {[@var{stack}, @var{idx}] =} dbstack (@dots{})
Display or return current debugging function stack information.
With optional argument @var{n}, omit the @var{n} innermost stack frames.

The optional return argument @var{stack} is a struct array with the
following fields:

@table @asis
@item file
The name of the m-file where the function code is located.

@item name
The name of the function with a breakpoint.

@item line
The line number of an active breakpoint.

@item column
The column number of the line where the breakpoint begins.

@item scope
Undocumented.

@item context
Undocumented.
@end table

The return argument @var{idx} specifies which element of the @var{stack}
struct array is currently active.
@seealso{dbup, dbdown, dbwhere, dbstatus}
@end deftypefn
dbup
@c dbup src/debug.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} dbup
@deftypefnx {Loadable Function} {} dbup (@var{n})
In debugging mode, move up the execution stack @var{n} frames.
If @var{n} is omitted, move up one frame.
@seealso{dbstack, dbdown}
@end deftypefn
dbdown
@c dbdown src/debug.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} dbdown
@deftypefnx {Loadable Function} {} dbdown (@var{n})
In debugging mode, move down the execution stack @var{n} frames.
If @var{n} is omitted, move down one frame.
@seealso{dbstack, dbup}
@end deftypefn
dbstep
@c dbstep src/debug.cc
-*- texinfo -*-
@deftypefn  {Command} {} dbstep
@deftypefnx {Command} {} dbstep @var{n}
@deftypefnx {Command} {} dbstep in
@deftypefnx {Command} {} dbstep out
@deftypefnx {Command} {} dbnext @dots{}
In debugging mode, execute the next @var{n} lines of code.
If @var{n} is omitted, execute the next single line of code.
If the next line of code is itself defined in terms of an m-file remain in
the existing function.

Using @code{dbstep in} will cause execution of the next line to step into
any m-files defined on the next line.  Using @code{dbstep out} will cause
execution to continue until the current function returns.

@code{dbnext} is an alias for @code{dbstep}.
@seealso{dbcont, dbquit}
@end deftypefn
dbcont
@c dbcont src/debug.cc
-*- texinfo -*-
@deftypefn {Command} {} dbcont
Leave command-line debugging mode and continue code execution normally.
@seealso{dbstep, dbquit}
@end deftypefn
dbquit
@c dbquit src/debug.cc
-*- texinfo -*-
@deftypefn {Command} {} dbquit
Quit debugging mode immediately without further code execution and
return to the Octave prompt.
@seealso{dbcont, dbstep}
@end deftypefn
isdebugmode
@c isdebugmode src/debug.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} isdebugmode ()
Return true if in debugging mode, otherwise false.
@seealso{dbwhere, dbstack, dbstatus}
@end deftypefn
EDITOR
@c EDITOR src/defaults.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} EDITOR ()
@deftypefnx {Built-in Function} {@var{old_val} =} EDITOR (@var{new_val})
@deftypefnx {Built-in Function} {} EDITOR (@var{new_val}, "local")
Query or set the internal variable that specifies the editor to
use with the @code{edit_history} command.  The default value is taken from
the environment variable @w{@env{EDITOR}} when Octave starts.  If the
environment variable is not initialized, @w{@env{EDITOR}} will be set to
@code{"emacs"}.

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.
@seealso{edit_history}
@end deftypefn
EXEC_PATH
@c EXEC_PATH src/defaults.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} EXEC_PATH ()
@deftypefnx {Built-in Function} {@var{old_val} =} EXEC_PATH (@var{new_val})
@deftypefnx {Built-in Function} {} EXEC_PATH (@var{new_val}, "local")
Query or set the internal variable that specifies a colon separated
list of directories to append to the shell PATH when executing external
programs.  The initial value of is taken from the environment variable
@w{@env{OCTAVE_EXEC_PATH}}, but that value can be overridden by
the command line argument @option{--exec-path PATH}.

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.
@end deftypefn
IMAGE_PATH
@c IMAGE_PATH src/defaults.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} IMAGE_PATH ()
@deftypefnx {Built-in Function} {@var{old_val} =} IMAGE_PATH (@var{new_val})
@deftypefnx {Built-in Function} {} IMAGE_PATH (@var{new_val}, "local")
Query or set the internal variable that specifies a colon separated
list of directories in which to search for image files.

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.
@end deftypefn
OCTAVE_HOME
@c OCTAVE_HOME src/defaults.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} OCTAVE_HOME ()
Return the name of the top-level Octave installation directory.
@end deftypefn
OCTAVE_VERSION
@c OCTAVE_VERSION src/defaults.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} OCTAVE_VERSION ()
Return the version number of Octave, as a string.
@end deftypefn
cd
@c cd src/dirfns.cc
-*- texinfo -*-
@deftypefn  {Command} {} cd dir
@deftypefnx {Command} {} chdir dir
Change the current working directory to @var{dir}.  If @var{dir} is
omitted, the current directory is changed to the user's home
directory.  For example,

@example
cd ~/octave
@end example

@noindent
changes the current working directory to @file{~/octave}.  If the
directory does not exist, an error message is printed and the working
directory is not changed.
@seealso{mkdir, rmdir, dir}
@end deftypefn
pwd
@c pwd src/dirfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} pwd ()
Return the current working directory.
@seealso{dir, ls}
@end deftypefn
readdir
@c readdir src/dirfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{files}, @var{err}, @var{msg}] =} readdir (@var{dir})
Return names of the files in the directory @var{dir} as a cell array of
strings.  If an error occurs, return an empty cell array in @var{files}.

If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a
system-dependent error message.
@seealso{ls, dir, glob}
@end deftypefn
mkdir
@c mkdir src/dirfns.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {[@var{status}, @var{msg}, @var{msgid}] =} mkdir (@var{dir})
@deftypefnx {Built-in Function} {[@var{status}, @var{msg}, @var{msgid}] =} mkdir (@var{parent}, @var{dir})
Create a directory named @var{dir} in the directory @var{parent}.

If successful, @var{status} is 1, with @var{msg} and @var{msgid} empty
character strings.  Otherwise, @var{status} is 0, @var{msg} contains a
system-dependent error message, and @var{msgid} contains a unique
message identifier.
@seealso{rmdir}
@end deftypefn
rmdir
@c rmdir src/dirfns.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {[@var{status}, @var{msg}, @var{msgid}] =} rmdir (@var{dir})
@deftypefnx {Built-in Function} {[@var{status}, @var{msg}, @var{msgid}] =} rmdir (@var{dir}, "s")
Remove the directory named @var{dir}.

If successful, @var{status} is 1, with @var{msg} and @var{msgid} empty
character strings.  Otherwise, @var{status} is 0, @var{msg} contains a
system-dependent error message, and @var{msgid} contains a unique
message identifier.

If the optional second parameter is supplied with value @code{"s"},
recursively remove all subdirectories as well.
@seealso{mkdir, confirm_recursive_rmdir}
@end deftypefn
link
@c link src/dirfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} link (@var{old}, @var{new})
Create a new link (also known as a hard link) to an existing file.

If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a
system-dependent error message.
@seealso{symlink}
@end deftypefn
symlink
@c symlink src/dirfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} symlink (@var{old}, @var{new})
Create a symbolic link @var{new} which contains the string @var{old}.

If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a
system-dependent error message.
@seealso{link, readlink}
@end deftypefn
readlink
@c readlink src/dirfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{result}, @var{err}, @var{msg}] =} readlink (@var{symlink})
Read the value of the symbolic link @var{symlink}.

If successful, @var{result} contains the contents of the symbolic link
@var{symlink}, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a
system-dependent error message.
@seealso{link, symlink}
@end deftypefn
rename
@c rename src/dirfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} rename (@var{old}, @var{new})
Change the name of file @var{old} to @var{new}.

If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a
system-dependent error message.
@seealso{ls, dir}
@end deftypefn
glob
@c glob src/dirfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} glob (@var{pattern})
Given an array of pattern strings (as a char array or a cell array) in
@var{pattern}, return a cell array of file names that match any of
them, or an empty cell array if no patterns match.  The pattern strings are
interpreted as filename globbing patterns (as they are used by Unix shells).
Within a pattern
@table @code
@itemx *
matches any string, including the null string,
@itemx ?
matches any single character, and

@item [@dots{}]
matches any of the enclosed characters.
@end table

Tilde expansion
is performed on each of the patterns before looking for matching file
names.  For example:

@example
ls
     @result{}
        file1  file2  file3  myfile1 myfile1b
glob ("*file1")
     @result{}
        @{
          [1,1] = file1
          [2,1] = myfile1
        @}
glob ("myfile?")
     @result{}
        @{
          [1,1] = myfile1
        @}
glob ("file[12]")
     @result{}
        @{
          [1,1] = file1
          [2,1] = file2
        @}
@end example
@seealso{ls, dir, readdir}
@end deftypefn
fnmatch
@c fnmatch src/dirfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} fnmatch (@var{pattern}, @var{string})
Return 1 or zero for each element of @var{string} that matches any of
the elements of the string array @var{pattern}, using the rules of
filename pattern matching.  For example:

@example
@group
fnmatch ("a*b", @{"ab"; "axyzb"; "xyzab"@})
     @result{} [ 1; 1; 0 ]
@end group
@end example
@end deftypefn
filesep
@c filesep src/dirfns.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} filesep ()
@deftypefnx {Built-in Function} {} filesep ('all')
Return the system-dependent character used to separate directory names.

If 'all' is given, the function returns all valid file separators in
the form of a string.  The list of file separators is system-dependent.
It is @samp{/} (forward slash) under UNIX or @w{Mac OS X}, @samp{/} and
@samp{\} (forward and backward slashes) under Windows.
@seealso{pathsep}
@end deftypefn
pathsep
@c pathsep src/dirfns.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} pathsep ()
@deftypefnx {Built-in Function} {@var{old_val} =} pathsep (@var{new_val})
Query or set the character used to separate directories in a path.
@seealso{filesep}
@end deftypefn
confirm_recursive_rmdir
@c confirm_recursive_rmdir src/dirfns.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} confirm_recursive_rmdir ()
@deftypefnx {Built-in Function} {@var{old_val} =} confirm_recursive_rmdir (@var{new_val})
@deftypefnx {Built-in Function} {} confirm_recursive_rmdir (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave
will ask for confirmation before recursively removing a directory tree.

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.
@end deftypefn
rethrow
@c rethrow src/error.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} rethrow (@var{err})
Reissue a previous error as defined by @var{err}.  @var{err} is a structure
that must contain at least the 'message' and 'identifier' fields.  @var{err}
can also contain a field 'stack' that gives information on the assumed
location of the error.  Typically @var{err} is returned from
@code{lasterror}.
@seealso{lasterror, lasterr, error}
@end deftypefn
error
@c error src/error.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} error (@var{template}, @dots{})
@deftypefnx {Built-in Function} {} error (@var{id}, @var{template}, @dots{})
Format the optional arguments under the control of the template string
@var{template} using the same rules as the @code{printf} family of
functions (@pxref{Formatted Output}) and print the resulting message
on the @code{stderr} stream.  The message is prefixed by the character
string @samp{error: }.

Calling @code{error} also sets Octave's internal error state such that
control will return to the top level without evaluating any more
commands.  This is useful for aborting from functions or scripts.

If the error message does not end with a new line character, Octave will
print a traceback of all the function calls leading to the error.  For
example, given the following function definitions:

@example
@group
function f () g (); end
function g () h (); end
function h () nargin == 1 || error ("nargin != 1"); end
@end group
@end example

@noindent
calling the function @code{f} will result in a list of messages that
can help you to quickly locate the exact location of the error:

@example
@group
f ()
error: nargin != 1
error: called from:
error:   error at line -1, column -1
error:   h at line 1, column 27
error:   g at line 1, column 15
error:   f at line 1, column 15
@end group
@end example

If the error message ends in a new line character, Octave will print the
message but will not display any traceback messages as it returns
control to the top level.  For example, modifying the error message
in the previous example to end in a new line causes Octave to only print
a single message:

@example
@group
function h () nargin == 1 || error ("nargin != 1\n"); end
f ()
error: nargin != 1
@end group
@end example
@end deftypefn
warning
@c warning src/error.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} warning (@var{template}, @dots{})
@deftypefnx {Built-in Function} {} warning (@var{id}, @var{template}, @dots{})
@deftypefnx {Built-in Function} {} warning ("on", @var{id})
@deftypefnx {Built-in Function} {} warning ("off", @var{id})
@deftypefnx {Built-in Function} {} warning ("query", @var{id})
@deftypefnx {Built-in Function} {} warning ("error", @var{id})
Format the optional arguments under the control of the template string
@var{template} using the same rules as the @code{printf} family of
functions (@pxref{Formatted Output}) and print the resulting message
on the @code{stderr} stream.  The message is prefixed by the character
string @samp{warning: }.
You should use this function when you want to notify the user
of an unusual condition, but only when it makes sense for your program
to go on.

The optional message identifier allows users to enable or disable
warnings tagged by @var{id}.  The special identifier @samp{"all"} may
be used to set the state of all warnings.

If the first argument is @samp{"on"} or @samp{"off"}, set the state
of a particular warning using the identifier @var{id}.  If the first
argument is @samp{"query"}, query the state of this warning instead.
If the identifier is omitted, a value of @samp{"all"} is assumed.  If
you set the state of a warning to @samp{"error"}, the warning named by
@var{id} is handled as if it were an error instead.  So, for example, the
following handles all warnings as errors:

@example
@group
warning ("error");
@end group
@end example
@seealso{warning_ids}
@end deftypefn
lasterror
@c lasterror src/error.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{lasterr} =} lasterror ()
@deftypefnx {Built-in Function} {} lasterror (@var{err})
@deftypefnx {Built-in Function} {} lasterror ('reset')
Query or set the last error message structure.  When called without
arguments, return a structure containing the last error message and other
information related to this error.  The elements of the structure are:

@table @asis
@item 'message'
The text of the last error message

@item 'identifier'
The message identifier of this error message

@item 'stack'
A structure containing information on where the message occurred.  This may
be an empty structure if the information cannot
be obtained.  The fields of the structure are:

@table @asis
@item 'file'
The name of the file where the error occurred

@item 'name'
The name of function in which the error occurred

@item 'line'
The line number at which the error occurred

@item 'column'
An optional field with the column number at which the error occurred
@end table
@end table

The last error structure may be set by passing a scalar structure, @var{err},
as input.  Any fields of @var{err} that match those above are set while any
unspecified fields are initialized with default values.

If @code{lasterror} is called with the argument 'reset', all fields are
set to their default values.
@seealso{lasterr}
@end deftypefn
lasterr
@c lasterr src/error.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {[@var{msg}, @var{msgid}] =} lasterr ()
@deftypefnx {Built-in Function} {} lasterr (@var{msg})
@deftypefnx {Built-in Function} {} lasterr (@var{msg}, @var{msgid})
Query or set the last error message.  When called without input arguments,
return the last error message and message identifier.  With one
argument, set the last error message to @var{msg}.  With two arguments,
also set the last message identifier.
@seealso{lasterror}
@end deftypefn
lastwarn
@c lastwarn src/error.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{msg}, @var{msgid}] =} lastwarn (@var{msg}, @var{msgid})
Without any arguments, return the last warning message.  With one
argument, set the last warning message to @var{msg}.  With two arguments,
also set the last message identifier.
@end deftypefn
usage
@c usage src/error.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} usage (@var{msg})
Print the message @var{msg}, prefixed by the string @samp{usage: }, and
set Octave's internal error state such that control will return to the
top level without evaluating any more commands.  This is useful for
aborting from functions.

After @code{usage} is evaluated, Octave will print a traceback of all
the function calls leading to the usage message.

You should use this function for reporting problems errors that result
from an improper call to a function, such as calling a function with an
incorrect number of arguments, or with arguments of the wrong type.  For
example, most functions distributed with Octave begin with code like
this

@example
@group
if (nargin != 2)
  usage ("foo (a, b)");
endif
@end group
@end example

@noindent
to check for the proper number of arguments.
@end deftypefn
beep_on_error
@c beep_on_error src/error.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} beep_on_error ()
@deftypefnx {Built-in Function} {@var{old_val} =} beep_on_error (@var{new_val})
@deftypefnx {Built-in Function} {} beep_on_error (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave will try
to ring the terminal bell before printing an error message.

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.
@end deftypefn
debug_on_error
@c debug_on_error src/error.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} debug_on_error ()
@deftypefnx {Built-in Function} {@var{old_val} =} debug_on_error (@var{new_val})
@deftypefnx {Built-in Function} {} debug_on_error (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave will try
to enter the debugger when an error is encountered.  This will also
inhibit printing of the normal traceback message (you will only see
the top-level error message).

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.
@end deftypefn
debug_on_warning
@c debug_on_warning src/error.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} debug_on_warning ()
@deftypefnx {Built-in Function} {@var{old_val} =} debug_on_warning (@var{new_val})
@deftypefnx {Built-in Function} {} debug_on_warning (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave will try
to enter the debugger when a warning is encountered.

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.
@end deftypefn
fclose
@c fclose src/file-io.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} fclose (@var{fid})
@deftypefnx {Built-in Function} {} fclose ("all")
Close the specified file.  If successful, @code{fclose} returns 0,
otherwise, it returns -1.  The second form of the @code{fclose} call closes
all open files except @code{stdout}, @code{stderr}, and @code{stdin}.
@seealso{fopen, fseek, ftell}
@end deftypefn
fclear
@c fclear src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} fclear (@var{fid})
Clear the stream state for the specified file.
@end deftypefn
fflush
@c fflush src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} fflush (@var{fid})
Flush output to @var{fid}.  This is useful for ensuring that all
pending output makes it to the screen before some other event occurs.
For example, it is always a good idea to flush the standard output
stream before calling @code{input}.

@code{fflush} returns 0 on success and an OS dependent error value
(@minus{}1 on Unix) on error.
@seealso{fopen, fclose}
@end deftypefn
fgetl
@c fgetl src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} fgetl (@var{fid}, @var{len})
Read characters from a file, stopping after a newline, or EOF,
or @var{len} characters have been read.  The characters read, excluding
the possible trailing newline, are returned as a string.

If @var{len} is omitted, @code{fgetl} reads until the next newline
character.

If there are no more characters to read, @code{fgetl} returns @minus{}1.
@seealso{fread, fscanf}
@end deftypefn
fgets
@c fgets src/file-io.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} fgets (@var{fid})
@deftypefnx {Built-in Function} {} fgets (@var{fid}, @var{len})
Read characters from a file, stopping after a newline, or EOF,
or @var{len} characters have been read.  The characters read, including
the possible trailing newline, are returned as a string.

If @var{len} is omitted, @code{fgets} reads until the next newline
character.

If there are no more characters to read, @code{fgets} returns @minus{}1.
@seealso{fputs, fopen, fread, fscanf}
@end deftypefn
fskipl
@c fskipl src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} fskipl (@var{fid}, @var{count})
Skip a given number of lines, i.e., discards characters until an end-of-line
is met exactly @var{count}-times, or end-of-file occurs.
Returns the number of lines skipped (end-of-line sequences encountered).
If @var{count} is omitted, it defaults to 1. @var{count} may also be
@code{Inf}, in which case lines are skipped to the end of file.
This form is suitable for counting lines in a file.
@seealso{fgetl, fgets}
@end deftypefn
fopen
@c fopen src/file-io.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {[@var{fid}, @var{msg}] =} fopen (@var{name}, @var{mode}, @var{arch})
@deftypefnx {Built-in Function} {@var{fid_list} =} fopen ("all")
@deftypefnx {Built-in Function} {[@var{file}, @var{mode}, @var{arch}] =} fopen (@var{fid})
The first form of the @code{fopen} function opens the named file with
the specified mode (read-write, read-only, etc.) and architecture
interpretation (IEEE big endian, IEEE little endian, etc.), and returns
an integer value that may be used to refer to the file later.  If an
error occurs, @var{fid} is set to @minus{}1 and @var{msg} contains the
corresponding system error message.  The @var{mode} is a one or two
character string that specifies whether the file is to be opened for
reading, writing, or both.

The second form of the @code{fopen} function returns a vector of file ids
corresponding to all the currently open files, excluding the
@code{stdin}, @code{stdout}, and @code{stderr} streams.

The third form of the @code{fopen} function returns information about the
open file given its file id.

For example,

@example
myfile = fopen ("splat.dat", "r", "ieee-le");
@end example

@noindent
opens the file @file{splat.dat} for reading.  If necessary, binary
numeric values will be read assuming they are stored in IEEE format with
the least significant bit first, and then converted to the native
representation.

Opening a file that is already open simply opens it again and returns a
separate file id.  It is not an error to open a file several times,
though writing to the same file through several different file ids may
produce unexpected results.

The possible values @samp{mode} may have are

@table @asis
@item @samp{r}
Open a file for reading.

@item @samp{w}
Open a file for writing.  The previous contents are discarded.

@item @samp{a}
Open or create a file for writing at the end of the file.

@item @samp{r+}
Open an existing file for reading and writing.

@item @samp{w+}
Open a file for reading or writing.  The previous contents are
discarded.

@item @samp{a+}
Open or create a file for reading or writing at the end of the
file.
@end table

Append a "t" to the mode string to open the file in text mode or a
"b" to open in binary mode.  On Windows and Macintosh systems, text
mode reading and writing automatically converts linefeeds to the
appropriate line end character for the system (carriage-return linefeed
on Windows, carriage-return on Macintosh).  The default if no mode is
specified is binary mode.

Additionally, you may append a "z" to the mode string to open a
gzipped file for reading or writing.  For this to be successful, you
must also open the file in binary mode.

The parameter @var{arch} is a string specifying the default data format
for the file.  Valid values for @var{arch} are:

@table @asis
@samp{native}
The format of the current machine (this is the default).

@samp{ieee-be}
IEEE big endian format.

@samp{ieee-le}
IEEE little endian format.

@samp{vaxd}
VAX D floating format.

@samp{vaxg}
VAX G floating format.

@samp{cray}
Cray floating format.
@end table

@noindent
however, conversions are currently only supported for @samp{native}
@samp{ieee-be}, and @samp{ieee-le} formats.
@seealso{fclose, fgets, fputs, fread, fseek, ferror, fprintf, fscanf, ftell, fwrite}
@end deftypefn
freport
@c freport src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} freport ()
Print a list of which files have been opened, and whether they are open
for reading, writing, or both.  For example:

@example
@group
freport ()

     @print{}  number  mode  name
     @print{}
     @print{}       0     r  stdin
     @print{}       1     w  stdout
     @print{}       2     w  stderr
     @print{}       3     r  myfile
@end group
@end example
@end deftypefn
frewind
@c frewind src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} frewind (@var{fid})
Move the file pointer to the beginning of the file @var{fid}, returning
0 for success, and -1 if an error was encountered.  It is equivalent to
@code{fseek (@var{fid}, 0, SEEK_SET)}.
@end deftypefn
fseek
@c fseek src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} fseek (@var{fid}, @var{offset}, @var{origin})
Set the file pointer to any location within the file @var{fid}.

The pointer is positioned @var{offset} characters from the @var{origin},
which may be one of the predefined variables @w{@code{SEEK_CUR}} (current
position), @w{@code{SEEK_SET}} (beginning), or @w{@code{SEEK_END}} (end of
file) or strings "cof", "bof" or "eof".  If @var{origin} is omitted,
@w{@code{SEEK_SET}} is assumed.  The offset must be zero, or a value returned
by @code{ftell} (in which case @var{origin} must be @w{@code{SEEK_SET}}).

Return 0 on success and -1 on error.
@seealso{ftell, fopen, fclose}
@end deftypefn
ftell
@c ftell src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} ftell (@var{fid})
Return the position of the file pointer as the number of characters
from the beginning of the file @var{fid}.
@seealso{fseek, fopen, fclose}
@end deftypefn
fprintf
@c fprintf src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} fprintf (@var{fid}, @var{template}, @dots{})
This function is just like @code{printf}, except that the output is
written to the stream @var{fid} instead of @code{stdout}.
If @var{fid} is omitted, the output is written to @code{stdout}.
@seealso{printf, sprintf, fread, fscanf, fopen, fclose}
@end deftypefn
printf
@c printf src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} printf (@var{template}, @dots{})
Print optional arguments under the control of the template string
@var{template} to the stream @code{stdout} and return the number of
characters printed.
@ifclear OCTAVE_MANUAL

See the Formatted Output section of the GNU Octave manual for a
complete description of the syntax of the template string.
@end ifclear
@seealso{fprintf, sprintf, scanf}
@end deftypefn
fputs
@c fputs src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} fputs (@var{fid}, @var{string})
Write a string to a file with no formatting.

Return a non-negative number on success and EOF on error.
@seealso{scanf, sscanf, fread, fprintf, fgets, fscanf}
@end deftypefn
puts
@c puts src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} puts (@var{string})
Write a string to the standard output with no formatting.

Return a non-negative number on success and EOF on error.
@end deftypefn
sprintf
@c sprintf src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} sprintf (@var{template}, @dots{})
This is like @code{printf}, except that the output is returned as a
string.  Unlike the C library function, which requires you to provide a
suitably sized string as an argument, Octave's @code{sprintf} function
returns the string, automatically sized to hold all of the items
converted.
@seealso{printf, fprintf, sscanf}
@end deftypefn
fscanf
@c fscanf src/file-io.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {[@var{val}, @var{count}, @var{errmsg}] =} fscanf (@var{fid}, @var{template}, @var{size})
@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}] =} fscanf (@var{fid}, @var{template}, "C")
In the first form, read from @var{fid} according to @var{template},
returning the result in the matrix @var{val}.

The optional argument @var{size} specifies the amount of data to read
and may be one of

@table @code
@item Inf
Read as much as possible, returning a column vector.

@item @var{nr}
Read up to @var{nr} elements, returning a column vector.

@item [@var{nr}, Inf]
Read as much as possible, returning a matrix with @var{nr} rows.  If the
number of elements read is not an exact multiple of @var{nr}, the last
column is padded with zeros.

@item [@var{nr}, @var{nc}]
Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with
@var{nr} rows.  If the number of elements read is not an exact multiple
of @var{nr}, the last column is padded with zeros.
@end table

@noindent
If @var{size} is omitted, a value of @code{Inf} is assumed.

A string is returned if @var{template} specifies only character
conversions.

The number of items successfully read is returned in @var{count}.

If an error occurs, @var{errmsg} contains a system-dependent error message.

In the second form, read from @var{fid} according to @var{template},
with each conversion specifier in @var{template} corresponding to a
single scalar return value.  This form is more `C-like', and also
compatible with previous versions of Octave.  The number of successful
conversions is returned in @var{count}
@ifclear OCTAVE_MANUAL

See the Formatted Input section of the GNU Octave manual for a
complete description of the syntax of the template string.
@end ifclear
@seealso{scanf, sscanf, fread, fprintf, fgets, fputs}
@end deftypefn
sscanf
@c sscanf src/file-io.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {[@var{val}, @var{count}, @var{errmsg}, @var{pos}] =} sscanf (@var{string}, @var{template}, @var{size})
@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}] =} sscanf (@var{string}, @var{template}, "C")
This is like @code{fscanf}, except that the characters are taken from the
string @var{string} instead of from a stream.  Reaching the end of the
string is treated as an end-of-file condition.  In addition to the values
returned by @code{fscanf}, the index of the next character to be read
is returned in @var{pos}.
@seealso{fscanf, scanf, sprintf}
@end deftypefn
scanf
@c scanf src/file-io.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {[@var{val}, @var{count}, @var{errmsg}] =} scanf (@var{template}, @var{size})
@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}]] =} scanf (@var{template}, "C")
This is equivalent to calling @code{fscanf} with @var{fid} = @code{stdin}.

It is currently not useful to call @code{scanf} in interactive
programs.
@seealso{fscanf, sscanf, printf}
@end deftypefn
fread
@c fread src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} fread (@var{fid}, @var{size}, @var{precision}, @var{skip}, @var{arch})
Read binary data of type @var{precision} from the specified file ID
@var{fid}.

The optional argument @var{size} specifies the amount of data to read
and may be one of

@table @code
@item Inf
Read as much as possible, returning a column vector.

@item @var{nr}
Read up to @var{nr} elements, returning a column vector.

@item [@var{nr}, Inf]
Read as much as possible, returning a matrix with @var{nr} rows.  If the
number of elements read is not an exact multiple of @var{nr}, the last
column is padded with zeros.

@item [@var{nr}, @var{nc}]
Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with
@var{nr} rows.  If the number of elements read is not an exact multiple
of @var{nr}, the last column is padded with zeros.
@end table

@noindent
If @var{size} is omitted, a value of @code{Inf} is assumed.

The optional argument @var{precision} is a string specifying the type of
data to read and may be one of

@table @asis
@item "schar"
@itemx "signed char"
Signed character.

@item "uchar"
@itemx "unsigned char"
Unsigned character.

@item "int8"
@itemx "integer*1"

8-bit signed integer.

@item "int16"
@itemx "integer*2"
16-bit signed integer.

@item "int32"
@itemx "integer*4"
32-bit signed integer.

@item "int64"
@itemx "integer*8"
64-bit signed integer.

@item "uint8"
8-bit unsigned integer.

@item "uint16"
16-bit unsigned integer.

@item "uint32"
32-bit unsigned integer.

@item "uint64"
64-bit unsigned integer.

@item "single"
@itemx "float32"
@itemx "real*4"
32-bit floating point number.

@item "double"
@itemx "float64"
@itemx "real*8"
64-bit floating point number.

@item "char"
@itemx "char*1"
Single character.

@item "short"
Short integer (size is platform dependent).

@item "int"
Integer (size is platform dependent).

@item "long"
Long integer (size is platform dependent).

@item "ushort"
@itemx "unsigned short"
Unsigned short integer (size is platform dependent).

@item "uint"
@itemx "unsigned int"
Unsigned integer (size is platform dependent).

@item "ulong"
@itemx "unsigned long"
Unsigned long integer (size is platform dependent).

@item "float"
Single precision floating point number (size is platform dependent).
@end table

@noindent
The default precision is @code{"uchar"}.

The @var{precision} argument may also specify an optional repeat
count.  For example, @samp{32*single} causes @code{fread} to read
a block of 32 single precision floating point numbers.  Reading in
blocks is useful in combination with the @var{skip} argument.

The @var{precision} argument may also specify a type conversion.
For example, @samp{int16=>int32} causes @code{fread} to read 16-bit
integer values and return an array of 32-bit integer values.  By
default, @code{fread} returns a double precision array.  The special
form @samp{*TYPE} is shorthand for @samp{TYPE=>TYPE}.

The conversion and repeat counts may be combined.  For example, the
specification @samp{32*single=>single} causes @code{fread} to read
blocks of single precision floating point values and return an array
of single precision values instead of the default array of double
precision values.

The optional argument @var{skip} specifies the number of bytes to skip
after each element (or block of elements) is read.  If it is not
specified, a value of 0 is assumed.  If the final block read is not
complete, the final skip is omitted.  For example,

@example
fread (f, 10, "3*single=>single", 8)
@end example

@noindent
will omit the final 8-byte skip because the last read will not be
a complete block of 3 values.

The optional argument @var{arch} is a string specifying the data format
for the file.  Valid values are

@table @code
@item "native"
The format of the current machine.

@item "ieee-be"
IEEE big endian.

@item "ieee-le"
IEEE little endian.

@item "vaxd"
VAX D floating format.

@item "vaxg"
VAX G floating format.

@item "cray"
Cray floating format.
@end table

@noindent
Conversions are currently only supported for @code{"ieee-be"} and
@code{"ieee-le"} formats.

The data read from the file is returned in @var{val}, and the number of
values read is returned in @code{count}
@seealso{fwrite, fopen, fclose}
@end deftypefn
fwrite
@c fwrite src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {@var{count} =} fwrite (@var{fid}, @var{data}, @var{precision}, @var{skip}, @var{arch})
Write data in binary form of type @var{precision} to the specified file
ID @var{fid}, returning the number of values successfully written to the
file.

The argument @var{data} is a matrix of values that are to be written to
the file.  The values are extracted in column-major order.

The remaining arguments @var{precision}, @var{skip}, and @var{arch} are
optional, and are interpreted as described for @code{fread}.

The behavior of @code{fwrite} is undefined if the values in @var{data}
are too large to fit in the specified precision.
@seealso{fread, fopen, fclose}
@end deftypefn
feof
@c feof src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} feof (@var{fid})
Return 1 if an end-of-file condition has been encountered for a given
file and 0 otherwise.  Note that it will only return 1 if the end of the
file has already been encountered, not if the next read operation will
result in an end-of-file condition.
@seealso{fread, fopen, fclose}
@end deftypefn
ferror
@c ferror src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} ferror (@var{fid}, "clear")
Return 1 if an error condition has been encountered for the file ID
@var{fid} and 0 otherwise.  Note that it will only return 1 if an error
has already been encountered, not if the next operation will result in
an error condition.

The second argument is optional.  If it is supplied, also clear the
error condition.
@end deftypefn
popen
@c popen src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {@var{fid} =} popen (@var{command}, @var{mode})
Start a process and create a pipe.  The name of the command to run is
given by @var{command}.  The file identifier corresponding to the input
or output stream of the process is returned in @var{fid}.  The argument
@var{mode} may be

@table @code
@item "r"
The pipe will be connected to the standard output of the process, and
open for reading.

@item "w"
The pipe will be connected to the standard input of the process, and
open for writing.
@end table

For example:

@example
@group
fid = popen ("ls -ltr / | tail -3", "r");
while (ischar (s = fgets (fid)))
  fputs (stdout, s);
endwhile
     @print{} drwxr-xr-x  33 root  root  3072 Feb 15 13:28 etc
     @print{} drwxr-xr-x   3 root  root  1024 Feb 15 13:28 lib
     @print{} drwxrwxrwt  15 root  root  2048 Feb 17 14:53 tmp
@end group
@end example
@end deftypefn
pclose
@c pclose src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} pclose (@var{fid})
Close a file identifier that was opened by @code{popen}.  You may also
use @code{fclose} for the same purpose.
@end deftypefn
tmpnam
@c tmpnam src/file-io.cc
-*- texinfo -*-
@c List other forms of function in documentation index
@findex octave_tmp_file_name

@deftypefn  {Built-in Function} {} tmpnam ()
@deftypefnx {Built-in Function} {} tmpnam (@var{dir})
@deftypefnx {Built-in Function} {} tmpnam (@var{dir}, @var{prefix})
Return a unique temporary file name as a string.

If @var{prefix} is omitted, a value of @code{"oct-"} is used.
If @var{dir} is also omitted, the default directory for temporary files
is used.  If @var{dir} is provided, it must exist, otherwise the default
directory for temporary files is used.  Since the named file is not
opened, by @code{tmpnam}, it is possible (though relatively unlikely)
that it will not be available by the time your program attempts to open it.
@seealso{tmpfile, mkstemp, P_tmpdir}
@end deftypefn
tmpfile
@c tmpfile src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{fid}, @var{msg}] =} tmpfile ()
Return the file ID corresponding to a new temporary file with a unique
name.  The file is opened in binary read/write (@code{"w+b"}) mode.
The file will be deleted automatically when it is closed or when Octave
exits.

If successful, @var{fid} is a valid file ID and @var{msg} is an empty
string.  Otherwise, @var{fid} is -1 and @var{msg} contains a
system-dependent error message.
@seealso{tmpnam, mkstemp, P_tmpdir}
@end deftypefn
mkstemp
@c mkstemp src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{fid}, @var{name}, @var{msg}] =} mkstemp (@var{template}, @var{delete})
Return the file ID corresponding to a new temporary file with a unique
name created from @var{template}.  The last six characters of @var{template}
must be @code{XXXXXX} and these are replaced with a string that makes the
filename unique.  The file is then created with mode read/write and
permissions that are system dependent (on GNU/Linux systems, the permissions
will be 0600 for versions of glibc 2.0.7 and later).  The file is opened
in binary mode and with the @w{@code{O_EXCL}} flag.

If the optional argument @var{delete} is supplied and is true,
the file will be deleted automatically when Octave exits, or when
the function @code{purge_tmp_files} is called.

If successful, @var{fid} is a valid file ID, @var{name} is the name of
the file, and @var{msg} is an empty string.  Otherwise, @var{fid}
is -1, @var{name} is empty, and @var{msg} contains a system-dependent
error message.
@seealso{tmpfile, tmpnam, P_tmpdir}
@end deftypefn
umask
@c umask src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} umask (@var{mask})
Set the permission mask for file creation.  The parameter @var{mask}
is an integer, interpreted as an octal number.  If successful,
returns the previous value of the mask (as an integer to be
interpreted as an octal number); otherwise an error message is printed.
@end deftypefn
P_tmpdir
@c P_tmpdir src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} P_tmpdir ()
Return the default name of the directory for temporary files on
this system.  The name of this directory is system dependent.
@end deftypefn
SEEK_SET
@c SEEK_SET src/file-io.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} SEEK_SET ()
@deftypefnx {Built-in Function} {} SEEK_CUR ()
@deftypefnx {Built-in Function} {} SEEK_END ()
Return the numerical value to pass to @code{fseek} to perform
one of the following actions:
@table @code
@item SEEK_SET
Position file relative to the beginning.

@item SEEK_CUR
Position file relative to the current position.

@item SEEK_END
Position file relative to the end.
@end table
@seealso{fseek}
@end deftypefn
SEEK_CUR
@c SEEK_CUR src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} SEEK_CUR ()
Return the numerical value to pass to @code{fseek} to
position the file pointer relative to the current position.
@seealso{SEEK_SET, SEEK_END}.
@end deftypefn
SEEK_END
@c SEEK_END src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} SEEK_END ()
Return the numerical value to pass to @code{fseek} to
position the file pointer relative to the end of the file.
@seealso{SEEK_SET, SEEK_CUR}.
@end deftypefn
stdin
@c stdin src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} stdin ()
Return the numeric value corresponding to the standard input stream.
When Octave is used interactively, this is filtered through the command
line editing functions.
@seealso{stdout, stderr}
@end deftypefn
stdout
@c stdout src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} stdout ()
Return the numeric value corresponding to the standard output stream.
Data written to the standard output is normally filtered through the pager.
@seealso{stdin, stderr}
@end deftypefn
stderr
@c stderr src/file-io.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} stderr ()
Return the numeric value corresponding to the standard error stream.
Even if paging is turned on, the standard error is not sent to the
pager.  It is useful for error messages and prompts.
@seealso{stdin, stdout}
@end deftypefn
ishandle
@c ishandle src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} ishandle (@var{h})
Return true if @var{h} is a graphics handle and false otherwise.
@var{h} may also be a matrix of handles in which case a logical
array is returned that is true where the elements of @var{h} are
graphics handles and false where they are not.
@seealso{isfigure}
@end deftypefn
__is_handle_visible__
@c __is_handle_visible__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} __is_handle_visible__ (@var{h})
Undocumented internal function.
@end deftypefn
reset
@c reset src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} reset (@var{h}, @var{property})
Remove any defaults set for the handle @var{h}.  The default figure
properties of "position", "units", "windowstyle" and
"paperunits" and the default axes properties of "position" and "units"
are not reset.
@end deftypefn
set
@c set src/graphics.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} set (@var{h}, @var{property}, @var{value}, @dots{})
@deftypefnx {Built-in Function} {} set (@var{h}, @var{properties}, @var{values})
@deftypefnx {Built-in Function} {} set (@var{h}, @var{pv})
Set named property values for the graphics handle (or vector of graphics
handles) @var{h}.
There are three ways how to give the property names and values:

@itemize
@item as a comma separated list of @var{property}, @var{value} pairs

Here, each @var{property} is a string containing the property name, each
@var{value} is a value of the appropriate type for the property.

@item as a cell array of strings @var{properties} containing property names
and a cell array @var{values} containing property values.

In this case, the number of columns of @var{values} must match the number of
elements in @var{properties}.  The first column of @var{values} contains
values for the first entry in @var{properties}, etc.  The number of rows of
@var{values} must be 1 or match the number of elements of @var{h}.  In the
first case, each handle in @var{h} will be assigned the same values.  In the
latter case, the first handle in @var{h} will be assigned the values from
the first row of @var{values} and so on.

@item as a structure array @var{pv}

Here, the field names of @var{pv} represent the property names, and the field
values give the property values.  In contrast to the previous case, all
elements of @var{pv} will be set in all handles in @var{h} independent of
the dimensions of @var{pv}.
@end itemize
@end deftypefn
get
@c get src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} get (@var{h}, @var{p})
Return the named property @var{p} from the graphics handle @var{h}.
If @var{p} is omitted, return the complete property list for @var{h}.
If @var{h} is a vector, return a cell array including the property
values or lists respectively.
@end deftypefn
__get__
@c __get__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __get__ (@var{h})
Undocumented internal function.
@end deftypefn
__go_figure__
@c __go_figure__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_figure__ (@var{fignum})
Undocumented internal function.
@end deftypefn
__calc_dimensions__
@c __calc_dimensions__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __calc_dimensions__ (@var{axes})
Internal function.  Determine the number of dimensions in a graphics
object, whether 2 or 3.
@end deftypefn
__go_axes__
@c __go_axes__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_axes__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_line__
@c __go_line__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_line__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_text__
@c __go_text__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_text__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_image__
@c __go_image__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_image__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_surface__
@c __go_surface__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_surface__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_patch__
@c __go_patch__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_patch__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_hggroup__
@c __go_hggroup__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_hggroup__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uimenu__
@c __go_uimenu__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_uimenu__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uicontrol__
@c __go_uicontrol__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_uicontrol__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uipanel__
@c __go_uipanel__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_uipanel__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uicontextmenu__
@c __go_uicontextmenu__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_uicontextmenu__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uitoolbar__
@c __go_uitoolbar__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_uitoolbar__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uipushtool__
@c __go_uipushtool__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_uipushtool__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uitoggletool__
@c __go_uitoggletool__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_uitoggletool__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_delete__
@c __go_delete__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_delete__ (@var{h})
Undocumented internal function.
@end deftypefn
__go_axes_init__
@c __go_axes_init__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_axes_init__ (@var{h}, @var{mode})
Undocumented internal function.
@end deftypefn
__go_handles__
@c __go_handles__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_handles__ (@var{show_hidden})
Undocumented internal function.
@end deftypefn
__go_figure_handles__
@c __go_figure_handles__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __go_figure_handles__ (@var{show_hidden})
Undocumented internal function.
@end deftypefn
__go_execute_callback__
@c __go_execute_callback__ src/graphics.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} __go_execute_callback__ (@var{h}, @var{name})
@deftypefnx {Built-in Function} {} __go_execute_callback__ (@var{h}, @var{name}, @var{param})
Undocumented internal function.
@end deftypefn
__image_pixel_size__
@c __image_pixel_size__ src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {@var{px}, @var{py}} __image_pixel_size__ (@var{h})
Internal function: returns the pixel size of the image in normalized units.
@end deftypefn
available_graphics_toolkits
@c available_graphics_toolkits src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} available_graphics_toolkits ()
Return a cell array of registered graphics toolkits.
@seealso{graphics_toolkit, register_graphics_toolkit}
@end deftypefn
register_graphics_toolkit
@c register_graphics_toolkit src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} register_graphics_toolkit (@var{toolkit})
List @var{toolkit} as an available graphics toolkit.
@seealso{available_graphics_toolkits}
@end deftypefn
loaded_graphics_toolkits
@c loaded_graphics_toolkits src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} loaded_graphics_toolkits ()
Return a cell array of the currently loaded graphics toolkits.
@seealso{available_graphics_toolkits}
@end deftypefn
drawnow
@c drawnow src/graphics.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} drawnow ()
@deftypefnx {Built-in Function} {} drawnow ("expose")
@deftypefnx {Built-in Function} {} drawnow (@var{term}, @var{file}, @var{mono}, @var{debug_file})
Update figure windows and their children.  The event queue is flushed and
any callbacks generated are executed.  With the optional argument
@code{"expose"}, only graphic objects are updated and no other events or
callbacks are processed.
The third calling form of @code{drawnow} is for debugging and is
undocumented.
@end deftypefn
addlistener
@c addlistener src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} addlistener (@var{h}, @var{prop}, @var{fcn})
Register @var{fcn} as listener for the property @var{prop} of the graphics
object @var{h}.  Property listeners are executed (in order of registration)
when the property is set.  The new value is already available when the
listeners are executed.

@var{prop} must be a string naming a valid property in @var{h}.

@var{fcn} can be a function handle, a string or a cell array whose first
element is a function handle.  If @var{fcn} is a function handle, the
corresponding function should accept at least 2 arguments, that will be
set to the object handle and the empty matrix respectively.  If @var{fcn}
is a string, it must be any valid octave expression.  If @var{fcn} is a cell
array, the first element must be a function handle with the same signature
as described above.  The next elements of the cell array are passed
as additional arguments to the function.

Example:

@example
@group
function my_listener (h, dummy, p1)
  fprintf ("my_listener called with p1=%s\n", p1);
endfunction

addlistener (gcf, "position", @{@@my_listener, "my string"@})
@end group
@end example

@end deftypefn
dellistener
@c dellistener src/graphics.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} dellistener (@var{h}, @var{prop}, @var{fcn})
Remove the registration of @var{fcn} as a listener for the property
@var{prop} of the graphics object @var{h}.  The function @var{fcn} must
be the same variable (not just the same value), as was passed to the
original call to @code{addlistener}.

If @var{fcn} is not defined then all listener functions of @var{prop}
are removed.

Example:

@example
@group
function my_listener (h, dummy, p1)
  fprintf ("my_listener called with p1=%s\n", p1);
endfunction

c = @{@@my_listener, "my string"@};
addlistener (gcf, "position", c);
dellistener (gcf, "position", c);
@end group
@end example

@end deftypefn
addproperty
@c addproperty src/graphics.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} addproperty (@var{name}, @var{h}, @var{type})
@deftypefnx {Built-in Function} {} addproperty (@var{name}, @var{h}, @var{type}, @var{arg}, @dots{})
Create a new property named @var{name} in graphics object @var{h}.
@var{type} determines the type of the property to create.  @var{args}
usually contains the default value of the property, but additional
arguments might be given, depending on the type of the property.

The supported property types are:

@table @code
@item string
A string property.  @var{arg} contains the default string value.

@item any
An un-typed property.  This kind of property can hold any octave
value.  @var{args} contains the default value.

@item radio
A string property with a limited set of accepted values.  The first
argument must be a string with all accepted values separated by
a vertical bar ('|').  The default value can be marked by enclosing
it with a '@{' '@}' pair.  The default value may also be given as
an optional second string argument.

@item boolean
A boolean property.  This property type is equivalent to a radio
property with "on|off" as accepted values.  @var{arg} contains
the default property value.

@item double
A scalar double property.  @var{arg} contains the default value.

@item handle
A handle property.  This kind of property holds the handle of a
graphics object.  @var{arg} contains the default handle value.
When no default value is given, the property is initialized to
the empty matrix.

@item data
A data (matrix) property.  @var{arg} contains the default data
value.  When no default value is given, the data is initialized to
the empty matrix.

@item color
A color property.  @var{arg} contains the default color value.
When no default color is given, the property is set to black.
An optional second string argument may be given to specify an
additional set of accepted string values (like a radio property).
@end table

@var{type} may also be the concatenation of a core object type and
a valid property name for that object type.  The property created
then has the same characteristics as the referenced property (type,
possible values, hidden state@dots{}).  This allows to clone an existing
property into the graphics object @var{h}.

Examples:

@example
@group
addproperty ("my_property", gcf, "string", "a string value");
addproperty ("my_radio", gcf, "radio", "val_1|val_2|@{val_3@}");
addproperty ("my_style", gcf, "linelinestyle", "--");
@end group
@end example

@end deftypefn
waitfor
@c waitfor src/graphics.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} waitfor (@var{h})
@deftypefnx {Built-in Function} {} waitfor (@var{h}, @var{prop})
@deftypefnx {Built-in Function} {} waitfor (@var{h}, @var{prop}, @var{value})
@deftypefnx {Built-in Function} {} waitfor (@dots{}, "timeout", @var{timeout})
Suspend the execution of the current program until a condition is
satisfied on the graphics handle @var{h}.  While the program is suspended
graphics events are still being processed normally, allowing callbacks to
modify the state of graphics objects.  This function is reentrant and can be
called from a callback, while another @code{waitfor} call is pending at
top-level.

In the first form, program execution is suspended until the graphics object
@var{h} is destroyed.  If the graphics handle is invalid, the function
returns immediately.

In the second form, execution is suspended until the graphics object is
destroyed or the property named @var{prop} is modified.  If the graphics
handle is invalid or the property does not exist, the function returns
immediately.

In the third form, execution is suspended until the graphics object is
destroyed or the property named @var{prop} is set to @var{value}.  The
function @code{isequal} is used to compare property values.  If the graphics
handle is invalid, the property does not exist or the property is already
set to @var{value}, the function returns immediately.

An optional timeout can be specified using the property @code{timeout}.
This timeout value is the number of seconds to wait for the condition to be
true.  @var{timeout} must be at least 1. If a smaller value is specified, a
warning is issued and a value of 1 is used instead.  If the timeout value is
not an integer, it is truncated towards 0.

To define a condition on a property named @code{timeout}, use the string
@code{\timeout} instead.

In all cases, typing CTRL-C stops program execution immediately.
@seealso{isequal}
@end deftypefn
get_help_text
@c get_help_text src/help.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{text}, @var{format}] =} get_help_text (@var{name})
Return the raw help text of function @var{name}.

The raw help text is returned in @var{text} and the format in @var{format}
The format is a string which is one of @t{"texinfo"}, @t{"html"}, or
@t{"plain text"}.
@end deftypefn
get_help_text_from_file
@c get_help_text_from_file src/help.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{text}, @var{format}] =} get_help_text_from_file (@var{fname})
Return the raw help text from the file @var{fname}.

The raw help text is returned in @var{text} and the format in @var{format}
The format is a string which is one of @t{"texinfo"}, @t{"html"}, or
@t{"plain text"}.
@end deftypefn
__operators__
@c __operators__ src/help.cc
-*- texinfo -*-
@deftypefn {Function File} __operators__ ()
Undocumented internal function.
@end deftypefn
__keywords__
@c __keywords__ src/help.cc
-*- texinfo -*-
@deftypefn {Function File} __keywords__ ()
Undocumented internal function.
@end deftypefn
__builtins__
@c __builtins__ src/help.cc
-*- texinfo -*-
@deftypefn {Function File} __builtins__ ()
Undocumented internal function.
@end deftypefn
__which__
@c __which__ src/help.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __which__ (@var{name}, @dots{})
Undocumented internal function.
@end deftypefn
__list_functions__
@c __list_functions__ src/help.cc
-*- texinfo -*-
@deftypefn  {Function File} {@var{retval} =} __list_functions__ ()
@deftypefnx {Function File} {@var{retval} =} __list_functions__ (@var{directory})
Undocumented internal function.
@end deftypefn
doc_cache_file
@c doc_cache_file src/help.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} doc_cache_file ()
@deftypefnx {Built-in Function} {@var{old_val} =} doc_cache_file (@var{new_val})
@deftypefnx {Built-in Function} {} doc_cache_file (@var{new_val}, "local")
Query or set the internal variable that specifies the name of the
Octave documentation cache file.  A cache file significantly improves
the performance of the @code{lookfor} command.  The default value is 
@file{@var{octave-home}/share/octave/@var{version}/etc/doc-cache},
in which @var{octave-home} is the root directory of the Octave installation,
and @var{version} is the Octave version number.
The default value may be overridden by the environment variable
@w{@env{OCTAVE_DOC_CACHE_FILE}}, or the command line argument
@samp{--doc-cache-file NAME}.

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.
@seealso{lookfor, info_program, doc, help, makeinfo_program}
@end deftypefn
info_file
@c info_file src/help.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} info_file ()
@deftypefnx {Built-in Function} {@var{old_val} =} info_file (@var{new_val})
@deftypefnx {Built-in Function} {} info_file (@var{new_val}, "local")
Query or set the internal variable that specifies the name of the
Octave info file.  The default value is
@file{@var{octave-home}/info/octave.info}, in
which @var{octave-home} is the root directory of the Octave installation.
The default value may be overridden by the environment variable
@w{@env{OCTAVE_INFO_FILE}}, or the command line argument
@samp{--info-file NAME}.

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.
@seealso{info_program, doc, help, makeinfo_program}
@end deftypefn
info_program
@c info_program src/help.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} info_program ()
@deftypefnx {Built-in Function} {@var{old_val} =} info_program (@var{new_val})
@deftypefnx {Built-in Function} {} info_program (@var{new_val}, "local")
Query or set the internal variable that specifies the name of the
info program to run.  The default value is
@file{@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch}/info}
in which @var{octave-home} is the root directory of the Octave installation,
@var{version} is the Octave version number, and @var{arch}
is the system type (for example, @code{i686-pc-linux-gnu}).  The
default value may be overridden by the environment variable
@w{@env{OCTAVE_INFO_PROGRAM}}, or the command line argument
@samp{--info-program NAME}.

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.
@seealso{info_file, doc, help, makeinfo_program}
@end deftypefn
makeinfo_program
@c makeinfo_program src/help.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} makeinfo_program ()
@deftypefnx {Built-in Function} {@var{old_val} =} makeinfo_program (@var{new_val})
@deftypefnx {Built-in Function} {} makeinfo_program (@var{new_val}, "local")
Query or set the internal variable that specifies the name of the
program that Octave runs to format help text containing
Texinfo markup commands.  The default value is @code{makeinfo}.

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.
@seealso{info_file, info_program, doc, help}
@end deftypefn
suppress_verbose_help_message
@c suppress_verbose_help_message src/help.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} suppress_verbose_help_message ()
@deftypefnx {Built-in Function} {@var{old_val} =} suppress_verbose_help_message (@var{new_val})
@deftypefnx {Built-in Function} {} suppress_verbose_help_message (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave
will add additional help information to the end of the output from
the @code{help} command and usage messages for built-in commands.

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.
@end deftypefn
input
@c input src/input.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} input (@var{prompt})
@deftypefnx {Built-in Function} {} input (@var{prompt}, "s")
Print a prompt and wait for user input.  For example,

@example
input ("Pick a number, any number! ")
@end example

@noindent
prints the prompt

@example
Pick a number, any number!
@end example

@noindent
and waits for the user to enter a value.  The string entered by the user
is evaluated as an expression, so it may be a literal constant, a
variable name, or any other valid expression.

Currently, @code{input} only returns one value, regardless of the number
of values produced by the evaluation of the expression.

If you are only interested in getting a literal string value, you can
call @code{input} with the character string @code{"s"} as the second
argument.  This tells Octave to return the string entered by the user
directly, without evaluating it first.

Because there may be output waiting to be displayed by the pager, it is
a good idea to always call @code{fflush (stdout)} before calling
@code{input}.  This will ensure that all pending output is written to
the screen before your prompt.  @xref{Input and Output}.
@end deftypefn
yes_or_no
@c yes_or_no src/input.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} yes_or_no (@var{prompt})
Ask the user a yes-or-no question.  Return 1 if the answer is yes.
Takes one argument, which is the string to display to ask the
question.  It should end in a space; @samp{yes-or-no-p} adds
@samp{(yes or no) } to it.  The user must confirm the answer with
RET and can edit it until it has been confirmed.
@end deftypefn
keyboard
@c keyboard src/input.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} keyboard ()
@deftypefnx {Built-in Function} {} keyboard (@var{prompt})
This function is normally used for simple debugging.  When the
@code{keyboard} function is executed, Octave prints a prompt and waits
for user input.  The input strings are then evaluated and the results
are printed.  This makes it possible to examine the values of variables
within a function, and to assign new values if necessary.  To leave the
prompt and return to normal execution type @samp{return} or @samp{dbcont}.
The @code{keyboard} function does not return an exit status.

If @code{keyboard} is invoked without arguments, a default prompt of
@samp{debug> } is used.
@seealso{dbcont, dbquit}
@end deftypefn
echo
@c echo src/input.cc
-*- texinfo -*-
@deftypefn {Command} {} echo options
Control whether commands are displayed as they are executed.  Valid
options are:

@table @code
@item on
Enable echoing of commands as they are executed in script files.

@item off
Disable echoing of commands as they are executed in script files.

@item on all
Enable echoing of commands as they are executed in script files and
functions.

@item off all
Disable echoing of commands as they are executed in script files and
functions.
@end table

@noindent
With no arguments, @code{echo} toggles the current echo state.
@end deftypefn
completion_matches
@c completion_matches src/input.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} completion_matches (@var{hint})
Generate possible completions given @var{hint}.

This function is provided for the benefit of programs like Emacs which
might be controlling Octave and handling user input.  The current
command number is not incremented when this function is called.  This is
a feature, not a bug.
@end deftypefn
read_readline_init_file
@c read_readline_init_file src/input.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} read_readline_init_file (@var{file})
Read the readline library initialization file @var{file}.  If
@var{file} is omitted, read the default initialization file (normally
@file{~/.inputrc}).

@xref{Readline Init File, , , readline, GNU Readline Library},
for details.
@end deftypefn
re_read_readline_init_file
@c re_read_readline_init_file src/input.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} re_read_readline_init_file ()
Re-read the last readline library initialization file that was read.
@xref{Readline Init File, , , readline, GNU Readline Library},
for details.
@end deftypefn
add_input_event_hook
@c add_input_event_hook src/input.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} add_input_event_hook (@var{fcn})
@deftypefnx {Built-in Function} {} add_input_event_hook (@var{fcn}, @var{data})
Add the named function @var{fcn} to the list of functions to call
periodically when Octave is waiting for input.  The function should
have the form

@example
@var{fcn} (@var{data})
@end example

If @var{data} is omitted, Octave calls the function without any
arguments.
@seealso{remove_input_event_hook}
@end deftypefn
remove_input_event_hook
@c remove_input_event_hook src/input.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} remove_input_event_hook (@var{fcn})
Remove the named function @var{fcn} from the list of functions to call
periodically when Octave is waiting for input.
@seealso{add_input_event_hook}
@end deftypefn
PS1
@c PS1 src/input.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} PS1 ()
@deftypefnx {Built-in Function} {@var{old_val} =} PS1 (@var{new_val})
@deftypefnx {Built-in Function} {} PS1 (@var{new_val}, "local")
Query or set the primary prompt string.  When executing interactively,
Octave displays the primary prompt when it is ready to read a command.

The default value of the primary prompt string is @code{"\s:\#> "}.
To change it, use a command like

@example
PS1 ("\\u@@\\H> ")
@end example

@noindent
which will result in the prompt @samp{boris@@kremvax> } for the user
@samp{boris} logged in on the host @samp{kremvax.kgb.su}.  Note that two
backslashes are required to enter a backslash into a double-quoted
character string.  @xref{Strings}.

You can also use ANSI escape sequences if your terminal supports them.
This can be useful for coloring the prompt.  For example,

@example
PS1 ("\\[\\033[01;31m\\]\\s:\\#> \\[\\033[0m\\]")
@end example

@noindent
will give the default Octave prompt a red coloring.

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.
@seealso{PS2, PS4}
@end deftypefn
PS2
@c PS2 src/input.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} PS2 ()
@deftypefnx {Built-in Function} {@var{old_val} =} PS2 (@var{new_val})
@deftypefnx {Built-in Function} {} PS2 (@var{new_val}, "local")
Query or set the secondary prompt string.  The secondary prompt is
printed when Octave is expecting additional input to complete a
command.  For example, if you are typing a @code{for} loop that spans several
lines, Octave will print the secondary prompt at the beginning of
each line after the first.  The default value of the secondary prompt
string is @code{"> "}.

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.
@seealso{PS1, PS4}
@end deftypefn
PS4
@c PS4 src/input.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} PS4 ()
@deftypefnx {Built-in Function} {@var{old_val} =} PS4 (@var{new_val})
@deftypefnx {Built-in Function} {} PS4 (@var{new_val}, "local")
Query or set the character string used to prefix output produced
when echoing commands is enabled.
The default value is @code{"+ "}.
@xref{Diary and Echo Commands}, for a description of echoing commands.

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.
@seealso{echo, echo_executing_commands, PS1, PS2}
@end deftypefn
completion_append_char
@c completion_append_char src/input.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} completion_append_char ()
@deftypefnx {Built-in Function} {@var{old_val} =} completion_append_char (@var{new_val})
@deftypefnx {Built-in Function} {} completion_append_char (@var{new_val}, "local")
Query or set the internal character variable that is appended to
successful command-line completion attempts.  The default
value is @code{" "} (a single space).

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.
@end deftypefn
echo_executing_commands
@c echo_executing_commands src/input.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} echo_executing_commands ()
@deftypefnx {Built-in Function} {@var{old_val} =} echo_executing_commands (@var{new_val})
@deftypefnx {Built-in Function} {} echo_executing_commands (@var{new_val}, "local")
Query or set the internal variable that controls the echo state.
It may be the sum of the following values:

@table @asis
@item 1
Echo commands read from script files.

@item 2
Echo commands from functions.

@item 4
Echo commands read from command line.
@end table

More than one state can be active at once.  For example, a value of 3 is
equivalent to the command @kbd{echo on all}.

The value of @code{echo_executing_commands} may be set by the @kbd{echo}
command or the command line option @option{--echo-commands}.

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.
@end deftypefn
__request_drawnow__
@c __request_drawnow__ src/input.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} __request_drawnow__ ()
@deftypefnx {Built-in Function} {} __request_drawnow__ (@var{flag})
Undocumented internal function.
@end deftypefn
__gud_mode__
@c __gud_mode__ src/input.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __gud_mode__ ()
Undocumented internal function.
@end deftypefn
filemarker
@c filemarker src/input.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} filemarker ()
@deftypefnx {Built-in Function} {} filemarker (@var{new_val})
@deftypefnx {Built-in Function} {} filemarker (@var{new_val}, "local")
Query or set the character used to separate filename from the
the subfunction names contained within the file.  This can be used in
a generic manner to interact with subfunctions.  For example,

@example
help (["myfunc", filemarker, "mysubfunc"])
@end example

@noindent
returns the help string associated with the sub-function @code{mysubfunc}
of the function @code{myfunc}.  Another use of @code{filemarker} is when
debugging it allows easier placement of breakpoints within sub-functions.
For example,

@example
dbstop (["myfunc", filemarker, "mysubfunc"])
@end example

@noindent
will set a breakpoint at the first line of the subfunction @code{mysubfunc}.

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.
@end deftypefn
iskeyword
@c iskeyword src/lex.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} iskeyword ()
@deftypefnx {Built-in Function} {} iskeyword (@var{name})
Return true if @var{name} is an Octave keyword.  If @var{name}
is omitted, return a list of keywords.
@seealso{isvarname, exist}
@end deftypefn
__display_tokens__
@c __display_tokens__ src/lex.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __display_tokens__ ()
Query or set the internal variable that determines whether Octave's
lexer displays tokens as they are read.
@end deftypefn
__token_count__
@c __token_count__ src/lex.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __token_count__ ()
Number of language tokens processed since Octave startup.
@end deftypefn
__lexer_debug_flag__
@c __lexer_debug_flag__ src/lex.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {@var{old_val} =} __lexer_debug_flag__ (@var{new_val}))
Undocumented internal function.
@end deftypefn
genpath
@c genpath src/load-path.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} genpath (@var{dir})
@deftypefnx {Built-in Function} {} genpath (@var{dir}, @var{skip}, @dots{})
Return a path constructed from @var{dir} and all its subdirectories.
If additional string parameters are given, the resulting path will
exclude directories with those names.
@end deftypefn
rehash
@c rehash src/load-path.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} rehash ()
Reinitialize Octave's load path directory cache.
@end deftypefn
command_line_path
@c command_line_path src/load-path.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} command_line_path (@dots{})
Return the command line path variable.

@seealso{path, addpath, rmpath, genpath, pathdef, savepath, pathsep}
@end deftypefn
restoredefaultpath
@c restoredefaultpath src/load-path.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} restoredefaultpath (@dots{})
Restore Octave's path to its initial state at startup.

@seealso{path, addpath, rmpath, genpath, pathdef, savepath, pathsep}
@end deftypefn
__pathorig__
@c __pathorig__ src/load-path.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {@var{val} =} __pathorig__ ()
Undocumented internal function.
@end deftypefn
path
@c path src/load-path.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} path (@dots{})
Modify or display Octave's load path.

If @var{nargin} and @var{nargout} are zero, display the elements of
Octave's load path in an easy to read format.

If @var{nargin} is zero and nargout is greater than zero, return the
current load path.

If @var{nargin} is greater than zero, concatenate the arguments,
separating them with @code{pathsep}.  Set the internal search path
to the result and return it.

No checks are made for duplicate elements.
@seealso{addpath, rmpath, genpath, pathdef, savepath, pathsep}
@end deftypefn
addpath
@c addpath src/load-path.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} addpath (@var{dir1}, @dots{})
@deftypefnx {Built-in Function} {} addpath (@var{dir1}, @dots{}, @var{option})
Add @var{dir1}, @dots{} to the current function search path.  If
@var{option} is "-begin" or 0 (the default), prepend the
directory name to the current path.  If @var{option} is "-end"
or 1, append the directory name to the current path.
Directories added to the path must exist.

In addition to accepting individual directory arguments, lists of
directory names separated by @code{pathsep} are also accepted.  For example:

@example
addpath ("dir1:/dir2:~/dir3");
@end example
@seealso{path, rmpath, genpath, pathdef, savepath, pathsep}
@end deftypefn
rmpath
@c rmpath src/load-path.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} rmpath (@var{dir1}, @dots{})
Remove @var{dir1}, @dots{} from the current function search path.

In addition to accepting individual directory arguments, lists of
directory names separated by @code{pathsep} are also accepted.  For example:

@example
rmpath ("dir1:/dir2:~/dir3");
@end example
@seealso{path, addpath, genpath, pathdef, savepath, pathsep}
@end deftypefn
load
@c load src/load-save.cc
-*- texinfo -*-
@deftypefn  {Command} {} load file
@deftypefnx {Command} {} load options file
@deftypefnx {Command} {} load options file v1 v2 @dots{}
@deftypefnx {Command} {S =} load ("options", "file", "v1", "v2", @dots{})
@deftypefnx {Command} {} load file options
@deftypefnx {Command} {} load file options v1 v2 @dots{}
@deftypefnx {Command} {S =} load ("file", "options", "v1", "v2", @dots{})
Load the named variables @var{v1}, @var{v2}, @dots{}, from the file
@var{file}.  If no variables are specified then all variables found in the
file will be loaded.  As with @code{save}, the list of variables to extract
can be full names or use a pattern syntax.  The format of the file is
automatically detected but may be overridden by supplying the appropriate
option.

If load is invoked using the functional form

@example
load ("-option1", @dots{}, "file", "v1", @dots{})
@end example

@noindent
then the @var{options}, @var{file}, and variable name arguments
(@var{v1}, @dots{}) must be specified as character strings.

If a variable that is not marked as global is loaded from a file when a
global symbol with the same name already exists, it is loaded in the
global symbol table.  Also, if a variable is marked as global in a file
and a local symbol exists, the local symbol is moved to the global
symbol table and given the value from the file.

If invoked with a single output argument, Octave returns data instead
of inserting variables in the symbol table.  If the data file contains
only numbers (TAB- or space-delimited columns), a matrix of values is
returned.  Otherwise, @code{load} returns a structure with members
 corresponding to the names of the variables in the file.

The @code{load} command can read data stored in Octave's text and
binary formats, and @sc{matlab}'s binary format.  If compiled with zlib
support, it can also load gzip-compressed files.  It will automatically
detect the type of file and do conversion from different floating point
formats (currently only IEEE big and little endian, though other formats
may be added in the future).

Valid options for @code{load} are listed in the following table.

@table @code
@item -force
This option is accepted for backward compatibility but is ignored.
Octave now overwrites variables currently in memory with
those of the same name found in the file.

@item -ascii
Force Octave to assume the file contains columns of numbers in text format
without any header or other information.  Data in the file will be loaded
as a single numeric matrix with the name of the variable derived from the
name of the file.

@item -binary
Force Octave to assume the file is in Octave's binary format.

@item -hdf5
Force Octave to assume the file is in @sc{hdf5} format.
(@sc{hdf5} is a free, portable binary format developed by the National
Center for Supercomputing Applications at the University of Illinois.)
Note that Octave can read @sc{hdf5} files not created by itself, but may
skip some datasets in formats that it cannot support.  This format is
only available if Octave was built with a link to the @sc{hdf5} libraries.

@item -import
This option is accepted for backward compatibility but is ignored.
Octave can now support multi-dimensional HDF data and automatically
modifies variable names if they are invalid Octave identifiers.

@item -mat
@itemx -mat-binary
@itemx -6
@itemx -v6
@itemx -7
@itemx -v7
Force Octave to assume the file is in @sc{matlab}'s version 6 or 7 binary
format.

@item  -mat4-binary
@itemx -4
@itemx -v4
@itemx -V4
Force Octave to assume the file is in the binary format written by
@sc{matlab} version 4.

@item -text
Force Octave to assume the file is in Octave's text format.
@end table
@seealso{save, dlmwrite, csvwrite, fwrite}
@end deftypefn
save
@c save src/load-save.cc
-*- texinfo -*-
@deftypefn  {Command} {} save file
@deftypefnx {Command} {} save options file
@deftypefnx {Command} {} save options file @var{v1} @var{v2} @dots{}
@deftypefnx {Command} {} save options file -struct @var{STRUCT} @var{f1} @var{f2} @dots{}
Save the named variables @var{v1}, @var{v2}, @dots{}, in the file
@var{file}.  The special filename @samp{-} may be used to write
output to the terminal.  If no variable names are listed, Octave saves
all the variables in the current scope.  Otherwise, full variable names or
pattern syntax can be used to specify the variables to save.
If the @option{-struct} modifier is used, fields @var{f1} @var{f2} @dots{}
of the scalar structure @var{STRUCT} are saved as if they were variables
with corresponding names.
Valid options for the @code{save} command are listed in the following table.
Options that modify the output format override the format specified by
@code{default_save_options}.

If save is invoked using the functional form

@example
save ("-option1", @dots{}, "file", "v1", @dots{})
@end example

@noindent
then the @var{options}, @var{file}, and variable name arguments
(@var{v1}, @dots{}) must be specified as character strings.

@table @code
@item -append
Append to the destination instead of overwriting.

@item -ascii
Save a single matrix in a text file without header or any other information.

@item -binary
Save the data in Octave's binary data format.

@item -float-binary
Save the data in Octave's binary data format but only using single
precision.  Only use this format if you know that all the
values to be saved can be represented in single precision.

@item -hdf5
Save the data in @sc{hdf5} format.
(HDF5 is a free, portable binary format developed by the National
Center for Supercomputing Applications at the University of Illinois.)
This format is only available if Octave was built with a link to the
@sc{hdf5} libraries.

@item -float-hdf5
Save the data in @sc{hdf5} format but only using single precision.
Only use this format if you know that all the
values to be saved can be represented in single precision.

@item -V7
@itemx -v7
@itemx -7
@itemx -mat7-binary
Save the data in @sc{matlab}'s v7 binary data format.

@item -V6
@itemx -v6
@itemx -6
@itemx -mat
@itemx -mat-binary
Save the data in @sc{matlab}'s v6 binary data format.

@item -V4
@itemx -v4
@itemx -4
@itemx -mat4-binary
Save the data in the binary format written by @sc{matlab} version 4.

@item -text
Save the data in Octave's text data format.  (default).

@item -zip
@itemx -z
Use the gzip algorithm to compress the file.  This works equally on files
that are compressed with gzip outside of octave, and gzip can equally be
used to convert the files for backward compatibility.
This option is only available if Octave was built with a link to the zlib
libraries.
@end table

The list of variables to save may use wildcard patterns containing
the following special characters:
@table @code
@item ?
Match any single character.

@item *
Match zero or more characters.

@item [ @var{list} ]
Match the list of characters specified by @var{list}.  If the first
character is @code{!} or @code{^}, match all characters except those
specified by @var{list}.  For example, the pattern @code{[a-zA-Z]} will
match all lower and uppercase alphabetic characters.

Wildcards may also be used in the field name specifications when using
the @option{-struct} modifier (but not in the struct name itself).

@end table

Except when using the @sc{matlab} binary data file format or the
@samp{-ascii} format, saving global
variables also saves the global status of the variable.  If the variable
is restored at a later time using @samp{load}, it will be restored as a
global variable.

The command

@example
save -binary data a b*
@end example

@noindent
saves the variable @samp{a} and all variables beginning with @samp{b} to
the file @file{data} in Octave's binary format.
@seealso{load, default_save_options, save_header_format_string, dlmread, csvread, fread}
@end deftypefn
crash_dumps_octave_core
@c crash_dumps_octave_core src/load-save.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} crash_dumps_octave_core ()
@deftypefnx {Built-in Function} {@var{old_val} =} crash_dumps_octave_core (@var{new_val})
@deftypefnx {Built-in Function} {} crash_dumps_octave_core (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave tries
to save all current variables to the file "octave-core" if it
crashes or receives a hangup, terminate or similar signal.

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.
@seealso{octave_core_file_limit, octave_core_file_name, octave_core_file_options}
@end deftypefn
default_save_options
@c default_save_options src/load-save.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} default_save_options ()
@deftypefnx {Built-in Function} {@var{old_val} =} default_save_options (@var{new_val})
@deftypefnx {Built-in Function} {} default_save_options (@var{new_val}, "local")
Query or set the internal variable that specifies the default options
for the @code{save} command, and defines the default format.
Typical values include @code{"-ascii"}, @code{"-text -zip"}.
The default value is @option{-text}.

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.
@seealso{save}
@end deftypefn
octave_core_file_limit
@c octave_core_file_limit src/load-save.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} octave_core_file_limit ()
@deftypefnx {Built-in Function} {@var{old_val} =} octave_core_file_limit (@var{new_val})
@deftypefnx {Built-in Function} {} octave_core_file_limit (@var{new_val}, "local")
Query or set the internal variable that specifies the maximum amount
of memory (in kilobytes) of the top-level workspace that Octave will
attempt to save when writing data to the crash dump file (the name of
the file is specified by @var{octave_core_file_name}).  If
@var{octave_core_file_options} flags specify a binary format,
then @var{octave_core_file_limit} will be approximately the maximum
size of the file.  If a text file format is used, then the file could
be much larger than the limit.  The default value is -1 (unlimited)

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.
@seealso{crash_dumps_octave_core, octave_core_file_name, octave_core_file_options}
@end deftypefn
octave_core_file_name
@c octave_core_file_name src/load-save.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} octave_core_file_name ()
@deftypefnx {Built-in Function} {@var{old_val} =} octave_core_file_name (@var{new_val})
@deftypefnx {Built-in Function} {} octave_core_file_name (@var{new_val}, "local")
Query or set the internal variable that specifies the name of the file
used for saving data from the top-level workspace if Octave aborts.
The default value is @code{"octave-core"}

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.
@seealso{crash_dumps_octave_core, octave_core_file_name, octave_core_file_options}
@end deftypefn
octave_core_file_options
@c octave_core_file_options src/load-save.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} octave_core_file_options ()
@deftypefnx {Built-in Function} {@var{old_val} =} octave_core_file_options (@var{new_val})
@deftypefnx {Built-in Function} {} octave_core_file_options (@var{new_val}, "local")
Query or set the internal variable that specifies the options used for
saving the workspace data if Octave aborts.  The value of
@code{octave_core_file_options} should follow the same format as the
options for the @code{save} function.  The default value is Octave's binary
format.

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.
@seealso{crash_dumps_octave_core, octave_core_file_name, octave_core_file_limit}
@end deftypefn
save_header_format_string
@c save_header_format_string src/load-save.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} save_header_format_string ()
@deftypefnx {Built-in Function} {@var{old_val} =} save_header_format_string (@var{new_val})
@deftypefnx {Built-in Function} {} save_header_format_string (@var{new_val}, "local")
Query or set the internal variable that specifies the format
string used for the comment line written at the beginning of
text-format data files saved by Octave.  The format string is
passed to @code{strftime} and should begin with the character
@samp{#} and contain no newline characters.  If the value of
@code{save_header_format_string} is the empty string,
the header comment is omitted from text-format data files.  The
default value is
@c Set example in small font to prevent overfull line

@smallexample
"# Created by Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@@HOST>"
@end smallexample

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.
@seealso{strftime, save}
@end deftypefn
save_precision
@c save_precision src/ls-oct-ascii.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} save_precision ()
@deftypefnx {Built-in Function} {@var{old_val} =} save_precision (@var{new_val})
@deftypefnx {Built-in Function} {} save_precision (@var{new_val}, "local")
Query or set the internal variable that specifies the number of
digits to keep when saving data in text format.

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.
@end deftypefn
abs
@c abs src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} abs (@var{z})
Compute the magnitude of @var{z}, defined as
@tex
$|z| = \sqrt{x^2 + y^2}$.
@end tex
@ifnottex
|@var{z}| = @code{sqrt (x^2 + y^2)}.
@end ifnottex

For example:

@example
@group
abs (3 + 4i)
     @result{} 5
@end group
@end example
@end deftypefn
acos
@c acos src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} acos (@var{x})
Compute the inverse cosine in radians for each element of @var{x}.
@seealso{cos, acosd}
@end deftypefn
acosh
@c acosh src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} acosh (@var{x})
Compute the inverse hyperbolic cosine for each element of @var{x}.
@seealso{cosh}
@end deftypefn
angle
@c angle src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} angle (@var{z})
See arg.
@end deftypefn
arg
@c arg src/mappers.cc
-*- texinfo -*-
@deftypefn  {Mapping Function} {} arg (@var{z})
@deftypefnx {Mapping Function} {} angle (@var{z})
Compute the argument of @var{z}, defined as,
@tex
$\theta = atan2 (y, x),$
@end tex
@ifnottex
@var{theta} = @code{atan2 (@var{y}, @var{x})},
@end ifnottex
in radians.

For example:

@example
@group
arg (3 + 4i)
     @result{} 0.92730
@end group
@end example
@end deftypefn
asin
@c asin src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} asin (@var{x})
Compute the inverse sine in radians for each element of @var{x}.
@seealso{sin, asind}
@end deftypefn
asinh
@c asinh src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} asinh (@var{x})
Compute the inverse hyperbolic sine for each element of @var{x}.
@seealso{sinh}
@end deftypefn
atan
@c atan src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} atan (@var{x})
Compute the inverse tangent in radians for each element of @var{x}.
@seealso{tan, atand}
@end deftypefn
atanh
@c atanh src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} atanh (@var{x})
Compute the inverse hyperbolic tangent for each element of @var{x}.
@seealso{tanh}
@end deftypefn
cbrt
@c cbrt src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} cbrt (@var{x})
Compute the real cube root of each element of @var{x}.
Unlike @code{@var{x}^(1/3)}, the result will be negative if @var{x} is
negative.
@seealso{nthroot}
@end deftypefn
ceil
@c ceil src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} ceil (@var{x})
Return the smallest integer not less than @var{x}.  This is equivalent to
rounding towards positive infinity.  If @var{x} is
complex, return @code{ceil (real (@var{x})) + ceil (imag (@var{x})) * I}.

@example
@group
ceil ([-2.7, 2.7])
   @result{}  -2   3
@end group
@end example
@seealso{floor, round, fix}
@end deftypefn
conj
@c conj src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} conj (@var{z})
Return the complex conjugate of @var{z}, defined as
@tex
$\bar{z} = x - iy$.
@end tex
@ifnottex
@code{conj (@var{z})} = @var{x} - @var{i}@var{y}.
@end ifnottex
@seealso{real, imag}
@end deftypefn
cos
@c cos src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} cos (@var{x})
Compute the cosine for each element of @var{x} in radians.
@seealso{acos, cosd, cosh}
@end deftypefn
cosh
@c cosh src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} cosh (@var{x})
Compute the hyperbolic cosine for each element of @var{x}.
@seealso{acosh, sinh, tanh}
@end deftypefn
erf
@c erf src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} erf (@var{z})
Compute the error function,
@tex
$$
 {\rm erf} (z) = {2 \over \sqrt{\pi}}\int_0^z e^{-t^2} dt
$$
@end tex
@ifnottex

@example
@group
@c spacing appears odd here, but is correct after Makeinfo
                          z
                         /
erf (z) = (2/sqrt (pi)) | e^(-t^2) dt
                         /
                      t=0
@end group
@end example

@end ifnottex
@seealso{erfc, erfcx, erfinv}
@end deftypefn
erfinv
@c erfinv src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} erfinv (@var{x})
Compute the inverse error function, i.e., @var{y} such that

@example
  erf (@var{y}) == @var{x}
@end example
@seealso{erf, erfc, erfcx}
@end deftypefn
erfc
@c erfc src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} erfc (@var{z})
Compute the complementary error function,
@tex
$1 - {\rm erf} (z)$.
@end tex
@ifnottex
@w{@code{1 - erf (@var{z})}}.
@end ifnottex
@seealso{erfcx, erf, erfinv}
@end deftypefn
erfcx
@c erfcx src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} erfcx (@var{z})
Compute the scaled complementary error function,
@tex
$$
 e^{z^2} {\rm erfc} (z) \equiv e^{z^2} (1 - {\rm erf} (z))
$$
@end tex
@ifnottex

@example
exp (z^2) * erfc (x)
@end example

@end ifnottex
@seealso{erfc, erf, erfinv}
@end deftypefn
exp
@c exp src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} exp (@var{x})
Compute
@tex
$e^{x}$
@end tex
@ifnottex
@code{e^x}
@end ifnottex
for each element of @var{x}.  To compute the matrix
exponential, see @ref{Linear Algebra}.
@seealso{log}
@end deftypefn
expm1
@c expm1 src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} expm1 (@var{x})
Compute
@tex
$ e^{x} - 1 $
@end tex
@ifnottex
@code{exp (@var{x}) - 1}
@end ifnottex
accurately in the neighborhood of zero.
@seealso{exp}
@end deftypefn
isfinite
@c isfinite src/mappers.cc
-*- texinfo -*-
@deftypefn  {Mapping Function} {} isfinite (@var{x})
@deftypefnx {Mapping Function} {} finite (@var{x})
Return a logical array which is true where the elements of @var{x} are
finite values and false where they are not.
For example:

@example
@group
finite ([13, Inf, NA, NaN])
     @result{} [ 1, 0, 0, 0 ]
@end group
@end example
@seealso{isinf, isnan, isna}
@end deftypefn
fix
@c fix src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} fix (@var{x})
Truncate fractional portion of @var{x} and return the integer portion.  This
is equivalent to rounding towards zero.  If @var{x} is complex, return
@code{fix (real (@var{x})) + fix (imag (@var{x})) * I}.

@example
@group
fix ([-2.7, 2.7])
   @result{} -2   2
@end group
@end example
@seealso{ceil, floor, round}
@end deftypefn
floor
@c floor src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} floor (@var{x})
Return the largest integer not greater than @var{x}.  This is equivalent to
rounding towards negative infinity.  If @var{x} is
complex, return @code{floor (real (@var{x})) + floor (imag (@var{x})) * I}.

@example
@group
floor ([-2.7, 2.7])
     @result{} -3   2
@end group
@end example
@seealso{ceil, round, fix}
@end deftypefn
gamma
@c gamma src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} gamma (@var{z})
Compute the Gamma function,
@tex
$$
 \Gamma (z) = \int_0^\infty t^{z-1} e^{-t} dt.
$$
@end tex
@ifnottex

@example
@group
@c spacing appears odd here, but is correct after Makeinfo
              infinity
             /
gamma (z) = | t^(z-1) exp (-t) dt.
             /
          t=0
@end group
@end example

@end ifnottex
@seealso{gammainc, lgamma}
@end deftypefn
imag
@c imag src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} imag (@var{z})
Return the imaginary part of @var{z} as a real number.
@seealso{real, conj}
@end deftypefn
isalnum
@c isalnum src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isalnum (@var{s})
Return a logical array which is true where the elements of @var{s} are
letters or digits and false where they are not.  This is equivalent to
(@code{isalpha (@var{s}) | isdigit (@var{s})}).
@seealso{isalpha, isdigit, ispunct, isspace, iscntrl}
@end deftypefn
isalpha
@c isalpha src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isalpha (@var{s})
Return a logical array which is true where the elements of @var{s} are
letters and false where they are not.  This is equivalent to
(@code{islower (@var{s}) | isupper (@var{s})}).
@seealso{isdigit, ispunct, isspace, iscntrl, isalnum, islower, isupper}
@end deftypefn
isascii
@c isascii src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isascii (@var{s})
Return a logical array which is true where the elements of @var{s} are
ASCII characters (in the range 0 to 127 decimal) and false where they are
not.
@end deftypefn
iscntrl
@c iscntrl src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} iscntrl (@var{s})
Return a logical array which is true where the elements of @var{s} are
control characters and false where they are not.
@seealso{ispunct, isspace, isalpha, isdigit}
@end deftypefn
isdigit
@c isdigit src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isdigit (@var{s})
Return a logical array which is true where the elements of @var{s} are
decimal digits (0-9) and false where they are not.
@seealso{isxdigit, isalpha, isletter, ispunct, isspace, iscntrl}
@end deftypefn
isinf
@c isinf src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isinf (@var{x})
Return a logical array which is true where the elements of @var{x} are
are infinite and false where they are not.
For example:

@example
@group
isinf ([13, Inf, NA, NaN])
     @result{} [ 0, 1, 0, 0 ]
@end group
@end example
@seealso{isfinite, isnan, isna}
@end deftypefn
isgraph
@c isgraph src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isgraph (@var{s})
Return a logical array which is true where the elements of @var{s} are
printable characters (but not the space character) and false where they are
not.
@seealso{isprint}
@end deftypefn
islower
@c islower src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} islower (@var{s})
Return a logical array which is true where the elements of @var{s} are
lowercase letters and false where they are not.
@seealso{isupper, isalpha, isletter, isalnum}
@end deftypefn
isna
@c isna src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isna (@var{x})
Return a logical array which is true where the elements of @var{x} are
NA (missing) values and false where they are not.
For example:

@example
@group
isna ([13, Inf, NA, NaN])
     @result{} [ 0, 0, 1, 0 ]
@end group
@end example
@seealso{isnan, isinf, isfinite}
@end deftypefn
isnan
@c isnan src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isnan (@var{x})
Return a logical array which is true where the elements of @var{x} are
NaN values and false where they are not.
NA values are also considered NaN values.  For example:

@example
@group
isnan ([13, Inf, NA, NaN])
     @result{} [ 0, 0, 1, 1 ]
@end group
@end example
@seealso{isna, isinf, isfinite}
@end deftypefn
isprint
@c isprint src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isprint (@var{s})
Return a logical array which is true where the elements of @var{s} are
printable characters (including the space character) and false where they
are not.
@seealso{isgraph}
@end deftypefn
ispunct
@c ispunct src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} ispunct (@var{s})
Return a logical array which is true where the elements of @var{s} are
punctuation characters and false where they are not.
@seealso{isalpha, isdigit, isspace, iscntrl}
@end deftypefn
isspace
@c isspace src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isspace (@var{s})
Return a logical array which is true where the elements of @var{s} are
whitespace characters (space, formfeed, newline, carriage return, tab, and
vertical tab) and false where they are not.
@seealso{iscntrl, ispunct, isalpha, isdigit}
@end deftypefn
isupper
@c isupper src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isupper (@var{s})
Return a logical array which is true where the elements of @var{s} are
uppercase letters and false where they are not.
@seealso{islower, isalpha, isletter, isalnum}
@end deftypefn
isxdigit
@c isxdigit src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} isxdigit (@var{s})
Return a logical array which is true where the elements of @var{s} are
hexadecimal digits (0-9 and @nospell{a-fA-F}).
@seealso{isdigit}
@end deftypefn
lgamma
@c lgamma src/mappers.cc
-*- texinfo -*-
@deftypefn  {Mapping Function} {} lgamma (@var{x})
@deftypefnx {Mapping Function} {} gammaln (@var{x})
Return the natural logarithm of the gamma function of @var{x}.
@seealso{gamma, gammainc}
@end deftypefn
log
@c log src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} log (@var{x})
Compute the natural logarithm,
@tex
$\ln{(x)},$
@end tex
@ifnottex
@code{ln (@var{x})},
@end ifnottex
for each element of @var{x}.  To compute the
matrix logarithm, see @ref{Linear Algebra}.
@seealso{exp, log1p, log2, log10, logspace}
@end deftypefn
log10
@c log10 src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} log10 (@var{x})
Compute the base-10 logarithm of each element of @var{x}.
@seealso{log, log2, logspace, exp}
@end deftypefn
log1p
@c log1p src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} log1p (@var{x})
Compute
@tex
$\ln{(1 + x)}$
@end tex
@ifnottex
@code{log (1 + @var{x})}
@end ifnottex
accurately in the neighborhood of zero.
@seealso{log, exp, expm1}
@end deftypefn
real
@c real src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} real (@var{z})
Return the real part of @var{z}.
@seealso{imag, conj}
@end deftypefn
round
@c round src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} round (@var{x})
Return the integer nearest to @var{x}.  If @var{x} is complex, return
@code{round (real (@var{x})) + round (imag (@var{x})) * I}.  If there
are two nearest integers, return the one further away from zero.

@example
@group
round ([-2.7, 2.7])
     @result{} -3   3
@end group
@end example
@seealso{ceil, floor, fix, roundb}
@end deftypefn
roundb
@c roundb src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} roundb (@var{x})
Return the integer nearest to @var{x}.  If there are two nearest
integers, return the even one (banker's rounding).  If @var{x} is complex,
return @code{roundb (real (@var{x})) + roundb (imag (@var{x})) * I}.
@seealso{round}
@end deftypefn
sign
@c sign src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} sign (@var{x})
Compute the @dfn{signum} function, which is defined as
@tex
$$
{\rm sign} (@var{x}) = \cases{1,&$x>0$;\cr 0,&$x=0$;\cr -1,&$x<0$.\cr}
$$
@end tex
@ifnottex

@example
@group
           -1, x < 0;
sign (x) =  0, x = 0;
            1, x > 0.
@end group
@end example

@end ifnottex

For complex arguments, @code{sign} returns @code{x ./ abs (@var{x})}.
@end deftypefn
sin
@c sin src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} sin (@var{x})
Compute the sine for each element of @var{x} in radians.
@seealso{asin, sind, sinh}
@end deftypefn
sinh
@c sinh src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} sinh (@var{x})
Compute the hyperbolic sine for each element of @var{x}.
@seealso{asinh, cosh, tanh}
@end deftypefn
sqrt
@c sqrt src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} sqrt (@var{x})
Compute the square root of each element of @var{x}.  If @var{x} is negative,
a complex result is returned.  To compute the matrix square root, see
@ref{Linear Algebra}.
@seealso{realsqrt, nthroot}
@end deftypefn
tan
@c tan src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} tan (@var{z})
Compute the tangent for each element of @var{x} in radians.
@seealso{atan, tand, tanh}
@end deftypefn
tanh
@c tanh src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} tanh (@var{x})
Compute hyperbolic tangent for each element of @var{x}.
@seealso{atanh, sinh, cosh}
@end deftypefn
toascii
@c toascii src/mappers.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} toascii (@var{s})
Return ASCII representation of @var{s} in a matrix.  For example:

@example
@group
toascii ("ASCII")
     @result{} [ 65, 83, 67, 73, 73 ]
@end group

@end example
@seealso{char}
@end deftypefn
tolower
@c tolower src/mappers.cc
-*- texinfo -*-
@deftypefn  {Mapping Function} {} tolower (@var{s})
@deftypefnx {Mapping Function} {} lower (@var{s})
Return a copy of the string or cell string @var{s}, with each uppercase
character replaced by the corresponding lowercase one; non-alphabetic
characters are left unchanged.  For example:

@example
@group
tolower ("MiXeD cAsE 123")
     @result{} "mixed case 123"
@end group
@end example
@seealso{toupper}
@end deftypefn
toupper
@c toupper src/mappers.cc
-*- texinfo -*-
@deftypefn  {Mapping Function} {} toupper (@var{s})
@deftypefnx {Mapping Function} {} upper (@var{s})
Return a copy of the string or cell string @var{s}, with each lowercase
character replaced by the corresponding uppercase one; non-alphabetic
characters are left unchanged.  For example:

@example
@group
toupper ("MiXeD cAsE 123")
     @result{} "MIXED CASE 123"
@end group
@end example
@seealso{tolower}
@end deftypefn
edit_history
@c edit_history src/oct-hist.cc
-*- texinfo -*-
@deftypefn {Command} {} edit_history [@var{first}] [@var{last}]
If invoked with no arguments, @code{edit_history} allows you to edit the
history list using the editor named by the variable @w{@env{EDITOR}}.  The
commands to be edited are first copied to a temporary file.  When you
exit the editor, Octave executes the commands that remain in the file.
It is often more convenient to use @code{edit_history} to define functions
rather than attempting to enter them directly on the command line.
By default, the block of commands is executed as soon as you exit the
editor.  To avoid executing any commands, simply delete all the lines
from the buffer before exiting the editor.

The @code{edit_history} command takes two optional arguments specifying
the history numbers of first and last commands to edit.  For example,
the command

@example
edit_history 13
@end example

@noindent
extracts all the commands from the 13th through the last in the history
list.  The command

@example
edit_history 13 169
@end example

@noindent
only extracts commands 13 through 169.  Specifying a larger number for
the first command than the last command reverses the list of commands
before placing them in the buffer to be edited.  If both arguments are
omitted, the previous command in the history list is used.
@seealso{run_history}
@end deftypefn
history
@c history src/oct-hist.cc
-*- texinfo -*-
@deftypefn {Command} {} history options
If invoked with no arguments, @code{history} displays a list of commands
that you have executed.  Valid options are:

@table @code
@item -w @var{file}
Write the current history to the file @var{file}.  If the name is
omitted, use the default history file (normally @file{~/.octave_hist}).

@item -r @var{file}
Read the file @var{file}, appending its contents to the current
history list.  If the name is omitted, use the default history file
(normally @file{~/.octave_hist}).

@item @var{n}
Display only the most recent @var{n} lines of history.

@item -q
Don't number the displayed lines of history.  This is useful for cutting
and pasting commands using the X Window System.
@end table

For example, to display the five most recent commands that you have
typed without displaying line numbers, use the command
@kbd{history -q 5}.
@end deftypefn
run_history
@c run_history src/oct-hist.cc
-*- texinfo -*-
@deftypefn {Command} {} run_history [@var{first}] [@var{last}]
Similar to @code{edit_history}, except that the editor is not invoked,
and the commands are simply executed as they appear in the history list.
@seealso{edit_history}
@end deftypefn
history_control
@c history_control src/oct-hist.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} history_control ()
@deftypefnx {Built-in Function} {@var{old_val} =} history_control (@var{new_val})
Query or set the internal variable that specifies how commands are saved
to the history list.  The default value is an empty character string,
but may be overridden by the environment variable
@w{@env{OCTAVE_HISTCONTROL}}.

The value of @code{history_control} is a colon-separated list of values
controlling how commands are saved on the history list.  If the list
of values includes @code{ignorespace}, lines which begin with a space
character are not saved in the history list.  A value of @code{ignoredups}
causes lines matching the previous history entry to not be saved.
A value of @code{ignoreboth} is shorthand for @code{ignorespace} and
@code{ignoredups}.  A value of @code{erasedups} causes all previous lines
matching the current line to be removed from the history list before that
line is saved.  Any value not in the above list is ignored.  If
@code{history_control} is the empty string, all commands are saved on
the history list, subject to the value of @code{saving_history}.
@seealso{history_file, history_size, history_timestamp_format_string, saving_history}
@end deftypefn
history_size
@c history_size src/oct-hist.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} history_size ()
@deftypefnx {Built-in Function} {@var{old_val} =} history_size (@var{new_val})
Query or set the internal variable that specifies how many entries
to store in the history file.  The default value is @code{1024},
but may be overridden by the environment variable @w{@env{OCTAVE_HISTSIZE}}.
@seealso{history_file, history_timestamp_format_string, saving_history}
@end deftypefn
history_file
@c history_file src/oct-hist.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} history_file ()
@deftypefnx {Built-in Function} {@var{old_val} =} history_file (@var{new_val})
Query or set the internal variable that specifies the name of the
file used to store command history.  The default value is
@file{~/.octave_hist}, but may be overridden by the environment
variable @w{@env{OCTAVE_HISTFILE}}.
@seealso{history_size, saving_history, history_timestamp_format_string}
@end deftypefn
history_timestamp_format_string
@c history_timestamp_format_string src/oct-hist.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} history_timestamp_format_string ()
@deftypefnx {Built-in Function} {@var{old_val} =} history_timestamp_format_string (@var{new_val})
@deftypefnx {Built-in Function} {} history_timestamp_format_string (@var{new_val}, "local")
Query or set the internal variable that specifies the format string
for the comment line that is written to the history file when Octave
exits.  The format string is passed to @code{strftime}.  The default
value is

@example
"# Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@@HOST>"
@end example

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.
@seealso{strftime, history_file, history_size, saving_history}
@end deftypefn
saving_history
@c saving_history src/oct-hist.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} saving_history ()
@deftypefnx {Built-in Function} {@var{old_val} =} saving_history (@var{new_val})
@deftypefnx {Built-in Function} {} saving_history (@var{new_val}, "local")
Query or set the internal variable that controls whether commands entered
on the command line are saved in the history file.

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.
@seealso{history_control, history_file, history_size, history_timestamp_format_string}
@end deftypefn
autoload
@c autoload src/oct-parse.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} autoload (@var{function}, @var{file})
Define @var{function} to autoload from @var{file}.

The second argument, @var{file}, should be an absolute file name or
a file name in the same directory as the function or script from which
the autoload command was run.  @var{file} should not depend on the
Octave load path.

Normally, calls to @code{autoload} appear in PKG_ADD script files that
are evaluated when a directory is added to the Octave's load path.  To
avoid having to hardcode directory names in @var{file}, if @var{file}
is in the same directory as the PKG_ADD script then

@example
autoload ("foo", "bar.oct");
@end example

@noindent
will load the function @code{foo} from the file @code{bar.oct}.  The above
when @code{bar.oct} is not in the same directory or uses like

@example
autoload ("foo", file_in_loadpath ("bar.oct"))
@end example

@noindent
are strongly discouraged, as their behavior might be unpredictable.

With no arguments, return a structure containing the current autoload map.
@seealso{PKG_ADD}
@end deftypefn
mfilename
@c mfilename src/oct-parse.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} mfilename ()
@deftypefnx {Built-in Function} {} mfilename ("fullpath")
@deftypefnx {Built-in Function} {} mfilename ("fullpathext")
Return the name of the currently executing file.  At the top-level,
return the empty string.  Given the argument @code{"fullpath"},
include the directory part of the file name, but not the extension.
Given the argument @code{"fullpathext"}, include the directory part
of the file name and the extension.
@end deftypefn
source
@c source src/oct-parse.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} source (@var{file})
Parse and execute the contents of @var{file}.  This is equivalent to
executing commands from a script file, but without requiring the file to
be named @file{@var{file}.m}.
@end deftypefn
feval
@c feval src/oct-parse.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} feval (@var{name}, @dots{})
Evaluate the function named @var{name}.  Any arguments after the first
are passed on to the named function.  For example,

@example
@group
feval ("acos", -1)
     @result{} 3.1416
@end group
@end example

@noindent
calls the function @code{acos} with the argument @samp{-1}.

The function @code{feval} can also be used with function handles of
any sort (@pxref{Function Handles}).  Historically, @code{feval} was
the only way to call user-supplied functions in strings, but
function handles are now preferred due to the cleaner syntax they
offer.  For example,

@example
@group
@var{f} = @@exp;
feval (@var{f}, 1)
     @result{} 2.7183
@var{f} (1)
     @result{} 2.7183
@end group
@end example

@noindent
are equivalent ways to call the function referred to by @var{f}.  If it
cannot be predicted beforehand that @var{f} is a function handle or the
function name in a string, @code{feval} can be used instead.
@end deftypefn
builtin
@c builtin src/oct-parse.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@dots{}]} builtin (@var{f}, @dots{})
Call the base function @var{f} even if @var{f} is overloaded to
another function for the given type signature.
@end deftypefn
eval
@c eval src/oct-parse.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} eval (@var{try})
@deftypefnx {Built-in Function} {} eval (@var{try}, @var{catch})
Parse the string @var{try} and evaluate it as if it were an Octave
program.  If that fails, evaluate the optional string @var{catch}.
The string @var{try} is evaluated in the current context,
so any results remain available after @code{eval} returns.

The following example makes the variable @var{a} with the approximate
value 3.1416 available.

@example
eval("a = acos(-1);");
@end example

If an error occurs during the evaluation of @var{try} the @var{catch}
string is evaluated, as the following example shows:

@example
@group
eval ('error ("This is a bad example");',
      'printf ("This error occurred:\n%s\n", lasterr ());');
     @print{} This error occurred:
        This is a bad example
@end group
@end example

Consider using try/catch blocks instead if you are only using @code{eval}
as an error-capturing mechanism rather than for the execution of arbitrary
code strings.
@seealso{evalin}
@end deftypefn
assignin
@c assignin src/oct-parse.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} assignin (@var{context}, @var{varname}, @var{value})
Assign @var{value} to @var{varname} in context @var{context}, which
may be either @code{"base"} or @code{"caller"}.
@seealso{evalin}
@end deftypefn
evalin
@c evalin src/oct-parse.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} evalin (@var{context}, @var{try})
@deftypefnx {Built-in Function} {} evalin (@var{context}, @var{try}, @var{catch})
Like @code{eval}, except that the expressions are evaluated in the
context @var{context}, which may be either @code{"caller"} or
@code{"base"}.
@seealso{eval, assignin}
@end deftypefn
__parser_debug_flag__
@c __parser_debug_flag__ src/oct-parse.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {@var{old_val} =} __parser_debug_flag__ (@var{new_val}))
Undocumented internal function.
@end deftypefn
__version_info__
@c __version_info__ src/octave.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {retval =} __version_info__ (@var{name}, @var{version}, @var{release}, @var{date})
Undocumented internal function.
@end deftypefn
argv
@c argv src/octave.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} argv ()
Return the command line arguments passed to Octave.  For example,
if you invoked Octave using the command

@example
octave --no-line-editing --silent
@end example

@noindent
@code{argv} would return a cell array of strings with the elements
@option{--no-line-editing} and @option{--silent}.

If you write an executable Octave script, @code{argv} will return the
list of arguments passed to the script.  @xref{Executable Octave Programs},
for an example of how to create an executable Octave script.
@end deftypefn
program_invocation_name
@c program_invocation_name src/octave.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} program_invocation_name ()
Return the name that was typed at the shell prompt to run Octave.

If executing a script from the command line (e.g., @code{octave foo.m})
or using an executable Octave script, the program name is set to the
name of the script.  @xref{Executable Octave Programs}, for an example of
how to create an executable Octave script.
@seealso{program_name}
@end deftypefn
program_name
@c program_name src/octave.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} program_name ()
Return the last component of the value returned by
@code{program_invocation_name}.
@seealso{program_invocation_name}
@end deftypefn
diary
@c diary src/pager.cc
-*- texinfo -*-
@deftypefn {Command} {} diary options
Record a list of all commands @emph{and} the output they produce, mixed
together just as you see them on your terminal.  Valid options are:

@table @code
@item on
Start recording your session in a file called @file{diary} in your
current working directory.

@item off
Stop recording your session in the diary file.

@item @var{file}
Record your session in the file named @var{file}.
@end table

With no arguments, @code{diary} toggles the current diary state.
@end deftypefn
more
@c more src/pager.cc
-*- texinfo -*-
@deftypefn  {Command} {} more
@deftypefnx {Command} {} more on
@deftypefnx {Command} {} more off
Turn output pagination on or off.  Without an argument, @code{more}
toggles the current state.
The current state can be determined via @code{page_screen_output}.
@end deftypefn
terminal_size
@c terminal_size src/pager.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} terminal_size ()
Return a two-element row vector containing the current size of the
terminal window in characters (rows and columns).
@seealso{list_in_columns}
@end deftypefn
page_output_immediately
@c page_output_immediately src/pager.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} page_output_immediately ()
@deftypefnx {Built-in Function} {@var{old_val} =} page_output_immediately (@var{new_val})
@deftypefnx {Built-in Function} {} page_output_immediately (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave sends
output to the pager as soon as it is available.  Otherwise, Octave
buffers its output and waits until just before the prompt is printed to
flush it to the pager.

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.
@end deftypefn
page_screen_output
@c page_screen_output src/pager.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} page_screen_output ()
@deftypefnx {Built-in Function} {@var{old_val} =} page_screen_output (@var{new_val})
@deftypefnx {Built-in Function} {} page_screen_output (@var{new_val}, "local")
Query or set the internal variable that controls whether output intended
for the terminal window that is longer than one page is sent through a
pager.  This allows you to view one screenful at a time.  Some pagers
(such as @code{less}---see @ref{Installation}) are also capable of moving
backward on the output.

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.
@end deftypefn
PAGER
@c PAGER src/pager.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} PAGER ()
@deftypefnx {Built-in Function} {@var{old_val} =} PAGER (@var{new_val})
@deftypefnx {Built-in Function} {} PAGER (@var{new_val}, "local")
Query or set the internal variable that specifies the program to use
to display terminal output on your system.  The default value is
normally @code{"less"}, @code{"more"}, or
@code{"pg"}, depending on what programs are installed on your system.
@xref{Installation}.

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.
@seealso{more, page_screen_output, page_output_immediately, PAGER_FLAGS}
@end deftypefn
PAGER_FLAGS
@c PAGER_FLAGS src/pager.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} PAGER_FLAGS ()
@deftypefnx {Built-in Function} {@var{old_val} =} PAGER_FLAGS (@var{new_val})
@deftypefnx {Built-in Function} {} PAGER_FLAGS (@var{new_val}, "local")
Query or set the internal variable that specifies the options to pass
to the pager.

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.
@seealso{PAGER}
@end deftypefn
rats
@c rats src/pr-output.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} rats (@var{x}, @var{len})
Convert @var{x} into a rational approximation represented as a string.
You can convert the string back into a matrix as follows:

@example
@group
   r = rats(hilb(4));
   x = str2num(r)
@end group
@end example

The optional second argument defines the maximum length of the string
representing the elements of @var{x}.  By default @var{len} is 9.
@seealso{format, rat}
@end deftypefn
disp
@c disp src/pr-output.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} disp (@var{x})
Display the value of @var{x}.  For example:

@example
@group
disp ("The value of pi is:"), disp (pi)

     @print{} the value of pi is:
     @print{} 3.1416
@end group
@end example

@noindent
Note that the output from @code{disp} always ends with a newline.

If an output value is requested, @code{disp} prints nothing and
returns the formatted output in a string.
@seealso{fdisp}
@end deftypefn
fdisp
@c fdisp src/pr-output.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} fdisp (@var{fid}, @var{x})
Display the value of @var{x} on the stream @var{fid}.  For example:

@example
@group
fdisp (stdout, "The value of pi is:"), fdisp (stdout, pi)

     @print{} the value of pi is:
     @print{} 3.1416
@end group
@end example

@noindent
Note that the output from @code{fdisp} always ends with a newline.
@seealso{disp}
@end deftypefn
format
@c format src/pr-output.cc
-*- texinfo -*-
@deftypefn  {Command} {} format
@deftypefnx {Command} {} format options
Reset or specify the format of the output produced by @code{disp} and
Octave's normal echoing mechanism.  This command only affects the display
of numbers but not how they are stored or computed.  To change the internal
representation from the default double use one of the conversion functions
such as @code{single}, @code{uint8}, @code{int64}, etc.

By default, Octave displays 5 significant digits in a human readable form
(option @samp{short} paired with @samp{loose} format for matrices).
If @code{format} is invoked without any options, this default format
is restored.

Valid formats for floating point numbers are listed in the following
table.

@table @code
@item short
Fixed point format with 5 significant figures in a field that is a maximum
of 10 characters wide.  (default).

If Octave is unable to format a matrix so that columns line up on the
decimal point and all numbers fit within the maximum field width then
it switches to an exponential @samp{e} format.

@item long
Fixed point format with 15 significant figures in a field that is a maximum
of 20 characters wide.

As with the @samp{short} format, Octave will switch to an exponential
@samp{e} format if it is unable to format a matrix properly using the
current format.

@item short e
@itemx long e
Exponential format.  The number to be represented is split between a mantissa
and an exponent (power of 10).  The mantissa has 5 significant digits in the
short format and 15 digits in the long format.
For example, with the @samp{short e} format, @code{pi} is displayed as
@code{3.1416e+00}.

@item short E
@itemx long E
Identical to @samp{short e} or @samp{long e} but displays an uppercase
@samp{E} to indicate the exponent.
For example, with the @samp{long E} format, @code{pi} is displayed as
@code{3.14159265358979E+00}.

@item short g
@itemx long g
Optimally choose between fixed point and exponential format based on
the magnitude of the number.
For example, with the @samp{short g} format,
@code{pi .^ [2; 4; 8; 16; 32]} is displayed as

@example
@group
ans =

      9.8696
      97.409
      9488.5
  9.0032e+07
  8.1058e+15
@end group
@end example

@item short eng
@itemx long eng
Identical to @samp{short e} or @samp{long e} but displays the value
using an engineering format, where the exponent is divisible by 3. For
example, with the @samp{short eng} format, @code{10 * pi} is displayed as
@code{31.4159e+00}.

@item long G
@itemx short G
Identical to @samp{short g} or @samp{long g} but displays an uppercase
@samp{E} to indicate the exponent.

@item free
@itemx none
Print output in free format, without trying to line up columns of
matrices on the decimal point.  This also causes complex numbers to be
formatted as numeric pairs like this @samp{(0.60419, 0.60709)} instead
of like this @samp{0.60419 + 0.60709i}.
@end table

The following formats affect all numeric output (floating point and
integer types).

@table @code
@item  +
@itemx + @var{chars}
@itemx plus
@itemx plus @var{chars}
Print a @samp{+} symbol for nonzero matrix elements and a space for zero
matrix elements.  This format can be very useful for examining the
structure of a large sparse matrix.

The optional argument @var{chars} specifies a list of 3 characters to use
for printing values greater than zero, less than zero and equal to zero.
For example, with the @samp{+ "+-."} format, @code{[1, 0, -1; -1, 0, 1]}
is displayed as

@example
@group
ans =

+.-
-.+
@end group
@end example

@item bank
Print in a fixed format with two digits to the right of the decimal
point.

@item native-hex
Print the hexadecimal representation of numbers as they are stored in
memory.  For example, on a workstation which stores 8 byte real values
in IEEE format with the least significant byte first, the value of
@code{pi} when printed in @code{native-hex} format is
@code{400921fb54442d18}.

@item hex
The same as @code{native-hex}, but always print the most significant
byte first.

@item native-bit
Print the bit representation of numbers as stored in memory.
For example, the value of @code{pi} is

@example
@group
01000000000010010010000111111011
01010100010001000010110100011000
@end group
@end example

(shown here in two 32 bit sections for typesetting purposes) when
printed in native-bit format on a workstation which stores 8 byte real values
in IEEE format with the least significant byte first.

@item bit
The same as @code{native-bit}, but always print the most significant
bits first.

@item rat
Print a rational approximation, i.e., values are approximated
as the ratio of small integers.
For example, with the @samp{rat} format,
@code{pi} is displayed as @code{355/113}.
@end table

The following two options affect the display of all matrices.

@table @code
@item compact
Remove blank lines around column number labels and between
matrices producing more compact output with more data per page.

@item loose
Insert blank lines above and below column number labels and between matrices
to produce a more readable output with less data per page.  (default).
@end table
@seealso{fixed_point_format, output_max_field_width, output_precision, split_long_rows, rats}
@end deftypefn
fixed_point_format
@c fixed_point_format src/pr-output.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} fixed_point_format ()
@deftypefnx {Built-in Function} {@var{old_val} =} fixed_point_format (@var{new_val})
@deftypefnx {Built-in Function} {} fixed_point_format (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave will
use a scaled format to print matrix values such that the largest
element may be written with a single leading digit with the scaling
factor is printed on the first line of output.  For example:

@example
@group
octave:1> logspace (1, 7, 5)'
ans =

  1.0e+07  *

  0.00000
  0.00003
  0.00100
  0.03162
  1.00000
@end group
@end example

@noindent
Notice that first value appears to be zero when it is actually 1.  For
this reason, you should be careful when setting
@code{fixed_point_format} to a nonzero value.

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.
@seealso{format, output_max_field_width, output_precision}
@end deftypefn
print_empty_dimensions
@c print_empty_dimensions src/pr-output.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} print_empty_dimensions ()
@deftypefnx {Built-in Function} {@var{old_val} =} print_empty_dimensions (@var{new_val})
@deftypefnx {Built-in Function} {} print_empty_dimensions (@var{new_val}, "local")
Query or set the internal variable that controls whether the
dimensions of empty matrices are printed along with the empty matrix
symbol, @samp{[]}.  For example, the expression

@example
zeros (3, 0)
@end example

@noindent
will print

@example
ans = [](3x0)
@end example

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.
@seealso{format}
@end deftypefn
split_long_rows
@c split_long_rows src/pr-output.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} split_long_rows ()
@deftypefnx {Built-in Function} {@var{old_val} =} split_long_rows (@var{new_val})
@deftypefnx {Built-in Function} {} split_long_rows (@var{new_val}, "local")
Query or set the internal variable that controls whether rows of a matrix
may be split when displayed to a terminal window.  If the rows are split,
Octave will display the matrix in a series of smaller pieces, each of
which can fit within the limits of your terminal width and each set of
rows is labeled so that you can easily see which columns are currently
being displayed.  For example:

@example
@group
octave:13> rand (2,10)
ans =

 Columns 1 through 6:

  0.75883  0.93290  0.40064  0.43818  0.94958  0.16467
  0.75697  0.51942  0.40031  0.61784  0.92309  0.40201

 Columns 7 through 10:

  0.90174  0.11854  0.72313  0.73326
  0.44672  0.94303  0.56564  0.82150
@end group
@end example

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.
@seealso{format}
@end deftypefn
output_max_field_width
@c output_max_field_width src/pr-output.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} output_max_field_width ()
@deftypefnx {Built-in Function} {@var{old_val} =} output_max_field_width (@var{new_val})
@deftypefnx {Built-in Function} {} output_max_field_width (@var{new_val}, "local")
Query or set the internal variable that specifies the maximum width
of a numeric output field.

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.
@seealso{format, fixed_point_format, output_precision}
@end deftypefn
output_precision
@c output_precision src/pr-output.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} output_precision ()
@deftypefnx {Built-in Function} {@var{old_val} =} output_precision (@var{new_val})
@deftypefnx {Built-in Function} {} output_precision (@var{new_val}, "local")
Query or set the internal variable that specifies the minimum number of
significant figures to display for numeric output.

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.
@seealso{format, fixed_point_format, output_max_field_width}
@end deftypefn
__profiler_enable__
@c __profiler_enable__ src/profiler.cc
-*- texinfo -*-
@deftypefn {Function File} __profiler_enable ()
Undocumented internal function.
@end deftypefn
__profiler_reset__
@c __profiler_reset__ src/profiler.cc
-*- texinfo -*-
@deftypefn {Function File} __profiler_reset ()
Undocumented internal function.
@end deftypefn
__profiler_data__
@c __profiler_data__ src/profiler.cc
-*- texinfo -*-
@deftypefn {Function File} __profiler_data ()
Undocumented internal function.
@end deftypefn
SIG
@c SIG src/sighandlers.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} SIG ()
Return a structure containing Unix signal names and their defined values.
@end deftypefn
debug_on_interrupt
@c debug_on_interrupt src/sighandlers.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} debug_on_interrupt ()
@deftypefnx {Built-in Function} {@var{old_val} =} debug_on_interrupt (@var{new_val})
@deftypefnx {Built-in Function} {} debug_on_interrupt (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave will try
to enter debugging mode when it receives an interrupt signal (typically
generated with @kbd{C-c}).  If a second interrupt signal is received
before reaching the debugging mode, a normal interrupt will occur.

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.
@end deftypefn
sighup_dumps_octave_core
@c sighup_dumps_octave_core src/sighandlers.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} sighup_dumps_octave_core ()
@deftypefnx {Built-in Function} {@var{old_val} =} sighup_dumps_octave_core (@var{new_val})
@deftypefnx {Built-in Function} {} sighup_dumps_octave_core (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave tries
to save all current variables to the file "octave-core" if it receives
a hangup signal.

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.
@end deftypefn
sigterm_dumps_octave_core
@c sigterm_dumps_octave_core src/sighandlers.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} sigterm_dumps_octave_core ()
@deftypefnx {Built-in Function} {@var{old_val} =} sigterm_dumps_octave_core (@var{new_val})
@deftypefnx {Built-in Function} {} sigterm_dumps_octave_core (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave tries
to save all current variables to the file "octave-core" if it receives
a terminate signal.

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.
@end deftypefn
issparse
@c issparse src/sparse.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} issparse (@var{x})
Return true if @var{x} is a sparse matrix.
@seealso{ismatrix}
@end deftypefn
sparse
@c sparse src/sparse.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{s} =} sparse (@var{a})
@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})
@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv})
@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, "unique")
@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{m}, @var{n})
Create a sparse matrix from the full matrix or row, column, value triplets.
If @var{a} is a full matrix, convert it to a sparse matrix representation,
removing all zero values in the process.

Given the integer index vectors @var{i} and @var{j}, a 1-by-@code{nnz} vector
of real of complex values @var{sv}, overall dimensions @var{m} and @var{n}
of the sparse matrix.  The argument @code{nzmax} is ignored but accepted for
compatibility with @sc{matlab}.  If @var{m} or @var{n} are not specified
their values are derived from the maximum index in the vectors @var{i} and
@var{j} as given by @code{@var{m} = max (@var{i})},
@code{@var{n} = max (@var{j})}.

@strong{Note}: if multiple values are specified with the same
@var{i}, @var{j} indices, the corresponding values in @var{s} will
be added.

The following are all equivalent:

@example
@group
s = sparse (i, j, s, m, n)
s = sparse (i, j, s, m, n, "summation")
s = sparse (i, j, s, m, n, "sum")
@end group
@end example

Given the option "unique". if more than two values are specified for the
same @var{i}, @var{j} indices, the last specified value will be used.

@code{sparse(@var{m}, @var{n})} is equivalent to
@code{sparse ([], [], [], @var{m}, @var{n}, 0)}

If any of @var{sv}, @var{i} or @var{j} are scalars, they are expanded
to have a common size.
@seealso{full}
@end deftypefn
spalloc
@c spalloc src/sparse.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{s} =} spalloc (@var{m}, @var{n}, @var{nz})
Create an @var{m}-by-@var{n} sparse matrix with pre-allocated space for at
most @var{nz} nonzero elements.  This is useful for building the matrix
incrementally by a sequence of indexed assignments.  Subsequent indexed
assignments will reuse the pre-allocated memory, provided they are of one of
the simple forms

@itemize
@item @code{@var{s}(I:J) = @var{x}}

@item @code{@var{s}(:,I:J) = @var{x}}

@item @code{@var{s}(K:L,I:J) = @var{x}}
@end itemize

@b{and} that the following conditions are met:

@itemize
@item the assignment does not decrease nnz(@var{S}).

@item after the assignment, nnz(@var{S}) does not exceed @var{nz}.

@item no index is out of bounds.
@end itemize

Partial movement of data may still occur, but in general the assignment will
be more memory and time-efficient under these circumstances.  In particular,
it is possible to efficiently build a pre-allocated sparse matrix from
contiguous block of columns.

The amount of pre-allocated memory for a given matrix may be queried using
the function @code{nzmax}.
@seealso{nzmax, sparse}
@end deftypefn
char
@c char src/strfns.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} char (@var{x})
@deftypefnx {Built-in Function} {} char (@var{x}, @dots{})
@deftypefnx {Built-in Function} {} char (@var{s1}, @var{s2}, @dots{})
@deftypefnx {Built-in Function} {} char (@var{cell_array})
Create a string array from one or more numeric matrices, character
matrices, or cell arrays.  Arguments are concatenated vertically.
The returned values are padded with blanks as needed to make each row
of the string array have the same length.  Empty input strings are
significant and will concatenated in the output.

For numerical input, each element is converted
to the corresponding ASCII character.  A range error results if an input
is outside the ASCII range (0-255).

For cell arrays, each element is concatenated separately.  Cell arrays
converted through
@code{char} can mostly be converted back with @code{cellstr}.
For example:

@example
@group
char ([97, 98, 99], "", @{"98", "99", 100@}, "str1", ["ha", "lf"])
     @result{} ["abc    "
         "       "
         "98     "
         "99     "
         "d      "
         "str1   "
         "half   "]
@end group
@end example
@seealso{strvcat, cellstr}
@end deftypefn
strvcat
@c strvcat src/strfns.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} strvcat (@var{x})
@deftypefnx {Built-in Function} {} strvcat (@var{x}, @dots{})
@deftypefnx {Built-in Function} {} strvcat (@var{s1}, @var{s2}, @dots{})
@deftypefnx {Built-in Function} {} strvcat (@var{cell_array})
Create a character array from one or more numeric matrices, character
matrices, or cell arrays.  Arguments are concatenated vertically.
The returned values are padded with blanks as needed to make each row
of the string array have the same length.  Unlike @code{char}, empty
strings are removed and will not appear in the output.

For numerical input, each element is converted
to the corresponding ASCII character.  A range error results if an input
is outside the ASCII range (0-255).

For cell arrays, each element is concatenated separately.  Cell arrays
converted through
@code{strvcat} can mostly be converted back with @code{cellstr}.
For example:

@example
@group
strvcat ([97, 98, 99], "", @{"98", "99", 100@}, "str1", ["ha", "lf"])
     @result{} ["abc    "
         "98     "
         "99     "
         "d      "
         "str1   "
         "half   "]
@end group
@end example
@seealso{char, strcat, cstrcat}
@end deftypefn
ischar
@c ischar src/strfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} ischar (@var{x})
Return true if @var{x} is a character array.
@seealso{isfloat, isinteger, islogical, isnumeric, iscellstr, isa}
@end deftypefn
strcmp
@c strcmp src/strfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} strcmp (@var{s1}, @var{s2})
Return 1 if the character strings @var{s1} and @var{s2} are the same,
and 0 otherwise.

If either @var{s1} or @var{s2} is a cell array of strings, then an array
of the same size is returned, containing the values described above for
every member of the cell array.  The other argument may also be a cell
array of strings (of the same size or with only one element), char matrix
or character string.

@strong{Caution:} For compatibility with @sc{matlab}, Octave's strcmp
function returns 1 if the character strings are equal, and 0 otherwise.
This is just the opposite of the corresponding C library function.
@seealso{strcmpi, strncmp, strncmpi}
@end deftypefn
strncmp
@c strncmp src/strfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} strncmp (@var{s1}, @var{s2}, @var{n})
Return 1 if the first @var{n} characters of strings @var{s1} and @var{s2} are
the same, and 0 otherwise.

@example
@group
strncmp ("abce", "abcd", 3)
     @result{} 1
@end group
@end example

If either @var{s1} or @var{s2} is a cell array of strings, then an array
of the same size is returned, containing the values described above for
every member of the cell array.  The other argument may also be a cell
array of strings (of the same size or with only one element), char matrix
or character string.

@example
@group
strncmp ("abce", @{"abcd", "bca", "abc"@}, 3)
     @result{} [1, 0, 1]
@end group
@end example

@strong{Caution:} For compatibility with @sc{matlab}, Octave's strncmp
function returns 1 if the character strings are equal, and 0 otherwise.
This is just the opposite of the corresponding C library function.
@seealso{strncmpi, strcmp, strcmpi}
@end deftypefn
strcmpi
@c strcmpi src/strfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} strcmpi (@var{s1}, @var{s2})
Return 1 if the character strings @var{s1} and @var{s2} are the same,
disregarding case of alphabetic characters, and 0 otherwise.

If either @var{s1} or @var{s2} is a cell array of strings, then an array
of the same size is returned, containing the values described above for
every member of the cell array.  The other argument may also be a cell
array of strings (of the same size or with only one element), char matrix
or character string.

@strong{Caution:} For compatibility with @sc{matlab}, Octave's strcmp
function returns 1 if the character strings are equal, and 0 otherwise.
This is just the opposite of the corresponding C library function.

@strong{Caution:} National alphabets are not supported.
@seealso{strcmp, strncmp, strncmpi}
@end deftypefn
strncmpi
@c strncmpi src/strfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} strncmpi (@var{s1}, @var{s2}, @var{n})
Return 1 if the first @var{n} character of @var{s1} and @var{s2} are the
same, disregarding case of alphabetic characters, and 0 otherwise.

If either @var{s1} or @var{s2} is a cell array of strings, then an array
of the same size is returned, containing the values described above for
every member of the cell array.  The other argument may also be a cell
array of strings (of the same size or with only one element), char matrix
or character string.

@strong{Caution:} For compatibility with @sc{matlab}, Octave's strncmpi
function returns 1 if the character strings are equal, and 0 otherwise.
This is just the opposite of the corresponding C library function.

@strong{Caution:} National alphabets are not supported.
@seealso{strncmp, strcmp, strcmpi}
@end deftypefn
list_in_columns
@c list_in_columns src/strfns.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} list_in_columns (@var{arg}, @var{width})
Return a string containing the elements of @var{arg} listed in
columns with an overall maximum width of @var{width}.  The argument
@var{arg} must be a cell array of character strings or a character array.
If @var{width} is not specified, the width of the terminal screen is used.
Newline characters are used to break the lines in the output string.
For example:
@c Set example in small font to prevent overfull line

@smallexample
@group
list_in_columns (@{"abc", "def", "ghijkl", "mnop", "qrs", "tuv"@}, 20)
     @result{} ans = abc     mnop
            def     qrs
            ghijkl  tuv

whos ans
     @result{}
     Variables in the current scope:

       Attr Name        Size                     Bytes  Class
       ==== ====        ====                     =====  =====
            ans         1x37                        37  char

     Total is 37 elements using 37 bytes
@end group
@end smallexample

@seealso{terminal_size}
@end deftypefn
ignore_function_time_stamp
@c ignore_function_time_stamp src/symtab.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} ignore_function_time_stamp ()
@deftypefnx {Built-in Function} {@var{old_val} =} ignore_function_time_stamp (@var{new_val})
Query or set the internal variable that controls whether Octave checks
the time stamp on files each time it looks up functions defined in
function files.  If the internal variable is set to @code{"system"},
Octave will not automatically recompile function files in subdirectories of
@file{@var{octave-home}/lib/@var{version}} if they have changed since
they were last compiled, but will recompile other function files in the
search path if they change.  If set to @code{"all"}, Octave will not
recompile any function files unless their definitions are removed with
@code{clear}.  If set to "none", Octave will always check time stamps
on files to determine whether functions defined in function files
need to recompiled.
@end deftypefn
__current_scope__
@c __current_scope__ src/symtab.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{scope}, @var{context}]} __dump_symtab_info__ ()
Undocumented internal function.
@end deftypefn
__dump_symtab_info__
@c __dump_symtab_info__ src/symtab.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} __dump_symtab_info__ ()
@deftypefnx {Built-in Function} {} __dump_symtab_info__ (@var{scope})
@deftypefnx {Built-in Function} {} __dump_symtab_info__ ("scopes")
@deftypefnx {Built-in Function} {} __dump_symtab_info__ ("functions")
Undocumented internal function.
@end deftypefn
dup2
@c dup2 src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{fid}, @var{msg}] =} dup2 (@var{old}, @var{new})
Duplicate a file descriptor.

If successful, @var{fid} is greater than zero and contains the new file
ID@.  Otherwise, @var{fid} is negative and @var{msg} contains a
system-dependent error message.
@end deftypefn
exec
@c exec src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} exec (@var{file}, @var{args})
Replace current process with a new process.  Calling @code{exec} without
first calling @code{fork} will terminate your current Octave process and
replace it with the program named by @var{file}.  For example,

@example
exec ("ls" "-l")
@end example

@noindent
will run @code{ls} and return you to your shell prompt.

If successful, @code{exec} does not return.  If @code{exec} does return,
@var{err} will be nonzero, and @var{msg} will contain a system-dependent
error message.
@end deftypefn
popen2
@c popen2 src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args})
Start a subprocess with two-way communication.  The name of the process
is given by @var{command}, and @var{args} is an array of strings
containing options for the command.  The file identifiers for the input
and output streams of the subprocess are returned in @var{in} and
@var{out}.  If execution of the command is successful, @var{pid}
contains the process ID of the subprocess.  Otherwise, @var{pid} is
@minus{}1.

For example:

@example
[in, out, pid] = popen2 ("sort", "-r");
fputs (in, "these\nare\nsome\nstrings\n");
fclose (in);
EAGAIN = errno ("EAGAIN");
done = false;
do
  s = fgets (out);
  if (ischar (s))
    fputs (stdout, s);
  elseif (errno () == EAGAIN)
    sleep (0.1);
    fclear (out);
  else
    done = true;
  endif
until (done)
fclose (out);
waitpid (pid);
     @print{} these
     @print{} strings
     @print{} some
     @print{} are
@end example

Note that @code{popen2}, unlike @code{popen}, will not "reap" the
child process.  If you don't use @code{waitpid} to check the child's
exit status, it will linger until Octave exits.
@end deftypefn
fcntl
@c fcntl src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} fcntl (@var{fid}, @var{request}, @var{arg})
Change the properties of the open file @var{fid}.  The following values
may be passed as @var{request}:

@vtable @code
@item F_DUPFD
Return a duplicate file descriptor.

@item F_GETFD
Return the file descriptor flags for @var{fid}.

@item F_SETFD
Set the file descriptor flags for @var{fid}.

@item F_GETFL
Return the file status flags for @var{fid}.  The following codes may be
returned (some of the flags may be undefined on some systems).

@vtable @code
@item O_RDONLY
Open for reading only.

@item O_WRONLY
Open for writing only.

@item O_RDWR
Open for reading and writing.

@item O_APPEND
Append on each write.

@item O_CREAT
Create the file if it does not exist.

@item O_NONBLOCK
Non-blocking mode.

@item O_SYNC
Wait for writes to complete.

@item O_ASYNC
Asynchronous I/O.
@end vtable

@item F_SETFL
Set the file status flags for @var{fid} to the value specified by
@var{arg}.  The only flags that can be changed are @w{@code{O_APPEND}} and
@w{@code{O_NONBLOCK}}.
@end vtable

If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a
system-dependent error message.
@end deftypefn
fork
@c fork src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{pid}, @var{msg}] =} fork ()
Create a copy of the current process.

Fork can return one of the following values:

@table @asis
@item > 0
You are in the parent process.  The value returned from @code{fork} is
the process id of the child process.  You should probably arrange to
wait for any child processes to exit.

@item 0
You are in the child process.  You can call @code{exec} to start another
process.  If that fails, you should probably call @code{exit}.

@item < 0
The call to @code{fork} failed for some reason.  You must take evasive
action.  A system dependent error message will be waiting in @var{msg}.
@end table
@end deftypefn
getpgrp
@c getpgrp src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {pgid =} getpgrp ()
Return the process group id of the current process.
@end deftypefn
getpid
@c getpid src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {pid =} getpid ()
Return the process id of the current process.
@end deftypefn
getppid
@c getppid src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {pid =} getppid ()
Return the process id of the parent process.
@end deftypefn
getegid
@c getegid src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {egid =} getegid ()
Return the effective group id of the current process.
@end deftypefn
getgid
@c getgid src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {gid =} getgid ()
Return the real group id of the current process.
@end deftypefn
geteuid
@c geteuid src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {euid =} geteuid ()
Return the effective user id of the current process.
@end deftypefn
getuid
@c getuid src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {uid =} getuid ()
Return the real user id of the current process.
@end deftypefn
kill
@c kill src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} kill (@var{pid}, @var{sig})
Send signal @var{sig} to process @var{pid}.

If @var{pid} is positive, then signal @var{sig} is sent to @var{pid}.

If @var{pid} is 0, then signal @var{sig} is sent to every process
in the process group of the current process.

If @var{pid} is -1, then signal @var{sig} is sent to every process
except process 1.

If @var{pid} is less than -1, then signal @var{sig} is sent to every
process in the process group @var{-pid}.

If @var{sig} is 0, then no signal is sent, but error checking is still
performed.

Return 0 if successful, otherwise return -1.
@end deftypefn
lstat
@c lstat src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{symlink})
Return a structure @var{info} containing information about the symbolic link
@var{symlink}.  The function outputs are described in the documentation for
@code{stat}.
@seealso{stat}
@end deftypefn
mkfifo
@c mkfifo src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} mkfifo (@var{name}, @var{mode})
Create a @var{fifo} special file named @var{name} with file mode @var{mode}

If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a
system-dependent error message.
@end deftypefn
pipe
@c pipe src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{read_fd}, @var{write_fd}, @var{err}, @var{msg}] =} pipe ()
Create a pipe and return the reading and writing ends of the pipe
into @var{read_fd} and @var{write_fd} respectively.

If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a
system-dependent error message.
@end deftypefn
stat
@c stat src/syscalls.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{file})
@deftypefnx {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{fid})
@deftypefnx {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{file})
@deftypefnx {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{fid})
Return a structure @var{info} containing the following information about
@var{file} or file identifier @var{fid}.

@table @code
@item dev
ID of device containing a directory entry for this file.

@item ino
File number of the file.

@item mode
File mode, as an integer.  Use the functions @w{@code{S_ISREG}},
@w{@code{S_ISDIR}}, @w{@code{S_ISCHR}}, @w{@code{S_ISBLK}}, @w{@code{S_ISFIFO}},
@w{@code{S_ISLNK}}, or @w{@code{S_ISSOCK}} to extract information from this
value.

@item modestr
File mode, as a string of ten letters or dashes as would be returned by
@kbd{ls -l}.

@item nlink
Number of links.

@item uid
User ID of file's owner.

@item gid
Group ID of file's group.

@item rdev
ID of device for block or character special files.

@item size
Size in bytes.

@item atime
Time of last access in the same form as time values returned from
@code{time}.  @xref{Timing Utilities}.

@item mtime
Time of last modification in the same form as time values returned from
@code{time}.  @xref{Timing Utilities}.

@item ctime
Time of last file status change in the same form as time values
returned from @code{time}.  @xref{Timing Utilities}.

@item blksize
Size of blocks in the file.

@item blocks
Number of blocks allocated for file.
@end table

If the call is successful @var{err} is 0 and @var{msg} is an empty
string.  If the file does not exist, or some other error occurs, @var{s}
is an empty matrix, @var{err} is @minus{}1, and @var{msg} contains the
corresponding system error message.

If @var{file} is a symbolic link, @code{stat} will return information
about the actual file that is referenced by the link.  Use @code{lstat}
if you want information about the symbolic link itself.

For example:

@example
[s, err, msg] = stat ("/vmlinuz")
      @result{} s =
        @{
          atime = 855399756
          rdev = 0
          ctime = 847219094
          uid = 0
          size = 389218
          blksize = 4096
          mtime = 847219094
          gid = 6
          nlink = 1
          blocks = 768
          mode = -rw-r--r--
          modestr = -rw-r--r--
          ino = 9316
          dev = 2049
        @}
     @result{} err = 0
     @result{} msg =
@end example
@end deftypefn
S_ISREG
@c S_ISREG src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} S_ISREG (@var{mode})
Return true if @var{mode} corresponds to a regular file.  The value
of @var{mode} is assumed to be returned from a call to @code{stat}.
@seealso{stat, lstat}
@end deftypefn
S_ISDIR
@c S_ISDIR src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} S_ISDIR (@var{mode})
Return true if @var{mode} corresponds to a directory.  The value
of @var{mode} is assumed to be returned from a call to @code{stat}.
@seealso{stat, lstat}
@end deftypefn
S_ISCHR
@c S_ISCHR src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} S_ISCHR (@var{mode})
Return true if @var{mode} corresponds to a character device.  The value
of @var{mode} is assumed to be returned from a call to @code{stat}.
@seealso{stat, lstat}
@end deftypefn
S_ISBLK
@c S_ISBLK src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} S_ISBLK (@var{mode})
Return true if @var{mode} corresponds to a block device.  The value
of @var{mode} is assumed to be returned from a call to @code{stat}.
@seealso{stat, lstat}
@end deftypefn
S_ISFIFO
@c S_ISFIFO src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} S_ISFIFO (@var{mode})
Return true if @var{mode} corresponds to a fifo.  The value
of @var{mode} is assumed to be returned from a call to @code{stat}.
@seealso{stat, lstat}
@end deftypefn
S_ISLNK
@c S_ISLNK src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} S_ISLNK (@var{mode})
Return true if @var{mode} corresponds to a symbolic link.  The value
of @var{mode} is assumed to be returned from a call to @code{stat}.
@seealso{stat, lstat}
@end deftypefn
S_ISSOCK
@c S_ISSOCK src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} S_ISSOCK (@var{mode})
Return true if @var{mode} corresponds to a socket.  The value
of @var{mode} is assumed to be returned from a call to @code{stat}.
@seealso{stat, lstat}
@end deftypefn
gethostname
@c gethostname src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} gethostname ()
Return the hostname of the system where Octave is running.
@end deftypefn
uname
@c uname src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{uts}, @var{err}, @var{msg}] =} uname ()
Return system information in the structure.  For example:

@example
@group
uname ()
     @result{} @{
           sysname = x86_64
           nodename = segfault
           release = 2.6.15-1-amd64-k8-smp
           version = Linux
           machine = #2 SMP Thu Feb 23 04:57:49 UTC 2006
         @}
@end group
@end example

If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a
system-dependent error message.
@end deftypefn
unlink
@c unlink src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} unlink (@var{file})
Delete the file named @var{file}.

If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a
system-dependent error message.
@end deftypefn
waitpid
@c waitpid src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{pid}, @var{status}, @var{msg}] =} waitpid (@var{pid}, @var{options})
Wait for process @var{pid} to terminate.  The @var{pid} argument can be:

@table @asis
@item @minus{}1
Wait for any child process.

@item 0
Wait for any child process whose process group ID is equal to that of
the Octave interpreter process.

@item > 0
Wait for termination of the child process with ID @var{pid}.
@end table

The @var{options} argument can be a bitwise OR of zero or more of
the following constants:

@table @code
@item 0
Wait until signal is received or a child process exits (this is the
default if the @var{options} argument is missing).

@item WNOHANG
Do not hang if status is not immediately available.

@item WUNTRACED
Report the status of any child processes that are stopped, and whose
status has not yet been reported since they stopped.

@item WCONTINUE
Return if a stopped child has been resumed by delivery of @code{SIGCONT}.
This value may not be meaningful on all systems.
@end table

If the returned value of @var{pid} is greater than 0, it is the process
ID of the child process that exited.  If an error occurs, @var{pid} will
be less than zero and @var{msg} will contain a system-dependent error
message.  The value of @var{status} contains additional system-dependent
information about the subprocess that exited.
@seealso{WCONTINUE, WCOREDUMP, WEXITSTATUS, WIFCONTINUED, WIFSIGNALED, WIFSTOPPED, WNOHANG, WSTOPSIG, WTERMSIG, WUNTRACED}
@end deftypefn
WIFEXITED
@c WIFEXITED src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} WIFEXITED (@var{status})
Given @var{status} from a call to @code{waitpid}, return true if the
child terminated normally.
@seealso{waitpid, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WEXITSTATUS
@c WEXITSTATUS src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} WEXITSTATUS (@var{status})
Given @var{status} from a call to @code{waitpid}, return the exit
status of the child.  This function should only be employed if
@code{WIFEXITED} returned true.
@seealso{waitpid, WIFEXITED, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WIFSIGNALED
@c WIFSIGNALED src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} WIFSIGNALED (@var{status})
Given @var{status} from a call to @code{waitpid}, return true if the
child process was terminated by a signal.
@seealso{waitpid, WIFEXITED, WEXITSTATUS, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WTERMSIG
@c WTERMSIG src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} WTERMSIG (@var{status})
Given @var{status} from a call to @code{waitpid}, return the number of
the signal that caused the child process to terminate.  This function
should only be employed if @code{WIFSIGNALED} returned true.
@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WCOREDUMP
@c WCOREDUMP src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} WCOREDUMP (@var{status})
Given @var{status} from a call to @code{waitpid}, return true if the
child produced a core dump.  This function should only be employed if
@code{WIFSIGNALED} returned true.  The macro used to implement this
function is not specified in POSIX.1-2001 and is not available on some
Unix implementations (e.g., AIX, SunOS).
@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WIFSTOPPED
@c WIFSTOPPED src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} WIFSTOPPED (@var{status})
Given @var{status} from a call to @code{waitpid}, return true if the
child process was stopped by delivery of a signal; this is only
possible if the call was done using @code{WUNTRACED} or when the child
is being traced (see ptrace(2)).
@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WSTOPSIG
@c WSTOPSIG src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} WSTOPSIG (@var{status})
Given @var{status} from a call to @code{waitpid}, return the number of
the signal which caused the child to stop.  This function should only
be employed if @code{WIFSTOPPED} returned true.
@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WIFCONTINUED}
@end deftypefn
WIFCONTINUED
@c WIFCONTINUED src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} WIFCONTINUED (@var{status})
Given @var{status} from a call to @code{waitpid}, return true if the
child process was resumed by delivery of @code{SIGCONT}.
@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG}
@end deftypefn
canonicalize_file_name
@c canonicalize_file_name src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {[@var{cname}, @var{status}, @var{msg}]} canonicalize_file_name (@var{name})
Return the canonical name of file @var{name}.
@end deftypefn
F_DUPFD
@c F_DUPFD src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} F_DUPFD ()
Return the numerical value to pass to @code{fcntl} to return a
duplicate file descriptor.
@seealso{fcntl, F_GETFD, F_GETFL, F_SETFD, F_SETFL}
@end deftypefn
F_GETFD
@c F_GETFD src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} F_GETFD ()
Return the numerical value to pass to @code{fcntl} to return the
file descriptor flags.
@seealso{fcntl, F_DUPFD, F_GETFL, F_SETFD, F_SETFL}
@end deftypefn
F_GETFL
@c F_GETFL src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} F_GETFL ()
Return the numerical value to pass to @code{fcntl} to return the
file status flags.
@seealso{fcntl, F_DUPFD, F_GETFD, F_SETFD, F_SETFL}
@end deftypefn
F_SETFD
@c F_SETFD src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} F_SETFD ()
Return the numerical value to pass to @code{fcntl} to set the file
descriptor flags.
@seealso{fcntl, F_DUPFD, F_GETFD, F_GETFL, F_SETFL}
@end deftypefn
F_SETFL
@c F_SETFL src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} F_SETFL ()
Return the numerical value to pass to @code{fcntl} to set the file
status flags.
@seealso{fcntl, F_DUPFD, F_GETFD, F_GETFL, F_SETFD}
@end deftypefn
O_APPEND
@c O_APPEND src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} O_APPEND ()
Return the numerical value of the file status flag that may be
returned by @code{fcntl} to indicate each write operation appends,
or that may be passed to @code{fcntl} to set the write mode to append.
@seealso{fcntl, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
@end deftypefn
O_ASYNC
@c O_ASYNC src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} O_ASYNC ()
Return the numerical value of the file status flag that may be
returned by @code{fcntl} to indicate asynchronous I/O.
@seealso{fcntl, O_APPEND, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
@end deftypefn
O_CREAT
@c O_CREAT src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} O_CREAT ()
Return the numerical value of the file status flag that may be
returned by @code{fcntl} to indicate that a file should be
created if it does not exist.
@seealso{fcntl, O_APPEND, O_ASYNC, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
@end deftypefn
O_EXCL
@c O_EXCL src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} O_EXCL ()
Return the numerical value of the file status flag that may be
returned by @code{fcntl} to indicate that file locking is used.
@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
@end deftypefn
O_NONBLOCK
@c O_NONBLOCK src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} O_NONBLOCK ()
Return the numerical value of the file status flag that may be
returned by @code{fcntl} to indicate that non-blocking I/O is in use,
or that may be passsed to @code{fcntl} to set non-blocking I/O.
@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
@end deftypefn
O_RDONLY
@c O_RDONLY src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} O_RDONLY ()
Return the numerical value of the file status flag that may be
returned by @code{fcntl} to indicate that a file is open for
reading only.
@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
@end deftypefn
O_RDWR
@c O_RDWR src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} O_RDWR ()
Return the numerical value of the file status flag that may be
returned by @code{fcntl} to indicate that a file is open for both
reading and writing.
@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_SYNC, O_TRUNC, O_WRONLY}
@end deftypefn
O_SYNC
@c O_SYNC src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} O_SYNC ()
Return the numerical value of the file status flag that may be
returned by @code{fcntl} to indicate that a file is open for
synchronous I/O.
@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY}
@end deftypefn
O_TRUNC
@c O_TRUNC src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} O_TRUNC ()
Return the numerical value of the file status flag that may be
returned by @code{fcntl} to indicate that if file exists, it should
be truncated when writing.
@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_WRONLY}
@end deftypefn
O_WRONLY
@c O_WRONLY src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} O_WRONLY ()
Return the numerical value of the file status flag that may be
returned by @code{fcntl} to indicate that a file is open for
writing only.
@seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC}
@end deftypefn
WNOHANG
@c WNOHANG src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} WNOHANG ()
Return the numerical value of the option argument that may be
passed to @code{waitpid} to indicate that it should return its
status immediately instead of waiting for a process to exit.
@seealso{waitpid, WUNTRACED, WCONTINUE}
@end deftypefn
WUNTRACED
@c WUNTRACED src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} WUNTRACED ()
Return the numerical value of the option argument that may be
passed to @code{waitpid} to indicate that it should also return
if the child process has stopped but is not traced via the
@code{ptrace} system call
@seealso{waitpid, WNOHANG, WCONTINUE}
@end deftypefn
WCONTINUE
@c WCONTINUE src/syscalls.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} WCONTINUE ()
Return the numerical value of the option argument that may be
passed to @code{waitpid} to indicate that it should also return
if a stopped child has been resumed by delivery of a @code{SIGCONT}
signal.
@seealso{waitpid, WNOHANG, WUNTRACED}
@end deftypefn
clc
@c clc src/sysdep.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} clc ()
@deftypefnx {Built-in Function} {} home ()
Clear the terminal screen and move the cursor to the upper left corner.
@end deftypefn
getenv
@c getenv src/sysdep.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} getenv (@var{var})
Return the value of the environment variable @var{var}.  For example,

@example
getenv ("PATH")
@end example

@noindent
returns a string containing the value of your path.
@end deftypefn
putenv
@c putenv src/sysdep.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} putenv (@var{var}, @var{value})
@deftypefnx {Built-in Function} {} setenv (@var{var}, @var{value})
Set the value of the environment variable @var{var} to @var{value}.
@end deftypefn
kbhit
@c kbhit src/sysdep.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} kbhit ()
Read a single keystroke from the keyboard.  If called with one
argument, don't wait for a keypress.  For example,

@example
x = kbhit ();
@end example

@noindent
will set @var{x} to the next character typed at the keyboard as soon as
it is typed.

@example
x = kbhit (1);
@end example

@noindent
identical to the above example, but don't wait for a keypress,
returning the empty string if no key is available.
@end deftypefn
pause
@c pause src/sysdep.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} pause (@var{seconds})
Suspend the execution of the program.  If invoked without any arguments,
Octave waits until you type a character.  With a numeric argument, it
pauses for the given number of seconds.  For example, the following
statement prints a message and then waits 5 seconds before clearing the
screen.

@example
@group
fprintf (stderr, "wait please...\n");
pause (5);
clc;
@end group
@end example
@end deftypefn
sleep
@c sleep src/sysdep.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} sleep (@var{seconds})
Suspend the execution of the program for the given number of seconds.
@end deftypefn
usleep
@c usleep src/sysdep.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} usleep (@var{microseconds})
Suspend the execution of the program for the given number of
microseconds.  On systems where it is not possible to sleep for periods
of time less than one second, @code{usleep} will pause the execution for
@code{round (@var{microseconds} / 1e6)} seconds.
@end deftypefn
isieee
@c isieee src/sysdep.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isieee ()
Return true if your computer @emph{claims} to conform to the IEEE standard
for floating point calculations.  No actual tests are performed.
@end deftypefn
native_float_format
@c native_float_format src/sysdep.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} native_float_format ()
Return the native floating point format as a string
@end deftypefn
tilde_expand
@c tilde_expand src/sysdep.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} tilde_expand (@var{string})
Perform tilde expansion on @var{string}.  If @var{string} begins with a
tilde character, (@samp{~}), all of the characters preceding the first
slash (or all characters, if there is no slash) are treated as a
possible user name, and the tilde and the following characters up to the
slash are replaced by the home directory of the named user.  If the
tilde is followed immediately by a slash, the tilde is replaced by the
home directory of the user running Octave.  For example:

@example
@group
tilde_expand ("~joeuser/bin")
     @result{} "/home/joeuser/bin"
tilde_expand ("~/bin")
     @result{} "/home/jwe/bin"
@end group
@end example
@end deftypefn
quit
@c quit src/toplev.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} exit (@var{status})
@deftypefnx {Built-in Function} {} quit (@var{status})
Exit the current Octave session.  If the optional integer value
@var{status} is supplied, pass that value to the operating system as the
Octave's exit status.  The default value is zero.
@end deftypefn
warranty
@c warranty src/toplev.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} warranty ()
Describe the conditions for copying and distributing Octave.
@end deftypefn
system
@c system src/toplev.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} system ("@var{string}")
@deftypefnx {Built-in Function} {} system ("@var{string}", @var{return_output})
@deftypefnx {Built-in Function} {} system ("@var{string}", @var{return_output}, @var{type})
@deftypefnx {Built-in Function} {[@var{status}, @var{output}] =} system (@dots{})
Execute a shell command specified by @var{string}.
If the optional argument @var{type} is "async", the process
is started in the background and the process ID of the child process
is returned immediately.  Otherwise, the child process is started and
Octave waits until it exits.  If the @var{type} argument is omitted, it
defaults to the value "sync".

If @var{system} is called with one or more output arguments, or if the
optional argument @var{return_output} is true and the subprocess is started
synchronously, then the output from the command is returned as a variable.  
Otherwise, if the subprocess is executed synchronously, its output is sent
to the standard output.  To send the output of a command executed with
@code{system} through the pager, use a command like

@example
@group
[output, text] = system ("cmd");
disp (text);
@end group
@end example

@noindent
or

@example
printf ("%s\n", nthargout (2, "system", "cmd"));
@end example

The @code{system} function can return two values.  The first is the
exit status of the command and the second is any output from the
command that was written to the standard output stream.  For example,

@example
[status, output] = system ("echo foo; exit 2");
@end example

@noindent
will set the variable @code{output} to the string @samp{foo}, and the
variable @code{status} to the integer @samp{2}.

For commands run asynchronously, @var{status} is the process id of the
command shell that is started to run the command.
@seealso{unix, dos}
@end deftypefn
atexit
@c atexit src/toplev.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} atexit (@var{fcn})
@deftypefnx {Built-in Function} {} atexit (@var{fcn}, @var{flag})
Register a function to be called when Octave exits.  For example,

@example
@group
function last_words ()
  disp ("Bye bye");
endfunction
atexit ("last_words");
@end group
@end example

@noindent
will print the message "Bye bye" when Octave exits.

The additional argument @var{flag} will register or unregister
@var{fcn} from the list of functions to be called when Octave
exits.  If @var{flag} is true, the function is registered, and if
@var{flag} is false, it is unregistered.  For example,
after registering the function @code{last_words} above,

@example
atexit ("last_words", false);
@end example

@noindent
will remove the function from the list and Octave will not call
@code{last_words} when it exits.

Note that @code{atexit} only removes the first occurrence of a function
from the list, so if a function was placed in the list multiple
times with @code{atexit}, it must also be removed from the list
multiple times.
@end deftypefn
octave_config_info
@c octave_config_info src/toplev.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} octave_config_info ()
@deftypefnx {Built-in Function} {} octave_config_info (@var{option})
Return a structure containing configuration and installation
information for Octave.

If @var{option} is a string, return the configuration information for the
specified option.

@end deftypefn
isvarname
@c isvarname src/utils.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isvarname (@var{name})
Return true if @var{name} is a valid variable name.
@seealso{iskeyword, exist, who}
@end deftypefn
file_in_loadpath
@c file_in_loadpath src/utils.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} file_in_loadpath (@var{file})
@deftypefnx {Built-in Function} {} file_in_loadpath (@var{file}, "all")

Return the absolute name of @var{file} if it can be found in
the list of directories specified by @code{path}.
If no file is found, return an empty character string.

If the first argument is a cell array of strings, search each
directory of the loadpath for element of the cell array and return
the first that matches.

If the second optional argument @code{"all"} is supplied, return
a cell array containing the list of all files that have the same
name in the path.  If no files are found, return an empty cell array.
@seealso{file_in_path, path}
@end deftypefn
file_in_path
@c file_in_path src/utils.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} file_in_path (@var{path}, @var{file})
@deftypefnx {Built-in Function} {} file_in_path (@var{path}, @var{file}, "all")
Return the absolute name of @var{file} if it can be found in
@var{path}.  The value of @var{path} should be a colon-separated list of
directories in the format described for @code{path}.  If no file
is found, return an empty character string.  For example:

@example
@group
file_in_path (EXEC_PATH, "sh")
     @result{} "/bin/sh"
@end group
@end example

If the second argument is a cell array of strings, search each
directory of the path for element of the cell array and return
the first that matches.

If the third optional argument @code{"all"} is supplied, return
a cell array containing the list of all files that have the same
name in the path.  If no files are found, return an empty cell array.
@seealso{file_in_loadpath}
@end deftypefn
do_string_escapes
@c do_string_escapes src/utils.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} do_string_escapes (@var{string})
Convert special characters in @var{string} to their escaped forms.
@end deftypefn
undo_string_escapes
@c undo_string_escapes src/utils.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} undo_string_escapes (@var{s})
Convert special characters in strings back to their escaped forms.  For
example, the expression

@example
bell = "\a";
@end example

@noindent
assigns the value of the alert character (control-g, ASCII code 7) to
the string variable @code{bell}.  If this string is printed, the
system will ring the terminal bell (if it is possible).  This is
normally the desired outcome.  However, sometimes it is useful to be
able to print the original representation of the string, with the
special characters replaced by their escape sequences.  For example,

@example
@group
octave:13> undo_string_escapes (bell)
ans = \a
@end group
@end example

@noindent
replaces the unprintable alert character with its printable
representation.
@end deftypefn
is_absolute_filename
@c is_absolute_filename src/utils.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} is_absolute_filename (@var{file})
Return true if @var{file} is an absolute filename.
@seealso{is_rooted_relative_filename, make_absolute_filename, isdir}
@end deftypefn
is_rooted_relative_filename
@c is_rooted_relative_filename src/utils.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} is_rooted_relative_filename (@var{file})
Return true if @var{file} is a rooted-relative filename.
@seealso{is_absolute_filename, make_absolute_filename, isdir}
@end deftypefn
make_absolute_filename
@c make_absolute_filename src/utils.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} make_absolute_filename (@var{file})
Return the full name of @var{file}, relative to the current directory.
@seealso{is_absolute_filename, is_rooted_relative_filename, isdir}
@end deftypefn
find_dir_in_path
@c find_dir_in_path src/utils.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} find_dir_in_path (@var{dir})
@deftypefnx {Built-in Function} {} find_dir_in_path (@var{dir}, "all")
Return the full name of the path element matching @var{dir}.  The
match is performed at the end of each path element.  For example, if
@var{dir} is @code{"foo/bar"}, it matches the path element
@code{"/some/dir/foo/bar"}, but not @code{"/some/dir/foo/bar/baz"}
or @code{"/some/dir/allfoo/bar"}.

The second argument is optional.  If it is supplied, return a cell array
containing all name matches rather than just the first.
@end deftypefn
errno
@c errno src/utils.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{err} =} errno ()
@deftypefnx {Built-in Function} {@var{err} =} errno (@var{val})
@deftypefnx {Built-in Function} {@var{err} =} errno (@var{name})
Return the current value of the system-dependent variable errno,
set its value to @var{val} and return the previous value, or return
the named error code given @var{name} as a character string, or -1
if @var{name} is not found.
@end deftypefn
errno_list
@c errno_list src/utils.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} errno_list ()
Return a structure containing the system-dependent errno values.
@end deftypefn
isindex
@c isindex src/utils.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} isindex (@var{ind})
@deftypefnx {Built-in Function} {} isindex (@var{ind}, @var{n})
Return true if @var{ind} is a valid index.  Valid indices are
either positive integers (although possibly of real data type), or logical
arrays.  If present, @var{n} specifies the maximum extent of the dimension
to be indexed.  When possible the internal result is cached so that
subsequent indexing using @var{ind} will not perform the check again.
@end deftypefn
isglobal
@c isglobal src/variables.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isglobal (@var{name})
Return true if @var{name} is a globally visible variable.
For example:

@example
@group
global x
isglobal ("x")
     @result{} 1
@end group
@end example
@seealso{isvarname, exist}
@end deftypefn
exist
@c exist src/variables.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} exist (@var{name}, @var{type})
Return 1 if the name exists as a variable, 2 if the name is an
absolute file name, an ordinary file in Octave's @code{path}, or (after
appending @samp{.m}) a function file in Octave's @code{path}, 3 if the
name is a @samp{.oct} or @samp{.mex} file in Octave's @code{path},
5 if the name is a built-in function, 7 if the name is a directory, or 103
if the name is a function not associated with a file (entered on
the command line).

Otherwise, return 0.

This function also returns 2 if a regular file called @var{name}
exists in Octave's search path.  If you want information about
other types of files, you should use some combination of the functions
@code{file_in_path} and @code{stat} instead.

If the optional argument @var{type} is supplied, check only for
symbols of the specified type.  Valid types are

@table @asis
@item "var"
Check only for variables.

@item "builtin"
Check only for built-in functions.

@item "file"
Check only for files.

@item "dir"
Check only for directories.
@end table
@seealso{file_in_loadpath}
@end deftypefn
who
@c who src/variables.cc
-*- texinfo -*-
@deftypefn  {Command} {} who
@deftypefnx {Command} {} who pattern @dots{}
@deftypefnx {Command} {} who option pattern @dots{}
@deftypefnx {Command} {C =} who ("pattern", @dots{})
List currently defined variables matching the given patterns.  Valid
pattern syntax is the same as described for the @code{clear} command.
If no patterns are supplied, all variables are listed.
By default, only variables visible in the local scope are displayed.

The following are valid options but may not be combined.

@table @code
@item global
List variables in the global scope rather than the current scope.

@item -regexp
The patterns are considered to be regular expressions when matching the
variables to display.  The same pattern syntax accepted by
the @code{regexp} function is used.

@item -file
The next argument is treated as a filename.  All variables found within the
specified file are listed.  No patterns are accepted when reading variables
from a file.
@end table

If called as a function, return a cell array of defined variable names
matching the given patterns.
@seealso{whos, isglobal, isvarname, exist, regexp}
@end deftypefn
whos
@c whos src/variables.cc
-*- texinfo -*-
@deftypefn  {Command} {} whos
@deftypefnx {Command} {} whos pattern @dots{}
@deftypefnx {Command} {} whos option pattern @dots{}
@deftypefnx {Command} {S =} whos ("pattern", @dots{})
Provide detailed information on currently defined variables matching the
given patterns.  Options and pattern syntax are the same as for the
@code{who} command.  Extended information about each variable is
summarized in a table with the following default entries.

@table @asis
@item Attr
Attributes of the listed variable.  Possible attributes are:
@table @asis
@item blank
Variable in local scope

@item @code{a}
Automatic variable.  An automatic variable is one created by the
interpreter, for example @code{argn}.

@item @code{c}
Variable of complex type.

@item @code{f}
Formal parameter (function argument).

@item @code{g}
Variable with global scope.

@item @code{p}
Persistent variable.
@end table

@item Name
The name of the variable.

@item Size
The logical size of the variable.  A scalar is 1x1, a vector is
@nospell{1xN} or @nospell{Nx1}, a 2-D matrix is @nospell{MxN}.

@item Bytes
The amount of memory currently used to store the variable.

@item Class
The class of the variable.  Examples include double, single, char, uint16,
cell, and struct.
@end table

The table can be customized to display more or less information through
the function @code{whos_line_format}.

If @code{whos} is called as a function, return a struct array of defined
variable names matching the given patterns.  Fields in the structure
describing each variable are: name, size, bytes, class, global, sparse,
complex, nesting, persistent.
@seealso{who, whos_line_format}
@end deftypefn
mlock
@c mlock src/variables.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} mlock ()
Lock the current function into memory so that it can't be cleared.
@seealso{munlock, mislocked, persistent}
@end deftypefn
munlock
@c munlock src/variables.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} munlock ()
@deftypefnx {Built-in Function} {} munlock (@var{fcn})
Unlock the named function @var{fcn}.  If no function is named
then unlock the current function.
@seealso{mlock, mislocked, persistent}
@end deftypefn
mislocked
@c mislocked src/variables.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} mislocked ()
@deftypefnx {Built-in Function} {} mislocked (@var{fcn})
Return true if the named function @var{fcn} is locked.  If no function is
named then return true if the current function is locked.
@seealso{mlock, munlock, persistent}
@end deftypefn
clear
@c clear src/variables.cc
-*- texinfo -*-
@deftypefn {Command} {} clear [options] pattern @dots{}
Delete the names matching the given patterns from the symbol table.  The
pattern may contain the following special characters:

@table @code
@item ?
Match any single character.

@item *
Match zero or more characters.

@item [ @var{list} ]
Match the list of characters specified by @var{list}.  If the first
character is @code{!} or @code{^}, match all characters except those
specified by @var{list}.  For example, the pattern @samp{[a-zA-Z]} will
match all lowercase and uppercase alphabetic characters.
@end table

For example, the command

@example
clear foo b*r
@end example

@noindent
clears the name @code{foo} and all names that begin with the letter
@code{b} and end with the letter @code{r}.

If @code{clear} is called without any arguments, all user-defined
variables (local and global) are cleared from the symbol table.  If
@code{clear} is called with at least one argument, only the visible
names matching the arguments are cleared.  For example, suppose you have
defined a function @code{foo}, and then hidden it by performing the
assignment @code{foo = 2}.  Executing the command @kbd{clear foo} once
will clear the variable definition and restore the definition of
@code{foo} as a function.  Executing @kbd{clear foo} a second time will
clear the function definition.

The following options are available in both long and short form
@table @code
@item -all, -a
Clears all local and global user-defined variables and all functions
from the symbol table.

@item -exclusive, -x
Clears the variables that don't match the following pattern.

@item -functions, -f
Clears the function names and the built-in symbols names.

@item -global, -g
Clears the global symbol names.

@item -variables, -v
Clears the local variable names.

@item -classes, -c
Clears the class structure table and clears all objects.

@item -regexp, -r
The arguments are treated as regular expressions as any variables that
match will be cleared.
@end table
With the exception of @code{exclusive}, all long options can be used
without the dash as well.
@end deftypefn
whos_line_format
@c whos_line_format src/variables.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} whos_line_format ()
@deftypefnx {Built-in Function} {@var{old_val} =} whos_line_format (@var{new_val})
@deftypefnx {Built-in Function} {} whos_line_format (@var{new_val}, "local")
Query or set the format string used by the command @code{whos}.

A full format string is:
@c Set example in small font to prevent overfull line

@smallexample
%[modifier]<command>[:width[:left-min[:balance]]];
@end smallexample

The following command sequences are available:

@table @code
@item %a
Prints attributes of variables (g=global, p=persistent,
f=formal parameter, a=automatic variable).

@item %b
Prints number of bytes occupied by variables.

@item %c
Prints class names of variables.

@item %e
Prints elements held by variables.

@item %n
Prints variable names.

@item %s
Prints dimensions of variables.

@item %t
Prints type names of variables.
@end table

Every command may also have an alignment modifier:

@table @code
@item l
Left alignment.

@item r
Right alignment (default).

@item c
Column-aligned (only applicable to command %s).
@end table

The @code{width} parameter is a positive integer specifying the minimum
number of columns used for printing.  No maximum is needed as the field will
auto-expand as required.

The parameters @code{left-min} and @code{balance} are only available when the
column-aligned modifier is used with the command @samp{%s}.
@code{balance} specifies the column number within the field width which will
be aligned between entries.  Numbering starts from 0 which indicates the
leftmost column.  @code{left-min} specifies the minimum field width to the
left of the specified balance column.

The default format is
@code{"  %a:4; %ln:6; %cs:16:6:1;  %rb:12;  %lc:-1;\n"}.

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.
@seealso{whos}
@end deftypefn
missing_function_hook
@c missing_function_hook src/variables.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} missing_function_hook ()
@deftypefnx {Built-in Function} {@var{old_val} =} missing_function_hook (@var{new_val})
@deftypefnx {Built-in Function} {} missing_function_hook (@var{new_val}, "local")
Query or set the internal variable that specifies the function to call when
an unknown identifier is requested.

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.
@end deftypefn
__varval__
@c __varval__ src/variables.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __varval__ (@var{name})
Undocumented internal function.
@end deftypefn
sparse_auto_mutate
@c sparse_auto_mutate src/ov-base.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} sparse_auto_mutate ()
@deftypefnx {Built-in Function} {@var{old_val} =} sparse_auto_mutate (@var{new_val})
@deftypefnx {Built-in Function} {} sparse_auto_mutate (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave will
automatically mutate sparse matrices to full matrices to save memory.
For example:

@example
@group
s = speye (3);
sparse_auto_mutate (false)
s(:, 1) = 1;
typeinfo (s)
@result{} sparse matrix
sparse_auto_mutate (true)
s(1, :) = 1;
typeinfo (s)
@result{} matrix
@end group
@end example

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.
@end deftypefn
logical
@c logical src/ov-bool-mat.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} logical (@var{x})
Convert @var{x} to logical type.
@seealso{double, single, char}
@end deftypefn
iscell
@c iscell src/ov-cell.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} iscell (@var{x})
Return true if @var{x} is a cell array object.
@seealso{ismatrix, isstruct, iscellstr, isa}
@end deftypefn
cell
@c cell src/ov-cell.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} cell (@var{n})
@deftypefnx {Built-in Function} {} cell (@var{m}, @var{n})
@deftypefnx {Built-in Function} {} cell (@var{m}, @var{n}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} cell ([@var{m} @var{n} @dots{}])
Create a new cell array object.
If invoked with a single scalar integer argument, return a square
@nospell{NxN} cell array.  If invoked with two or more scalar
integer arguments, or a vector of integer values, return an array with
the given dimensions.
@end deftypefn
iscellstr
@c iscellstr src/ov-cell.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} iscellstr (@var{cell})
Return true if every element of the cell array @var{cell} is a
character string.
@seealso{ischar}
@end deftypefn
cellstr
@c cellstr src/ov-cell.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} cellstr (@var{string})
Create a new cell array object from the elements of the string
array @var{string}.
@end deftypefn
struct2cell
@c struct2cell src/ov-cell.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} struct2cell (@var{S})
Create a new cell array from the objects stored in the struct object.
If @var{f} is the number of fields in the structure, the resulting
cell array will have a dimension vector corresponding to
@code{[@var{F} size(@var{S})]}.  For example:

@example
@group
  s = struct('name', @{'Peter', 'Hannah', 'Robert'@},
             'age', @{23, 16, 3@});
  c = struct2cell(s)
     @result{} c = @{1x1x3 Cell Array@}
  c(1,1,:)(:)
     @result{} ans =
        @{
          [1,1] = Peter
          [2,1] = Hannah
          [3,1] = Robert
        @}
  c(2,1,:)(:)
     @result{} ans =
        @{
          [1,1] = 23
          [2,1] = 16
          [3,1] = 3
        @}
@end group
@end example

@seealso{cell2struct, fieldnames}
@end deftypefn
class
@c class src/ov-class.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} class (@var{expr})
@deftypefnx {Built-in Function} {} class (@var{s}, @var{id})
@deftypefnx {Built-in Function} {} class (@var{s}, @var{id}, @var{p}, @dots{})
Return the class of the expression @var{expr} or create a class with
fields from structure @var{s} and name (string) @var{id}.  Additional
arguments name a list of parent classes from which the new class is
derived.
@end deftypefn
__isa_parent__
@c __isa_parent__ src/ov-class.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __isa_parent__ (@var{class}, @var{name})
Undocumented internal function.
@end deftypefn
__parent_classes__
@c __parent_classes__ src/ov-class.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __parent_classes__ (@var{x})
Undocumented internal function.
@end deftypefn
isobject
@c isobject src/ov-class.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isobject (@var{x})
Return true if @var{x} is a class object.
@seealso{class, typeinfo, isa, ismethod}
@end deftypefn
ismethod
@c ismethod src/ov-class.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} ismethod (@var{x}, @var{method})
Return true if @var{x} is a class object and the string @var{method}
is a method of this class.
@seealso{isobject}
@end deftypefn
methods
@c methods src/ov-class.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} methods (@var{x})
@deftypefnx {Built-in Function} {} methods ("classname")
Return a cell array containing the names of the methods for the
object @var{x} or the named class.
@end deftypefn
superiorto
@c superiorto src/ov-class.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} superiorto (@var{class_name}, @dots{})
When called from a class constructor, mark the object currently
constructed as having a higher precedence than @var{class_name}.
More that one such class can be specified in a single call.
This function may only be called from a class constructor.
@end deftypefn
inferiorto
@c inferiorto src/ov-class.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} inferiorto (@var{class_name}, @dots{})
When called from a class constructor, mark the object currently
constructed as having a lower precedence than @var{class_name}.
More that one such class can be specified in a single call.
This function may only be called from a class constructor.
@end deftypefn
functions
@c functions src/ov-fcn-handle.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} functions (@var{fcn_handle})
Return a struct containing information about the function handle
@var{fcn_handle}.
@end deftypefn
func2str
@c func2str src/ov-fcn-handle.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} func2str (@var{fcn_handle})
Return a string containing the name of the function referenced by
the function handle @var{fcn_handle}.
@end deftypefn
str2func
@c str2func src/ov-fcn-handle.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} str2func (@var{fcn_name})
@deftypefnx {Built-in Function} {} str2func (@var{fcn_name}, "global")
Return a function handle constructed from the string @var{fcn_name}.
If the optional "global" argument is passed, locally visible functions
are ignored in the lookup.
@end deftypefn
is_function_handle
@c is_function_handle src/ov-fcn-handle.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} is_function_handle (@var{x})
Return true if @var{x} is a function handle.
@seealso{isa, typeinfo, class}
@end deftypefn
inline
@c inline src/ov-fcn-inline.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} inline (@var{str})
@deftypefnx {Built-in Function} {} inline (@var{str}, @var{arg1}, @dots{})
@deftypefnx {Built-in Function} {} inline (@var{str}, @var{n})
Create an inline function from the character string @var{str}.
If called with a single argument, the arguments of the generated
function are extracted from the function itself.  The generated
function arguments will then be in alphabetical order.  It should
be noted that i, and j are ignored as arguments due to the
ambiguity between their use as a variable or their use as an inbuilt
constant.  All arguments followed by a parenthesis are considered
to be functions.

If the second and subsequent arguments are character strings,
they are the names of the arguments of the function.

If the second argument is an integer @var{n}, the arguments are
@code{"x"}, @code{"P1"}, @dots{}, @code{"P@var{N}"}.
@seealso{argnames, formula, vectorize}
@end deftypefn
formula
@c formula src/ov-fcn-inline.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} formula (@var{fun})
Return a character string representing the inline function @var{fun}.
Note that @code{char (@var{fun})} is equivalent to
@code{formula (@var{fun})}.
@seealso{argnames, inline, vectorize}
@end deftypefn
argnames
@c argnames src/ov-fcn-inline.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} argnames (@var{fun})
Return a cell array of character strings containing the names of
the arguments of the inline function @var{fun}.
@seealso{inline, formula, vectorize}
@end deftypefn
vectorize
@c vectorize src/ov-fcn-inline.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} vectorize (@var{fun})
Create a vectorized version of the inline function @var{fun}
by replacing all occurrences of @code{*}, @code{/}, etc., with
@code{.*}, @code{./}, etc.

This may be useful, for example, when using inline functions with
numerical integration or optimization where a vector-valued function
is expected.

@example
@group
fcn = vectorize (inline ("x^2 - 1"))
   @result{} fcn = f(x) = x.^2 - 1
quadv (fcn, 0, 3)
   @result{} 6
@end group
@end example
@seealso{inline, formula, argnames}
@end deftypefn
single
@c single src/ov-flt-re-mat.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} single (@var{x})
Convert @var{x} to single precision type.
@seealso{double}
@end deftypefn
isnull
@c isnull src/ov-null-mat.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isnull (@var{x})
Return true if @var{x} is a special null matrix, string, or single quoted
string.  Indexed assignment with such a value on the right-hand side should
delete array elements.  This function should be used when overloading
indexed assignment for user-defined classes instead of @code{isempty}, to
distinguish the cases:
@table @asis
@item @code{A(I) = []}
This should delete elements if @code{I} is nonempty.

@item @code{X = []; A(I) = X}
This should give an error if @code{I} is nonempty.
@end table
@seealso{isempty, isindex}
@end deftypefn
onCleanup
@c onCleanup src/ov-oncleanup.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{c} =} onCleanup (@var{action})
Create a special object that executes a given function upon destruction.
If the object is copied to multiple variables (or cell or struct array
elements) or returned from a function, @var{action} will be executed after
clearing the last copy of the object.  Note that if multiple local onCleanup
variables are created, the order in which they are called is unspecified.
For similar functionality @xref{The @code{unwind_protect} Statement}.
@end deftypefn
allow_noninteger_range_as_index
@c allow_noninteger_range_as_index src/ov-range.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} allow_noninteger_range_as_index ()
@deftypefnx {Built-in Function} {@var{old_val} =} allow_noninteger_range_as_index (@var{new_val})
@deftypefnx {Built-in Function} {} allow_noninteger_range_as_index (@var{new_val}, "local")
Query or set the internal variable that controls whether non-integer
ranges are allowed as indices.  This might be useful for @sc{matlab}
compatibility; however, it is still not entirely compatible because
@sc{matlab} treats the range expression differently in different contexts.

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.
@end deftypefn
double
@c double src/ov-re-mat.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} double (@var{x})
Convert @var{x} to double precision type.
@seealso{single}
@end deftypefn
struct
@c struct src/ov-struct.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} struct ("field", @var{value}, "field", @var{value}, @dots{})

Create a structure and initialize its value.

If the values are cell arrays, create a structure array and initialize
its values.  The dimensions of each cell array of values must match.
Singleton cells and non-cell values are repeated so that they fill
the entire array.  If the cells are empty, create an empty structure
array with the specified field names.

If the argument is an object, return the underlying struct.
@end deftypefn
isstruct
@c isstruct src/ov-struct.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isstruct (@var{x})
Return true if @var{x} is a structure or a structure array.
@seealso{ismatrix, iscell, isa}
@end deftypefn
fieldnames
@c fieldnames src/ov-struct.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} fieldnames (@var{struct})
Return a cell array of strings naming the elements of the structure
@var{struct}.  It is an error to call @code{fieldnames} with an
argument that is not a structure.
@end deftypefn
isfield
@c isfield src/ov-struct.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isfield (@var{x}, @var{name})
Return true if the @var{x} is a structure and it
includes an element named @var{name}.  If @var{name} is a cell
array of strings then a logical array of equal dimension is returned.
@end deftypefn
nfields
@c nfields src/ov-struct.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} nfields (@var{s})
Return the number of fields of the structure @var{s}.
@end deftypefn
cell2struct
@c cell2struct src/ov-struct.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} cell2struct (@var{cell}, @var{fields}, @var{dim})
Convert @var{cell} to a structure.  The number of fields in @var{fields}
must match the number of elements in @var{cell} along dimension @var{dim},
that is @code{numel (@var{fields}) == size (@var{cell}, @var{dim})}.
If @var{dim} is omitted, a value of 1 is assumed.

@example
@group
A = cell2struct (@{'Peter', 'Hannah', 'Robert';
                   185, 170, 168@},
                 @{'Name','Height'@}, 1);
A(1)
     @result{} ans =
        @{
          Name   = Peter
          Height = 185
        @}

@end group
@end example
@end deftypefn
rmfield
@c rmfield src/ov-struct.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} rmfield (@var{s}, @var{f})
Return a copy of the structure (array) @var{s} with the field @var{f}
removed.  If @var{f} is a cell array of strings or a character array, remove
the named fields.
@seealso{cellstr, iscellstr, setfield}
@end deftypefn
struct_levels_to_print
@c struct_levels_to_print src/ov-struct.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} struct_levels_to_print ()
@deftypefnx {Built-in Function} {@var{old_val} =} struct_levels_to_print (@var{new_val})
@deftypefnx {Built-in Function} {} struct_levels_to_print (@var{new_val}, "local")
Query or set the internal variable that specifies the number of
structure levels to display.

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.
@end deftypefn
print_struct_array_contents
@c print_struct_array_contents src/ov-struct.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} print_struct_array_contents ()
@deftypefnx {Built-in Function} {@var{old_val} =} print_struct_array_contents (@var{new_val})
@deftypefnx {Built-in Function} {} print_struct_array_contents (@var{new_val}, "local")
Query or set the internal variable that specifies whether to print struct
array contents.  If true, values of struct array elements are printed.
This variable does not affect scalar structures.  Their elements
are always printed.  In both cases, however, printing will be limited to
the number of levels specified by @var{struct_levels_to_print}.

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.
@end deftypefn
typeinfo
@c typeinfo src/ov-typeinfo.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} typeinfo ()
@deftypefnx {Built-in Function} {} typeinfo (@var{expr})

Return the type of the expression @var{expr}, as a string.  If
@var{expr} is omitted, return an cell array of strings containing all the
currently installed data types.
@end deftypefn
nargin
@c nargin src/ov-usr-fcn.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} nargin ()
@deftypefnx {Built-in Function} {} nargin (@var{fcn_name})
Within a function, return the number of arguments passed to the function.
At the top level, return the number of command line arguments passed to
Octave.  If called with the optional argument @var{fcn_name}, return the
maximum number of arguments the named function can accept, or -1 if the
function accepts a variable number of arguments.
@seealso{nargout, varargin, isargout, varargout, nthargout}
@end deftypefn
nargout
@c nargout src/ov-usr-fcn.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {} nargout ()
@deftypefnx {Built-in Function} {} nargout (@var{fcn_name})
Within a function, return the number of values the caller expects to
receive.  If called with the optional argument @var{fcn_name}, return the
maximum number of values the named function can produce, or -1 if the
function can produce a variable number of values.

For example,

@example
f ()
@end example

@noindent
will cause @code{nargout} to return 0 inside the function @code{f} and

@example
[s, t] = f ()
@end example

@noindent
will cause @code{nargout} to return 2 inside the function
@code{f}.

At the top level, @code{nargout} is undefined.
@seealso{nargin, varargin, isargout, varargout, nthargout}
@end deftypefn
optimize_subsasgn_calls
@c optimize_subsasgn_calls src/ov-usr-fcn.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} optimize_subsasgn_calls ()
@deftypefnx {Built-in Function} {@var{old_val} =} optimize_subsasgn_calls (@var{new_val})
@deftypefnx {Built-in Function} {} optimize_subsasgn_calls (@var{new_val}, "local")
Query or set the internal flag for subsasgn method call optimizations.
If true, Octave will attempt to eliminate the redundant copying when calling
subsasgn method of a user-defined class.

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.
@end deftypefn
isargout
@c isargout src/ov-usr-fcn.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} isargout (@var{k})
Within a function, return a logical value indicating whether the argument
@var{k} will be assigned on output to a variable.  If the result is false,
the argument has been ignored during the function call through the use of
the tilde (~) special output argument.  Functions can use @code{isargout} to
avoid performing unnecessary calculations for outputs which are unwanted.

If @var{k} is outside the range @code{1:max(nargout)}, the function returns
false.  @var{k} can also be an array, in which case the function works
element-by-element and a logical array is returned.  At the top level,
@code{isargout} returns an error.
@seealso{nargout, nargin, varargin, varargout, nthargout}
@end deftypefn
sizeof
@c sizeof src/ov.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} sizeof (@var{val})
Return the size of @var{val} in bytes.
@seealso{whos}
@end deftypefn
subsref
@c subsref src/ov.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} subsref (@var{val}, @var{idx})
Perform the subscripted element selection operation according to
the subscript specified by @var{idx}.

The subscript @var{idx} is expected to be a structure array with
fields @samp{type} and @samp{subs}.  Valid values for @samp{type}
are @samp{"()"}, @samp{"@{@}"}, and @samp{"."}.
The @samp{subs} field may be either @samp{":"} or a cell array
of index values.

The following example shows how to extract the two first columns of
a matrix

@example
@group
val = magic(3)
     @result{} val = [ 8   1   6
                3   5   7
                4   9   2 ]
idx.type = "()";
idx.subs = @{":", 1:2@};
subsref(val, idx)
     @result{} [ 8   1
          3   5
          4   9 ]
@end group
@end example

@noindent
Note that this is the same as writing @code{val(:,1:2)}.

If @var{idx} is an empty structure array with fields @samp{type}
and @samp{subs}, return @var{val}.
@seealso{subsasgn, substruct}
@end deftypefn
subsasgn
@c subsasgn src/ov.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} subsasgn (@var{val}, @var{idx}, @var{rhs})
Perform the subscripted assignment operation according to
the subscript specified by @var{idx}.

The subscript @var{idx} is expected to be a structure array with
fields @samp{type} and @samp{subs}.  Valid values for @samp{type}
are @samp{"()"}, @samp{"@{@}"}, and @samp{"."}.
The @samp{subs} field may be either @samp{":"} or a cell array
of index values.

The following example shows how to set the two first columns of a
3-by-3 matrix to zero.

@example
@group
val = magic(3);
idx.type = "()";
idx.subs = @{":", 1:2@};
subsasgn (val, idx, 0)
     @result{} [ 0   0   6
          0   0   7
          0   0   2 ]
@end group
@end example

Note that this is the same as writing @code{val(:,1:2) = 0}.

If @var{idx} is an empty structure array with fields @samp{type}
and @samp{subs}, return @var{rhs}.
@seealso{subsref, substruct}
@end deftypefn
is_sq_string
@c is_sq_string src/ov.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} is_sq_string (@var{x})
Return true if @var{x} is a single-quoted character string.
@seealso{is_dq_string, ischar}
@end deftypefn
is_dq_string
@c is_dq_string src/ov.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} is_dq_string (@var{x})
Return true if @var{x} is a double-quoted character string.
@seealso{is_sq_string, ischar}
@end deftypefn
int16
@c int16 src/ov-int16.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} int16 (@var{x})
Convert @var{x} to 16-bit integer type.
@end deftypefn
int32
@c int32 src/ov-int32.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} int32 (@var{x})
Convert @var{x} to 32-bit integer type.
@end deftypefn
int64
@c int64 src/ov-int64.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} int64 (@var{x})
Convert @var{x} to 64-bit integer type.
@end deftypefn
int8
@c int8 src/ov-int8.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} int8 (@var{x})
Convert @var{x} to 8-bit integer type.
@end deftypefn
uint16
@c uint16 src/ov-uint16.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} uint16 (@var{x})
Convert @var{x} to unsigned 16-bit integer type.
@end deftypefn
uint32
@c uint32 src/ov-uint32.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} uint32 (@var{x})
Convert @var{x} to unsigned 32-bit integer type.
@end deftypefn
uint64
@c uint64 src/ov-uint64.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} uint64 (@var{x})
Convert @var{x} to unsigned 64-bit integer type.
@end deftypefn
uint8
@c uint8 src/ov-uint8.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} uint8 (@var{x})
Convert @var{x} to unsigned 8-bit integer type.
@end deftypefn
__end__
@c __end__ src/pt-arg-list.cc
internal function
do_braindead_shortcircuit_evaluation
@c do_braindead_shortcircuit_evaluation src/pt-binop.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} do_braindead_shortcircuit_evaluation ()
@deftypefnx {Built-in Function} {@var{old_val} =} do_braindead_shortcircuit_evaluation (@var{new_val})
@deftypefnx {Built-in Function} {} do_braindead_shortcircuit_evaluation (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave will
do short-circuit evaluation of @samp{|} and @samp{&} operators inside the
conditions of if or while statements.

This feature is only provided for compatibility with @sc{matlab} and should
not be used unless you are porting old code that relies on this feature.

To obtain short-circuit behavior for logical expressions in new programs,
you should always use the @samp{&&} and @samp{||} operators.

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.
@end deftypefn
max_recursion_depth
@c max_recursion_depth src/pt-eval.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} max_recursion_depth ()
@deftypefnx {Built-in Function} {@var{old_val} =} max_recursion_depth (@var{new_val})
@deftypefnx {Built-in Function} {} max_recursion_depth (@var{new_val}, "local")
Query or set the internal limit on the number of times a function may
be called recursively.  If the limit is exceeded, an error message is
printed and control returns to the top level.

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.
@end deftypefn
silent_functions
@c silent_functions src/pt-eval.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} silent_functions ()
@deftypefnx {Built-in Function} {@var{old_val} =} silent_functions (@var{new_val})
@deftypefnx {Built-in Function} {} silent_functions (@var{new_val}, "local")
Query or set the internal variable that controls whether internal
output from a function is suppressed.  If this option is disabled,
Octave will display the results produced by evaluating expressions
within a function body that are not terminated with a semicolon.

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.
@end deftypefn
string_fill_char
@c string_fill_char src/pt-mat.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} string_fill_char ()
@deftypefnx {Built-in Function} {@var{old_val} =} string_fill_char (@var{new_val})
@deftypefnx {Built-in Function} {} string_fill_char (@var{new_val}, "local")
Query or set the internal variable used to pad all rows of a character
matrix to the same length.  It must be a single character.  The default
value is @code{" "} (a single space).  For example:

@example
@group
string_fill_char ("X");
[ "these"; "are"; "strings" ]
     @result{} "theseXX"
        "areXXXX"
        "strings"
@end group
@end example

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.
@end deftypefn
__contourc__
@c __contourc__ src/DLD-FUNCTIONS/__contourc__.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __contourc__ (@var{x}, @var{y}, @var{z}, @var{levels})
Undocumented internal function.
@end deftypefn
__delaunayn__
@c __delaunayn__ src/DLD-FUNCTIONS/__delaunayn__.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{T} =} __delaunayn__ (@var{pts})
@deftypefnx {Loadable Function} {@var{T} =} __delaunayn__ (@var{pts}, @var{options})
Undocumented internal function.
@end deftypefn
__dispatch__
@c __dispatch__ src/DLD-FUNCTIONS/__dispatch__.cc
Undocumented internal function
__dsearchn__
@c __dsearchn__ src/DLD-FUNCTIONS/__dsearchn__.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{idx}, @var{d}] =} dsearch (@var{x}, @var{xi})
Undocumented internal function.
@end deftypefn
__fltk_uigetfile__
@c __fltk_uigetfile__ src/DLD-FUNCTIONS/__fltk_uigetfile__.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} __fltk_uigetfile__ (@dots{})
Undocumented internal function.
@end deftypefn
__glpk__
@c __glpk__ src/DLD-FUNCTIONS/__glpk__.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{values}] =} __glpk__ (@var{args})
Undocumented internal function.
@end deftypefn
__init_fltk__
@c __init_fltk__ src/DLD-FUNCTIONS/__init_fltk__.cc

__fltk_redraw__
@c __fltk_redraw__ src/DLD-FUNCTIONS/__init_fltk__.cc

__fltk_maxtime__
@c __fltk_maxtime__ src/DLD-FUNCTIONS/__init_fltk__.cc

mouse_wheel_zoom
@c mouse_wheel_zoom src/DLD-FUNCTIONS/__init_fltk__.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{speed} =} mouse_wheel_zoom ()
@deftypefnx {Built-in Function} {} mouse_wheel_zoom (@var{speed})
Query or set the mouse wheel zoom factor.

This function is currently implemented only for the FLTK graphics toolkit.
@seealso{gui_mode}
@end deftypefn
gui_mode
@c gui_mode src/DLD-FUNCTIONS/__init_fltk__.cc
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{mode} =} gui_mode ()
@deftypefnx {Built-in Function} {} gui_mode (@var{mode})
Query or set the GUI mode for the current graphics toolkit.
The @var{mode} argument can be one of the following strings:
@table @asis
@item '2d'
Allows panning and zooming of current axes.

@item '3d'
Allows rotating and zooming of current axes.

@item 'none'
Mouse inputs have no effect.
@end table

This function is currently implemented only for the FLTK graphics toolkit.
@seealso{mouse_wheel_zoom}
@end deftypefn
__init_gnuplot__
@c __init_gnuplot__ src/DLD-FUNCTIONS/__init_gnuplot__.cc

__lin_interpn__
@c __lin_interpn__ src/DLD-FUNCTIONS/__lin_interpn__.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{vi} =} __lin_interpn__ (@var{x1}, @var{x2}, @dots{}, @var{xn}, @var{v}, @var{y1}, @var{y2}, @dots{}, @var{yn})
Undocumented internal function.
@end deftypefn
__magick_read__
@c __magick_read__ src/DLD-FUNCTIONS/__magick_read__.cc
-*- texinfo -*-
@deftypefn  {Function File} {@var{m} =} __magick_read__(@var{fname}, @var{index})
@deftypefnx {Function File} {[@var{m}, @var{colormap}] =} __magick_read__(@var{fname}, @var{index})
@deftypefnx {Function File} {[@var{m}, @var{colormap}, @var{alpha}] =} __magick_read__(@var{fname}, @var{index})
Read images with ImageMagick++.  In general you should not be using this
function.  Instead use @code{imread}.
@seealso{imread}
@end deftypefn
__magick_write__
@c __magick_write__ src/DLD-FUNCTIONS/__magick_read__.cc
-*- texinfo -*-
@deftypefn  {Function File} {} __magick_write__(@var{fname}, @var{fmt}, @var{img})
@deftypefnx {Function File} {} __magick_write__(@var{fname}, @var{fmt}, @var{img}, @var{map})
Write images with ImageMagick++.  In general you should not be using this
function.  Instead use @code{imwrite}.
@seealso{imread}
@end deftypefn
__magick_finfo__
@c __magick_finfo__ src/DLD-FUNCTIONS/__magick_read__.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __magick_finfo__(@var{fname})
Read image information with GraphicsMagick++.  In general you should
not be using this function.  Instead use @code{imfinfo}.
@seealso{imfinfo, imread}
@end deftypefn
__magick_format_list__
@c __magick_format_list__ src/DLD-FUNCTIONS/__magick_read__.cc
-*- texinfo -*-
@deftypefn {Function File} {} __magick_format_list__ (@var{formats})
Undocumented internal function.
@end deftypefn
__pchip_deriv__
@c __pchip_deriv__ src/DLD-FUNCTIONS/__pchip_deriv__.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __pchip_deriv__ (@var{x}, @var{y}, @var{dim})
Undocumented internal function.
@end deftypefn
__qp__
@c __qp__ src/DLD-FUNCTIONS/__qp__.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{x}, @var{lambda}, @var{info}, @var{iter}] =} __qp__ (@var{x0}, @var{H}, @var{q}, @var{Aeq}, @var{beq}, @var{Ain}, @var{bin}, @var{maxit})
Undocumented internal function.
@end deftypefn
__voronoi__
@c __voronoi__ src/DLD-FUNCTIONS/__voronoi__.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{C}, @var{F} =} __voronoi__ (@var{caller}, @var{pts})
@deftypefnx {Loadable Function} {@var{C}, @var{F} =} __voronoi__ (@var{caller}, @var{pts}, @var{options})
@deftypefnx {Loadable Function} {@var{C}, @var{F}, @var{Inf_Pts} =} __voronoi__ (@dots{})
Undocumented internal function.
@end deftypefn
amd
@c amd src/DLD-FUNCTIONS/amd.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{p} =} amd (@var{S})
@deftypefnx {Loadable Function} {@var{p} =} amd (@var{S}, @var{opts})

Return the approximate minimum degree permutation of a matrix.  This
permutation such that the Cholesky@tie{}factorization of @code{@var{S}
(@var{p}, @var{p})} tends to be sparser than the Cholesky@tie{}factorization
of @var{S} itself.  @code{amd} is typically faster than @code{symamd} but
serves a similar purpose.

The optional parameter @var{opts} is a structure that controls the
behavior of @code{amd}.  The fields of the structure are

@table @asis
@item @var{opts}.dense
Determines what @code{amd} considers to be a dense row or column of the
input matrix.  Rows or columns with more than @code{max(16, (dense *
sqrt (@var{n})} entries, where @var{n} is the order of the matrix @var{S},
are ignored by @code{amd} during the calculation of the permutation
The value of dense must be a positive scalar and its default value is 10.0

@item @var{opts}.aggressive
If this value is a non zero scalar, then @code{amd} performs aggressive
absorption.  The default is not to perform aggressive absorption.
@end table

The author of the code itself is Timothy A. Davis
@email{davis@@cise.ufl.edu}, University of Florida (see
@url{http://www.cise.ufl.edu/research/sparse/amd}).
@seealso{symamd, colamd}
@end deftypefn
balance
@c balance src/DLD-FUNCTIONS/balance.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{AA} =} balance (@var{A})
@deftypefnx {Loadable Function} {@var{AA} =} balance (@var{A}, @var{opt})
@deftypefnx {Loadable Function} {[@var{DD}, @var{AA}] =} balance (@var{A}, @var{opt})
@deftypefnx {Loadable Function} {[@var{D}, @var{P}, @var{AA}] =} balance (@var{A}, @var{opt})
@deftypefnx {Loadable Function} {[@var{CC}, @var{DD}, @var{AA}, @var{BB}] =} balance (@var{A}, @var{B}, @var{opt})

Compute @code{@var{AA} = @var{DD} \ @var{A} * @var{DD}} in which @var{AA}
is a matrix whose row and column norms are roughly equal in magnitude, and
@code{@var{DD} = @var{P} * @var{D}}, in which @var{P} is a permutation
matrix and @var{D} is a diagonal matrix of powers of two.  This allows the
equilibration to be computed without round-off.  Results of eigenvalue
calculation are typically improved by balancing first.

If two output values are requested, @code{balance} returns
the diagonal @var{D} and the permutation @var{P} separately as vectors.
In this case, @code{@var{DD} = eye(n)(:,@var{P}) * diag (@var{D})}, where
@math{n} is the matrix size.

If four output values are requested, compute @code{@var{AA} =
@var{CC}*@var{A}*@var{DD}} and @code{@var{BB} = @var{CC}*@var{B}*@var{DD}},
in which @var{AA} and @var{BB} have non-zero elements of approximately the
same magnitude and @var{CC} and @var{DD} are permuted diagonal matrices as
in @var{DD} for the algebraic eigenvalue problem.

The eigenvalue balancing option @var{opt} may be one of:

@table @asis
@item "noperm", "S"
Scale only; do not permute.

@item "noscal", "P"
Permute only; do not scale.
@end table

Algebraic eigenvalue balancing uses standard @sc{lapack} routines.

Generalized eigenvalue problem balancing uses Ward's algorithm
(SIAM Journal on Scientific and Statistical Computing, 1981).
@end deftypefn
besselj
@c besselj src/DLD-FUNCTIONS/besselj.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{j}, @var{ierr}] =} besselj (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Loadable Function} {[@var{y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Loadable Function} {[@var{i}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Loadable Function} {[@var{k}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Loadable Function} {[@var{h}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt})
Compute Bessel or Hankel functions of various kinds:

@table @code
@item besselj
Bessel functions of the first kind.  If the argument @var{opt} is supplied,
the result is multiplied by @code{exp(-abs(imag(@var{x})))}.

@item bessely
Bessel functions of the second kind.  If the argument @var{opt} is supplied,
the result is multiplied by @code{exp(-abs(imag(@var{x})))}.

@item besseli

Modified Bessel functions of the first kind.  If the argument @var{opt} is
supplied, the result is multiplied by @code{exp(-abs(real(@var{x})))}.

@item besselk

Modified Bessel functions of the second kind.  If the argument @var{opt} is
supplied, the result is multiplied by @code{exp(@var{x})}.

@item besselh
Compute Hankel functions of the first (@var{k} = 1) or second (@var{k}
= 2) kind.  If the argument @var{opt} is supplied, the result is multiplied
by @code{exp (-I*@var{x})} for @var{k} = 1 or @code{exp (I*@var{x})} for
@var{k} = 2.
@end table

If @var{alpha} is a scalar, the result is the same size as @var{x}.
If @var{x} is a scalar, the result is the same size as @var{alpha}.
If @var{alpha} is a row vector and @var{x} is a column vector, the
result is a matrix with @code{length (@var{x})} rows and
@code{length (@var{alpha})} columns.  Otherwise, @var{alpha} and
@var{x} must conform and the result will be the same size.

The value of @var{alpha} must be real.  The value of @var{x} may be
complex.

If requested, @var{ierr} contains the following status information
and is the same size as the result.

@enumerate 0
@item
Normal return.

@item
Input error, return @code{NaN}.

@item
Overflow, return @code{Inf}.

@item
Loss of significance by argument reduction results in less than
half of machine accuracy.

@item
Complete loss of significance by argument reduction, return @code{NaN}.

@item
Error---no computation, algorithm termination condition not met,
return @code{NaN}.
@end enumerate
@end deftypefn
bessely
@c bessely src/DLD-FUNCTIONS/besselj.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt})
See besselj.
@end deftypefn
besseli
@c besseli src/DLD-FUNCTIONS/besselj.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{i}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt})
See besselj.
@end deftypefn
besselk
@c besselk src/DLD-FUNCTIONS/besselj.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{k}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt})
See besselj.
@end deftypefn
besselh
@c besselh src/DLD-FUNCTIONS/besselj.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{h}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt})
See besselj.
@end deftypefn
airy
@c airy src/DLD-FUNCTIONS/besselj.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{a}, @var{ierr}] =} airy (@var{k}, @var{z}, @var{opt})
Compute Airy functions of the first and second kind, and their
derivatives.

@example
@group
 K   Function   Scale factor (if 'opt' is supplied)
---  --------   ---------------------------------------
 0   Ai (Z)     exp ((2/3) * Z * sqrt (Z))
 1   dAi(Z)/dZ  exp ((2/3) * Z * sqrt (Z))
 2   Bi (Z)     exp (-abs (real ((2/3) * Z *sqrt (Z))))
 3   dBi(Z)/dZ  exp (-abs (real ((2/3) * Z *sqrt (Z))))
@end group
@end example

The function call @code{airy (@var{z})} is equivalent to
@code{airy (0, @var{z})}.

The result is the same size as @var{z}.

If requested, @var{ierr} contains the following status information and
is the same size as the result.

@enumerate 0
@item
Normal return.

@item
Input error, return @code{NaN}.

@item
Overflow, return @code{Inf}.

@item
Loss of significance by argument reduction results in less than half
 of machine accuracy.

@item
Complete loss of significance by argument reduction, return @code{NaN}.

@item
Error---no computation, algorithm termination condition not met,
return @code{NaN}.
@end enumerate
@end deftypefn
betainc
@c betainc src/DLD-FUNCTIONS/betainc.cc
-*- texinfo -*-
@deftypefn {Mapping Function} {} betainc (@var{x}, @var{a}, @var{b})
Return the regularized incomplete Beta function,
@tex
$$
 I (x, a, b) = {1 \over {B (a, b)}} \int_0^x t^{(a-z)} (1-t)^{(b-1)} dt.
$$
@end tex
@ifnottex
@c Set example in small font to prevent overfull line

@smallexample
@group
@c spacing appears odd here, but is correct after Makeinfo
                                     x
                          1         /
betainc (x, a, b) = -----------    | t^(a-1) (1-t)^(b-1) dt.
                     beta (a, b)    /
                                 t=0
@end group
@end smallexample

@end ifnottex

If @var{x} has more than one component, both @var{a} and @var{b} must be
scalars.  If @var{x} is a scalar, @var{a} and @var{b} must be of
compatible dimensions.
@end deftypefn
bsxfun
@c bsxfun src/DLD-FUNCTIONS/bsxfun.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} bsxfun (@var{f}, @var{A}, @var{B})
The binary singleton expansion function applier performs broadcasting,
that is, applies a binary function @var{f} element-by-element to two
array arguments @var{A} and @var{B}, and expands as necessary
singleton dimensions in either input argument.  @var{f} is a function
handle, inline function, or string containing the name of the function
to evaluate.  The function @var{f} must be capable of accepting two
column-vector arguments of equal length, or one column vector argument
and a scalar.

The dimensions of @var{A} and @var{B} must be equal or singleton.  The
singleton dimensions of the arrays will be expanded to the same
dimensionality as the other array.
@seealso{arrayfun, cellfun}
@end deftypefn
ccolamd
@c ccolamd src/DLD-FUNCTIONS/ccolamd.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{p} =} ccolamd (@var{S})
@deftypefnx {Loadable Function} {@var{p} =} ccolamd (@var{S}, @var{knobs})
@deftypefnx {Loadable Function} {@var{p} =} ccolamd (@var{S}, @var{knobs}, @var{cmember})
@deftypefnx {Loadable Function} {[@var{p}, @var{stats}] =} ccolamd (@dots{})

Constrained column approximate minimum degree permutation.
@code{@var{p} = ccolamd (@var{S})} returns the column approximate minimum
degree permutation vector for the sparse matrix @var{S}.  For a non-symmetric
matrix
@var{S},
@code{@var{S}(:, @var{p})} tends to have sparser LU@tie{}factors than
@var{S}.  @code{chol (@var{S}(:, @var{p})' * @var{S}(:, @var{p}))} also
tends to be sparser than @code{chol (@var{S}' * @var{S})}.  @code{@var{p} =
ccolamd (@var{S}, 1)} optimizes the ordering for @code{lu (@var{S}(:,
@var{p}))}.  The ordering is followed by a column elimination tree
post-ordering.

@var{knobs} is an optional 1-element to 5-element input vector, with a
default value of @code{[0 10 10 1 0]} if not present or empty.  Entries not
present are set to their defaults.

@table @code
@item @var{knobs}(1)
if nonzero, the ordering is optimized for @code{lu (S(:, p))}.  It will be a
poor ordering for @code{chol (@var{S}(:, @var{p})' * @var{S}(:,
@var{p}))}.  This is the most important knob for ccolamd.

@item @var{knobs}(2)
if @var{S} is m-by-n, rows with more than @code{max (16, @var{knobs}(2) *
sqrt (n))} entries are ignored.

@item @var{knobs}(3)
columns with more than @code{max (16, @var{knobs}(3) * sqrt (min (@var{m},
@var{n})))} entries are ignored and ordered last in the output permutation
(subject to the cmember constraints).

@item @var{knobs}(4)
if nonzero, aggressive absorption is performed.

@item @var{knobs}(5)
if nonzero, statistics and knobs are printed.

@end table

@var{cmember} is an optional vector of length @math{n}.  It defines the
constraints on the column ordering.  If @code{@var{cmember}(j) = @var{c}},
then column @var{j} is in constraint set @var{c} (@var{c} must be in the
range 1 to
n).  In the output permutation @var{p}, all columns in set 1 appear
first, followed by all columns in set 2, and so on.  @code{@var{cmember} =
ones(1,n)} if not present or empty.
@code{ccolamd (@var{S}, [], 1 : n)} returns @code{1 : n}

@code{@var{p} = ccolamd (@var{S})} is about the same as
@code{@var{p} = colamd (@var{S})}.  @var{knobs} and its default values
differ.  @code{colamd} always does aggressive absorption, and it finds an
ordering suitable for both @code{lu (@var{S}(:, @var{p}))} and @code{chol
(@var{S}(:, @var{p})' * @var{S}(:, @var{p}))}; it cannot optimize its
ordering for @code{lu (@var{S}(:, @var{p}))} to the extent that
@code{ccolamd (@var{S}, 1)} can.

@var{stats} is an optional 20-element output vector that provides data
about the ordering and the validity of the input matrix @var{S}.  Ordering
statistics are in @code{@var{stats}(1 : 3)}.  @code{@var{stats}(1)} and
@code{@var{stats}(2)} are the number of dense or empty rows and columns
ignored by @sc{ccolamd} and @code{@var{stats}(3)} is the number of garbage
collections performed on the internal data structure used by @sc{ccolamd}
(roughly of size @code{2.2 * nnz (@var{S}) + 4 * @var{m} + 7 * @var{n}}
integers).

@code{@var{stats}(4 : 7)} provide information if CCOLAMD was able to
continue.  The matrix is OK if @code{@var{stats}(4)} is zero, or 1 if
invalid.  @code{@var{stats}(5)} is the rightmost column index that is
unsorted or contains duplicate entries, or zero if no such column exists.
@code{@var{stats}(6)} is the last seen duplicate or out-of-order row
index in the column index given by @code{@var{stats}(5)}, or zero if no
such row index exists.  @code{@var{stats}(7)} is the number of duplicate
or out-of-order row indices.  @code{@var{stats}(8 : 20)} is always zero in
the current version of @sc{ccolamd} (reserved for future use).

The authors of the code itself are S. Larimore, T. Davis (Univ. of Florida)
and S. Rajamanickam in collaboration with J. Bilbert and E. Ng.  Supported
by the National Science Foundation (DMS-9504974, DMS-9803599, CCR-0203270),
and a grant from Sandia National Lab.  See
@url{http://www.cise.ufl.edu/research/sparse} for ccolamd, csymamd, amd,
colamd, symamd, and other related orderings.
@seealso{colamd, csymamd}
@end deftypefn
csymamd
@c csymamd src/DLD-FUNCTIONS/ccolamd.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{p} =} csymamd (@var{S})
@deftypefnx {Loadable Function} {@var{p} =} csymamd (@var{S}, @var{knobs})
@deftypefnx {Loadable Function} {@var{p} =} csymamd (@var{S}, @var{knobs}, @var{cmember})
@deftypefnx {Loadable Function} {[@var{p}, @var{stats}] =} csymamd (@dots{})

For a symmetric positive definite matrix @var{S}, returns the permutation
vector @var{p} such that @code{@var{S}(@var{p},@var{p})} tends to have a
sparser Cholesky@tie{}factor than @var{S}.  Sometimes @code{csymamd} works
well for symmetric indefinite matrices too.  The matrix @var{S} is assumed
to be symmetric; only the strictly lower triangular part is referenced.
@var{S} must be square.  The ordering is followed by an elimination tree
post-ordering.

@var{knobs} is an optional 1-element to 3-element input vector, with a
default value of @code{[10 1 0]} if present or empty.  Entries not
present are set to their defaults.

@table @code
@item @var{knobs}(1)
If @var{S} is n-by-n, then rows and columns with more than
@code{max(16,@var{knobs}(1)*sqrt(n))} entries are ignored, and ordered
last in the output permutation (subject to the cmember constraints).

@item @var{knobs}(2)
If nonzero, aggressive absorption is performed.

@item @var{knobs}(3)
If nonzero, statistics and knobs are printed.

@end table

@var{cmember} is an optional vector of length n. It defines the constraints
on the ordering.  If @code{@var{cmember}(j) = @var{S}}, then row/column j is
in constraint set @var{c} (@var{c} must be in the range 1 to n).  In the
output permutation @var{p}, rows/columns in set 1 appear first, followed
by all rows/columns in set 2, and so on.  @code{@var{cmember} = ones(1,n)}
if not present or empty.  @code{csymamd(@var{S},[],1:n)} returns @code{1:n}.

@code{@var{p} = csymamd(@var{S})} is about the same as @code{@var{p} =
symamd(@var{S})}.  @var{knobs} and its default values differ.

@code{@var{stats}(4:7)} provide information if CCOLAMD was able to
continue.  The matrix is OK if @code{@var{stats}(4)} is zero, or 1 if
invalid.  @code{@var{stats}(5)} is the rightmost column index that is
unsorted or contains duplicate entries, or zero if no such column exists.
@code{@var{stats}(6)} is the last seen duplicate or out-of-order row
index in the column index given by @code{@var{stats}(5)}, or zero if no
such row index exists.  @code{@var{stats}(7)} is the number of duplicate
or out-of-order row indices.  @code{@var{stats}(8:20)} is always zero in
the current version of @sc{ccolamd} (reserved for future use).

The authors of the code itself are S. Larimore, T. Davis (Uni of Florida)
and S. Rajamanickam in collaboration with J. Bilbert and E. Ng.  Supported
by the National Science Foundation (DMS-9504974, DMS-9803599, CCR-0203270),
and a grant from Sandia National Lab.  See
@url{http://www.cise.ufl.edu/research/sparse} for ccolamd, csymamd, amd,
colamd, symamd, and other related orderings.
@seealso{symamd, ccolamd}
@end deftypefn
cellfun
@c cellfun src/DLD-FUNCTIONS/cellfun.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} cellfun (@var{name}, @var{C})
@deftypefnx {Loadable Function} {} cellfun ("size", @var{C}, @var{k})
@deftypefnx {Loadable Function} {} cellfun ("isclass", @var{C}, @var{class})
@deftypefnx {Loadable Function} {} cellfun (@var{func}, @var{C})
@deftypefnx {Loadable Function} {} cellfun (@var{func}, @var{C}, @var{D})
@deftypefnx {Loadable Function} {[@var{a}, @dots{}] =} cellfun (@dots{})
@deftypefnx {Loadable Function} {} cellfun (@dots{}, 'ErrorHandler', @var{errfunc})
@deftypefnx {Loadable Function} {} cellfun (@dots{}, 'UniformOutput', @var{val})

Evaluate the function named @var{name} on the elements of the cell array
@var{C}.  Elements in @var{C} are passed on to the named function
individually.  The function @var{name} can be one of the functions

@table @code
@item isempty
Return 1 for empty elements.

@item islogical
Return 1 for logical elements.

@item isreal
Return 1 for real elements.

@item length
Return a vector of the lengths of cell elements.

@item ndims
Return the number of dimensions of each element.

@item numel
@itemx prodofsize
Return the number of elements contained within each cell element.  The
number is the product of the dimensions of the object at each cell element.

@item size
Return the size along the @var{k}-th dimension.

@item isclass
Return 1 for elements of @var{class}.
@end table

Additionally, @code{cellfun} accepts an arbitrary function @var{func}
in the form of an inline function, function handle, or the name of a
function (in a character string).  In the case of a character string
argument, the function must accept a single argument named @var{x}, and
it must return a string value.  The function can take one or more arguments,
with the inputs arguments given by @var{C}, @var{D}, etc.  Equally the
function can return one or more output arguments.  For example:

@example
@group
cellfun ("atan2", @{1, 0@}, @{0, 1@})
     @result{}ans = [1.57080   0.00000]
@end group
@end example

The number of output arguments of @code{cellfun} matches the number of output
arguments of the function.  The outputs of the function will be collected
into the output arguments of @code{cellfun} like this:

@example
@group
function [a, b] = twoouts (x)
  a = x;
  b = x*x;
endfunction
[aa, bb] = cellfun(@@twoouts, @{1, 2, 3@})
     @result{}
        aa =
           1 2 3
        bb =
           1 4 9
@end group
@end example

Note that per default the output argument(s) are arrays of the same size as
the input arguments.  Input arguments that are singleton (1x1) cells will be
automatically expanded to the size of the other arguments.

If the parameter 'UniformOutput' is set to true (the default), then the
function must return scalars which will be concatenated into the return
array(s).  If 'UniformOutput' is false, the outputs are concatenated into a
cell array (or cell arrays).  For example:

@example
@group
cellfun ("tolower", @{"Foo", "Bar", "FooBar"@},
         "UniformOutput",false)
@result{} ans = @{"foo", "bar", "foobar"@}
@end group
@end example

Given the parameter 'ErrorHandler', then @var{errfunc} defines a function to
call in case @var{func} generates an error.  The form of the function is

@example
function [@dots{}] = errfunc (@var{s}, @dots{})
@end example

@noindent
where there is an additional input argument to @var{errfunc} relative to
@var{func}, given by @var{s}.  This is a structure with the elements
'identifier', 'message' and 'index', giving respectively the error
identifier, the error message, and the index into the input arguments
of the element that caused the error.  For example:

@example
@group
function y = foo (s, x), y = NaN; endfunction
cellfun ("factorial", @{-1,2@}, 'ErrorHandler', @@foo)
@result{} ans = [NaN 2]
@end group
@end example

Use @code{cellfun} intelligently.  The @code{cellfun} function is a
useful tool for avoiding loops.  It is often used with anonymous
function handles; however, calling an anonymous function involves an
overhead quite comparable to the overhead of an m-file function.
Passing a handle to a built-in function is faster, because the
interpreter is not involved in the internal loop.  For example:

@example
@group
a = @{@dots{}@}
v = cellfun (@@(x) det(x), a); # compute determinants
v = cellfun (@@det, a); # faster
@end group
@end example

@seealso{arrayfun, structfun, spfun}
@end deftypefn
arrayfun
@c arrayfun src/DLD-FUNCTIONS/cellfun.cc
-*- texinfo -*-
@deftypefn  {Function File} {} arrayfun (@var{func}, @var{A})
@deftypefnx {Function File} {@var{x} =} arrayfun (@var{func}, @var{A})
@deftypefnx {Function File} {@var{x} =} arrayfun (@var{func}, @var{A}, @var{b}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @dots{}] =} arrayfun (@var{func}, @var{A}, @dots{})
@deftypefnx {Function File} {} arrayfun (@dots{}, "UniformOutput", @var{val})
@deftypefnx {Function File} {} arrayfun (@dots{}, "ErrorHandler", @var{errfunc})

Execute a function on each element of an array.  This is useful for
functions that do not accept array arguments.  If the function does
accept array arguments it is better to call the function directly.

The first input argument @var{func} can be a string, a function
handle, an inline function, or an anonymous function.  The input
argument @var{A} can be a logic array, a numeric array, a string
array, a structure array, or a cell array.  By a call of the function
@command{arrayfun} all elements of @var{A} are passed on to the named
function @var{func} individually.

The named function can also take more than two input arguments, with
the input arguments given as third input argument @var{b}, fourth
input argument @var{c}, @dots{}  If given more than one array input
argument then all input arguments must have the same sizes, for
example:

@example
@group
arrayfun (@@atan2, [1, 0], [0, 1])
@result{} ans = [1.5708   0.0000]
@end group
@end example

If the parameter @var{val} after a further string input argument
"UniformOutput" is set @code{true} (the default), then the named
function @var{func} must return a single element which then will be
concatenated into the return value and is of type matrix.  Otherwise,
if that parameter is set to @code{false}, then the outputs are
concatenated in a cell array.  For example:

@example
@group
arrayfun (@@(x,y) x:y, "abc", "def", "UniformOutput", false)
@result{} ans =
    @{
      [1,1] = abcd
      [1,2] = bcde
      [1,3] = cdef
    @}
@end group
@end example

If more than one output arguments are given then the named function
must return the number of return values that also are expected, for
example:

@example
@group
[A, B, C] = arrayfun (@@find, [10; 0], "UniformOutput", false)
@result{}
A =
@{
  [1,1] =  1
  [2,1] = [](0x0)
@}
B =
@{
  [1,1] =  1
  [2,1] = [](0x0)
@}
C =
@{
  [1,1] =  10
  [2,1] = [](0x0)
@}
@end group
@end example

If the parameter @var{errfunc} after a further string input argument
"ErrorHandler" is another string, a function handle, an inline
function, or an anonymous function, then @var{errfunc} defines a
function to call in the case that @var{func} generates an error.
The definition of the function must be of the form

@example
function [@dots{}] = errfunc (@var{s}, @dots{})
@end example

@noindent
where there is an additional input argument to @var{errfunc}
relative to @var{func}, given by @var{s}.  This is a structure with
the elements "identifier", "message", and "index" giving,
respectively, the error identifier, the error message, and the index of
the array elements that caused the error.  The size of the output
argument of @var{errfunc} must have the same size as the output
argument of @var{func}, otherwise a real error is thrown.  For
example:

@example
@group
function y = ferr (s, x), y = "MyString"; endfunction
arrayfun (@@str2num, [1234],
           "UniformOutput", false, "ErrorHandler", @@ferr)
@result{} ans =
    @{
     [1,1] = MyString
    @}
@end group
@end example

@seealso{spfun, cellfun, structfun}
@end deftypefn
num2cell
@c num2cell src/DLD-FUNCTIONS/cellfun.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{C} =} num2cell (@var{A})
@deftypefnx {Loadable Function} {@var{C} =} num2cell (@var{A}, @var{dim})
Convert the numeric matrix @var{A} to a cell array.  If @var{dim} is
defined, the value @var{C} is of dimension 1 in this dimension and the
elements of @var{A} are placed into @var{C} in slices.  For example:

@example
@group
num2cell([1,2;3,4])
     @result{} ans =
        @{
          [1,1] =  1
          [2,1] =  3
          [1,2] =  2
          [2,2] =  4
        @}
num2cell([1,2;3,4],1)
     @result{} ans =
        @{
          [1,1] =
             1
             3
          [1,2] =
             2
             4
        @}
@end group
@end example

@seealso{mat2cell}
@end deftypefn
mat2cell
@c mat2cell src/DLD-FUNCTIONS/cellfun.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{C} =} mat2cell (@var{A}, @var{m}, @var{n})
@deftypefnx {Loadable Function} {@var{C} =} mat2cell (@var{A}, @var{d1}, @var{d2}, @dots{})
@deftypefnx {Loadable Function} {@var{C} =} mat2cell (@var{A}, @var{r})
Convert the matrix @var{A} to a cell array.  If @var{A} is 2-D, then
it is required that @code{sum (@var{m}) == size (@var{A}, 1)} and
@code{sum (@var{n}) == size (@var{A}, 2)}.  Similarly, if @var{A} is
multi-dimensional and the number of dimensional arguments is equal
to the dimensions of @var{A}, then it is required that @code{sum (@var{di})
== size (@var{A}, i)}.

Given a single dimensional argument @var{r}, the other dimensional
arguments are assumed to equal @code{size (@var{A},@var{i})}.

An example of the use of mat2cell is

@example
mat2cell (reshape(1:16,4,4),[3,1],[3,1])
@result{} @{
  [1,1] =

     1   5   9
     2   6  10
     3   7  11

  [2,1] =

     4   8  12

  [1,2] =

    13
    14
    15

  [2,2] = 16
@}
@end example
@seealso{num2cell, cell2mat}
@end deftypefn
cellslices
@c cellslices src/DLD-FUNCTIONS/cellfun.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{sl} =} cellslices (@var{x}, @var{lb}, @var{ub}, @var{dim})
Given an array @var{x}, this function produces a cell array of slices from
the array determined by the index vectors @var{lb}, @var{ub}, for lower and
upper bounds, respectively.  In other words, it is equivalent to the
following code:

@example
@group
n = length (lb);
sl = cell (1, n);
for i = 1:length (lb)
  sl@{i@} = x(:,@dots{},lb(i):ub(i),@dots{},:);
endfor
@end group
@end example

The position of the index is determined by @var{dim}.  If not specified,
slicing is done along the first non-singleton dimension.
@seealso{cell2mat, cellindexmat, cellfun}
@end deftypefn
cellindexmat
@c cellindexmat src/DLD-FUNCTIONS/cellfun.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{y} =} cellindexmat (@var{x}, @var{varargin})
Given a cell array of matrices @var{x}, this function computes

@example
@group
  Y = cell (size (X));
  for i = 1:numel (X)
    Y@{i@} = X@{i@}(varargin@{:@});
  endfor
@end group
@end example
@seealso{cellslices, cellfun}
@end deftypefn
chol
@c chol src/DLD-FUNCTIONS/chol.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{R} =} chol (@var{A})
@deftypefnx {Loadable Function} {[@var{R}, @var{p}] =} chol (@var{A})
@deftypefnx {Loadable Function} {[@var{R}, @var{p}, @var{Q}] =} chol (@var{S})
@deftypefnx {Loadable Function} {[@var{R}, @var{p}, @var{Q}] =} chol (@var{S}, 'vector')
@deftypefnx {Loadable Function} {[@var{L}, @dots{}] =} chol (@dots{}, 'lower')
@deftypefnx {Loadable Function} {[@var{L}, @dots{}] =} chol (@dots{}, 'upper')
@cindex Cholesky factorization
Compute the Cholesky@tie{}factor, @var{R}, of the symmetric positive definite
matrix @var{A}, where
@tex
$ R^T R = A $.
@end tex
@ifnottex

@example
@var{R}' * @var{R} = @var{A}.
@end example

@end ifnottex

Called with one output argument @code{chol} fails if @var{A} or @var{S} is
not positive definite.  With two or more output arguments @var{p} flags
whether the matrix was positive definite and @code{chol} does not fail.  A
zero value indicated that the matrix was positive definite and the @var{R}
gives the factorization, and @var{p} will have a positive value otherwise.

If called with 3 outputs then a sparsity preserving row/column permutation
is applied to @var{A} prior to the factorization.  That is @var{R}
is the factorization of @code{@var{A}(@var{Q},@var{Q})} such that
@tex
$ R^T R = Q^T A Q$.
@end tex
@ifnottex

@example
@var{R}' * @var{R} = @var{Q}' * @var{A} * @var{Q}.
@end example

@end ifnottex

The sparsity preserving permutation is generally returned as a matrix.
However, given the flag 'vector', @var{Q} will be returned as a vector
such that
@tex
$ R^T R = A (Q, Q)$.
@end tex
@ifnottex

@example
@var{R}' * @var{R} = @var{A}(@var{Q}, @var{Q}).
@end example

@end ifnottex

Called with either a sparse or full matrix and using the 'lower' flag,
@code{chol} returns the lower triangular factorization such that
@tex
$ L L^T = A $.
@end tex
@ifnottex

@example
@var{L} * @var{L}' = @var{A}.
@end example

@end ifnottex

For full matrices, if the 'lower' flag is set only the lower triangular part
of the matrix is used for the factorization, otherwise the upper triangular
part is used.

In general the lower triangular factorization is significantly faster for
sparse matrices.
@seealso{cholinv, chol2inv}
@end deftypefn
cholinv
@c cholinv src/DLD-FUNCTIONS/chol.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} cholinv (@var{A})
Use the Cholesky@tie{}factorization to compute the inverse of the
symmetric positive definite matrix @var{A}.
@seealso{chol, chol2inv, inv}
@end deftypefn
chol2inv
@c chol2inv src/DLD-FUNCTIONS/chol.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} chol2inv (@var{U})
Invert a symmetric, positive definite square matrix from its Cholesky
decomposition, @var{U}.  Note that @var{U} should be an upper-triangular
matrix with positive diagonal elements.  @code{chol2inv (@var{U})}
provides @code{inv (@var{U}'*@var{U})} but it is much faster than
using @code{inv}.
@seealso{chol, cholinv, inv}
@end deftypefn
cholupdate
@c cholupdate src/DLD-FUNCTIONS/chol.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{R1}, @var{info}] =} cholupdate (@var{R}, @var{u}, @var{op})
Update or downdate a Cholesky@tie{}factorization.  Given an upper triangular
matrix @var{R} and a column vector @var{u}, attempt to determine another
upper triangular matrix @var{R1} such that
@itemize @bullet
@item
@var{R1}'*@var{R1} = @var{R}'*@var{R} + @var{u}*@var{u}'
if @var{op} is "+"

@item
@var{R1}'*@var{R1} = @var{R}'*@var{R} - @var{u}*@var{u}'
if @var{op} is "-"
@end itemize

If @var{op} is "-", @var{info} is set to
@itemize
@item 0 if the downdate was successful,

@item 1 if @var{R}'*@var{R} - @var{u}*@var{u}' is not positive definite,

@item 2 if @var{R} is singular.
@end itemize

If @var{info} is not present, an error message is printed in cases 1 and 2.
@seealso{chol, qrupdate}
@end deftypefn
cholinsert
@c cholinsert src/DLD-FUNCTIONS/chol.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{R1} =} cholinsert (@var{R}, @var{j}, @var{u})
@deftypefnx {Loadable Function} {[@var{R1}, @var{info}] =} cholinsert (@var{R}, @var{j}, @var{u})
Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian
positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper
triangular, return the Cholesky@tie{}factorization of
@var{A1}, where @w{A1(p,p) = A}, @w{A1(:,j) = A1(j,:)' = u} and
@w{p = [1:j-1,j+1:n+1]}.  @w{u(j)} should be positive.
On return, @var{info} is set to
@itemize
@item 0 if the insertion was successful,

@item 1 if @var{A1} is not positive definite,

@item 2 if @var{R} is singular.
@end itemize

If @var{info} is not present, an error message is printed in cases 1 and 2.
@seealso{chol, cholupdate, choldelete}
@end deftypefn
choldelete
@c choldelete src/DLD-FUNCTIONS/chol.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{R1} =} choldelete (@var{R}, @var{j})
Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian
positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper
triangular, return the Cholesky@tie{}factorization of @w{A(p,p)}, where
@w{p = [1:j-1,j+1:n+1]}.
@seealso{chol, cholupdate, cholinsert}
@end deftypefn
cholshift
@c cholshift src/DLD-FUNCTIONS/chol.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{R1} =} cholshift (@var{R}, @var{i}, @var{j})
Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian
positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper
triangular, return the Cholesky@tie{}factorization of
@w{@var{A}(p,p)}, where @w{p} is the permutation @*
@code{p = [1:i-1, shift(i:j, 1), j+1:n]} if @w{@var{i} < @var{j}} @*
 or @*
@code{p = [1:j-1, shift(j:i,-1), i+1:n]} if @w{@var{j} < @var{i}}.  @*

@seealso{chol, cholinsert, choldelete}
@end deftypefn
colamd
@c colamd src/DLD-FUNCTIONS/colamd.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{p} =} colamd (@var{S})
@deftypefnx {Loadable Function} {@var{p} =} colamd (@var{S}, @var{knobs})
@deftypefnx {Loadable Function} {[@var{p}, @var{stats}] =} colamd (@var{S})
@deftypefnx {Loadable Function} {[@var{p}, @var{stats}] =} colamd (@var{S}, @var{knobs})

Column approximate minimum degree permutation.
@code{@var{p} = colamd (@var{S})} returns the column approximate minimum
degree permutation vector for the sparse matrix @var{S}.  For a
non-symmetric matrix @var{S}, @code{@var{S}(:,@var{p})} tends to have
sparser LU@tie{}factors than @var{S}.  The Cholesky@tie{}factorization of
@code{@var{S}(:,@var{p})' * @var{S}(:,@var{p})} also tends to be sparser
than that of @code{@var{S}' * @var{S}}.

@var{knobs} is an optional one- to three-element input vector.  If @var{S} is
m-by-n, then rows with more than @code{max(16,@var{knobs}(1)*sqrt(n))}
entries are ignored.  Columns with more than
@code{max(16,@var{knobs}(2)*sqrt(min(m,n)))} entries are removed prior to
ordering, and ordered last in the output permutation @var{p}.  Only
completely dense rows or columns are removed if @code{@var{knobs}(1)} and
@code{@var{knobs}(2)} are < 0, respectively.  If @code{@var{knobs}(3)} is
nonzero, @var{stats} and @var{knobs} are printed.  The default is
@code{@var{knobs} = [10 10 0]}.  Note that @var{knobs} differs from earlier
versions of colamd.

@var{stats} is an optional 20-element output vector that provides data
about the ordering and the validity of the input matrix @var{S}.  Ordering
statistics are in @code{@var{stats}(1:3)}.  @code{@var{stats}(1)} and
@code{@var{stats}(2)} are the number of dense or empty rows and columns
ignored by @sc{colamd} and @code{@var{stats}(3)} is the number of garbage
collections performed on the internal data structure used by @sc{colamd}
(roughly of size @code{2.2 * nnz(@var{S}) + 4 * @var{m} + 7 * @var{n}}
integers).

Octave built-in functions are intended to generate valid sparse matrices,
with no duplicate entries, with ascending row indices of the nonzeros
in each column, with a non-negative number of entries in each column (!)
and so on.  If a matrix is invalid, then @sc{colamd} may or may not be able
to continue.  If there are duplicate entries (a row index appears two or
more times in the same column) or if the row indices in a column are out
of order, then @sc{colamd} can correct these errors by ignoring the duplicate
entries and sorting each column of its internal copy of the matrix
@var{S} (the input matrix @var{S} is not repaired, however).  If a matrix
is invalid in other ways then @sc{colamd} cannot continue, an error message
is printed, and no output arguments (@var{p} or @var{stats}) are returned.
@sc{colamd} is thus a simple way to check a sparse matrix to see if it's
valid.

@code{@var{stats}(4:7)} provide information if COLAMD was able to
continue.  The matrix is OK if @code{@var{stats}(4)} is zero, or 1 if
invalid.  @code{@var{stats}(5)} is the rightmost column index that is
unsorted or contains duplicate entries, or zero if no such column exists.
@code{@var{stats}(6)} is the last seen duplicate or out-of-order row
index in the column index given by @code{@var{stats}(5)}, or zero if no
such row index exists.  @code{@var{stats}(7)} is the number of duplicate
or out-of-order row indices.  @code{@var{stats}(8:20)} is always zero in
the current version of @sc{colamd} (reserved for future use).

The ordering is followed by a column elimination tree post-ordering.

The authors of the code itself are Stefan I. Larimore and Timothy A.
Davis @email{davis@@cise.ufl.edu}, University of Florida.  The algorithm was
developed in collaboration with John Gilbert, Xerox PARC, and Esmond
Ng, Oak Ridge National Laboratory.  (see
@url{http://www.cise.ufl.edu/research/sparse/colamd})
@seealso{colperm, symamd, ccolamd}
@end deftypefn
symamd
@c symamd src/DLD-FUNCTIONS/colamd.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{p} =} symamd (@var{S})
@deftypefnx {Loadable Function} {@var{p} =} symamd (@var{S}, @var{knobs})
@deftypefnx {Loadable Function} {[@var{p}, @var{stats}] =} symamd (@var{S})
@deftypefnx {Loadable Function} {[@var{p}, @var{stats}] =} symamd (@var{S}, @var{knobs})

For a symmetric positive definite matrix @var{S}, returns the permutation
vector p such that @code{@var{S}(@var{p}, @var{p})} tends to have a
sparser Cholesky@tie{}factor than @var{S}.  Sometimes @code{symamd} works
well for symmetric indefinite matrices too.  The matrix @var{S} is assumed
to be symmetric; only the strictly lower triangular part is referenced.
@var{S} must be square.

@var{knobs} is an optional one- to two-element input vector.  If @var{S} is
n-by-n, then rows and columns with more than
@code{max(16,@var{knobs}(1)*sqrt(n))} entries are removed prior to ordering,
and ordered last in the output permutation @var{p}.  No rows/columns are
removed if @code{@var{knobs}(1) < 0}.  If @code{@var{knobs} (2)} is nonzero,
@code{stats} and @var{knobs} are printed.  The default is @code{@var{knobs}
= [10 0]}.  Note that @var{knobs} differs from earlier versions of symamd.

@var{stats} is an optional 20-element output vector that provides data
about the ordering and the validity of the input matrix @var{S}.  Ordering
statistics are in @code{@var{stats}(1:3)}.  @code{@var{stats}(1) =
@var{stats}(2)} is the number of dense or empty rows and columns
ignored by SYMAMD and @code{@var{stats}(3)} is the number of garbage
collections performed on the internal data structure used by SYMAMD
(roughly of size @code{8.4 * nnz (tril (@var{S}, -1)) + 9 * @var{n}}
integers).

Octave built-in functions are intended to generate valid sparse matrices,
with no duplicate entries, with ascending row indices of the nonzeros
in each column, with a non-negative number of entries in each column (!)
and so on.  If a matrix is invalid, then SYMAMD may or may not be able
to continue.  If there are duplicate entries (a row index appears two or
more times in the same column) or if the row indices in a column are out
of order, then SYMAMD can correct these errors by ignoring the duplicate
entries and sorting each column of its internal copy of the matrix S (the
input matrix S is not repaired, however).  If a matrix is invalid in
other ways then SYMAMD cannot continue, an error message is printed, and
no output arguments (@var{p} or @var{stats}) are returned.  SYMAMD is
thus a simple way to check a sparse matrix to see if it's valid.

@code{@var{stats}(4:7)} provide information if SYMAMD was able to
continue.  The matrix is OK if @code{@var{stats} (4)} is zero, or 1
if invalid.  @code{@var{stats}(5)} is the rightmost column index that
is unsorted or contains duplicate entries, or zero if no such column
exists.  @code{@var{stats}(6)} is the last seen duplicate or out-of-order
row index in the column index given by @code{@var{stats}(5)}, or zero
if no such row index exists.  @code{@var{stats}(7)} is the number of
duplicate or out-of-order row indices.  @code{@var{stats}(8:20)} is
always zero in the current version of SYMAMD (reserved for future use).

The ordering is followed by a column elimination tree post-ordering.

The authors of the code itself are Stefan I. Larimore and Timothy A.
Davis @email{davis@@cise.ufl.edu}, University of Florida.  The algorithm was
developed in collaboration with John Gilbert, Xerox PARC, and Esmond
Ng, Oak Ridge National Laboratory.  (see
@url{http://www.cise.ufl.edu/research/sparse/colamd})
@seealso{colperm, colamd}
@end deftypefn
etree
@c etree src/DLD-FUNCTIONS/colamd.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{p} =} etree (@var{S})
@deftypefnx {Loadable Function} {@var{p} =} etree (@var{S}, @var{typ})
@deftypefnx {Loadable Function} {[@var{p}, @var{q}] =} etree (@var{S}, @var{typ})

Return the elimination tree for the matrix @var{S}.  By default @var{S}
is assumed to be symmetric and the symmetric elimination tree is
returned.  The argument @var{typ} controls whether a symmetric or
column elimination tree is returned.  Valid values of @var{typ} are
'sym' or 'col', for symmetric or column elimination tree respectively

Called with a second argument, @code{etree} also returns the postorder
permutations on the tree.
@end deftypefn
colloc
@c colloc src/DLD-FUNCTIONS/colloc.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{r}, @var{amat}, @var{bmat}, @var{q}] =} colloc (@var{n}, "left", "right")
Compute derivative and integral weight matrices for orthogonal
collocation using the subroutines given in J. Villadsen and
M. L. Michelsen, @cite{Solution of Differential Equation Models by
Polynomial Approximation}.
@end deftypefn
conv2
@c conv2 src/DLD-FUNCTIONS/conv2.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} conv2 (@var{A}, @var{B})
@deftypefnx {Loadable Function} {} conv2 (@var{v1}, @var{v2}, @var{m})
@deftypefnx {Loadable Function} {} conv2 (@dots{}, @var{shape})
Return the 2-D convolution of @var{A} and @var{B}.  The size of the result
is determined by the optional @var{shape} argument which takes the following
values

@table @asis
@item @var{shape} = "full"
Return the full convolution.  (default)

@item @var{shape} = "same"
Return the central part of the convolution with the same size as @var{A}.
The central part of the convolution begins at the indices
@code{floor ([size(@var{B})/2] + 1)}.

@item @var{shape} = "valid"
Return only the parts which do not include zero-padded edges.
The size of the result is @code{max (size (A) - size (B) + 1, 0)}.
@end table

When the third argument is a matrix, return the convolution of the matrix
@var{m} by the vector @var{v1} in the column direction and by the vector
@var{v2} in the row direction.
@seealso{conv, convn}
@end deftypefn
convn
@c convn src/DLD-FUNCTIONS/conv2.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{C} =} convn (@var{A}, @var{B})
@deftypefnx {Loadable Function} {@var{C} =} convn (@var{A}, @var{B}, @var{shape})
Return the n-D convolution of @var{A} and @var{B}.  The size of the result
is determined by the optional @var{shape} argument which takes the following
values

@table @asis
@item @var{shape} = "full"
Return the full convolution.  (default)

@item @var{shape} = "same"
Return central part of the convolution with the same size as @var{A}.
The central part of the convolution begins at the indices
@code{floor ([size(@var{B})/2] + 1)}.

@item @var{shape} = "valid"
Return only the parts which do not include zero-padded edges.
The size of the result is @code{max (size (A) - size (B) + 1, 0)}.
@end table

@seealso{conv2, conv}
@end deftypefn
convhulln
@c convhulln src/DLD-FUNCTIONS/convhulln.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{h} =} convhulln (@var{pts})
@deftypefnx {Loadable Function} {@var{h} =} convhulln (@var{pts}, @var{options})
@deftypefnx {Loadable Function} {[@var{h}, @var{v}] =} convhulln (@dots{})
Compute the convex hull of the set of points @var{pts} which is a matrix
of size [n, dim] containing n points in a space of dimension dim.
The hull @var{h} is an index vector into the set of points and specifies
which points form the enclosing hull.

An optional second argument, which must be a string or cell array of strings,
contains options passed to the underlying qhull command.
See the documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.
The default options depend on the dimension of the input:

@itemize
@item 2D, 3D, 4D: @var{options} = @code{@{"Qt"@}}

@item 5D and higher: @var{options} = @code{@{"Qt", "Qx"@}}
@end itemize

If @var{options} is not present or @code{[]} then the default arguments are
used.  Otherwise, @var{options} replaces the default argument list.
To append user options to the defaults it is necessary to repeat the
default arguments in @var{options}.  Use a null string to pass no arguments.

If the second output @var{v} is requested the volume of the enclosing
convex hull is calculated.

@seealso{convhull, delaunayn, voronoin}
@end deftypefn
daspk_options
@c daspk_options src/DLD-FUNCTIONS/daspk.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} daspk_options ()
@deftypefnx {Loadable Function} {val =} daspk_options (@var{opt})
@deftypefnx {Loadable Function} {} daspk_options (@var{opt}, @var{val})
Query or set options for the function @code{daspk}.
When called with no arguments, the names of all available options and
their current values are displayed.
Given one argument, return the value of the corresponding option.
When called with two arguments, @code{daspk_options} set the option
@var{opt} to value @var{val}.

Options include

@table @code
@item "absolute tolerance"
Absolute tolerance.  May be either vector or scalar.  If a vector, it
must match the dimension of the state vector, and the relative
tolerance must also be a vector of the same length.

@item "relative tolerance"
Relative tolerance.  May be either vector or scalar.  If a vector, it
must match the dimension of the state vector, and the absolute
tolerance must also be a vector of the same length.

The local error test applied at each integration step is

@example
@group
  abs (local error in x(i))
       <= rtol(i) * abs (Y(i)) + atol(i)
@end group
@end example

@item "compute consistent initial condition"
Denoting the differential variables in the state vector by @samp{Y_d}
and the algebraic variables by @samp{Y_a}, @code{ddaspk} can solve
one of two initialization problems:

@enumerate
@item Given Y_d, calculate Y_a and Y'_d

@item Given Y', calculate Y.
@end enumerate

In either case, initial values for the given components are input, and
initial guesses for the unknown components must also be provided as
input.  Set this option to 1 to solve the first problem, or 2 to solve
the second (the default is 0, so you must provide a set of
initial conditions that are consistent).

If this option is set to a nonzero value, you must also set the
@code{"algebraic variables"} option to declare which variables in the
problem are algebraic.

@item "use initial condition heuristics"
Set to a nonzero value to use the initial condition heuristics options
described below.

@item "initial condition heuristics"
A vector of the following parameters that can be used to control the
initial condition calculation.

@table @code
@item MXNIT
Maximum number of Newton iterations (default is 5).

@item MXNJ
Maximum number of Jacobian evaluations (default is 6).

@item MXNH
Maximum number of values of the artificial stepsize parameter to be
tried if the @code{"compute consistent initial condition"} option has
been set to 1 (default is 5).

Note that the maximum total number of Newton iterations allowed is
@code{MXNIT*MXNJ*MXNH} if the @code{"compute consistent initial
condition"} option has been set to 1 and @code{MXNIT*MXNJ} if it is
set to 2.

@item LSOFF
Set to a nonzero value to disable the linesearch algorithm (default is
0).

@item STPTOL
Minimum scaled step in linesearch algorithm (default is eps^(2/3)).

@item EPINIT
Swing factor in the Newton iteration convergence test.  The test is
applied to the residual vector, premultiplied by the approximate
Jacobian.  For convergence, the weighted RMS norm of this vector
(scaled by the error weights) must be less than @code{EPINIT*EPCON},
where @code{EPCON} = 0.33 is the analogous test constant used in the
time steps.  The default is @code{EPINIT} = 0.01.
@end table

@item "print initial condition info"
Set this option to a nonzero value to display detailed information
about the initial condition calculation (default is 0).

@item "exclude algebraic variables from error test"
Set to a nonzero value to exclude algebraic variables from the error
test.  You must also set the @code{"algebraic variables"} option to
declare which variables in the problem are algebraic (default is 0).

@item "algebraic variables"
A vector of the same length as the state vector.  A nonzero element
indicates that the corresponding element of the state vector is an
algebraic variable (i.e., its derivative does not appear explicitly
in the equation set.

This option is required by the
@code{compute consistent initial condition"} and
@code{"exclude algebraic variables from error test"} options.

@item "enforce inequality constraints"
Set to one of the following values to enforce the inequality
constraints specified by the @code{"inequality constraint types"}
option (default is 0).

@enumerate
@item To have constraint checking only in the initial condition calculation.

@item To enforce constraint checking during the integration.

@item To enforce both options 1 and 2.
@end enumerate

@item "inequality constraint types"
A vector of the same length as the state specifying the type of
inequality constraint.  Each element of the vector corresponds to an
element of the state and should be assigned one of the following
codes

@table @asis
@item -2
Less than zero.

@item -1
Less than or equal to zero.

@item 0
Not constrained.

@item 1
Greater than or equal to zero.

@item 2
Greater than zero.
@end table

This option only has an effect if the
@code{"enforce inequality constraints"} option is nonzero.

@item "initial step size"
Differential-algebraic problems may occasionally suffer from severe
scaling difficulties on the first step.  If you know a great deal
about the scaling of your problem, you can help to alleviate this
problem by specifying an initial stepsize (default is computed
automatically).

@item "maximum order"
Restrict the maximum order of the solution method.  This option must
be between 1 and 5, inclusive (default is 5).

@item "maximum step size"
Setting the maximum stepsize will avoid passing over very large
regions (default is not specified).
@end table
@end deftypefn
daspk
@c daspk src/DLD-FUNCTIONS/daspk.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{x}, @var{xdot}, @var{istate}, @var{msg}] =} daspk (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
Solve the set of differential-algebraic equations
@tex
$$ 0 = f (x, \dot{x}, t) $$
with
$$ x(t_0) = x_0, \dot{x}(t_0) = \dot{x}_0 $$
@end tex
@ifnottex

@example
0 = f (x, xdot, t)
@end example

@noindent
with

@example
x(t_0) = x_0, xdot(t_0) = xdot_0
@end example

@end ifnottex
The solution is returned in the matrices @var{x} and @var{xdot},
with each row in the result matrices corresponding to one of the
elements in the vector @var{t}.  The first element of @var{t}
should be @math{t_0} and correspond to the initial state of the
system @var{x_0} and its derivative @var{xdot_0}, so that the first
row of the output @var{x} is @var{x_0} and the first row
of the output @var{xdot} is @var{xdot_0}.

The first argument, @var{fcn}, is a string, inline, or function handle
that names the function @math{f} to call to compute the vector of
residuals for the set of equations.  It must have the form

@example
@var{res} = f (@var{x}, @var{xdot}, @var{t})
@end example

@noindent
in which @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a
scalar.

If @var{fcn} is a two-element string array or a two-element cell array
of strings, inline functions, or function handles, the first element names
the function @math{f} described above, and the second element names a
function to compute the modified Jacobian
@tex
$$
J = {\partial f \over \partial x}
  + c {\partial f \over \partial \dot{x}}
$$
@end tex
@ifnottex

@example
@group
      df       df
jac = -- + c ------
      dx     d xdot
@end group
@end example

@end ifnottex

The modified Jacobian function must have the form

@example
@group

@var{jac} = j (@var{x}, @var{xdot}, @var{t}, @var{c})

@end group
@end example

The second and third arguments to @code{daspk} specify the initial
condition of the states and their derivatives, and the fourth argument
specifies a vector of output times at which the solution is desired,
including the time corresponding to the initial condition.

The set of initial states and derivatives are not strictly required to
be consistent.  If they are not consistent, you must use the
@code{daspk_options} function to provide additional information so
that @code{daspk} can compute a consistent starting point.

The fifth argument is optional, and may be used to specify a set of
times that the DAE solver should not integrate past.  It is useful for
avoiding difficulties with singularities and points where there is a
discontinuity in the derivative.

After a successful computation, the value of @var{istate} will be
greater than zero (consistent with the Fortran version of @sc{daspk}).

If the computation is not successful, the value of @var{istate} will be
less than zero and @var{msg} will contain additional information.

You can use the function @code{daspk_options} to set optional
parameters for @code{daspk}.
@seealso{dassl}
@end deftypefn
dasrt_options
@c dasrt_options src/DLD-FUNCTIONS/dasrt.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} dasrt_options ()
@deftypefnx {Loadable Function} {val =} dasrt_options (@var{opt})
@deftypefnx {Loadable Function} {} dasrt_options (@var{opt}, @var{val})
Query or set options for the function @code{dasrt}.
When called with no arguments, the names of all available options and
their current values are displayed.
Given one argument, return the value of the corresponding option.
When called with two arguments, @code{dasrt_options} set the option
@var{opt} to value @var{val}.

Options include

@table @code
@item "absolute tolerance"
Absolute tolerance.  May be either vector or scalar.  If a vector, it
must match the dimension of the state vector, and the relative
tolerance must also be a vector of the same length.

@item "relative tolerance"
Relative tolerance.  May be either vector or scalar.  If a vector, it
must match the dimension of the state vector, and the absolute
tolerance must also be a vector of the same length.

The local error test applied at each integration step is

@example
@group
  abs (local error in x(i)) <= ...
      rtol(i) * abs (Y(i)) + atol(i)
@end group
@end example

@item "initial step size"
Differential-algebraic problems may occasionally suffer from severe
scaling difficulties on the first step.  If you know a great deal
about the scaling of your problem, you can help to alleviate this
problem by specifying an initial stepsize.

@item "maximum order"
Restrict the maximum order of the solution method.  This option must
be between 1 and 5, inclusive.

@item "maximum step size"
Setting the maximum stepsize will avoid passing over very large
regions.

@item "step limit"
Maximum number of integration steps to attempt on a single call to the
underlying Fortran code.
@end table
@end deftypefn
dasrt
@c dasrt src/DLD-FUNCTIONS/dasrt.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{x}, @var{xdot}, @var{t_out}, @var{istat}, @var{msg}] =} dasrt (@var{fcn}, [], @var{x_0}, @var{xdot_0}, @var{t})
@deftypefnx {Loadable Function} {@dots{} =} dasrt (@var{fcn}, @var{g}, @var{x_0}, @var{xdot_0}, @var{t})
@deftypefnx {Loadable Function} {@dots{} =} dasrt (@var{fcn}, [], @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
@deftypefnx {Loadable Function} {@dots{} =} dasrt (@var{fcn}, @var{g}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
Solve the set of differential-algebraic equations
@tex
$$ 0 = f (x, \dot{x}, t) $$
with
$$ x(t_0) = x_0, \dot{x}(t_0) = \dot{x}_0 $$
@end tex
@ifnottex

@example
0 = f (x, xdot, t)
@end example

@noindent
with

@example
x(t_0) = x_0, xdot(t_0) = xdot_0
@end example

@end ifnottex
with functional stopping criteria (root solving).

The solution is returned in the matrices @var{x} and @var{xdot},
with each row in the result matrices corresponding to one of the
elements in the vector @var{t_out}.  The first element of @var{t}
should be @math{t_0} and correspond to the initial state of the
system @var{x_0} and its derivative @var{xdot_0}, so that the first
row of the output @var{x} is @var{x_0} and the first row
of the output @var{xdot} is @var{xdot_0}.

The vector @var{t} provides an upper limit on the length of the
integration.  If the stopping condition is met, the vector
@var{t_out} will be shorter than @var{t}, and the final element of
@var{t_out} will be the point at which the stopping condition was met,
and may not correspond to any element of the vector @var{t}.

The first argument, @var{fcn}, is a string, inline, or function handle
that names the function @math{f} to call to compute the vector of
residuals for the set of equations.  It must have the form

@example
@var{res} = f (@var{x}, @var{xdot}, @var{t})
@end example

@noindent
in which @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a
scalar.

If @var{fcn} is a two-element string array or a two-element cell array
of strings, inline functions, or function handles, the first element names
the function @math{f} described above, and the second element names a
function to compute the modified Jacobian

@tex
$$
J = {\partial f \over \partial x}
  + c {\partial f \over \partial \dot{x}}
$$
@end tex
@ifnottex

@example
@group
      df       df
jac = -- + c ------
      dx     d xdot
@end group
@end example

@end ifnottex

The modified Jacobian function must have the form

@example
@group

@var{jac} = j (@var{x}, @var{xdot}, @var{t}, @var{c})

@end group
@end example

The optional second argument names a function that defines the
constraint functions whose roots are desired during the integration.
This function must have the form

@example
@var{g_out} = g (@var{x}, @var{t})
@end example

@noindent
and return a vector of the constraint function values.
If the value of any of the constraint functions changes sign, @sc{dasrt}
will attempt to stop the integration at the point of the sign change.

If the name of the constraint function is omitted, @code{dasrt} solves
the same problem as @code{daspk} or @code{dassl}.

Note that because of numerical errors in the constraint functions
due to round-off and integration error, @sc{dasrt} may return false
roots, or return the same root at two or more nearly equal values of
@var{T}.  If such false roots are suspected, the user should consider
smaller error tolerances or higher precision in the evaluation of the
constraint functions.

If a root of some constraint function defines the end of the problem,
the input to @sc{dasrt} should nevertheless allow integration to a
point slightly past that root, so that @sc{dasrt} can locate the root
by interpolation.

The third and fourth arguments to @code{dasrt} specify the initial
condition of the states and their derivatives, and the fourth argument
specifies a vector of output times at which the solution is desired,
including the time corresponding to the initial condition.

The set of initial states and derivatives are not strictly required to
be consistent.  In practice, however, @sc{dassl} is not very good at
determining a consistent set for you, so it is best if you ensure that
the initial values result in the function evaluating to zero.

The sixth argument is optional, and may be used to specify a set of
times that the DAE solver should not integrate past.  It is useful for
avoiding difficulties with singularities and points where there is a
discontinuity in the derivative.

After a successful computation, the value of @var{istate} will be
greater than zero (consistent with the Fortran version of @sc{dassl}).

If the computation is not successful, the value of @var{istate} will be
less than zero and @var{msg} will contain additional information.

You can use the function @code{dasrt_options} to set optional
parameters for @code{dasrt}.
@seealso{dasrt_options, daspk, dasrt, lsode}
@end deftypefn
dassl_options
@c dassl_options src/DLD-FUNCTIONS/dassl.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} dassl_options ()
@deftypefnx {Loadable Function} {val =} dassl_options (@var{opt})
@deftypefnx {Loadable Function} {} dassl_options (@var{opt}, @var{val})
Query or set options for the function @code{dassl}.
When called with no arguments, the names of all available options and
their current values are displayed.
Given one argument, return the value of the corresponding option.
When called with two arguments, @code{dassl_options} set the option
@var{opt} to value @var{val}.

Options include

@table @code
@item "absolute tolerance"
Absolute tolerance.  May be either vector or scalar.  If a vector, it
must match the dimension of the state vector, and the relative
tolerance must also be a vector of the same length.

@item "relative tolerance"
Relative tolerance.  May be either vector or scalar.  If a vector, it
must match the dimension of the state vector, and the absolute
tolerance must also be a vector of the same length.

The local error test applied at each integration step is

@example
@group
  abs (local error in x(i))
       <= rtol(i) * abs (Y(i)) + atol(i)
@end group
@end example

@item "compute consistent initial condition"
If nonzero, @code{dassl} will attempt to compute a consistent set of initial
conditions.  This is generally not reliable, so it is best to provide
a consistent set and leave this option set to zero.

@item "enforce nonnegativity constraints"
If you know that the solutions to your equations will always be
non-negative, it may help to set this parameter to a nonzero
value.  However, it is probably best to try leaving this option set to
zero first, and only setting it to a nonzero value if that doesn't
work very well.

@item "initial step size"
Differential-algebraic problems may occasionally suffer from severe
scaling difficulties on the first step.  If you know a great deal
about the scaling of your problem, you can help to alleviate this
problem by specifying an initial stepsize.

@item "maximum order"
Restrict the maximum order of the solution method.  This option must
be between 1 and 5, inclusive.

@item "maximum step size"
Setting the maximum stepsize will avoid passing over very large
regions  (default is not specified).

@item "step limit"
Maximum number of integration steps to attempt on a single call to the
underlying Fortran code.
@end table
@end deftypefn
dassl
@c dassl src/DLD-FUNCTIONS/dassl.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{x}, @var{xdot}, @var{istate}, @var{msg}] =} dassl (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
Solve the set of differential-algebraic equations
@tex
$$ 0 = f (x, \dot{x}, t) $$
with
$$ x(t_0) = x_0, \dot{x}(t_0) = \dot{x}_0 $$
@end tex
@ifnottex

@example
0 = f (x, xdot, t)
@end example

@noindent
with

@example
x(t_0) = x_0, xdot(t_0) = xdot_0
@end example

@end ifnottex
The solution is returned in the matrices @var{x} and @var{xdot},
with each row in the result matrices corresponding to one of the
elements in the vector @var{t}.  The first element of @var{t}
should be @math{t_0} and correspond to the initial state of the
system @var{x_0} and its derivative @var{xdot_0}, so that the first
row of the output @var{x} is @var{x_0} and the first row
of the output @var{xdot} is @var{xdot_0}.

The first argument, @var{fcn}, is a string, inline, or function handle
that names the function @math{f} to call to compute the vector of
residuals for the set of equations.  It must have the form

@example
@var{res} = f (@var{x}, @var{xdot}, @var{t})
@end example

@noindent
in which @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a
scalar.

If @var{fcn} is a two-element string array or a two-element cell array
of strings, inline functions, or function handles, the first element names
the function @math{f} described above, and the second element names a
function to compute the modified Jacobian

@tex
$$
J = {\partial f \over \partial x}
  + c {\partial f \over \partial \dot{x}}
$$
@end tex
@ifnottex

@example
@group
      df       df
jac = -- + c ------
      dx     d xdot
@end group
@end example

@end ifnottex

The modified Jacobian function must have the form

@example
@group

@var{jac} = j (@var{x}, @var{xdot}, @var{t}, @var{c})

@end group
@end example

The second and third arguments to @code{dassl} specify the initial
condition of the states and their derivatives, and the fourth argument
specifies a vector of output times at which the solution is desired,
including the time corresponding to the initial condition.

The set of initial states and derivatives are not strictly required to
be consistent.  In practice, however, @sc{dassl} is not very good at
determining a consistent set for you, so it is best if you ensure that
the initial values result in the function evaluating to zero.

The fifth argument is optional, and may be used to specify a set of
times that the DAE solver should not integrate past.  It is useful for
avoiding difficulties with singularities and points where there is a
discontinuity in the derivative.

After a successful computation, the value of @var{istate} will be
greater than zero (consistent with the Fortran version of @sc{dassl}).

If the computation is not successful, the value of @var{istate} will be
less than zero and @var{msg} will contain additional information.

You can use the function @code{dassl_options} to set optional
parameters for @code{dassl}.
@seealso{daspk, dasrt, lsode}
@end deftypefn
det
@c det src/DLD-FUNCTIONS/det.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} det (@var{A})
@deftypefnx {Loadable Function} {[@var{d}, @var{rcond}] =} det (@var{A})
Compute the determinant of @var{A}.

Return an estimate of the reciprocal condition number if requested.

Routines from @sc{lapack} are used for full matrices and code from
@sc{umfpack} is used for sparse matrices.

The determinant should not be used to check a matrix for singularity.
For that, use any of the condition number functions: @code{cond},
@code{condest}, @code{rcond}.
@seealso{cond, condest, rcond}
@end deftypefn
dlmread
@c dlmread src/DLD-FUNCTIONS/dlmread.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{data} =} dlmread (@var{file})
@deftypefnx {Loadable Function} {@var{data} =} dlmread (@var{file}, @var{sep})
@deftypefnx {Loadable Function} {@var{data} =} dlmread (@var{file}, @var{sep}, @var{r0}, @var{c0})
@deftypefnx {Loadable Function} {@var{data} =} dlmread (@var{file}, @var{sep}, @var{range})
@deftypefnx {Loadable Function} {@var{data} =} dlmread (@dots{}, "emptyvalue", @var{EMPTYVAL})
Read the matrix @var{data} from a text file.  If not defined the separator
between fields is determined from the file itself.  Otherwise the
separation character is defined by @var{sep}.

Given two scalar arguments @var{r0} and @var{c0}, these define the starting
row and column of the data to be read.  These values are indexed from zero,
such that the first row corresponds to an index of zero.

The @var{range} parameter may be a 4-element vector containing the upper
left and lower right corner @code{[@var{R0},@var{C0},@var{R1},@var{C1}]}
where the lowest index value is zero.  Alternatively, a spreadsheet style
range such as 'A2..Q15' or 'T1:AA5' can be used.  The lowest alphabetical
index 'A' refers to the first column.  The lowest row index is 1.

@var{file} should be a file name or file id given by @code{fopen}.  In the
latter case, the file is read until end of file is reached.

The "emptyvalue" option may be used to specify the value used to fill empty
fields.  The default is zero.
@seealso{csvread, textscan, textread, dlmwrite}
@end deftypefn
dmperm
@c dmperm src/DLD-FUNCTIONS/dmperm.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{p} =} dmperm (@var{S})
@deftypefnx {Loadable Function} {[@var{p}, @var{q}, @var{r}, @var{S}] =} dmperm (@var{S})

@cindex Dulmage-Mendelsohn decomposition
Perform a Dulmage-Mendelsohn permutation of the sparse matrix @var{S}.
With a single output argument @code{dmperm} performs the row permutations
@var{p} such that @code{@var{S}(@var{p},:)} has no zero elements on the
diagonal.

Called with two or more output arguments, returns the row and column
permutations, such that @code{@var{S}(@var{p}, @var{q})} is in block
triangular form.  The values of @var{r} and @var{S} define the boundaries
of the blocks.  If @var{S} is square then @code{@var{r} == @var{S}}.

The method used is described in: A. Pothen & C.-J. Fan. @cite{Computing the
Block Triangular Form of a Sparse Matrix}. ACM Trans. Math. Software,
16(4):303-324, 1990.
@seealso{colamd, ccolamd}
@end deftypefn
sprank
@c sprank src/DLD-FUNCTIONS/dmperm.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{p} =} sprank (@var{S})
@cindex structural rank

Calculate the structural rank of the sparse matrix @var{S}.  Note that
only the structure of the matrix is used in this calculation based on
a Dulmage-Mendelsohn permutation to block triangular form.  As such the
numerical rank of the matrix @var{S} is bounded by
@code{sprank (@var{S}) >= rank (@var{S})}.  Ignoring floating point errors
@code{sprank (@var{S}) == rank (@var{S})}.
@seealso{dmperm}
@end deftypefn
dot
@c dot src/DLD-FUNCTIONS/dot.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} dot (@var{x}, @var{y}, @var{dim})
Compute the dot product of two vectors.  If @var{x} and @var{y}
are matrices, calculate the dot products along the first
non-singleton dimension.  If the optional argument @var{dim} is
given, calculate the dot products along this dimension.

This is equivalent to
@code{sum (conj (@var{X}) .* @var{Y}, @var{dim})},
but avoids forming a temporary array and is faster.  When @var{X} and
@var{Y} are column vectors, the result is equivalent to
@code{@var{X}' * @var{Y}}.
@seealso{cross, divergence}
@end deftypefn
blkmm
@c blkmm src/DLD-FUNCTIONS/dot.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} blkmm (@var{A}, @var{B})
Compute products of matrix blocks.  The blocks are given as
2-dimensional subarrays of the arrays @var{A}, @var{B}.
The size of @var{A} must have the form @code{[m,k,@dots{}]} and
size of @var{B} must be @code{[k,n,@dots{}]}.  The result is
then of size @code{[m,n,@dots{}]} and is computed as follows:

@example
@group
  for i = 1:prod (size (@var{A})(3:end))
    @var{C}(:,:,i) = @var{A}(:,:,i) * @var{B}(:,:,i)
  endfor
@end group
@end example
@end deftypefn
eig
@c eig src/DLD-FUNCTIONS/eig.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{lambda} =} eig (@var{A})
@deftypefnx {Loadable Function} {@var{lambda} =} eig (@var{A}, @var{B})
@deftypefnx {Loadable Function} {[@var{V}, @var{lambda}] =} eig (@var{A})
@deftypefnx {Loadable Function} {[@var{V}, @var{lambda}] =} eig (@var{A}, @var{B})
Compute the eigenvalues and eigenvectors of a matrix.

Eigenvalues are computed in a several step process which begins with a
Hessenberg decomposition, followed by a Schur@tie{}decomposition, from which
the eigenvalues are apparent.  The eigenvectors, when desired, are computed
by further manipulations of the Schur@tie{}decomposition.

The eigenvalues returned by @code{eig} are not ordered.
@seealso{eigs, svd}
@end deftypefn
eigs
@c eigs src/DLD-FUNCTIONS/eigs.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{d} =} eigs (@var{A})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{k})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{k}, @var{sigma})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{B})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{B}, @var{k})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{B}, @var{k}, @var{sigma})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{B}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{B})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{k})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{B}, @var{k})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{k}, @var{sigma})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {Loadable Function} {[@var{V}, @var{d}] =} eigs (@var{A}, @dots{})
@deftypefnx {Loadable Function} {[@var{V}, @var{d}] =} eigs (@var{af}, @var{n}, @dots{})
@deftypefnx {Loadable Function} {[@var{V}, @var{d}, @var{flag}] =} eigs (@var{A}, @dots{})
@deftypefnx {Loadable Function} {[@var{V}, @var{d}, @var{flag}] =} eigs (@var{af}, @var{n}, @dots{})
Calculate a limited number of eigenvalues and eigenvectors of @var{A},
based on a selection criteria.  The number of eigenvalues and eigenvectors to
calculate is given by @var{k} and defaults to 6.

By default, @code{eigs} solve the equation
@tex
$A \nu = \lambda \nu$,
@end tex
@ifinfo
@code{A * v = lambda * v},
@end ifinfo
where
@tex
$\lambda$ is a scalar representing one of the eigenvalues, and $\nu$
@end tex
@ifinfo
@code{lambda} is a scalar representing one of the eigenvalues, and @code{v}
@end ifinfo
is the corresponding eigenvector.  If given the positive definite matrix
@var{B} then @code{eigs} solves the general eigenvalue equation
@tex
$A \nu = \lambda B \nu$.
@end tex
@ifinfo
@code{A * v = lambda * B * v}.
@end ifinfo

The argument @var{sigma} determines which eigenvalues are returned.
@var{sigma} can be either a scalar or a string.  When @var{sigma} is a
scalar, the @var{k} eigenvalues closest to @var{sigma} are returned.  If
@var{sigma} is a string, it must have one of the following values.

@table @asis
@item 'lm'
Largest Magnitude (default).

@item 'sm'
Smallest Magnitude.

@item 'la'
Largest Algebraic (valid only for real symmetric problems).

@item 'sa'
Smallest Algebraic (valid only for real symmetric problems).

@item 'be'
Both Ends, with one more from the high-end if @var{k} is odd (valid only for
real symmetric problems).

@item 'lr'
Largest Real part (valid only for complex or unsymmetric problems).

@item 'sr'
Smallest Real part (valid only for complex or unsymmetric problems).

@item 'li'
Largest Imaginary part (valid only for complex or unsymmetric problems).

@item 'si'
Smallest Imaginary part (valid only for complex or unsymmetric problems).
@end table

If @var{opts} is given, it is a structure defining possible options that
@code{eigs} should use.  The fields of the @var{opts} structure are:

@table @code
@item issym
If @var{af} is given, then flags whether the function @var{af} defines a
symmetric problem.  It is ignored if @var{A} is given.  The default is false.

@item isreal
If @var{af} is given, then flags whether the function @var{af} defines a
real problem.  It is ignored if @var{A} is given.  The default is true.

@item tol
Defines the required convergence tolerance, calculated as
@code{tol * norm (A)}.  The default is @code{eps}.

@item maxit
The maximum number of iterations.  The default is 300.

@item p
The number of Lanzcos basis vectors to use.  More vectors will result in
faster convergence, but a greater use of memory.  The optimal value of
@code{p} is problem dependent and should be in the range @var{k} to @var{n}.
The default value is @code{2 * @var{k}}.

@item v0
The starting vector for the algorithm.  An initial vector close to the
final vector will speed up convergence.  The default is for @sc{arpack}
to randomly generate a starting vector.  If specified, @code{v0} must be
an @var{n}-by-1 vector where @code{@var{n} = rows (@var{A})}

@item disp
The level of diagnostic printout (0|1|2).  If @code{disp} is 0 then
diagnostics are disabled.  The default value is 0.

@item cholB
Flag if @code{chol (@var{B})} is passed rather than @var{B}.  The default is
false.

@item permB
The permutation vector of the Cholesky@tie{}factorization of @var{B} if
@code{cholB} is true.  That is @code{chol (@var{B}(permB, permB))}.  The
default is @code{1:@var{n}}.

@end table
It is also possible to represent @var{A} by a function denoted @var{af}.
@var{af} must be followed by a scalar argument @var{n} defining the length
of the vector argument accepted by @var{af}.  @var{af} can be
a function handle, an inline function, or a string.  When @var{af} is a
string it holds the name of the function to use.

@var{af} is a function of the form @code{y = af (x)}
where the required return value of @var{af} is determined by
the value of @var{sigma}.  The four possible forms are

@table @code
@item A * x
if @var{sigma} is not given or is a string other than 'sm'.

@item A \ x
if @var{sigma} is 0 or 'sm'.

@item (A - sigma * I) \ x
for the standard eigenvalue problem, where @code{I} is the identity matrix of
the same size as @var{A}.

@item (A - sigma * B) \ x
for the general eigenvalue problem.
@end table

The return arguments of @code{eigs} depend on the number of return arguments
requested.  With a single return argument, a vector @var{d} of length @var{k}
is returned containing the @var{k} eigenvalues that have been found.  With
two return arguments, @var{V} is a @var{n}-by-@var{k} matrix whose columns
are the @var{k} eigenvectors corresponding to the returned eigenvalues.  The
eigenvalues themselves are returned in @var{d} in the form of a
@var{n}-by-@var{k} matrix, where the elements on the diagonal are the
eigenvalues.

Given a third return argument @var{flag}, @code{eigs} returns the status
of the convergence.  If @var{flag} is 0 then all eigenvalues have converged.
Any other value indicates a failure to converge.

This function is based on the @sc{arpack} package, written by R. Lehoucq,
K. Maschhoff, D. Sorensen, and C. Yang.  For more information see
@url{http://www.caam.rice.edu/software/ARPACK/}.

@seealso{eig, svds}
@end deftypefn
fft
@c fft src/DLD-FUNCTIONS/fft.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} fft (@var{x})
@deftypefnx {Loadable Function} {} fft (@var{x}, @var{n})
@deftypefnx {Loadable Function} {} fft (@var{x}, @var{n}, @var{dim})
Compute the discrete Fourier transform of @var{A} using
a Fast Fourier Transform (FFT) algorithm.

The FFT is calculated along the first non-singleton dimension of the
array.  Thus if @var{x} is a matrix, @code{fft (@var{x})} computes the
FFT for each column of @var{x}.

If called with two arguments, @var{n} is expected to be an integer
specifying the number of elements of @var{x} to use, or an empty
matrix to specify that its value should be ignored.  If @var{n} is
larger than the dimension along which the FFT is calculated, then
@var{x} is resized and padded with zeros.  Otherwise, if @var{n} is
smaller than the dimension along which the FFT is calculated, then
@var{x} is truncated.

If called with three arguments, @var{dim} is an integer specifying the
dimension of the matrix along which the FFT is performed
@seealso{ifft, fft2, fftn, fftw}
@end deftypefn
ifft
@c ifft src/DLD-FUNCTIONS/fft.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} ifft (@var{x})
@deftypefnx {Loadable Function} {} ifft (@var{x}, @var{n})
@deftypefnx {Loadable Function} {} ifft (@var{x}, @var{n}, @var{dim})
Compute the inverse discrete Fourier transform of @var{A}
using a Fast Fourier Transform (FFT) algorithm.

The inverse FFT is calculated along the first non-singleton dimension
of the array.  Thus if @var{x} is a matrix, @code{fft (@var{x})} computes
the inverse FFT for each column of @var{x}.

If called with two arguments, @var{n} is expected to be an integer
specifying the number of elements of @var{x} to use, or an empty
matrix to specify that its value should be ignored.  If @var{n} is
larger than the dimension along which the inverse FFT is calculated, then
@var{x} is resized and padded with zeros.  Otherwise, if @var{n} is
smaller than the dimension along which the inverse FFT is calculated,
then @var{x} is truncated.

If called with three arguments, @var{dim} is an integer specifying the
dimension of the matrix along which the inverse FFT is performed
@seealso{fft, ifft2, ifftn, fftw}
@end deftypefn
fft2
@c fft2 src/DLD-FUNCTIONS/fft2.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} fft2 (@var{A})
@deftypefnx {Loadable Function} {} fft2 (@var{A}, @var{m}, @var{n})
Compute the two-dimensional discrete Fourier transform of @var{A} using
a Fast Fourier Transform (FFT) algorithm.

The optional arguments @var{m} and @var{n} may be used specify the
number of rows and columns of @var{A} to use.  If either of these is
larger than the size of @var{A}, @var{A} is resized and padded with
zeros.

If @var{A} is a multi-dimensional matrix, each two-dimensional sub-matrix
of @var{A} is treated separately.
@seealso {ifft2, fft, fftn, fftw}
@end deftypefn
ifft2
@c ifft2 src/DLD-FUNCTIONS/fft2.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} ifft2 (@var{A})
@deftypefnx {Loadable Function} {} ifft2 (@var{A}, @var{m}, @var{n})
Compute the inverse two-dimensional discrete Fourier transform of @var{A}
using a Fast Fourier Transform (FFT) algorithm.

The optional arguments @var{m} and @var{n} may be used specify the
number of rows and columns of @var{A} to use.  If either of these is
larger than the size of @var{A}, @var{A} is resized and padded with
zeros.

If @var{A} is a multi-dimensional matrix, each two-dimensional sub-matrix
of @var{A} is treated separately
@seealso {fft2, ifft, ifftn, fftw}
@end deftypefn
fftn
@c fftn src/DLD-FUNCTIONS/fftn.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} fftn (@var{A})
@deftypefnx {Loadable Function} {} fftn (@var{A}, @var{size})
Compute the N-dimensional discrete Fourier transform of @var{A} using
a Fast Fourier Transform (FFT) algorithm.

The optional vector argument @var{size} may be used specify the
dimensions of the array to be used.  If an element of @var{size} is
smaller than the corresponding dimension of @var{A}, then the dimension of
@var{A} is truncated prior to performing the FFT@.  Otherwise, if an element
of @var{size} is larger than the corresponding dimension then @var{A}
is resized and padded with zeros.
@seealso{ifftn, fft, fft2, fftw}
@end deftypefn
ifftn
@c ifftn src/DLD-FUNCTIONS/fftn.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} ifftn (@var{A})
@deftypefnx {Loadable Function} {} ifftn (@var{A}, @var{size})
Compute the inverse N-dimensional discrete Fourier transform of @var{A}
using a Fast Fourier Transform (FFT) algorithm.

The optional vector argument @var{size} may be used specify the
dimensions of the array to be used.  If an element of @var{size} is
smaller than the corresponding dimension of @var{A}, then the dimension of
@var{A} is truncated prior to performing the inverse FFT@.  Otherwise, if an
element of @var{size} is larger than the corresponding dimension then @var{A}
is resized and padded with zeros.
@seealso{fftn, ifft, ifft2, fftw}
@end deftypefn
fftw
@c fftw src/DLD-FUNCTIONS/fftw.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{method} =} fftw ('planner')
@deftypefnx {Loadable Function} {} fftw ('planner', @var{method})
@deftypefnx {Loadable Function} {@var{wisdom} =} fftw ('dwisdom')
@deftypefnx {Loadable Function} {} fftw ('dwisdom', @var{wisdom})

Manage @sc{fftw} wisdom data.  Wisdom data can be used to significantly
accelerate the calculation of the FFTs, but implies an initial cost
in its calculation.  When the @sc{fftw} libraries are initialized, they read
a system wide wisdom file (typically in @file{/etc/fftw/wisdom}), allowing
wisdom to be shared between applications other than Octave.  Alternatively,
the @code{fftw} function can be used to import wisdom.  For example,

@example
@var{wisdom} = fftw ('dwisdom')
@end example

@noindent
will save the existing wisdom used by Octave to the string @var{wisdom}.
This string can then be saved to a file and restored using the @code{save}
and @code{load} commands respectively.  This existing wisdom can be
reimported as follows

@example
fftw ('dwisdom', @var{wisdom})
@end example

If @var{wisdom} is an empty matrix, then the wisdom used is cleared.

During the calculation of Fourier transforms further wisdom is generated.
The fashion in which this wisdom is generated is also controlled by
the @code{fftw} function.  There are five different manners in which the
wisdom can be treated:

@table @asis
@item 'estimate'
Specifies that no run-time measurement of the optimal means of
calculating a particular is performed, and a simple heuristic is used
to pick a (probably sub-optimal) plan.  The advantage of this method is
that there is little or no overhead in the generation of the plan, which
is appropriate for a Fourier transform that will be calculated once.

@item 'measure'
In this case a range of algorithms to perform the transform is considered
and the best is selected based on their execution time.

@item 'patient'
Similar to 'measure', but a wider range of algorithms is considered.

@item 'exhaustive'
Like 'measure', but all possible algorithms that may be used to
treat the transform are considered.

@item 'hybrid'
As run-time measurement of the algorithm can be expensive, this is a
compromise where 'measure' is used for transforms up to the size of 8192
and beyond that the 'estimate' method is used.
@end table

The default method is 'estimate'.  The current method can
be queried with

@example
@var{method} = fftw ('planner')
@end example

@noindent
or set by using

@example
fftw ('planner', @var{method})
@end example

Note that calculated wisdom will be lost when restarting Octave.  However,
the wisdom data can be reloaded if it is saved to a file as described
above.  Saved wisdom files should not be used on different platforms since
they will not be efficient and the point of calculating the wisdom is lost.
@seealso{fft, ifft, fft2, ifft2, fftn, ifftn}
@end deftypefn
filter
@c filter src/DLD-FUNCTIONS/filter.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {y =} filter (@var{b}, @var{a}, @var{x})
@deftypefnx {Loadable Function} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, @var{si})
@deftypefnx {Loadable Function} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, [], @var{dim})
@deftypefnx {Loadable Function} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, @var{si}, @var{dim})
Return the solution to the following linear, time-invariant difference
equation:
@tex
$$
\sum_{k=0}^N a_{k+1} y_{n-k} = \sum_{k=0}^M b_{k+1} x_{n-k}, \qquad
 1 \le n \le P
$$
@end tex
@ifnottex
@c Set example in small font to prevent overfull line

@smallexample
@group
   N                   M
  SUM a(k+1) y(n-k) = SUM b(k+1) x(n-k)      for 1<=n<=length(x)
  k=0                 k=0
@end group
@end smallexample

@end ifnottex

@noindent
where
@ifnottex
 N=length(a)-1 and M=length(b)-1.
@end ifnottex
@tex
 $a \in \Re^{N-1}$, $b \in \Re^{M-1}$, and $x \in \Re^P$.
@end tex
over the first non-singleton dimension of @var{x} or over @var{dim} if
supplied.  An equivalent form of this equation is:
@tex
$$
y_n = -\sum_{k=1}^N c_{k+1} y_{n-k} + \sum_{k=0}^M d_{k+1} x_{n-k}, \qquad
 1 \le n \le P
$$
@end tex
@ifnottex
@c Set example in small font to prevent overfull line

@smallexample
@group
            N                   M
  y(n) = - SUM c(k+1) y(n-k) + SUM d(k+1) x(n-k)  for 1<=n<=length(x)
           k=1                 k=0
@end group
@end smallexample

@end ifnottex

@noindent
where
@ifnottex
 c = a/a(1) and d = b/a(1).
@end ifnottex
@tex
$c = a/a_1$ and $d = b/a_1$.
@end tex

If the fourth argument @var{si} is provided, it is taken as the
initial state of the system and the final state is returned as
@var{sf}.  The state vector is a column vector whose length is
equal to the length of the longest coefficient vector minus one.
If @var{si} is not supplied, the initial state vector is set to all
zeros.

In terms of the Z Transform, y is the result of passing the discrete-
time signal x through a system characterized by the following rational
system function:
@tex
$$
H(z) = {\displaystyle\sum_{k=0}^M d_{k+1} z^{-k}
        \over 1 + \displaystyle\sum_{k+1}^N c_{k+1} z^{-k}}
$$
@end tex
@ifnottex

@example
@group
             M
            SUM d(k+1) z^(-k)
            k=0
  H(z) = ----------------------
               N
          1 + SUM c(k+1) z^(-k)
              k=1
@end group
@end example

@end ifnottex
@seealso{filter2, fftfilt, freqz}
@end deftypefn
find
@c find src/DLD-FUNCTIONS/find.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{idx} =} find (@var{x})
@deftypefnx {Loadable Function} {@var{idx} =} find (@var{x}, @var{n})
@deftypefnx {Loadable Function} {@var{idx} =} find (@var{x}, @var{n}, @var{direction})
@deftypefnx {Loadable Function} {[i, j] =} find (@dots{})
@deftypefnx {Loadable Function} {[i, j, v] =} find (@dots{})
Return a vector of indices of nonzero elements of a matrix, as a row if
@var{x} is a row vector or as a column otherwise.  To obtain a single index
for each matrix element, Octave pretends that the columns of a matrix form
one long vector (like Fortran arrays are stored).  For example:

@example
@group
find (eye (2))
     @result{} [ 1; 4 ]
@end group
@end example

If two outputs are requested, @code{find} returns the row and column
indices of nonzero elements of a matrix.  For example:

@example
@group
[i, j] = find (2 * eye (2))
     @result{} i = [ 1; 2 ]
     @result{} j = [ 1; 2 ]
@end group
@end example

If three outputs are requested, @code{find} also returns a vector
containing the nonzero values.  For example:

@example
@group
[i, j, v] = find (3 * eye (2))
     @result{} i = [ 1; 2 ]
     @result{} j = [ 1; 2 ]
     @result{} v = [ 3; 3 ]
@end group
@end example

If two inputs are given, @var{n} indicates the maximum number of
elements to find from the beginning of the matrix or vector.

If three inputs are given, @var{direction} should be one of "first" or
"last", requesting only the first or last @var{n} indices, respectively.
However, the indices are always returned in ascending order.

Note that this function is particularly useful for sparse matrices, as
it extracts the non-zero elements as vectors, which can then be used to
create the original matrix.  For example:

@example
@group
sz = size (a);
[i, j, v] = find (a);
b = sparse (i, j, v, sz(1), sz(2));
@end group
@end example
@seealso{nonzeros}
@end deftypefn
gammainc
@c gammainc src/DLD-FUNCTIONS/gammainc.cc
-*- texinfo -*-
@deftypefn  {Mapping Function} {} gammainc (@var{x}, @var{a})
@deftypefnx {Mapping Function} {} gammainc (@var{x}, @var{a}, "lower")
@deftypefnx {Mapping Function} {} gammainc (@var{x}, @var{a}, "upper")
Compute the normalized incomplete gamma function,
@tex
$$
 \gamma (x, a) = {1 \over {\Gamma (a)}}\displaystyle{\int_0^x t^{a-1} e^{-t} dt}
$$
@end tex
@ifnottex

@example
@group
                                 x
                       1        /
gammainc (x, a) = ---------    | exp (-t) t^(a-1) dt
                   gamma (a)    /
                             t=0
@end group
@end example

@end ifnottex
with the limiting value of 1 as @var{x} approaches infinity.
The standard notation is @math{P(a,x)}, e.g., Abramowitz and Stegun (6.5.1).

If @var{a} is scalar, then @code{gammainc (@var{x}, @var{a})} is returned
for each element of @var{x} and vice versa.

If neither @var{x} nor @var{a} is scalar, the sizes of @var{x} and
@var{a} must agree, and @code{gammainc} is applied element-by-element.

By default the incomplete gamma function integrated from 0 to @var{x} is
computed.  If "upper" is given then the complementary function integrated
from @var{x} to infinity is calculated.  It should be noted that

@example
gammainc (@var{x}, @var{a}) @equiv{} 1 - gammainc (@var{x}, @var{a}, "upper")
@end example
@seealso{gamma, lgamma}
@end deftypefn
gcd
@c gcd src/DLD-FUNCTIONS/gcd.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{g} =} gcd (@var{a1}, @var{a2}, @dots{})
@deftypefnx {Loadable Function} {[@var{g}, @var{v1}, @dots{}] =} gcd (@var{a1}, @var{a2}, @dots{})

Compute the greatest common divisor of @var{a1}, @var{a2}, @dots{}.  If more
than one argument is given all arguments must be the same size or scalar.
In this case the greatest common divisor is calculated for each element
individually.  All elements must be ordinary or Gaussian (complex)
integers.  Note that for Gaussian integers, the gcd is not unique up to
units (multiplication by 1, -1, @var{i} or -@var{i}), so an arbitrary
greatest common divisor amongst four possible is returned.  For example,

@noindent
and

@example
@group
gcd ([15, 9], [20, 18])
    @result{}  5  9
@end group
@end example

Optional return arguments @var{v1}, etc., contain integer vectors such
that,

@tex
$g = v_1 a_1 + v_2 a_2 + \cdots$
@end tex
@ifnottex

@example
@var{g} = @var{v1} .* @var{a1} + @var{v2} .* @var{a2} + @dots{}
@end example

@end ifnottex

@seealso{lcm, factor}
@end deftypefn
getgrent
@c getgrent src/DLD-FUNCTIONS/getgrent.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{grp_struct} =} getgrent ()
Return an entry from the group database, opening it if necessary.
Once the end of data has been reached, @code{getgrent} returns 0.
@end deftypefn
getgrgid
@c getgrgid src/DLD-FUNCTIONS/getgrent.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{grp_struct} =} getgrgid (@var{gid}).
Return the first entry from the group database with the group ID
@var{gid}.  If the group ID does not exist in the database,
@code{getgrgid} returns 0.
@end deftypefn
getgrnam
@c getgrnam src/DLD-FUNCTIONS/getgrent.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{grp_struct} =} getgrnam (@var{name})
Return the first entry from the group database with the group name
@var{name}.  If the group name does not exist in the database,
@code{getgrnam} returns 0.
@end deftypefn
setgrent
@c setgrent src/DLD-FUNCTIONS/getgrent.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} setgrent ()
Return the internal pointer to the beginning of the group database.
@end deftypefn
endgrent
@c endgrent src/DLD-FUNCTIONS/getgrent.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} endgrent ()
Close the group database.
@end deftypefn
getpwent
@c getpwent src/DLD-FUNCTIONS/getpwent.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{pw_struct} =} getpwent ()
Return a structure containing an entry from the password database,
opening it if necessary.  Once the end of the data has been reached,
@code{getpwent} returns 0.
@end deftypefn
getpwuid
@c getpwuid src/DLD-FUNCTIONS/getpwent.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{pw_struct} =} getpwuid (@var{uid}).
Return a structure containing the first entry from the password database
with the user ID @var{uid}.  If the user ID does not exist in the
database, @code{getpwuid} returns 0.
@end deftypefn
getpwnam
@c getpwnam src/DLD-FUNCTIONS/getpwent.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{pw_struct} =} getpwnam (@var{name})
Return a structure containing the first entry from the password database
with the user name @var{name}.  If the user name does not exist in the
database, @code{getpwname} returns 0.
@end deftypefn
setpwent
@c setpwent src/DLD-FUNCTIONS/getpwent.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} setpwent ()
Return the internal pointer to the beginning of the password database.
@end deftypefn
endpwent
@c endpwent src/DLD-FUNCTIONS/getpwent.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} endpwent ()
Close the password database.
@end deftypefn
getrusage
@c getrusage src/DLD-FUNCTIONS/getrusage.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} getrusage ()
Return a structure containing a number of statistics about the current
Octave process.  Not all fields are available on all systems.  If it is
not possible to get CPU time statistics, the CPU time slots are set to
zero.  Other missing data are replaced by NaN@.  The list of possible
fields is:

@table @code
@item idrss
Unshared data size.

@item inblock
Number of block input operations.

@item isrss
Unshared stack size.

@item ixrss
Shared memory size.

@item majflt
Number of major page faults.

@item maxrss
Maximum data size.

@item minflt
Number of minor page faults.

@item msgrcv
Number of messages received.

@item msgsnd
Number of messages sent.

@item nivcsw
Number of involuntary context switches.

@item nsignals
Number of signals received.

@item nswap
Number of swaps.

@item nvcsw
Number of voluntary context switches.

@item oublock
Number of block output operations.

@item stime
A structure containing the system CPU time used.  The structure has the
elements @code{sec} (seconds) @code{usec} (microseconds).

@item utime
A structure containing the user CPU time used.  The structure has the
elements @code{sec} (seconds) @code{usec} (microseconds).
@end table
@end deftypefn
givens
@c givens src/DLD-FUNCTIONS/givens.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{g} =} givens (@var{x}, @var{y})
@deftypefnx {Loadable Function} {[@var{c}, @var{s}] =} givens (@var{x}, @var{y})
@tex
Return a $2\times 2$ orthogonal matrix
$$
 G = \left[\matrix{c & s\cr -s'& c\cr}\right]
$$
such that
$$
 G \left[\matrix{x\cr y}\right] = \left[\matrix{\ast\cr 0}\right]
$$
with $x$ and $y$ scalars.
@end tex
@ifnottex
Return a 2 by 2 orthogonal matrix
@code{@var{g} = [@var{c} @var{s}; -@var{s}' @var{c}]} such that
@code{@var{g} [@var{x}; @var{y}] = [*; 0]} with @var{x} and @var{y} scalars.
@end ifnottex

For example:

@example
@group
givens (1, 1)
     @result{}   0.70711   0.70711
         -0.70711   0.70711
@end group
@end example
@end deftypefn
hess
@c hess src/DLD-FUNCTIONS/hess.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{H} =} hess (@var{A})
@deftypefnx {Loadable Function} {[@var{P}, @var{H}] =} hess (@var{A})
@cindex Hessenberg decomposition
Compute the Hessenberg decomposition of the matrix @var{A}.

The Hessenberg decomposition is
@tex
$$
A = PHP^T
$$
where $P$ is a square unitary matrix ($P^TP = I$), and $H$
is upper Hessenberg ($H_{i,j} = 0, \forall i \ge j+1$).
@end tex
@ifnottex
@code{@var{P} * @var{H} * @var{P}' = @var{A}} where @var{P} is a square
unitary matrix (@code{@var{P}' * @var{P} = I}, using complex-conjugate
transposition) and @var{H} is upper Hessenberg
(@code{@var{H}(i, j) = 0 forall i >= j+1)}.
@end ifnottex

The Hessenberg decomposition is usually used as the first step in an
eigenvalue computation, but has other applications as well (see Golub,
Nash, and Van Loan, IEEE Transactions on Automatic Control, 1979).
@end deftypefn
hex2num
@c hex2num src/DLD-FUNCTIONS/hex2num.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{n} =} hex2num (@var{s})
Typecast the 16 character hexadecimal character string to an IEEE 754
double precision number.  If fewer than 16 characters are given the
strings are right padded with '0' characters.

Given a string matrix, @code{hex2num} treats each row as a separate
number.

@example
@group
hex2num (["4005bf0a8b145769";"4024000000000000"])
@result{} [2.7183; 10.000]
@end group
@end example
@seealso{num2hex, hex2dec, dec2hex}
@end deftypefn
num2hex
@c num2hex src/DLD-FUNCTIONS/hex2num.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{s} =} num2hex (@var{n})
Typecast a double precision number or vector to a 16 character hexadecimal
string of the IEEE 754 representation of the number.  For example:

@example
@group
num2hex ([-1, 1, e, Inf, NaN, NA]);
@result{} "bff0000000000000
    3ff0000000000000
    4005bf0a8b145769
    7ff0000000000000
    fff8000000000000
    7ff00000000007a2"
@end group
@end example
@seealso{hex2num, hex2dec, dec2hex}
@end deftypefn
inv
@c inv src/DLD-FUNCTIONS/inv.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{x} =} inv (@var{A})
@deftypefnx {Loadable Function} {[@var{x}, @var{rcond}] =} inv (@var{A})
Compute the inverse of the square matrix @var{A}.  Return an estimate
of the reciprocal condition number if requested, otherwise warn of an
ill-conditioned matrix if the reciprocal condition number is small.

In general it is best to avoid calculating the inverse of a matrix
directly.  For example, it is both faster and more accurate to solve
systems of equations (@var{A}*@math{x} = @math{b}) with
@code{@var{y} = @var{A} \ @math{b}}, rather than
@code{@var{y} = inv (@var{A}) * @math{b}}.

If called with a sparse matrix, then in general @var{x} will be a full
matrix requiring significantly more storage.  Avoid forming the inverse
of a sparse matrix if possible.
@seealso{ldivide, rdivide}
@end deftypefn
inverse
@c inverse src/DLD-FUNCTIONS/inv.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{x} =} inverse (@var{A})
@deftypefnx {Loadable Function} {[@var{x}, @var{rcond}] =} inverse (@var{A})
Compute the inverse of the square matrix @var{A}.

This is an alias for @code{inv}.
@seealso{inv}
@end deftypefn
kron
@c kron src/DLD-FUNCTIONS/kron.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} kron (@var{A}, @var{B})
@deftypefnx {Loadable Function} {} kron (@var{A1}, @var{A2}, @dots{})
Form the Kronecker product of two or more matrices, defined block by 
block as

@example
x = [a(i, j) b]
@end example

For example:

@example
@group
kron (1:4, ones (3, 1))
      @result{}  1  2  3  4
          1  2  3  4
          1  2  3  4
@end group
@end example

If there are more than two input arguments @var{A1}, @var{A2}, @dots{}, 
@var{An} the Kronecker product is computed as

@example
kron (kron (@var{A1}, @var{A2}), @dots{}, @var{An})
@end example

@noindent
Since the Kronecker product is associative, this is well-defined.
@end deftypefn
lookup
@c lookup src/DLD-FUNCTIONS/lookup.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{idx} =} lookup (@var{table}, @var{y})
@deftypefnx {Loadable Function} {@var{idx} =} lookup (@var{table}, @var{y}, @var{opt})
Lookup values in a sorted table.  Usually used as a prelude to
interpolation.

If table is increasing and @code{idx = lookup (table, y)}, then
@code{table(idx(i)) <= y(i) < table(idx(i+1))} for all @code{y(i)}
within the table.  If @code{y(i) < table(1)} then
@code{idx(i)} is 0. If @code{y(i) >= table(end)} or @code{isnan (y(i))} then
@code{idx(i)} is @code{n}.

If the table is decreasing, then the tests are reversed.
For non-strictly monotonic tables, empty intervals are always skipped.
The result is undefined if @var{table} is not monotonic, or if
@var{table} contains a NaN.

The complexity of the lookup is O(M*log(N)) where N is the size of
@var{table} and M is the size of @var{y}.  In the special case when @var{y}
is also sorted, the complexity is O(min(M*log(N),M+N)).

@var{table} and @var{y} can also be cell arrays of strings
(or @var{y} can be a single string).  In this case, string lookup
is performed using lexicographical comparison.

If @var{opts} is specified, it must be a string with letters indicating
additional options.

@table @code
@item m
@code{table(idx(i)) == val(i)} if @code{val(i)}
occurs in table; otherwise, @code{idx(i)} is zero.

@item b
@code{idx(i)} is a logical 1 or 0, indicating whether
@code{val(i)} is contained in table or not.

@item l
For numeric lookups
the leftmost subinterval shall be extended to infinity (i.e., all indices
at least 1)

@item r
For numeric lookups
the rightmost subinterval shall be extended to infinity (i.e., all indices
at most n-1).
@end table
@end deftypefn
lsode_options
@c lsode_options src/DLD-FUNCTIONS/lsode.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} lsode_options ()
@deftypefnx {Loadable Function} {val =} lsode_options (@var{opt})
@deftypefnx {Loadable Function} {} lsode_options (@var{opt}, @var{val})
Query or set options for the function @code{lsode}.
When called with no arguments, the names of all available options and
their current values are displayed.
Given one argument, return the value of the corresponding option.
When called with two arguments, @code{lsode_options} set the option
@var{opt} to value @var{val}.

Options include

@table @code
@item "absolute tolerance"
Absolute tolerance.  May be either vector or scalar.  If a vector, it
must match the dimension of the state vector.

@item "relative tolerance"
Relative tolerance parameter.  Unlike the absolute tolerance, this
parameter may only be a scalar.

The local error test applied at each integration step is

@example
@group
  abs (local error in x(i)) <= ...
      rtol * abs (y(i)) + atol(i)
@end group
@end example

@item "integration method"
A string specifying the method of integration to use to solve the ODE
system.  Valid values are

@table @asis
@item "adams"
@itemx "non-stiff"
No Jacobian used (even if it is available).

@item "bdf"
@itemx "stiff"
Use stiff backward differentiation formula (BDF) method.  If a
function to compute the Jacobian is not supplied, @code{lsode} will
compute a finite difference approximation of the Jacobian matrix.
@end table

@item "initial step size"
The step size to be attempted on the first step (default is determined
automatically).

@item "maximum order"
Restrict the maximum order of the solution method.  If using the Adams
method, this option must be between 1 and 12.  Otherwise, it must be
between 1 and 5, inclusive.

@item "maximum step size"
Setting the maximum stepsize will avoid passing over very large
regions  (default is not specified).

@item "minimum step size"
The minimum absolute step size allowed (default is 0).

@item "step limit"
Maximum number of steps allowed (default is 100000).
@end table
@end deftypefn
lsode
@c lsode src/DLD-FUNCTIONS/lsode.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{x}, @var{istate}, @var{msg}] =} lsode (@var{fcn}, @var{x_0}, @var{t})
@deftypefnx {Loadable Function} {[@var{x}, @var{istate}, @var{msg}] =} lsode (@var{fcn}, @var{x_0}, @var{t}, @var{t_crit})
Solve the set of differential equations
@tex
$$ {dx \over dt} = f (x, t) $$
with
$$ x(t_0) = x_0 $$
@end tex
@ifnottex

@example
@group
dx
-- = f(x, t)
dt
@end group
@end example

@noindent
with

@example
x(t_0) = x_0
@end example

@end ifnottex
The solution is returned in the matrix @var{x}, with each row
corresponding to an element of the vector @var{t}.  The first element
of @var{t} should be @math{t_0} and should correspond to the initial
state of the system @var{x_0}, so that the first row of the output
is @var{x_0}.

The first argument, @var{fcn}, is a string, inline, or function handle
that names the function @math{f} to call to compute the vector of right
hand sides for the set of equations.  The function must have the form

@example
@var{xdot} = f (@var{x}, @var{t})
@end example

@noindent
in which @var{xdot} and @var{x} are vectors and @var{t} is a scalar.

If @var{fcn} is a two-element string array or a two-element cell array
of strings, inline functions, or function handles, the first element names
the function @math{f} described above, and the second element names a
function to compute the Jacobian of @math{f}.  The Jacobian function
must have the form

@example
@var{jac} = j (@var{x}, @var{t})
@end example

@noindent
in which @var{jac} is the matrix of partial derivatives
@tex
$$ J = {\partial f_i \over \partial x_j} = \left[\matrix{
{\partial f_1 \over \partial x_1}
  & {\partial f_1 \over \partial x_2}
  & \cdots
  & {\partial f_1 \over \partial x_N} \cr
{\partial f_2 \over \partial x_1}
  & {\partial f_2 \over \partial x_2}
  & \cdots
  & {\partial f_2 \over \partial x_N} \cr
 \vdots & \vdots & \ddots & \vdots \cr
{\partial f_3 \over \partial x_1}
  & {\partial f_3 \over \partial x_2}
  & \cdots
  & {\partial f_3 \over \partial x_N} \cr}\right]$$
@end tex
@ifnottex

@example
@group
             | df_1  df_1       df_1 |
             | ----  ----  ...  ---- |
             | dx_1  dx_2       dx_N |
             |                       |
             | df_2  df_2       df_2 |
             | ----  ----  ...  ---- |
      df_i   | dx_1  dx_2       dx_N |
jac = ---- = |                       |
      dx_j   |  .    .     .    .    |
             |  .    .      .   .    |
             |  .    .       .  .    |
             |                       |
             | df_N  df_N       df_N |
             | ----  ----  ...  ---- |
             | dx_1  dx_2       dx_N |
@end group
@end example

@end ifnottex

The second and third arguments specify the initial state of the system,
@math{x_0}, and the initial value of the independent variable @math{t_0}.

The fourth argument is optional, and may be used to specify a set of
times that the ODE solver should not integrate past.  It is useful for
avoiding difficulties with singularities and points where there is a
discontinuity in the derivative.

After a successful computation, the value of @var{istate} will be 2
(consistent with the Fortran version of @sc{lsode}).

If the computation is not successful, @var{istate} will be something
other than 2 and @var{msg} will contain additional information.

You can use the function @code{lsode_options} to set optional
parameters for @code{lsode}.
@seealso{daspk, dassl, dasrt}
@end deftypefn
lu
@c lu src/DLD-FUNCTIONS/lu.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{L}, @var{U}] =} lu (@var{A})
@deftypefnx {Loadable Function} {[@var{L}, @var{U}, @var{P}] =} lu (@var{A})
@deftypefnx {Loadable Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} lu (@var{S})
@deftypefnx {Loadable Function} {[@var{L}, @var{U}, @var{P}, @var{Q}, @var{R}] =} lu (@var{S})
@deftypefnx {Loadable Function} {[@dots{}] =} lu (@var{S}, @var{thres})
@deftypefnx {Loadable Function} {@var{y} =} lu (@dots{})
@deftypefnx {Loadable Function} {[@dots{}] =} lu (@dots{}, 'vector')
@cindex LU decomposition
Compute the LU@tie{}decomposition of @var{A}.  If @var{A} is full
subroutines from
@sc{lapack} are used and if @var{A} is sparse then @sc{umfpack} is used.  The
result is returned in a permuted form, according to the optional return
value @var{P}.  For example, given the matrix @code{a = [1, 2; 3, 4]},

@example
[l, u, p] = lu (@var{a})
@end example

@noindent
returns

@example
@group
l =

  1.00000  0.00000
  0.33333  1.00000

u =

  3.00000  4.00000
  0.00000  0.66667

p =

  0  1
  1  0
@end group
@end example

The matrix is not required to be square.

When called with two or three output arguments and a spare input matrix,
@code{lu} does not attempt to perform sparsity preserving column
permutations.  Called with a fourth output argument, the sparsity
preserving column transformation @var{Q} is returned, such that
@code{@var{P} * @var{A} * @var{Q} = @var{L} * @var{U}}.

Called with a fifth output argument and a sparse input matrix,
@code{lu} attempts to use a scaling factor @var{R} on the input matrix
such that
@code{@var{P} * (@var{R} \ @var{A}) * @var{Q} = @var{L} * @var{U}}.
This typically leads to a sparser and more stable factorization.

An additional input argument @var{thres}, that defines the pivoting
threshold can be given.  @var{thres} can be a scalar, in which case
it defines the @sc{umfpack} pivoting tolerance for both symmetric and
unsymmetric cases.  If @var{thres} is a 2-element vector, then the first
element defines the pivoting tolerance for the unsymmetric @sc{umfpack}
pivoting strategy and the second for the symmetric strategy.  By default,
the values defined by @code{spparms} are used ([0.1, 0.001]).

Given the string argument 'vector', @code{lu} returns the values of @var{P}
and @var{Q} as vector values, such that for full matrix, @code{@var{A}
(@var{P},:) = @var{L} * @var{U}}, and @code{@var{R}(@var{P},:) * @var{A}
(:, @var{Q}) = @var{L} * @var{U}}.

With two output arguments, returns the permuted forms of the upper and
lower triangular matrices, such that @code{@var{A} = @var{L} * @var{U}}.
With one output argument @var{y}, then the matrix returned by the @sc{lapack}
routines is returned.  If the input matrix is sparse then the matrix @var{L}
is embedded into @var{U} to give a return value similar to the full case.
For both full and sparse matrices, @code{lu} loses the permutation
information.
@end deftypefn
luupdate
@c luupdate src/DLD-FUNCTIONS/lu.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{L}, @var{U}] =} luupdate (@var{L}, @var{U}, @var{x}, @var{y})
@deftypefnx {Loadable Function} {[@var{L}, @var{U}, @var{P}] =} luupdate (@var{L}, @var{U}, @var{P}, @var{x}, @var{y})
Given an LU@tie{}factorization of a real or complex matrix
@w{@var{A} = @var{L}*@var{U}}, @var{L}@tie{}lower unit trapezoidal and
@var{U}@tie{}upper trapezoidal, return the LU@tie{}factorization
of @w{@var{A} + @var{x}*@var{y}.'}, where @var{x} and @var{y} are
column vectors (rank-1 update) or matrices with equal number of columns
(rank-k update).
Optionally, row-pivoted updating can be used by supplying
a row permutation (pivoting) matrix @var{P};
in that case, an updated permutation matrix is returned.
Note that if @var{L}, @var{U}, @var{P} is a pivoted LU@tie{}factorization
as obtained by @code{lu}:

@example
  [@var{L}, @var{U}, @var{P}] = lu (@var{A});
@end example

@noindent
then a factorization of @xcode{@var{A}+@var{x}*@var{y}.'} can be obtained
either as

@example
  [@var{L1}, @var{U1}] = lu (@var{L}, @var{U}, @var{P}*@var{x}, @var{y})
@end example

@noindent
or

@example
  [@var{L1}, @var{U1}, @var{P1}] = lu (@var{L}, @var{U}, @var{P}, @var{x}, @var{y})
@end example

The first form uses the unpivoted algorithm, which is faster, but less
stable.  The second form uses a slower pivoted algorithm, which is more
stable.

The matrix case is done as a sequence of rank-1 updates;
thus, for large enough k, it will be both faster and more accurate to
recompute the factorization from scratch.
@seealso{lu, qrupdate, cholupdate}
@end deftypefn
luinc
@c luinc src/DLD-FUNCTIONS/luinc.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, '0')
@deftypefnx {Loadable Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, @var{droptol})
@deftypefnx {Loadable Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, @var{opts})
@cindex LU decomposition
Produce the incomplete LU@tie{}factorization of the sparse matrix @var{A}.
Two types of incomplete factorization are possible, and the type
is determined by the second argument to @code{luinc}.

Called with a second argument of '0', the zero-level incomplete
LU@tie{}factorization is produced.  This creates a factorization of @var{A}
where the position of the non-zero arguments correspond to the same
positions as in the matrix @var{A}.

Alternatively, the fill-in of the incomplete LU@tie{}factorization can
be controlled through the variable @var{droptol} or the structure
@var{opts}.  The @sc{umfpack} multifrontal factorization code by Tim A.
Davis is used for the incomplete LU@tie{}factorization, (availability
@url{http://www.cise.ufl.edu/research/sparse/umfpack/})

@var{droptol} determines the values below which the values in the
LU@tie{} factorization are dropped and replaced by zero.  It must be a
positive scalar, and any values in the factorization whose absolute value
are less than this value are dropped, expect if leaving them increase the
sparsity of the matrix.  Setting @var{droptol} to zero results in a complete
LU@tie{}factorization which is the default.

@var{opts} is a structure containing one or more of the fields

@table @code
@item droptol
The drop tolerance as above.  If @var{opts} only contains @code{droptol}
then this is equivalent to using the variable @var{droptol}.

@item milu
A logical variable flagging whether to use the modified incomplete
LU@tie{} factorization.  In the case that @code{milu} is true, the dropped
values are subtracted from the diagonal of the matrix @var{U} of the
factorization.  The default is @code{false}.

@item udiag
A logical variable that flags whether zero elements on the diagonal of
@var{U} should be replaced with @var{droptol} to attempt to avoid singular
factors.  The default is @code{false}.

@item thresh
Defines the pivot threshold in the interval [0,1].  Values outside that
range are ignored.
@end table

All other fields in @var{opts} are ignored.  The outputs from @code{luinc}
are the same as for @code{lu}.

Given the string argument 'vector', @code{luinc} returns the values of
@var{p} @var{q} as vector values.
@seealso{sparse, lu}
@end deftypefn
matrix_type
@c matrix_type src/DLD-FUNCTIONS/matrix_type.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{type} =} matrix_type (@var{A})
@deftypefnx {Loadable Function} {@var{type} =} matrix_type (@var{A}, 'nocompute')
@deftypefnx {Loadable Function} {@var{A} =} matrix_type (@var{A}, @var{type})
@deftypefnx {Loadable Function} {@var{A} =} matrix_type (@var{A}, 'upper', @var{perm})
@deftypefnx {Loadable Function} {@var{A} =} matrix_type (@var{A}, 'lower', @var{perm})
@deftypefnx {Loadable Function} {@var{A} =} matrix_type (@var{A}, 'banded', @var{nl}, @var{nu})
Identify the matrix type or mark a matrix as a particular type.  This allows
more rapid solutions of linear equations involving @var{A} to be performed.
Called with a single argument, @code{matrix_type} returns the type of the
matrix and caches it for future use.  Called with more than one argument,
@code{matrix_type} allows the type of the matrix to be defined.

If the option 'nocompute' is given, the function will not attempt to guess
the type if it is still unknown.  This is useful for debugging purposes.

The possible matrix types depend on whether the matrix is full or sparse, and
can be one of the following

@table @asis
@item 'unknown'
Remove any previously cached matrix type, and mark type as unknown.

@item 'full'
Mark the matrix as full.

@item 'positive definite'
Probable full positive definite matrix.

@item 'diagonal'
Diagonal matrix.  (Sparse matrices only)

@item 'permuted diagonal'
Permuted Diagonal matrix.  The permutation does not need to be specifically
indicated, as the structure of the matrix explicitly gives this.  (Sparse
matrices only)

@item 'upper'
Upper triangular.  If the optional third argument @var{perm} is given, the
matrix is assumed to be a permuted upper triangular with the permutations
defined by the vector @var{perm}.

@item 'lower'
Lower triangular.  If the optional third argument @var{perm} is given, the
matrix is assumed to be a permuted lower triangular with the permutations
defined by the vector @var{perm}.

@item 'banded'
@itemx 'banded positive definite'
Banded matrix with the band size of @var{nl} below the diagonal and @var{nu}
above it.  If @var{nl} and @var{nu} are 1, then the matrix is tridiagonal and
treated with specialized code.  In addition the matrix can be marked as
probably a positive definite.  (Sparse matrices only)

@item 'singular'
The matrix is assumed to be singular and will be treated with a minimum norm
solution.

@end table

Note that the matrix type will be discovered automatically on the first
attempt to solve a linear equation involving @var{A}.  Therefore
@code{matrix_type} is only useful to give Octave hints of the matrix type.
Incorrectly defining the matrix type will result in incorrect results from
solutions of linear equations; it is entirely @strong{the responsibility of
the user} to correctly identify the matrix type.

Also, the test for positive definiteness is a low-cost test for a Hermitian
matrix with a real positive diagonal.  This does not guarantee that the
matrix is positive definite, but only that it is a probable candidate.  When
such a matrix is factorized, a Cholesky@tie{}factorization is first
attempted, and if that fails the matrix is then treated with an
LU@tie{}factorization.  Once the matrix has been factorized,
@code{matrix_type} will return the correct classification of the matrix.
@end deftypefn
min
@c min src/DLD-FUNCTIONS/max.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} min (@var{x})
@deftypefnx {Loadable Function} {} min (@var{x}, @var{y})
@deftypefnx {Loadable Function} {} min (@var{x}, [], @var{dim})
@deftypefnx {Loadable Function} {} min (@var{x}, @var{y}, @var{dim})
@deftypefnx {Loadable Function} {[@var{w}, @var{iw}] =} min (@var{x})
For a vector argument, return the minimum value.  For a matrix
argument, return the minimum value from each column, as a row
vector, or over the dimension @var{dim} if defined, in which case @var{y} 
should be set to the empty matrix (it's ignored otherwise).  For two matrices
(or a matrix and scalar), return the pair-wise minimum.
Thus,

@example
min (min (@var{x}))
@end example

@noindent
returns the smallest element of @var{x}, and

@example
@group
min (2:5, pi)
    @result{}  2.0000  3.0000  3.1416  3.1416
@end group
@end example

@noindent
compares each element of the range @code{2:5} with @code{pi}, and
returns a row vector of the minimum values.

For complex arguments, the magnitude of the elements are used for
comparison.

If called with one input and two output arguments,
@code{min} also returns the first index of the
minimum value(s).  Thus,

@example
@group
[x, ix] = min ([1, 3, 0, 2, 0])
    @result{}  x = 0
        ix = 3
@end group
@end example
@seealso{max, cummin, cummax}
@end deftypefn
max
@c max src/DLD-FUNCTIONS/max.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} max (@var{x})
@deftypefnx {Loadable Function} {} max (@var{x}, @var{y})
@deftypefnx {Loadable Function} {} max (@var{x}, [], @var{dim})
@deftypefnx {Loadable Function} {} max (@var{x}, @var{y}, @var{dim})
@deftypefnx {Loadable Function} {[@var{w}, @var{iw}] =} max (@var{x})
For a vector argument, return the maximum value.  For a matrix
argument, return the maximum value from each column, as a row
vector, or over the dimension @var{dim} if defined, in which case @var{y} 
should be set to the empty matrix (it's ignored otherwise).  For two matrices
(or a matrix and scalar), return the pair-wise maximum.
Thus,

@example
max (max (@var{x}))
@end example

@noindent
returns the largest element of the matrix @var{x}, and

@example
@group
max (2:5, pi)
    @result{}  3.1416  3.1416  4.0000  5.0000
@end group
@end example

@noindent
compares each element of the range @code{2:5} with @code{pi}, and
returns a row vector of the maximum values.

For complex arguments, the magnitude of the elements are used for
comparison.

If called with one input and two output arguments,
@code{max} also returns the first index of the
maximum value(s).  Thus,

@example
@group
[x, ix] = max ([1, 3, 5, 2, 5])
    @result{}  x = 5
        ix = 3
@end group
@end example
@seealso{min, cummax, cummin}
@end deftypefn
cummin
@c cummin src/DLD-FUNCTIONS/max.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} cummin (@var{x})
@deftypefnx {Loadable Function} {} cummin (@var{x}, @var{dim})
@deftypefnx {Loadable Function} {[@var{w}, @var{iw}] =} cummin (@var{x})
Return the cumulative minimum values along dimension @var{dim}.  If @var{dim}
is unspecified it defaults to column-wise operation.  For example:

@example
@group
cummin ([5 4 6 2 3 1])
    @result{}  5  4  4  2  2  1
@end group
@end example


The call

@example
  [w, iw] = cummin (x)
@end example

@noindent
with @code{x} a vector, is equivalent to the following code:

@example
@group
w = iw = zeros (size (x));
for i = 1:length (x)
  [w(i), iw(i)] = max (x(1:i));
endfor
@end group
@end example

@noindent
but computed in a much faster manner.
@seealso{cummax, min, max}
@end deftypefn
cummax
@c cummax src/DLD-FUNCTIONS/max.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} cummax (@var{x})
@deftypefnx {Loadable Function} {} cummax (@var{x}, @var{dim})
@deftypefnx {Loadable Function} {[@var{w}, @var{iw}] =} cummax (@var{x})
Return the cumulative maximum values along dimension @var{dim}.  If @var{dim}
is unspecified it defaults to column-wise operation.  For example:

@example
@group
cummax ([1 3 2 6 4 5])
    @result{}  1  3  3  6  6  6
@end group
@end example

The call

@example
[w, iw] = cummax (x, dim)
@end example

@noindent
with @code{x} a vector, is equivalent to the following code:

@example
@group
w = iw = zeros (size (x));
for i = 1:length (x)
  [w(i), iw(i)] = max (x(1:i));
endfor
@end group
@end example

@noindent
but computed in a much faster manner.
@seealso{cummin, max, min}
@end deftypefn
md5sum
@c md5sum src/DLD-FUNCTIONS/md5sum.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} md5sum (@var{file})
@deftypefnx {Loadable Function} {} md5sum (@var{str}, @var{opt})
Calculate the MD5 sum of the file @var{file}.  If the second parameter
@var{opt} exists and is true, then calculate the MD5 sum of the
string @var{str}.
@end deftypefn
mgorth
@c mgorth src/DLD-FUNCTIONS/mgorth.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{y}, @var{h}] =} mgorth (@var{x}, @var{v})
Orthogonalize a given column vector @var{x} with respect to a given
orthonormal basis @var{v} using a modified Gram-Schmidt orthogonalization.  
On exit, @var{y} is a unit vector such that:

@example
@group
  norm (@var{y}) = 1
  @var{v}' * @var{y} = 0
  @var{x} = @var{h}*[@var{v}, @var{y}]
@end group
@end example

@end deftypefn
nproc
@c nproc src/DLD-FUNCTIONS/nproc.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} nproc ()
@deftypefnx {Loadable Function} {} nproc (@var{query})
Return the current number of available processors.

If called with the optional argument @var{query}, modify how processors
are counted as follows:
@table @code
@item all
total number of processors.

@item current
processors available to the current process.

@item overridable
likewise, but overridable through the @w{@env{OMP_NUM_THREADS}} environment
variable.
@end table
@end deftypefn
pinv
@c pinv src/DLD-FUNCTIONS/pinv.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} pinv (@var{x})
@deftypefnx {Loadable Function} {} pinv (@var{x}, @var{tol})
Return the pseudoinverse of @var{x}.  Singular values less than
@var{tol} are ignored.

If the second argument is omitted, it is taken to be

@example
tol = max (size (@var{x})) * sigma_max (@var{x}) * eps,
@end example

@noindent
where @code{sigma_max (@var{x})} is the maximal singular value of @var{x}.
@end deftypefn
qr
@c qr src/DLD-FUNCTIONS/qr.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{Q}, @var{R}, @var{P}] =} qr (@var{A})
@deftypefnx {Loadable Function} {[@var{Q}, @var{R}, @var{P}] =} qr (@var{A}, '0')
@deftypefnx {Loadable Function} {[@var{C}, @var{R}] =} qr (@var{A}, @var{B})
@deftypefnx {Loadable Function} {[@var{C}, @var{R}] =} qr (@var{A}, @var{B}, '0')
@cindex QR factorization
Compute the QR@tie{}factorization of @var{A}, using standard @sc{lapack}
subroutines.  For example, given the matrix @code{@var{A} = [1, 2; 3, 4]},

@example
[@var{Q}, @var{R}] = qr (@var{A})
@end example

@noindent
returns

@example
@group
@var{Q} =

  -0.31623  -0.94868
  -0.94868   0.31623

@var{R} =

  -3.16228  -4.42719
   0.00000  -0.63246
@end group
@end example

The @code{qr} factorization has applications in the solution of least
squares problems
@tex
$$
\min_x \left\Vert A x - b \right\Vert_2
$$
@end tex
@ifnottex

@example
@code{min norm(A x - b)}
@end example

@end ifnottex
for overdetermined systems of equations (i.e.,
@tex
$A$
@end tex
@ifnottex
@var{A}
@end ifnottex
 is a tall, thin matrix).  The QR@tie{}factorization is
@tex
$QR = A$ where $Q$ is an orthogonal matrix and $R$ is upper triangular.
@end tex
@ifnottex
@code{@var{Q} * @var{Q} = @var{A}} where @var{Q} is an orthogonal matrix and
@var{R} is upper triangular.
@end ifnottex

If given a second argument of '0', @code{qr} returns an economy-sized
QR@tie{}factorization, omitting zero rows of @var{R} and the corresponding
columns of @var{Q}.

If the matrix @var{A} is full, the permuted QR@tie{}factorization
@code{[@var{Q}, @var{R}, @var{P}] = qr (@var{A})} forms the
QR@tie{}factorization such that the diagonal entries of @var{R} are
decreasing in magnitude order.  For example, given the matrix @code{a = [1,
2; 3, 4]},

@example
[@var{Q}, @var{R}, @var{P}] = qr (@var{A})
@end example

@noindent
returns

@example
@group
@var{Q} =

  -0.44721  -0.89443
  -0.89443   0.44721

@var{R} =

  -4.47214  -3.13050
   0.00000   0.44721

@var{P} =

   0  1
   1  0
@end group
@end example

The permuted @code{qr} factorization @code{[@var{Q}, @var{R}, @var{P}] = qr
(@var{A})} factorization allows the construction of an orthogonal basis of
@code{span (A)}.

If the matrix @var{A} is sparse, then compute the sparse
QR@tie{}factorization of @var{A}, using @sc{CSparse}.  As the matrix @var{Q}
is in general a full matrix, this function returns the @var{Q}-less
factorization @var{R} of @var{A}, such that @code{@var{R} = chol (@var{A}' *
@var{A})}.

If the final argument is the scalar @code{0} and the number of rows is
larger than the number of columns, then an economy factorization is
returned.  That is @var{R} will have only @code{size (@var{A},1)} rows.

If an additional matrix @var{B} is supplied, then @code{qr} returns
@var{C}, where @code{@var{C} = @var{Q}' * @var{B}}.  This allows the
least squares approximation of @code{@var{A} \ @var{B}} to be calculated
as

@example
@group
[@var{C}, @var{R}] = qr (@var{A}, @var{B})
x = @var{R} \ @var{C}
@end group
@end example
@end deftypefn
qrupdate
@c qrupdate src/DLD-FUNCTIONS/qr.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{Q1}, @var{R1}] =} qrupdate (@var{Q}, @var{R}, @var{u}, @var{v})
Given a QR@tie{}factorization of a real or complex matrix
@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and
@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization
of @w{@var{A} + @var{u}*@var{v}'}, where @var{u} and @var{v} are
column vectors (rank-1 update) or matrices with equal number of columns
(rank-k update).  Notice that the latter case is done as a sequence of rank-1
updates; thus, for k large enough, it will be both faster and more accurate
to recompute the factorization from scratch.

The QR@tie{}factorization supplied may be either full
(Q is square) or economized (R is square).

@seealso{qr, qrinsert, qrdelete}
@end deftypefn
qrinsert
@c qrinsert src/DLD-FUNCTIONS/qr.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{Q1}, @var{R1}] =} qrinsert (@var{Q}, @var{R}, @var{j}, @var{x}, @var{orient})
Given a QR@tie{}factorization of a real or complex matrix
@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and
@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization of
@w{[A(:,1:j-1) x A(:,j:n)]}, where @var{u} is a column vector to be
inserted into @var{A} (if @var{orient} is @code{"col"}), or the
QR@tie{}factorization of @w{[A(1:j-1,:);x;A(:,j:n)]}, where @var{x}
is a row vector to be inserted into @var{A} (if @var{orient} is
@code{"row"}).

The default value of @var{orient} is @code{"col"}.
If @var{orient} is @code{"col"},
@var{u} may be a matrix and @var{j} an index vector
resulting in the QR@tie{}factorization of a matrix @var{B} such that
@w{B(:,@var{j})} gives @var{u} and @w{B(:,@var{j}) = []} gives @var{A}.
Notice that the latter case is done as a sequence of k insertions;
thus, for k large enough, it will be both faster and more accurate to
recompute the factorization from scratch.

If @var{orient} is @code{"col"},
the QR@tie{}factorization supplied may be either full
(Q is square) or economized (R is square).

If @var{orient} is @code{"row"}, full factorization is needed.
@seealso{qr, qrupdate, qrdelete}
@end deftypefn
qrdelete
@c qrdelete src/DLD-FUNCTIONS/qr.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{Q1}, @var{R1}] =} qrdelete (@var{Q}, @var{R}, @var{j}, @var{orient})
Given a QR@tie{}factorization of a real or complex matrix
@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and
@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization of
@w{[A(:,1:j-1) A(:,j+1:n)]}, i.e., @var{A} with one column deleted
(if @var{orient} is "col"), or the QR@tie{}factorization of
@w{[A(1:j-1,:);A(j+1:n,:)]}, i.e., @var{A} with one row deleted (if
   @var{orient} is "row").

The default value of @var{orient} is "col".

If @var{orient} is @code{"col"},
@var{j} may be an index vector
resulting in the QR@tie{}factorization of a matrix @var{B} such that
@w{A(:,@var{j}) = []} gives @var{B}.
Notice that the latter case is done as a sequence of k deletions;
thus, for k large enough, it will be both faster and more accurate to
recompute the factorization from scratch.

If @var{orient} is @code{"col"},
the QR@tie{}factorization supplied may be either full
(Q is square) or economized (R is square).

If @var{orient} is @code{"row"}, full factorization is needed.
@seealso{qr, qrinsert, qrupdate}
@end deftypefn
qrshift
@c qrshift src/DLD-FUNCTIONS/qr.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{Q1}, @var{R1}] =} qrshift (@var{Q}, @var{R}, @var{i}, @var{j})
Given a QR@tie{}factorization of a real or complex matrix
@w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and
@var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization
of @w{@var{A}(:,p)}, where @w{p} is the permutation @*
@code{p = [1:i-1, shift(i:j, 1), j+1:n]} if @w{@var{i} < @var{j}} @*
 or @*
@code{p = [1:j-1, shift(j:i,-1), i+1:n]} if @w{@var{j} < @var{i}}.  @*

@seealso{qr, qrinsert, qrdelete}
@end deftypefn
quad_options
@c quad_options src/DLD-FUNCTIONS/quad.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} quad_options ()
@deftypefnx {Loadable Function} {val =} quad_options (@var{opt})
@deftypefnx {Loadable Function} {} quad_options (@var{opt}, @var{val})
Query or set options for the function @code{quad}.
When called with no arguments, the names of all available options and
their current values are displayed.
Given one argument, return the value of the corresponding option.
When called with two arguments, @code{quad_options} set the option
@var{opt} to value @var{val}.

Options include

@table @code
@item "absolute tolerance"
Absolute tolerance; may be zero for pure relative error test.

@item "relative tolerance"
Non-negative relative tolerance.  If the absolute tolerance is zero,
the relative tolerance must be greater than or equal to
@w{@code{max (50*eps, 0.5e-28)}}.

@item "single precision absolute tolerance"
Absolute tolerance for single precision; may be zero for pure relative
error test.

@item "single precision relative tolerance"
Non-negative relative tolerance for single precision.  If the absolute
tolerance is zero, the relative tolerance must be greater than or equal to
@w{@code{max (50*eps, 0.5e-28)}}.
@end table
@end deftypefn
quad
@c quad src/DLD-FUNCTIONS/quad.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{q} =} quad (@var{f}, @var{a}, @var{b})
@deftypefnx {Loadable Function} {@var{q} =} quad (@var{f}, @var{a}, @var{b}, @var{tol})
@deftypefnx {Loadable Function} {@var{q} =} quad (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing})
@deftypefnx {Loadable Function} {[@var{q}, @var{ier}, @var{nfun}, @var{err}] =} quad (@dots{})
Numerically evaluate the integral of @var{f} from @var{a} to @var{b} using
Fortran routines from @w{@sc{quadpack}}.  @var{f} is a function handle,
inline function, or a string containing the name of the function to
evaluate.  The function must have the form @code{y = f (x)} where @var{y} and
@var{x} are scalars.

@var{a} and @var{b} are the lower and upper limits of integration.  Either
or both may be infinite.

The optional argument @var{tol} is a vector that specifies the desired
accuracy of the result.  The first element of the vector is the desired
absolute tolerance, and the second element is the desired relative
tolerance.  To choose a relative test only, set the absolute
tolerance to zero.  To choose an absolute test only, set the relative
tolerance to zero.  Both tolerances default to @code{sqrt(eps)} or
approximately @math{1.5e^{-8}}.

The optional argument @var{sing} is a vector of values at which the
integrand is known to be singular.

The result of the integration is returned in @var{q}.  @var{ier}
contains an integer error code (0 indicates a successful integration).
@var{nfun} indicates the number of function evaluations that were
made, and @var{err} contains an estimate of the error in the
solution.

The function @code{quad_options} can set other optional
parameters for @code{quad}.

Note: because @code{quad} is written in Fortran it cannot be called
recursively.  This prevents its use in integrating over more than one
variable by routines @code{dblquad} and @code{triplequad}.
@seealso{quad_options, quadv, quadl, quadgk, quadcc, trapz, dblquad, triplequad}
@end deftypefn
quadcc
@c quadcc src/DLD-FUNCTIONS/quadcc.cc
-*- texinfo -*-
@deftypefn  {Function File} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b})
@deftypefnx {Function File} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b}, @var{tol})
@deftypefnx {Function File} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing})
@deftypefnx {Function File} {[@var{q}, @var{err}, @var{nr_points}] =} quadcc (@dots{})
Numerically evaluate the integral of @var{f} from @var{a} to @var{b}
using the doubly-adaptive Clenshaw-Curtis quadrature described by P. Gonnet
in @cite{Increasing the Reliability of Adaptive Quadrature Using Explicit
Interpolants}.
@var{f} is a function handle, inline function, or string
containing the name of the function to evaluate.
The function @var{f} must be vectorized and must return a vector of output
values if given a vector of input values.  For example,

@example
   f = @@(x) x .* sin (1./x) .* sqrt (abs (1 - x));
@end example

@noindent
which uses the element-by-element `dot' form for all operators.

@var{a} and @var{b} are the lower and upper limits of integration.  Either
or both limits may be infinite.  @code{quadcc} handles an inifinite limit
by substituting the variable of integration with @code{x=tan(pi/2*u)}.

The optional argument @var{tol} defines the relative tolerance used to stop
the integration procedure.  The default value is @math{1e^{-6}}.

The optional argument @var{sing} contains a list of points where the
integrand has known singularities, or discontinuities
in any of its derivatives, inside the integration interval.
For the example above, which has a discontinuity at x=1, the call to
@code{quadcc} would be as follows

@example
   int = quadcc (f, a, b, 1.0e-6, [ 1 ]);
@end example

The result of the integration is returned in @var{q}.
@var{err} is an estimate of the absolute integration error and
@var{nr_points} is the number of points at which the integrand was evaluated.
If the adaptive integration did not converge, the value of
@var{err} will be larger than the requested tolerance.  Therefore, it is
recommended to verify this value for difficult integrands.

@code{quadcc} is capable of dealing with non-numeric
values of the integrand such as @code{NaN} or @code{Inf}.
If the integral diverges, and @code{quadcc} detects this,
then a warning is issued and @code{Inf} or @code{-Inf} is returned.

Note: @code{quadcc} is a general purpose quadrature algorithm
and, as such, may be less efficient for a smooth or otherwise
well-behaved integrand than other methods such as @code{quadgk}.

The algorithm uses Clenshaw-Curtis quadrature rules of increasing
degree in each interval and bisects the interval if either the
function does not appear to be smooth or a rule of maximum
degree has been reached.  The error estimate is computed from the
L2-norm of the difference between two successive interpolations
of the integrand over the nodes of the respective quadrature rules.

Reference: P. Gonnet, @cite{Increasing the Reliability of Adaptive
Quadrature Using Explicit Interpolants}, ACM Transactions on
Mathematical Software, Vol. 37, Issue 3, Article No. 3, 2010.
@seealso{quad, quadv, quadl, quadgk, trapz, dblquad, triplequad}
@end deftypefn
qz
@c qz src/DLD-FUNCTIONS/qz.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{lambda} =} qz (@var{A}, @var{B})
@deftypefnx {Loadable Function} {@var{lambda} =} qz (@var{A}, @var{B}, @var{opt})
QZ@tie{}decomposition of the generalized eigenvalue problem
(@math{A x = s B x}).  There are three ways to call this function:
@enumerate
@item @code{@var{lambda} = qz (@var{A}, @var{B})}

Computes the generalized eigenvalues
@tex
$\lambda$
@end tex
@ifnottex
@var{lambda}
@end ifnottex
of @math{(A - s B)}.

@item @code{[AA, BB, Q, Z, V, W, @var{lambda}] = qz (@var{A}, @var{B})}

Computes QZ@tie{}decomposition, generalized eigenvectors, and
generalized eigenvalues of @math{(A - s B)}
@tex
$$ AV = BV{ \rm diag }(\lambda) $$
$$ W^T A = { \rm diag }(\lambda)W^T B $$
$$ AA = Q^T AZ, BB = Q^T BZ $$
@end tex
@ifnottex

@example
@group

    A * V = B * V * diag (@var{lambda})
    W' * A = diag (@var{lambda}) * W' * B
    AA = Q * A * Z, BB = Q * B * Z

@end group
@end example

@end ifnottex
with @var{Q} and @var{Z} orthogonal (unitary)= @var{I}

@item @code{[AA,BB,Z@{, @var{lambda}@}] = qz (@var{A}, @var{B}, @var{opt})}

As in form [2], but allows ordering of generalized eigenpairs
for (e.g.) solution of discrete time algebraic Riccati equations.
Form 3 is not available for complex matrices, and does not compute
the generalized eigenvectors @var{V}, @var{W}, nor the orthogonal matrix
@var{Q}.

@table @var
@item opt
for ordering eigenvalues of the GEP pencil.  The leading block
of the revised pencil contains all eigenvalues that satisfy:
@table @asis
@item "N"
= unordered (default)

@item "S"
= small: leading block has all |lambda| @leq{} 1

@item "B"
= big: leading block has all |lambda| @geq{} 1

@item "-"
= negative real part: leading block has all eigenvalues
in the open left half-plane

@item "+"
= non-negative real part: leading block has all eigenvalues
in the closed right half-plane
@end table
@end table
@end enumerate

Note: @code{qz} performs permutation balancing, but not scaling
(@pxref{doc-balance}).  The order of output arguments was selected for
compatibility with @sc{matlab}.
@seealso{balance, eig, schur}
@end deftypefn
rand
@c rand src/DLD-FUNCTIONS/rand.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} rand (@var{n})
@deftypefnx {Loadable Function} {} rand (@var{n}, @var{m}, @dots{})
@deftypefnx {Loadable Function} {} rand ([@var{n} @var{m} @dots{}])
@deftypefnx {Loadable Function} {@var{v} =} rand ("state")
@deftypefnx {Loadable Function} {} rand ("state", @var{v})
@deftypefnx {Loadable Function} {} rand ("state", "reset")
@deftypefnx {Loadable Function} {@var{v} =} rand ("seed")
@deftypefnx {Loadable Function} {} rand ("seed", @var{v})
@deftypefnx {Loadable Function} {} rand ("seed", "reset")
Return a matrix with random elements uniformly distributed on the
interval (0, 1).  The arguments are handled the same as the arguments
for @code{eye}.

You can query the state of the random number generator using the
form

@example
v = rand ("state")
@end example

This returns a column vector @var{v} of length 625.  Later, you can
restore the random number generator to the state @var{v}
using the form

@example
rand ("state", v)
@end example

@noindent
You may also initialize the state vector from an arbitrary vector of
length @leq{} 625 for @var{v}.  This new state will be a hash based on the
value of @var{v}, not @var{v} itself.

By default, the generator is initialized from @code{/dev/urandom} if it is
available, otherwise from CPU time, wall clock time, and the current
fraction of a second.

To compute the pseudo-random sequence, @code{rand} uses the Mersenne
Twister with a period of @math{2^{19937}-1} (See M. Matsumoto and
T. Nishimura,
@cite{Mersenne Twister: A 623-dimensionally equidistributed uniform
pseudorandom number generator}, ACM Trans. on
Modeling and Computer Simulation Vol. 8, No. 1, pp. 3-30, January 1998,
@url{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html}).
Do @strong{not} use for cryptography without securely hashing
several returned values together, otherwise the generator state
can be learned after reading 624 consecutive values.

Older versions of Octave used a different random number generator.
The new generator is used by default
as it is significantly faster than the old generator, and produces
random numbers with a significantly longer cycle time.  However, in
some circumstances it might be desirable to obtain the same random
sequences as used by the old generators.  To do this the keyword
"seed" is used to specify that the old generators should be use,
as in

@example
rand ("seed", val)
@end example

@noindent
which sets the seed of the generator to @var{val}.  The seed of the
generator can be queried with

@example
s = rand ("seed")
@end example

However, it should be noted that querying the seed will not cause
@code{rand} to use the old generators, only setting the seed will.
To cause @code{rand} to once again use the new generators, the
keyword "state" should be used to reset the state of the @code{rand}.

The state or seed of the generator can be reset to a new random value
using the "reset" keyword.
@seealso{randn, rande, randg, randp}
@end deftypefn
randn
@c randn src/DLD-FUNCTIONS/rand.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} randn (@var{n})
@deftypefnx {Loadable Function} {} randn (@var{n}, @var{m}, @dots{})
@deftypefnx {Loadable Function} {} randn ([@var{n} @var{m} @dots{}])
@deftypefnx {Loadable Function} {@var{v} =} randn ("state")
@deftypefnx {Loadable Function} {} randn ("state", @var{v})
@deftypefnx {Loadable Function} {} randn ("state", "reset")
@deftypefnx {Loadable Function} {@var{v} =} randn ("seed")
@deftypefnx {Loadable Function} {} randn ("seed", @var{v})
@deftypefnx {Loadable Function} {} randn ("seed", "reset")
Return a matrix with normally distributed random
elements having zero mean and variance one.  The arguments are
handled the same as the arguments for @code{rand}.

By default, @code{randn} uses the Marsaglia and Tsang ``Ziggurat technique''
to transform from a uniform to a normal distribution.

Reference: G. Marsaglia and W.W. Tsang,
@cite{Ziggurat Method for Generating Random Variables},
J. Statistical Software, vol 5, 2000,
@url{http://www.jstatsoft.org/v05/i08/})

@seealso{rand, rande, randg, randp}
@end deftypefn
rande
@c rande src/DLD-FUNCTIONS/rand.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} rande (@var{n})
@deftypefnx {Loadable Function} {} rande (@var{n}, @var{m}, @dots{})
@deftypefnx {Loadable Function} {} rande ([@var{n} @var{m} @dots{}])
@deftypefnx {Loadable Function} {@var{v} =} rande ("state")
@deftypefnx {Loadable Function} {} rande ("state", @var{v})
@deftypefnx {Loadable Function} {} rande ("state", "reset")
@deftypefnx {Loadable Function} {@var{v} =} rande ("seed")
@deftypefnx {Loadable Function} {} rande ("seed", @var{v})
@deftypefnx {Loadable Function} {} rande ("seed", "reset")
Return a matrix with exponentially distributed random elements.  The
arguments are handled the same as the arguments for @code{rand}.

By default, @code{randn} uses the Marsaglia and Tsang ``Ziggurat technique''
to transform from a uniform to an exponential distribution.

Reference: G. Marsaglia and W.W. Tsang,
@cite{Ziggurat Method for Generating Random Variables},
J. Statistical Software, vol 5, 2000,
@url{http://www.jstatsoft.org/v05/i08/})

@seealso{rand, randn, randg, randp}
@end deftypefn
randg
@c randg src/DLD-FUNCTIONS/rand.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} randg (@var{n})
@deftypefnx {Loadable Function} {} randg (@var{n}, @var{m}, @dots{})
@deftypefnx {Loadable Function} {} randg ([@var{n} @var{m} @dots{}])
@deftypefnx {Loadable Function} {@var{v} =} randg ("state")
@deftypefnx {Loadable Function} {} randg ("state", @var{v})
@deftypefnx {Loadable Function} {} randg ("state", "reset")
@deftypefnx {Loadable Function} {@var{v} =} randg ("seed")
@deftypefnx {Loadable Function} {} randg ("seed", @var{v})
@deftypefnx {Loadable Function} {} randg ("seed", "reset")
Return a matrix with @code{gamma(@var{a},1)} distributed random elements.
The arguments are handled the same as the arguments for @code{rand},
except for the argument @var{a}.

This can be used to generate many distributions:

@table @asis
@item @code{gamma (a, b)} for @code{a > -1}, @code{b > 0}

@example
r = b * randg (a)
@end example

@item @code{beta (a, b)} for @code{a > -1}, @code{b > -1}

@example
@group
r1 = randg (a, 1)
r = r1 / (r1 + randg (b, 1))
@end group
@end example

@item @code{Erlang (a, n)}

@example
r = a * randg (n)
@end example

@item @code{chisq (df)} for @code{df > 0}

@example
r = 2 * randg (df / 2)
@end example

@item @code{t (df)} for @code{0 < df < inf} (use randn if df is infinite)

@example
r = randn () / sqrt (2 * randg (df / 2) / df)
@end example

@item @code{F (n1, n2)} for @code{0 < n1}, @code{0 < n2}

@example
@group
## r1 equals 1 if n1 is infinite
r1 = 2 * randg (n1 / 2) / n1
## r2 equals 1 if n2 is infinite
r2 = 2 * randg (n2 / 2) / n2
r = r1 / r2

@end group
@end example

@item negative @code{binomial (n, p)} for @code{n > 0}, @code{0 < p <= 1}

@example
r = randp ((1 - p) / p * randg (n))
@end example

@item non-central @code{chisq (df, L)}, for @code{df >= 0} and @code{L > 0}
(use chisq if @code{L = 0})

@example
@group
r = randp (L / 2)
r(r > 0) = 2 * randg (r(r > 0))
r(df > 0) += 2 * randg (df(df > 0)/2)
@end group
@end example

@item @code{Dirichlet (a1, @dots{} ak)}

@example
@group
r = (randg (a1), @dots{}, randg (ak))
r = r / sum (r)
@end group
@end example

@end table
@seealso{rand, randn, rande, randp}
@end deftypefn
randp
@c randp src/DLD-FUNCTIONS/rand.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} randp (@var{l}, @var{n})
@deftypefnx {Loadable Function} {} randp (@var{l}, @var{n}, @var{m}, @dots{})
@deftypefnx {Loadable Function} {} randp (@var{l}, [@var{n} @var{m} @dots{}])
@deftypefnx {Loadable Function} {@var{v} =} randp ("state")
@deftypefnx {Loadable Function} {} randp ("state", @var{v})
@deftypefnx {Loadable Function} {} randp ("state", "reset")
@deftypefnx {Loadable Function} {@var{v} =} randp ("seed")
@deftypefnx {Loadable Function} {} randp ("seed", @var{v})
@deftypefnx {Loadable Function} {} randp ("seed", "reset")
Return a matrix with Poisson distributed random elements with mean value
parameter given by the first argument, @var{l}.  The arguments
are handled the same as the arguments for @code{rand}, except for the
argument @var{l}.

Five different algorithms are used depending on the range of @var{l}
and whether or not @var{l} is a scalar or a matrix.

@table @asis
@item For scalar @var{l} @leq{} 12, use direct method.
W.H. Press, et al., @cite{Numerical Recipes in C},
Cambridge University Press, 1992.

@item For scalar @var{l} > 12, use rejection method.[1]
W.H. Press, et al., @cite{Numerical Recipes in C},
Cambridge University Press, 1992.

@item For matrix @var{l} @leq{} 10, use inversion method.[2]
E. Stadlober, et al., WinRand source code, available via FTP.

@item For matrix @var{l} > 10, use patchwork rejection method.
E. Stadlober, et al., WinRand source code, available via FTP, or
H. Zechner, @cite{Efficient sampling from continuous and discrete
unimodal distributions}, Doctoral Dissertation, 156pp., Technical
University Graz, Austria, 1994.

@item For @var{l} > 1e8, use normal approximation.
L. Montanet, et al., @cite{Review of Particle Properties}, Physical Review
D 50 p1284, 1994.
@end table
@seealso{rand, randn, rande, randg}
@end deftypefn
randperm
@c randperm src/DLD-FUNCTIONS/rand.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} randperm (@var{n})
@deftypefnx {Loadable Function} {} randperm (@var{n}, @var{m})
Return a row vector containing a random permutation of @code{1:@var{n}}.
If @var{m} is supplied, return @var{m} unique entries, sampled without
replacement from @code{1:@var{n}}.  The complexity is O(@var{n}) in
memory and O(@var{m}) in time, unless @var{m} < @var{n}/5, in which case
O(@var{m}) memory is used as well.  The randomization is performed using
rand(). All permutations are equally likely.
@seealso{perms}
@end deftypefn
rcond
@c rcond src/DLD-FUNCTIONS/rcond.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{c} =} rcond (@var{A})
Compute the 1-norm estimate of the reciprocal condition number as returned
by @sc{lapack}.  If the matrix is well-conditioned then @var{c} will be near
1 and if the matrix is poorly conditioned it will be close to zero.

The matrix @var{A} must not be sparse.  If the matrix is sparse then
@code{condest (@var{A})} or @code{rcond (full (@var{A}))} should be used
instead.
@seealso{cond, condest}
@end deftypefn
regexp
@c regexp src/DLD-FUNCTIONS/regexp.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}] =} regexp (@var{str}, @var{pat})
@deftypefnx {Loadable Function} {[@dots{}] =} regexp (@var{str}, @var{pat}, "@var{opt1}", @dots{})
Regular expression string matching.  Search for @var{pat} in @var{str} and
return the positions and substrings of any matches, or empty values if there
are none.

The matched pattern @var{pat} can include any of the standard regex
operators, including:

@table @code
@item .
Match any character

@item * + ? @{@}
Repetition operators, representing
@table @code
@item *
Match zero or more times

@item +
Match one or more times

@item ?
Match zero or one times

@item @{@var{n}@}
Match exactly @var{n} times

@item @{@var{n},@}
Match @var{n} or more times

@item @{@var{m},@var{n}@}
Match between @var{m} and @var{n} times
@end table

@item [@dots{}] [^@dots{}]

List operators.  The pattern will match any character listed between "["
and "]".  If the first character is "^" then the pattern is inverted and
any character except those listed between brackets will match.

Escape sequences defined below can also be used inside list
operators.  For example, a template for a floating point number might be
@code{[-+.\d]+}.

@item ()
Grouping operator

@item |
Alternation operator.  Match one of a choice of regular expressions.  The
alternatives must be delimited by the grouping operator @code{()} above.

@item ^ $
Anchoring operators.  Requires pattern to occur at the start (@code{^}) or
end (@code{$}) of the string.
@end table

In addition, the following escaped characters have special meaning.  Note,
it is recommended to quote @var{pat} in single quotes, rather than double
quotes, to avoid the escape sequences being interpreted by Octave before
being passed to @code{regexp}.

@table @code
@item \b
Match a word boundary

@item \B
Match within a word

@item \w
Match any word character

@item \W
Match any non-word character

@item \<
Match the beginning of a word

@item \>
Match the end of a word

@item \s
Match any whitespace character

@item \S
Match any non-whitespace character

@item \d
Match any digit

@item \D
Match any non-digit
@end table

The outputs of @code{regexp} default to the order given below

@table @var
@item s
The start indices of each matching substring

@item e
The end indices of each matching substring

@item te
The extents of each matched token surrounded by @code{(@dots{})} in
@var{pat}

@item m
A cell array of the text of each match

@item t
A cell array of the text of each token matched

@item nm
A structure containing the text of each matched named token, with the name
being used as the fieldname.  A named token is denoted by
@code{(?<name>@dots{})}.

@item sp
A cell array of the text not returned by match.
@end table

Particular output arguments, or the order of the output arguments, can be
selected by additional @var{opt} arguments.  These are strings and the
correspondence between the output arguments and the optional argument
are

@multitable @columnfractions 0.2 0.3 0.3 0.2
@item @tab 'start'        @tab @var{s}  @tab
@item @tab 'end'          @tab @var{e}  @tab
@item @tab 'tokenExtents' @tab @var{te} @tab
@item @tab 'match'        @tab @var{m}  @tab
@item @tab 'tokens'       @tab @var{t}  @tab
@item @tab 'names'        @tab @var{nm} @tab
@item @tab 'split'        @tab @var{sp} @tab
@end multitable

Additional arguments are summarized below.

@table @samp
@item once
Return only the first occurrence of the pattern.

@item matchcase
Make the matching case sensitive.  (default)

Alternatively, use (?-i) in the pattern.

@item ignorecase
Ignore case when matching the pattern to the string.

Alternatively, use (?i) in the pattern.

@item stringanchors
Match the anchor characters at the beginning and end of the string.
(default)

Alternatively, use (?-m) in the pattern.

@item lineanchors
Match the anchor characters at the beginning and end of the line.

Alternatively, use (?m) in the pattern.

@item dotall
The pattern @code{.} matches all characters including the newline character.
 (default)

Alternatively, use (?s) in the pattern.

@item dotexceptnewline
The pattern @code{.} matches all characters except the newline character.

Alternatively, use (?-s) in the pattern.

@item literalspacing
All characters in the pattern, including whitespace, are significant and are
used in pattern matching.  (default)

Alternatively, use (?-x) in the pattern.

@item freespacing
The pattern may include arbitrary whitespace and also comments beginning with
the character @samp{#}.

Alternatively, use (?x) in the pattern.

@end table
@seealso{regexpi, strfind, regexprep}
@end deftypefn
regexpi
@c regexpi src/DLD-FUNCTIONS/regexp.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}] =} regexpi (@var{str}, @var{pat})
@deftypefnx {Loadable Function} {[@dots{}] =} regexpi (@var{str}, @var{pat}, "@var{opt1}", @dots{})

Case insensitive regular expression string matching.  Search for @var{pat} in
@var{str} and return the positions and substrings of any matches, or empty
values if there are none.  @xref{doc-regexp,,regexp}, for details on the
syntax of the search pattern.
@seealso{regexp}
@end deftypefn
regexprep
@c regexprep src/DLD-FUNCTIONS/regexp.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{outstr} =} regexprep (@var{string}, @var{pat}, @var{repstr})
@deftypefnx {Loadable Function} {@var{outstr} =} regexprep (@var{string}, @var{pat}, @var{repstr}, "@var{opt1}", @dots{})
Replace occurrences of pattern @var{pat} in @var{string} with @var{repstr}.

The pattern is a regular expression as documented for @code{regexp}.
@xref{doc-regexp,,regexp}.

The replacement string may contain @code{$i}, which substitutes
for the ith set of parentheses in the match string.  For example,

@example
regexprep("Bill Dunn",'(\w+) (\w+)','$2, $1')
@end example

@noindent
returns "Dunn, Bill"

Options in addition to those of @code{regexp} are

@table @samp

@item once
Replace only the first occurrence of @var{pat} in the result.

@item warnings
This option is present for compatibility but is ignored.

@end table
@seealso{regexp, regexpi, strrep}
@end deftypefn
schur
@c schur src/DLD-FUNCTIONS/schur.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{S} =} schur (@var{A})
@deftypefnx {Loadable Function} {@var{S} =} schur (@var{A}, "real")
@deftypefnx {Loadable Function} {@var{S} =} schur (@var{A}, "complex")
@deftypefnx {Loadable Function} {@var{S} =} schur (@var{A}, @var{opt})
@deftypefnx {Loadable Function} {[@var{U}, @var{S}] =} schur (@var{A}, @dots{})
@cindex Schur decomposition
Compute the Schur@tie{}decomposition of @var{A}
@tex
$$
 S = U^T A U
$$
@end tex
@ifnottex

@example
@code{@var{S} = @var{U}' * @var{A} * @var{U}}
@end example

@end ifnottex
where @var{U} is a unitary matrix
@tex
($U^T U$ is identity)
@end tex
@ifnottex
(@code{@var{U}'* @var{U}} is identity)
@end ifnottex
and @var{S} is upper triangular.  The eigenvalues of @var{A} (and @var{S})
are the diagonal elements of @var{S}.  If the matrix @var{A}
is real, then the real Schur@tie{}decomposition is computed, in which the
matrix @var{U} is orthogonal and @var{S} is block upper triangular
with blocks of size at most
@tex
$2 \times 2$
@end tex
@ifnottex
@code{2 x 2}
@end ifnottex
along the diagonal.  The diagonal elements of @var{S}
(or the eigenvalues of the
@tex
$2 \times 2$
@end tex
@ifnottex
@code{2 x 2}
@end ifnottex
blocks, when appropriate) are the eigenvalues of @var{A} and @var{S}.

The default for real matrices is a real Schur@tie{}decomposition.
A complex decomposition may be forced by passing the flag "complex".

The eigenvalues are optionally ordered along the diagonal according to
the value of @var{opt}.  @code{@var{opt} = "a"} indicates that all
eigenvalues with negative real parts should be moved to the leading
block of @var{S}
(used in @code{are}), @code{@var{opt} = "d"} indicates that all eigenvalues
with magnitude less than one should be moved to the leading block of @var{S}
(used in @code{dare}), and @code{@var{opt} = "u"}, the default, indicates
that no ordering of eigenvalues should occur.  The leading @var{k}
columns of @var{U} always span the @var{A}-invariant
subspace corresponding to the @var{k} leading eigenvalues of @var{S}.

The Schur@tie{}decomposition is used to compute eigenvalues of a
square matrix, and has applications in the solution of algebraic
Riccati equations in control (see @code{are} and @code{dare}).
@seealso{rsf2csf}
@end deftypefn
rsf2csf
@c rsf2csf src/DLD-FUNCTIONS/schur.cc
-*- texinfo -*-
@deftypefn {Function File} {[@var{U}, @var{T}] =} rsf2csf (@var{UR}, @var{TR})
Convert a real, upper quasi-triangular Schur@tie{}form @var{TR} to a complex,
upper triangular Schur@tie{}form @var{T}.

Note that the following relations hold:

@tex
$UR \cdot TR \cdot {UR}^T = U T U^{\dagger}$ and
$U^{\dagger} U$ is the identity matrix I.
@end tex
@ifnottex
@xcode{@var{UR} * @var{TR} * @var{UR}' = @var{U} * @var{T} * @var{U}'} and
@code{@var{U}' * @var{U}} is the identity matrix I.
@end ifnottex

Note also that @var{U} and @var{T} are not unique.
@seealso{schur}
@end deftypefn
spparms
@c spparms src/DLD-FUNCTIONS/spparms.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} { } spparms ()
@deftypefnx {Loadable Function} {@var{vals} =} spparms ()
@deftypefnx {Loadable Function} {[@var{keys}, @var{vals}] =} spparms ()
@deftypefnx {Loadable Function} {@var{val} =} spparms (@var{key})
@deftypefnx {Loadable Function} { } spparms (@var{vals})
@deftypefnx {Loadable Function} { } spparms ('defaults')
@deftypefnx {Loadable Function} { } spparms ('tight')
@deftypefnx {Loadable Function} { } spparms (@var{key}, @var{val})
Query or set the parameters used by the sparse solvers and factorization
functions.  The first four calls above get information about the current
settings, while the others change the current settings.  The parameters are
stored as pairs of keys and values, where the values are all floats and the
keys are one of the following strings:

@table @samp
@item spumoni
Printing level of debugging information of the solvers (default 0)

@item ths_rel
Included for compatibility.  Not used.  (default 1)

@item ths_abs
Included for compatibility.  Not used.  (default 1)

@item exact_d
Included for compatibility.  Not used.  (default 0)

@item supernd
Included for compatibility.  Not used.  (default 3)

@item rreduce
Included for compatibility.  Not used.  (default 3)

@item wh_frac
Included for compatibility.  Not used.  (default 0.5)

@item autommd
Flag whether the LU/QR and the '\' and '/' operators will automatically
use the sparsity preserving mmd functions (default 1)

@item autoamd
Flag whether the LU and the '\' and '/' operators will automatically
use the sparsity preserving amd functions (default 1)

@item piv_tol
The pivot tolerance of the @sc{umfpack} solvers (default 0.1)

@item sym_tol
The pivot tolerance of the @sc{umfpack} symmetric solvers (default 0.001)

@item bandden
The density of non-zero elements in a banded matrix before it is treated
by the @sc{lapack} banded solvers (default 0.5)

@item umfpack
Flag whether the @sc{umfpack} or mmd solvers are used for the LU, '\' and
'/' operations (default 1)
@end table

The value of individual keys can be set with
@code{spparms (@var{key}, @var{val})}.
The default values can be restored with the special keyword
'defaults'.  The special keyword 'tight' can be used to set the mmd solvers
to attempt a sparser solution at the potential cost of longer running
time.
@end deftypefn
sqrtm
@c sqrtm src/DLD-FUNCTIONS/sqrtm.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{s} =} sqrtm (@var{A})
@deftypefnx {Loadable Function} {[@var{s}, @var{error_estimate}] =} sqrtm (@var{A})
Compute the matrix square root of the square matrix @var{A}.

Ref: N.J. Higham.  @cite{A New sqrtm for @sc{matlab}}.  Numerical
Analysis Report No. 336, Manchester @nospell{Centre} for Computational
Mathematics, Manchester, England, January 1999.
@seealso{expm, logm}
@end deftypefn
strfind
@c strfind src/DLD-FUNCTIONS/strfind.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{idx} =} strfind (@var{str}, @var{pattern})
@deftypefnx {Loadable Function} {@var{idx} =} strfind (@var{cellstr}, @var{pattern})
Search for @var{pattern} in the string @var{str} and return the
starting index of every such occurrence in the vector @var{idx}.
If there is no such occurrence, or if @var{pattern} is longer
than @var{str}, then @var{idx} is the empty array @code{[]}.

If a cell array of strings @var{cellstr} is specified
then @var{idx} is a cell array of vectors, as specified
above.  Examples:

@example
@group
strfind ("abababa", "aba")
     @result{} [1, 3, 5]

strfind (@{"abababa", "bebebe", "ab"@}, "aba")
     @result{} ans =
        @{
          [1,1] =

             1   3   5

          [1,2] = [](1x0)
          [1,3] = [](1x0)
        @}
@end group
@end example
@seealso{findstr, strmatch, regexp, regexpi, find}
@end deftypefn
strrep
@c strrep src/DLD-FUNCTIONS/strfind.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} strrep (@var{s}, @var{ptn}, @var{rep})
@deftypefnx {Loadable Function} {} strrep (@var{s}, @var{ptn}, @var{rep}, "overlaps", @var{o})
Replace all occurrences of the substring @var{ptn} in the string @var{s}
with the string @var{rep} and return the result.  For example:

@example
@group
strrep ("This is a test string", "is", "&%$")
     @result{} "Th&%$ &%$ a test string"
@end group
@end example

@var{s} may also be a cell array of strings, in which case the replacement is
done for each element and a cell array is returned.
@seealso{regexprep, strfind, findstr}
@end deftypefn
str2double
@c str2double src/DLD-FUNCTIONS/str2double.cc
-*- texinfo -*-
@deftypefn {Built-in Function} {} str2double (@var{s})
Convert a string to a real or complex number.

The string must be in one of the following formats where
a and b are real numbers and the complex unit is 'i' or 'j':

@itemize
@item a + bi

@item a + b*i

@item a + i*b

@item bi + a

@item b*i + a

@item i*b + a
@end itemize

If present, a and/or b are of the form @nospell{[+-]d[,.]d[[eE][+-]d]} where
the brackets indicate optional arguments and 'd' indicates zero or more
digits.  The special input values @code{Inf}, @code{NaN}, and @code{NA} are
also accepted.

@var{s} may also be a character matrix, in which case the conversion is
repeated for each row.  Or @var{s} may be a cell array of strings, in which
case each element is converted and an array of the same dimensions is
returned.

@code{str2double} returns NaN for elements of @var{s} which cannot be
converted.

@code{str2double} can replace @code{str2num}, and it avoids the security
risk of using @code{eval} on unknown data.
@seealso{str2num}
@end deftypefn
sub2ind
@c sub2ind src/DLD-FUNCTIONS/sub2ind.cc
-*- texinfo -*-
@deftypefn  {Function File} {@var{ind} =} sub2ind (@var{dims}, @var{i}, @var{j})
@deftypefnx {Function File} {@var{ind} =} sub2ind (@var{dims}, @var{s1}, @var{s2}, @dots{}, @var{sN})
Convert subscripts to a linear index.

The following example shows how to convert the two-dimensional
index @code{(2,3)} of a 3-by-3 matrix to a linear index.  The matrix
is linearly indexed moving from one column to next, filling up
all rows in each column.

@example
@group
linear_index = sub2ind ([3, 3], 2, 3)
@result{} 8
@end group
@end example
@seealso{ind2sub}
@end deftypefn
ind2sub
@c ind2sub src/DLD-FUNCTIONS/sub2ind.cc
-*- texinfo -*-
@deftypefn {Function File} {[@var{s1}, @var{s2}, @dots{}, @var{sN}] =} ind2sub (@var{dims}, @var{ind})
Convert a linear index to subscripts.

The following example shows how to convert the linear index @code{8}
in a 3-by-3 matrix into a subscript.  The matrix is linearly indexed
moving from one column to next, filling up all rows in each column.

@example
@group
[r, c] = ind2sub ([3, 3], 8)
@result{} r =  2
   c =  3
@end group
@end example
@seealso{sub2ind}
@end deftypefn
svd
@c svd src/DLD-FUNCTIONS/svd.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{s} =} svd (@var{A})
@deftypefnx {Loadable Function} {[@var{U}, @var{S}, @var{V}] =} svd (@var{A})
@deftypefnx {Loadable Function} {[@var{U}, @var{S}, @var{V}] =} svd (@var{A}, @var{econ})
@cindex singular value decomposition
Compute the singular value decomposition of @var{A}
@tex
$$
 A = U S V^{\dagger}
$$
@end tex
@ifnottex

@example
A = U*S*V'
@end example

@end ifnottex

The function @code{svd} normally returns only the vector of singular values.
When called with three return values, it computes
@tex
$U$, $S$, and $V$.
@end tex
@ifnottex
@var{U}, @var{S}, and @var{V}.
@end ifnottex
For example,

@example
svd (hilb (3))
@end example

@noindent
returns

@example
@group
ans =

  1.4083189
  0.1223271
  0.0026873
@end group
@end example

@noindent
and

@example
[u, s, v] = svd (hilb (3))
@end example

@noindent
returns

@example
@group
u =

  -0.82704   0.54745   0.12766
  -0.45986  -0.52829  -0.71375
  -0.32330  -0.64901   0.68867

s =

  1.40832  0.00000  0.00000
  0.00000  0.12233  0.00000
  0.00000  0.00000  0.00269

v =

  -0.82704   0.54745   0.12766
  -0.45986  -0.52829  -0.71375
  -0.32330  -0.64901   0.68867
@end group
@end example

If given a second argument, @code{svd} returns an economy-sized
decomposition, eliminating the unnecessary rows or columns of @var{U} or
@var{V}.
@seealso{svd_driver, svds, eig}
@end deftypefn
svd_driver
@c svd_driver src/DLD-FUNCTIONS/svd.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{val} =} svd_driver ()
@deftypefnx {Loadable Function} {@var{old_val} =} svd_driver (@var{new_val})
@deftypefnx {Loadable Function} {} svd_driver (@var{new_val}, "local")
Query or set the underlying @sc{lapack} driver used by @code{svd}.
Currently recognized values are "gesvd" and "gesdd".  The default
is "gesvd".

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.
@seealso{svd}
@end deftypefn
syl
@c syl src/DLD-FUNCTIONS/syl.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{x} =} syl (@var{A}, @var{B}, @var{C})
Solve the Sylvester equation
@tex
$$
 A X + X B + C = 0
$$
@end tex
@ifnottex

@example
A X + X B + C = 0
@end example

@end ifnottex
using standard @sc{lapack} subroutines.  For example:

@example
@group
syl ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12])
     @result{} [ -0.50000, -0.66667; -0.66667, -0.50000 ]
@end group
@end example
@end deftypefn
symbfact
@c symbfact src/DLD-FUNCTIONS/symbfact.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{count}, @var{h}, @var{parent}, @var{post}, @var{r}] =} symbfact (@var{S})
@deftypefnx {Loadable Function} {[@dots{}] =} symbfact (@var{S}, @var{typ})
@deftypefnx {Loadable Function} {[@dots{}] =} symbfact (@var{S}, @var{typ}, @var{mode})

Perform a symbolic factorization analysis on the sparse matrix @var{S}.
Where

@table @var
@item S
@var{S} is a complex or real sparse matrix.

@item typ
Is the type of the factorization and can be one of

@table @samp
@item sym
Factorize @var{S}.  This is the default.

@item col
Factorize @code{@var{S}' * @var{S}}.

@item row
Factorize @xcode{@var{S} * @var{S}'}.

@item lo
Factorize @xcode{@var{S}'}
@end table

@item mode
The default is to return the Cholesky@tie{}factorization for @var{r}, and if
@var{mode} is 'L', the conjugate transpose of the Cholesky@tie{}factorization
is returned.  The conjugate transpose version is faster and uses less
memory, but returns the same values for @var{count}, @var{h}, @var{parent}
and @var{post} outputs.
@end table

The output variables are

@table @var
@item count
The row counts of the Cholesky@tie{}factorization as determined by @var{typ}.

@item h
The height of the elimination tree.

@item parent
The elimination tree itself.

@item post
A sparse boolean matrix whose structure is that of the Cholesky
factorization as determined by @var{typ}.
@end table
@end deftypefn
symrcm
@c symrcm src/DLD-FUNCTIONS/symrcm.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{p} =} symrcm (@var{S})
Return the symmetric reverse Cuthill-McKee permutation of @var{S}.
@var{p} is a permutation vector such that
@code{@var{S}(@var{p}, @var{p})} tends to have its diagonal elements
closer to the diagonal than @var{S}.  This is a good preordering for LU
or Cholesky@tie{}factorization of matrices that come from 'long, skinny'
problems.  It works for both symmetric and asymmetric @var{S}.

The algorithm represents a heuristic approach to the NP-complete
bandwidth minimization problem.  The implementation is based in the
descriptions found in

E. Cuthill, J. McKee. @cite{Reducing the Bandwidth of Sparse Symmetric
Matrices}. Proceedings of the 24th ACM National Conference, 157--172
1969, Brandon Press, New Jersey.

A. George, J.W.H. Liu. @cite{Computer Solution of Large Sparse
Positive Definite Systems}, Prentice Hall Series in Computational
Mathematics, ISBN 0-13-165274-5, 1981.

@seealso{colperm, colamd, symamd}
@end deftypefn
time
@c time src/DLD-FUNCTIONS/time.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{seconds} =} time ()
Return the current time as the number of seconds since the epoch.  The
epoch is referenced to 00:00:00 CUT (Coordinated Universal Time) 1 Jan
1970.  For example, on Monday February 17, 1997 at 07:15:06 CUT, the
value returned by @code{time} was 856163706.
@seealso{strftime, strptime, localtime, gmtime, mktime, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
gmtime
@c gmtime src/DLD-FUNCTIONS/time.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{tm_struct} =} gmtime (@var{t})
Given a value returned from @code{time}, or any non-negative integer,
return a time structure corresponding to CUT (Coordinated Universal Time).
For example:

@example
@group
gmtime (time ())
     @result{} @{
           usec = 0
           sec = 6
           min = 15
           hour = 7
           mday = 17
           mon = 1
           year = 97
           wday = 1
           yday = 47
           isdst = 0
           zone = CST
         @}
@end group
@end example
@seealso{strftime, strptime, localtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
localtime
@c localtime src/DLD-FUNCTIONS/time.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{tm_struct} =} localtime (@var{t})
Given a value returned from @code{time}, or any non-negative integer,
return a time structure corresponding to the local time zone.

@example
@group
localtime (time ())
     @result{} @{
           usec = 0
           sec = 6
           min = 15
           hour = 1
           mday = 17
           mon = 1
           year = 97
           wday = 1
           yday = 47
           isdst = 0
           zone = CST
         @}
@end group
@end example
@seealso{strftime, strptime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
mktime
@c mktime src/DLD-FUNCTIONS/time.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{seconds} =} mktime (@var{tm_struct})
Convert a time structure corresponding to the local time to the number
of seconds since the epoch.  For example:

@example
@group
mktime (localtime (time ()))
     @result{} 856163706
@end group
@end example
@seealso{strftime, strptime, localtime, gmtime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
strftime
@c strftime src/DLD-FUNCTIONS/time.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} strftime (@var{fmt}, @var{tm_struct})
Format the time structure @var{tm_struct} in a flexible way using the
format string @var{fmt} that contains @samp{%} substitutions
similar to those in @code{printf}.  Except where noted, substituted
fields have a fixed size; numeric fields are padded if necessary.
Padding is with zeros by default; for fields that display a single
number, padding can be changed or inhibited by following the @samp{%}
with one of the modifiers described below.  Unknown field specifiers are
copied as normal characters.  All other characters are copied to the
output without change.  For example:

@example
@group
strftime ("%r (%Z) %A %e %B %Y", localtime (time ()))
     @result{} "01:15:06 AM (CST) Monday 17 February 1997"
@end group
@end example

Octave's @code{strftime} function supports a superset of the ANSI C
field specifiers.

@noindent
Literal character fields:

@table @code
@item %%
% character.

@item %n
Newline character.

@item %t
Tab character.
@end table

@noindent
Numeric modifiers (a nonstandard extension):

@table @code
@item - (dash)
Do not pad the field.

@item _ (underscore)
Pad the field with spaces.
@end table

@noindent
Time fields:

@table @code
@item %H
Hour (00-23).

@item %I
Hour (01-12).

@item %k
Hour (0-23).

@item %l
Hour (1-12).

@item %M
Minute (00-59).

@item %p
Locale's AM or PM.

@item %r
Time, 12-hour (hh:mm:ss [AP]M).

@item %R
Time, 24-hour (hh:mm).

@item %s
Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard extension).

@item %S
Second (00-61).

@item %T
Time, 24-hour (hh:mm:ss).

@item %X
Locale's time representation (%H:%M:%S).

@item %Z
Time zone (EDT), or nothing if no time zone is determinable.
@end table

@noindent
Date fields:

@table @code
@item %a
Locale's abbreviated weekday name (Sun-Sat).

@item %A
Locale's full weekday name, variable length (Sunday-Saturday).

@item %b
Locale's abbreviated month name (Jan-Dec).

@item %B
Locale's full month name, variable length (January-December).

@item %c
Locale's date and time (Sat Nov 04 12:02:33 EST 1989).

@item %C
Century (00-99).

@item %d
Day of month (01-31).

@item %e
Day of month ( 1-31).

@item %D
Date (mm/dd/yy).

@item %h
Same as %b.

@item %j
Day of year (001-366).

@item %m
Month (01-12).

@item %U
Week number of year with Sunday as first day of week (00-53).

@item %w
Day of week (0-6).

@item %W
Week number of year with Monday as first day of week (00-53).

@item %x
Locale's date representation (mm/dd/yy).

@item %y
Last two digits of year (00-99).

@item %Y
Year (1970-).
@end table
@seealso{strptime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
strptime
@c strptime src/DLD-FUNCTIONS/time.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{tm_struct}, @var{nchars}] =} strptime (@var{str}, @var{fmt})
Convert the string @var{str} to the time structure @var{tm_struct} under
the control of the format string @var{fmt}.

If @var{fmt} fails to match, @var{nchars} is 0; otherwise, it is set to the
position of last matched character plus 1. Always check for this unless
you're absolutely sure the date string will be parsed correctly.
@seealso{strftime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
tril
@c tril src/DLD-FUNCTIONS/tril.cc
-*- texinfo -*-
@deftypefn  {Function File} {} tril (@var{A})
@deftypefnx {Function File} {} tril (@var{A}, @var{k})
@deftypefnx {Function File} {} tril (@var{A}, @var{k}, @var{pack})
@deftypefnx {Function File} {} triu (@var{A})
@deftypefnx {Function File} {} triu (@var{A}, @var{k})
@deftypefnx {Function File} {} triu (@var{A}, @var{k}, @var{pack})
Return a new matrix formed by extracting the lower (@code{tril})
or upper (@code{triu}) triangular part of the matrix @var{A}, and
setting all other elements to zero.  The second argument is optional,
and specifies how many diagonals above or below the main diagonal should
also be set to zero.

The default value of @var{k} is zero, so that @code{triu} and
@code{tril} normally include the main diagonal as part of the result.

If the value of @var{k} is negative, additional elements above (for
@code{tril}) or below (for @code{triu}) the main diagonal are also
selected.

The absolute value of @var{k} must not be greater than the number of
sub-diagonals or super-diagonals.

For example:

@example
@group
tril (ones (3), -1)
     @result{}  0  0  0
         1  0  0
         1  1  0
@end group
@end example

@noindent
and

@example
@group
tril (ones (3), 1)
     @result{}  1  1  0
         1  1  1
         1  1  1
@end group
@end example

If the option "pack" is given as third argument, the extracted elements
are not inserted into a matrix, but rather stacked column-wise one above
other.
@seealso{diag}
@end deftypefn
triu
@c triu src/DLD-FUNCTIONS/tril.cc
-*- texinfo -*-
@deftypefn  {Function File} {} triu (@var{A})
@deftypefnx {Function File} {} triu (@var{A}, @var{k})
@deftypefnx {Function File} {} triu (@var{A}, @var{k}, @var{pack})
See the documentation for the @code{tril} function (@pxref{tril}).
@end deftypefn
tsearch
@c tsearch src/DLD-FUNCTIONS/tsearch.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{idx} =} tsearch (@var{x}, @var{y}, @var{t}, @var{xi}, @var{yi})
Search for the enclosing Delaunay convex hull.  For @code{@var{t} =
delaunay (@var{x}, @var{y})}, finds the index in @var{t} containing the
points @code{(@var{xi}, @var{yi})}.  For points outside the convex hull,
@var{idx} is NaN.
@seealso{delaunay, delaunayn}
@end deftypefn
typecast
@c typecast src/DLD-FUNCTIONS/typecast.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} typecast (@var{x}, @var{class})
Return a new array @var{y} resulting from interpreting the data of
@var{x} in memory as data of the numeric class @var{class}.  Both the class
of @var{x} and @var{class} must be one of the built-in numeric classes:

@example
@group
  "logical"
  "char"
  "int8"
  "int16"
  "int32"
  "int64"
  "uint8"
  "uint16"
  "uint32"
  "uint64"
  "double"
  "single"
  "double complex"
  "single complex"
@end group
@end example

@noindent
the last two are reserved for @var{class}; they indicate that a
complex-valued result is requested.  Complex arrays are stored in memory as
consecutive pairs of real numbers.  The sizes of integer types are given by
their bit counts.  Both logical and char are typically one byte wide;
however, this is not guaranteed by C++.  If your system is IEEE conformant,
single and double should be 4 bytes and 8 bytes wide, respectively.
"logical" is not allowed for @var{class}.  If the input is a row vector,
the return value is a row vector, otherwise it is a column vector.  If the
bit length of @var{x} is not divisible by that of @var{class}, an error
occurs.

An example of the use of typecast on a little-endian machine is

@example
@group
@var{x} = uint16 ([1, 65535]);
typecast (@var{x}, 'uint8')
@result{} [   0,   1, 255, 255]
@end group
@end example
@seealso{cast, bitunpack, bitpack, swapbytes}
@end deftypefn
bitpack
@c bitpack src/DLD-FUNCTIONS/typecast.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{y} =} bitpack (@var{x}, @var{class})
Return a new array @var{y} resulting from interpreting an array
@var{x} as raw bit patterns for data of the numeric class @var{class}.
@var{class} must be one of the built-in numeric classes:

@example
@group
  "char"
  "int8"
  "int16"
  "int32"
  "int64"
  "uint8"
  "uint16"
  "uint32"
  "uint64"
  "double"
  "single"
@end group
@end example

The number of elements of @var{x} should be divisible by the bit length of
@var{class}.  If it is not, excess bits are discarded.  Bits come in
increasing order of significance, i.e., @code{x(1)} is bit 0, @code{x(2)} is
bit 1, etc.  The result is a row vector if @var{x} is a row vector, otherwise
it is a column vector.
@seealso{bitunpack, typecast}
@end deftypefn
bitunpack
@c bitunpack src/DLD-FUNCTIONS/typecast.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{y} =} bitunpack (@var{x})
Return an array @var{y} corresponding to the raw bit patterns of
@var{x}.  @var{x} must belong to one of the built-in numeric classes:

@example
@group
  "char"
  "int8"
  "int16"
  "int32"
  "int64"
  "uint8"
  "uint16"
  "uint32"
  "uint64"
  "double"
  "single"
@end group
@end example

The result is a row vector if @var{x} is a row vector; otherwise, it is a
column vector.
@seealso{bitpack, typecast}
@end deftypefn
urlwrite
@c urlwrite src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} urlwrite (@var{url}, @var{localfile})
@deftypefnx {Loadable Function} {@var{f} =} urlwrite (@var{url}, @var{localfile})
@deftypefnx {Loadable Function} {[@var{f}, @var{success}] =} urlwrite (@var{url}, @var{localfile})
@deftypefnx {Loadable Function} {[@var{f}, @var{success}, @var{message}] =} urlwrite (@var{url}, @var{localfile})
Download a remote file specified by its @var{url} and save it as
@var{localfile}.  For example:

@example
@group
urlwrite ("ftp://ftp.octave.org/pub/octave/README",
          "README.txt");
@end group
@end example

The full path of the downloaded file is returned in @var{f}.  The
variable @var{success} is 1 if the download was successful,
otherwise it is 0 in which case @var{message} contains an error
message.  If no output argument is specified and an error occurs,
then the error is signaled through Octave's error handling mechanism.

This function uses libcurl.  Curl supports, among others, the HTTP,
FTP and FILE protocols.  Username and password may be specified in
the URL, for example:

@example
@group
urlwrite ("http://username:password@@example.com/file.txt",
          "file.txt");
@end group
@end example

GET and POST requests can be specified by @var{method} and @var{param}.
The parameter @var{method} is either @samp{get} or @samp{post}
and @var{param} is a cell array of parameter and value pairs.
For example:

@example
@group
urlwrite ("http://www.google.com/search", "search.html",
          "get", @{"query", "octave"@});
@end group
@end example
@seealso{urlread}
@end deftypefn
urlread
@c urlread src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{s} =} urlread (@var{url})
@deftypefnx {Loadable Function} {[@var{s}, @var{success}] =} urlread (@var{url})
@deftypefnx {Loadable Function} {[@var{s}, @var{success}, @var{message}] =} urlread (@var{url})
@deftypefnx {Loadable Function} {[@dots{}] =} urlread (@var{url}, @var{method}, @var{param})
Download a remote file specified by its @var{url} and return its content
in string @var{s}.  For example:

@example
s = urlread ("ftp://ftp.octave.org/pub/octave/README");
@end example

The variable @var{success} is 1 if the download was successful,
otherwise it is 0 in which case @var{message} contains an error
message.  If no output argument is specified and an error occurs,
then the error is signaled through Octave's error handling mechanism.

This function uses libcurl.  Curl supports, among others, the HTTP,
FTP and FILE protocols.  Username and password may be specified in the
URL@.  For example:

@example
s = urlread ("http://user:password@@example.com/file.txt");
@end example

GET and POST requests can be specified by @var{method} and @var{param}.
The parameter @var{method} is either @samp{get} or @samp{post}
and @var{param} is a cell array of parameter and value pairs.
For example:

@example
@group
s = urlread ("http://www.google.com/search", "get",
             @{"query", "octave"@});
@end group
@end example
@seealso{urlwrite}
@end deftypefn
__ftp__
@c __ftp__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn  {Loadable Function} {} __ftp__ (@var{handle}, @var{host})
@deftypefnx {Loadable Function} {} __ftp__ (@var{handle}, @var{host}, @var{username}, @var{password})
Undocumented internal function
@end deftypefn
__ftp_pwd__
@c __ftp_pwd__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_pwd__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_cwd__
@c __ftp_cwd__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_cwd__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_dir__
@c __ftp_dir__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_dir__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_ascii__
@c __ftp_ascii__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_ascii__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_binary__
@c __ftp_binary__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_binary__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_close__
@c __ftp_close__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_close__ (@var{handle})
 Undocumented internal function
 @end deftypefn
__ftp_mode__
@c __ftp_mode__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_mode__ (@var{handle})
 Undocumented internal function
 @end deftypefn
__ftp_delete__
@c __ftp_delete__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_delete__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_rmdir__
@c __ftp_rmdir__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_rmdir__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_mkdir__
@c __ftp_mkdir__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_mkdir__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_rename__
@c __ftp_rename__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_rename__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_mput__
@c __ftp_mput__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_mput__ (@var{handle}, @var{files})
Undocumented internal function
@end deftypefn
__ftp_mget__
@c __ftp_mget__ src/DLD-FUNCTIONS/urlwrite.cc
-*- texinfo -*-
@deftypefn {Loadable Function} {} __ftp_mget__ (@var{handle}, @var{files})
Undocumented internal function
@end deftypefn
