### DO NOT EDIT!
###
### This file is generated automatically from Octave source files.
### Edit source files directly and run make to update this file.

__delaunayn__
@c __delaunayn__ libinterp/dldfcn/__delaunayn__.cc
-*- texinfo -*-
@deftypefn  {} {@var{T} =} __delaunayn__ (@var{pts})
@deftypefnx {} {@var{T} =} __delaunayn__ (@var{pts}, @var{options})
Undocumented internal function.
@end deftypefn
__eigs__
@c __eigs__ libinterp/dldfcn/__eigs__.cc
-*- texinfo -*-
@deftypefn  {} {@var{d} =} __eigs__ (@var{A})
@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{k})
@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{k}, @var{sigma})
@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B})
@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B}, @var{k})
@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B}, @var{k}, @var{sigma})
@deftypefnx {} {@var{d} =} __eigs__ (@var{A}, @var{B}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n})
@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B})
@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{k})
@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B}, @var{k})
@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{k}, @var{sigma})
@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma})
@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {} {@var{d} =} __eigs__ (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {} {[@var{V}, @var{d}] =} __eigs__ (@var{A}, @dots{})
@deftypefnx {} {[@var{V}, @var{d}] =} __eigs__ (@var{af}, @var{n}, @dots{})
@deftypefnx {} {[@var{V}, @var{d}, @var{flag}] =} __eigs__ (@var{A}, @dots{})
@deftypefnx {} {[@var{V}, @var{d}, @var{flag}] =} __eigs__ (@var{af}, @var{n}, @dots{})
Undocumented internal function.
@end deftypefn
__fltk_uigetfile__
@c __fltk_uigetfile__ libinterp/dldfcn/__fltk_uigetfile__.cc
-*- texinfo -*-
@deftypefn {} {} __fltk_uigetfile__ (@dots{})
Undocumented internal function.
@end deftypefn
__glpk__
@c __glpk__ libinterp/dldfcn/__glpk__.cc
-*- texinfo -*-
@deftypefn {} {[@var{values}] =} __glpk__ (@var{args})
Undocumented internal function.
@end deftypefn
__fltk_check__
@c __fltk_check__ libinterp/dldfcn/__init_fltk__.cc
-*- texinfo -*-
@deftypefn {} {} __fltk_check__ ()
Undocumented internal function.  Calls Fl::check ()
@end deftypefn
__init_fltk__
@c __init_fltk__ libinterp/dldfcn/__init_fltk__.cc
-*- texinfo -*-
@deftypefn {} {} __init_fltk__ ()
Undocumented internal function.
@end deftypefn
__init_gnuplot__
@c __init_gnuplot__ libinterp/dldfcn/__init_gnuplot__.cc
-*- texinfo -*-
@deftypefn {} {} __init_gnuplot__ ()
Undocumented internal function.
@end deftypefn
__have_gnuplot__
@c __have_gnuplot__ libinterp/dldfcn/__init_gnuplot__.cc
-*- texinfo -*-
@deftypefn {} {@var{gnuplot_available} =} __have_gnuplot__ ()
Undocumented internal function.
@end deftypefn
__ode15__
@c __ode15__ libinterp/dldfcn/__ode15__.cc
-*- texinfo -*-
@deftypefn {} {@var{t}, @var{y} =} __ode15__ (@var{fun}, @var{tspan}, @var{y0}, @var{yp0}, @var{options})
Undocumented internal function.
@end deftypefn
__voronoi__
@c __voronoi__ libinterp/dldfcn/__voronoi__.cc
-*- texinfo -*-
@deftypefn  {} {@var{C}, @var{F} =} __voronoi__ (@var{caller}, @var{pts})
@deftypefnx {} {@var{C}, @var{F} =} __voronoi__ (@var{caller}, @var{pts}, @var{options})
@deftypefnx {} {@var{C}, @var{F}, @var{Inf_Pts} =} __voronoi__ (@dots{})
Undocumented internal function.
@end deftypefn
amd
@c amd libinterp/dldfcn/amd.cc
-*- texinfo -*-
@deftypefn  {} {@var{p} =} amd (@var{S})
@deftypefnx {} {@var{p} =} amd (@var{S}, @var{opts})

Return the approximate minimum degree permutation of a matrix.

This is a 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 the default value is 10.0

@item @var{opts}.aggressive
If this value is a nonzero 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
(see @url{http://faculty.cse.tamu.edu/davis/suitesparse.html}).
@seealso{symamd, colamd}
@end deftypefn
audiodevinfo
@c audiodevinfo libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{devinfo} =} audiodevinfo ()

@deftypefnx {} {@var{devs} =} audiodevinfo (@var{io})
@deftypefnx {} {@var{name} =} audiodevinfo (@var{io}, @var{id})
@deftypefnx {} {@var{id} =} audiodevinfo (@var{io}, @var{name})
@deftypefnx {} {@var{id} =} audiodevinfo (@var{io}, @var{rate}, @var{bits}, @var{chans})

@deftypefnx {} {@var{supports} =} audiodevinfo (@var{io}, @var{id}, @var{rate}, @var{bits}, @var{chans})

Return a structure describing the available audio input and output devices.

The @var{devinfo} structure has two fields @qcode{"input"} and
@qcode{"output"}.  The value of each field is a structure array with
fields @qcode{"Name"}, @nospell{"DriverVersion"} and @qcode{"ID"}
describing an audio device.

If the optional argument @var{io} is 1, return information about input
devices only.  If it is 0, return information about output devices
only.  If @var{io} is the only argument supplied, return the number of
input or output devices available.

If the optional argument @var{id} is provided, return information about
the corresponding device.

If the optional argument @var{name} is provided, return the id of the
named device.

Given a sampling rate, bits per sample, and number of channels for an input
or output device, return the ID of the first device that supports playback
or recording using the specified parameters.

If also given a device ID, return true if the device supports playback or
recording using those parameters.
@end deftypefn
__recorder_audiorecorder__
@c __recorder_audiorecorder__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn  {} {@var{recorder} =} __recorder_audiorecorder__ (@var{fs}, @var{nbits}, @var{channels})
@deftypefnx {} {@var{recorder} =} __recorder_audiorecorder__ (@var{fs}, @var{nbits}, @var{channels}, @var{id})
@deftypefnx {} {@var{recorder} =} __recorder_audiorecorder__ (@var{fcn}, @dots{})
Undocumented internal function.
@end deftypefn
__recorder_getaudiodata__
@c __recorder_getaudiodata__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{data} =} __recorder_getaudiodata__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_channels__
@c __recorder_get_channels__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{n} =} __recorder_get_channels__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_fs__
@c __recorder_get_fs__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{fs} =} __recorder_get_fs__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_id__
@c __recorder_get_id__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{id} =} __recorder_get_id__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_nbits__
@c __recorder_get_nbits__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{nbits} =} __recorder_get_nbits__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_sample_number__
@c __recorder_get_sample_number__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{n} =} __recorder_get_sample_number__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_tag__
@c __recorder_get_tag__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{tag} =} __recorder_get_tag__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_total_samples__
@c __recorder_get_total_samples__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{n} =} __recorder_get_total_samples__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_userdata__
@c __recorder_get_userdata__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{data} =} __recorder_get_userdata__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_isrecording__
@c __recorder_isrecording__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __recorder_isrecording__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_pause__
@c __recorder_pause__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __recorder_pause__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_recordblocking__
@c __recorder_recordblocking__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __recorder_recordblocking__ (@var{recorder}, @var{seconds})
Undocumented internal function.
@end deftypefn
__recorder_record__
@c __recorder_record__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn  {} {} __recorder_record__ (@var{recorder})
@deftypefnx {} {} __recorder_record__ (@var{recorder}, @var{seconds})
Undocumented internal function.
@end deftypefn
__recorder_resume__
@c __recorder_resume__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __recorder_resume__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_set_fs__
@c __recorder_set_fs__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __recorder_set_fs__ (@var{recorder}, @var{fs})
Undocumented internal function.
@end deftypefn
__recorder_set_tag__
@c __recorder_set_tag__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __recorder_set_tag__ (@var{recorder}, @var{tag})
Undocumented internal function.
@end deftypefn
__recorder_set_userdata__
@c __recorder_set_userdata__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __recorder_set_userdata__ (@var{recorder}, @var{data})
Undocumented internal function.
@end deftypefn
__recorder_stop__
@c __recorder_stop__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __recorder_stop__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__player_audioplayer__
@c __player_audioplayer__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn  {} {@var{player} =} __player_audioplayer__ (@var{y}, @var{fs})
@deftypefnx {} {@var{player} =} __player_audioplayer__ (@var{y}, @var{fs}, @var{nbits})
@deftypefnx {} {@var{player} =} __player_audioplayer__ (@var{y}, @var{fs}, @var{nbits}, @var{id})
Undocumented internal function.
@end deftypefn
__player_get_channels__
@c __player_get_channels__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{n} =} __player_get_channels__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_get_fs__
@c __player_get_fs__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{fs} =} __player_get_fs__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_get_id__
@c __player_get_id__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{id} =} __player_get_id__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_get_nbits__
@c __player_get_nbits__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{nbits} =} __player_get_nbits__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_get_sample_number__
@c __player_get_sample_number__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{n} =} __player_get_sample_number__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_get_tag__
@c __player_get_tag__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{tag} =} __player_get_tag__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_get_total_samples__
@c __player_get_total_samples__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{n} =} __player_get_total_samples__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_get_userdata__
@c __player_get_userdata__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {@var{data} =} __player_get_userdata__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_isplaying__
@c __player_isplaying__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __player_isplaying__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_pause__
@c __player_pause__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __player_pause__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_playblocking__
@c __player_playblocking__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn  {} {} __player_playblocking__ (@var{player})
@deftypefnx {} {} __player_playblocking__ (@var{player}, @var{start})
@deftypefnx {} {} __player_playblocking__ (@var{player}, [@var{start}, @var{end}])
Undocumented internal function.
@end deftypefn
__player_play__
@c __player_play__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn  {} {} __player_play__ (@var{player})
@deftypefnx {} {} __player_play__ (@var{player}, @var{start})
@deftypefnx {} {} __player_play__ (@var{player}, [@var{start}, @var{end}])
Undocumented internal function.
@end deftypefn
__player_resume__
@c __player_resume__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __player_resume__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_set_fs__
@c __player_set_fs__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __player_set_fs__ (@var{player}, @var{fs})
Undocumented internal function.
@end deftypefn
__player_set_tag__
@c __player_set_tag__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __player_set_tag__ (@var{player}, @var{tag})
Undocumented internal function.
@end deftypefn
__player_set_userdata__
@c __player_set_userdata__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __player_set_userdata__ (@var{player}, @var{data})
Undocumented internal function.
@end deftypefn
__player_stop__
@c __player_stop__ libinterp/dldfcn/audiodevinfo.cc
-*- texinfo -*-
@deftypefn {} {} __player_stop__ (@var{player})
Undocumented internal function.
@end deftypefn
audioread
@c audioread libinterp/dldfcn/audioread.cc
-*- texinfo -*-
@deftypefn  {} {[@var{y}, @var{fs}] =} audioread (@var{filename})
@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples})

@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{datatype})
@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples}, @var{datatype})
Read the audio file @var{filename} and return the audio data @var{y} and
sampling rate @var{fs}.

The audio data is stored as matrix with rows corresponding to audio frames
and columns corresponding to channels.

The optional two-element vector argument @var{samples} specifies starting
and ending frames.

The optional argument @var{datatype} specifies the datatype to return.
If it is @qcode{"native"}, then the type of data depends on how the data
is stored in the audio file.
@seealso{audiowrite, audioformats, audioinfo}
@end deftypefn
audiowrite
@c audiowrite libinterp/dldfcn/audioread.cc
-*- texinfo -*-
@deftypefn  {} {} audiowrite (@var{filename}, @var{y}, @var{fs})
@deftypefnx {} {} audiowrite (@var{filename}, @var{y}, @var{fs}, @var{name}, @var{value}, @dots{})

Write audio data from the matrix @var{y} to @var{filename} at sampling rate
@var{fs} with the file format determined by the file extension.

Additional name/value argument pairs may be used to specify the
following options:

@table @samp
@item BitsPerSample
Number of bits per sample.  Valid values are 8, 16, 24, and 32.  Default is
16.

@item BitRate
Valid argument name, but ignored.  Left for compatibility with @sc{matlab}.

@item Quality
Quality setting for the Ogg Vorbis compressor.  Values can range between 0
and 100 with 100 being the highest quality setting.  Default is 75.

@item Title
Title for the audio file.

@item Artist
Artist name.

@item Comment
Comment.
@end table
@seealso{audioread, audioformats, audioinfo}
@end deftypefn
audioinfo
@c audioinfo libinterp/dldfcn/audioread.cc
-*- texinfo -*-
@deftypefn {} {@var{info} =} audioinfo (@var{filename})
Return information about an audio file specified by @var{filename}.

The output @var{info} is a structure containing the following fields:

@table @samp
@item Filename
Name of the audio file.

@item CompressionMethod
Audio compression method.  Unused, only present for compatibility with
@sc{matlab}.

@item NumChannels
Number of audio channels.

@item SampleRate
Sample rate of the audio, in Hertz.

@item TotalSamples
Number of samples in the file.

@item Duration
Duration of the audio, in seconds.

@item BitsPerSample
Number of bits per sample.

@item BitRate
Audio bit rate.  Unused, only present for compatibility with @sc{matlab}.

@item Title
@qcode{"Title"} audio metadata value as a string, or empty if not present.

@item Artist
@qcode{"Artist"} audio metadata value as a string, or empty if not present.

@item Comment
@qcode{"Comment"} audio metadata value as a string, or empty if not present.
@end table
@seealso{audioread, audiowrite}
@end deftypefn
audioformats
@c audioformats libinterp/dldfcn/audioread.cc
-*- texinfo -*-
@deftypefn  {} {} audioformats ()
@deftypefnx {} {} audioformats (@var{format})
Display information about all supported audio formats.

If the optional argument @var{format} is given, then display only formats
with names that start with @var{format}.
@seealso{audioread, audiowrite}
@end deftypefn
ccolamd
@c ccolamd libinterp/dldfcn/ccolamd.cc
-*- texinfo -*-
@deftypefn  {} {@var{p} =} ccolamd (@var{S})
@deftypefnx {} {@var{p} =} ccolamd (@var{S}, @var{knobs})
@deftypefnx {} {@var{p} =} ccolamd (@var{S}, @var{knobs}, @var{cmember})
@deftypefnx {} {[@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 @nospell{S. Larimore, T. Davis} and
@nospell{S. Rajamanickam} in collaboration with @nospell{J. Bilbert and E. Ng}.
Supported by the National Science Foundation
@nospell{(DMS-9504974, DMS-9803599, CCR-0203270)}, and a grant from
@nospell{Sandia} National Lab.
See @url{http://faculty.cse.tamu.edu/davis/suitesparse.html} for ccolamd,
csymamd, amd, colamd, symamd, and other related orderings.
@seealso{colamd, csymamd}
@end deftypefn
csymamd
@c csymamd libinterp/dldfcn/ccolamd.cc
-*- texinfo -*-
@deftypefn  {} {@var{p} =} csymamd (@var{S})
@deftypefnx {} {@var{p} =} csymamd (@var{S}, @var{knobs})
@deftypefnx {} {@var{p} =} csymamd (@var{S}, @var{knobs}, @var{cmember})
@deftypefnx {} {[@var{p}, @var{stats}] =} csymamd (@dots{})

For a symmetric positive definite matrix @var{S}, return 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]}.  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 @nospell{S. Larimore, T. Davis} and
@nospell{S. Rajamanickam} in collaboration with @nospell{J. Bilbert and E. Ng}.
Supported by the National Science Foundation
@nospell{(DMS-9504974, DMS-9803599, CCR-0203270)}, and a grant from
@nospell{Sandia} National Lab.
See @url{http://faculty.cse.tamu.edu/davis/suitesparse.html} for ccolamd,
colamd, csymamd, amd, colamd, symamd, and other related orderings.
@seealso{symamd, ccolamd}
@end deftypefn
chol
@c chol libinterp/dldfcn/chol.cc
-*- texinfo -*-
@deftypefn  {} {@var{R} =} chol (@var{A})
@deftypefnx {} {[@var{R}, @var{p}] =} chol (@var{A})
@deftypefnx {} {[@var{R}, @var{p}, @var{Q}] =} chol (@var{A})
@deftypefnx {} {[@var{R}, @var{p}, @var{Q}] =} chol (@var{A}, "vector")
@deftypefnx {} {[@var{L}, @dots{}] =} chol (@dots{}, "lower")
@deftypefnx {} {[@var{R}, @dots{}] =} chol (@dots{}, "upper")
@cindex Cholesky factorization
Compute the upper Cholesky@tie{}factor, @var{R}, of the real symmetric
or complex Hermitian positive definite matrix @var{A}.

The upper Cholesky@tie{}factor @var{R} is computed by using the upper
triangular part of matrix @var{A} and is defined by
@tex
$ R^T R = A $.
@end tex
@ifnottex

@example
@var{R}' * @var{R} = @var{A}.
@end example

@end ifnottex

Calling @code{chol} using the optional @qcode{"upper"} flag has the
same behavior.  In contrast, using the optional @qcode{"lower"} flag,
@code{chol} returns the lower triangular factorization, computed by using
the lower triangular part of matrix @var{A}, such that
@tex
$ L L^T = A $.
@end tex
@ifnottex

@example
@var{L} * @var{L}' = @var{A}.
@end example

@end ifnottex

Called with one output argument @code{chol} fails if matrix @var{A} is
not positive definite.  Note that if matrix @var{A} is not real symmetric
or complex Hermitian then the lower triangular part is considered to be
the (complex conjugate) transpose of the upper triangular part, or vice
versa, given the @qcode{"lower"} flag.

Called with two or more output arguments @var{p} flags whether the matrix
@var{A} was positive definite and @code{chol} does not fail.  A zero value
of @var{p} indicates that matrix @var{A} is positive definite and @var{R}
gives the factorization.  Otherwise, @var{p} will have a positive value.

If called with three output arguments matrix @var{A} must be sparse and
a sparsity preserving row/column permutation is applied to matrix @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 optional flag @qcode{"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

In general the lower triangular factorization is significantly faster for
sparse matrices.
@seealso{hess, lu, qr, qz, schur, svd, ichol, cholinv, chol2inv, cholupdate, cholinsert, choldelete, cholshift}
@end deftypefn
cholinv
@c cholinv libinterp/dldfcn/chol.cc
-*- texinfo -*-
@deftypefn {} {} cholinv (@var{A})
Compute the inverse of the symmetric positive definite matrix @var{A} using
the Cholesky@tie{}factorization.
@seealso{chol, chol2inv, inv}
@end deftypefn
chol2inv
@c chol2inv libinterp/dldfcn/chol.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/dldfcn/chol.cc
-*- texinfo -*-
@deftypefn {} {[@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 @qcode{"+"}

@item
@var{R1}'*@var{R1} = @var{R}'*@var{R} - @var{u}*@var{u}'
if @var{op} is @qcode{"-"}
@end itemize

If @var{op} is @qcode{"-"}, @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, cholinsert, choldelete, cholshift}
@end deftypefn
cholinsert
@c cholinsert libinterp/dldfcn/chol.cc
-*- texinfo -*-
@deftypefn  {} {@var{R1} =} cholinsert (@var{R}, @var{j}, @var{u})
@deftypefnx {} {[@var{R1}, @var{info}] =} cholinsert (@var{R}, @var{j}, @var{u})
Update a Cholesky factorization given a row or column to insert in the
original factored matrix.

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, cholshift}
@end deftypefn
choldelete
@c choldelete libinterp/dldfcn/chol.cc
-*- texinfo -*-
@deftypefn {} {@var{R1} =} choldelete (@var{R}, @var{j})
Update a Cholesky factorization given a row or column to delete from the
original factored matrix.

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, cholshift}
@end deftypefn
cholshift
@c cholshift libinterp/dldfcn/chol.cc
-*- texinfo -*-
@deftypefn {} {@var{R1} =} cholshift (@var{R}, @var{i}, @var{j})
Update a Cholesky factorization given a range of columns to shift in the
original factored matrix.

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, cholupdate, cholinsert, choldelete}
@end deftypefn
colamd
@c colamd libinterp/dldfcn/colamd.cc
-*- texinfo -*-
@deftypefn  {} {@var{p} =} colamd (@var{S})
@deftypefnx {} {@var{p} =} colamd (@var{S}, @var{knobs})
@deftypefnx {} {[@var{p}, @var{stats}] =} colamd (@var{S})
@deftypefnx {} {[@var{p}, @var{stats}] =} colamd (@var{S}, @var{knobs})

Compute the 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 @sc{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 @nospell{Stefan I. Larimore} and
@nospell{Timothy A. Davis}.  The algorithm was developed in collaboration with
@nospell{John Gilbert}, Xerox PARC, and @nospell{Esmond Ng}, Oak Ridge National
Laboratory.  (see @url{http://faculty.cse.tamu.edu/davis/suitesparse.html})
@seealso{colperm, symamd, ccolamd}
@end deftypefn
symamd
@c symamd libinterp/dldfcn/colamd.cc
-*- texinfo -*-
@deftypefn  {} {@var{p} =} symamd (@var{S})
@deftypefnx {} {@var{p} =} symamd (@var{S}, @var{knobs})
@deftypefnx {} {[@var{p}, @var{stats}] =} symamd (@var{S})
@deftypefnx {} {[@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, @var{stats} and @var{knobs} are
printed.  The default is @code{@var{knobs} = [10 0]}.  Note that
@var{knobs} differs from earlier versions of @code{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 @nospell{Stefan I. Larimore} and
@nospell{Timothy A. Davis}.  The algorithm was developed in collaboration with
@nospell{John Gilbert}, Xerox PARC, and @nospell{Esmond Ng}, Oak Ridge National
Laboratory.  (see @url{http://faculty.cse.tamu.edu/davis/suitesparse.html})
@seealso{colperm, colamd}
@end deftypefn
etree
@c etree libinterp/dldfcn/colamd.cc
-*- texinfo -*-
@deftypefn  {} {@var{p} =} etree (@var{S})
@deftypefnx {} {@var{p} =} etree (@var{S}, @var{typ})
@deftypefnx {} {[@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
@qcode{"sym"} or @qcode{"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
convhulln
@c convhulln libinterp/dldfcn/convhulln.cc
-*- texinfo -*-
@deftypefn  {} {@var{h} =} convhulln (@var{pts})
@deftypefnx {} {@var{h} =} convhulln (@var{pts}, @var{options})
@deftypefnx {} {[@var{h}, @var{v}] =} convhulln (@dots{})
Compute the convex hull of the set of points @var{pts}.

@var{pts} 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
dmperm
@c dmperm libinterp/dldfcn/dmperm.cc
-*- texinfo -*-
@deftypefn  {} {@var{p} =} dmperm (@var{S})
@deftypefnx {} {[@var{p}, @var{q}, @var{r}, @var{S}] =} dmperm (@var{S})

@cindex @nospell{Dulmage-Mendelsohn} decomposition
Perform a @nospell{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: @nospell{A. Pothen & C.-J. Fan.}
@cite{Computing the Block Triangular Form of a Sparse Matrix}.
@nospell{ACM} Trans. Math. Software, 16(4):303--324, 1990.
@seealso{colamd, ccolamd}
@end deftypefn
sprank
@c sprank libinterp/dldfcn/dmperm.cc
-*- texinfo -*-
@deftypefn {} {@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 @nospell{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
fftw
@c fftw libinterp/dldfcn/fftw.cc
-*- texinfo -*-
@deftypefn  {} {@var{method} =} fftw ("planner")
@deftypefnx {} {} fftw ("planner", @var{method})
@deftypefnx {} {@var{wisdom} =} fftw ("dwisdom")
@deftypefnx {} {} fftw ("dwisdom", @var{wisdom})
@deftypefnx {} {} fftw ("threads", @var{nthreads})
@deftypefnx {} {@var{nthreads} =} fftw ("threads")

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
re-imported as follows

@example
fftw ("dwisdom", @var{wisdom})
@end example

If @var{wisdom} is an empty string, 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 @qcode{"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 @qcode{"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 @qcode{"patient"}
Similar to @qcode{"measure"}, but a wider range of algorithms is
considered.

@item @qcode{"exhaustive"}
Like @qcode{"measure"}, but all possible algorithms that may be used to
treat the transform are considered.

@item @qcode{"hybrid"}
As run-time measurement of the algorithm can be expensive, this is a
compromise where @qcode{"measure"} is used for transforms up to the size
of 8192 and beyond that the @qcode{"estimate"} method is used.
@end table

The default method is @qcode{"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.

The number of threads used for computing the plans and executing the
transforms can be set with

@example
fftw ("threads", @var{NTHREADS})
@end example

Note that octave must be compiled with multi-threaded @sc{fftw} support for
this feature.  The number of processors available to the current process is
used per default.

@seealso{fft, ifft, fft2, ifft2, fftn, ifftn}
@end deftypefn
gzip
@c gzip libinterp/dldfcn/gzip.cc
-*- texinfo -*-
@deftypefn  {} {@var{filelist} =} gzip (@var{files})
@deftypefnx {} {@var{filelist} =} gzip (@var{files}, @var{dir})
Compress the list of files and directories specified in @var{files}.

@var{files} is a character array or cell array of strings.  Shell wildcards
in the filename such as @samp{*} or @samp{?} are accepted and expanded.
Each file is compressed separately and a new file with a @file{".gz"}
extension is created.  The original files are not modified, but existing
compressed files will be silently overwritten.  If a directory is
specified then @code{gzip} recursively compresses all files in the
directory.

If @var{dir} is defined the compressed files are placed in this directory,
rather than the original directory where the uncompressed file resides.
Note that this does not replicate a directory tree in @var{dir} which may
lead to files overwriting each other if there are multiple files with the
same name.

If @var{dir} does not exist it is created.

The optional output @var{filelist} is a list of the compressed files.
@seealso{gunzip, unpack, bzip2, zip, tar}
@end deftypefn
bzip2
@c bzip2 libinterp/dldfcn/gzip.cc
-*- texinfo -*-
@deftypefn  {} {@var{filelist} =} bzip2 (@var{files})
@deftypefnx {} {@var{filelist} =} bzip2 (@var{files}, @var{dir})
Compress the list of files specified in @var{files}.

@var{files} is a character array or cell array of strings.  Shell wildcards
in the filename such as @samp{*} or @samp{?} are accepted and expanded.
Each file is compressed separately and a new file with a @file{".bz2"}
extension is created.  The original files are not modified, but existing
compressed files will be silently overwritten.

If @var{dir} is defined the compressed files are placed in this directory,
rather than the original directory where the uncompressed file resides.
Note that this does not replicate a directory tree in @var{dir} which may
lead to files overwriting each other if there are multiple files with the
same name.

If @var{dir} does not exist it is created.

The optional output @var{filelist} is a list of the compressed files.
@seealso{bunzip2, unpack, gzip, zip, tar}
@end deftypefn
qr
@c qr libinterp/dldfcn/qr.cc
-*- texinfo -*-
@deftypefn  {} {[@var{Q}, @var{R}] =} qr (@var{A})
@deftypefnx {} {[@var{Q}, @var{R}, @var{P}] =} qr (@var{A})  # non-sparse A
@deftypefnx {} {@var{X} =} qr (@var{A})  # non-sparse A
@deftypefnx {} {@var{R} =} qr (@var{A})  # sparse A
@deftypefnx {} {[@var{C}, @var{R}] =} qr (@var{A}, @var{B})
@deftypefnx {} {[@dots{}] =} qr (@dots{}, 0)
@deftypefnx {} {[@dots{}] =} qr (@dots{}, "vector")
@deftypefnx {} {[@dots{}] =} qr (@dots{}, "matrix")
@cindex QR factorization
Compute the QR@tie{}factorization of @var{A}, using standard @sc{lapack}
subroutines.

The QR@tie{}factorization is
@tex
$QR = A$ where $Q$ is an orthogonal matrix and $R$ is upper triangular.
@end tex
@ifnottex

@example
@var{Q} * @var{R} = @var{A}
@end example

@noindent
where @var{Q} is an orthogonal matrix and @var{R} is upper triangular.
@end ifnottex

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

@noindent
which multiplied together return the original matrix

@example
@group
@var{Q} * @var{R}
  @result{}
     1.0000   2.0000
     3.0000   4.0000
@end group
@end example

If just a single return value is requested then it is either @var{R}, if
@var{A} is sparse, or @var{X}, such that @code{@var{R} = triu (@var{X})} if
@var{A} is full.  (Note: unlike most commands, the single return value is not
the first return value when multiple values are requested.)

If the matrix @var{A} is full, and a third output @var{P} is requested, then
@code{qr} calculates the permuted QR@tie{}factorization
@tex
$QR = AP$ where $Q$ is an orthogonal matrix, $R$ is upper triangular, and $P$
is a permutation matrix.
@end tex
@ifnottex

@example
@var{Q} * @var{R} = @var{A} * @var{P}
@end example

@noindent
where @var{Q} is an orthogonal matrix, @var{R} is upper triangular, and
@var{P} is a permutation matrix.
@end ifnottex

The permuted QR@tie{}factorization has the additional property that the
diagonal entries of @var{R} are ordered by decreasing magnitude.  In other
words, @code{abs (diag (@var{R}))} will be ordered from largest to smallest.

For example, given the matrix @code{@var{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

If the input matrix @var{A} is sparse then the sparse QR@tie{}factorization
is computed using @sc{CSparse}.  Because the matrix @var{Q} is, in general, a
full matrix, it is recommended to request only one return value @var{R}.  In
that case, the computation avoids the construction of @var{Q} and returns
@var{R} such that @code{@var{R} = chol (@var{A}' * @var{A})}.

If an additional matrix @var{B} is supplied and two return values are
requested, 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})
@var{x} = @var{R} \ @var{C}
@end group
@end example

If the final argument is the string @qcode{"vector"} then @var{P} is a
permutation vector (of the columns of @var{A}) instead of a permutation matrix.
In this case, the defining relationship is

@example
@var{Q} * @var{R} = @var{A}(:, @var{P})
@end example

The default, however, is to return a permutation matrix and this may be
explicitly specified by using a final argument of @qcode{"matrix"}.

If the final argument is the scalar 0 an @qcode{"economy"} factorization is
returned.  When the original matrix @var{A} has size MxN and M > N then the
@qcode{"economy"} factorization will calculate just N rows in @var{R} and N
columns in @var{Q} and omit the zeros in @var{R}.  If M @leq{} N there is no
difference between the economy and standard factorizations.  When calculating
an @qcode{"economy"} factorization the output @var{P} is always a vector
rather than a matrix.

Background: The 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
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 permuted QR@tie{}factorization
@code{[@var{Q}, @var{R}, @var{P}] = qr (@var{A})} allows the construction of an
orthogonal basis of @code{span (A)}.

@seealso{chol, hess, lu, qz, schur, svd, qrupdate, qrinsert, qrdelete, qrshift}
@end deftypefn
qrupdate
@c qrupdate libinterp/dldfcn/qr.cc
-*- texinfo -*-
@deftypefn {} {[@var{Q1}, @var{R1}] =} qrupdate (@var{Q}, @var{R}, @var{u}, @var{v})
Update a QR factorization given update vectors or matrices.

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, qrshift}
@end deftypefn
qrinsert
@c qrinsert libinterp/dldfcn/qr.cc
-*- texinfo -*-
@deftypefn {} {[@var{Q1}, @var{R1}] =} qrinsert (@var{Q}, @var{R}, @var{j}, @var{x}, @var{orient})
Update a QR factorization given a row or column to insert in the original
factored matrix.


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 @qcode{"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 @qcode{"row"}).

The default value of @var{orient} is @qcode{"col"}.  If @var{orient} is
@qcode{"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 @qcode{"col"}, the QR@tie{}factorization supplied may
be either full (Q is square) or economized (R is square).

If @var{orient} is @qcode{"row"}, full factorization is needed.
@seealso{qr, qrupdate, qrdelete, qrshift}
@end deftypefn
qrdelete
@c qrdelete libinterp/dldfcn/qr.cc
-*- texinfo -*-
@deftypefn {} {[@var{Q1}, @var{R1}] =} qrdelete (@var{Q}, @var{R}, @var{j}, @var{orient})
Update a QR factorization given a row or column to delete from the original
factored matrix.

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), U, A(:,j:n)]},
where @var{u} is a column vector to be inserted into @var{A}
(if @var{orient} is @qcode{"col"}),
or the QR@tie{}factorization of @w{[A(1:j-1,:);X;A(:,j:n)]},
where @var{x} is a row @var{orient} is @qcode{"row"}).
The default value of @var{orient} is @qcode{"col"}.

If @var{orient} is @qcode{"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 @qcode{"col"}, the QR@tie{}factorization supplied may
be either full (Q is square) or economized (R is square).

If @var{orient} is @qcode{"row"}, full factorization is needed.
@seealso{qr, qrupdate, qrinsert, qrshift}
@end deftypefn
qrshift
@c qrshift libinterp/dldfcn/qr.cc
-*- texinfo -*-
@deftypefn {} {[@var{Q1}, @var{R1}] =} qrshift (@var{Q}, @var{R}, @var{i}, @var{j})
Update a QR factorization given a range of columns to shift in the original
factored matrix.

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, qrupdate, qrinsert, qrdelete}
@end deftypefn
symbfact
@c symbfact libinterp/dldfcn/symbfact.cc
-*- texinfo -*-
@deftypefn  {} {[@var{count}, @var{h}, @var{parent}, @var{post}, @var{R}] =} symbfact (@var{S})
@deftypefnx {} {[@dots{}] =} symbfact (@var{S}, @var{typ})
@deftypefnx {} {[@dots{}] =} symbfact (@var{S}, @var{typ}, @var{mode})

Perform a symbolic factorization analysis of the sparse matrix @var{S}.

The input variables are

@table @var
@item S
@var{S} is a real or complex sparse matrix.

@item typ
Is the type of the factorization and can be one of

@table @asis
@item @qcode{"sym"} (default)
Factorize @var{S}.  Assumes @var{S} is symmetric and uses the upper
triangular portion of the matrix.

@item @qcode{"col"}
Factorize @tcode{@var{S}' * @var{S}}.

@item @qcode{"row"}
Factorize @tcode{@var{S} * @var{S}'}.

@item @qcode{"lo"}
Factorize @tcode{@var{S}'}.  Assumes @var{S} is symmetric and uses the lower
triangular portion of the matrix.
@end table

@item mode
When @var{mode} is unspecified return the Cholesky@tie{}factorization for
@var{R}.  If @var{mode} is @qcode{"lower"} or @qcode{"L"} then return
the conjugate transpose @tcode{@var{R}'} which is a lower triangular factor.
The conjugate transpose version is faster and uses less memory, but still
returns the same values for all other outputs: @var{count}, @var{h},
@var{parent}, and @var{post}.
@end table

The output variables are:

@table @var
@item count
The row counts of the Cholesky@tie{}factorization as determined by
@var{typ}.  The computational difficulty of performing the true
factorization using @code{chol} is @code{sum (@var{count} .^ 2)}.

@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@tie{}factorization as determined by @var{typ}.
@end table
@seealso{chol, etree, treelayout}
@end deftypefn
symrcm
@c symrcm libinterp/dldfcn/symrcm.cc
-*- texinfo -*-
@deftypefn {} {@var{p} =} symrcm (@var{S})
Return the symmetric reverse @nospell{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

@nospell{E. Cuthill, J. McKee}.
@cite{Reducing the Bandwidth of Sparse Symmetric Matrices}.
Proceedings of the 24th @nospell{ACM} National Conference,
157--172 1969, Brandon Press, New Jersey.

@nospell{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
daspk_options
@c daspk_options libinterp/corefcn/DASPK-opts.cc
-*- texinfo -*-
@deftypefn  {} {} daspk_options ()
@deftypefnx {} {val =} daspk_options (@var{opt})
@deftypefnx {} {} 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 option @var{opt}.

When called with two arguments, @code{daspk_options} sets the option
@var{opt} to value @var{val}.

Options include

@table @asis
@item @qcode{"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 @qcode{"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 @qcode{"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
@qcode{"algebraic variables"} option to declare which variables in the
problem are algebraic.

@item @qcode{"use initial condition heuristics"}
Set to a nonzero value to use the initial condition heuristics options
described below.

@item @qcode{"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 @qcode{"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 @qcode{"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 @qcode{"print initial condition info"}
Set this option to a nonzero value to display detailed information
about the initial condition calculation (default is 0).

@item @qcode{"exclude algebraic variables from error test"}
Set to a nonzero value to exclude algebraic variables from the error
test.  You must also set the @qcode{"algebraic variables"} option to
declare which variables in the problem are algebraic (default is 0).

@item @qcode{"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
@qcode{"compute consistent initial condition"} and
@qcode{"exclude algebraic variables from error test"} options.

@item @qcode{"enforce inequality constraints"}
Set to one of the following values to enforce the inequality
constraints specified by the @qcode{"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 @qcode{"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
@qcode{"enforce inequality constraints"} option is nonzero.

@item @qcode{"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 @qcode{"maximum order"}
Restrict the maximum order of the solution method.  This option must
be between 1 and 5, inclusive (default is 5).

@item @qcode{"maximum step size"}
Setting the maximum stepsize will avoid passing over very large
regions (default is not specified).
@end table
@end deftypefn
dasrt_options
@c dasrt_options libinterp/corefcn/DASRT-opts.cc
-*- texinfo -*-
@deftypefn  {} {} dasrt_options ()
@deftypefnx {} {val =} dasrt_options (@var{opt})
@deftypefnx {} {} 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 option @var{opt}.

When called with two arguments, @code{dasrt_options} sets the option
@var{opt} to value @var{val}.

Options include

@table @asis
@item @qcode{"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 @qcode{"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 @qcode{"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 @qcode{"maximum order"}
Restrict the maximum order of the solution method.  This option must
be between 1 and 5, inclusive.

@item @qcode{"maximum step size"}
Setting the maximum stepsize will avoid passing over very large
regions.

@item @qcode{"step limit"}
Maximum number of integration steps to attempt on a single call to the
underlying Fortran code.
@end table
@end deftypefn
dassl_options
@c dassl_options libinterp/corefcn/DASSL-opts.cc
-*- texinfo -*-
@deftypefn  {} {} dassl_options ()
@deftypefnx {} {val =} dassl_options (@var{opt})
@deftypefnx {} {} 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 option @var{opt}.

When called with two arguments, @code{dassl_options} sets the option
@var{opt} to value @var{val}.

Options include

@table @asis
@item @qcode{"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 @qcode{"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 @qcode{"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 @qcode{"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 @qcode{"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 @qcode{"maximum order"}
Restrict the maximum order of the solution method.  This option must
be between 1 and 5, inclusive.

@item @qcode{"maximum step size"}
Setting the maximum stepsize will avoid passing over very large
regions  (default is not specified).

@item @qcode{"step limit"}
Maximum number of integration steps to attempt on a single call to the
underlying Fortran code.
@end table
@end deftypefn
lsode_options
@c lsode_options libinterp/corefcn/LSODE-opts.cc
-*- texinfo -*-
@deftypefn  {} {} lsode_options ()
@deftypefnx {} {val =} lsode_options (@var{opt})
@deftypefnx {} {} 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 option @var{opt}.

When called with two arguments, @code{lsode_options} sets the option
@var{opt} to value @var{val}.

Options include

@table @asis
@item @qcode{"absolute tolerance"}
Absolute tolerance.  May be either vector or scalar.  If a vector, it
must match the dimension of the state vector.

@item @qcode{"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 @qcode{"integration method"}
A string specifying the method of integration to use to solve the ODE
system.  Valid values are

@table @asis
@item  @qcode{"adams"}
@itemx @qcode{"non-stiff"}
No Jacobian used (even if it is available).

@item  @qcode{"bdf"}
@itemx @qcode{"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 @qcode{"initial step size"}
The step size to be attempted on the first step (default is determined
automatically).

@item @qcode{"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 @qcode{"maximum step size"}
Setting the maximum stepsize will avoid passing over very large
regions  (default is not specified).

@item @qcode{"minimum step size"}
The minimum absolute step size allowed (default is 0).

@item @qcode{"step limit"}
Maximum number of steps allowed (default is 100000).
@end table
@end deftypefn
quad_options
@c quad_options libinterp/corefcn/Quad-opts.cc
-*- texinfo -*-
@deftypefn  {} {} quad_options ()
@deftypefnx {} {val =} quad_options (@var{opt})
@deftypefnx {} {} 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 option @var{opt}.

When called with two arguments, @code{quad_options} sets the option
@var{opt} to value @var{val}.

Options include

@table @asis
@item @qcode{"absolute tolerance"}
Absolute tolerance; may be zero for pure relative error test.

@item @qcode{"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 @qcode{"single precision absolute tolerance"}
Absolute tolerance for single precision; may be zero for pure relative
error test.

@item @qcode{"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
isguirunning
@c isguirunning libinterp/octave.cc
-*- texinfo -*-
@deftypefn {} {} isguirunning ()
Return true if Octave is running in GUI mode and false otherwise.
@seealso{have_window_system}
@end deftypefn
argv
@c argv libinterp/octave.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/octave.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/octave.cc
-*- texinfo -*-
@deftypefn {} {} program_name ()
Return the last component of the value returned by
@code{program_invocation_name}.
@seealso{program_invocation_name}
@end deftypefn
sparse_auto_mutate
@c sparse_auto_mutate libinterp/octave-value/ov-base.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} sparse_auto_mutate ()
@deftypefnx {} {@var{old_val} =} sparse_auto_mutate (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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 libinterp/octave-value/ov-bool-mat.cc
-*- texinfo -*-
@deftypefn {} {} logical (@var{x})
Convert the numeric object @var{x} to logical type.

Any nonzero values will be converted to true (1) while zero values will be
converted to false (0).  The non-numeric value NaN cannot be converted and
will produce an error.

Compatibility Note: Octave accepts complex values as input, whereas
@sc{matlab} issues an error.
@seealso{double, single, char}
@end deftypefn
iscell
@c iscell libinterp/octave-value/ov-cell.cc
-*- texinfo -*-
@deftypefn {} {} iscell (@var{x})
Return true if @var{x} is a cell array object.
@seealso{ismatrix, isstruct, iscellstr, isa}
@end deftypefn
cell
@c cell libinterp/octave-value/ov-cell.cc
-*- texinfo -*-
@deftypefn  {} {} cell (@var{n})
@deftypefnx {} {} cell (@var{m}, @var{n})
@deftypefnx {} {} cell (@var{m}, @var{n}, @var{k}, @dots{})
@deftypefnx {} {} 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.
@seealso{cellstr, mat2cell, num2cell, struct2cell}
@end deftypefn
iscellstr
@c iscellstr libinterp/octave-value/ov-cell.cc
-*- texinfo -*-
@deftypefn {} {} iscellstr (@var{cell})
Return true if every element of the cell array @var{cell} is a character
string.
@seealso{ischar, isstring}
@end deftypefn
cellstr
@c cellstr libinterp/octave-value/ov-cell.cc
-*- texinfo -*-
@deftypefn {} {@var{cstr} =} cellstr (@var{strmat})
Create a new cell array object from the elements of the string array
@var{strmat}.

Each row of @var{strmat} becomes an element of @var{cstr}.  Any trailing
spaces in a row are deleted before conversion.

To convert back from a cellstr to a character array use @code{char}.
@seealso{cell, char}
@end deftypefn
struct2cell
@c struct2cell libinterp/octave-value/ov-cell.cc
-*- texinfo -*-
@deftypefn {} {@var{c} =} 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 = @{2x1x3 Cell Array@}
c(1,1,:)(:)
   @result{}
      @{
        [1,1] = Peter
        [2,1] = Hannah
        [3,1] = Robert
      @}
c(2,1,:)(:)
   @result{}
      @{
        [1,1] = 23
        [2,1] = 16
        [3,1] = 3
      @}
@end group
@end example

@seealso{cell2struct, fieldnames}
@end deftypefn
class
@c class libinterp/octave-value/ov-class.cc
-*- texinfo -*-
@deftypefn  {} {@var{classname} =} class (@var{obj})
@deftypefnx {} {} class (@var{s}, @var{id})
@deftypefnx {} {} class (@var{s}, @var{id}, @var{p}, @dots{})
Return the class of the object @var{obj}, 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.
@seealso{typeinfo, isa}
@end deftypefn
isa
@c isa libinterp/octave-value/ov-class.cc
-*- texinfo -*-
@deftypefn {} {} isa (@var{obj}, @var{classname})
Return true if @var{obj} is an object from the class @var{classname}.

@var{classname} may also be one of the following class categories:

@table @asis
@item @qcode{"float"}
Floating point value comprising classes @qcode{"double"} and
@qcode{"single"}.

@item @qcode{"integer"}
Integer value comprising classes (u)int8, (u)int16, (u)int32, (u)int64.

@item @qcode{"numeric"}
Numeric value comprising either a floating point or integer value.
@end table

If @var{classname} is a cell array of string, a logical array of the same
size is returned, containing true for each class to which @var{obj}
belongs to.

@seealso{class, typeinfo}
@end deftypefn
__parent_classes__
@c __parent_classes__ libinterp/octave-value/ov-class.cc
-*- texinfo -*-
@deftypefn {} {} __parent_classes__ (@var{x})
Undocumented internal function.
@end deftypefn
isobject
@c isobject libinterp/octave-value/ov-class.cc
-*- texinfo -*-
@deftypefn {} {} isobject (@var{x})
Return true if @var{x} is a class object.
@seealso{class, typeinfo, isa, ismethod, isprop}
@end deftypefn
ismethod
@c ismethod libinterp/octave-value/ov-class.cc
-*- texinfo -*-
@deftypefn  {} {} ismethod (@var{obj}, @var{method})
@deftypefnx {} {} ismethod (@var{clsname}, @var{method})
Return true if the string @var{method} is a valid method of the object
@var{obj} or of the class @var{clsname}.
@seealso{isprop, isobject}
@end deftypefn
__methods__
@c __methods__ libinterp/octave-value/ov-class.cc
-*- texinfo -*-
@deftypefn  {} {} __methods__ (@var{x})
@deftypefnx {} {} __methods__ ("classname")
Internal function.

Implements @code{methods} for Octave class objects and classnames.
@seealso{methods}
@end deftypefn
superiorto
@c superiorto libinterp/octave-value/ov-class.cc
-*- texinfo -*-
@deftypefn {} {} 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 @emph{only} be called from a class constructor.
@seealso{inferiorto}
@end deftypefn
inferiorto
@c inferiorto libinterp/octave-value/ov-class.cc
-*- texinfo -*-
@deftypefn {} {} 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 @emph{only} be called from a class constructor.
@seealso{superiorto}
@end deftypefn
__meta_get_package__
@c __meta_get_package__ libinterp/octave-value/ov-classdef.cc
-*- texinfo -*-
@deftypefn {} {} __meta_get_package__ ()
Undocumented internal function.
@end deftypefn
__superclass_reference__
@c __superclass_reference__ libinterp/octave-value/ov-classdef.cc
-*- texinfo -*-
@deftypefn {} {} __superclass_reference__ ()
Undocumented internal function.
@end deftypefn
__meta_class_query__
@c __meta_class_query__ libinterp/octave-value/ov-classdef.cc
-*- texinfo -*-
@deftypefn {} {} __meta_class_query__ ()
Undocumented internal function.
@end deftypefn
metaclass
@c metaclass libinterp/octave-value/ov-classdef.cc
-*- texinfo -*-
@deftypefn {} {} metaclass (obj)
Returns the meta.class object corresponding to the class of @var{obj}.
@end deftypefn
functions
@c functions libinterp/octave-value/ov-fcn-handle.cc
-*- texinfo -*-
@deftypefn {} {@var{s} =} functions (@var{fcn_handle})
Return a structure containing information about the function handle
@var{fcn_handle}.

The structure @var{s} always contains these three fields:

@table @asis
@item function
The function name.  For an anonymous function (no name) this will be the
actual function definition.

@item type
Type of the function.

@table @asis
@item anonymous
The function is anonymous.

@item private
The function is private.

@item overloaded
The function overloads an existing function.

@item simple
The function is a built-in or m-file function.

@item subfunction
The function is a subfunction within an m-file.
@end table

@item file
The m-file that will be called to perform the function.  This field is empty
for anonymous and built-in functions.
@end table

In addition, some function types may return more information in additional
fields.

@strong{Warning:} @code{functions} is provided for debugging purposes only.
Its behavior may change in the future and programs should not depend on any
particular output format.

@seealso{func2str, str2func}
@end deftypefn
func2str
@c func2str libinterp/octave-value/ov-fcn-handle.cc
-*- texinfo -*-
@deftypefn {} {} func2str (@var{fcn_handle})
Return a string containing the name of the function referenced by the
function handle @var{fcn_handle}.
@seealso{str2func, functions}
@end deftypefn
str2func
@c str2func libinterp/octave-value/ov-fcn-handle.cc
-*- texinfo -*-
@deftypefn {} {} str2func (@var{fcn_name})
Return a function handle constructed from the string @var{fcn_name}.

Previous versions of Octave accepted an optional second argument,
@qcode{"global"}, that caused str2func to ignore locally visible
functions.  This option is no longer supported.
@seealso{func2str, inline, functions}
@end deftypefn
is_function_handle
@c is_function_handle libinterp/octave-value/ov-fcn-handle.cc
-*- texinfo -*-
@deftypefn {} {} is_function_handle (@var{x})
Return true if @var{x} is a function handle.
@seealso{isa, typeinfo, class, functions}
@end deftypefn
inline
@c inline libinterp/octave-value/ov-fcn-inline.cc
-*- texinfo -*-
@deftypefn  {} {} inline (@var{str})
@deftypefnx {} {} inline (@var{str}, @var{arg1}, @dots{})
@deftypefnx {} {} 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 built-in constant.  All arguments followed by a parenthesis
are considered to be functions.  If no arguments are found, a function
taking a single argument named @code{x} will be created.

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
@qcode{"x"}, @qcode{"P1"}, @dots{}, @qcode{"P@var{N}"}.

Programming Note: The use of @code{inline} is discouraged and it may be
removed from a future version of Octave.  The preferred way to create
functions from strings is through the use of anonymous functions
(@pxref{Anonymous Functions}) or @code{str2func}.
@seealso{argnames, formula, vectorize, str2func}
@end deftypefn
formula
@c formula libinterp/octave-value/ov-fcn-inline.cc
-*- texinfo -*-
@deftypefn {} {} 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{char, argnames, inline, vectorize}
@end deftypefn
argnames
@c argnames libinterp/octave-value/ov-fcn-inline.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/octave-value/ov-fcn-inline.cc
-*- texinfo -*-
@deftypefn {} {} 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
__java_init__
@c __java_init__ libinterp/octave-value/ov-java.cc
-*- texinfo -*-
@deftypefn {} {} __java_init__ ()
Internal function used @strong{only} when debugging Java interface.

Function will directly call initialize_java to create an instance of a JVM.
@end deftypefn
__java_exit__
@c __java_exit__ libinterp/octave-value/ov-java.cc
-*- texinfo -*-
@deftypefn {} {} __java_exit__ ()
Internal function used @strong{only} when debugging Java interface.

Function will directly call terminate_jvm to destroy the current JVM
instance.
@end deftypefn
javaObject
@c javaObject libinterp/octave-value/ov-java.cc
-*- texinfo -*-
@deftypefn  {} {@var{jobj} =} javaObject (@var{classname})
@deftypefnx {} {@var{jobj} =} javaObject (@var{classname}, @var{arg1}, @dots{})
Create a Java object of class @var{classsname}, by calling the class
constructor with the arguments @var{arg1}, @dots{}

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

@example
@group
x = javaObject ("java.lang.StringBuffer")
x = javaObject ("java.lang.StringBuffer", "Initial string")
@end group
@end example

@seealso{javaMethod, javaArray}
@end deftypefn
javaMethod
@c javaMethod libinterp/octave-value/ov-java.cc
-*- texinfo -*-
@deftypefn  {} {@var{ret} =} javaMethod (@var{methodname}, @var{obj})
@deftypefnx {} {@var{ret} =} javaMethod (@var{methodname}, @var{obj}, @var{arg1}, @dots{})
Invoke the method @var{methodname} on the Java object @var{obj} with the
arguments @var{arg1}, @dots{}.

For static methods, @var{obj} can be a string representing the fully
qualified name of the corresponding class.

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

@example
@group
  ret = javaMethod ("method1", x, 1.0, "a string")
  ret = x.method1 (1.0, "a string")
@end group
@end example

@code{javaMethod} returns the result of the method invocation.

@seealso{methods, javaObject}
@end deftypefn
__java_get__
@c __java_get__ libinterp/octave-value/ov-java.cc
-*- texinfo -*-
@deftypefn {} {@var{val} =} __java_get__ (@var{obj}, @var{name})
Get the value of the field @var{name} of the Java object @var{obj}.

For static fields, @var{obj} can be a string representing the fully
qualified name of the corresponding class.

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

@example
@group
  __java_get__ (x, "field1")
  x.field1
@end group
@end example

@seealso{__java_set__, javaMethod, javaObject}
@end deftypefn
__java_set__
@c __java_set__ libinterp/octave-value/ov-java.cc
-*- texinfo -*-
@deftypefn {} {@var{obj} =} __java_set__ (@var{obj}, @var{name}, @var{val})
Set the value of the field @var{name} of the Java object @var{obj} to
@var{val}.

For static fields, @var{obj} can be a string representing the fully
qualified named of the corresponding Java class.

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

@example
@group
  __java_set__ (x, "field1", val)
  x.field1 = val
@end group
@end example

@seealso{__java_get__, javaMethod, javaObject}
@end deftypefn
__java2mat__
@c __java2mat__ libinterp/octave-value/ov-java.cc
-*- texinfo -*-
@deftypefn {} {} __java2mat__ (@var{javaobj})
Undocumented internal function.
@end deftypefn
java_matrix_autoconversion
@c java_matrix_autoconversion libinterp/octave-value/ov-java.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} java_matrix_autoconversion ()
@deftypefnx {} {@var{old_val} =} java_matrix_autoconversion (@var{new_val})
@deftypefnx {} {} java_matrix_autoconversion (@var{new_val}, "local")
Query or set the internal variable that controls whether Java arrays are
automatically converted to Octave matrices.

The default value is false.

When called from inside a function with the @qcode{"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{java_unsigned_autoconversion, debug_java}
@end deftypefn
java_unsigned_autoconversion
@c java_unsigned_autoconversion libinterp/octave-value/ov-java.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} java_unsigned_autoconversion ()
@deftypefnx {} {@var{old_val} =} java_unsigned_autoconversion (@var{new_val})
@deftypefnx {} {} java_unsigned_autoconversion (@var{new_val}, "local")
Query or set the internal variable that controls how integer classes are
converted when @code{java_matrix_autoconversion} is enabled.

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

When called from inside a function with the @qcode{"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{java_matrix_autoconversion, debug_java}
@end deftypefn
debug_java
@c debug_java libinterp/octave-value/ov-java.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} debug_java ()
@deftypefnx {} {@var{old_val} =} debug_java (@var{new_val})
@deftypefnx {} {} debug_java (@var{new_val}, "local")
Query or set the internal variable that determines whether extra debugging
information regarding the initialization of the JVM and any Java exceptions
is printed.

When called from inside a function with the @qcode{"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{java_matrix_autoconversion, java_unsigned_autoconversion}
@end deftypefn
isjava
@c isjava libinterp/octave-value/ov-java.cc
-*- texinfo -*-
@deftypefn {} {} isjava (@var{x})
Return true if @var{x} is a Java object.
@seealso{class, typeinfo, isa, javaObject}
@end deftypefn
isnull
@c isnull libinterp/octave-value/ov-null-mat.cc
-*- texinfo -*-
@deftypefn {} {} isnull (@var{x})
Return true if @var{x} is a special null matrix, string, or single quoted
string.

Indexed assignment with such a null value on the right-hand side should delete
array elements.  This function is used in place of @code{isempty} when
overloading the indexed assignment method (@code{subsasgn}) for user-defined
classes.  @code{isnull} is used to distinguish between these two cases:

@code{@var{A}(@var{I}) = []}

and

@code{@var{X} = []; @var{A}(@var{I}) = @var{X}}

In the first assignment, the right-hand side is @code{[]} which is a special
null value.  As long as the index @var{I} is not empty, this code should
delete elements from @var{A} rather than perform assignment.

In the second assignment, the right-hand side is empty (because @var{X} is
@code{[]}), but it is @strong{not} null.  This code should assign the empty
value to elements in @var{A}.

An example from Octave's built-in char class demonstrates the interpreter
behavior when @code{isnull} is used correctly.

@example
@group
str = "Hello World";
nm = "Wally";
str(7:end) = nm                # indexed assignment
  @result{} str = Hello Wally
str(7:end) = ""                # indexed deletion
  @result{} str = Hello
@end group
@end example
@seealso{isempty, isindex}
@end deftypefn
onCleanup
@c onCleanup libinterp/octave-value/ov-oncleanup.cc
-*- texinfo -*-
@deftypefn {} {@var{obj} =} onCleanup (@var{function})
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{function} 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 unwind_protect Statement}.
@end deftypefn
struct
@c struct libinterp/octave-value/ov-struct.cc
-*- texinfo -*-
@deftypefn  {} {@var{s} =} struct ()
@deftypefnx {} {@var{s} =} struct (@var{field1}, @var{value1}, @var{field2}, @var{value2}, @dots{})
@deftypefnx {} {@var{s} =} struct (@var{obj})

Create a scalar or array structure and initialize its values.

The @var{field1}, @var{field2}, @dots{} variables are strings specifying the
names of the fields and the @var{value1}, @var{value2}, @dots{} variables
can be of any type.

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.

Observe that the syntax is optimized for struct @strong{arrays}.  Consider
the following examples:

@example
@group
struct ("foo", 1)
  @result{} scalar structure containing the fields:
    foo =  1

struct ("foo", @{@})
  @result{} 0x0 struct array containing the fields:
    foo

struct ("foo", @{ @{@} @})
  @result{} scalar structure containing the fields:
    foo = @{@}(0x0)

struct ("foo", @{1, 2, 3@})
  @result{} 1x3 struct array containing the fields:
    foo

@end group
@end example

@noindent
The first case is an ordinary scalar struct---one field, one value.  The
second produces an empty struct array with one field and no values, since
being passed an empty cell array of struct array values.  When the value is
a cell array containing a single entry, this becomes a scalar struct with
that single entry as the value of the field.  That single entry happens
to be an empty cell array.

Finally, if the value is a non-scalar cell array, then @code{struct}
produces a struct @strong{array}.
@seealso{cell2struct, fieldnames, getfield, setfield, rmfield, isfield, orderfields, isstruct, structfun}
@end deftypefn
isstruct
@c isstruct libinterp/octave-value/ov-struct.cc
-*- texinfo -*-
@deftypefn {} {} isstruct (@var{x})
Return true if @var{x} is a structure or a structure array.
@seealso{ismatrix, iscell, isa}
@end deftypefn
__fieldnames__
@c __fieldnames__ libinterp/octave-value/ov-struct.cc
-*- texinfo -*-
@deftypefn  {} {} __fieldnames__ (@var{struct})
@deftypefnx {} {} __fieldnames__ (@var{obj})
Internal function.

Implements @code{fieldnames()} for structures and Octave objects.
@seealso{fieldnames}
@end deftypefn
isfield
@c isfield libinterp/octave-value/ov-struct.cc
-*- texinfo -*-
@deftypefn  {} {} isfield (@var{x}, "@var{name}")
@deftypefnx {} {} 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.
@seealso{fieldnames}
@end deftypefn
numfields
@c numfields libinterp/octave-value/ov-struct.cc
-*- texinfo -*-
@deftypefn {} {} numfields (@var{s})
Return the number of fields of the structure @var{s}.
@seealso{fieldnames}
@end deftypefn
cell2struct
@c cell2struct libinterp/octave-value/ov-struct.cc
-*- texinfo -*-
@deftypefn  {} {} cell2struct (@var{cell}, @var{fields})
@deftypefnx {} {} 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{}
      @{
        Name   = Peter
        Height = 185
      @}

@end group
@end example
@seealso{struct2cell, cell2mat, struct}
@end deftypefn
rmfield
@c rmfield libinterp/octave-value/ov-struct.cc
-*- texinfo -*-
@deftypefn  {} {@var{sout} =} rmfield (@var{s}, "@var{f}")
@deftypefnx {} {@var{sout} =} rmfield (@var{s}, @var{f})
Return a @emph{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 each of
the named fields.
@seealso{orderfields, fieldnames, isfield}
@end deftypefn
struct_levels_to_print
@c struct_levels_to_print libinterp/octave-value/ov-struct.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} struct_levels_to_print ()
@deftypefnx {} {@var{old_val} =} struct_levels_to_print (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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{print_struct_array_contents}
@end deftypefn
print_struct_array_contents
@c print_struct_array_contents libinterp/octave-value/ov-struct.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} print_struct_array_contents ()
@deftypefnx {} {@var{old_val} =} print_struct_array_contents (@var{new_val})
@deftypefnx {} {} 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 whose 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 @qcode{"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{struct_levels_to_print}
@end deftypefn
typeinfo
@c typeinfo libinterp/octave-value/ov-typeinfo.cc
-*- texinfo -*-
@deftypefn  {} {} typeinfo ()
@deftypefnx {} {} typeinfo (@var{expr})

Return the type of the expression @var{expr}, as a string.

If @var{expr} is omitted, return a cell array of strings containing all the
currently installed data types.
@seealso{class, isa}
@end deftypefn
__dump_typeinfo__
@c __dump_typeinfo__ libinterp/octave-value/ov-typeinfo.cc
-*- texinfo -*-
@deftypefn {} {} __dump_typeinfo__ ()
Undocumented internal function.
@end deftypefn
nargin
@c nargin libinterp/octave-value/ov-usr-fcn.cc
-*- texinfo -*-
@deftypefn  {} {} nargin ()
@deftypefnx {} {} nargin (@var{fcn})
Report the number of input arguments to a function.

Called from 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}---a function name or
handle---return the declared number of arguments that the function can
accept.

If the last argument to @var{fcn} is @var{varargin} the returned value is
negative.  For example, the function @code{union} for sets is declared as

@example
@group
function [y, ia, ib] = union (a, b, varargin)

and

nargin ("union")
@result{} -3
@end group
@end example

Programming Note: @code{nargin} does not work on compiled functions
(@file{.oct} files) such as built-in or dynamically loaded functions.
@seealso{nargout, narginchk, varargin, inputname}
@end deftypefn
nargout
@c nargout libinterp/octave-value/ov-usr-fcn.cc
-*- texinfo -*-
@deftypefn  {} {} nargout ()
@deftypefnx {} {} nargout (@var{fcn})
Report the number of output arguments from a function.

Called from within a function, return the number of values the caller
expects to receive.  At the top level, @code{nargout} with no argument is
undefined and will produce an error.

If called with the optional argument @var{fcn}---a function name or
handle---return the number of declared output values that the function can
produce.

If the final output argument is @var{varargout} the returned value is
negative.

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

In the second usage,

@example
nargout (@@histc)   # or nargout ("histc") using a string input
@end example

@noindent
will return 2, because @code{histc} has two outputs, whereas

@example
nargout (@@imread)
@end example

@noindent
will return -2, because @code{imread} has two outputs and the second is
@var{varargout}.

Programming Note.  @code{nargout} does not work for built-in functions and
returns -1 for all anonymous functions.
@seealso{nargin, varargout, isargout, nthargout}
@end deftypefn
optimize_subsasgn_calls
@c optimize_subsasgn_calls libinterp/octave-value/ov-usr-fcn.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} optimize_subsasgn_calls ()
@deftypefnx {} {@var{old_val} =} optimize_subsasgn_calls (@var{new_val})
@deftypefnx {} {} optimize_subsasgn_calls (@var{new_val}, "local")
Query or set the internal flag for @code{subsasgn} method call
optimizations.

If true, Octave will attempt to eliminate the redundant copying when calling
the @code{subsasgn} method of a user-defined class.

When called from inside a function with the @qcode{"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{subsasgn}
@end deftypefn
isargout
@c isargout libinterp/octave-value/ov-usr-fcn.cc
-*- texinfo -*-
@deftypefn {} {} isargout (@var{k})
Within a function, return a logical value indicating whether the argument
@var{k} will be assigned to a variable on output.

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, varargout, nthargout}
@end deftypefn
double
@c double libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} double (@var{x})
Convert @var{x} to double precision type.
@seealso{single}
@end deftypefn
single
@c single libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} single (@var{x})
Convert @var{x} to single precision type.
@seealso{double}
@end deftypefn
int8
@c int8 libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} int8 (@var{x})
Convert @var{x} to 8-bit integer type.
@seealso{uint8, int16, uint16, int32, uint32, int64, uint64}
@end deftypefn
int16
@c int16 libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} int16 (@var{x})
Convert @var{x} to 16-bit integer type.
@seealso{int8, uint8, uint16, int32, uint32, int64, uint64}
@end deftypefn
int32
@c int32 libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} int32 (@var{x})
Convert @var{x} to 32-bit integer type.
@seealso{int8, uint8, int16, uint16, uint32, int64, uint64}
@end deftypefn
int64
@c int64 libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} int64 (@var{x})
Convert @var{x} to 64-bit integer type.
@seealso{int8, uint8, int16, uint16, int32, uint32, uint64}
@end deftypefn
uint8
@c uint8 libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} uint8 (@var{x})
Convert @var{x} to unsigned 8-bit integer type.
@seealso{int8, int16, uint16, int32, uint32, int64, uint64}
@end deftypefn
uint16
@c uint16 libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} uint16 (@var{x})
Convert @var{x} to unsigned 16-bit integer type.
@seealso{int8, uint8, int16, int32, uint32, int64, uint64}
@end deftypefn
uint32
@c uint32 libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} uint32 (@var{x})
Convert @var{x} to unsigned 32-bit integer type.
@seealso{int8, uint8, int16, uint16, int32, int64, uint64}
@end deftypefn
uint64
@c uint64 libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} uint64 (@var{x})
Convert @var{x} to unsigned 64-bit integer type.
@seealso{int8, uint8, int16, uint16, int32, uint32, int64}
@end deftypefn
sizeof
@c sizeof libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} sizeof (@var{val})
Return the size of @var{val} in bytes.
@seealso{whos}
@end deftypefn
subsref
@c subsref libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} subsref (@var{val}, @var{idx})
Perform the subscripted element selection operation on @var{val} according
to the subscript specified by @var{idx}.

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

The following example shows how to extract the first two 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 libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} subsasgn (@var{val}, @var{idx}, @var{rhs})
Perform the subscripted assignment operation according to the subscript
specified by @var{idx}.

The subscript @var{idx} must be a structure array with fields @samp{type}
and @samp{subs}.  Valid values for @samp{type} are @qcode{"()"},
@qcode{"@{@}"}, and @qcode{"."}.  The @samp{subs} field may be either
@qcode{":"} 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, optimize_subsasgn_calls}
@end deftypefn
is_sq_string
@c is_sq_string libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn {} {} is_dq_string (@var{x})
Return true if @var{x} is a double-quoted character string.
@seealso{is_sq_string, ischar}
@end deftypefn
disable_permutation_matrix
@c disable_permutation_matrix libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} disable_permutation_matrix ()
@deftypefnx {} {@var{old_val} =} disable_permutation_matrix (@var{new_val})
@deftypefnx {} {} disable_permutation_matrix (@var{new_val}, "local")
Query or set the internal variable that controls whether permutation
matrices are stored in a special space-efficient format.

The default value is true.  If this option is disabled Octave will store
permutation matrices as full matrices.

When called from inside a function with the @qcode{"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{disable_range, disable_diagonal_matrix}
@end deftypefn
disable_diagonal_matrix
@c disable_diagonal_matrix libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} disable_diagonal_matrix ()
@deftypefnx {} {@var{old_val} =} disable_diagonal_matrix (@var{new_val})
@deftypefnx {} {} disable_diagonal_matrix (@var{new_val}, "local")
Query or set the internal variable that controls whether diagonal
matrices are stored in a special space-efficient format.

The default value is true.  If this option is disabled Octave will store
diagonal matrices as full matrices.

When called from inside a function with the @qcode{"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{disable_range, disable_permutation_matrix}
@end deftypefn
disable_range
@c disable_range libinterp/octave-value/ov.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} disable_range ()
@deftypefnx {} {@var{old_val} =} disable_range (@var{new_val})
@deftypefnx {} {} disable_range (@var{new_val}, "local")
Query or set the internal variable that controls whether ranges are stored
in a special space-efficient format.

The default value is true.  If this option is disabled Octave will store
ranges as full matrices.

When called from inside a function with the @qcode{"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{disable_diagonal_matrix, disable_permutation_matrix}
@end deftypefn
iskeyword
@c iskeyword libinterp/parse-tree/lex.ll
-*- texinfo -*-
@deftypefn  {} {} iskeyword ()
@deftypefnx {} {} 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
autoload
@c autoload libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {@var{autoload_map} =} autoload ()
@deftypefnx {} {} autoload (@var{function}, @var{file})
@deftypefnx {} {} autoload (@dots{}, "remove")
Define @var{function} to autoload from @var{file}.

The second argument, @var{file}, should be an absolute filename or a file
name in the same directory as the function or script from which the autoload
command was run.  @var{file} @emph{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 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
usage when @code{bar.oct} is not in the same directory, or usages such as

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

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

With no arguments, return a structure containing the current autoload map.

If a third argument @qcode{"remove"} is given, the function is cleared and
not loaded anymore during the current Octave session.

@seealso{PKG_ADD}
@end deftypefn
mfilename
@c mfilename libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {} mfilename ()
@deftypefnx {} {} mfilename ("fullpath")
@deftypefnx {} {} mfilename ("fullpathext")
Return the name of the currently executing file.

The base name of the currently executing script or function is returned without
any extension.  If called from outside an m-file, such as the command line,
return the empty string.

Given the argument @qcode{"fullpath"}, include the directory part of the
filename, but not the extension.

Given the argument @qcode{"fullpathext"}, include the directory part of
the filename and the extension.
@seealso{inputname, dbstack}
@end deftypefn
source
@c source libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {} source (@var{file})
@deftypefnx {} {} source (@var{file}, @var{context})
Parse and execute the contents of @var{file}.

Without specifying @var{context}, this is equivalent to executing commands
from a script file, but without requiring the file to be named
@file{@var{file}.m} or to be on the execution path.

Instead of the current context, the script may be executed in either the
context of the function that called the present function
(@qcode{"caller"}), or the top-level context (@qcode{"base"}).
@seealso{run}
@end deftypefn
feval
@c feval libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} feval (@var{name}, @dots{})
Evaluate the function named @var{name}.

Any arguments after the first are passed as inputs 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 whether @var{f} is a function handle,
function name in a string, or inline function then @code{feval} can be used
instead.
@end deftypefn
builtin
@c builtin libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {[@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.

This is normally useful when doing object-oriented programming and there is
a requirement to call one of Octave's base functions rather than the
overloaded one of a new class.

A trivial example which redefines the @code{sin} function to be the
@code{cos} function shows how @code{builtin} works.

@example
@group
sin (0)
  @result{} 0
function y = sin (x), y = cos (x); endfunction
sin (0)
  @result{} 1
builtin ("sin", 0)
  @result{} 0
@end group
@end example
@end deftypefn
eval
@c eval libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {} eval (@var{try})
@deftypefnx {} {} eval (@var{try}, @var{catch})
Parse the string @var{try} and evaluate it as if it were an Octave
program.

If execution 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 creates the variable @var{A} with the approximate
value of 3.1416 in the current workspace.

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

If an error occurs during the evaluation of @var{try} then 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

Programming Note: if you are only using @code{eval} as an error-capturing
mechanism, rather than for the execution of arbitrary code strings,
Consider using try/catch blocks or unwind_protect/unwind_protect_cleanup
blocks instead.  These techniques have higher performance and don't
introduce the security considerations that the evaluation of arbitrary code
does.
@seealso{evalin, evalc, assignin, feval}
@end deftypefn
assignin
@c assignin libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} assignin (@var{context}, @var{varname}, @var{value})
Assign @var{value} to @var{varname} in context @var{context}, which
may be either @qcode{"base"} or @qcode{"caller"}.
@seealso{evalin}
@end deftypefn
evalin
@c evalin libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {} evalin (@var{context}, @var{try})
@deftypefnx {} {} 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 @qcode{"caller"} or @qcode{"base"}.
@seealso{eval, assignin}
@end deftypefn
evalc
@c evalc libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {@var{s} =} evalc (@var{try})
@deftypefnx {} {@var{s} =} evalc (@var{try}, @var{catch})
Parse and evaluate the string @var{try} as if it were an Octave program,
while capturing the output into the return variable @var{s}.

If execution fails, evaluate the optional string @var{catch}.

This function behaves like @code{eval}, but any output or warning messages
which would normally be written to the console are captured and returned in
the string @var{s}.

The @code{diary} is disabled during the execution of this function.  When
@code{system} is used, any output produced by external programs is
@emph{not} captured, unless their output is captured by the @code{system}
function itself.

@example
@group
s = evalc ("t = 42"), t
  @result{} s = t =  42

  @result{} t =  42
@end group
@end example
@seealso{eval, diary}
@end deftypefn
__parser_debug_flag__
@c __parser_debug_flag__ libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {@var{val} =} __parser_debug_flag__ ()
@deftypefnx {} {@var{old_val} =} __parser_debug_flag__ (@var{new_val})
Query or set the internal flag that determines whether Octave's parser
prints debug information as it processes an expression.
@seealso{__lexer_debug_flag__}
@end deftypefn
__parse_file__
@c __parse_file__ libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} __parse_file__ (@var{file}, @var{verbose})
Undocumented internal function.
@end deftypefn
__profiler_enable__
@c __profiler_enable__ libinterp/parse-tree/profiler.cc
-*- texinfo -*-
@deftypefn {} {} __profiler_enable__ ()
Undocumented internal function.
@end deftypefn
__profiler_reset__
@c __profiler_reset__ libinterp/parse-tree/profiler.cc
-*- texinfo -*-
@deftypefn {} {} __profiler_reset__ ()
Undocumented internal function.
@end deftypefn
__profiler_data__
@c __profiler_data__ libinterp/parse-tree/profiler.cc
-*- texinfo -*-
@deftypefn {} {} __profiler_data__ ()
Undocumented internal function.
@end deftypefn
end
@c end libinterp/parse-tree/pt-eval.cc
-*- texinfo -*-
@deftypefn {} {} end
Last element of an array or the end of any @code{for}, @code{parfor},
@code{if}, @code{do}, @code{while}, @code{function}, @code{switch},
@code{try}, or @code{unwind_protect} block.

As an index of an array, the magic index @qcode{"end"} refers to the
last valid entry in an indexing operation.

Example:

@example
@group
@var{x} = [ 1 2 3; 4 5 6 ];
@var{x}(1,end)
   @result{} 3
@var{x}(end,1)
   @result{} 4
@var{x}(end,end)
   @result{} 6
@end group
@end example
@seealso{for, parfor, if, do, while, function, switch, try, unwind_protect}
@end deftypefn
max_recursion_depth
@c max_recursion_depth libinterp/parse-tree/pt-eval.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} max_recursion_depth ()
@deftypefnx {} {@var{old_val} =} max_recursion_depth (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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{max_stack_depth}
@end deftypefn
whos_line_format
@c whos_line_format libinterp/parse-tree/pt-eval.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} whos_line_format ()
@deftypefnx {} {@var{old_val} =} whos_line_format (@var{new_val})
@deftypefnx {} {} 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:

@qcode{"  %a:4; %ln:6; %cs:16:6:1;  %rb:12;  %lc:-1;@xbackslashchar{}n"}

When called from inside a function with the @qcode{"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
silent_functions
@c silent_functions libinterp/parse-tree/pt-eval.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} silent_functions ()
@deftypefnx {} {@var{old_val} =} silent_functions (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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 libinterp/parse-tree/pt-eval.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} string_fill_char ()
@deftypefnx {} {@var{old_val} =} string_fill_char (@var{new_val})
@deftypefnx {} {} 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.

The value must be a single character and the default is @qcode{" "} (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 @qcode{"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
PS4
@c PS4 libinterp/parse-tree/pt-eval.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} PS4 ()
@deftypefnx {} {@var{old_val} =} PS4 (@var{new_val})
@deftypefnx {} {} 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 @qcode{"+ "}.
@xref{Diary and Echo Commands}, for a description of echoing commands.

When called from inside a function with the @qcode{"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, PS1, PS2}
@end deftypefn
echo
@c echo libinterp/parse-tree/pt-eval.cc
-*- texinfo -*-
@deftypefn  {} {} echo
@deftypefnx {} {} echo on
@deftypefnx {} {} echo off
@deftypefnx {} {} echo on all
@deftypefnx {} {} echo off all
@deftypefnx {} {} echo @var{function} on
@deftypefnx {} {} echo @var{function} off
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.

@item @var{function} on
Enable echoing of commands as they are executed in the named function.

@item @var{function} off
Disable echoing of commands as they are executed in the named function.
@end table

@noindent
With no arguments, @code{echo} toggles the current echo state.

@seealso{PS4}
@end deftypefn
jit_failcnt
@c jit_failcnt libinterp/parse-tree/pt-jit.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} jit_failcnt ()
@deftypefnx {} {@var{old_val} =} jit_failcnt (@var{new_val})
@deftypefnx {} {} jit_failcnt (@var{new_val}, "local")
Query or set the internal variable that counts the number of JIT fail
exceptions for Octave's JIT compiler.

When called from inside a function with the @qcode{"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{jit_enable, jit_startcnt, debug_jit}
@end deftypefn
debug_jit
@c debug_jit libinterp/parse-tree/pt-jit.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} debug_jit ()
@deftypefnx {} {@var{old_val} =} debug_jit (@var{new_val})
@deftypefnx {} {} debug_jit (@var{new_val}, "local")
Query or set the internal variable that determines whether
debugging/tracing is enabled for Octave's JIT compiler.

When called from inside a function with the @qcode{"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{jit_enable, jit_startcnt}
@end deftypefn
jit_enable
@c jit_enable libinterp/parse-tree/pt-jit.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} jit_enable ()
@deftypefnx {} {@var{old_val} =} jit_enable (@var{new_val})
@deftypefnx {} {} jit_enable (@var{new_val}, "local")
Query or set the internal variable that enables Octave's JIT compiler.

When called from inside a function with the @qcode{"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{jit_startcnt, debug_jit}
@end deftypefn
jit_startcnt
@c jit_startcnt libinterp/parse-tree/pt-jit.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} jit_startcnt ()
@deftypefnx {} {@var{old_val} =} jit_startcnt (@var{new_val})
@deftypefnx {} {} jit_startcnt (@var{new_val}, "local")
Query or set the internal variable that determines whether JIT compilation
will take place for a specific loop.

Because compilation is a costly operation it does not make sense to employ
JIT when the loop count is low.  By default only loops with greater than
1000 iterations will be accelerated.

When called from inside a function with the @qcode{"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{jit_enable, jit_failcnt, debug_jit}
@end deftypefn
__betainc__
@c __betainc__ libinterp/corefcn/__betainc__.cc
-*- texinfo -*-
@deftypefn {} {@var{y} =} __betainc__ (@var{x}, @var{a}, @var{b})
Continued fraction for incomplete beta function.
@end deftypefn
__contourc__
@c __contourc__ libinterp/corefcn/__contourc__.cc
-*- texinfo -*-
@deftypefn {} {} __contourc__ (@var{x}, @var{y}, @var{z}, @var{levels})
Undocumented internal function.
@end deftypefn
__dsearchn__
@c __dsearchn__ libinterp/corefcn/__dsearchn__.cc
-*- texinfo -*-
@deftypefn {} {[@var{idx}, @var{d}] =} dsearch (@var{x}, @var{xi})
Undocumented internal function.
@end deftypefn
__expint__
@c __expint__ libinterp/corefcn/__expint__.cc
-*- texinfo -*-
@deftypefn {} {@var{y} =} __expint__ (@var{x})
Continued fraction expansion for the exponential integral.
@end deftypefn
__gammainc__
@c __gammainc__ libinterp/corefcn/__gammainc__.cc
-*- texinfo -*-
@deftypefn {} {@var{y} =} __gammainc__ (@var{x}, @var{a})
Continued fraction for incomplete gamma function.
@end deftypefn
__ichol0__
@c __ichol0__ libinterp/corefcn/__ichol__.cc
-*- texinfo -*-
@deftypefn {} {@var{L} =} __ichol0__ (@var{A}, @var{michol})
Undocumented internal function.
@end deftypefn
__icholt__
@c __icholt__ libinterp/corefcn/__ichol__.cc
-*- texinfo -*-
@deftypefn {} {@var{L} =} __icholt__ (@var{A}, @var{droptol}, @var{michol})
Undocumented internal function.
@end deftypefn
__ilu0__
@c __ilu0__ libinterp/corefcn/__ilu__.cc
-*- texinfo -*-
@deftypefn  {} {[@var{L}, @var{U}] =} __ilu0__ (@var{A}, @var{milu})
@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} __ilu0__ (@var{A}, @var{milu})
Undocumented internal function.
@end deftypefn
__iluc__
@c __iluc__ libinterp/corefcn/__ilu__.cc
-*- texinfo -*-
@deftypefn {} {[@var{L}, @var{U}] =} __iluc__ (@var{A}, @var{droptol}, @var{milu})
Undocumented internal function.
@end deftypefn
__ilutp__
@c __ilutp__ libinterp/corefcn/__ilu__.cc
-*- texinfo -*-
@deftypefn  {} {[@var{L}, @var{U}] =} __ilutp__ (@var{A}, @var{droptol}, @var{thresh}, @var{milu}, @var{udiag})
@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} __ilutp__ (@dots{})
Undocumented internal function.
@end deftypefn
__lin_interpn__
@c __lin_interpn__ libinterp/corefcn/__lin_interpn__.cc
-*- texinfo -*-
@deftypefn {} {@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__ libinterp/corefcn/__magick_read__.cc
-*- texinfo -*-
@deftypefn {} {[@var{img}, @var{map}, @var{alpha}] =} __magick_read__ (@var{fname}, @var{options})
Read image with GraphicsMagick or ImageMagick.

This is a private internal function not intended for direct use.
Use @code{imread} instead.

@seealso{imfinfo, imformats, imread, imwrite}
@end deftypefn
__magick_write__
@c __magick_write__ libinterp/corefcn/__magick_read__.cc
-*- texinfo -*-
@deftypefn {} {} __magick_write__ (@var{fname}, @var{fmt}, @var{img}, @var{map}, @var{options})
Write image with GraphicsMagick or ImageMagick.

This is a private internal function not intended for direct use.
Use @code{imwrite} instead.

@seealso{imfinfo, imformats, imread, imwrite}
@end deftypefn
__magick_ping__
@c __magick_ping__ libinterp/corefcn/__magick_read__.cc
-*- texinfo -*-
@deftypefn {} {} __magick_ping__ (@var{fname}, @var{idx})
Ping image information with GraphicsMagick or ImageMagick.

This is a private internal function not intended for direct use.

@seealso{imfinfo}
@end deftypefn
__magick_finfo__
@c __magick_finfo__ libinterp/corefcn/__magick_read__.cc
-*- texinfo -*-
@deftypefn {} {} __magick_finfo__ (@var{fname})
Read image information with GraphicsMagick or ImageMagick.

This is a private internal function not intended for direct use.
Use @code{imfinfo} instead.

@seealso{imfinfo, imformats, imread, imwrite}
@end deftypefn
__magick_formats__
@c __magick_formats__ libinterp/corefcn/__magick_read__.cc
-*- texinfo -*-
@deftypefn {} {} __magick_imformats__ (@var{formats})
Fill formats info with GraphicsMagick CoderInfo.

@seealso{imfinfo, imformats, imread, imwrite}
@end deftypefn
__pchip_deriv__
@c __pchip_deriv__ libinterp/corefcn/__pchip_deriv__.cc
-*- texinfo -*-
@deftypefn {} {} __pchip_deriv__ (@var{x}, @var{y}, @var{dim})
Undocumented internal function.
@end deftypefn
__qp__
@c __qp__ libinterp/corefcn/__qp__.cc
-*- texinfo -*-
@deftypefn {} {[@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
balance
@c balance libinterp/corefcn/balance.cc
-*- texinfo -*-
@deftypefn  {} {@var{AA} =} balance (@var{A})
@deftypefnx {} {@var{AA} =} balance (@var{A}, @var{opt})
@deftypefnx {} {[@var{DD}, @var{AA}] =} balance (@var{A}, @var{opt})
@deftypefnx {} {[@var{D}, @var{P}, @var{AA}] =} balance (@var{A}, @var{opt})
@deftypefnx {} {[@var{CC}, @var{DD}, @var{AA}, @var{BB}] =} balance (@var{A}, @var{B}, @var{opt})

Balance the matrix @var{A} to reduce numerical errors in future
calculations.

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 nonzero 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 @qcode{"noperm"}, @qcode{"S"}
Scale only; do not permute.

@item @qcode{"noscal"}, @qcode{"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 libinterp/corefcn/besselj.cc
-*- texinfo -*-
@deftypefn  {} {@var{J} =} besselj (@var{alpha}, @var{x})
@deftypefnx {} {@var{J} =} besselj (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {} {[@var{J}, @var{ierr}] =} besselj (@dots{})
Compute Bessel functions of the first kind.

The order of the Bessel function @var{alpha} must be real.  The points for
evaluation @var{x} may be complex.

If the optional argument @var{opt} is 1 or true, the result @var{J} is
multiplied by @w{@code{exp (-abs (imag (@var{x})))}}.

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.

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
Loss of significance by argument reduction, output may be inaccurate.

@item
Error---no computation, algorithm termination condition not met, return
@code{NaN}.
@end enumerate

@seealso{bessely, besseli, besselk, besselh}
@end deftypefn
bessely
@c bessely libinterp/corefcn/besselj.cc
-*- texinfo -*-
@deftypefn  {} {@var{Y} =} bessely (@var{alpha}, @var{x})
@deftypefnx {} {@var{Y} =} bessely (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {} {[@var{Y}, @var{ierr}] =} bessely (@dots{})
Compute Bessel functions of the second kind.

The order of the Bessel function @var{alpha} must be real.  The points for
evaluation @var{x} may be complex.

If the optional argument @var{opt} is 1 or true, the result @var{Y} is
multiplied by @w{@code{exp (-abs (imag (@var{x})))}}.

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.

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

@seealso{besselj, besseli, besselk, besselh}
@end deftypefn
besseli
@c besseli libinterp/corefcn/besselj.cc
-*- texinfo -*-
@deftypefn  {} {@var{I} =} besseli (@var{alpha}, @var{x})
@deftypefnx {} {@var{I} =} besseli (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {} {[@var{I}, @var{ierr}] =} besseli (@dots{})
Compute modified Bessel functions of the first kind.

The order of the Bessel function @var{alpha} must be real.  The points for
evaluation @var{x} may be complex.

If the optional argument @var{opt} is 1 or true, the result @var{I} is
multiplied by @w{@code{exp (-abs (real (@var{x})))}}.

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.

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

@seealso{besselk, besselj, bessely, besselh}
@end deftypefn
besselk
@c besselk libinterp/corefcn/besselj.cc
-*- texinfo -*-
@deftypefn  {} {@var{K} =} besselk (@var{alpha}, @var{x})
@deftypefnx {} {@var{K} =} besselk (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {} {[@var{K}, @var{ierr}] =} besselk (@dots{})

Compute modified Bessel functions of the second kind.

The order of the Bessel function @var{alpha} must be real.  The points for
evaluation @var{x} may be complex.

If the optional argument @var{opt} is 1 or true, the result @var{K} is
multiplied by @w{@code{exp (@var{x})}}.

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.

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

@seealso{besseli, besselj, bessely, besselh}
@end deftypefn
besselh
@c besselh libinterp/corefcn/besselj.cc
-*- texinfo -*-
@deftypefn  {} {@var{H} =} besselh (@var{alpha}, @var{x})
@deftypefnx {} {@var{H} =} besselh (@var{alpha}, @var{k}, @var{x})
@deftypefnx {} {@var{H} =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt})
@deftypefnx {} {[@var{H}, @var{ierr}] =} besselh (@dots{})
Compute Bessel functions of the third kind (Hankel functions).

The order of the Bessel function @var{alpha} must be real.  The kind of Hankel
function is specified by @var{k} and may be either first (@var{k} = 1) or
second (@var{k} = 2).  The default is Hankel functions of the first kind.  The
points for evaluation @var{x} may be complex.

If the optional argument @var{opt} is 1 or true, the result is multiplied
by @code{exp (-I*@var{x})} for @var{k} = 1 or @code{exp (I*@var{x})} for
@var{k} = 2.

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.

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

@seealso{besselj, bessely, besseli, besselk}
@end deftypefn
airy
@c airy libinterp/corefcn/besselj.cc
-*- texinfo -*-
@deftypefn {} {[@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
Loss of significance by argument reduction, output may be inaccurate.

@item
Error---no computation, algorithm termination condition not met,
return @code{NaN}.
@end enumerate
@end deftypefn
bitand
@c bitand libinterp/corefcn/bitfcns.cc
-*- texinfo -*-
@deftypefn {} {} bitand (@var{x}, @var{y})
Return the bitwise AND of non-negative integers.

@var{x}, @var{y} must be in the range [0,intmax]
@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax}
@end deftypefn
bitor
@c bitor libinterp/corefcn/bitfcns.cc
-*- texinfo -*-
@deftypefn {} {} bitor (@var{x}, @var{y})
Return the bitwise OR of non-negative integers @var{x} and @var{y}.

@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax}
@end deftypefn
bitxor
@c bitxor libinterp/corefcn/bitfcns.cc
-*- texinfo -*-
@deftypefn {} {} bitxor (@var{x}, @var{y})
Return the bitwise XOR of non-negative integers @var{x} and @var{y}.

@seealso{bitand, bitor, bitset, bitget, bitcmp, bitshift, intmax, flintmax}
@end deftypefn
bitshift
@c bitshift libinterp/corefcn/bitfcns.cc
-*- texinfo -*-
@deftypefn  {} {} bitshift (@var{a}, @var{k})
@deftypefnx {} {} 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 64.
@var{n} must be in the range [1,64].

@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, intmax, flintmax}
@end deftypefn
flintmax
@c flintmax libinterp/corefcn/bitfcns.cc
-*- texinfo -*-
@deftypefn  {} {} flintmax ()
@deftypefnx {} {} flintmax ("double")
@deftypefnx {} {} flintmax ("single")
@deftypefnx {} {} flintmax (@var{var})
Return the largest integer that can be represented consecutively in a
floating point value.

The input is either a string specifying a floating point type, or it is an
existing floating point variable @var{var}.

The default type is @qcode{"double"}, but @qcode{"single"} is a valid option.
On IEEE 754 compatible systems, @code{flintmax} is @w{@math{2^{53}}} for
@qcode{"double"} and @w{@math{2^{24}}} for @qcode{"single"}.

Example Code - query an existing variable

@example
@group
x = single (1);
flintmax (x)
  @result{} 16777216
@end group
@end example

@seealso{intmax, realmax, realmin}
@end deftypefn
intmax
@c intmax libinterp/corefcn/bitfcns.cc
-*- texinfo -*-
@deftypefn  {} {} intmax ()
@deftypefnx {} {} intmax ("@var{type}")
@deftypefnx {} {} intmax (@var{var})
Return the largest integer that can be represented by a specific integer type.

The input is either a string @qcode{"@var{type}"} specifying an integer type,
or it is an existing integer variable @var{var}.

Possible values for @var{type} are

@table @asis
@item @qcode{"int8"}
signed 8-bit integer.

@item @qcode{"int16"}
signed 16-bit integer.

@item @qcode{"int32"}
signed 32-bit integer.

@item @qcode{"int64"}
signed 64-bit integer.

@item @qcode{"uint8"}
unsigned 8-bit integer.

@item @qcode{"uint16"}
unsigned 16-bit integer.

@item @qcode{"uint32"}
unsigned 32-bit integer.

@item @qcode{"uint64"}
unsigned 64-bit integer.
@end table

The default for @var{type} is @qcode{"int32"}.

Example Code - query an existing variable

@example
@group
x = int8 (1);
intmax (x)
  @result{} 127
@end group
@end example

@seealso{intmin, flintmax}
@end deftypefn
intmin
@c intmin libinterp/corefcn/bitfcns.cc
-*- texinfo -*-
@deftypefn  {} {} intmin ()
@deftypefnx {} {} intmin ("@var{type}")
@deftypefnx {} {} intmin (@var{var})
Return the smallest integer that can be represented by a specific integer type.

The input is either a string @qcode{"@var{type}"} specifying an integer type,
or it is an existing integer variable @var{var}.

Possible values for @var{type} are

@table @asis
@item @qcode{"int8"}
signed 8-bit integer.

@item @qcode{"int16"}
signed 16-bit integer.

@item @qcode{"int32"}
signed 32-bit integer.

@item @qcode{"int64"}
signed 64-bit integer.

@item @qcode{"uint8"}
unsigned 8-bit integer.

@item @qcode{"uint16"}
unsigned 16-bit integer.

@item @qcode{"uint32"}
unsigned 32-bit integer.

@item @qcode{"uint64"}
unsigned 64-bit integer.
@end table

The default for @var{type} is @qcode{"int32"}.

Example Code - query an existing variable

@example
@group
x = int8 (1);
intmin (x)
  @result{} -128
@end group
@end example

@seealso{intmax, flintmax}
@end deftypefn
sizemax
@c sizemax libinterp/corefcn/bitfcns.cc
-*- texinfo -*-
@deftypefn {} {} 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
bsxfun
@c bsxfun libinterp/corefcn/bsxfun.cc
-*- texinfo -*-
@deftypefn {} {} bsxfun (@var{f}, @var{A}, @var{B})
Apply a binary function @var{f} element-by-element to two array arguments
@var{A} and @var{B}, expanding singleton dimensions in either input argument as
necessary.

@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
max_stack_depth
@c max_stack_depth libinterp/corefcn/call-stack.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} max_stack_depth ()
@deftypefnx {} {@var{old_val} =} max_stack_depth (@var{new_val})
@deftypefnx {} {} max_stack_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 @qcode{"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{max_recursion_depth}
@end deftypefn
who
@c who libinterp/corefcn/call-stack.cc
-*- texinfo -*-
@deftypefn  {} {} who
@deftypefnx {} {} who pattern @dots{}
@deftypefnx {} {} who option pattern @dots{}
@deftypefnx {} {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 libinterp/corefcn/call-stack.cc
-*- texinfo -*-
@deftypefn  {} {} whos
@deftypefnx {} {} whos pattern @dots{}
@deftypefnx {} {} whos option pattern @dots{}
@deftypefnx {} {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
cellfun
@c cellfun libinterp/corefcn/cellfun.cc
-*- texinfo -*-
@deftypefn  {} {} cellfun (@var{name}, @var{C})
@deftypefnx {} {} cellfun ("size", @var{C}, @var{k})
@deftypefnx {} {} cellfun ("isclass", @var{C}, @var{class})
@deftypefnx {} {} cellfun (@var{func}, @var{C})
@deftypefnx {} {} cellfun (@var{func}, @var{C}, @var{D})
@deftypefnx {} {[@var{a}, @dots{}] =} cellfun (@dots{})
@deftypefnx {} {} cellfun (@dots{}, "ErrorHandler", @var{errfunc})
@deftypefnx {} {} 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 isnumeric
Return 1 for numeric 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).  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{} [ 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 @qcode{"UniformOutput"} is set to true (the default),
then the function must return scalars which will be concatenated into the
return array(s).  If @qcode{"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{} @{"foo", "bar", "foobar"@}
@end group
@end example

Given the parameter @qcode{"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
@qcode{"identifier"}, @qcode{"message"}, and @qcode{"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{} [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 libinterp/corefcn/cellfun.cc
-*- texinfo -*-
@deftypefn  {} {} arrayfun (@var{func}, @var{A})
@deftypefnx {} {@var{x} =} arrayfun (@var{func}, @var{A})
@deftypefnx {} {@var{x} =} arrayfun (@var{func}, @var{A}, @var{b}, @dots{})
@deftypefnx {} {[@var{x}, @var{y}, @dots{}] =} arrayfun (@var{func}, @var{A}, @dots{})
@deftypefnx {} {} arrayfun (@dots{}, "UniformOutput", @var{val})
@deftypefnx {} {} 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
@code{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{} [ 1.57080   0.00000 ]
@end group
@end example

If the parameter @var{val} after a further string input argument
@qcode{"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{}
   @{
     [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
@qcode{"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 @qcode{"identifier"}, @qcode{"message"}, and
@qcode{"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{}
   @{
     [1,1] = MyString
   @}
@end group
@end example

@seealso{spfun, cellfun, structfun}
@end deftypefn
num2cell
@c num2cell libinterp/corefcn/cellfun.cc
-*- texinfo -*-
@deftypefn  {} {@var{C} =} num2cell (@var{A})
@deftypefnx {} {@var{C} =} num2cell (@var{A}, @var{dim})
Convert the numeric matrix @var{A} to a cell array.

When no @var{dim} is specified, each element of @var{A} becomes a 1x1 element
in the output @var{C}.

If @var{dim} is defined then individual elements of @var{C} contain all of the
elements from @var{A} along the specified dimension.  @var{dim} may also be a
vector of dimensions with the same rule applied.

For example:

@example
x = [1,2;3,4]
@result{}
    1    2
    3    4

## each element of A becomes a 1x1 element of C
num2cell (x)
   @result{}
      @{
        [1,1] =  1
        [2,1] =  3
        [1,2] =  2
        [2,2] =  4
      @}
## all rows (dim 1) of A appear in each element of C
num2cell (x, 1)
   @result{}
      @{
        [1,1] =
           1
           3
        [1,2] =
           2
           4
      @}
## all columns (dim 2) of A appear in each element of C
num2cell (x, 2)
   @result{}
      @{
        [1,1] =
           1   2
        [2,1] =
           3   4
      @}
## all rows and cols appear in each element of C
## (hence, only 1 output)
num2cell (x, [1, 2])
   @result{}
      @{
        [1,1] =
           1   2
           3   4
      @}
@end example

@seealso{mat2cell}
@end deftypefn
mat2cell
@c mat2cell libinterp/corefcn/cellfun.cc
-*- texinfo -*-
@deftypefn  {} {@var{C} =} mat2cell (@var{A}, @var{dim1}, @var{dim2}, @dots{}, @var{dimi}, @dots{}, @var{dimn})
@deftypefnx {} {@var{C} =} mat2cell (@var{A}, @var{rowdim})
Convert the matrix @var{A} to a cell array.

Each dimension argument (@var{dim1}, @var{dim2}, etc.@:) is a vector of
integers which specifies how to divide that dimension's elements amongst the
new elements in the output @var{C}.  The number of elements in the @var{i}-th
dimension is @code{size (@var{A}, @var{i})}.  Because all elements in @var{A}
must be partitioned, there is a requirement that @code{sum (@var{dimi}) == size
(@var{A}, i)}.  The size of the output cell @var{C} is numel (@var{dim1}) x
numel (@var{dim2}) x @dots{} x numel (@var{dimn}).

Given a single dimensional argument, @var{rowdim}, the output is divided into
rows as specified.  All other dimensions are not divided and thus all
columns (dim 2), pages (dim 3), etc.@: appear in each output element.

Examples

@example
x = reshape (1:12, [3, 4])'
@result{}
    1    2    3
    4    5    6
    7    8    9
   10   11   12

@group
## The 4 rows (dim1) are divided in to two cell elements
## with 2 rows each.
## The 3 cols (dim2) are divided in to three cell elements
## with 1 col each.
mat2cell (x, [2,2], [1,1,1])
@result{}
@{
  [1,1] =

     1
     4

  [2,1] =

      7
     10

  [1,2] =

     2
     5

  [2,2] =
      8
     11

  [1,3] =

     3
     6

  [2,3] =
      9
     12
@}
@end group

@group
## The 4 rows (dim1) are divided in to two cell elements
## with a 3/1 split.
## All columns appear in each output element.
mat2cell (x, [3,1])
@result{}
@{
  [1,1] =

     1   2   3
     4   5   6
     7   8   9

  [2,1] =

     10   11   12
@}
@end group
@end example

@seealso{num2cell, cell2mat}
@end deftypefn
cellslices
@c cellslices libinterp/corefcn/cellfun.cc
-*- texinfo -*-
@deftypefn {} {@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 libinterp/corefcn/cellfun.cc
-*- texinfo -*-
@deftypefn {} {@var{y} =} cellindexmat (@var{x}, @var{varargin})
Perform indexing of matrices in a cell array.

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@{1@}, varargin@{2@}, @dots{}, varargin@{N@});
endfor
@end group
@end example

The indexing arguments may be scalar (@code{2}), arrays (@code{[1, 3]}),
ranges (@code{1:3}), or the colon operator (@qcode{":"}).  However, the
indexing keyword @code{end} is not available.
@seealso{cellslices, cellfun}
@end deftypefn
colloc
@c colloc libinterp/corefcn/colloc.cc
-*- texinfo -*-
@deftypefn {} {[@var{r}, @var{amat}, @var{bmat}, @var{q}] =} colloc (@var{n}, "left", "right")
Compute derivative and integral weight matrices for orthogonal collocation.

Reference: @nospell{J. Villadsen}, @nospell{M. L. Michelsen},
@cite{Solution of Differential Equation Models by Polynomial Approximation}.
@end deftypefn
conv2
@c conv2 libinterp/corefcn/conv2.cc
-*- texinfo -*-
@deftypefn  {} {} conv2 (@var{A}, @var{B})
@deftypefnx {} {} conv2 (@var{v1}, @var{v2}, @var{m})
@deftypefnx {} {} 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} = @qcode{"full"}
Return the full convolution.  (default)

@item @var{shape} = @qcode{"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} = @qcode{"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 libinterp/corefcn/conv2.cc
-*- texinfo -*-
@deftypefn  {} {@var{C} =} convn (@var{A}, @var{B})
@deftypefnx {} {@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} = @qcode{"full"}
Return the full convolution.  (default)

@item @var{shape} = @qcode{"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} = @qcode{"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
daspk
@c daspk libinterp/corefcn/daspk.cc
-*- texinfo -*-
@deftypefn {} {[@var{x}, @var{xdot}, @var{istate}, @var{msg}] =} daspk (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
Solve a set of differential-algebraic equations.

@code{daspk} solves the set of 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
@c dasrt libinterp/corefcn/dasrt.cc
-*- texinfo -*-
@deftypefn  {} {[@var{x}, @var{xdot}, @var{t_out}, @var{istat}, @var{msg}] =} dasrt (@var{fcn}, @var{g}, @var{x_0}, @var{xdot_0}, @var{t})
@deftypefnx {} {@dots{} =} dasrt (@var{fcn}, @var{g}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
@deftypefnx {} {@dots{} =} dasrt (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t})
@deftypefnx {} {@dots{} =} dasrt (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
Solve a set of differential-algebraic equations.

@code{dasrt} solves the set of 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
@c dassl libinterp/corefcn/dassl.cc
-*- texinfo -*-
@deftypefn {} {[@var{x}, @var{xdot}, @var{istate}, @var{msg}] =} dassl (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
Solve a set of differential-algebraic equations.

@code{dassl} solves the set of 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
all
@c all libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} all (@var{x})
@deftypefnx {} {} 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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} any (@var{x})
@deftypefnx {} {} 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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} atan2 (@var{y}, @var{x})
Compute atan (@var{y} / @var{x}) for corresponding elements of @var{y}
and @var{x}.

@var{y} and @var{x} must match in size and orientation.  The signs of
elements of @var{y} and @var{x} are used to determine the quadrants of each
resulting value.

This function is equivalent to @code{arg (complex (@var{x}, @var{y}))}.
@seealso{tan, tand, tanh, atanh}
@end deftypefn
hypot
@c hypot libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} hypot (@var{x}, @var{y})
@deftypefnx {} {} 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 is 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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} log2 (@var{x})
@deftypefnx {} {[@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
@w{@code{1/2 <= abs(f) < 1}}
@end ifnottex
and @var{e} is an integer.  If
@tex
$x = 0$, $f = e = 0$.
@end tex
@ifnottex
@w{@code{x = 0}}, @w{@code{f = e = 0}}.
@end ifnottex
@seealso{pow2, log, log10, exp}
@end deftypefn
rem
@c rem libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} rem (@var{x}, @var{y})
Return the remainder of the division @code{@var{x} / @var{y}}.

The remainder is 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 argument is complex.

Programming Notes: When calculating with floating point numbers (double,
single), values within a few eps of an integer will be rounded to that
integer before computation for compatibility with @sc{matlab}.  Any floating
point integers greater than @code{flintmax} (2^53 for double) will not compute
correctly.  For larger integer values convert the input to @code{uint64} before
calling this function.

By convention,

@example
@group
rem (@var{x}, 0) = NaN  if @var{x} is a floating point variable
rem (@var{x}, 0) = 0    if @var{x} is an integer variable
rem (@var{x}, @var{y})  returns a value with the signbit from @var{x}
@end group
@end example

For the opposite conventions see the @code{mod} function.  In general,
@code{rem} is best when computing the remainder after division of two
@emph{positive} numbers.  For negative numbers, or when the values are
periodic, @code{mod} is a better choice.
@seealso{mod}
@end deftypefn
mod
@c mod libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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,
@w{@code{mod (-1, 3)}} is 2, not -1, as @w{@code{rem (-1, 3)}} returns.

An error results if the dimensions of the arguments do not agree, or if
either of the arguments is complex.

Programming Notes: When calculating with floating point numbers (double,
single), values within a few eps of an integer will be rounded to that
integer before computation for compatibility with @sc{matlab}.  Any floating
point integers greater than @code{flintmax} (2^53 for double) will not compute
correctly.  For larger integer values convert the input to @code{uint64} before
calling this function.

By convention,

@example
@group
mod (@var{x}, 0) = @var{x}
mod (@var{x}, @var{y})      returns a value with the signbit from @var{y}
@end group
@end example

For the opposite conventions see the @code{rem} function.  In general,
@code{mod} is a better choice than @code{rem} when any of the inputs are
negative numbers or when the values are periodic.
@seealso{rem}
@end deftypefn
cumprod
@c cumprod libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} cumprod (@var{x})
@deftypefnx {} {} 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.
For example:

@example
@group
cumprod ([1, 2; 3, 4; 5, 6])
   @result{}  1   2
       3   8
      15  48
@end group
@end example
@seealso{prod, cumsum}
@end deftypefn
cumsum
@c cumsum libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} cumsum (@var{x})
@deftypefnx {} {} cumsum (@var{x}, @var{dim})
@deftypefnx {} {} cumsum (@dots{}, "native")
@deftypefnx {} {} cumsum (@dots{}, "double")
Cumulative sum of elements along dimension @var{dim}.

If @var{dim} is omitted, it defaults to the first non-singleton dimension.
For example:

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

See @code{sum} for an explanation of the optional parameters @qcode{"native"}
and @qcode{"double"}.
@seealso{sum, cumprod}
@end deftypefn
diag
@c diag libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {@var{M} =} diag (@var{v})
@deftypefnx {} {@var{M} =} diag (@var{v}, @var{k})
@deftypefnx {} {@var{M} =} diag (@var{v}, @var{m}, @var{n})
@deftypefnx {} {@var{v} =} diag (@var{M})
@deftypefnx {} {@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 superdiagonal.  If it is negative, it is placed on the
@var{-k}-th subdiagonal.  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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} prod (@var{x})
@deftypefnx {} {} prod (@var{x}, @var{dim})
@deftypefnx {} {} prod (@dots{}, "native")
@deftypefnx {} {} prod (@dots{}, "double")
Product of elements along dimension @var{dim}.

If @var{dim} is omitted, it defaults to the first non-singleton dimension.

The optional @qcode{"type"} input determines the class of the variable
used for calculations.  If the argument @qcode{"native"} is given, then
the operation is performed in the same type as the original argument, rather
than the default double type.

For example:

@example
@group
prod ([true, true])
   @result{} 1
prod ([true, true], "native")
   @result{} true
@end group
@end example

On the contrary, if @qcode{"double"} is given, the operation is performed
in double precision even for single precision inputs.
@seealso{cumprod, sum}
@end deftypefn
horzcat
@c horzcat libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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 in 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(:,:,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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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
@w{@code{1:ndims (A)}} (in any order, but each element must appear only
once).  The @var{N}th dimension of @var{A} gets remapped to dimension
@code{@var{PERM}(@var{N})}.  For example:

@example
@group
@var{x} = zeros ([2, 3, 5, 7]);
size (@var{x})
   @result{}  2   3   5   7

size (permute (@var{x}, [2, 1, 3, 4]))
   @result{}  3   2   5   7

size (permute (@var{x}, [1, 3, 4, 2]))
   @result{}  2   5   7   3

## The identity permutation
size (permute (@var{x}, [1, 2, 3, 4]))
   @result{}  2   3   5   7
@end group
@end example
@seealso{ipermute}
@end deftypefn
ipermute
@c ipermute libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} length (@var{a})
Return the length of the object @var{a}.

The length is 0 for empty objects, 1 for scalars, and the number of elements
for vectors.  For matrix or N-dimensional objects, the length is the number
of elements along the largest dimension
(equivalent to @w{@code{max (size (@var{a}))}}).
@seealso{numel, size}
@end deftypefn
ndims
@c ndims libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} ndims (@var{a})
Return the number of dimensions of @var{a}.

For any array, the result will always be greater than or equal to 2.
Trailing singleton dimensions are not counted, i.e., tailing dimensions @var{d}
greater than 2, for which @code{size (@var{a}, @var{d}) = 1}.

@example
@group
ndims (ones (4, 1, 2, 1))
    @result{} 3
@end group
@end example
@seealso{size}
@end deftypefn
numel
@c numel libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} numel (@var{a})
@deftypefnx {} {} 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 scalar numbers.  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}.
Or the index could be the string @qcode{":"} which represents the colon
operator.  For example,

@example
@group
@var{a} = ones (5, 3);
numel (@var{a}, 2, ":")
@end group
@end example

@noindent
will return 3 as the second row has three column entries.

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, length, ndims}
@end deftypefn
size
@c size libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {@var{sz} =} size (@var{a})
@deftypefnx {} {@var{dim_sz} =} size (@var{a}, @var{dim})
@deftypefnx {} {[@var{rows}, @var{cols}, @dots{}, @var{dim_N_sz}] =} size (@dots{})
Return a row vector with the size (number of elements) of each dimension for
the object @var{a}.

When given a second argument, @var{dim}, return the size of the corresponding
dimension.

With a single output argument, @code{size} returns a row vector.  When called
with multiple output arguments, @code{size} returns the size of dimension N
in the Nth argument.  The number of rows, dimension 1, is returned in the
first argument, the number of columns, dimension 2, is returned in the
second argument, etc.  If there are more dimensions in @var{a} than there are
output arguments, @code{size} returns the total number of elements in the
remaining dimensions in the final output argument.

Example 1: single row vector output

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

Example 2: number of elements in 2nd dimension (columns)

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

Example 3: number of output arguments == number of dimensions

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

Example 4: number of output arguments < number of dimensions

@example
@group
[nr, remainder] = size (ones (2, 3, 4, 5))
    @result{} nr = 2
    @result{} remainder = 60
@end group
@end example

@seealso{numel, ndims, length, rows, columns, size_equal, common_size}
@end deftypefn
size_equal
@c size_equal libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} size_equal (@var{a}, @var{b}, @dots{})
Return true if the dimensions of all arguments agree.

Trailing singleton dimensions are ignored.  When called with a single argument,
or no argument, @code{size_equal} returns true.
@seealso{size, numel, ndims, common_size}
@end deftypefn
nnz
@c nnz libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {@var{n} =} nnz (@var{a})
Return the number of nonzero elements in @var{a}.
@seealso{nzmax, nonzeros, find}
@end deftypefn
nzmax
@c nzmax libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {@var{n} =} nzmax (@var{SM})
Return the amount of storage allocated to the sparse matrix @var{SM}.

Programming Note: Octave tends to crop unused memory at the first opportunity
for sparse objects.  Thus, in general the value of @code{nzmax} will be the
same as @code{nnz}, except for some cases of user-created sparse objects.

Also, note that Octave always reserves storage for at least one value.  Thus,
for empty matrices @code{nnz} will report 0, but @code{nzmax} will report 1.
@seealso{nnz, spalloc, sparse}
@end deftypefn
rows
@c rows libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} rows (@var{a})
Return the number of rows of @var{a}.  This is equivalent to
@code{size (@var{a}, 1)}.
@seealso{columns, size, length, numel, isscalar, isvector, ismatrix}
@end deftypefn
columns
@c columns libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} columns (@var{a})
Return the number of columns of @var{a}.  This is equivalent to
@code{size (@var{a}, 2)}.
@seealso{rows, size, length, numel, isscalar, isvector, ismatrix}
@end deftypefn
sum
@c sum libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} sum (@var{x})
@deftypefnx {} {} sum (@var{x}, @var{dim})
@deftypefnx {} {} sum (@dots{}, "native")
@deftypefnx {} {} sum (@dots{}, "double")
@deftypefnx {} {} sum (@dots{}, "extra")
Sum of elements along dimension @var{dim}.

If @var{dim} is omitted, it defaults to the first non-singleton dimension.

The optional @qcode{"type"} input determines the class of the variable
used for calculations.  By default, operations on floating point inputs (double
or single) are performed in their native data type, while operations on
integer, logical, and character data types are performed using doubles.  If the
argument @qcode{"native"} is given, then the operation is performed in the same
type as the original argument.

For example:

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

If @qcode{"double"} is given the sum is performed in double precision even for
single precision inputs.

For double precision inputs, the @qcode{"extra"} option will use a more
accurate algorithm than straightforward summation.  For single precision
inputs, @qcode{"extra"} is the same as @qcode{"double"}.  For all other data
type @qcode{"extra"} has no effect.
@seealso{cumsum, sumsq, prod}
@end deftypefn
sumsq
@c sumsq libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} sumsq (@var{x})
@deftypefnx {} {} 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, prod}
@end deftypefn
islogical
@c islogical libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} islogical (@var{x})
@deftypefnx {} {} isbool (@var{x})
Return true if @var{x} is a logical object.
@seealso{ischar, isfloat, isinteger, isstring, isnumeric, isa}
@end deftypefn
isinteger
@c isinteger libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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, isstring, isnumeric, isa}
@end deftypefn
iscomplex
@c iscomplex libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} iscomplex (@var{x})
Return true if @var{x} is a complex-valued numeric object.
@seealso{isreal, isnumeric, ischar, isfloat, islogical, isstring, isa}
@end deftypefn
isfloat
@c isfloat libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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, isstring, isa}
@end deftypefn
complex
@c complex libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} complex (@var{x})
@deftypefnx {} {} complex (@var{re}, @var{im})
Return a complex value from real arguments.

With 1 real argument @var{x}, return the complex result
@w{@code{@var{x} + 0i}}.

With 2 real arguments, return the complex result
@w{@code{@var{re} + @var{im}i}}.
@code{complex} can often be more convenient than expressions such as
@w{@code{a + b*i}}.
For example:

@example
@group
complex ([1, 2], [3, 4])
  @result{} [ 1 + 3i   2 + 4i ]
@end group
@end example
@seealso{real, imag, iscomplex, abs, arg}
@end deftypefn
isreal
@c isreal libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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, isa}
@end deftypefn
isempty
@c isempty libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} isempty (@var{a})
Return true if @var{a} is an empty matrix (any one of its dimensions is
zero).
@seealso{isnull, isa}
@end deftypefn
isnumeric
@c isnumeric libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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, ischar, islogical, isstring, iscell, isstruct, isa}
@end deftypefn
isscalar
@c isscalar libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} isscalar (@var{x})
Return true if @var{x} is a scalar, i.e., @code{size (@var{x})} returns
@code{[1 1]}.
@seealso{isvector, ismatrix}
@end deftypefn
isvector
@c isvector libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} isvector (@var{x})
Return true if @var{x} is a vector.

A vector is a 2-D array where one of the dimensions is equal to 1.  As a
consequence a 1x1 array, or scalar, is also a vector.
@seealso{isscalar, ismatrix, size, rows, columns, length}
@end deftypefn
isrow
@c isrow libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} isrow (@var{x})
Return true if @var{x} is a row vector, i.e., @code{size (@var{x})} returns
@code{[1 N]} with non-negative N.
@seealso{iscolumn, isscalar, isvector, ismatrix}
@end deftypefn
iscolumn
@c iscolumn libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} iscolumn (@var{x})
Return true if @var{x} is a column vector, i.e., @code{size (@var{x})} returns
@code{[N 1]} with non-negative N.
@seealso{isrow, isscalar, isvector, ismatrix}
@end deftypefn
ismatrix
@c ismatrix libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} ismatrix (@var{a})
Return true if @var{a} is a 2-D array, i.e., @code{size (@var{a})} returns
@code{[M N]} with non-negative M and N.
@seealso{isscalar, isvector, iscell, isstruct, issparse, isa}
@end deftypefn
issquare
@c issquare libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} issquare (@var{x})
Return true if @var{x} is a square matrix, i.e., @code{size (@var{x})} returns
@code{[N N]} with non-negative N.
@seealso{isscalar, isvector, ismatrix, size}
@end deftypefn
ones
@c ones libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} ones (@var{n})
@deftypefnx {} {} ones (@var{m}, @var{n})
@deftypefnx {} {} ones (@var{m}, @var{n}, @var{k}, @dots{})
@deftypefnx {} {} ones ([@var{m} @var{n} @dots{}])
@deftypefnx {} {} 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.

To create a constant matrix whose values are all the same use an expression
such as

@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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} zeros (@var{n})
@deftypefnx {} {} zeros (@var{m}, @var{n})
@deftypefnx {} {} zeros (@var{m}, @var{n}, @var{k}, @dots{})
@deftypefnx {} {} zeros ([@var{m} @var{n} @dots{}])
@deftypefnx {} {} 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 libinterp/corefcn/data.cc
-*- texinfo -*-
@c List other form of function in documentation index
@findex inf

@deftypefn  {} {} Inf
@deftypefnx {} {} Inf (@var{n})
@deftypefnx {} {} Inf (@var{n}, @var{m})
@deftypefnx {} {} Inf (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {} {} 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
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 @qcode{"double"} or @qcode{"single"}.
@seealso{isinf, NaN}
@end deftypefn
NaN
@c NaN libinterp/corefcn/data.cc
-*- texinfo -*-
@c List other form of function in documentation index
@findex nan

@deftypefn  {} {} NaN
@deftypefnx {} {} NaN (@var{n})
@deftypefnx {} {} NaN (@var{n}, @var{m})
@deftypefnx {} {} NaN (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {} {} 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 @qcode{"double"} or @qcode{"single"}.
@seealso{isnan, Inf}
@end deftypefn
e
@c e libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} e
@deftypefnx {} {} e (@var{n})
@deftypefnx {} {} e (@var{n}, @var{m})
@deftypefnx {} {} e (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {} {} 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 @qcode{"double"} or @qcode{"single"}.
@seealso{log, exp, pi, I}
@end deftypefn
eps
@c eps libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} eps
@deftypefnx {} {} eps (@var{x})
@deftypefnx {} {} eps (@var{n}, @var{m})
@deftypefnx {} {} eps (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {} {} 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 @qcode{"double"} or @qcode{"single"}.
@seealso{realmax, realmin, intmax, flintmax}
@end deftypefn
pi
@c pi libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} pi
@deftypefnx {} {} pi (@var{n})
@deftypefnx {} {} pi (@var{n}, @var{m})
@deftypefnx {} {} pi (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {} {} 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 @qcode{"double"} or @qcode{"single"}.
@seealso{e, I}
@end deftypefn
realmax
@c realmax libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} realmax
@deftypefnx {} {} realmax (@var{n})
@deftypefnx {} {} realmax (@var{n}, @var{m})
@deftypefnx {} {} realmax (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {} {} 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 (@qcode{"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 @qcode{"double"} or @qcode{"single"}.
@seealso{realmin, intmax, flintmax, eps}
@end deftypefn
realmin
@c realmin libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} realmin
@deftypefnx {} {} realmin (@var{n})
@deftypefnx {} {} realmin (@var{n}, @var{m})
@deftypefnx {} {} realmin (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {} {} 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 (@qcode{"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 @qcode{"double"} or @qcode{"single"}.
@seealso{realmax, intmin, eps}
@end deftypefn
I
@c I libinterp/corefcn/data.cc
-*- texinfo -*-
@c List other forms of function in documentation index
@findex i
@findex j
@findex J

@deftypefn  {} {} I
@deftypefnx {} {} I (@var{n})
@deftypefnx {} {} I (@var{n}, @var{m})
@deftypefnx {} {} I (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {} {} 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
@w{@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 @qcode{"double"} or @qcode{"single"}.
@seealso{e, pi, log, exp}
@end deftypefn
NA
@c NA libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} NA
@deftypefnx {} {} NA (@var{n})
@deftypefnx {} {} NA (@var{n}, @var{m})
@deftypefnx {} {} NA (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {} {} 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 @qcode{"double"} or @qcode{"single"}.
@seealso{isna}
@end deftypefn
false
@c false libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} false (@var{x})
@deftypefnx {} {} false (@var{n}, @var{m})
@deftypefnx {} {} 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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} true (@var{x})
@deftypefnx {} {} true (@var{n}, @var{m})
@deftypefnx {} {} 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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} eye (@var{n})
@deftypefnx {} {} eye (@var{m}, @var{n})
@deftypefnx {} {} eye ([@var{m} @var{n}])
@deftypefnx {} {} 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, ones, zeros}
@end deftypefn
linspace
@c linspace libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} linspace (@var{start}, @var{end})
@deftypefnx {} {} linspace (@var{start}, @var{end}, @var{n})
Return a row vector with @var{n} linearly spaced elements between @var{start}
and @var{end}.

If the number of elements is greater than one, then the endpoints @var{start}
and @var{end} are always included in the range.  If @var{start} is greater than
@var{end}, 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 returns a row vector when both @var{start} and
@var{end} are scalars.  If one, or both, inputs are vectors, then
@code{linspace} transforms them to column vectors and returns a matrix where
each row is an independent sequence between
@w{@code{@var{start}(@var{row_n}), @var{end}(@var{row_n})}}.

For compatibility with @sc{matlab}, return the second argument (@var{end}) when
only a single value (@var{n} = 1) is requested.
@seealso{colon, logspace}
@end deftypefn
resize
@c resize libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} resize (@var{x}, @var{m})
@deftypefnx {} {} resize (@var{x}, @var{m}, @var{n}, @dots{})
@deftypefnx {} {} 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, prepad, cat}
@end deftypefn
reshape
@c reshape libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} reshape (@var{A}, @var{m}, @var{n}, @dots{})
@deftypefnx {} {} reshape (@var{A}, [@var{m} @var{n} @dots{}])
@deftypefnx {} {} reshape (@var{A}, @dots{}, [], @dots{})
@deftypefnx {} {} 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, vec, postpad, cat, squeeze}
@end deftypefn
vec
@c vec libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {@var{v} =} vec (@var{x})
@deftypefnx {} {@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, resize, cat}
@end deftypefn
squeeze
@c squeeze libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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.
@seealso{reshape}
@end deftypefn
full
@c full libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {@var{FM} =} full (@var{SM})
Return a full storage matrix from a sparse, diagonal, or permutation matrix,
or a range.
@seealso{sparse, issparse}
@end deftypefn
norm
@c norm libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} norm (@var{A})
@deftypefnx {} {} norm (@var{A}, @var{p})
@deftypefnx {} {} norm (@var{A}, @var{p}, @var{opt})
Compute the p-norm of the matrix @var{A}.

If the second argument is not given, @w{@code{p = 2}} is used.

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 @qcode{"inf"}
@cindex infinity norm
Infinity norm, the largest row sum of the absolute values of @var{A}.

@item @var{p} = @qcode{"fro"}
@cindex @nospell{Frobenius} norm
@nospell{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 @qcode{"inf"}
@code{max (abs (@var{A}))}.

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

@item @var{p} = @qcode{"fro"}
@nospell{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 @qcode{"rows"}, treat each row as a vector and
compute its norm.  The result is returned as a column vector.
Similarly, if @var{opt} is @qcode{"columns"} or @qcode{"cols"} then
compute the norms of each column and return a row vector.
@seealso{normest, normest1, vecnorm, cond, svd}
@end deftypefn
not
@c not libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {@var{z} =} not (@var{x})
Return the logical NOT of @var{x}.

This function is equivalent to the operator syntax @w{@code{! @var{x}}}.
@seealso{and, or, xor}
@end deftypefn
uplus
@c uplus libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} uplus (@var{x})
This function and @w{@tcode{+ @var{x}}} are equivalent.
@seealso{uminus, plus, minus}
@end deftypefn
uminus
@c uminus libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} uminus (@var{x})
This function and @w{@tcode{- @var{x}}} are equivalent.
@seealso{uplus, minus}
@end deftypefn
transpose
@c transpose libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} transpose (@var{x})
Return the transpose of @var{x}.

This function and @tcode{@var{x}.'} are equivalent.
@seealso{ctranspose}
@end deftypefn
ctranspose
@c ctranspose libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} ctranspose (@var{x})
Return the complex conjugate transpose of @var{x}.

This function and @tcode{@var{x}'} are equivalent.
@seealso{transpose}
@end deftypefn
plus
@c plus libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} plus (@var{x}, @var{y})
@deftypefnx {} {} plus (@var{x1}, @var{x2}, @dots{})
This function and @w{@tcode{@var{x} + @var{y}}} are equivalent.

If more arguments are given, the summation is applied
cumulatively from left to right:

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

@seealso{minus, uplus}
@end deftypefn
minus
@c minus libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} minus (@var{x}, @var{y})
This function and @w{@tcode{@var{x} - @var{y}}} are equivalent.
@seealso{plus, uminus}
@end deftypefn
mtimes
@c mtimes libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} mtimes (@var{x}, @var{y})
@deftypefnx {} {} mtimes (@var{x1}, @var{x2}, @dots{})
Return the matrix multiplication product of inputs.

This function and @w{@tcode{@var{x} * @var{y}}} are equivalent.
If more arguments are given, the multiplication is applied
cumulatively from left to right:

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

@seealso{times, plus, minus, rdivide, mrdivide, mldivide, mpower}
@end deftypefn
mrdivide
@c mrdivide libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} mrdivide (@var{x}, @var{y})
Return the matrix right division of @var{x} and @var{y}.

This function and @w{@tcode{@var{x} / @var{y}}} are equivalent.
@seealso{mldivide, rdivide, plus, minus}
@end deftypefn
mpower
@c mpower libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} mpower (@var{x}, @var{y})
Return the matrix power operation of @var{x} raised to the @var{y} power.

This function and @w{@tcode{@var{x} ^ @var{y}}} are equivalent.
@seealso{power, mtimes, plus, minus}
@end deftypefn
mldivide
@c mldivide libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} mldivide (@var{x}, @var{y})
Return the matrix left division of @var{x} and @var{y}.

This function and @w{@tcode{@var{x} @xbackslashchar{} @var{y}}} are equivalent.
@seealso{mrdivide, ldivide, rdivide}
@end deftypefn
lt
@c lt libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} lt (@var{x}, @var{y})
This function is equivalent to @w{@code{@var{x} < @var{y}}}.
@seealso{le, eq, ge, gt, ne}
@end deftypefn
le
@c le libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} le (@var{x}, @var{y})
This function is equivalent to @w{@code{@var{x} <= @var{y}}}.
@seealso{eq, ge, gt, ne, lt}
@end deftypefn
eq
@c eq libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} eq (@var{x}, @var{y})
Return true if the two inputs are equal.

This function is equivalent to @w{@code{@var{x} == @var{y}}}.
@seealso{ne, isequal, le, ge, gt, ne, lt}
@end deftypefn
ge
@c ge libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} ge (@var{x}, @var{y})
This function is equivalent to @w{@code{@var{x} >= @var{y}}}.
@seealso{le, eq, gt, ne, lt}
@end deftypefn
gt
@c gt libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} gt (@var{x}, @var{y})
This function is equivalent to @w{@code{@var{x} > @var{y}}}.
@seealso{le, eq, ge, ne, lt}
@end deftypefn
ne
@c ne libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} ne (@var{x}, @var{y})
Return true if the two inputs are not equal.

This function is equivalent to @w{@code{@var{x} != @var{y}}}.
@seealso{eq, isequal, le, ge, lt}
@end deftypefn
times
@c times libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} times (@var{x}, @var{y})
@deftypefnx {} {} times (@var{x1}, @var{x2}, @dots{})
Return the element-by-element multiplication product of inputs.

This function and @w{@tcode{@var{x} .* @var{y}}} are equivalent.
If more arguments are given, the multiplication is applied
cumulatively from left to right:

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

@seealso{mtimes, rdivide}
@end deftypefn
rdivide
@c rdivide libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} rdivide (@var{x}, @var{y})
Return the element-by-element right division of @var{x} and @var{y}.

This function and @w{@tcode{@var{x} ./ @var{y}}} are equivalent.
@seealso{ldivide, mrdivide, times, plus}
@end deftypefn
power
@c power libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} power (@var{x}, @var{y})
Return the element-by-element operation of @var{x} raised to the
@var{y} power.

This function and @w{@tcode{@var{x} .^ @var{y}}} are equivalent.

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.

@seealso{mpower, realpow, realsqrt, cbrt, nthroot}
@end deftypefn
ldivide
@c ldivide libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} ldivide (@var{x}, @var{y})
Return the element-by-element left division of @var{x} and @var{y}.

This function and @w{@tcode{@var{x} .@xbackslashchar{} @var{y}}} are
equivalent.
@seealso{rdivide, mldivide, times, plus}
@end deftypefn
and
@c and libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {@var{z} =} and (@var{x}, @var{y})
@deftypefnx {} {@var{z} =} and (@var{x1}, @var{x2}, @dots{})
Return the logical AND of @var{x} and @var{y}.

This function is equivalent to the operator syntax
@w{@code{@var{x} & @var{y}}}.  If more than two arguments are given, the
logical AND is applied cumulatively from left to right:

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

@seealso{or, not, xor}
@end deftypefn
or
@c or libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {@var{z} =} or (@var{x}, @var{y})
@deftypefnx {} {@var{z} =} or (@var{x1}, @var{x2}, @dots{})
Return the logical OR of @var{x} and @var{y}.

This function is equivalent to the operator syntax
@w{@code{@var{x} | @var{y}}}.  If more than two arguments are given, the
logical OR is applied cumulatively from left to right:

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

@seealso{and, not, xor}
@end deftypefn
colon
@c colon libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {@var{r} =} colon (@var{base}, @var{limit})
@deftypefnx {} {@var{r} =} colon (@var{base}, @var{increment}, @var{limit})
Return the result of the colon expression corresponding to @var{base},
@var{limit}, and optionally, @var{increment}.

This function is equivalent to the operator syntax
@w{@code{@var{base} : @var{limit}}} or
@w{@code{@var{base} : @var{increment} : @var{limit}}}.
@seealso{linspace}
@end deftypefn
tic
@c tic libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} tic ()
@deftypefnx {} {@var{id} =} tic ()
Initialize a wall-clock timer.

Calling @code{tic} without an output argument resets the internal timer.
Subsequent calls to @code{toc} return the number of seconds since the timer was
set.

If called with one output argument, @code{tic} creates a new timer instance and
returns a timer identifier @var{id}.  The @var{id} is a scalar of type
@code{uint64} that may be passed to @code{toc} to check elapsed time on this
timer, rather than the default internal timer.

Example 1 : benchmarking code with internal timer

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

Example 2 : mixed timer id and internal timer

@example
@group
tic;
pause (1);
toc
@result{} Elapsed time is 1.0089 seconds.
id = tic;
pause (2);
toc (id)
@result{} Elapsed time is 2.01142 seconds.
toc
Elapsed time is 3.02308 seconds.
@end group
@end example

@noindent
Calling @code{tic} and @code{toc} in this way allows nested timing calls.

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.
@seealso{toc, cputime}
@end deftypefn
toc
@c toc libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} toc ()
@deftypefnx {} {} toc (@var{id})
@deftypefnx {} {@var{elapsed_time} =} toc (@dots{})
Measure elapsed time on a wall-clock timer.

With no arguments, return the number of seconds elapsed on the internal timer
since the last call to @code{tic}.

When given the identifier @var{id} of a specific timer, return the number of
seconds elapsed since the timer @var{id} was initialized.

@xref{XREFtic, , tic}, for examples of the use of @code{tic}/@code{toc}.

@seealso{tic, cputime}
@end deftypefn
cputime
@c cputime libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {[@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.
@seealso{tic, toc}
@end deftypefn
sort
@c sort libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {[@var{s}, @var{i}] =} sort (@var{x})
@deftypefnx {} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim})
@deftypefnx {} {[@var{s}, @var{i}] =} sort (@var{x}, @var{mode})
@deftypefnx {} {[@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 @var{mode}
defines the order in which the values will be sorted.  Valid values of
@var{mode} are @qcode{"ascend"} or @qcode{"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
(@w{@code{abs (@var{z})}}) and for any ties by phase angle
(@w{@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.
@seealso{sortrows, issorted}
@end deftypefn
__sort_rows_idx__
@c __sort_rows_idx__ libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} __sort_rows_idx__ (@var{a}, @var{mode})
Undocumented internal function.
@end deftypefn
issorted
@c issorted libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} issorted (@var{a})
@deftypefnx {} {} issorted (@var{a}, @var{mode})
@deftypefnx {} {} issorted (@var{a}, "rows", @var{mode})
Return true if the array is sorted according to @var{mode}, which may be either
@qcode{"ascend"}, @qcode{"descend"}, or @qcode{"either"}.

By default, @var{mode} is @qcode{"ascend"}.  NaNs are treated in the same
manner as @code{sort}.

If the optional argument @qcode{"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 libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} nth_element (@var{x}, @var{n})
@deftypefnx {} {} nth_element (@var{x}, @var{n}, @var{dim})
Select the n-th smallest element of a vector, using the ordering defined by
@code{sort}.

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.

Programming Note: 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__ libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} __accumarray_sum__ (@var{idx}, @var{vals}, @var{n})
Undocumented internal function.
@end deftypefn
__accumarray_min__
@c __accumarray_min__ libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} __accumarray_min__ (@var{idx}, @var{vals}, @var{zero}, @var{n})
Undocumented internal function.
@end deftypefn
__accumarray_max__
@c __accumarray_max__ libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} __accumarray_max__ (@var{idx}, @var{vals}, @var{zero}, @var{n})
Undocumented internal function.
@end deftypefn
__accumdim_sum__
@c __accumdim_sum__ libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} __accumdim_sum__ (@var{idx}, @var{vals}, @var{dim}, @var{n})
Undocumented internal function.
@end deftypefn
merge
@c merge libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} merge (@var{mask}, @var{tval}, @var{fval})
@deftypefnx {} {} 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, diff}
@end deftypefn
diff
@c diff libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {} diff (@var{x})
@deftypefnx {} {} diff (@var{x}, @var{k})
@deftypefnx {} {} diff (@var{x}, @var{k}, @var{dim})
If @var{x} is a vector of length @math{n}, @w{@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, @w{@code{diff (@var{x})}} is the matrix of column
differences along the first non-singleton dimension.

The second argument is optional.  If supplied,
@w{@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 @w{@code{size (@var{x}, @var{dim})}}
an empty matrix is returned.
@seealso{sort, merge}
@end deftypefn
repelems
@c repelems libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {} 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, cat}
@end deftypefn
base64_encode
@c base64_encode libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn {} {@var{s} =} base64_encode (@var{x})
Encode a double matrix or array @var{x} into the base64 format string
@var{s}.

@seealso{base64_decode}
@end deftypefn
base64_decode
@c base64_decode libinterp/corefcn/data.cc
-*- texinfo -*-
@deftypefn  {} {@var{x} =} base64_decode (@var{s})
@deftypefnx {} {@var{x} =} base64_decode (@var{s}, @var{dims})
Decode the double matrix or array @var{x} from the base64 encoded string
@var{s}.

The optional input parameter @var{dims} should be a vector containing the
dimensions of the decoded array.
@seealso{base64_encode}
@end deftypefn
dbstop
@c dbstop libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn  {} {} dbstop @var{func}
@deftypefnx {} {} dbstop @var{func} @var{line}
@deftypefnx {} {} dbstop @var{func} @var{line1} @var{line2} @dots{}
@deftypefnx {} {} dbstop @var{line1} @dots{}
@deftypefnx {} {} dbstop in @var{func}
@deftypefnx {} {} dbstop in @var{func} at @var{line}
@deftypefnx {} {} dbstop in @var{func} at @var{line} if "@var{condition}"
@deftypefnx {} {} dbstop if @var{event}
@deftypefnx {} {} dbstop if @var{event} @var{ID}
@deftypefnx {} {} dbstop (@var{bp_struct})
@deftypefnx {} {@var{rline} =} dbstop @dots{}

Set breakpoints for the built-in debugger.

@var{func} is the name of a function on the current @code{path}.  When
already in debug mode the @var{func} argument can be omitted and the current
function will be used.  Breakpoints at subfunctions are set with the scope
operator @samp{>}.  For example, If @file{file.m} has a subfunction
@code{func2}, then a breakpoint in @code{func2} can be specified by
@code{file>func2}.

@var{line} is the line number at which to break.  If @var{line} is not
specified, it defaults to the first executable line in the file
@file{func.m}.  Multiple lines can be specified in a single command; when
function syntax is used, the lines may also be passed as a single vector
argument (@code{[@var{line1}, @var{line2}, @dots{}]}).

@var{condition} is any Octave expression that can be evaluated in the code
context that exists at the breakpoint.  When the breakpoint is encountered,
@var{condition} will be evaluated, and execution will stop if
@var{condition} is true.  If @var{condition} cannot be evaluated, for
example because it refers to an undefined variable, an error will be thrown.
 Expressions with side effects (such as @code{y++ > 1}) will alter
variables, and should generally be avoided.  Conditions containing quotes
(@samp{"}, @samp{'}) or comment characters (@samp{#}, @samp{%}) must be
enclosed in quotes.  (This does not apply to conditions entered from the
editor's context menu.)  For example:

@example
dbstop in axis at 246 if 'any (opt == "x")'
@end example

The form specifying @var{event} does not cause a specific breakpoint at a
given function and line number.  Instead it causes debug mode to be entered
when certain unexpected events are encountered.  Possible values are

@table @code
@item error
Stop when an error is reported.  This is equivalent to specifying
both @code{debug_on_error (true)} and @code{debug_on_interrupt (true)}.

@item caught error
Stop when an error is caught by a try-catch block (not yet implemented).

@item interrupt
Stop when an interrupt (@kbd{Ctrl-C}) occurs.

@item naninf
Stop when code returns a non-finite value (not yet implemented).

@item warning
Stop when a warning is reported.  This is equivalent to specifying
@code{debug_on_warning (true)}.
@end table

The events @code{error}, @code{caught error}, and @code{warning} can all be
followed by a string specifying an error ID or warning ID@.  If that is
done, only errors with the specified ID will cause execution to stop.  To
stop on one of a set of IDs, multiple @code{dbstop} commands must be
issued.

Breakpoints and events can be removed using the @code{dbclear} command with
the same syntax.

It is possible to save all breakpoints and restore them at once by issuing
the commands @code{bp_state = dbstatus; @dots{}; dbstop (bp_state)}.

The optional output @var{rline} is the real line number where the breakpoint
was set.  This can differ from the 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.

When a file is re-parsed, such as when it is modified outside the GUI,
all breakpoints within the file are cleared.

@seealso{dbclear, dbstatus, dbstep, debug_on_error, debug_on_warning, debug_on_interrupt}
@end deftypefn
dbclear
@c dbclear libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn  {} {} dbclear @var{func}
@deftypefnx {} {} dbclear @var{func} @var{line}
@deftypefnx {} {} dbclear @var{func} @var{line1} @var{line2} @dots{}
@deftypefnx {} {} dbclear @var{line} @dots{}
@deftypefnx {} {} dbclear all
@deftypefnx {} {} dbclear in @var{func}
@deftypefnx {} {} dbclear in @var{func} at @var{line}
@deftypefnx {} {} dbclear if @var{event}
@deftypefnx {} {} dbclear ("@var{func}")
@deftypefnx {} {} dbclear ("@var{func}", @var{line})
@deftypefnx {} {} dbclear ("@var{func}", @var{line1}, @var{line2}, @dots{})
@deftypefnx {} {} dbclear ("@var{func}", @var{line1}, @dots{})
@deftypefnx {} {} dbclear (@var{line}, @dots{})
@deftypefnx {} {} dbclear ("all")
Delete a breakpoint at line number @var{line} in the function @var{func}.

Arguments are

@table @var
@item func
Function name as a string variable.  When already in debug mode this
argument can be omitted and the current function will be used.

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

@item event
An event such as @code{error}, @code{interrupt}, or @code{warning}
(@pxref{XREFdbstop,,dbstop} for details).
@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.

The special keyword @qcode{"all"} will clear all breakpoints from all
files.
@seealso{dbstop, dbstatus, dbwhere}
@end deftypefn
dbstatus
@c dbstatus libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn  {} {} dbstatus
@deftypefnx {} {} dbstatus @var{func}
@deftypefnx {} {@var{bp_list} =} dbstatus @dots{}
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 and its subfunctions.

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

@table @asis
@item name
The name of the function with a breakpoint.  A subfunction, say @code{func2}
within an m-file, say @file{file.m}, is specified as @code{file>func2}.

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

@item line
The line number with the breakpoint.

@item cond
The condition that must be satisfied for the breakpoint to be active, or
the empty string for unconditional breakpoints.
@end table

@c Note: When @code{dbstatus} is called from the debug prompt within a function,
@c the list of breakpoints is automatically trimmed to the breakpoints in the
@c current function.
If @code{dbstop if error} is true but no explicit IDs are specified, the
return value will have an empty field called @qcode{"errs"}.  If IDs are
specified, the @code{errs} field will have one row per ID@.  If
@code{dbstop if error} is false, there is no @qcode{"errs"} field.
The @qcode{"warn"} field is set similarly by @code{dbstop if warning}.

@seealso{dbstop, dbclear, dbwhere, dblist, dbstack}
@end deftypefn
dbwhere
@c dbwhere libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn {} {} dbwhere
In debugging mode, report the current file and line number where execution
is stopped.
@seealso{dbstack, dblist, dbstatus, dbcont, dbstep, dbup, dbdown}
@end deftypefn
dbtype
@c dbtype libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn  {} {} dbtype
@deftypefnx {} {} dbtype @var{lineno}
@deftypefnx {} {} dbtype @var{startl:endl}
@deftypefnx {} {} dbtype @var{startl:end}
@deftypefnx {} {} dbtype @var{func}
@deftypefnx {} {} dbtype @var{func} @var{lineno}
@deftypefnx {} {} dbtype @var{func} @var{startl:endl}
@deftypefnx {} {} dbtype @var{func} @var{startl:end}
Display a script file with line numbers.

When called with no arguments in debugging mode, display the script file
currently being debugged.

An optional range specification can be used to list only a portion of the
file.  The special keyword @qcode{"end"} is a valid line number
specification for the last line of the file.

When called with the name of a function, list that script file with line
numbers.
@seealso{dblist, dbwhere, dbstatus, dbstop}
@end deftypefn
dblist
@c dblist libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn  {} {} dblist
@deftypefnx {} {} dblist @var{n}
In debugging mode, list @var{n} lines of the function being debugged
centered around the current line to be executed.

If unspecified @var{n} defaults to 10 (+/- 5 lines)
@seealso{dbwhere, dbtype, dbstack}
@end deftypefn
dbstack
@c dbstack libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn  {} {} dbstack
@deftypefnx {} {} dbstack @var{n}
@deftypefnx {} {} dbstack @var{-completenames}
@deftypefnx {} {[@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.

Although accepted, the argument @var{-completenames} is silently ignored.
Octave always returns absolute filenames.

The arguments @var{n} and @var{-completenames} can be both specified in any
order.

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, dblist, dbstatus}
@end deftypefn
dbup
@c dbup libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn  {} {} dbup
@deftypefnx {} {} 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 libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn  {} {} dbdown
@deftypefnx {} {} 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 libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn  {} {} dbstep
@deftypefnx {} {} dbstep @var{n}
@deftypefnx {} {} dbstep in
@deftypefnx {} {} dbstep out
@deftypefnx {} {} 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 libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn {} {} dbcont
Leave command-line debugging mode and continue code execution normally.
@seealso{dbstep, dbquit}
@end deftypefn
dbquit
@c dbquit libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn {} {} dbquit
Quit debugging mode immediately without further code execution and return to
the Octave prompt.
@seealso{dbcont, dbstep}
@end deftypefn
isdebugmode
@c isdebugmode libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn {} {} isdebugmode ()
Return true if in debugging mode, otherwise false.
@seealso{dbwhere, dbstack, dbstatus}
@end deftypefn
__db_next_breakpoint_quiet__
@c __db_next_breakpoint_quiet__ libinterp/corefcn/debug.cc
-*- texinfo -*-
@deftypefn  {} {} __db_next_breakpoint_quiet__ ()
@deftypefnx {} {} __db_next_breakpoint_quiet__ (@var{flag})
Disable line info printing at the next breakpoint.

With a logical argument @var{flag}, set the state on or off.
@end deftypefn
OCTAVE_HOME
@c OCTAVE_HOME libinterp/corefcn/defaults.cc
-*- texinfo -*-
@deftypefn {} {} OCTAVE_HOME ()
Return the name of the top-level Octave installation directory.
OCTAVE_HOME corresponds to the configuration variable @var{prefix}.
@seealso{EXEC_PATH, IMAGE_PATH, OCTAVE_EXEC_HOME}
@end deftypefn
OCTAVE_EXEC_HOME
@c OCTAVE_EXEC_HOME libinterp/corefcn/defaults.cc
-*- texinfo -*-
@deftypefn {} {} OCTAVE_EXEC_HOME ()
Return the name of the top-level Octave installation directory for
architecture-dependent files.  If not specified separately, the value
is the same as OCTAVE_HOME@.  OCTAVE_EXEC_HOME corresponds to the
configuration variable @var{exec_prefix}.
@seealso{EXEC_PATH, IMAGE_PATH, OCTAVE_HOME}
@end deftypefn
OCTAVE_VERSION
@c OCTAVE_VERSION libinterp/corefcn/defaults.cc
-*- texinfo -*-
@deftypefn {} {} OCTAVE_VERSION ()
Return the version number of Octave as a string.
@seealso{ver, version}
@end deftypefn
det
@c det libinterp/corefcn/det.cc
-*- texinfo -*-
@deftypefn  {} {} det (@var{A})
@deftypefnx {} {[@var{d}, @var{rcond}] =} det (@var{A})
Compute the determinant of @var{A}.

Return an estimate of the reciprocal condition number if requested.

Programming Notes: 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
cd
@c cd libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn  {} {} cd @var{dir}
@deftypefnx {} {} cd
@deftypefnx {} {@var{old_dir} =} cd (@var{dir})
@deftypefnx {} {} chdir @dots{}
Change the current working directory to @var{dir}.

If @var{dir} is omitted, the current directory is changed to the user's home
directory (@qcode{"~"}).

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.

@code{chdir} is an alias for @code{cd} and can be used in all of the same
calling formats.

Compatibility Note: When called with no arguments, @sc{matlab} prints the
present working directory rather than changing to the user's home directory.
@seealso{pwd, mkdir, rmdir, dir, ls}
@end deftypefn
pwd
@c pwd libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn  {} {} pwd ()
@deftypefnx {} {@var{dir} =} pwd ()
Return the current working directory.
@seealso{cd, dir, ls, mkdir, rmdir}
@end deftypefn
readdir
@c readdir libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn  {} {@var{files} =} readdir (@var{dir})
@deftypefnx {} {[@var{files}, @var{err}, @var{msg}] =} readdir (@var{dir})
Return the names of 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, what}
@end deftypefn
__mkdir__
@c __mkdir__ libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn {} {} __mkdir__ (@var{parent}, @var{dir})
Internal function called by mkdir.m.
@seealso{mkdir, rmdir, pwd, cd, umask}
@end deftypefn
rmdir
@c rmdir libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn  {} {} rmdir @var{dir}
@deftypefnx {} {} rmdir (@var{dir}, "s")
@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} rmdir (@dots{})
Remove the directory named @var{dir}.

If the optional second parameter is supplied with value @qcode{"s"},
recursively remove all subdirectories as well.

If successful, @var{status} is 1, and @var{msg}, @var{msgid} are 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{mkdir, confirm_recursive_rmdir, pwd}
@end deftypefn
link
@c link libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn  {} {} link @var{old} @var{new}
@deftypefnx {} {[@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, unlink, readlink, lstat}
@end deftypefn
symlink
@c symlink libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn  {} {} symlink @var{old} @var{new}
@deftypefnx {} {[@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, unlink, readlink, lstat}
@end deftypefn
readlink
@c readlink libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn  {} {} readlink @var{symlink}
@deftypefnx {} {[@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{lstat, symlink, link, unlink, delete}
@end deftypefn
rename
@c rename libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn  {} {} rename @var{old} @var{new}
@deftypefnx {} {[@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{movefile, copyfile, ls, dir}
@end deftypefn
glob
@c glob libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn {} {} 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 filenames 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
@item *
matches any string, including the null string,

@item ?
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 filenames.  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, what}
@end deftypefn
__wglob__
@c __wglob__ libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn {} {} __wglob__ (@var{pattern})
Windows-like glob for dir.

Given an array of pattern strings (as a char array or a cell array) in
@var{pattern}, return a cell array of filenames that match any of
them, or an empty cell array if no patterns match.

The pattern strings are interpreted as filename globbing patterns
(roughly as they are used by Windows dir).

Within a pattern

@table @code
@item *
matches any string, including the null string,

@item ?
matches any single character, and

@item *.*
matches any string, even if no . is present.
@end table

Tilde expansion is performed on each of the patterns before looking for
matching filenames.  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 ("*.*")
   @result{}
      @{
        [1,1] = file1
        [2,1] = file2
        [3,1] = file3
        [4,1] = myfile1
        [5,1] = myfile1b
      @}
@end example
@seealso{glob, dir}
@end deftypefn
__fnmatch__
@c __fnmatch__ libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn {} {} fnmatch (@var{pattern}, @var{string})
Return true or false 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
@seealso{glob, regexp}
@end deftypefn
filesep
@c filesep libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn  {} {} filesep ()
@deftypefnx {} {} filesep ("all")
Return the system-dependent character used to separate directory names.

If @qcode{"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 libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn {} {@var{val} =} pathsep ()
Query the character used to separate directories in a path.
@seealso{filesep}
@end deftypefn
confirm_recursive_rmdir
@c confirm_recursive_rmdir libinterp/corefcn/dirfns.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} confirm_recursive_rmdir ()
@deftypefnx {} {@var{old_val} =} confirm_recursive_rmdir (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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{rmdir}
@end deftypefn
have_window_system
@c have_window_system libinterp/corefcn/display.cc
-*- texinfo -*-
@deftypefn {} {} have_window_system ()
Return true if a window system is available (X11, Windows, or Apple OS X)
and false otherwise.
@seealso{isguirunning}
@end deftypefn
dlmread
@c dlmread libinterp/corefcn/dlmread.cc
-*- texinfo -*-
@deftypefn  {} {@var{data} =} dlmread (@var{file})
@deftypefnx {} {@var{data} =} dlmread (@var{file}, @var{sep})
@deftypefnx {} {@var{data} =} dlmread (@var{file}, @var{sep}, @var{r0}, @var{c0})
@deftypefnx {} {@var{data} =} dlmread (@var{file}, @var{sep}, @var{range})
@deftypefnx {} {@var{data} =} dlmread (@dots{}, "emptyvalue", @var{EMPTYVAL})
Read numeric data from the text file @var{file} which uses the delimiter
@var{sep} between data values.

If @var{sep} is not defined the separator between fields is determined from
the file itself.

The optional scalar arguments @var{r0} and @var{c0} define the starting row
and column of the data to be read.  These values are indexed from zero,
i.e., the first data row corresponds to an index of zero.

The @var{range} parameter specifies exactly which data elements are read.
The first form of the parameter is a 4-element vector containing the upper
left and lower right corners @code{[@var{R0},@var{C0},@var{R1},@var{C1}]}
where the indices are zero-based.  Alternatively, a spreadsheet style
form such as @qcode{"A2..Q15"} or @qcode{"T1:AA5"} can be used.  The
lowest alphabetical index @qcode{'A'} refers to the first column.  The
lowest row index is 1.

@var{file} should be a filename or a file id given by @code{fopen}.  In the
latter case, the file is read until end of file is reached.

The @qcode{"emptyvalue"} option may be used to specify the value used to
fill empty fields.  The default is zero.  Note that any non-numeric values,
such as text, are also replaced by the @qcode{"emptyvalue"}.
@seealso{csvread, textscan, dlmwrite}
@end deftypefn
dot
@c dot libinterp/corefcn/dot.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/dot.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/eig.cc
-*- texinfo -*-
@deftypefn  {} {@var{lambda} =} eig (@var{A})
@deftypefnx {} {@var{lambda} =} eig (@var{A}, @var{B})
@deftypefnx {} {[@var{V}, @var{lambda}] =} eig (@var{A})
@deftypefnx {} {[@var{V}, @var{lambda}] =} eig (@var{A}, @var{B})
@deftypefnx {} {[@var{V}, @var{lambda}, @var{W}] =} eig (@var{A})
@deftypefnx {} {[@var{V}, @var{lambda}, @var{W}] =} eig (@var{A}, @var{B})
@deftypefnx {} {[@dots{}] =} eig (@var{A}, @var{balanceOption})
@deftypefnx {} {[@dots{}] =} eig (@var{A}, @var{B}, @var{algorithm})
@deftypefnx {} {[@dots{}] =} eig (@dots{}, @var{eigvalOption})
Compute the eigenvalues (@var{lambda}) and optionally the right eigenvectors
(@var{V}) and the left eigenvectors (@var{W}) of a matrix or pair of matrices.

The flag @var{balanceOption} can be one of:

@table @asis
@item @qcode{"balance"} (default)
Preliminary balancing is on.

@item @qcode{"nobalance"}
Disables preliminary balancing.
@end table

The flag @var{eigvalOption} can be one of:

@table @asis
@item @qcode{"matrix"}
Return the eigenvalues in a diagonal matrix.  (default if 2 or 3 outputs
are requested)

@item @qcode{"vector"}
Return the eigenvalues in a column vector.  (default if only 1 output is
requested, e.g., @var{lambda} = eig (@var{A}))
@end table

The flag @var{algorithm} can be one of:

@table @asis
@item @qcode{"chol"}
Use the Cholesky factorization of B.  (default if @var{A} is symmetric
(Hermitian) and @var{B} is symmetric (Hermitian) positive definite)

@item @qcode{"qz"}
Use the QZ algorithm.  (used whenever @var{A} or @var{B} are not symmetric)
@end table

@multitable @columnfractions .31 .23 .23 .23
@headitem @tab no flag @tab chol @tab qz
@item both are symmetric
@tab @qcode{"chol"}
@tab @qcode{"chol"}
@tab @qcode{"qz"}
@item at least one is not symmetric
@tab @qcode{"qz"}
@tab @qcode{"qz"}
@tab @qcode{"qz"}
@end multitable

The eigenvalues returned by @code{eig} are not ordered.
@seealso{eigs, svd}
@end deftypefn
ellipj
@c ellipj libinterp/corefcn/ellipj.cc
-*- texinfo -*-
@deftypefn  {} {[@var{sn}, @var{cn}, @var{dn}, @var{err}] =} ellipj (@var{u}, @var{m})
@deftypefnx {} {[@var{sn}, @var{cn}, @var{dn}, @var{err}] =} ellipj (@var{u}, @var{m}, @var{tol})
Compute the Jacobi elliptic functions @var{sn}, @var{cn}, and @var{dn}
of complex argument @var{u} and real parameter @var{m}.

If @var{m} is a scalar, the results are the same size as @var{u}.
If @var{u} is a scalar, the results are the same size as @var{m}.
If @var{u} is a column vector and @var{m} is a row vector, the
results are matrices with @code{length (@var{u})} rows and
@code{length (@var{m})} columns.  Otherwise, @var{u} and
@var{m} must conform in size and the results will be the same size as the
inputs.

The value of @var{u} may be complex.
The value of @var{m} must be 0 @leq{} @var{m} @leq{} 1.

The optional input @var{tol} is currently ignored (@sc{matlab} uses this to
allow faster, less accurate approximation).

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

@enumerate 0
@item
Normal return.

@item
Error---no computation, algorithm termination condition not met,
return @code{NaN}.
@end enumerate

Reference: Milton @nospell{Abramowitz} and Irene A @nospell{Stegun},
@cite{Handbook of Mathematical Functions}, Chapter 16 (Sections 16.4, 16.13,
and 16.15), Dover, 1965.

@seealso{ellipke}
@end deftypefn
EDITOR
@c EDITOR libinterp/corefcn/environment.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} EDITOR ()
@deftypefnx {} {@var{old_val} =} EDITOR (@var{new_val})
@deftypefnx {} {} EDITOR (@var{new_val}, "local")
Query or set the internal variable that specifies the default text editor.

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 @qcode{"emacs"}.

When called from inside a function with the @qcode{"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, edit_history}
@end deftypefn
EXEC_PATH
@c EXEC_PATH libinterp/corefcn/environment.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} EXEC_PATH ()
@deftypefnx {} {@var{old_val} =} EXEC_PATH (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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{IMAGE_PATH, OCTAVE_HOME, OCTAVE_EXEC_HOME}
@end deftypefn
IMAGE_PATH
@c IMAGE_PATH libinterp/corefcn/environment.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} IMAGE_PATH ()
@deftypefnx {} {@var{old_val} =} IMAGE_PATH (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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{EXEC_PATH, OCTAVE_HOME, OCTAVE_EXEC_HOME}
@end deftypefn
rethrow
@c rethrow libinterp/corefcn/error.cc
-*- texinfo -*-
@deftypefn {} {} rethrow (@var{err})
Reissue a previous error as defined by @var{err}.

@var{err} is a structure that must contain at least the @qcode{"message"}
and @qcode{"identifier"} fields.  @var{err} can also contain a field
@qcode{"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 libinterp/corefcn/error.cc
-*- texinfo -*-
@deftypefn  {} {} error (@var{template}, @dots{})
@deftypefnx {} {} error (@var{id}, @var{template}, @dots{})
Display an error message and stop m-file execution.

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 further
commands.  This is useful for aborting from functions or scripts.

If the error message does not end with a newline 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 find the exact location of the error:

@example
@group
f ()
error: nargin != 1
error: called from:
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 newline 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 newline 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

A null string ("") input to @code{error} will be ignored and the code
will continue running as if the statement were a NOP@.  This is for
compatibility with @sc{matlab}.  It also makes it possible to write code
such as

@example
@group
err_msg = "";
if (CONDITION 1)
  err_msg = "CONDITION 1 found";
elseif (CONDITION2)
  err_msg = "CONDITION 2 found";
@dots{}
endif
error (err_msg);
@end group
@end example

@noindent
which will only stop execution if an error has been found.

Implementation Note: For compatibility with @sc{matlab}, escape
sequences in @var{template} (e.g., @qcode{"@xbackslashchar{}n"} =>
newline) are processed regardless of whether @var{template} has been defined
with single quotes, as long as there are two or more input arguments.  To
disable escape sequence expansion use a second backslash before the sequence
(e.g., @qcode{"@xbackslashchar{}@xbackslashchar{}n"}) or use the
@code{regexptranslate} function.
@seealso{warning, lasterror}
@end deftypefn
warning
@c warning libinterp/corefcn/error.cc
-*- texinfo -*-
@deftypefn  {} {} warning (@var{template}, @dots{})
@deftypefnx {} {} warning (@var{id}, @var{template}, @dots{})
@deftypefnx {} {} warning ("on", @var{id})
@deftypefnx {} {} warning ("off", @var{id})
@deftypefnx {} {} warning ("error", @var{id})
@deftypefnx {} {} warning ("query", @var{id})
@deftypefnx {} {} warning (@var{state}, @var{id}, "local")
@deftypefnx {} {} warning (@var{warning_struct})
@deftypefnx {} {@var{warning_struct} =} warning (@dots{})
@deftypefnx {} {} warning (@var{state}, @var{mode})

Display a warning message or control the behavior of Octave's warning system.

The first call form uses a template @var{template} and optional additional
arguments to display a message on the @code{stderr} stream.  The message is
formatted using the same rules as the @code{printf} family of functions
(@pxref{Formatted Output}) and prefixed by the character string
@w{@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.  For example:

@example
@group
warning ("foo: maybe something wrong here");
@end group
@end example

If the warning message does not end with a newline character, Octave will
print a traceback of all the function calls leading to the warning.  If the
warning message does end in a newline character, Octave will suppress the
traceback messages as it returns control to the top level.  For more details
and examples, see @ref{XREFerror,,error}.

The optional warning identifier @var{id} allows users to enable or disable
warnings tagged by this identifier.  A message identifier is a string of the
form @qcode{"NAMESPACE:WARNING-NAME"}.  Octave's own warnings use the
@qcode{"Octave"} namespace (@pxref{XREFwarning_ids,,warning_ids}).  For
example:

@example
@group
warning ("MyNameSpace:check-something",
         "foo: maybe something wrong here");
@end group
@end example

The second call form is meant to change and/or query the state of warnings.
The first input argument must be a string @var{state} (@qcode{"on"},
@qcode{"off"}, @qcode{"error"}, or @qcode{"query"}) followed by an optional
warning identifier @var{id} or @qcode{"all"} (default).

The optional output argument @var{warning_struct} is a structure or structure
array with fields @qcode{"state"} and @qcode{"identifier"}.  The @var{state}
argument may have the following values:

@table @asis
@item @qcode{"on"}|@qcode{"off"}:
Enable or disable the display of warnings identified by @var{id} and optionally
return their previous state @var{stout}.

@item @qcode{"error"}:
Turn warnings identified by @var{id} into errors and optionally return their
previous state @var{stout}.

@item @qcode{"query"}:
Return the current state of warnings identified by @var{id}.
@end table

A structure or structure array @var{warning_struct}, with fields
@qcode{"state"} and @qcode{"identifier"}, may be given as an input to achieve
equivalent results.  The following example shows how to temporarily disable a
warning and then restore its original state:

@example
@group
loglog (-1:10);
## Disable the previous warning and save its original state
[~, id] = lastwarn ();
warnstate = warning ("off", id);
loglog (-1:10);
## Restore its original state
warning (warnstate);
@end group
@end example

If a final argument @qcode{"local"} is provided then the warning state will be
set temporarily until the end of the current function.  Changes to warning
states that are set locally affect the current function and all functions
called from the current scope.  The previous warning state is restored on
return from the current function.  The @qcode{"local"} option is ignored if
used in the top-level workspace.

With no input argument @code{warning ()} is equivalent to
@code{warning ("query", "all")} except that in the absence of an output
argument, the state of warnings is displayed on @code{stderr}.

The level of verbosity of the warning system may also be controlled by two
modes @var{mode}:

@table @asis
@item @qcode{"backtrace"}:
enable/disable the display of the stack trace after the warning message

@item @qcode{"verbose"}:
enable/disable the display of additional information after the warning message
@end table

In this case the @var{state} argument may only be @qcode{"on"} or
@qcode{"off"}.

Implementation Note: For compatibility with @sc{matlab}, escape sequences in
@var{template} (e.g., @qcode{"@xbackslashchar{}n"} => newline) are processed
regardless of whether @var{template} has been defined with single quotes, as
long as there are two or more input arguments.  To disable escape sequence
expansion use a second backslash before the sequence (e.g.,
@qcode{"@xbackslashchar{}@xbackslashchar{}n"}) or use the
@code{regexptranslate} function.
@seealso{warning_ids, lastwarn, error}
@end deftypefn
lasterror
@c lasterror libinterp/corefcn/error.cc
-*- texinfo -*-
@deftypefn  {} {@var{lasterr} =} lasterror ()
@deftypefnx {} {} lasterror (@var{err})
@deftypefnx {} {} 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 @code
@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 @code
@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 @qcode{"reset"}, all
fields are set to their default values.
@seealso{lasterr, error, lastwarn}
@end deftypefn
lasterr
@c lasterr libinterp/corefcn/error.cc
-*- texinfo -*-
@deftypefn  {} {[@var{msg}, @var{msgid}] =} lasterr ()
@deftypefnx {} {} lasterr (@var{msg})
@deftypefnx {} {} 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, error, lastwarn}
@end deftypefn
lastwarn
@c lastwarn libinterp/corefcn/error.cc
-*- texinfo -*-
@deftypefn  {} {[@var{msg}, @var{msgid}] =} lastwarn ()
@deftypefnx {} {} lastwarn (@var{msg})
@deftypefnx {} {} lastwarn (@var{msg}, @var{msgid})
Query or set the last warning message.

When called without input arguments, return the last warning message and
message identifier.

With one argument, set the last warning message to @var{msg}.

With two arguments, also set the last message identifier.
@seealso{warning, lasterror, lasterr}
@end deftypefn
beep_on_error
@c beep_on_error libinterp/corefcn/error.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} beep_on_error ()
@deftypefnx {} {@var{old_val} =} beep_on_error (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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 libinterp/corefcn/error.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} debug_on_error ()
@deftypefnx {} {@var{old_val} =} debug_on_error (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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{debug_on_warning, debug_on_interrupt}
@end deftypefn
debug_on_warning
@c debug_on_warning libinterp/corefcn/error.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} debug_on_warning ()
@deftypefnx {} {@var{old_val} =} debug_on_warning (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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{debug_on_error, debug_on_interrupt}
@end deftypefn
fft
@c fft libinterp/corefcn/fft.cc
-*- texinfo -*-
@deftypefn  {} {} fft (@var{x})
@deftypefnx {} {} fft (@var{x}, @var{n})
@deftypefnx {} {} fft (@var{x}, @var{n}, @var{dim})
Compute the discrete Fourier transform of @var{x} 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 libinterp/corefcn/fft.cc
-*- texinfo -*-
@deftypefn  {} {} ifft (@var{x})
@deftypefnx {} {} ifft (@var{x}, @var{n})
@deftypefnx {} {} ifft (@var{x}, @var{n}, @var{dim})
Compute the inverse discrete Fourier transform of @var{x}
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 libinterp/corefcn/fft2.cc
-*- texinfo -*-
@deftypefn  {} {} fft2 (@var{A})
@deftypefnx {} {} 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 libinterp/corefcn/fft2.cc
-*- texinfo -*-
@deftypefn  {} {} ifft2 (@var{A})
@deftypefnx {} {} 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 libinterp/corefcn/fftn.cc
-*- texinfo -*-
@deftypefn  {} {} fftn (@var{A})
@deftypefnx {} {} 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 libinterp/corefcn/fftn.cc
-*- texinfo -*-
@deftypefn  {} {} ifftn (@var{A})
@deftypefnx {} {} 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
fclose
@c fclose libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {} fclose (@var{fid})
@deftypefnx {} {} fclose ("all")
@deftypefnx {} {@var{status} =} fclose ("all")
Close the file specified by the file descriptor @var{fid}.

If successful, @code{fclose} returns 0, otherwise, it returns -1.  The
second form of the @code{fclose} call closes all open files except
@code{stdin}, @code{stdout}, @code{stderr}, and any FIDs associated
with gnuplot.
@seealso{fopen, fflush, freport}
@end deftypefn
fclear
@c fclear libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} fclear (@var{fid})
Clear the stream state for the file specified by the file descriptor
@var{fid}.
@seealso{ferror, fopen}
@end deftypefn
fflush
@c fflush libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} fflush (@var{fid})
Flush output to file descriptor @var{fid}.

@code{fflush} returns 0 on success and an OS dependent error value
(@minus{}1 on Unix) on error.

Programming Note: Flushing 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}.
@seealso{fopen, fclose}
@end deftypefn
fgetl
@c fgetl libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {@var{str} =} fgetl (@var{fid})
@deftypefnx {} {@var{str} =} 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.

To read a line and return the terminating newline see @code{fgets}.
@seealso{fgets, fscanf, fread, fopen}
@end deftypefn
fgets
@c fgets libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {@var{str} =} fgets (@var{fid})
@deftypefnx {} {@var{str} =} 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.

To read a line and discard the terminating newline see @code{fgetl}.
@seealso{fputs, fgetl, fscanf, fread, fopen}
@end deftypefn
fskipl
@c fskipl libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {@var{nlines} =} fskipl (@var{fid})
@deftypefnx {} {@var{nlines} =} fskipl (@var{fid}, @var{count})
@deftypefnx {} {@var{nlines} =} fskipl (@var{fid}, Inf)
Read and skip @var{count} lines from the file specified by the file
descriptor @var{fid}.

@code{fskipl} discards characters until an end-of-line is encountered
exactly @var{count}-times, or until the end-of-file marker is found.

If @var{count} is omitted, it defaults to 1.  @var{count} may also be
@code{Inf}, in which case lines are skipped until the end of the file.
This form is suitable for counting the number of lines in a file.

Returns the number of lines skipped (end-of-line sequences encountered).
@seealso{fgetl, fgets, fscanf, fopen}
@end deftypefn
fopen
@c fopen libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {@var{fid} =} fopen (@var{name})
@deftypefnx {} {@var{fid} =} fopen (@var{name}, @var{mode})
@deftypefnx {} {@var{fid} =} fopen (@var{name}, @var{mode}, @var{arch})
@deftypefnx {} {[@var{fid}, @var{msg}] =} fopen (@dots{})
@deftypefnx {} {@var{fid_list} =} fopen ("all")
@deftypefnx {} {[@var{file}, @var{mode}, @var{arch}] =} fopen (@var{fid})
Open a file for low-level I/O or query open files and file descriptors.

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 of @var{mode} are

@table @asis
@item @samp{r} (default)
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 @qcode{"t"} to the mode string to open the file in text mode or a
@qcode{"b"} to open in binary mode.  On Windows systems,
text mode reading and writing automatically converts linefeeds to the
appropriate line end character for the system (carriage-return linefeed on
Windows).  The default when no mode is specified is binary.

Additionally, you may append a @qcode{"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
@item @qcode{"native"} or @qcode{"n"} (default)
The format of the current machine.

@item @qcode{"ieee-be"} or @qcode{"b"}
IEEE big endian format.

@item @qcode{"ieee-le"} or @qcode{"l"}
IEEE little endian format.
@end table

@noindent
However, conversions are currently only supported for @samp{native},
@samp{ieee-be}, and @samp{ieee-le} formats.

When opening a new file that does not yet exist, permissions will be set to
@code{0666 - @var{umask}}.

Compatibility Note: Octave opens files using buffered I/O.  Small writes are
accumulated until an internal buffer is filled, and then everything is written
in a single operation.  This is very efficient and improves performance.
@sc{matlab}, however, opens files using flushed I/O where every write operation
is immediately performed.  If the write operation must be performed immediately
after data has been written then the write should be followed by a call to
@code{fflush} to flush the internal buffer.
@seealso{fclose, fgets, fgetl, fscanf, fread, fputs, fdisp, fprintf, fwrite, fskipl, fseek, frewind, ftell, feof, ferror, fclear, fflush, freport, umask}
@end deftypefn
freport
@c freport libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} 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  arch       name
     @print{}  ------  ----  ----       ----
     @print{}     0     r    ieee-le    stdin
     @print{}     1     w    ieee-le    stdout
     @print{}     2     w    ieee-le    stderr
     @print{}     3     r    ieee-le    myfile
@end group
@end example
@seealso{fopen, fclose, is_valid_file_id}
@end deftypefn
frewind
@c frewind libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {} frewind (@var{fid})
@deftypefnx {} {@var{status} =} frewind (@var{fid})
Move the file pointer to the beginning of the file specified by file
descriptor @var{fid}.

@code{frewind} returns 0 for success, and -1 if an error is encountered.  It
is equivalent to @code{fseek (@var{fid}, 0, SEEK_SET)}.
@seealso{fseek, ftell, fopen}
@end deftypefn
fseek
@c fseek libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {} fseek (@var{fid}, @var{offset})
@deftypefnx {} {} fseek (@var{fid}, @var{offset}, @var{origin})
@deftypefnx {} {@var{status} =} fseek (@dots{})
Set the file pointer to the location @var{offset} 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{@qcode{SEEK_SET}} (beginning),
@w{@qcode{SEEK_CUR}} (current position), or @w{@qcode{SEEK_END}} (end of file)
or strings @nospell{@qcode{"bof"}}, @nospell{@qcode{"cof"}}, or
@nospell{@qcode{"eof"}}.  If @var{origin} is omitted, @w{@qcode{SEEK_SET}} is
assumed.  @var{offset} may be positive, negative, or zero but not all
combinations of @var{origin} and @var{offset} can be realized.

@code{fseek} returns 0 on success and -1 on error.
@seealso{fskipl, frewind, ftell, fopen, SEEK_SET, SEEK_CUR, SEEK_END}
@end deftypefn
ftell
@c ftell libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {@var{pos} =} ftell (@var{fid})
Return the position of the file pointer as the number of characters from the
beginning of the file specified by file descriptor @var{fid}.
@seealso{fseek, frewind, feof, fopen}
@end deftypefn
fprintf
@c fprintf libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {} fprintf (@var{fid}, @var{template}, @dots{})
@deftypefnx {} {} fprintf (@var{template}, @dots{})
@deftypefnx {} {@var{numbytes} =} fprintf (@dots{})
This function is equivalent to @code{printf}, except that the output is
written to the file descriptor @var{fid} instead of @code{stdout}.

If @var{fid} is omitted, the output is written to @code{stdout} making the
function exactly equivalent to @code{printf}.

The optional output returns the number of bytes written to the file.

Implementation Note: For compatibility with @sc{matlab}, escape sequences in
the template string (e.g., @qcode{"@xbackslashchar{}n"} => newline) are
expanded even when the template string is defined with single quotes.
@seealso{fputs, fdisp, fwrite, fscanf, printf, sprintf, fopen}
@end deftypefn
printf
@c printf libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} 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

Implementation Note: For compatibility with @sc{matlab}, escape sequences in
the template string (e.g., @qcode{"@xbackslashchar{}n"} => newline) are
expanded even when the template string is defined with single quotes.
@seealso{fprintf, sprintf, scanf}
@end deftypefn
fputs
@c fputs libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {} fputs (@var{fid}, @var{string})
@deftypefnx {} {@var{status} =} fputs (@var{fid}, @var{string})
Write the string @var{string} to the file with file descriptor @var{fid}.

The string is written to the file with no additional formatting.  Use
@code{fdisp} instead to automatically append a newline character appropriate
for the local machine.

Return a non-negative number on success or EOF on error.
@seealso{fdisp, fprintf, fwrite, fopen}
@end deftypefn
puts
@c puts libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {} puts (@var{string})
@deftypefnx {} {@var{status} =} puts (@var{string})
Write a string to the standard output with no formatting.

The string is written verbatim to the standard output.  Use @code{disp} to
automatically append a newline character appropriate for the local machine.

Return a non-negative number on success and EOF on error.
@seealso{fputs, disp}
@end deftypefn
sprintf
@c sprintf libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} 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.

Implementation Note: For compatibility with @sc{matlab}, escape sequences in
the template string (e.g., @qcode{"@xbackslashchar{}n"} => newline) are
expanded even when the template string is defined with single quotes.
@seealso{printf, fprintf, sscanf}
@end deftypefn
fscanf
@c fscanf libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {[@var{val}, @var{count}, @var{errmsg}] =} fscanf (@var{fid}, @var{template}, @var{size})
@deftypefnx {} {[@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{fgets, fgetl, fread, scanf, sscanf, fopen}
@end deftypefn
sscanf
@c sscanf libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {[@var{val}, @var{count}, @var{errmsg}, @var{pos}] =} sscanf (@var{string}, @var{template}, @var{size})
@deftypefnx {} {[@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 libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {[@var{val}, @var{count}, @var{errmsg}] =} scanf (@var{template}, @var{size})
@deftypefnx {} {[@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
textscan
@c textscan libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {@var{C} =} textscan (@var{fid}, @var{format})
@deftypefnx {} {@var{C} =} textscan (@var{fid}, @var{format}, @var{repeat})
@deftypefnx {} {@var{C} =} textscan (@var{fid}, @var{format}, @var{param}, @var{value}, @dots{})
@deftypefnx {} {@var{C} =} textscan (@var{fid}, @var{format}, @var{repeat}, @var{param}, @var{value}, @dots{})
@deftypefnx {} {@var{C} =} textscan (@var{str}, @dots{})
@deftypefnx {} {[@var{C}, @var{position}, @var{errmsg}] =} textscan (@dots{})
Read data from a text file or string.

The string @var{str} or file associated with @var{fid} is read from and
parsed according to @var{format}.  The function is an extension of
@code{strread} and @code{textread}.  Differences include: the ability to
read from either a file or a string, additional options, and additional
format specifiers.

The input is interpreted as a sequence of words, delimiters (such as
whitespace), and literals.  The characters that form delimiters and
whitespace are determined by the options.  The format consists of format
specifiers interspersed between literals.  In the format, whitespace forms
a delimiter between consecutive literals, but is otherwise ignored.

The output @var{C} is a cell array where the number of columns is determined
by the number of format specifiers.

The first word of the input is matched to the first specifier of the format
and placed in the first column of the output; the second is matched to the
second specifier and placed in the second column and so forth.  If there
are more words than specifiers then the process is repeated until all words
have been processed or the limit imposed by @var{repeat} has been met (see
below).

The string @var{format} describes how the words in @var{str} should be
parsed.  As in @var{fscanf}, any (non-whitespace) text in the format that is
not one of these specifiers is considered a literal.  If there is a literal
between two format specifiers then that same literal must appear in the
input stream between the matching words.

The following specifiers are valid:

@table @code
@item  %f
@itemx %f64
@itemx %n
The word is parsed as a number and converted to double.

@item  %f32
The word is parsed as a number and converted to single (float).

@item  %d
@itemx %d8
@itemx %d16
@itemx %d32
@itemx %d64
The word is parsed as a number and converted to int8, int16, int32, or
int64.  If no size is specified then int32 is used.

@item  %u
@itemx %u8
@itemx %u16
@itemx %u32
@itemx %u64
The word is parsed as a number and converted to uint8, uint16, uint32, or
uint64.  If no size is specified then uint32 is used.

@item %s
The word is parsed as a string ending at the last character before
whitespace, an end-of-line, or a delimiter specified in the options.

@item %q
The word is parsed as a "quoted string".
If the first character of the string is a double quote (") then the string
includes everything until a matching double quote---including whitespace,
delimiters, and end-of-line characters.  If a pair of consecutive double
quotes appears in the input, it is replaced in the output by a single
double quote.  For examples, the input "He said ""Hello""" would
return the value 'He said "Hello"'.

@item  %c
The next character of the input is read.
This includes delimiters, whitespace, and end-of-line characters.

@item  %[@dots{}]
@itemx %[^@dots{}]
In the first form, the word consists of the longest run consisting of only
characters between the brackets.  Ranges of characters can be specified by
a hyphen; for example, %[0-9a-zA-Z] matches all alphanumeric characters (if
the underlying character set is ASCII).  Since @sc{matlab} treats hyphens
literally, this expansion only applies to alphanumeric characters.  To
include '-' in the set, it should appear first or last in the brackets; to
include ']', it should be the first character.  If the first character is
'^' then the word consists of characters @strong{not} listed.

@item %N@dots{}
For %s, %c %d, %f, %n, %u, an optional width can be specified as %Ns, etc.
where N is an integer > 1.  For %c, this causes exactly N characters to be
read instead of a single character.  For the other specifiers, it is an
upper bound on the number of characters read; normal delimiters can cause
fewer characters to be read.  For complex numbers, this limit applies to
the real and imaginary components individually.  For %f and %n, format
specifiers like %N.Mf are allowed, where M is an upper bound on number of
characters after the decimal point to be considered; subsequent digits are
skipped.  For example, the specifier %8.2f would read 12.345e6 as 1.234e7.

@item %*@dots{}
The word specified by the remainder of the conversion specifier is skipped.

@item literals
In addition the format may contain literal character strings; these will be
skipped during reading.  If the input string does not match this literal,
the processing terminates.
@end table

Parsed words corresponding to the first specifier are returned in the first
output argument and likewise for the rest of the specifiers.

By default, if there is only one input argument, @var{format} is @t{"%f"}.
This means that numbers are read from the input into a single column vector.
If @var{format} is explicitly empty (@qcode{""}) then textscan will
return data in a number of columns matching the number of fields on the
first data line of the input.  Either of these is suitable only when the
input is exclusively numeric.

For example, the string

@smallexample
@group
@var{str} = "\
Bunny Bugs   5.5\n\
Duck Daffy  -7.5e-5\n\
Penguin Tux   6"
@end group
@end smallexample

@noindent
can be read using

@example
@var{a} = textscan (@var{str}, "%s %s %f");
@end example

The optional numeric argument @var{repeat} can be used for limiting the
number of items read:

@table @asis
@item -1
Read all of the string or file until the end (default).

@item N
Read until the first of two conditions occurs: 1) the format has been
processed N times, or 2) N lines of the input have been processed.  Zero
(0) is an acceptable value for @var{repeat}.  Currently, end-of-line
characters inside %q, %c, and %[@dots{}]$ conversions do not contribute to
the line count.  This is incompatible with @sc{matlab} and may change in
future.
@end table

The behavior of @code{textscan} can be changed via property/value pairs.
The following properties are recognized:

@table @asis
@item @qcode{"BufSize"}
This specifies the number of bytes to use for the internal buffer.
A modest speed improvement may be obtained by setting this to a large value
when reading a large file, especially if the input contains long strings.
The default is 4096, or a value dependent on @var{n} if that is specified.

@item @qcode{"CollectOutput"}
A value of 1 or true instructs @code{textscan} to concatenate consecutive
columns of the same class in the output cell array.  A value of 0 or false
(default) leaves output in distinct columns.

@item @qcode{"CommentStyle"}
Specify parts of the input which are considered comments and will be
skipped.  @var{value} is the comment style and can be either (1) A string
or 1x1 cell string, to skip everything to the right of it; (2) A cell array
of two strings, to skip everything between the first and second strings.
Comments are only parsed where whitespace is accepted and do not act as
delimiters.

@item @qcode{"Delimiter"}
If @var{value} is a string, any character in @var{value} will be used to
split the input into words.  If @var{value} is a cell array of strings,
any string in the array will be used to split the input into words.
(default value = any whitespace.)

@item @qcode{"EmptyValue"}
Value to return for empty numeric values in non-whitespace delimited data.
The default is NaN@.  When the data type does not support NaN (int32 for
example), then the default is zero.

@item @qcode{"EndOfLine"}
@var{value} can be either an emtpy or one character specifying the
end-of-line character, or the pair
@qcode{"@xbackslashchar{}r@xbackslashchar{}n"} (CRLF).
In the latter case, any of
@qcode{"@xbackslashchar{}r"}, @qcode{"@xbackslashchar{}n"} or
@qcode{"@xbackslashchar{}r@xbackslashchar{}n"} is counted as a (single)
newline.  If no value is given,
@qcode{"@xbackslashchar{}r@xbackslashchar{}n"} is used.
@c If set to "" (empty string) EOLs are ignored as delimiters and added
@c to whitespace.

@c When reading from a character string, optional input argument @var{n}
@c specifies the number of times @var{format} should be used (i.e., to limit
@c the amount of data read).
@c When reading from file, @var{n} specifies the number of data lines to read;
@c in this sense it differs slightly from the format repeat count in strread.

@item @qcode{"HeaderLines"}
The first @var{value} number of lines of @var{fid} are skipped.  Note that
this does not refer to the first non-comment lines, but the first lines of
any type.

@item @qcode{"MultipleDelimsAsOne"}
If @var{value} is nonzero, treat a series of consecutive delimiters,
without whitespace in between, as a single delimiter.  Consecutive
delimiter series need not be vertically aligned.  Without this option, a
single delimiter before the end of the line does not cause the line to be
considered to end with an empty value, but a single delimiter at the start
of a line causes the line to be considered to start with an empty value.

@item @qcode{"TreatAsEmpty"}
Treat single occurrences (surrounded by delimiters or whitespace) of the
string(s) in @var{value} as missing values.

@item @qcode{"ReturnOnError"}
If set to numerical 1 or true, return normally as soon as an error is
encountered, such as trying to read a string using @code{%f}.
If set to 0 or false, return an error and no data.

@item @qcode{"Whitespace"}
Any character in @var{value} will be interpreted as whitespace and trimmed;
The default value for whitespace is
@c Note: the next line specifically has a newline which generates a space
@c       in the output of qcode, but keeps the next line < 80 characters.
@qcode{"
@xbackslashchar{}b@xbackslashchar{}r@xbackslashchar{}n@xbackslashchar{}t"}
(note the space).  Unless whitespace is set to @qcode{""} (empty) AND at
least one @qcode{"%s"} format conversion specifier is supplied, a space is
always part of whitespace.

@end table

When the number of words in @var{str} or @var{fid} doesn't match an exact
multiple of the number of format conversion specifiers, @code{textscan}'s
behavior depends on whether the last character of the string or file is an
end-of-line as specified by the @code{EndOfLine} option:

@table @asis
@item last character = end-of-line
Data columns are padded with empty fields, NaN or 0 (for integer fields) so
that all columns have equal length

@item last character is not end-of-line
Data columns are not padded; @code{textscan} returns columns of unequal
length
@end table

The second output @var{position} provides the location, in characters
from the beginning of the file or string, where processing stopped.

@seealso{dlmread, fscanf, load, strread, textread}
@end deftypefn
__textscan__
@c __textscan__ libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {@var{C} =} __textscan__ (@var{who}, @dots{})
Like @code{textscan} but accept additional argument @var{who} to use
as the name of the function when reporting errors.
@end deftypefn
fread
@c fread libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} fread (@var{fid})
@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size})
@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size}, @var{precision})
@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size}, @var{precision}, @var{skip})
@deftypefnx {} {@var{val} =} fread (@var{fid}, @var{size}, @var{precision}, @var{skip}, @var{arch})
@deftypefnx {} {[@var{val}, @var{count}] =} fread (@dots{})
Read binary data from the file specified by the file descriptor @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 @qcode{"uint8"} (default)
8-bit unsigned integer.

@item  @qcode{"int8"}
@itemx @qcode{"integer*1"}
8-bit signed integer.

@item  @qcode{"uint16"}
@itemx @qcode{"ushort"}
@itemx @qcode{"unsigned short"}
16-bit unsigned integer.

@item  @qcode{"int16"}
@itemx @qcode{"integer*2"}
@itemx @qcode{"short"}
16-bit signed integer.

@item  @qcode{"uint"}
@itemx @qcode{"uint32"}
@itemx @qcode{"unsigned int"}
@itemx @qcode{"ulong"}
@itemx @qcode{"unsigned long"}
32-bit unsigned integer.

@item  @qcode{"int"}
@itemx @qcode{"int32"}
@itemx @qcode{"integer*4"}
@itemx @qcode{"long"}
32-bit signed integer.

@item @qcode{"uint64"}
64-bit unsigned integer.

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

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

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

@item  @qcode{"char"}
@itemx @qcode{"char*1"}
8-bit single character.

@item  @qcode{"uchar"}
@itemx @qcode{"unsigned char"}
8-bit unsigned character.

@item  @qcode{"schar"}
@itemx @qcode{"signed char"}
8-bit signed character.

@end table

@noindent
The default precision is @qcode{"uint8"}.

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 @asis
@item @qcode{"native"} or @qcode{"n"}
The format of the current machine.

@item @qcode{"ieee-be"} or @qcode{"b"}
IEEE big endian.

@item @qcode{"ieee-le"} or @qcode{"l"}
IEEE little endian.
@end table

If no @var{arch} is given the value used in the call to @code{fopen} which
created the file descriptor is used.  Otherwise, the value specified with
@code{fread} overrides that of @code{fopen} and determines the data format.

The output argument @var{val} contains the data read from the file.

The optional return value @var{count} contains the number of elements read.
@seealso{fwrite, fgets, fgetl, fscanf, fopen}
@end deftypefn
fwrite
@c fwrite libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {} fwrite (@var{fid}, @var{data})
@deftypefnx {} {} fwrite (@var{fid}, @var{data}, @var{precision})
@deftypefnx {} {} fwrite (@var{fid}, @var{data}, @var{precision}, @var{skip})
@deftypefnx {} {} fwrite (@var{fid}, @var{data}, @var{precision}, @var{skip}, @var{arch})
@deftypefnx {} {@var{count} =} fwrite (@dots{})
Write data in binary form to the file specified by the file descriptor
@var{fid}, returning the number of values @var{count} 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, fputs, fprintf, fopen}
@end deftypefn
feof
@c feof libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {@var{status} =} feof (@var{fid})
Return 1 if an end-of-file condition has been encountered for the file
specified by file descriptor @var{fid} and 0 otherwise.

Note that @code{feof} 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, frewind, fseek, fclear, fopen}
@end deftypefn
ferror
@c ferror libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {@var{msg} =} ferror (@var{fid})
@deftypefnx {} {[@var{msg}, @var{err}] =} ferror (@var{fid})
@deftypefnx {} {[@dots{}] =} ferror (@var{fid}, "clear")
Query the error status of the stream specified by file descriptor @var{fid}.

If an error condition exists then return a string @var{msg} describing the
error.  Otherwise, return an empty string @qcode{""}.

The second input @qcode{"clear"} is optional.  If supplied, the error
state on the stream will be cleared.

The optional second output is a numeric indication of the error status.
@var{err} is 1 if an error condition has been encountered and 0 otherwise.

Note that @code{ferror} indicates if an error has already occurred, not
whether the next operation will result in an error condition.
@seealso{fclear, fopen}
@end deftypefn
popen
@c popen libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {@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 argument
@var{mode} may be

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

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

The file identifier corresponding to the input or output stream of the
process is returned in @var{fid}.

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
@seealso{popen2}
@end deftypefn
pclose
@c pclose libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} pclose (@var{fid})
Close a file identifier that was opened by @code{popen}.

The function @code{fclose} may also be used for the same purpose.
@seealso{fclose, popen}
@end deftypefn
tempname
@c tempname libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {@var{fname} =} tempname ()
@deftypefnx {} {@var{fname} =} tempname (@var{dir})
@deftypefnx {} {@var{fname} =} tempname (@var{dir}, @var{prefix})
Return a unique temporary filename as a string.

If @var{prefix} is omitted, a value of @qcode{"oct-"} is used.

If @var{dir} is also omitted, the default directory for temporary files
(@code{P_tmpdir}) is used.  If @var{dir} is provided, it must exist,
otherwise the default directory for temporary files is used.

Programming Note: Because the named file is not opened by @code{tempname},
it is possible, though relatively unlikely, that it will not be available
by the time your program attempts to open it.  If this is a concern,
see @code{tmpfile}.
@seealso{mkstemp, tempdir, P_tmpdir, tmpfile}
@end deftypefn
tmpfile
@c tmpfile libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {[@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 (@qcode{"w+b"}) mode and 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{tempname, mkstemp, tempdir, P_tmpdir}
@end deftypefn
mkstemp
@c mkstemp libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn  {} {[@var{fid}, @var{name}, @var{msg}] =} mkstemp ("@var{template}")
@deftypefnx {} {[@var{fid}, @var{name}, @var{msg}] =} mkstemp ("@var{template}", @var{delete})
Return the file descriptor @var{fid} corresponding to a new temporary file
with a unique name created from @var{template}.

The last six characters of @var{template} must be @qcode{"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.

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{tempname, tempdir, P_tmpdir, tmpfile, fopen}
@end deftypefn
umask
@c umask libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} 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.

The permission mask is a UNIX concept used when creating new objects on a
file system such as files, directories, or named FIFOs.  The object to be
created has base permissions in an octal number @var{mode} which are
modified according to the octal value of @var{mask}.  The final permissions
for the new object are @code{@var{mode} - @var{mask}}.
@seealso{fopen, mkdir, mkfifo}
@end deftypefn
P_tmpdir
@c P_tmpdir libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} P_tmpdir ()
Return the name of the host system's @strong{default} directory for
temporary files.

Programming Note: The value returned by @code{P_tmpdir} is always the
default location.  This value may not agree with that returned from
@code{tempdir} if the user has overridden the default with the @env{TMPDIR}
environment variable.
@seealso{tempdir, tempname, mkstemp, tmpfile}
@end deftypefn
SEEK_SET
@c SEEK_SET libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} SEEK_SET ()
Return the numerical value to pass to @code{fseek} to position the file pointer
relative to the beginning of the file.
@seealso{SEEK_CUR, SEEK_END, fseek}
@end deftypefn
SEEK_CUR
@c SEEK_CUR libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} 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, fseek}
@end deftypefn
SEEK_END
@c SEEK_END libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} 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, fseek}
@end deftypefn
stdin
@c stdin libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} stdin ()
Return the numeric value corresponding to the standard input stream.

When Octave is used interactively, stdin is filtered through the command
line editing functions.
@seealso{stdout, stderr}
@end deftypefn
stdout
@c stdout libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} stdout ()
Return the numeric value corresponding to the standard output stream.

Data written to the standard output may be filtered through the pager.
@seealso{stdin, stderr, page_screen_output}
@end deftypefn
stderr
@c stderr libinterp/corefcn/file-io.cc
-*- texinfo -*-
@deftypefn {} {} 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
filter
@c filter libinterp/corefcn/filter.cc
-*- texinfo -*-
@deftypefn  {} {@var{y} =} filter (@var{b}, @var{a}, @var{x})
@deftypefnx {} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, @var{si})
@deftypefnx {} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, [], @var{dim})
@deftypefnx {} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, @var{si}, @var{dim})
Apply a 1-D digital filter to the data @var{x}.

@code{filter} returns 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
The result is calculated over the first non-singleton dimension of @var{x}
or over @var{dim} if supplied.

An equivalent form of the 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, @var{y} is the result of passing the
discrete-time signal @var{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 libinterp/corefcn/find.cc
-*- texinfo -*-
@deftypefn  {} {@var{idx} =} find (@var{x})
@deftypefnx {} {@var{idx} =} find (@var{x}, @var{n})
@deftypefnx {} {@var{idx} =} find (@var{x}, @var{n}, @var{direction})
@deftypefnx {} {[i, j] =} find (@dots{})
@deftypefnx {} {[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 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
@qcode{"first"} or @qcode{"last"}, requesting only the first or last
@var{n} indices, respectively.  However, the indices are always returned in
ascending order.

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

Note that this function is particularly useful for sparse matrices, as
it extracts the nonzero 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
gcd
@c gcd libinterp/corefcn/gcd.cc
-*- texinfo -*-
@deftypefn  {} {@var{g} =} gcd (@var{a1}, @var{a2}, @dots{})
@deftypefnx {} {[@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 then 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 only unique up to a
phase factor (multiplication by 1, -1, i, or -i), so an arbitrary greatest
common divisor among the four possible is returned.

Optional return arguments @var{v1}, @dots{}, 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

Example code:

@example
@group
gcd ([15, 9], [20, 18])
   @result{}  5  9
@end group
@end example

@seealso{lcm, factor, isprime}
@end deftypefn
getgrent
@c getgrent libinterp/corefcn/getgrent.cc
-*- texinfo -*-
@deftypefn {} {@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.
@seealso{setgrent, endgrent}
@end deftypefn
getgrgid
@c getgrgid libinterp/corefcn/getgrent.cc
-*- texinfo -*-
@deftypefn {} {@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.
@seealso{getgrnam}
@end deftypefn
getgrnam
@c getgrnam libinterp/corefcn/getgrent.cc
-*- texinfo -*-
@deftypefn {} {@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.
@seealso{getgrgid}
@end deftypefn
setgrent
@c setgrent libinterp/corefcn/getgrent.cc
-*- texinfo -*-
@deftypefn {} {} setgrent ()
Return the internal pointer to the beginning of the group database.
@seealso{getgrent, endgrent}
@end deftypefn
endgrent
@c endgrent libinterp/corefcn/getgrent.cc
-*- texinfo -*-
@deftypefn {} {} endgrent ()
Close the group database.
@seealso{getgrent, setgrent}
@end deftypefn
getpwent
@c getpwent libinterp/corefcn/getpwent.cc
-*- texinfo -*-
@deftypefn {} {@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.
@seealso{setpwent, endpwent}
@end deftypefn
getpwuid
@c getpwuid libinterp/corefcn/getpwent.cc
-*- texinfo -*-
@deftypefn {} {@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.
@seealso{getpwnam}
@end deftypefn
getpwnam
@c getpwnam libinterp/corefcn/getpwent.cc
-*- texinfo -*-
@deftypefn {} {@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.
@seealso{getpwuid}
@end deftypefn
setpwent
@c setpwent libinterp/corefcn/getpwent.cc
-*- texinfo -*-
@deftypefn {} {} setpwent ()
Return the internal pointer to the beginning of the password database.
@seealso{getpwent, endpwent}
@end deftypefn
endpwent
@c endpwent libinterp/corefcn/getpwent.cc
-*- texinfo -*-
@deftypefn {} {} endpwent ()
Close the password database.
@seealso{getpwent, setpwent}
@end deftypefn
getrusage
@c getrusage libinterp/corefcn/getrusage.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/givens.cc
-*- texinfo -*-
@deftypefn  {} {@var{G} =} givens (@var{x}, @var{y})
@deftypefnx {} {[@var{c}, @var{s}] =} givens (@var{x}, @var{y})
Compute the Givens rotation matrix @var{G}.

@tex
The Givens matrix is 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
The Givens matrix is a 2-by-2 orthogonal matrix

@example
@group
@var{G} = [ @var{c} , @var{s}
     -@var{s}', @var{c}]
@end group
@end example

@noindent
such that

@example
@var{G} * [@var{x}; @var{y}] = [*; 0]
@end example

@noindent
with @var{x} and @var{y} scalars.
@end ifnottex

If two output arguments are requested, return the factors @var{c} and @var{s}
rather than the Givens rotation matrix.

For example:

@example
@group
givens (1, 1)
   @result{}   0.70711   0.70711
       -0.70711   0.70711
@end group
@end example

Note: The Givens matrix represents a counterclockwise rotation of a 2-D
plane and can be used to introduce zeros into a matrix prior to complete
factorization.
@seealso{planerot, qr}
@end deftypefn
__update_normals__
@c __update_normals__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __update_normals__ (@var{h})
Update FaceNormals and VertexNormals of the patch or surface referred to by
@var{h}.

@end deftypefn
ishghandle
@c ishghandle libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} ishghandle (@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{isgraphics, isaxes, isfigure, ishandle}
@end deftypefn
__is_handle_visible__
@c __is_handle_visible__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __is_handle_visible__ (@var{h})
Undocumented internal function.
@end deftypefn
reset
@c reset libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} reset (@var{h})
Reset the properties of the graphic object @var{h} to their default values.

For figures, the properties @qcode{"position"}, @qcode{"units"},
@qcode{"windowstyle"}, and @qcode{"paperunits"} are not affected.
For axes, the properties @qcode{"position"} and @qcode{"units"} are
not affected.

The input @var{h} may also be a vector of graphic handles in which case
each individual object will be reset.
@seealso{cla, clf, newplot}
@end deftypefn
set
@c set libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn  {} {} set (@var{h}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} set (@var{h}, @var{properties}, @var{values})
@deftypefnx {} {} set (@var{h}, @var{pv})
@deftypefnx {} {@var{value_list} =} set (@var{h}, @var{property})
@deftypefnx {} {@var{all_value_list} =} set (@var{h})
Set named property values for the graphics handle (or vector of graphics
handles) @var{h}.

There are three ways 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

@code{set} is also used to query the list of values a named property will
take.  @code{@var{clist} = set (@var{h}, "property")} will return the list
of possible values for @qcode{"property"} in the cell list @var{clist}.
If no output variable is used then the list is formatted and printed to the
screen.

If no property is specified (@code{@var{slist} = set (@var{h})}) then a
structure @var{slist} is returned where the fieldnames are the properties of
the object @var{h} and the fields are the list of possible values for each
property.  If no output variable is used then the list is formatted and
printed to the screen.

For example,

@example
@group
hf = figure ();
set (hf, "paperorientation")
@result{}  [ landscape | @{portrait@} ]
@end group
@end example

@noindent
shows the paperorientation property can take two values with the default
being @qcode{"portrait"}.
@seealso{get}
@end deftypefn
get
@c get libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} get (@var{h})
@deftypefnx {} {@var{val} =} get (@var{h}, @var{p})
Return the value of 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.
@seealso{set}
@end deftypefn
__get__
@c __get__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __get__ (@var{h})
Undocumented internal function.
@end deftypefn
__go_figure__
@c __go_figure__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_figure__ (@var{fignum})
Undocumented internal function.
@end deftypefn
__calc_dimensions__
@c __calc_dimensions__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __calc_dimensions__ (@var{axes})
Internal function.

Determine the number of dimensions in a graphics object, either 2 or 3.
@end deftypefn
__go_axes__
@c __go_axes__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_axes__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_line__
@c __go_line__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_line__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_text__
@c __go_text__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_text__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_image__
@c __go_image__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_image__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_surface__
@c __go_surface__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_surface__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_patch__
@c __go_patch__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_patch__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_light__
@c __go_light__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_light__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_hggroup__
@c __go_hggroup__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_hggroup__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uimenu__
@c __go_uimenu__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_uimenu__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uicontrol__
@c __go_uicontrol__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_uicontrol__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uibuttongroup__
@c __go_uibuttongroup__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_uibuttongroup__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uipanel__
@c __go_uipanel__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_uipanel__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uicontextmenu__
@c __go_uicontextmenu__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_uicontextmenu__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uitable__
@c __go_uitable__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_uitable__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uitoolbar__
@c __go_uitoolbar__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_uitoolbar__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uipushtool__
@c __go_uipushtool__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_uipushtool__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uitoggletool__
@c __go_uitoggletool__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_uitoggletool__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_delete__
@c __go_delete__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_delete__ (@var{h})
Undocumented internal function.
@end deftypefn
__go_handles__
@c __go_handles__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_handles__ (@var{show_hidden})
Undocumented internal function.
@end deftypefn
__go_figure_handles__
@c __go_figure_handles__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __go_figure_handles__ (@var{show_hidden})
Undocumented internal function.
@end deftypefn
__go_execute_callback__
@c __go_execute_callback__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn  {} {} __go_execute_callback__ (@var{h}, @var{name})
@deftypefnx {} {} __go_execute_callback__ (@var{h}, @var{name}, @var{param})
Undocumented internal function.
@end deftypefn
__go_post_callback__
@c __go_post_callback__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn  {} {} __go_post_callback__ (@var{h}, @var{name})
@deftypefnx {} {} __go_post_callback__ (@var{h}, @var{name}, @var{param})
Undocumented internal function.
@end deftypefn
__image_pixel_size__
@c __image_pixel_size__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {@var{sz} =} __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 libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} loaded_graphics_toolkits ()
Return a cell array of the currently loaded graphics toolkits.
@seealso{available_graphics_toolkits}
@end deftypefn
__show_figure__
@c __show_figure__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} __show_figure__ (@var{n})
Undocumented internal function.
@end deftypefn
drawnow
@c drawnow libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn  {} {} drawnow ()
@deftypefnx {} {} drawnow ("expose")
@deftypefnx {} {} drawnow (@var{term}, @var{file}, @var{debug_file})
Update figure windows and their children.

The event queue is flushed and any callbacks generated are executed.

With the optional argument @qcode{"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.
@seealso{refresh}
@end deftypefn
addlistener
@c addlistener libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} 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

@seealso{dellistener, addproperty, hggroup}
@end deftypefn
dellistener
@c dellistener libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {} 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

@seealso{addlistener}
@end deftypefn
addproperty
@c addproperty libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn  {} {} addproperty (@var{name}, @var{h}, @var{type})
@deftypefnx {} {} 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 @nospell{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 one 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

@seealso{addlistener, hggroup}
@end deftypefn
waitfor
@c waitfor libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn  {} {} waitfor (@var{h})
@deftypefnx {} {} waitfor (@var{h}, @var{prop})
@deftypefnx {} {} waitfor (@var{h}, @var{prop}, @var{value})
@deftypefnx {} {} 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 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 the top-level.

In the first form, program execution is suspended until the graphics object
@var{h} is destroyed.  If the graphics handle is invalid or if @var{h} is
the root graphics handle and no property @var{prop} was provided, 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 @qcode{"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 @qcode{"timeout"}, use the string
@qcode{'\timeout'} instead.

In all cases, typing CTRL-C stops program execution immediately.
@seealso{waitforbuttonpress, isequal}
@end deftypefn
__zoom__
@c __zoom__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn  {} {} __zoom__ (@var{axes}, @var{mode}, @var{factor})
@deftypefnx {} {} __zoom__ (@var{axes}, "out")
@deftypefnx {} {} __zoom__ (@var{axes}, "reset")
Undocumented internal function.
@end deftypefn
__get_frame__
@c __get_frame__ libinterp/corefcn/graphics.cc
-*- texinfo -*-
@deftypefn {} {@var{cdata} =} __get_frame__ (@var{hfig})
Internal function.

Return the pixel cdata of figure hfig in the form of a height-by-width-by-3
uint8 array.
@end deftypefn
gsvd
@c gsvd libinterp/corefcn/gsvd.cc
-*- texinfo -*-
@deftypefn  {} {@var{S} =} gsvd (@var{A}, @var{B})
@deftypefnx {} {[@var{U}, @var{V}, @var{X}, @var{C}, @var{S}] =} gsvd (@var{A}, @var{B})
@deftypefnx {} {[@var{U}, @var{V}, @var{X}, @var{C}, @var{S}] =} gsvd (@var{A}, @var{B}, 0)
Compute the generalized singular value decomposition of (@var{A}, @var{B}).

The generalized singular value decomposition is defined by the following
relations:

@tex
$$ A = U C X^\dagger $$
$$ B = V S X^\dagger $$
$$ C^\dagger C + S^\dagger S = eye (columns (A)) $$
@end tex
@ifnottex

@example
@group
A = U*C*X'
B = V*S*X'
C'*C + S'*S = eye (columns (A))
@end group
@end example

@end ifnottex

The function @code{gsvd} normally returns just the vector of generalized
singular values
@tex
$$ \sqrt{{{diag (C^\dagger C)} \over {diag (S^\dagger S)}}} $$
@end tex
@ifnottex
@code{sqrt (diag (C'*C) ./ diag (S'*S))}.
@end ifnottex
If asked for five return values, it also computes
@tex
$U$, $V$, $X$, and $C$.
@end tex
@ifnottex
U, V, X, and C.
@end ifnottex

If the optional third input is present, @code{gsvd} constructs the
"economy-sized" decomposition where the number of columns of @var{U}, @var{V}
and the number of rows of @var{C}, @var{S} is less than or equal to the number
of columns of @var{A}.  This option is not yet implemented.

Programming Note: the code is a wrapper to the corresponding @sc{lapack} dggsvd
and zggsvd routines.

@seealso{svd}
@end deftypefn
hash
@c hash libinterp/corefcn/hash.cc
-*- texinfo -*-
@deftypefn {} {} hash (@var{hfun}, @var{str})
Calculate the hash value of the string @var{str} using the hash function
@var{hfun}.

The available hash functions are given in the table below.

@table @samp
@item MD2
Message-Digest Algorithm 2 (RFC 1319).

@item MD4
Message-Digest Algorithm 4 (RFC 1320).

@item MD5
Message-Digest Algorithm 5 (RFC 1321).

@item SHA1
Secure Hash Algorithm 1 (RFC 3174)

@item SHA224
Secure Hash Algorithm 2 (224 Bits, RFC 3874)

@item SHA256
Secure Hash Algorithm 2 (256 Bits, RFC 6234)

@item SHA384
Secure Hash Algorithm 2 (384 Bits, RFC 6234)

@item SHA512
Secure Hash Algorithm 2 (512 Bits, RFC 6234)
@end table

To calculate for example the MD5 hash value of the string
@nospell{@qcode{"abc"}} the @code{hash} function is called as follows:

@example
@group
hash ("md5", "abc")
     @print{} ans = 900150983cd24fb0d6963f7d28e17f72
@end group
@end example

For the same string, the SHA-1 hash value is calculated with:

@example
@group
hash ("sha1", "abc")
     @print{} ans = a9993e364706816aba3e25717850c26c9cd0d89d
@end group
@end example

And to compute the hash value of a file, e.g., @code{file = "file.txt"},
call @code{hash} in combination with the @code{fileread}:

@example
@group
hash ("md5", fileread (file));
@end group
@end example

@end deftypefn
get_help_text
@c get_help_text libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn {} {[@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 @qcode{"texinfo"}, @qcode{"html"}, or
@w{@qcode{"plain text"}}.
@seealso{get_help_text_from_file}
@end deftypefn
get_help_text_from_file
@c get_help_text_from_file libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn {} {[@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 @qcode{"texinfo"}, @qcode{"html"}, or
@w{@qcode{"plain text"}}.
@seealso{get_help_text}
@end deftypefn
__operators__
@c __operators__ libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn {} {} __operators__ ()
Undocumented internal function.
@end deftypefn
__builtins__
@c __builtins__ libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn {} {} __builtins__ ()
Undocumented internal function.
@end deftypefn
localfunctions
@c localfunctions libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn {} {} localfunctions ()
Return a list of all local functions, i.e., subfunctions, within the current
file.

The return value is a column cell array of function handles to all local
functions accessible from the function from which @code{localfunctions} is
called.  Nested functions are @emph{not} included in the list.

If the call is from the command line, an anonymous function, or a script,
the return value is an empty cell array.

@seealso{functions}
@end deftypefn
__which__
@c __which__ libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn {} {} __which__ (@var{name}, @dots{})
Undocumented internal function.
@end deftypefn
__list_functions__
@c __list_functions__ libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn  {} {@var{retval} =} __list_functions__ ()
@deftypefnx {} {@var{retval} =} __list_functions__ (@var{directory})
Return a list of all functions (.m and .oct functions) in the load path.

If the optional argument @var{directory} is given then list only the functions
in that directory.
@seealso{path}
@end deftypefn
built_in_docstrings_file
@c built_in_docstrings_file libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} built_in_docstrings_file ()
@deftypefnx {} {@var{old_val} =} built_in_docstrings_file (@var{new_val})
@deftypefnx {} {} built_in_docstrings_file (@var{new_val}, "local")
Query or set the internal variable that specifies the name of the
file containing docstrings for built-in Octave functions.

The default value is
@file{@var{octave-home}/share/octave/@var{version}/etc/built-in-docstrings},
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_BUILT_IN_DOCSTRINGS_FILE}}, or the command line argument
@option{--built-in-docstrings-file FNAME}.

Note: This variable is only used when Octave is initializing itself.
Modifying it during a running session of Octave will have no effect.
@end deftypefn
doc_cache_file
@c doc_cache_file libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} doc_cache_file ()
@deftypefnx {} {@var{old_val} =} doc_cache_file (@var{new_val})
@deftypefnx {} {} 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
@option{--doc-cache-file FNAME}.

When called from inside a function with the @qcode{"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{doc_cache_create, lookfor, info_program, doc, help, makeinfo_program}
@seealso{lookfor}
@end deftypefn
info_file
@c info_file libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} info_file ()
@deftypefnx {} {@var{old_val} =} info_file (@var{new_val})
@deftypefnx {} {} 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
@option{--info-file FNAME}.

When called from inside a function with the @qcode{"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 libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} info_program ()
@deftypefnx {} {@var{old_val} =} info_program (@var{new_val})
@deftypefnx {} {} 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
@option{--info-program NAME}.

When called from inside a function with the @qcode{"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 libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} makeinfo_program ()
@deftypefnx {} {@var{old_val} =} makeinfo_program (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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{texi_macros_file, info_file, info_program, doc, help}
@end deftypefn
suppress_verbose_help_message
@c suppress_verbose_help_message libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} suppress_verbose_help_message ()
@deftypefnx {} {@var{old_val} =} suppress_verbose_help_message (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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
texi_macros_file
@c texi_macros_file libinterp/corefcn/help.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} texi_macros_file ()
@deftypefnx {} {@var{old_val} =} texi_macros_file (@var{new_val})
@deftypefnx {} {} texi_macros_file (@var{new_val}, "local")
Query or set the internal variable that specifies the name of the
file containing Texinfo macros that are prepended to documentation strings
before they are passed to makeinfo.

The default value is
@file{@var{octave-home}/share/octave/@var{version}/etc/macros.texi},
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_TEXI_MACROS_FILE}}, or the command line argument
@option{--texi-macros-file FNAME}.

When called from inside a function with the @qcode{"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{makeinfo_program}
@end deftypefn
hess
@c hess libinterp/corefcn/hess.cc
-*- texinfo -*-
@deftypefn  {} {@var{H} =} hess (@var{A})
@deftypefnx {} {[@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 > 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 @nospell{Golub, Nash, and Van Loan},
IEEE Transactions on Automatic Control, 1979).
@seealso{eig, chol, lu, qr, qz, schur, svd}
@end deftypefn
hex2num
@c hex2num libinterp/corefcn/hex2num.cc
-*- texinfo -*-
@deftypefn  {} {@var{n} =} hex2num (@var{s})
@deftypefnx {} {@var{n} =} hex2num (@var{s}, @var{class})
Typecast a hexadecimal character array or cell array of strings to an
array of numbers.

By default, the input array is interpreted as a hexadecimal number
representing a double precision value.  If fewer than 16 characters are
given the strings are right padded with @qcode{'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

The optional second argument @var{class} may be used to cause the input
array to be interpreted as a different value type.  Possible values are

@multitable {Option} {Characters}
@headitem Option @tab Characters
@item @qcode{"int8"} @tab 2
@item @qcode{"uint8"} @tab 2
@item @qcode{"int16"} @tab 4
@item @qcode{"uint16"} @tab 4
@item @qcode{"int32"} @tab 8
@item @qcode{"uint32"} @tab 8
@item @qcode{"int64"} @tab 16
@item @qcode{"uint64"} @tab 16
@item @qcode{"char"} @tab 2
@item @qcode{"single"} @tab 8
@item @qcode{"double"} @tab 16
@end multitable

For example:

@example
@group
hex2num (["402df854"; "41200000"], "single")
   @result{} [2.7183; 10.000]
@end group
@end example
@seealso{num2hex, hex2dec, dec2hex}
@end deftypefn
num2hex
@c num2hex libinterp/corefcn/hex2num.cc
-*- texinfo -*-
@deftypefn  {} {@var{s} =} num2hex (@var{n})
@deftypefnx {} {@var{s} =} num2hex (@var{n}, "cell")
Convert a numeric array to an array of hexadecimal strings.

For example:

@example
@group
num2hex ([-1, 1, e, Inf])
@result{} "bff0000000000000
    3ff0000000000000
    4005bf0a8b145769
    7ff0000000000000"
@end group
@end example

If the argument @var{n} is a single precision number or vector, the returned
string has a length of 8.  For example:

@example
@group
num2hex (single ([-1, 1, e, Inf]))
@result{} "bf800000
    3f800000
    402df854
    7f800000"
@end group
@end example

With the optional second argument @qcode{"cell"}, return a cell array of
strings instead of a character array.
@seealso{hex2num, hex2dec, dec2hex}
@end deftypefn
input
@c input libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn  {} {@var{ans} =} input (@var{prompt})
@deftypefnx {} {@var{ans} =} input (@var{prompt}, "s")
Print @var{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 Octave code.

The number of return arguments, their size, and their class depend on the
expression entered.

If you are only interested in getting a literal string value, you can call
@code{input} with the character string @qcode{"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.
@seealso{yes_or_no, kbhit, pause, menu, listdlg}
@end deftypefn
yes_or_no
@c yes_or_no libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn {} {@var{ans} =} yes_or_no ("@var{prompt}")
Ask the user a yes-or-no question.

Return logical true if the answer is yes or false if the answer is no.

Takes one argument, @var{prompt}, which is the string to display when asking
the question.  @var{prompt} should end in a space; @code{yes-or-no} adds the
string @samp{(yes or no) } to it.  The user must confirm the answer with
@key{RET} and can edit it until it has been confirmed.
@seealso{input}
@end deftypefn
keyboard
@c keyboard libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn  {} {} keyboard ()
@deftypefnx {} {} keyboard ("@var{prompt}")
Stop m-file execution and enter debug mode.

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{dbstop, dbcont, dbquit}
@end deftypefn
completion_matches
@c completion_matches libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn {} {} 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
readline_read_init_file
@c readline_read_init_file libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn {} {} readline_read_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.
@seealso{readline_re_read_init_file}
@end deftypefn
readline_re_read_init_file
@c readline_re_read_init_file libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn {} {} readline_re_read_init_file ()
Re-read the last readline library initialization file that was read.

@xref{Readline Init File, , , readline, GNU Readline Library},
for details.
@seealso{readline_read_init_file}
@end deftypefn
add_input_event_hook
@c add_input_event_hook libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn  {} {@var{id} =} add_input_event_hook (@var{fcn})
@deftypefnx {} {@var{id} =} add_input_event_hook (@var{fcn}, @var{data})
Add the named function or function handle @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.

The returned identifier may be used to remove the function handle from the
list of input hook functions.
@seealso{remove_input_event_hook}
@end deftypefn
remove_input_event_hook
@c remove_input_event_hook libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn  {} {} remove_input_event_hook (@var{name})
@deftypefnx {} {} remove_input_event_hook (@var{fcn_id})
Remove the named function or function handle with the given identifier
from the list of functions to call periodically when Octave is waiting
for input.
@seealso{add_input_event_hook}
@end deftypefn
PS1
@c PS1 libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} PS1 ()
@deftypefnx {} {@var{old_val} =} PS1 (@var{new_val})
@deftypefnx {} {} 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 @qcode{'octave:\#> '}.
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 @qcode{"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 libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} PS2 ()
@deftypefnx {} {@var{old_val} =} PS2 (@var{new_val})
@deftypefnx {} {} 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 @qcode{"> "}.

When called from inside a function with the @qcode{"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
completion_append_char
@c completion_append_char libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} completion_append_char ()
@deftypefnx {} {@var{old_val} =} completion_append_char (@var{new_val})
@deftypefnx {} {} 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 @qcode{" "} (a single space).

When called from inside a function with the @qcode{"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__ libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn  {} {} __request_drawnow__ ()
@deftypefnx {} {} __request_drawnow__ (@var{flag})
Undocumented internal function.
@end deftypefn
__gud_mode__
@c __gud_mode__ libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn {} {} __gud_mode__ ()
Undocumented internal function.
@end deftypefn
__mfile_encoding__
@c __mfile_encoding__ libinterp/corefcn/input.cc
-*- texinfo -*-
@deftypefn {} {@var{current_encoding} =} __mfile_encoding__ (@var{new_encoding})
Set and query the codepage that is used for reading .m files.
@end deftypefn
inv
@c inv libinterp/corefcn/inv.cc
-*- texinfo -*-
@deftypefn  {} {@var{x} =} inv (@var{A})
@deftypefnx {} {[@var{x}, @var{rcond}] =} inv (@var{A})
@deftypefnx {} {[@dots{}] =} inverse (@dots{})
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.

@code{inverse} is an alias and may be used identically in place of @code{inv}.
@seealso{ldivide, rdivide, pinv}
@end deftypefn
__version_info__
@c __version_info__ libinterp/corefcn/interpreter.cc
-*- texinfo -*-
@deftypefn {} {retval =} __version_info__ (@var{name}, @var{version}, @var{release}, @var{date})
Undocumented internal function.
@end deftypefn
quit
@c quit libinterp/corefcn/interpreter.cc
-*- texinfo -*-
@deftypefn  {} {} exit
@deftypefnx {} {} exit (@var{status})
@deftypefnx {} {} quit
@deftypefnx {} {} 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 Octave's exit status.  The default value is zero.

When exiting, Octave will attempt to run the m-file @file{finish.m} if it
exists.  User commands to save the workspace or clean up temporary files
may be placed in that file.  Alternatively, another m-file may be scheduled
to run using @code{atexit}.
@seealso{atexit}
@end deftypefn
atexit
@c atexit libinterp/corefcn/interpreter.cc
-*- texinfo -*-
@deftypefn  {} {} atexit (@var{fcn})
@deftypefnx {} {} 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 @qcode{"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.
@seealso{quit}
@end deftypefn
kron
@c kron libinterp/corefcn/kron.cc
-*- texinfo -*-
@deftypefn  {} {} kron (@var{A}, @var{B})
@deftypefnx {} {} kron (@var{A1}, @var{A2}, @dots{})
Form the Kronecker product of two or more matrices.

This is 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
genpath
@c genpath libinterp/corefcn/load-path.cc
-*- texinfo -*-
@deftypefn  {} {} genpath (@var{dir})
@deftypefnx {} {} genpath (@var{dir}, @var{skip}, @dots{})
Return a path constructed from @var{dir} and all its subdirectories.

The path does not include package directories (beginning with @samp{+}),
old-style class directories (beginning with @samp{@@}), @file{private}
directories, or any subdirectories of these types.

If additional string parameters are given, the resulting path will exclude
directories with those names.
@seealso{path, addpath}
@end deftypefn
rehash
@c rehash libinterp/corefcn/load-path.cc
-*- texinfo -*-
@deftypefn {} {} rehash ()
Reinitialize Octave's load path directory cache.
@end deftypefn
command_line_path
@c command_line_path libinterp/corefcn/load-path.cc
-*- texinfo -*-
@deftypefn {} {} command_line_path ()
Return the command line path variable.

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

@seealso{path, addpath, rmpath, genpath, pathdef, savepath, pathsep}
@end deftypefn
__pathorig__
@c __pathorig__ libinterp/corefcn/load-path.cc
-*- texinfo -*-
@deftypefn {} {@var{val} =} __pathorig__ ()
Undocumented internal function.
@end deftypefn
path
@c path libinterp/corefcn/load-path.cc
-*- texinfo -*-
@deftypefn  {} {} path ()
@deftypefnx {} {@var{str} =} path ()
@deftypefnx {} {@var{str} =} path (@var{path1}, @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 libinterp/corefcn/load-path.cc
-*- texinfo -*-
@deftypefn  {} {} addpath (@var{dir1}, @dots{})
@deftypefnx {} {} addpath (@var{dir1}, @dots{}, @var{option})
Add named directories to the function search path.

If @var{option} is @qcode{"-begin"} or 0 (the default), prepend the
directory name to the current path.  If @var{option} is @qcode{"-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

For each directory that is added, and that was not already in the path,
@code{addpath} checks for the existence of a file named @file{PKG_ADD}
(note lack of .m extension) and runs it if it exists.

@seealso{path, rmpath, genpath, pathdef, savepath, pathsep}
@end deftypefn
rmpath
@c rmpath libinterp/corefcn/load-path.cc
-*- texinfo -*-
@deftypefn {} {} 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

For each directory that is removed, @code{rmpath} checks for the
existence of a file named @file{PKG_DEL} (note lack of .m extension)
and runs it if it exists.

@seealso{path, addpath, genpath, pathdef, savepath, pathsep}
@end deftypefn
__dump_load_path__
@c __dump_load_path__ libinterp/corefcn/load-path.cc
-*- texinfo -*-
@deftypefn {} {} __dump_load_path__ ()
Undocumented internal function.
@end deftypefn
load
@c load libinterp/corefcn/load-save.cc
-*- texinfo -*-
@deftypefn  {} {} load file
@deftypefnx {} {} load options file
@deftypefnx {} {} load options file v1 v2 @dots{}
@deftypefnx {} {S =} load ("options", "file", "v1", "v2", @dots{})
@deftypefnx {} {} load file options
@deftypefnx {} {} load file options v1 v2 @dots{}
@deftypefnx {} {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 only read @sc{hdf5} files that were created by itself with
@code{save}.  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 libinterp/corefcn/load-save.cc
-*- texinfo -*-
@deftypefn  {} {} save file
@deftypefnx {} {} save options file
@deftypefnx {} {} save options file @var{v1} @var{v2} @dots{}
@deftypefnx {} {} save options file -struct @var{STRUCT}
@deftypefnx {} {} save options file -struct @var{STRUCT} @var{f1} @var{f2} @dots{}
@deftypefnx {} {} save - @var{v1} @var{v2} @dots{}
@deftypefnx {} {@var{str} =} save ("-", @qcode{"@var{v1}"}, @qcode{"@var{v2}"}, @dots{})
Save the named variables @var{v1}, @var{v2}, @dots{}, in the file @var{file}.

The special filename @samp{-} may be used to return the content of the
variables as a string.  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 then the fields of the @strong{scalar} struct are saved as if
they were variables with the corresponding field names.  The @option{-struct}
option can be combined with specific field names @var{f1}, @var{f2}, @dots{} to
write only certain fields to the file.

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{save_default_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.

If called with a filename of @qcode{"-"}, write the output to stdout if nargout
is 0, otherwise return the output in a character string.

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

@item -ascii
Save a matrix in a text file without a header or any other information.  The
matrix must be 2-D and only the real part of any complex value is written to
the file.  Numbers are stored in single-precision format and separated by
spaces.  Additional options for the @option{-ascii} format are

@table @code
@item -double
Store numbers in double-precision format.

@item -tabs
Separate numbers with tabs.
@end table

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

@item -float-binary
Save the data in Octave's binary data format but using only single precision.
Use this format @strong{only} 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 using only single precision.  Use this
format @strong{only} 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 on files that are
compressed with gzip outside of Octave, and gzip can also 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, save_default_options, save_header_format_string, save_precision, dlmread, csvread, fread}
@end deftypefn
crash_dumps_octave_core
@c crash_dumps_octave_core libinterp/corefcn/load-save.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} crash_dumps_octave_core ()
@deftypefnx {} {@var{old_val} =} crash_dumps_octave_core (@var{new_val})
@deftypefnx {} {} 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 @file{octave-workspace} if it
crashes or receives a hangup, terminate or similar signal.

When called from inside a function with the @qcode{"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
save_default_options
@c save_default_options libinterp/corefcn/load-save.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} save_default_options ()
@deftypefnx {} {@var{old_val} =} save_default_options (@var{new_val})
@deftypefnx {} {} save_default_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.

The default value is @qcode{"-text"} (Octave's own text-based file format).
See the documentation of the @code{save} command for other choices.

When called from inside a function with the @qcode{"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, save_header_format_string, save_precision}
@end deftypefn
octave_core_file_limit
@c octave_core_file_limit libinterp/corefcn/load-save.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} octave_core_file_limit ()
@deftypefnx {} {@var{old_val} =} octave_core_file_limit (@var{new_val})
@deftypefnx {} {} octave_core_file_limit (@var{new_val}, "local")
Query or set the internal variable that specifies the maximum amount of memory
that Octave will save when writing a crash dump file.

The limit is measured in kilobytes and is applied to the top-level workspace.
The name of the crash dump 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 @qcode{"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 libinterp/corefcn/load-save.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} octave_core_file_name ()
@deftypefnx {} {@var{old_val} =} octave_core_file_name (@var{new_val})
@deftypefnx {} {} 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 @qcode{"octave-workspace"}

When called from inside a function with the @qcode{"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 libinterp/corefcn/load-save.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} octave_core_file_options ()
@deftypefnx {} {@var{old_val} =} octave_core_file_options (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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 libinterp/corefcn/load-save.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} save_header_format_string ()
@deftypefnx {} {@var{old_val} =} save_header_format_string (@var{new_val})
@deftypefnx {} {} 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 must 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 @qcode{"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_default_options}
@end deftypefn
lookup
@c lookup libinterp/corefcn/lookup.cc
-*- texinfo -*-
@deftypefn  {} {@var{idx} =} lookup (@var{table}, @var{y})
@deftypefnx {} {@var{idx} =} lookup (@var{table}, @var{y}, @var{opt})
Lookup values in a @strong{sorted} table.

This function is usually used as a prelude to interpolation.

If table is increasing, of length N 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 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 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
Match.  @code{table(idx(i)) == y(i)} if @code{y(i)} occurs in table;
otherwise, @code{idx(i)} is zero.

@item b
Boolean.  @code{idx(i)} is a logical 1 or 0, indicating whether @code{y(i)}
is contained in table or not.

@item l
Left.  For numeric lookups the leftmost subinterval shall be extended to
minus infinity (i.e., all indices at least 1).

@item r
Right.  For numeric lookups the rightmost subinterval shall be extended to
infinity (i.e., all indices at most N-1).
@end table

@strong{Note}: If @var{table} is not sorted the results from @code{lookup}
will be unpredictable.
@end deftypefn
save_precision
@c save_precision libinterp/corefcn/ls-oct-text.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} save_precision ()
@deftypefnx {} {@var{old_val} =} save_precision (@var{new_val})
@deftypefnx {} {} 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.

The default value is 17 which is the minimum necessary for the lossless saving
and restoring of IEEE-754 double values; For IEEE-754 single values the minimum
value is 9.  If file size is a concern, it is probably better to choose a
binary format for saving data rather than to reduce the precision of the saved
values.

When called from inside a function with the @qcode{"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_default_options}
@end deftypefn
lsode
@c lsode libinterp/corefcn/lsode.cc
-*- texinfo -*-
@deftypefn  {} {[@var{x}, @var{istate}, @var{msg}] =} lsode (@var{fcn}, @var{x_0}, @var{t})
@deftypefnx {} {[@var{x}, @var{istate}, @var{msg}] =} lsode (@var{fcn}, @var{x_0}, @var{t}, @var{t_crit})
Ordinary Differential Equation (ODE) solver.

The set of differential equations to solve is
@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 argument specifies the initial state of the system @math{x_0}.  The
third argument is a vector, @var{t}, specifying the time values for which a
solution is sought.

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 libinterp/corefcn/lu.cc
-*- texinfo -*-
@deftypefn  {} {[@var{L}, @var{U}] =} lu (@var{A})
@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} lu (@var{A})
@deftypefnx {} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} lu (@var{S})
@deftypefnx {} {[@var{L}, @var{U}, @var{P}, @var{Q}, @var{R}] =} lu (@var{S})
@deftypefnx {} {[@dots{}] =} lu (@var{S}, @var{thres})
@deftypefnx {} {@var{y} =} lu (@dots{})
@deftypefnx {} {[@dots{}] =} lu (@dots{}, "vector")
@cindex LU decomposition
Compute the LU@tie{}decomposition of @var{A}.

If @var{A} is full then 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 sparse 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}}.  This is the
@strong{preferred} way to call @code{lu} with sparse input matrices.

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 @qcode{"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.
@seealso{luupdate, ilu, chol, hess, qr, qz, schur, svd}
@end deftypefn
luupdate
@c luupdate libinterp/corefcn/lu.cc
-*- texinfo -*-
@deftypefn  {} {[@var{L}, @var{U}] =} luupdate (@var{L}, @var{U}, @var{x}, @var{y})
@deftypefnx {} {[@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 @tcode{@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, cholupdate, qrupdate}
@end deftypefn
abs
@c abs libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} abs (@var{z})
Compute the magnitude of @var{z}.

The magnitude is 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
@seealso{arg}
@end deftypefn
acos
@c acos libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} acos (@var{x})
Compute the inverse cosine in radians for each element of @var{x}.
@seealso{cos, acosd}
@end deftypefn
acosh
@c acosh libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} acosh (@var{x})
Compute the inverse hyperbolic cosine for each element of @var{x}.
@seealso{cosh}
@end deftypefn
angle
@c angle libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} angle (@var{z})
See @code{arg}.
@seealso{arg}
@end deftypefn
arg
@c arg libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn  {} {} arg (@var{z})
@deftypefnx {} {} angle (@var{z})
Compute the argument, i.e., angle of @var{z}.

This is 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
@seealso{abs}
@end deftypefn
asin
@c asin libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} asin (@var{x})
Compute the inverse sine in radians for each element of @var{x}.
@seealso{sin, asind}
@end deftypefn
asinh
@c asinh libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} asinh (@var{x})
Compute the inverse hyperbolic sine for each element of @var{x}.
@seealso{sinh}
@end deftypefn
atan
@c atan libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} atan (@var{x})
Compute the inverse tangent in radians for each element of @var{x}.
@seealso{tan, atand}
@end deftypefn
atanh
@c atanh libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} atanh (@var{x})
Compute the inverse hyperbolic tangent for each element of @var{x}.
@seealso{tanh}
@end deftypefn
cbrt
@c cbrt libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} conj (@var{z})
Return the complex conjugate of @var{z}.

The complex conjugate is 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} cos (@var{x})
Compute the cosine for each element of @var{x} in radians.
@seealso{acos, cosd, cosh}
@end deftypefn
cosh
@c cosh libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} cosh (@var{x})
Compute the hyperbolic cosine for each element of @var{x}.
@seealso{acosh, sinh, tanh}
@end deftypefn
erf
@c erf libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} erf (@var{z})
Compute the error function.

The error function is defined as
@tex
$$
 {\rm erf} (z) = {2 \over \sqrt{\pi}}\int_0^z e^{-t^2} dt
$$
@end tex
@ifnottex

@example
@group
                        z
              2        /
erf (z) = --------- *  | e^(-t^2) dt
          sqrt (pi)    /
                    t=0
@end group
@end example

@end ifnottex
@seealso{erfc, erfcx, erfi, dawson, erfinv, erfcinv}
@end deftypefn
erfinv
@c erfinv libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} erfinv (@var{x})
Compute the inverse error function.

The inverse error function is defined such that

@example
erf (@var{y}) == @var{x}
@end example
@seealso{erf, erfc, erfcx, erfi, dawson, erfcinv}
@end deftypefn
erfcinv
@c erfcinv libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} erfcinv (@var{x})
Compute the inverse complementary error function.

The inverse complementary error function is defined such that

@example
erfc (@var{y}) == @var{x}
@end example
@seealso{erfc, erf, erfcx, erfi, dawson, erfinv}
@end deftypefn
erfc
@c erfc libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} erfc (@var{z})
Compute the complementary error function.

The complementary error function is defined as
@tex
$1 - {\rm erf} (z)$.
@end tex
@ifnottex
@w{@code{1 - erf (@var{z})}}.
@end ifnottex
@seealso{erfcinv, erfcx, erfi, dawson, erf, erfinv}
@end deftypefn
erfcx
@c erfcx libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} erfcx (@var{z})
Compute the scaled complementary error function.

The scaled complementary error function is defined as
@tex
$$
 e^{z^2} {\rm erfc} (z) \equiv e^{z^2} (1 - {\rm erf} (z))
$$
@end tex
@ifnottex

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

@end ifnottex
@seealso{erfc, erf, erfi, dawson, erfinv, erfcinv}
@end deftypefn
erfi
@c erfi libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} erfi (@var{z})
Compute the imaginary error function.

The imaginary error function is defined as
@tex
$$
 -i {\rm erf} (iz)
$$
@end tex
@ifnottex

@example
-i * erf (i*z)
@end example

@end ifnottex
@seealso{erfc, erf, erfcx, dawson, erfinv, erfcinv}
@end deftypefn
dawson
@c dawson libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} dawson (@var{z})
Compute the Dawson (scaled imaginary error) function.

The Dawson function is defined as
@tex
$$
 {\sqrt{\pi} \over 2} e^{-z^2} {\rm erfi} (z) \equiv -i {\sqrt{\pi} \over 2} e^{-z^2} {\rm erf} (iz)
$$
@end tex
@ifnottex

@example
(sqrt (pi) / 2) * exp (-z^2) * erfi (z)
@end example

@end ifnottex
@seealso{erfc, erf, erfcx, erfi, erfinv, erfcinv}
@end deftypefn
exp
@c exp libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} isfinite (@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
isfinite ([13, Inf, NA, NaN])
     @result{} [ 1, 0, 0, 0 ]
@end group
@end example
@seealso{isinf, isnan, isna}
@end deftypefn
fix
@c fix libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} gamma (@var{z})
Compute the Gamma function.

The Gamma function is defined as
@tex
$$
 \Gamma (z) = \int_0^\infty t^{z-1} e^{-t} dt.
$$
@end tex
@ifnottex

@example
@group
             infinity
            /
gamma (z) = | t^(z-1) exp (-t) dt.
            /
         t=0
@end group
@end example

@end ifnottex

Programming Note: The gamma function can grow quite large even for small
input values.  In many cases it may be preferable to use the natural
logarithm of the gamma function (@code{gammaln}) in calculations to minimize
loss of precision.  The final result is then
@code{exp (@var{result_using_gammaln}).}
@seealso{gammainc, gammaln, factorial}
@end deftypefn
imag
@c imag libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} imag (@var{z})
Return the imaginary part of @var{z} as a real number.
@seealso{real, conj}
@end deftypefn
isalnum
@c isalnum libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} isinf (@var{x})
Return a logical array which is true where the elements of @var{x} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn  {} {} gammaln (@var{x})
@deftypefnx {} {} lgamma (@var{x})
Return the natural logarithm of the gamma function of @var{x}.
@seealso{gamma, gammainc}
@end deftypefn
log
@c log libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} log10 (@var{x})
Compute the base-10 logarithm of each element of @var{x}.
@seealso{log, log2, logspace, exp}
@end deftypefn
log1p
@c log1p libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} real (@var{z})
Return the real part of @var{z}.
@seealso{imag, conj}
@end deftypefn
round
@c round libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} sign (@var{x})
Compute the @dfn{signum} function.

This 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})}.

Note that @code{sign (-0.0)} is 0.  Although IEEE 754 floating point
allows zero to be signed, 0.0 and -0.0 compare equal.  If you must test
whether zero is signed, use the @code{signbit} function.
@seealso{signbit}
@end deftypefn
signbit
@c signbit libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} signbit (@var{x})
Return logical true if the value of @var{x} has its sign bit set and false
otherwise.

This behavior is consistent with the other logical functions.
See @ref{Logical Values}.  The behavior differs from the C language function
which returns nonzero if the sign bit is set.

This is not the same as @code{x < 0.0}, because IEEE 754 floating point
allows zero to be signed.  The comparison @code{-0.0 < 0.0} is false,
but @code{signbit (-0.0)} will return a nonzero value.
@seealso{sign}
@end deftypefn
sin
@c sin libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} sin (@var{x})
Compute the sine for each element of @var{x} in radians.
@seealso{asin, sind, sinh}
@end deftypefn
sinh
@c sinh libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} sinh (@var{x})
Compute the hyperbolic sine for each element of @var{x}.
@seealso{asinh, cosh, tanh}
@end deftypefn
sqrt
@c sqrt libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} tan (@var{z})
Compute the tangent for each element of @var{x} in radians.
@seealso{atan, tand, tanh}
@end deftypefn
tanh
@c tanh libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn {} {} tanh (@var{x})
Compute hyperbolic tangent for each element of @var{x}.
@seealso{atanh, sinh, cosh}
@end deftypefn
tolower
@c tolower libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn  {} {} tolower (@var{s})
@deftypefnx {} {} 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 libinterp/corefcn/mappers.cc
-*- texinfo -*-
@deftypefn  {} {} toupper (@var{s})
@deftypefnx {} {} 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
matrix_type
@c matrix_type libinterp/corefcn/matrix_type.cc
-*- texinfo -*-
@deftypefn  {} {@var{type} =} matrix_type (@var{A})
@deftypefnx {} {@var{type} =} matrix_type (@var{A}, "nocompute")
@deftypefnx {} {@var{A} =} matrix_type (@var{A}, @var{type})
@deftypefnx {} {@var{A} =} matrix_type (@var{A}, "upper", @var{perm})
@deftypefnx {} {@var{A} =} matrix_type (@var{A}, "lower", @var{perm})
@deftypefnx {} {@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 @qcode{"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 @qcode{"unknown"}
Remove any previously cached matrix type, and mark type as unknown.

@item @qcode{"full"}
Mark the matrix as full.

@item @qcode{"positive definite"}
Probable full positive definite matrix.

@item @qcode{"diagonal"}
Diagonal matrix.  (Sparse matrices only)

@item @qcode{"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 @qcode{"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 @qcode{"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  @qcode{"banded"}
@itemx @qcode{"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 @qcode{"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 libinterp/corefcn/max.cc
-*- texinfo -*-
@deftypefn  {} {} min (@var{x})
@deftypefnx {} {} min (@var{x}, [], @var{dim})
@deftypefnx {} {[@var{w}, @var{iw}] =} min (@var{x})
@deftypefnx {} {} min (@var{x}, @var{y})
Find minimum values in the array @var{x}.

For a vector argument, return the minimum value.  For a matrix argument,
return a row vector with the minimum value of each column.  For a
multi-dimensional array, @code{min} operates along the first non-singleton
dimension.

If the optional third argument @var{dim} is present then operate along
this dimension.  In this case the second argument is ignored and should be
set to the empty matrix.

For two matrices (or a matrix and a scalar), return the pairwise minimum.

Thus,

@example
min (min (@var{x}))
@end example

@noindent
returns the smallest element of the 2-D matrix @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 the magnitudes are identical, then the results are ordered
by phase angle in the range (-pi, pi].  Hence,

@example
@group
min ([-1 i 1 -i])
    @result{} -i
@end group
@end example

@noindent
because all entries have magnitude 1, but -i has the smallest phase angle
with value -pi/2.

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 libinterp/corefcn/max.cc
-*- texinfo -*-
@deftypefn  {} {} max (@var{x})
@deftypefnx {} {} max (@var{x}, [], @var{dim})
@deftypefnx {} {[@var{w}, @var{iw}] =} max (@var{x})
@deftypefnx {} {} max (@var{x}, @var{y})
Find maximum values in the array @var{x}.

For a vector argument, return the maximum value.  For a matrix argument,
return a row vector with the maximum value of each column.  For a
multi-dimensional array, @code{max} operates along the first non-singleton
dimension.

If the optional third argument @var{dim} is present then operate along
this dimension.  In this case the second argument is ignored and should be
set to the empty matrix.

For two matrices (or a matrix and a scalar), return the pairwise maximum.

Thus,

@example
max (max (@var{x}))
@end example

@noindent
returns the largest element of the 2-D 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 the magnitudes are identical, then the results are ordered
by phase angle in the range (-pi, pi].  Hence,

@example
@group
max ([-1 i 1 -i])
    @result{} -1
@end group
@end example

@noindent
because all entries have magnitude 1, but -1 has the largest phase angle
with value pi.

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 libinterp/corefcn/max.cc
-*- texinfo -*-
@deftypefn  {} {} cummin (@var{x})
@deftypefnx {} {} cummin (@var{x}, @var{dim})
@deftypefnx {} {[@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

If called with two output arguments the index of the minimum value is also
returned.

@example
@group
[w, iw] = cummin ([5 4 6 2 3 1])
@result{}
w =  5  4  4  2  2  1
iw = 1  2  2  4  4  6
@end group
@end example

@seealso{cummax, min, max}
@end deftypefn
cummax
@c cummax libinterp/corefcn/max.cc
-*- texinfo -*-
@deftypefn  {} {} cummax (@var{x})
@deftypefnx {} {} cummax (@var{x}, @var{dim})
@deftypefnx {} {[@var{w}, @var{iw}] =} cummax (@dots{})
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

If called with two output arguments the index of the maximum value is also
returned.

@example
@group
[w, iw] = cummax ([1 3 2 6 4 5])
@result{}
w =  1  3  3  6  6  6
iw = 1  2  2  4  4  4
@end group
@end example

@seealso{cummin, max, min}
@end deftypefn
mgorth
@c mgorth libinterp/corefcn/mgorth.cc
-*- texinfo -*-
@deftypefn {} {[@var{y}, @var{h}] =} mgorth (@var{x}, @var{v})
Orthogonalize a given column vector @var{x} with respect to a set of
orthonormal vectors comprising the columns of @var{v} using the modified
Gram-Schmidt method.

On exit, @var{y} is a unit vector such that:

@example
@group
  norm (@var{y}) = 1
  @var{v}' * @var{y} = 0
  @var{x} = [@var{v}, @var{y}]*@var{h}'
@end group
@end example

@end deftypefn
nproc
@c nproc libinterp/corefcn/nproc.cc
-*- texinfo -*-
@deftypefn  {} {} nproc ()
@deftypefnx {} {} 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
same as @code{current}, but overridable through the
@w{@env{OMP_NUM_THREADS}} environment variable.
@end table
@end deftypefn
edit_history
@c edit_history libinterp/corefcn/oct-hist.cc
-*- texinfo -*-
@deftypefn  {} {} edit_history
@deftypefnx {} {} edit_history @var{cmd_number}
@deftypefnx {} {} edit_history @var{first} @var{last}
Edit the history list using the editor named by the variable @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.
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 leaving the editor.

When invoked with no arguments, edit the previously executed command;
With one argument, edit the specified command @var{cmd_number};
With two arguments, edit the list of commands between @var{first} and
@var{last}.  Command number specifiers may also be negative where -1
refers to the most recently executed command.
The following are equivalent and edit the most recently executed command.

@example
@group
edit_history
edit_history -1
@end group
@end example

When using ranges, specifying a larger number for the first command than the
last command reverses the list of commands before they are placed in the
buffer to be edited.
@seealso{run_history, history}
@end deftypefn
history
@c history libinterp/corefcn/oct-hist.cc
-*- texinfo -*-
@deftypefn  {} {} history
@deftypefnx {} {} history @var{opt1} @dots{}
@deftypefnx {} {@var{h} =} history ()
@deftypefnx {} {@var{h} =} history (@var{opt1}, @dots{})
If invoked with no arguments, @code{history} displays a list of commands
that you have executed.

Valid options are:

@table @code
@item   @var{n}
@itemx -@var{n}
Display only the most recent @var{n} lines of history.

@item -c
Clear the history list.

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

@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 -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}).
@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}.

If invoked with a single output argument, the history will be saved to that
argument as a cell string and will not be output to screen.
@seealso{edit_history, run_history}
@end deftypefn
run_history
@c run_history libinterp/corefcn/oct-hist.cc
-*- texinfo -*-
@deftypefn  {} {} run_history
@deftypefnx {} {} run_history @var{cmd_number}
@deftypefnx {} {} run_history @var{first} @var{last}
Run commands from the history list.

When invoked with no arguments, run the previously executed command;

With one argument, run the specified command @var{cmd_number};

With two arguments, run the list of commands between @var{first} and
@var{last}.  Command number specifiers may also be negative where -1
refers to the most recently executed command.  For example, the command

@example
@group
run_history
     OR
run_history -1
@end group
@end example

@noindent
executes the most recent command again.
The command

@example
run_history 13 169
@end example

@noindent
executes commands 13 through 169.

Specifying a larger number for the first command than the last command
reverses the list of commands before executing them.
For example:

@example
@group
disp (1)
disp (2)
run_history -1 -2
@result{}
 2
 1
@end group
@end example

@seealso{edit_history, history}
@end deftypefn
history_control
@c history_control libinterp/corefcn/oct-hist.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} history_control ()
@deftypefnx {} {@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{history_save}.
@seealso{history_file, history_size, history_timestamp_format_string, history_save}
@end deftypefn
history_size
@c history_size libinterp/corefcn/oct-hist.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} history_size ()
@deftypefnx {} {@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{1000}, but may be overridden by the environment
variable @w{@env{OCTAVE_HISTSIZE}}.
@seealso{history_file, history_timestamp_format_string, history_save}
@end deftypefn
history_file
@c history_file libinterp/corefcn/oct-hist.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} history_file ()
@deftypefnx {} {@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.

All future commands issued during the current Octave session will be written to
this new file (if the current setting of @code{history_save} allows for this).

The default value is @file{~/.octave_hist}, but may be overridden by the
environment variable @w{@env{OCTAVE_HISTFILE}}.

Programming Notes:

If you want to permanently change the location of Octave's history file you
need to issue the @code{history_file} command in every new Octave session.
This can be achieved by using Octave's @file{.octaverc} startup file.

If you also want to read the saved history commands of past Octave sessions
from this different history file, then you need to use the additional command
@code{history -r} after setting the new value of the history file.  Example
code in Octave's startup file to do this might look like this:

@example
@group
history_file ("~/new/.octave_hist");
if (exist (history_file ()))
  history ("-r", history_file());
endif
@end group
@end example

@seealso{history, history_control, history_save, history_size, history_timestamp_format_string}
@end deftypefn
history_timestamp_format_string
@c history_timestamp_format_string libinterp/corefcn/oct-hist.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} history_timestamp_format_string ()
@deftypefnx {} {@var{old_val} =} history_timestamp_format_string (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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, history_save}
@end deftypefn
history_save
@c history_save libinterp/corefcn/oct-hist.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} history_save ()
@deftypefnx {} {@var{old_val} =} history_save (@var{new_val})
@deftypefnx {} {} history_save (@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 @qcode{"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
__octave_link_enabled__
@c __octave_link_enabled__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_enabled__ ()
Undocumented internal function.
@end deftypefn
__octave_link_edit_file__
@c __octave_link_edit_file__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_edit_file__ (@var{file})
Undocumented internal function.
@end deftypefn
__octave_link_question_dialog__
@c __octave_link_question_dialog__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_question_dialog__ (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{btn3}, @var{default})
Undocumented internal function.
@end deftypefn
__octave_link_file_dialog__
@c __octave_link_file_dialog__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_file_dialog__ (@var{filterlist}, @var{title}, @var{filename}, @var{size} @var{multiselect}, @var{pathname})
Undocumented internal function.
@end deftypefn
__octave_link_list_dialog__
@c __octave_link_list_dialog__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_list_dialog__ (@var{list}, @var{mode}, @var{size}, @var{intial}, @var{name}, @var{prompt}, @var{ok_string}, @var{cancel_string})
Undocumented internal function.
@end deftypefn
__octave_link_input_dialog__
@c __octave_link_input_dialog__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_input_dialog__ (@var{prompt}, @var{title}, @var{rowscols}, @var{defaults})
Undocumented internal function.
@end deftypefn
__octave_link_named_icon__
@c __octave_link_named_icon__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_dialog_icons__ (@var{icon_name})
Undocumented internal function.
@end deftypefn
__octave_link_show_preferences__
@c __octave_link_show_preferences__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_show_preferences__ ()
Undocumented internal function.
@end deftypefn
__octave_link_gui_preference__
@c __octave_link_gui_preference__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_gui_preference__ ()
Undocumented internal function.
@end deftypefn
__octave_link_file_remove__
@c __octave_link_file_remove__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_file_remove__ ()
Undocumented internal function.
@end deftypefn
__octave_link_file_renamed__
@c __octave_link_file_renamed__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_file_renamed__ ()
Undocumented internal function.
@end deftypefn
openvar
@c openvar libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} openvar (@var{name})
Open the variable @var{name} in the graphical Variable Editor.
@end deftypefn
__octave_link_show_doc__
@c __octave_link_show_doc__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_show_doc__ (@var{filename})
Undocumented internal function.
@end deftypefn
__octave_link_register_doc__
@c __octave_link_register_doc__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_register_doc__ (@var{filename})
Undocumented internal function.
@end deftypefn
__octave_link_unregister_doc__
@c __octave_link_unregister_doc__ libinterp/corefcn/octave-link.cc
-*- texinfo -*-
@deftypefn {} {} __octave_link_unregister_doc__ (@var{filename})
Undocumented internal function.
@end deftypefn
ordschur
@c ordschur libinterp/corefcn/ordschur.cc
-*- texinfo -*-
@deftypefn {} {[@var{UR}, @var{SR}] =} ordschur (@var{U}, @var{S}, @var{select})
Reorders the real Schur factorization (@var{U},@var{S}) obtained with the
@code{schur} function, so that selected eigenvalues appear in the upper left
diagonal blocks of the quasi triangular Schur matrix.

The logical vector @var{select} specifies the selected eigenvalues as they
appear along @var{S}'s diagonal.

For example, given the matrix @code{@var{A} = [1, 2; 3, 4]}, and its Schur
decomposition

@example
[@var{U}, @var{S}] = schur (@var{A})
@end example

@noindent
which returns

@example
@group
@var{U} =

  -0.82456  -0.56577
   0.56577  -0.82456

@var{S} =

  -0.37228  -1.00000
   0.00000   5.37228

@end group
@end example

It is possible to reorder the decomposition so that the positive eigenvalue
is in the upper left corner, by doing:

@example
[@var{U}, @var{S}] = ordschur (@var{U}, @var{S}, [0,1])
@end example

@seealso{schur, ordeig}
@end deftypefn
diary
@c diary libinterp/corefcn/pager.cc
-*- texinfo -*-
@deftypefn  {} {} diary
@deftypefnx {} {} diary on
@deftypefnx {} {} diary off
@deftypefnx {} {} diary @var{filename}
@deftypefnx {} {[@var{status}, @var{diaryfile}] =} diary
Record a list of all commands @emph{and} the output they produce, mixed
together just as they appear on the terminal.

Valid options are:

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

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

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

With no input or output arguments, @code{diary} toggles the current diary
state.

If output arguments are requested, @code{diary} ignores inputs and returns
the current status.  The boolean @var{status} indicates whether recording is on
or off, and @var{diaryfile} is the name of the file where the session is
stored.
@seealso{history, evalc}
@end deftypefn
more
@c more libinterp/corefcn/pager.cc
-*- texinfo -*-
@deftypefn  {} {} more
@deftypefnx {} {} more on
@deftypefnx {} {} 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}.
@seealso{page_screen_output, page_output_immediately, PAGER, PAGER_FLAGS}
@end deftypefn
terminal_size
@c terminal_size libinterp/corefcn/pager.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/pager.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} page_output_immediately ()
@deftypefnx {} {@var{old_val} =} page_output_immediately (@var{new_val})
@deftypefnx {} {} 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.

When the value is @code{false}, Octave buffers its output and waits until just
before the prompt is printed to flush it to the pager.  This is the default.

When @code{page_screen_output} is @code{false}, this variable has no effect.

When called from inside a function with the @qcode{"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{page_screen_output, more, PAGER, PAGER_FLAGS}
@end deftypefn
page_screen_output
@c page_screen_output libinterp/corefcn/pager.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} page_screen_output ()
@deftypefnx {} {@var{old_val} =} page_screen_output (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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_output_immediately, PAGER, PAGER_FLAGS}
@end deftypefn
PAGER
@c PAGER libinterp/corefcn/pager.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} PAGER ()
@deftypefnx {} {@var{old_val} =} PAGER (@var{new_val})
@deftypefnx {} {} 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 @qcode{"less"}, @qcode{"more"}, or
@qcode{"pg"}, depending on what programs are installed on your system.
@xref{Installation}.

When called from inside a function with the @qcode{"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_FLAGS, page_output_immediately, more, page_screen_output}
@end deftypefn
PAGER_FLAGS
@c PAGER_FLAGS libinterp/corefcn/pager.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} PAGER_FLAGS ()
@deftypefnx {} {@var{old_val} =} PAGER_FLAGS (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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, more, page_screen_output, page_output_immediately}
@end deftypefn
pinv
@c pinv libinterp/corefcn/pinv.cc
-*- texinfo -*-
@deftypefn  {} {} pinv (@var{x})
@deftypefnx {} {} pinv (@var{x}, @var{tol})
Return the @nospell{Moore-Penrose} 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 ([rows(@var{x}), columns(@var{x})]) * norm (@var{x}) * eps
@end example

@seealso{inv, ldivide}
@end deftypefn
output_precision
@c output_precision libinterp/corefcn/pr-flt-fmt.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} output_precision ()
@deftypefnx {} {@var{old_val} =} output_precision (@var{new_val})
@deftypefnx {} {} 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.

Note that regardless of the value set for @code{output_precision}, the
number of digits of precision displayed is limited to 16 for double
precision values and 7 for single precision values.

When called from inside a function with the @qcode{"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}
@end deftypefn
rats
@c rats libinterp/corefcn/pr-output.cc
-*- texinfo -*-
@deftypefn  {} {@var{s} =} rats (@var{x})
@deftypefnx {} {@var{s} =} rats (@var{x}, @var{len})
Convert @var{x} into a rational approximation represented as a string.

A rational approximation to a floating point number is a simple fraction
with numerator @var{N} and denominator @var{D} such that
@code{@var{x} = @var{N}/@var{D}}.

The optional second argument defines the maximum length of the string
representing the elements of @var{x}.  By default, @var{len} is 9.

If the length of the smallest possible rational approximation exceeds
@var{len}, an asterisk (*) padded with spaces will be returned instead.

Example conversion from matrix to string, and back again.

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

@seealso{rat, format}
@end deftypefn
disp
@c disp libinterp/corefcn/pr-output.cc
-*- texinfo -*-
@deftypefn  {} {} disp (@var{x})
@deftypefnx {} {@var{str} =} 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 libinterp/corefcn/pr-output.cc
-*- texinfo -*-
@deftypefn {} {} 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
display
@c display libinterp/corefcn/pr-output.cc
-*- texinfo -*-
@deftypefn {} {} display (@var{obj})
Display the contents of the object @var{obj} prepended by its name.

The Octave interpreter calls the @code{display} function whenever it needs
to present a class on-screen.  Typically, this would be a statement which
does not end in a semicolon to suppress output.  For example:

@example
myclass (@dots{})
@end example

Or:

@example
myobj = myclass (@dots{})
@end example

In general, user-defined classes should overload the @code{disp} method to
avoid the default output:

@example
@group
myobj = myclass (@dots{})
  @result{} myobj =

  <class myclass>
@end group
@end example

When overloading the @code{display} method instead, one has to take care
of properly displaying the object's name.  This can be done by using the
@code{inputname} function.

@seealso{disp, class, subsref, subsasgn}
@end deftypefn
format
@c format libinterp/corefcn/pr-output.cc
-*- texinfo -*-
@deftypefn  {} {} format
@deftypefnx {} {} format options
@deftypefnx {} {[@var{format}, @var{formatspacing}] =} format
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 (default).

@item long
Fixed point format with 16 significant figures.

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.  In the long format, double values are displayed with 16
significant digits and single values are displayed with 8.  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.141592653589793E+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.416e+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 is a raw format equivalent to the C++ code
@code{std::cout << @var{variable}}.  In general, the result is a presentation
with 6 significant digits where unnecessary precision (such as trailing zeros
for integers) is suppressed.  Complex numbers are 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 @asis
@item  @qcode{"+"}
@itemx @qcode{"+"} @qcode{"@var{chars}"}
@itemx @code{plus}
@itemx @code{plus @var{chars}}
Print a @samp{+} symbol for matrix elements greater than zero, a @samp{-}
symbol for elements less than zero, and a space for zero matrix elements.  This
format can be useful for examining the sparsity structure of a large matrix.
For very large matrices the function @code{spy} which plots the sparsity
pattern will be clearer.

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 format @qcode{"+" "+-."}, the matrix
@code{[1, 0, -1; -1, 0, 1]} is displayed as

@example
@group
ans =

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

@item bank
Print variable in a format appropriate for a currency (fixed format with two
digits to the right of the decimal point).  Only the real part of a variable is
displayed, as the imaginary part makes no sense for a currency.

@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

If called with one or two output arguments, and no inputs, return the current
format and format spacing.

@seealso{fixed_point_format, output_precision, split_long_rows, print_empty_dimensions, rats}
@end deftypefn
fixed_point_format
@c fixed_point_format libinterp/corefcn/pr-output.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} fixed_point_format ()
@deftypefnx {} {@var{old_val} =} fixed_point_format (@var{new_val})
@deftypefnx {} {} 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.

The scaled format prints a scaling factor on the first line of output chosen
such that the largest matrix element can be written with a single leading
digit.  For example:

@example
@group
fixed_point_format (true)
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 the first value appears to be 0 when it is actually 1.  Because
of the possibility for confusion you should be careful about enabling
@code{fixed_point_format}.

When called from inside a function with the @qcode{"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_precision}
@end deftypefn
print_empty_dimensions
@c print_empty_dimensions libinterp/corefcn/pr-output.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} print_empty_dimensions ()
@deftypefnx {} {@var{old_val} =} print_empty_dimensions (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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 libinterp/corefcn/pr-output.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} split_long_rows ()
@deftypefnx {} {@var{old_val} =} split_long_rows (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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
psi
@c psi libinterp/corefcn/psi.cc
-*- texinfo -*-
@deftypefn  {} {} psi (@var{z})
@deftypefnx {} {} psi (@var{k}, @var{z})
Compute the psi (polygamma) function.

The polygamma functions are the @var{k}th derivative of the logarithm
of the gamma function.  If unspecified, @var{k} defaults to zero.  A value
of zero computes the digamma function, a value of 1, the trigamma function,
and so on.

The digamma function is defined:

@tex
$$
\Psi (z) = {d (log (\Gamma (z))) \over dx}
$$
@end tex
@ifnottex

@example
@group
psi (z) = d (log (gamma (z))) / dx
@end group
@end example

@end ifnottex

When computing the digamma function (when @var{k} equals zero), @var{z}
can have any value real or complex value.  However, for polygamma functions
(@var{k} higher than 0), @var{z} must be real and non-negative.

@seealso{gamma, gammainc, gammaln}
@end deftypefn
quad
@c quad libinterp/corefcn/quad.cc
-*- texinfo -*-
@deftypefn  {} {@var{q} =} quad (@var{f}, @var{a}, @var{b})
@deftypefnx {} {@var{q} =} quad (@var{f}, @var{a}, @var{b}, @var{tol})
@deftypefnx {} {@var{q} =} quad (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing})
@deftypefnx {} {[@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 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.

@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 libinterp/corefcn/quadcc.cc
-*- texinfo -*-
@deftypefn  {} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b})
@deftypefnx {} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b}, @var{tol})
@deftypefnx {} {@var{q} =} quadcc (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing})
@deftypefnx {} {[@var{q}, @var{err}, @var{nr_points}] =} quadcc (@dots{})
Numerically evaluate the integral of @var{f} from @var{a} to @var{b} using
doubly-adaptive @nospell{Clenshaw-Curtis} quadrature.

@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 infinite limit by
substituting the variable of integration with @code{x = tan (pi/2*u)}.

The optional argument @var{tol} is a 1- or 2-element 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.  The default
absolute tolerance is 1e-10 (1e-5 for single), and the default relative
tolerance is 1e-6 (1e-4 for single).

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

The result of the integration is returned in @var{q}.

@var{err} is an estimate of the absolute integration error.

@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 @nospell{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.

@c FIXME: DEPRECATED: Remove in Octave version 6.
Implementation Note: For Octave versions @leq{} 4.2, @code{quadcc} accepted a
single tolerance argument which specified the relative tolerance.  For
versions 4.4 and 5, @code{quadcc} will issue a warning when called with a
single tolerance argument indicating that the meaning of this input has
changed from relative tolerance to absolute tolerance.  The warning ID for this
message is @qcode{"Octave:quadcc:RelTol-conversion"}.  The warning may be
disabled with @code{warning ("off", "Octave:quadcc:RelTol-conversion")}.

Reference: @nospell{P. Gonnet}, @cite{Increasing the Reliability of Adaptive
Quadrature Using Explicit Interpolants}, @nospell{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 libinterp/corefcn/qz.cc
-*- texinfo -*-
@deftypefn  {} {@var{lambda} =} qz (@var{A}, @var{B})
@deftypefnx {} {[@var{AA}, @var{BB}, @var{Q}, @var{Z}, @var{V}, @var{W}, @var{lambda}] =} qz (@var{A}, @var{B})
@deftypefnx {} {[@var{AA}, @var{BB}, @var{Z}] =} qz (@var{A}, @var{B}, @var{opt})
@deftypefnx {} {[@var{AA}, @var{BB}, @var{Z}, @var{lambda}] =} qz (@var{A}, @var{B}, @var{opt})
Compute the QZ@tie{}decomposition of a generalized eigenvalue problem.

The generalized eigenvalue problem is defined as

@tex
$$A x = \lambda B x$$
@end tex
@ifnottex

@math{A x = @var{lambda} B x}

@end ifnottex

There are three calling forms of the function:

@enumerate
@item @code{@var{lambda} = qz (@var{A}, @var{B})}

Compute the generalized eigenvalues
@tex
$\lambda.$
@end tex
@ifnottex
@var{lambda}.
@end ifnottex

@item @code{[@var{AA}, @var{BB}, @var{Q}, @var{Z}, @var{V}, @var{W}, @var{lambda}] = qz (@var{A}, @var{B})}

Compute QZ@tie{}decomposition, generalized eigenvectors, and generalized
eigenvalues.
@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

@var{A} * @var{V} = @var{B} * @var{V} * diag (@var{lambda})
@var{W}' * @var{A} = diag (@var{lambda}) * @var{W}' * @var{B}
@var{AA} = @var{Q} * @var{A} * @var{Z}, @var{BB} = @var{Q} * @var{B} * @var{Z}

@end group
@end example

@end ifnottex
with @var{Q} and @var{Z} orthogonal (unitary for complex case).

@item @code{[@var{AA}, @var{BB}, @var{Z} @{, @var{lambda}@}] = qz (@var{A}, @var{B}, @var{opt})}

As in form 2 above, but allows ordering of generalized eigenpairs for, e.g.,
solution of discrete time algebraic @nospell{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 @nospell{GEP} pencil.  The leading block of
the revised pencil contains all eigenvalues that satisfy:

@table @asis
@item @qcode{"N"}
unordered (default)

@item @qcode{"S"}
small: leading block has all
@tex
$|\lambda| < 1$
@end tex
@ifnottex
|@var{lambda}| < 1
@end ifnottex

@item @qcode{"B"}
big: leading block has all
@tex
$|\lambda| \geq 1$
@end tex
@ifnottex
|@var{lambda}| @geq{} 1
@end ifnottex

@item @qcode{"-"}
negative real part: leading block has all eigenvalues in the open left
half-plane

@item @qcode{"+"}
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{XREFbalance,,balance}), which may be lead to less accurate results than
@code{eig}.  The order of output arguments was selected for compatibility with
@sc{matlab}.
@seealso{eig, ordeig, balance, lu, chol, hess, qr, qzhess, schur, svd}
@end deftypefn
rand
@c rand libinterp/corefcn/rand.cc
-*- texinfo -*-
@deftypefn  {} {} rand (@var{n})
@deftypefnx {} {} rand (@var{m}, @var{n}, @dots{})
@deftypefnx {} {} rand ([@var{m} @var{n} @dots{}])
@deftypefnx {} {@var{v} =} rand ("state")
@deftypefnx {} {} rand ("state", @var{v})
@deftypefnx {} {} rand ("state", "reset")
@deftypefnx {} {@var{v} =} rand ("seed")
@deftypefnx {} {} rand ("seed", @var{v})
@deftypefnx {} {} rand ("seed", "reset")
@deftypefnx {} {} rand (@dots{}, "single")
@deftypefnx {} {} rand (@dots{}, "double")
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.  Note that this differs from @sc{matlab}, which
always initializes the state to the same state at startup.  To obtain
behavior comparable to @sc{matlab}, initialize with a deterministic state
vector in Octave's startup files (@pxref{Startup Files}).

To compute the pseudo-random sequence, @code{rand} uses the Mersenne
Twister with a period of @math{2^{19937}-1}
(See @nospell{M. Matsumoto and T. Nishimura},
@cite{Mersenne Twister: A 623-dimensionally equidistributed uniform
pseudorandom number generator},
@nospell{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 produced by the old generators.  To do this the
keyword @qcode{"seed"} is used to specify that the old generators should
be used, 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
@qcode{"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 @qcode{"reset"} keyword.

The class of the value returned can be controlled by a trailing
@qcode{"double"} or @qcode{"single"} argument.  These are the only valid
classes.
@seealso{randn, rande, randg, randp}
@end deftypefn
randn
@c randn libinterp/corefcn/rand.cc
-*- texinfo -*-
@deftypefn  {} {} randn (@var{n})
@deftypefnx {} {} randn (@var{m}, @var{n}, @dots{})
@deftypefnx {} {} randn ([@var{m} @var{n} @dots{}])
@deftypefnx {} {@var{v} =} randn ("state")
@deftypefnx {} {} randn ("state", @var{v})
@deftypefnx {} {} randn ("state", "reset")
@deftypefnx {} {@var{v} =} randn ("seed")
@deftypefnx {} {} randn ("seed", @var{v})
@deftypefnx {} {} randn ("seed", "reset")
@deftypefnx {} {} randn (@dots{}, "single")
@deftypefnx {} {} randn (@dots{}, "double")
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 @nospell{Marsaglia and Tsang}
``Ziggurat technique'' to transform from a uniform to a normal distribution.

The class of the value returned can be controlled by a trailing
@qcode{"double"} or @qcode{"single"} argument.  These are the only valid
classes.

Reference: @nospell{G. Marsaglia and W.W. Tsang},
@cite{Ziggurat Method for Generating Random Variables},
J. Statistical Software, vol 5, 2000,
@url{https://www.jstatsoft.org/v05/i08/}

@seealso{rand, rande, randg, randp}
@end deftypefn
rande
@c rande libinterp/corefcn/rand.cc
-*- texinfo -*-
@deftypefn  {} {} rande (@var{n})
@deftypefnx {} {} rande (@var{m}, @var{n}, @dots{})
@deftypefnx {} {} rande ([@var{m} @var{n} @dots{}])
@deftypefnx {} {@var{v} =} rande ("state")
@deftypefnx {} {} rande ("state", @var{v})
@deftypefnx {} {} rande ("state", "reset")
@deftypefnx {} {@var{v} =} rande ("seed")
@deftypefnx {} {} rande ("seed", @var{v})
@deftypefnx {} {} rande ("seed", "reset")
@deftypefnx {} {} rande (@dots{}, "single")
@deftypefnx {} {} rande (@dots{}, "double")
Return a matrix with exponentially distributed random elements.

The arguments are handled the same as the arguments for @code{rand}.

By default, @code{rande} uses the @nospell{Marsaglia and Tsang}
``Ziggurat technique'' to transform from a uniform to an exponential
distribution.

The class of the value returned can be controlled by a trailing
@qcode{"double"} or @qcode{"single"} argument.  These are the only valid
classes.

Reference: @nospell{G. Marsaglia and W.W. Tsang},
@cite{Ziggurat Method for Generating Random Variables},
J. Statistical Software, vol 5, 2000,
@url{https://www.jstatsoft.org/v05/i08/}

@seealso{rand, randn, randg, randp}
@end deftypefn
randg
@c randg libinterp/corefcn/rand.cc
-*- texinfo -*-
@deftypefn  {} {} randg (@var{a}, @var{n})
@deftypefnx {} {} randg (@var{a}, @var{m}, @var{n}, @dots{})
@deftypefnx {} {} randg (@var{a}, [@var{m} @var{n} @dots{}])
@deftypefnx {} {@var{v} =} randg ("state")
@deftypefnx {} {} randg ("state", @var{v})
@deftypefnx {} {} randg ("state", "reset")
@deftypefnx {} {@var{v} =} randg ("seed")
@deftypefnx {} {} randg ("seed", @var{v})
@deftypefnx {} {} randg ("seed", "reset")
@deftypefnx {} {} randg (@dots{}, "single")
@deftypefnx {} {} randg (@dots{}, "double")

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

The class of the value returned can be controlled by a trailing
@qcode{"double"} or @qcode{"single"} argument.  These are the only valid
classes.
@seealso{rand, randn, rande, randp}
@end deftypefn
randp
@c randp libinterp/corefcn/rand.cc
-*- texinfo -*-
@deftypefn  {} {} randp (@var{l}, @var{n})
@deftypefnx {} {} randp (@var{l}, @var{m}, @var{n}, @dots{})
@deftypefnx {} {} randp (@var{l}, [@var{m} @var{n} @dots{}])
@deftypefnx {} {@var{v} =} randp ("state")
@deftypefnx {} {} randp ("state", @var{v})
@deftypefnx {} {} randp ("state", "reset")
@deftypefnx {} {@var{v} =} randp ("seed")
@deftypefnx {} {} randp ("seed", @var{v})
@deftypefnx {} {} randp ("seed", "reset")
@deftypefnx {} {} randp (@dots{}, "single")
@deftypefnx {} {} randp (@dots{}, "double")
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]
@nospell{E. Stadlober, et al., WinRand source code}, available via FTP.

@item For matrix @var{l} > 10, use patchwork rejection method.
@nospell{E. Stadlober, et al., WinRand source code}, available via FTP, or
@nospell{H. Zechner}, @cite{Efficient sampling from continuous and discrete
unimodal distributions}, Doctoral Dissertation, 156pp., Technical
University @nospell{Graz}, Austria, 1994.

@item For @var{l} > 1e8, use normal approximation.
@nospell{L. Montanet}, et al., @cite{Review of Particle Properties},
Physical Review D 50 p1284, 1994.
@end table

The class of the value returned can be controlled by a trailing
@qcode{"double"} or @qcode{"single"} argument.  These are the only valid
classes.
@seealso{rand, randn, rande, randg}
@end deftypefn
randperm
@c randperm libinterp/corefcn/rand.cc
-*- texinfo -*-
@deftypefn  {} {} randperm (@var{n})
@deftypefnx {} {} 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 libinterp/corefcn/rcond.cc
-*- texinfo -*-
@deftypefn {} {@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 0.

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 libinterp/corefcn/regexp.cc
-*- texinfo -*-
@deftypefn  {} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}, @var{sp}] =} regexp (@var{str}, @var{pat})
@deftypefnx {} {[@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
@qcode{"["} and @qcode{"]"}.  If the first character is @qcode{"^"} 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.  The first form, parentheses only, also creates a token.

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

@table @code

@item \d
Match any digit

@item \D
Match any non-digit

@item \s
Match any whitespace character

@item \S
Match any non-whitespace character

@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 \B
Match within a word
@end table

Implementation Note: For compatibility with @sc{matlab}, escape sequences
in @var{pat} (e.g., @qcode{"@xbackslashchar{}n"} => newline) are expanded
even when @var{pat} has been defined with single quotes.  To disable
expansion use a second backslash before the escape sequence (e.g.,
"@xbackslashchar{}@xbackslashchar{}n") or use the @code{regexptranslate}
function.

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, i.e., what remains if you
split the string based on @var{pat}.
@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 @qcode{'start'}        @tab @var{s}  @tab
@item @tab @qcode{'end'}          @tab @var{e}  @tab
@item @tab @qcode{'tokenExtents'} @tab @var{te} @tab
@item @tab @qcode{'match'}        @tab @var{m}  @tab
@item @tab @qcode{'tokens'}       @tab @var{t}  @tab
@item @tab @qcode{'names'}        @tab @var{nm} @tab
@item @tab @qcode{'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.

@item noemptymatch
Zero-length matches are not returned.  (default)

@item emptymatch
Return zero-length matches.

@code{regexp ('a', 'b*', 'emptymatch')} returns @code{[1 2]} because there
are zero or more @qcode{'b'} characters at positions 1 and end-of-string.

@end table

Stack Limitation Note: Pattern searches are done with a recursive function
which can overflow the program stack when there are a high number of matches.
For example,

@example
@code{regexp (repmat ('a', 1, 1e5), '(a)+')}
@end example

@noindent
may lead to a segfault.  As an alternative, consider constructing pattern
searches that reduce the number of matches (e.g., by creatively using set
complement), and then further processing the return variables (now reduced in
size) with successive @code{regexp} searches.
@seealso{regexpi, strfind, regexprep}
@end deftypefn
regexpi
@c regexpi libinterp/corefcn/regexp.cc
-*- texinfo -*-
@deftypefn  {} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}, @var{sp}] =} regexpi (@var{str}, @var{pat})
@deftypefnx {} {[@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{XREFregexp,,regexp},
for details on the syntax of the search pattern.
@seealso{regexp}
@end deftypefn
regexprep
@c regexprep libinterp/corefcn/regexp.cc
-*- texinfo -*-
@deftypefn  {} {@var{outstr} =} regexprep (@var{string}, @var{pat}, @var{repstr})
@deftypefnx {} {@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{XREFregexp,,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 @qcode{"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

Implementation Note: For compatibility with @sc{matlab}, escape sequences
in @var{pat} (e.g., @qcode{"@xbackslashchar{}n"} => newline) are expanded
even when @var{pat} has been defined with single quotes.  To disable
expansion use a second backslash before the escape sequence (e.g.,
"@xbackslashchar{}@xbackslashchar{}n") or use the @code{regexptranslate}
function.
@seealso{regexp, regexpi, strrep}
@end deftypefn
schur
@c schur libinterp/corefcn/schur.cc
-*- texinfo -*-
@deftypefn  {} {@var{S} =} schur (@var{A})
@deftypefnx {} {@var{S} =} schur (@var{A}, "real")
@deftypefnx {} {@var{S} =} schur (@var{A}, "complex")
@deftypefnx {} {@var{S} =} schur (@var{A}, @var{opt})
@deftypefnx {} {[@var{U}, @var{S}] =} schur (@dots{})
@cindex Schur decomposition
Compute the Schur@tie{}decomposition of @var{A}.

The Schur@tie{}decomposition is defined as
@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
@qcode{"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 @nospell{Riccati}
equations in control (see @code{are} and @code{dare}).
@seealso{rsf2csf, ordschur, ordeig, lu, chol, hess, qr, qz, svd}
@end deftypefn
rsf2csf
@c rsf2csf libinterp/corefcn/schur.cc
-*- texinfo -*-
@deftypefn {} {[@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
@tcode{@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
__display_tokens__
@c __display_tokens__ libinterp/corefcn/settings.cc
-*- texinfo -*-
@deftypefn {} {} __display_tokens__ ()
Query or set the internal variable that determines whether Octave's
lexer displays tokens as they are read.
@seealso{__lexer_debug_flag__, __token_count__}
@end deftypefn
__token_count__
@c __token_count__ libinterp/corefcn/settings.cc
-*- texinfo -*-
@deftypefn {} {} __token_count__ ()
Return the number of language tokens processed since Octave startup.
@seealso{__lexer_debug_flag__, __display_tokens__}
@end deftypefn
__lexer_debug_flag__
@c __lexer_debug_flag__ libinterp/corefcn/settings.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} __lexer_debug_flag__ ()
@deftypefnx {} {@var{old_val} =} __lexer_debug_flag__ (@var{new_val})
Query or set the internal flag that determines whether Octave's lexer prints
debug information as it processes an expression.
@seealso{__display_tokens__, __token_count__, __parse_debug_flag__}
@end deftypefn
SIG
@c SIG libinterp/corefcn/sighandlers.cc
-*- texinfo -*-
@deftypefn {} {} SIG ()
Return a structure containing Unix signal names and their defined values.
@end deftypefn
debug_on_interrupt
@c debug_on_interrupt libinterp/corefcn/sighandlers.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} debug_on_interrupt ()
@deftypefnx {} {@var{old_val} =} debug_on_interrupt (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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{debug_on_error, debug_on_warning}
@end deftypefn
sighup_dumps_octave_core
@c sighup_dumps_octave_core libinterp/corefcn/sighandlers.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} sighup_dumps_octave_core ()
@deftypefnx {} {@var{old_val} =} sighup_dumps_octave_core (@var{new_val})
@deftypefnx {} {} 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 @file{octave-workspace} if it
receives a hangup signal.

When called from inside a function with the @qcode{"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
sigquit_dumps_octave_core
@c sigquit_dumps_octave_core libinterp/corefcn/sighandlers.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} sigquit_dumps_octave_core ()
@deftypefnx {} {@var{old_val} =} sigquit_dumps_octave_core (@var{new_val})
@deftypefnx {} {} sigquit_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 @file{octave-workspace} if it
receives a quit signal.

When called from inside a function with the @qcode{"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 libinterp/corefcn/sighandlers.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} sigterm_dumps_octave_core ()
@deftypefnx {} {@var{old_val} =} sigterm_dumps_octave_core (@var{new_val})
@deftypefnx {} {} 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 @file{octave-workspace} if it
receives a terminate signal.

When called from inside a function with the @qcode{"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 libinterp/corefcn/sparse.cc
-*- texinfo -*-
@deftypefn {} {} issparse (@var{x})
Return true if @var{x} is a sparse matrix.
@seealso{ismatrix}
@end deftypefn
sparse
@c sparse libinterp/corefcn/sparse.cc
-*- texinfo -*-
@deftypefn  {} {@var{s} =} sparse (@var{a})
@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n})
@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv})
@deftypefnx {} {@var{s} =} sparse (@var{m}, @var{n})
@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, "unique")
@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})
Create a sparse matrix from a 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}, and a 1-by-@code{nnz}
vector of real or complex values @var{sv}, construct the sparse matrix
@code{S(@var{i}(@var{k}),@var{j}(@var{k})) = @var{sv}(@var{k})} with overall
dimensions @var{m} and @var{n}.  If any of @var{sv}, @var{i} or @var{j} are
scalars, they are expanded to have a common size.

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 value in @var{s} will be the sum of the
values at the repeated location.  See @code{accumarray} for an example of
how to produce different behavior, such as taking the minimum instead.

If the option @qcode{"unique"} is given, and more than one value is
specified at the same @var{i}, @var{j} indices, then the last specified
value will be used.

@code{sparse (@var{m}, @var{n})} will create an empty @var{m}x@var{n} sparse
matrix and is equivalent to @code{sparse ([], [], [], @var{m}, @var{n})}

The argument @var{nzmax} is ignored but accepted for compatibility with
@sc{matlab}.

Example 1 (sum at repeated indices):

@example
@group
@var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5];
sparse (@var{i}, @var{j}, @var{sv}, 3, 4)
@result{}
   Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%])

     (1, 1) ->  7
     (2, 2) ->  5
@end group
@end example

Example 2 ("unique" option):

@example
@group
@var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5];
sparse (@var{i}, @var{j}, @var{sv}, 3, 4, "unique")
@result{}
   Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%])

     (1, 1) ->  4
     (2, 2) ->  5
@end group
@end example
@seealso{full, accumarray, spalloc, spdiags, speye, spones, sprand, sprandn, sprandsym, spconvert, spfun}
@end deftypefn
spalloc
@c spalloc libinterp/corefcn/sparse.cc
-*- texinfo -*-
@deftypefn {} {@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 a matrix incrementally by a sequence of indexed
assignments.  Subsequent indexed assignments after @code{spalloc} 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 @code{nnz (@var{S})}.

@item after the assignment, @code{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 a
contiguous block of columns.

The amount of pre-allocated memory for a given matrix may be queried using
the function @code{nzmax}.

Programming Note: Octave always reserves memory for at least one value,
even if @var{nz} is 0.
@seealso{nzmax, sparse}
@end deftypefn
spparms
@c spparms libinterp/corefcn/spparms.cc
-*- texinfo -*-
@deftypefn  {} { } spparms ()
@deftypefnx {} {@var{vals} =} spparms ()
@deftypefnx {} {[@var{keys}, @var{vals}] =} spparms ()
@deftypefnx {} {@var{val} =} spparms (@var{key})
@deftypefnx {} { } spparms (@var{vals})
@deftypefnx {} { } spparms ("default")
@deftypefnx {} { } spparms ("tight")
@deftypefnx {} { } 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 nonzero 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
@qcode{"default"}.  The special keyword @qcode{"tight"} can be used to
set the mmd solvers to attempt a sparser solution at the potential cost of
longer running time.
@seealso{chol, colamd, lu, qr, symamd}
@end deftypefn
sqrtm
@c sqrtm libinterp/corefcn/sqrtm.cc
-*- texinfo -*-
@deftypefn  {} {@var{s} =} sqrtm (@var{A})
@deftypefnx {} {[@var{s}, @var{error_estimate}] =} sqrtm (@var{A})
Compute the matrix square root of the square matrix @var{A}.

Ref: @nospell{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 libinterp/corefcn/strfind.cc
-*- texinfo -*-
@deftypefn  {} {@var{idx} =} strfind (@var{str}, @var{pattern})
@deftypefnx {} {@var{idx} =} strfind (@var{cellstr}, @var{pattern})
@deftypefnx {} {@var{idx} =} strfind (@dots{}, "overlaps", @var{val})
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}, or if @var{pattern} itself is empty, then @var{idx} is the empty
array @code{[]}.

The optional argument @qcode{"overlaps"} determines whether the pattern
can match at every position in @var{str} (true), or only for unique
occurrences of the complete pattern (false).  The default is true.

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", "aba", "overlaps", false)
     @result{} [1, 5]

strfind (@{"abababa", "bebebe", "ab"@}, "aba")
     @result{}
        @{
          [1,1] =

             1   3   5

          [1,2] = [](1x0)
          [1,3] = [](1x0)
        @}
@end group
@end example
@seealso{regexp, regexpi, find}
@end deftypefn
strrep
@c strrep libinterp/corefcn/strfind.cc
-*- texinfo -*-
@deftypefn  {} {@var{newstr} =} strrep (@var{str}, @var{ptn}, @var{rep})
@deftypefnx {} {@var{newstr} =} strrep (@var{cellstr}, @var{ptn}, @var{rep})
@deftypefnx {} {@var{newstr} =} strrep (@dots{}, "overlaps", @var{val})
Replace all occurrences of the pattern @var{ptn} in the string @var{str}
with the string @var{rep} and return the result.

The optional argument @qcode{"overlaps"} determines whether the pattern
can match at every position in @var{str} (true), or only for unique
occurrences of the complete pattern (false).  The default is true.

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

Example:

@example
@group
strrep ("This is a test string", "is", "&%$")
    @result{}  "Th&%$ &%$ a test string"
@end group
@end example

@seealso{regexprep, strfind}
@end deftypefn
char
@c char libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn  {} {} char (@var{x})
@deftypefnx {} {} char (@var{x}, @dots{})
@deftypefnx {} {} char (@var{s1}, @var{s2}, @dots{})
@deftypefnx {} {} 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 libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn  {} {} strvcat (@var{x})
@deftypefnx {} {} strvcat (@var{x}, @dots{})
@deftypefnx {} {} strvcat (@var{s1}, @var{s2}, @dots{})
@deftypefnx {} {} 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 libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn {} {} ischar (@var{x})
Return true if @var{x} is a character array.
@seealso{isfloat, isinteger, islogical, isnumeric, isstring, iscellstr, isa}
@end deftypefn
strcmp
@c strcmp libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn {} {} 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
str2double
@c str2double libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn {} {} 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 @qcode{'i'} or @qcode{'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 @qcode{'d'} indicates zero or
more digits.  The special input values @code{Inf}, @code{NaN}, and @code{NA}
are also accepted.

@var{s} may be a character string, character matrix, or cell array.  For
character arrays the conversion is repeated for every row, and a double or
complex array is returned.  Empty rows in @var{s} are deleted and not
returned in the numeric array.  For cell arrays each character string
element is processed and a double or complex array of the same dimensions as
@var{s} is returned.

For unconvertible scalar or character string input @code{str2double} returns
a NaN@.  Similarly, for character array input @code{str2double} returns a
NaN for any row of @var{s} that could not be converted.  For a cell array,
@code{str2double} returns a NaN for any element of @var{s} for which
conversion fails.  Note that numeric elements in a mixed string/numeric
cell array are not strings and the conversion will fail for these elements
and return NaN.

@code{str2double} can replace @code{str2num}, and it avoids the security
risk of using @code{eval} on unknown data.
@seealso{str2num}
@end deftypefn
__native2unicode__
@c __native2unicode__ libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn {} {@var{utf8_str} =} __native2unicode__ (@var{native_bytes}, @var{codepage})
Convert byte stream @var{native_bytes} to UTF-8 using @var{codepage}.

@seealso{native2unicode, __unicode2native__}
@end deftypefn
__unicode2native__
@c __unicode2native__ libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn {} {@var{native_bytes} =} __unicode2native__ (@var{utf8_str}, @var{codepage})
Convert UTF-8 string @var{utf8_str} to byte stream @var{native_bytes} using
@var{codepage}.

@seealso{unicode2native, __native2unicode__}
@end deftypefn
unicode_idx
@c unicode_idx libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn {} {@var{idx} =} unicode_idx (@var{str})
Return an array with the indices for each UTF-8 encoded character in @var{str}.

@example
@group
unicode_idx ("aäbc")
     @result{} [1, 2, 2, 3, 4]
@end group
@end example

@end deftypefn
list_in_columns
@c list_in_columns libinterp/corefcn/strfns.cc
-*- texinfo -*-
@deftypefn {} {} list_in_columns (@var{arg}, @var{width}, @var{prefix})
Return a string containing the elements of @var{arg} listed in columns with
an overall maximum width of @var{width} and optional prefix @var{prefix}.

The argument @var{arg} must be a cell array of character strings or a
character array.

If @var{width} is not specified or is an empty matrix, or less than or equal
to zero, 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{} 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
sub2ind
@c sub2ind libinterp/corefcn/sub2ind.cc
-*- texinfo -*-
@deftypefn  {} {@var{ind} =} sub2ind (@var{dims}, @var{i}, @var{j})
@deftypefnx {} {@var{ind} =} sub2ind (@var{dims}, @var{s1}, @var{s2}, @dots{}, @var{sN})
Convert subscripts to linear indices.

The input @var{dims} is a dimension vector where each element is the size of
the array in the respective dimension (@pxref{XREFsize,,size}).  The remaining
inputs are scalars or vectors of subscripts to be converted.

The output vector @var{ind} contains the converted linear indices.

Background: Array elements can be specified either by a linear index which
starts at 1 and runs through the number of elements in the array, or they may
be specified with subscripts for the row, column, page, etc.  The functions
@code{ind2sub} and @code{sub2ind} interconvert between the two forms.

The linear index traverses dimension 1 (rows), then dimension 2 (columns), then
dimension 3 (pages), etc.@: until it has numbered all of the elements.
Consider the following 3-by-3 matrices:

@example
@group
[(1,1), (1,2), (1,3)]     [1, 4, 7]
[(2,1), (2,2), (2,3)] ==> [2, 5, 8]
[(3,1), (3,2), (3,3)]     [3, 6, 9]
@end group
@end example

@noindent
The left matrix contains the subscript tuples for each matrix element.  The
right matrix shows the linear indices for the same matrix.

The following example shows how to convert the two-dimensional indices
@code{(2,1)} and @code{(2,3)} of a 3-by-3 matrix to linear indices with a
single call to @code{sub2ind}.

@example
@group
s1 = [2, 2];
s2 = [1, 3];
ind = sub2ind ([3, 3], s1, s2)
    @result{} ind =  2   8
@end group
@end example
@seealso{ind2sub, size}
@end deftypefn
ind2sub
@c ind2sub libinterp/corefcn/sub2ind.cc
-*- texinfo -*-
@deftypefn {} {[@var{s1}, @var{s2}, @dots{}, @var{sN}] =} ind2sub (@var{dims}, @var{ind})
Convert linear indices to subscripts.

The input @var{dims} is a dimension vector where each element is the size of
the array in the respective dimension (@pxref{XREFsize,,size}).  The second
input @var{ind} contains linear indies to be converted.

The outputs @var{s1}, @dots{}, @var{sN} contain the converted subscripts.

Background: Array elements can be specified either by a linear index which
starts at 1 and runs through the number of elements in the array, or they may
be specified with subscripts for the row, column, page, etc.  The functions
@code{ind2sub} and @code{sub2ind} interconvert between the two forms.

The linear index traverses dimension 1 (rows), then dimension 2 (columns), then
dimension 3 (pages), etc.@: until it has numbered all of the elements.
Consider the following 3-by-3 matrices:

@example
@group
[1, 4, 7]     [(1,1), (1,2), (1,3)]
[2, 5, 8] ==> [(2,1), (2,2), (2,3)]
[3, 6, 9]     [(3,1), (3,2), (3,3)]
@end group
@end example

@noindent
The left matrix contains the linear indices for each matrix element.  The right
matrix shows the subscript tuples for the same matrix.

The following example shows how to convert the two-dimensional indices
@code{(2,1)} and @code{(2,3)} of a 3-by-3 matrix to linear indices with a
single call to @code{sub2ind}.

The following example shows how to convert the linear indices @code{2} and
@code{8} in a 3-by-3 matrix into subscripts.

@example
@group
ind = [2, 8];
[r, c] = ind2sub ([3, 3], ind)
    @result{} r =  2   2
    @result{} c =  1   3
@end group
@end example

If the number of output subscripts exceeds the number of dimensions, the
exceeded dimensions are set to @code{1}.  On the other hand, if fewer
subscripts than dimensions are provided, the exceeding dimensions are merged
into the final requested dimension.  For clarity, consider the following
examples:

@example
@group
ind  = [2, 8];
dims = [3, 3];
## same as dims = [3, 3, 1]
[r, c, s] = ind2sub (dims, ind)
    @result{} r =  2   2
    @result{} c =  1   3
    @result{} s =  1   1
## same as dims = [9]
r = ind2sub (dims, ind)
    @result{} r =  2   8
@end group
@end example
@seealso{ind2sub, size}
@end deftypefn
svd
@c svd libinterp/corefcn/svd.cc
-*- texinfo -*-
@deftypefn  {} {@var{s} =} svd (@var{A})
@deftypefnx {} {[@var{U}, @var{S}, @var{V}] =} svd (@var{A})
@deftypefnx {} {[@var{U}, @var{S}, @var{V}] =} svd (@var{A}, "econ")
@deftypefnx {} {[@var{U}, @var{S}, @var{V}] =} svd (@var{A}, 0)
@cindex singular value decomposition
Compute the singular value decomposition of @var{A}.

The singular value decomposition is defined by the relation

@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

When given a second argument that is not 0, @code{svd} returns an economy-sized
decomposition, eliminating the unnecessary rows or columns of @var{U} or
@var{V}.

If the second argument is exactly 0, then the choice of decomposition is based
on the matrix @var{A}.  If @var{A} has more rows than columns then an
economy-sized decomposition is returned, otherwise a regular decomposition
is calculated.

Algorithm Notes: When calculating the full decomposition (left and right
singular matrices in addition to singular values) there is a choice of two
routines in @sc{lapack}.  The default routine used by Octave is @code{gesvd}.
The alternative is @code{gesdd} which is 5X faster, but may use more memory
and may be inaccurate for some input matrices.  See the documentation for
@code{svd_driver} for more information on choosing a driver.
@seealso{svd_driver, svds, eig, lu, chol, hess, qr, qz}
@end deftypefn
svd_driver
@c svd_driver libinterp/corefcn/svd.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} svd_driver ()
@deftypefnx {} {@var{old_val} =} svd_driver (@var{new_val})
@deftypefnx {} {} svd_driver (@var{new_val}, "local")
Query or set the underlying @sc{lapack} driver used by @code{svd}.

Currently recognized values are @qcode{"gesdd"} and @qcode{"gesvd"}.
The default is @qcode{"gesvd"}.

When called from inside a function with the @qcode{"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.

Algorithm Notes: The @sc{lapack} library provides two routines for calculating
the full singular value decomposition (left and right singular matrices as
well as singular values).  When calculating just the singular values the
following discussion is not relevant.

The newer @code{gesdd} routine is based on a Divide-and-Conquer algorithm that
is 5X faster than the alternative @code{gesvd}, which is based on QR
factorization.  However, the new algorithm can use significantly more memory.
For an @nospell{MxN} input matrix the memory usage is of order O(min(M,N) ^ 2),
whereas the alternative is of order O(max(M,N)).

Beyond speed and memory issues, there have been instances where some input
matrices were not accurately decomposed by @code{gesdd}.  See currently active
bug @url{https://savannah.gnu.org/bugs/?55564}.  Until these accuracy issues
are resolved in a new version of the @sc{lapack} library, the default driver
in Octave has been set to @qcode{"gesvd"}.

@seealso{svd}
@end deftypefn
sylvester
@c sylvester libinterp/corefcn/sylvester.cc
-*- texinfo -*-
@deftypefn {} {@var{X} =} sylvester (@var{A}, @var{B}, @var{C})
Solve the Sylvester equation.

The Sylvester equation is defined as:
@tex
$$
 A X + X B = C
$$
@end tex
@ifnottex

@example
A X + X B = C
@end example

@end ifnottex
The solution is computed using standard @sc{lapack} subroutines.

For example:

@example
@group
sylvester ([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
ignore_function_time_stamp
@c ignore_function_time_stamp libinterp/corefcn/symtab.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} ignore_function_time_stamp ()
@deftypefnx {} {@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 @qcode{"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 @qcode{"all"}, Octave will not recompile any function files
unless their definitions are removed with @code{clear}.

If set to @qcode{"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__ libinterp/corefcn/symtab.cc
-*- texinfo -*-
@deftypefn {} {[@var{scope}, @var{context}] =} __current_scope__ ()
Return the current scope and context as integers.
@seealso{__dump_symtab_info__}
@end deftypefn
__dump_symtab_info__
@c __dump_symtab_info__ libinterp/corefcn/symtab.cc
-*- texinfo -*-
@deftypefn  {} {} __dump_symtab_info__ ()
@deftypefnx {} {} __dump_symtab_info__ (@var{function})
Undocumented internal function.
@seealso{__current_scope__}
@end deftypefn
__get_cmdline_fcn_txt__
@c __get_cmdline_fcn_txt__ libinterp/corefcn/symtab.cc
-*- texinfo -*-
@deftypefn {} {} __get_cmdline_fcn_txt__ (@var{name})
Undocumented internal function.
@end deftypefn
dup2
@c dup2 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {[@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.
@seealso{fopen, fclose, fcntl}
@end deftypefn
exec
@c exec libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {[@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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {[@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 or cell 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)
    pause (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 @nospell{"reap"}
the child process.  If you don't use @code{waitpid} to check the child's
exit status, it will linger until Octave exits.
@seealso{popen, waitpid}
@end deftypefn
fcntl
@c fcntl libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {[@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.
@seealso{fopen, dup2}
@end deftypefn
fork
@c fork libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {[@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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {pgid =} getpgrp ()
Return the process group id of the current process.
@end deftypefn
getpid
@c getpid libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {pid =} getpid ()
Return the process id of the current process.
@seealso{getppid}
@end deftypefn
getppid
@c getppid libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {pid =} getppid ()
Return the process id of the parent process.
@seealso{getpid}
@end deftypefn
getegid
@c getegid libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {egid =} getegid ()
Return the effective group id of the current process.
@seealso{getgid}
@end deftypefn
getgid
@c getgid libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {gid =} getgid ()
Return the real group id of the current process.
@seealso{getegid}
@end deftypefn
geteuid
@c geteuid libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {euid =} geteuid ()
Return the effective user id of the current process.
@seealso{getuid}
@end deftypefn
getuid
@c getuid libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {uid =} getuid ()
Return the real user id of the current process.
@seealso{geteuid}
@end deftypefn
kill
@c kill libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {[@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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn  {} {@var{info} =} lstat (@var{symlink})
@deftypefnx {} {[@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, symlink}
@end deftypefn
mkfifo
@c mkfifo libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn  {} {@var{err} =} mkfifo (@var{name}, @var{mode})
@deftypefnx {} {[@var{err}, @var{msg}] =} mkfifo (@var{name}, @var{mode})
Create a FIFO special file named @var{name} with file mode @var{mode}.

@var{mode} is interpreted as an octal number and is subject to umask
processing.  The final calculated mode is @code{@var{mode} - @var{umask}}.

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{pipe, umask}
@end deftypefn
pipe
@c pipe libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {[@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.
@seealso{mkfifo}
@end deftypefn
stat
@c stat libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn  {} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{file})
@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{fid})
@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{file})
@deftypefnx {} {[@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{info} 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
[info, err, msg] = stat ("/vmlinuz")
  @result{} info =
     @{
       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
@seealso{lstat, ls, dir, isfile, isfolder}
@end deftypefn
S_ISREG
@c S_ISREG libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} gethostname ()
Return the hostname of the system where Octave is running.
@end deftypefn
uname
@c uname libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {[@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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {[@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.
@seealso{delete, rmdir}
@end deftypefn
waitpid
@c waitpid libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {[@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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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., @nospell{AIX, SunOS}).
@seealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WIFSTOPPED
@c WIFSTOPPED libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {[@var{cname}, @var{status}, @var{msg}] =} canonicalize_file_name (@var{fname})
Return the canonical name of file @var{fname}.

If the file does not exist the empty string ("") is returned.
@seealso{make_absolute_filename, is_absolute_filename, is_rooted_relative_filename}
@end deftypefn
F_DUPFD
@c F_DUPFD libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} O_APPEND ()
Return the numerical value of the @code{O_APPEND} macro.

@code{O_APPEND} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} O_ASYNC ()
Return the numerical value of the @code{O_ASYNC} macro.

@code{O_ASYNC} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} O_CREAT ()
Return the numerical value of the @code{O_CREAT}.

@code{O_CREAT} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} O_EXCL ()
Return the numerical value of the @code{O_EXCL}.

@code{O_EXCL} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} O_NONBLOCK ()
Return the numerical value of the @code{O_NONBLOCK}.

@code{O_NONBLOCK} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} O_RDONLY ()
Return the numerical value of the @code{O_RDONLY}.

@code{O_RDONLY} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} O_RDWR ()
Return the numerical value of the @code{O_RDWR}.

@code{O_RDWR} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} O_SYNC ()
Return the numerical value of the @code{O_SYNC}.

@code{O_SYNC} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} O_TRUNC ()
Return the numerical value of the @code{O_TRUNC}.

@code{O_TRUNC} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} O_WRONLY ()
Return the numerical value of the @code{O_WRONLY}.

@code{O_WRONLY} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} WNOHANG ()
Return the numerical value of the @code{WNOHANG} macro.

@code{WNOHANG} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} WUNTRACED ()
Return the numerical value of the @code{WUNTRACED} macro.

@code{WUNTRACED} is 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 libinterp/corefcn/syscalls.cc
-*- texinfo -*-
@deftypefn {} {} WCONTINUE ()
Return the numerical value of the @code{WCONTINUE} macro.

@code{WCONTINUE} is 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
__open_with_system_app__
@c __open_with_system_app__ libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn {} {} __open_with_system_app__ (@var{file})
Undocumented internal function.
@end deftypefn
clc
@c clc libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn  {} {} clc ()
@deftypefnx {} {} home ()
Clear the terminal screen and move the cursor to the upper left corner.
@end deftypefn
getenv
@c getenv libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn {} {} 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.
@seealso{setenv, unsetenv}
@end deftypefn
setenv
@c setenv libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn  {} {} setenv (@var{var}, @var{value})
@deftypefnx {} {} setenv (@var{var})
@deftypefnx {} {} putenv (@dots{})
Set the value of the environment variable @var{var} to @var{value}.

If no @var{value} is specified then the variable will be assigned the null
string.
@seealso{unsetenv, getenv}
@end deftypefn
unsetenv
@c unsetenv libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn {} {@var{status} =} unsetenv (@var{var})
Delete the environment variable @var{var}.

Return 0 if the variable was deleted, or did not exist, and -1 if an error
occurred.
@seealso{setenv, getenv}
@end deftypefn
winqueryreg
@c winqueryreg libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn  {} {@var{value} =} winqueryreg (@var{rootkey}, @var{subkey}, @var{valuename})
@deftypefnx {} {@var{value} =} winqueryreg (@var{rootkey}, @var{subkey})
@deftypefnx {} {@var{names} =} winqueryreg (@code{"name"}, @var{rootkey}, @var{subkey})

Query names or value from the Windows registry.

On Windows, return the value of the registry key @var{subkey} from the root key
@var{rootkey}.  You can specify the name of the queried registry value with the
optional argument @var{valuename}.  Otherwise, if called with only two
arguments or @var{valuename} is empty, then the default value of @var{subkey}
is returned.  If the registry value is of type @nospell{@qcode{"REG_DWORD"}}
then @var{value} is of class int32.  If the value is of the type
@nospell{@qcode{"REG_SZ"}} or @nospell{@qcode{"REG_EXPAND_SZ"}} a string is
returned.

If the first argument is @qcode{"name"}, a cell array of strings with the names
of the values at that key is returned.

The variable @var{rootkey} must be a string with a valid root key identifier:

@table @asis
@item  @nospell{HKCR}
@itemx @nospell{HKEY_CLASSES_ROOT}

@item @nospell{HKEY_CURRENT_CONFIG}

@item  @nospell{HKCU}
@itemx @nospell{HKEY_CURRENT_USER}

@item  @nospell{HKLM}
@itemx @nospell{HKEY_LOCAL_MACHINE}


@item  @nospell{HKU}
@itemx @nospell{HKEY_USERS}


@item @nospell{HKEY_PERFORMANCE_DATA}

@end table

Examples:

Get a list of value names at the key @nospell{@qcode{'HKCU\Environment'}}:

@example
@group
@var{valuenames} = winqueryreg ("name", "HKEY_CURRENT_USER", ...
                          "Environment");
@end group
@end example

For each @var{valuenames}, display the value:

@example
@group
for @var{k} = 1:numel (@var{valuenames})
  @var{val} = winqueryreg ("HKEY_CURRENT_USER", "Environment", ...
                     @var{valuenames}@{@var{k}@});
  @var{str} = sprintf ("%s = %s", @var{valuenames}@{@var{k}@}, num2str (@var{val}));
  disp (@var{str});
endfor
@end group
@end example

On non-Windows platforms this function fails with an error.
@end deftypefn
kbhit
@c kbhit libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn  {} {} kbhit ()
@deftypefnx {} {} kbhit (1)
Read a single keystroke from the keyboard.

If called with an 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
is identical to the above example, but doesn't wait for a keypress,
returning the empty string if no key is available.
@seealso{input, pause}
@end deftypefn
pause
@c pause libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn  {} {} pause ()
@deftypefnx {} {} pause (@var{n})
@deftypefnx {} {@var{old_state} =} pause ("on")
@deftypefnx {} {@var{old_state} =} pause ("off")
@deftypefnx {} {@var{old_state} =} pause ("query")
Suspend the execution of the program or change the state of the pause function.

If invoked without an input arguments then the program is suspended until a
character is typed.  If argument @var{n} is a positive real value, it indicates
the number of seconds the program shall be suspended, for example:

@example
@group
tic; pause (0.05); toc
     @print{} Elapsed time is 0.05039 seconds.
@end group
@end example

The following example prints a message and then waits 5 seconds before
clearing the screen.

@example
@group
disp ("wait please...");
pause (5);
clc;
@end group
@end example

If invoked with a string argument @qcode{"on"}, @qcode{"off"}, or
@qcode{"query"}, the state of the pause function is changed or queried.  When
the state is @qcode{"off"}, the pause function returns immediately.  The
optional return value contains the previous state of the pause function.  In
the following example pause is disabled locally:

@example
@group
old_state = pause ("off");
tic; pause (0.05); toc
     @print{} Elapsed time is 3.00407e-05 seconds.
pause (old_state);
@end group
@end example

While the program is suspended Octave still handles figures painting and
graphics callbacks execution.

@seealso{kbhit}
@end deftypefn
isieee
@c isieee libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn {} {} native_float_format ()
Return the native floating point format as a string.
@end deftypefn
tilde_expand
@c tilde_expand libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn  {} {} tilde_expand (@var{string})
@deftypefnx {} {} tilde_expand (@var{cellstr})
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.

If the input is a cell array of strings @var{cellstr} then tilde expansion
is performed on each string element.

Examples:

@example
@group
tilde_expand ("~joeuser/bin")
     @result{} "/home/joeuser/bin"
tilde_expand ("~/bin")
     @result{} "/home/jwe/bin"
@end group
@end example
@end deftypefn
get_home_directory
@c get_home_directory libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn {} {@var{homedir} =} get_home_directory ()
Return the current home directory.

On most systems, this is equivalent to @code{getenv ("HOME")}.  On Windows
systems, if the environment variable @env{HOME} is not set then it is
equivalent to
@code{fullfile (getenv ("HOMEDRIVE"), getenv ("HOMEPATH"))}
@seealso{getenv}
@end deftypefn
__blas_version__
@c __blas_version__ libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn {} {} __blas_version__ ()
Undocumented internal function.
@end deftypefn
__lapack_version__
@c __lapack_version__ libinterp/corefcn/sysdep.cc
-*- texinfo -*-
@deftypefn {} {} __lapack_version__ ()
Undocumented internal function.
@end deftypefn
time
@c time libinterp/corefcn/time.cc
-*- texinfo -*-
@deftypefn {} {@var{seconds} =} time ()
Return the current time as the number of seconds since the epoch.

The epoch is referenced to 00:00:00 UTC (Coordinated Universal Time) 1 Jan
1970.  For example, on Monday February 17, 1997 at 07:15:06 UTC, 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 libinterp/corefcn/time.cc
-*- texinfo -*-
@deftypefn {} {@var{tm_struct} =} gmtime (@var{t})
Given a value returned from @code{time}, or any non-negative integer,
return a time structure corresponding to UTC (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
           gmtoff = 0
           zone = GMT
        @}
@end group
@end example
@seealso{strftime, strptime, localtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
localtime
@c localtime libinterp/corefcn/time.cc
-*- texinfo -*-
@deftypefn {} {@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
           gmtoff = -21600
           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 libinterp/corefcn/time.cc
-*- texinfo -*-
@deftypefn {} {@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 libinterp/corefcn/time.cc
-*- texinfo -*-
@deftypefn {} {} 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
Offset from UTC (±@nospell{hhmm}), or nothing if no time zone is
determinable.

@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 libinterp/corefcn/time.cc
-*- texinfo -*-
@deftypefn {} {[@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
warranty
@c warranty libinterp/corefcn/toplev.cc
-*- texinfo -*-
@deftypefn {} {} warranty ()
Describe the conditions for copying and distributing Octave.
@end deftypefn
system
@c system libinterp/corefcn/toplev.cc
-*- texinfo -*-
@deftypefn  {} {} system ("@var{string}")
@deftypefnx {} {} system ("@var{string}", @var{return_output})
@deftypefnx {} {} system ("@var{string}", @var{return_output}, @var{type})
@deftypefnx {} {[@var{status}, @var{output}] =} system (@dots{})
Execute a shell command specified by @var{string}.

If the optional argument @var{type} is @qcode{"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 @qcode{"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
[~, text] = system ("cmd");
more on;
disp (text);
@end group
@end example

@noindent
or

@example
@group
more on;
printf ("%s\n", nthargout (2, "system", "cmd"));
@end group
@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 @var{output} to the string @samp{foo}, and the
variable @var{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.

The shell used for executing commands varies with operating system and is
typically @file{/bin/sh} for UNIX systems and @nospell{@file{cmd.exe}} for
Windows
systems.
@seealso{unix, dos}
@end deftypefn
__octave_config_info__
@c __octave_config_info__ libinterp/corefcn/toplev.cc
-*- texinfo -*-
@deftypefn  {} {} __octave_config_info__ ()
@deftypefnx {} {} __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.

@seealso{computer}
@end deftypefn
tril
@c tril libinterp/corefcn/tril.cc
-*- texinfo -*-
@deftypefn  {} {@var{A_LO} =} tril (@var{A})
@deftypefnx {} {@var{A_LO} =} tril (@var{A}, @var{k})
@deftypefnx {} {@var{A_LO} =} tril (@var{A}, @var{k}, @var{pack})
Return a new matrix formed by extracting the lower triangular part of the
matrix @var{A}, and setting all other elements to zero.

The optional second argument specifies how many diagonals above or below the
main diagonal should also be set to zero.  The default value of @var{k} is
zero which includes the main diagonal as part of the result.  If the value of
@var{k} is a nonzero integer then the selection of elements starts at an offset
of @var{k} diagonals above the main diagonal for positive @var{k} or below the
main diagonal for negative @var{k}.  The absolute value of @var{k} may not be
greater than the number of subdiagonals or superdiagonals.

Example 1 : exclude main diagonal

@example
@group
tril (ones (3), -1)
     @result{}  0  0  0
         1  0  0
         1  1  0
@end group
@end example

@noindent

Example 2 : include first superdiagonal

@example
@group
tril (ones (3), 1)
     @result{}  1  1  0
         1  1  1
         1  1  1
@end group
@end example

If the optional third argument @qcode{"pack"} is given then the extracted
elements are not inserted into a matrix, but instead stacked column-wise one
above another, and returned as a column vector.
@seealso{triu, istril, diag}
@end deftypefn
triu
@c triu libinterp/corefcn/tril.cc
-*- texinfo -*-
@deftypefn  {} {@var{A_UP} =} triu (@var{A})
@deftypefnx {} {@var{A_UP} =} triu (@var{A}, @var{k})
@deftypefnx {} {@var{A_UP} =} triu (@var{A}, @var{k}, @var{pack})
Return a new matrix formed by extracting the upper triangular part of the
matrix @var{A}, and setting all other elements to zero.

The optional second argument specifies how many diagonals above or below the
main diagonal should also be set to zero.  The default value of @var{k} is
zero which includes the main diagonal as part of the result.  If the value of
@var{k} is a nonzero integer then the selection of elements starts at an offset
of @var{k} diagonals above the main diagonal for positive @var{k} or below the
main diagonal for negative @var{k}.  The absolute value of @var{k} may not be
greater than the number of subdiagonals or superdiagonals.

Example 1 : exclude main diagonal

@example
@group
triu (ones (3), 1)
     @result{}  0  1  1
         0  0  1
         0  0  0
@end group
@end example

@noindent

Example 2 : include first subdiagonal

@example
@group
triu (ones (3), -1)
     @result{}  1  1  1
         1  1  1
         0  1  1
@end group
@end example

If the optional third argument @qcode{"pack"} is given then the extracted
elements are not inserted into a matrix, but instead stacked column-wise one
above another, and returned as a column vector.
@seealso{tril, istriu, diag}
@end deftypefn
tsearch
@c tsearch libinterp/corefcn/tsearch.cc
-*- texinfo -*-
@deftypefn {} {@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 libinterp/corefcn/typecast.cc
-*- texinfo -*-
@deftypefn {} {@var{y} =} 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 only used with @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 will be 4 bytes and 8 bytes wide, respectively.
@qcode{"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{} [   1,   0, 255, 255]
@end group
@end example
@seealso{cast, bitpack, bitunpack, swapbytes}
@end deftypefn
bitpack
@c bitpack libinterp/corefcn/typecast.cc
-*- texinfo -*-
@deftypefn {} {@var{y} =} bitpack (@var{x}, @var{class})
Return a new array @var{y} resulting from interpreting the logical 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
"double"
"single"
"double complex"
"single complex"
"char"
"int8"
"int16"
"int32"
"int64"
"uint8"
"uint16"
"uint32"
"uint64"
@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 libinterp/corefcn/typecast.cc
-*- texinfo -*-
@deftypefn {} {@var{y} =} bitunpack (@var{x})
Return a logical 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
"double"
"single"
"char"
"int8"
"int16"
"int32"
"int64"
"uint8"
"uint16"
"uint32"
"uint64"
@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 libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn  {} {} urlwrite (@var{url}, @var{localfile})
@deftypefnx {} {@var{f} =} urlwrite (@var{url}, @var{localfile})
@deftypefnx {} {[@var{f}, @var{success}] =} urlwrite (@var{url}, @var{localfile})
@deftypefnx {} {[@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/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 libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn  {} {@var{s} =} urlread (@var{url})
@deftypefnx {} {[@var{s}, @var{success}] =} urlread (@var{url})
@deftypefnx {} {[@var{s}, @var{success}, @var{message}] =} urlread (@var{url})
@deftypefnx {} {[@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/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__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn  {} {@var{handle} =} __ftp__ (@var{host})
@deftypefnx {} {@var{handle} =} __ftp__ (@var{host}, @var{username}, @var{password})
Undocumented internal function
@end deftypefn
__ftp_pwd__
@c __ftp_pwd__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_pwd__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_cwd__
@c __ftp_cwd__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_cwd__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_dir__
@c __ftp_dir__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_dir__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_ascii__
@c __ftp_ascii__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_ascii__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_binary__
@c __ftp_binary__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_binary__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_close__
@c __ftp_close__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_close__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_mode__
@c __ftp_mode__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_mode__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_delete__
@c __ftp_delete__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_delete__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_rmdir__
@c __ftp_rmdir__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_rmdir__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_mkdir__
@c __ftp_mkdir__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_mkdir__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_rename__
@c __ftp_rename__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_rename__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_mput__
@c __ftp_mput__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn {} {} __ftp_mput__ (@var{handle}, @var{files})
Undocumented internal function
@end deftypefn
__ftp_mget__
@c __ftp_mget__ libinterp/corefcn/urlwrite.cc
-*- texinfo -*-
@deftypefn  {} {} __ftp_mget__ (@var{handle}, @var{pattern})
@deftypefnx {} {} __ftp_mget__ (@var{handle}, @var{pattern}, @var{target})
Undocumented internal function
@end deftypefn
isvarname
@c isvarname libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn {} {} isvarname (@var{name})
Return true if @var{name} is a valid variable name.

A valid variable name is composed of letters, digits, and underscores ("_"),
and the first character must not be a digit.
@seealso{iskeyword, exist, who}
@end deftypefn
file_in_loadpath
@c file_in_loadpath libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn  {} {@var{fname} =} file_in_loadpath (@var{file})
@deftypefnx {} {@var{fname} =} 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.

When @var{file} is already an absolute name, the name is checked against the
file system instead of Octave's loadpath.  In this case, if @var{file} exists
it will be returned in @var{fname}, otherwise an empty string is returned.

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 @qcode{"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, dir_in_loadpath, path}
@end deftypefn
file_in_path
@c file_in_path libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn  {} {} file_in_path (@var{path}, @var{file})
@deftypefnx {} {} 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 @qcode{"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, dir_in_loadpath, path}
@end deftypefn
do_string_escapes
@c do_string_escapes libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn {} {} do_string_escapes (@var{string})
Convert escape sequences in @var{string} to the characters they represent.

Escape sequences begin with a leading backslash
(@qcode{'@xbackslashchar{}'}) followed by 1--3 characters
(.e.g., @qcode{"@xbackslashchar{}n"} => newline).
@seealso{undo_string_escapes}
@end deftypefn
undo_string_escapes
@c undo_string_escapes libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn {} {} 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.
@seealso{do_string_escapes}
@end deftypefn
is_absolute_filename
@c is_absolute_filename libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn {} {} is_absolute_filename (@var{file})
Return true if @var{file} is an absolute filename.
@seealso{is_rooted_relative_filename, make_absolute_filename, isfolder}
@end deftypefn
is_rooted_relative_filename
@c is_rooted_relative_filename libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn {} {} is_rooted_relative_filename (@var{file})
Return true if @var{file} is a rooted-relative filename.
@seealso{is_absolute_filename, make_absolute_filename, isfolder}
@end deftypefn
make_absolute_filename
@c make_absolute_filename libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn {} {} make_absolute_filename (@var{file})
Return the full name of @var{file} beginning from the root of the file
system.

No check is done for the existence of @var{file}.
@seealso{canonicalize_file_name, is_absolute_filename, is_rooted_relative_filename, isfolder}
@end deftypefn
dir_in_loadpath
@c dir_in_loadpath libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn  {} {@var{dirname} =} dir_in_loadpath (@var{dir})
@deftypefnx {} {@var{dirname} =} dir_in_loadpath (@var{dir}, "all")
Return the absolute name of the loadpath element matching @var{dir} if it can
be found in the list of directories specified by @code{path}.

If no match is found, return an empty character string.

The match is performed at the end of each path element.  For example, if
@var{dir} is @qcode{"foo/bar"}, it matches the path element
@nospell{@qcode{"/some/dir/foo/bar"}}, but not
@nospell{@qcode{"/some/dir/foo/bar/baz"}}
@nospell{@qcode{"/some/dir/allfoo/bar"}}.  When @var{dir} is an absolute name,
rather than just a path fragment, it is matched against the file system
instead of Octave's loadpath.  In this case, if @var{dir} exists it will be
returned in @var{dirname}, otherwise an empty string is returned.

If the optional second argument is supplied, return a cell array containing
all name matches rather than just the first.
@seealso{file_in_path, file_in_loadpath, path}
@end deftypefn
errno
@c errno libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn  {} {@var{err} =} errno ()
@deftypefnx {} {@var{err} =} errno (@var{val})
@deftypefnx {} {@var{err} =} errno (@var{name})
Query or set the system-dependent variable errno.

When called with no inputs, return the current value of errno.

When called with a numeric input @var{val}, set the current value of errno
to the specified value.  The previous value of errno is returned as @var{err}.

When called with a character string @var{name}, return the numeric value of
errno which corresponds to the specified error code.  If @var{name} is not
a recognized error code then -1 is returned.

@seealso{errno_list}
@end deftypefn
errno_list
@c errno_list libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn {} {} errno_list ()
Return a structure containing the system-dependent errno values.
@seealso{errno}
@end deftypefn
isindex
@c isindex libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn  {} {} isindex (@var{ind})
@deftypefnx {} {} 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.

Implementation Note: Strings are first converted to double values before the
checks for valid indices are made.  Unless a string contains the NULL
character @nospell{"@xbackslashchar{}0"}, it will always be a valid index.
@end deftypefn
isstudent
@c isstudent libinterp/corefcn/utils.cc
-*- texinfo -*-
@deftypefn {} {} isstudent ()
Return true if running in the student edition of @sc{matlab}.

@code{isstudent} always returns false in Octave.
@seealso{false}
@end deftypefn
isglobal
@c isglobal libinterp/corefcn/variables.cc
-*- texinfo -*-
@deftypefn {} {} 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 libinterp/corefcn/variables.cc
-*- texinfo -*-
@deftypefn  {} {@var{c} =} exist (@var{name})
@deftypefnx {} {@var{c} =} exist (@var{name}, @var{type})
Check for the existence of @var{name} as a variable, function, file, directory,
or class.

The return code @var{c} is one of

@table @asis
@item 1
@var{name} is a variable.

@item 2
@var{name} is an absolute filename, an ordinary file in Octave's @code{path},
or (after appending @samp{.m}) a function file in Octave's @code{path}.

@item 3
@var{name} is a @samp{.oct} or @samp{.mex} file in Octave's @code{path}.

@item 5
@var{name} is a built-in function.

@item 7
@var{name} is a directory.

@item 8
@var{name} is a class.  (Note: not currently implemented)

@item 103
@var{name} is a function not associated with a file (entered on the command
line).

@item 0
@var{name} does not exist.
@end table

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

@table @asis
@item @qcode{"var"}
Check only for variables.

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

@item @qcode{"dir"}
Check only for directories.

@item @qcode{"file"}
Check only for files and directories.

@item @qcode{"class"}
Check only for classes.  (Note: This option is accepted, but not currently
implemented)
@end table

If no type is given, and there are multiple possible matches for name,
@code{exist} will return a code according to the following priority list:
variable, built-in function, oct-file, directory, file, class.

@code{exist} returns 2 if a regular file called @var{name} is present in
Octave's search path.  For information about other types of files not on the
search path use some combination of the functions @code{file_in_path} and
@code{stat} instead.

Programming Note: If @var{name} is implemented by a buggy .oct/.mex file,
calling @var{exist} may cause Octave to crash.  To maintain high performance,
Octave trusts .oct/.mex files instead of @nospell{sandboxing} them.

@seealso{file_in_loadpath, file_in_path, dir_in_loadpath, stat}
@end deftypefn
mlock
@c mlock libinterp/corefcn/variables.cc
-*- texinfo -*-
@deftypefn {} {} mlock ()
Lock the current function into memory so that it can't be removed with
@code{clear}.
@seealso{munlock, mislocked, persistent, clear}
@end deftypefn
munlock
@c munlock libinterp/corefcn/variables.cc
-*- texinfo -*-
@deftypefn  {} {} munlock ()
@deftypefnx {} {} munlock (@var{fcn})
Unlock the named function @var{fcn} so that it may be removed from memory with
@code{clear}.

If no function is named then unlock the current function.
@seealso{mlock, mislocked, persistent, clear}
@end deftypefn
mislocked
@c mislocked libinterp/corefcn/variables.cc
-*- texinfo -*-
@deftypefn  {} {} mislocked ()
@deftypefnx {} {} mislocked (@var{fcn})
Return true if the named function @var{fcn} is locked in memory.

If no function is named then return true if the current function is locked.
@seealso{mlock, munlock, persistent, clear}
@end deftypefn
clear
@c clear libinterp/corefcn/variables.cc
-*- texinfo -*-
@deftypefn  {} {} clear
@deftypefnx {} {} clear @var{pattern} @dots{}
@deftypefnx {} {} clear @var{options} @var{pattern} @dots{}
Delete the names matching the given @var{pattern}s from the symbol table.

The @var{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 @code{[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 @samp{b}
and end with the letter @samp{r}.

If @code{clear} is called without any arguments, all user-defined variables
are cleared from the current workspace (i.e., local variables).  Any global
variables present will no longer be visible in the current workspace, but they
will continue to exist in the global workspace.  Functions are unaffected by
this form of @code{clear}.

The following options are available in both long and short form

@table @code
@item all, -all, -a
Clear all local and global user-defined variables, and all functions from the
symbol table.

@item -exclusive, -x
Clear variables that do @strong{not} match the following pattern.

@item functions, -functions, -f
Clear function names from the function symbol table.  Persistent variables
will be re-initialized to their default value unless the function has been
locked in memory with @code{mlock}.

@item global, -global, -g
Clear global variable names.

@item variables, -variables, -v
Clear local variable names.

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

@item -regexp, -r
The @var{pattern} arguments are treated as regular expressions and any matches
will be cleared.
@end table

With the exception of @option{-exclusive} and @option{-regexp}, all long
options can be used without the dash as well.  Note that, aside from
@option{-exclusive}, only one other option may appear.  All options must
appear before any patterns.

Programming Note: The command @code{clear @var{name}} only clears the variable
@var{name} when both a variable and a (shadowed) function named @var{name}
are currently defined.  For example, suppose you have defined a function
@code{foo}, and then hidden it by performing the assignment @code{foo = 2}.
Executing the command @code{clear foo} once will clear the variable
definition and restore the definition of @code{foo} as a function.
Executing @code{clear foo} a second time will clear the function definition.

@seealso{who, whos, exist, mlock}
@end deftypefn
missing_function_hook
@c missing_function_hook libinterp/corefcn/variables.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} missing_function_hook ()
@deftypefnx {} {@var{old_val} =} missing_function_hook (@var{new_val})
@deftypefnx {} {} 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 @qcode{"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{missing_component_hook}
@end deftypefn
__varval__
@c __varval__ libinterp/corefcn/variables.cc
-*- texinfo -*-
@deftypefn {} {} __varval__ (@var{name})
Return the value of the variable @var{name} directly from the symbol table.
@end deftypefn
missing_component_hook
@c missing_component_hook libinterp/corefcn/variables.cc
-*- texinfo -*-
@deftypefn  {} {@var{val} =} missing_component_hook ()
@deftypefnx {} {@var{old_val} =} missing_component_hook (@var{new_val})
@deftypefnx {} {} missing_component_hook (@var{new_val}, "local")
Query or set the internal variable that specifies the function to call when
a component of Octave is missing.

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

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

The hook function is expected to be of the form

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

Octave will call @var{fcn} with the name of the function that requires the
component and a string describing the missing component.  The hook function
should return an error message to be displayed.
@seealso{missing_function_hook}
@end deftypefn
!
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} !
Logical 'not' operator.
@seealso{~, not}
@end deftypefn
~
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} ~
Logical 'not' operator.

The symbol may also be used to discard outputs of a function that are unwanted
without using a temporary variable.

@example
[~, @var{idx_of_max}] = max (@var{x})
@end example
@seealso{!, not}
@end deftypefn
!=
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} !=
Logical 'not equals' operator.
@seealso{~=, ne}
@end deftypefn
~=
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} ~=
Logical 'not equals' operator.
@seealso{!=, ne}
@end deftypefn
"
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} "
String delimiter.

Escape sequences within double-quoted strings are expanded.  I.e., "\n" is a
1-character string representing a newline.  See the single quote delimiter (')
to create strings without escape sequence processing.
@seealso{'}
@end deftypefn
#
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} #
Begin comment character.
@seealso{%, #@\{}
@end deftypefn
%
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} %
Begin comment character.
@seealso{#, %@\{}
@end deftypefn
#{
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} #@{
Begin block comment.

There must be no other characters, other than whitespace, on the line before
and after @code{#@{}.  It is possible to nest block comments.
@seealso{%@\{, #@\}, #}
@end deftypefn
%{
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} %@{
Begin block comment.

There must be no other characters, other than whitespace, on the line before
and after @code{%@{}.  It is possible to nest block comments.
@seealso{#@\{, %@\}, %}
@end deftypefn
#}
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} #@}
Close block comment.

There must be no other characters, other than whitespace, on the line before
and after @code{#@}}.  It is possible to nest block comments.
@seealso{%@\}, #@\{, #}
@end deftypefn
%}
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} %@}
Close block comment.

There must be no other characters, other than whitespace, on the line before
and after @code{%@}}.  It is possible to nest block comments.
@seealso{#@\}, %@\{, %}
@end deftypefn
...
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} ...
Continuation marker.

Joins current line with following line before parsing.
@end deftypefn
&
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} &
Element by element logical 'and' operator.
@seealso{&&, and}
@end deftypefn
&&
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} &&
Logical 'and' operator (with short-circuit evaluation).
@seealso{&, and}
@end deftypefn
'
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} '
Matrix transpose operator or string delimiter.

For complex matrices, computes the complex conjugate (Hermitian) transpose.

The single quote character may also be used to delimit strings.  Escape
sequences within single-quoted strings are not expanded.  I.e., '\n' is a
2-character string '\' and 'n' rather than "\n" which is a single character
representing a newline.
@seealso{.', transpose, "}
@end deftypefn
(
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} (
Array index or function argument delimiter.
@end deftypefn
)
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {})
Array index or function argument delimiter.
@end deftypefn
*
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} *
Multiplication operator.
@seealso{.*, times}
@end deftypefn
**
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} **
Power operator.

This may return complex results for real inputs.  Use @code{realsqrt},
@code{cbrt}, @code{nthroot}, or @code{realpow} to obtain real results when
possible.
@seealso{power, ^, .**, .^, realpow, realsqrt, cbrt, nthroot}
@end deftypefn
^
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} ^
Power operator.

This may return complex results for real inputs.  Use @code{realsqrt},
@code{cbrt}, @code{nthroot}, or @code{realpow} to obtain real results when
possible.
@seealso{power, **, .^, .**, realpow, realsqrt, cbrt, nthroot}
@end deftypefn
+
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} +
Addition operator.
@seealso{plus}
@end deftypefn
++
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} ++
Increment operator.

As in C, may be applied as a prefix or postfix operator.
@seealso{--}
@end deftypefn
,
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} ,
Array index, function argument, or command separator.
@end deftypefn
-
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} -
Subtraction or unary negation operator.
@seealso{minus}
@end deftypefn
--
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} --
Decrement operator.

As in C, may be applied as a prefix or postfix operator.
@seealso{++}
@end deftypefn
.'
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} .'
Matrix transpose operator.

For complex matrices, computes the transpose, @emph{not} the complex conjugate
(Hermitian) transpose.
@seealso{', transpose}
@end deftypefn
.*
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} .*
Element by element multiplication operator.
@seealso{*, times}
@end deftypefn
.**
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} .**
Element by element power operator.

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.
@seealso{**, ^, .^, power, realpow, realsqrt, cbrt, nthroot}
@end deftypefn
.^
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} .^
Element by element power operator.

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.
@seealso{.**, ^, **, power, realpow, realsqrt, cbrt, nthroot}
@end deftypefn
./
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} ./
Element by element right division operator.
@seealso{/, .\\, rdivide, mrdivide}
@end deftypefn
/
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} /
Right division operator.
@seealso{./, \\, rdivide, mrdivide}
@end deftypefn
.\
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} .\
Element by element left division operator.
@seealso{\\, ./, rdivide, mrdivide}
@end deftypefn
\
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} \
Left division operator.

Within double-quoted strings, @samp{\} is the line continuation marker used
to join the current line with the following line.
@seealso{.\\, /, ldivide, mldivide}
@end deftypefn
:
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} :
Select entire rows or columns of matrices.
@end deftypefn
;
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} ;
Array row or command separator.
@seealso{,}
@end deftypefn
<
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} <
'Less than' operator.
@seealso{lt}
@end deftypefn
<=
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} <=
'Less than' or 'equals' operator.
@seealso{le}
@end deftypefn
=
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} =
Assignment operator.
@end deftypefn
==
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} ==
Equality test operator.
@seealso{eq}
@end deftypefn
>
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} >
'Greater than' operator.
@seealso{gt}
@end deftypefn
>=
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} >=
'Greater than' or 'equals' operator.
@seealso{ge}
@end deftypefn
[
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} [
Return list delimiter.
@seealso{]}
@end deftypefn
]
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} ]
Return list delimiter.
@seealso{[}
@end deftypefn
|
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} |
Element by element logical 'or' operator.
@seealso{||, or}
@end deftypefn
||
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} ||
Logical 'or' (with short-circuit evaluation) operator.
@seealso{|, or}
@end deftypefn
@
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} @@
Return handle to a function.

Example:

@example
@group
f = @@plus;
f (2, 2)
@result{}  4
@end group
@end example

(Note: @@ also finds use in creating classes.  See manual chapter titled
Object Oriented Programming for detailed description.)
@seealso{function, functions, func2str, str2func}
@end deftypefn
break
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} break
Exit the innermost enclosing do, while, or for loop.
@seealso{do, while, for, parfor, continue}
@end deftypefn
case
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {} case @var{value}
@deftypefnx {} {} case @{@var{value}, @dots{}@}
A case statement in a switch block.

Octave cases are exclusive and do not fall-through as do C-language cases.  A
switch statement must have at least one case.  See @code{switch} for an
example.
@seealso{switch}
@end deftypefn
catch
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {} catch
@deftypefnx {} {} catch @var{value}
Begin the cleanup part of a try-catch block.
@seealso{try}
@end deftypefn
classdef
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} classdef
Begin a classdef block.
@seealso{properties, methods, events, enumeration}
@end deftypefn
continue
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} continue
Jump to the end of the innermost enclosing do, while, or for loop.
@seealso{break, do, while, for, parfor}
@end deftypefn
do
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} do
Begin a do-until loop.

This differs from a while loop in that the body of the loop is executed at
least once.

@example
@group
i = 0;
do
  i++
until (i == 10)
@end group
@end example
@seealso{for, until, while}
@end deftypefn
else
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} else
Alternate action for an if block.  See @code{if} for  an example.
@seealso{if}
@end deftypefn
elseif
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} elseif (@var{condition})
Alternate conditional test for an if block.  See @code{if} for an example.
@seealso{if}
@end deftypefn
end_try_catch
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} end_try_catch
Mark the end of a @code{try-catch} block.
@seealso{try, catch}
@end deftypefn
end_unwind_protect
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} end_unwind_protect
Mark the end of an unwind_protect block.
@seealso{unwind_protect}
@end deftypefn
endclassdef
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} endclassdef
Mark the end of a classdef definition.
@seealso{classdef}
@end deftypefn
endenumeration
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} endenumeration
Mark the end of an enumeration block in a classdef definition.
@seealso{enumeration}
@end deftypefn
endevents
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} endevents
Mark the end of an events block in a classdef definition.
@seealso{events}
@end deftypefn
endfor
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} endfor
Mark the end of a for loop.  See @code{for} for an example.
@seealso{for}
@end deftypefn
endfunction
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} endfunction
Mark the end of a function.
@seealso{function}
@end deftypefn
endif
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} endif
Mark the end of an if block.  See @code{if} for an example.
@seealso{if}
@end deftypefn
endmethods
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} endmethods
Mark the end of a methods block in a classdef definition.
@seealso{methods}
@end deftypefn
endparfor
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} endparfor
Mark the end of a parfor loop.  See @code{parfor} for an example.
@seealso{parfor}
@end deftypefn
endproperties
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} endproperties
Mark the end of a properties block in a classdef definition.
@seealso{properties}
@end deftypefn
endswitch
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} endswitch
Mark the end of a switch block.  See @code{switch} for an example.
@seealso{switch}
@end deftypefn
endwhile
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} endwhile
Mark the end of a while loop.  See @code{while} for an example.
@seealso{do, while}
@end deftypefn
enumeration
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} enumeration
Begin an enumeration block in a classdef definition.
@end deftypefn
events
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} events
Begin an events block in a classdef definition.
@end deftypefn
for
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} for @var{i} = @var{range}
Begin a for loop.

@example
@group
for i = 1:10
  i
endfor
@end group
@end example
@seealso{parfor, do, while}
@end deftypefn
function
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {} function @var{outputs} = function_name (@var{input}, @dots{})
@deftypefnx {} {} function {} function_name (@var{input}, @dots{})
@deftypefnx {} {} function @var{outputs} = function_name
Begin a function body with name @code{function_name}, with @var{outputs} as
results, and with @var{inputs} as parameters.  The function can later be
invoked in Octave using the syntax

@example
[@var{output1}, @var{output2}, @dots{}] = function_name (@var{input1}, @var{input2}, @dots{})
@end example

@seealso{return}
@end deftypefn
global
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} global @var{var}
Declare variables to have global scope.

@example
@group
global @var{x};
if (isempty (@var{x}))
  x = 1;
endif
@end group
@end example
@seealso{persistent}
@end deftypefn
if
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {} if (@var{cond}) @dots{} endif
@deftypefnx {} {} if (@var{cond}) @dots{} else @dots{} endif
@deftypefnx {} {} if (@var{cond}) @dots{} elseif (@var{cond}) @dots{} endif
@deftypefnx {} {} if (@var{cond}) @dots{} elseif (@var{cond}) @dots{} else @dots{} endif
Begin an if block.

@example
@group
x = 1;
if (x == 1)
  disp ("one");
elseif (x == 2)
  disp ("two");
else
  disp ("not one or two");
endif
@end group
@end example
@seealso{switch}
@end deftypefn
@c ## FIXME: Can't have duplicate DOCSTRING entries.  The function methods
@c ##        already has a docstring which overrides this keyword definition.
@c #methods
@c #@c libinterp/parse-tree/oct-parse.yy
@c #-*- texinfo -*-
@c #@deftypefn {} {} methods
@c #Begin a methods block in a classdef definition.
@c #@end deftypefn
otherwise
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} otherwise
The default statement in a switch block which is executed when no other
case statements match the input.
@seealso{switch, case}
@end deftypefn
parfor
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn  {} {} parfor @var{i} = @var{range}
@deftypefnx {} {} parfor (@var{i} = @var{range}, @var{maxproc})
Begin a for loop that may execute in parallel.

A @code{parfor} loop has the same syntax as a @code{for} loop.  If your Octave
session has a parallel processing pool enabled, the iterations of the
@code{parfor} loop will be executed in parallel across the pool's workers.
Otherwise, @code{parfor} will behave exactly as @code{for}.

When operating in parallel mode, a @code{parfor} loop's iterations are not
guaranteed to occur sequentially, and there are additional restrictions about
the data access operations you can do inside the loop body.

@strong{Warning:} parallel processing pools are currently unimplemented in
Octave; @code{parfor} currently behaves exactly as a normal @code{for} loop.

@example
@group
parfor i = 1:10
  i
endparfor
@end group
@end example
@seealso{for, do, while}
@end deftypefn
persistent
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} persistent @var{var}
Declare variables as persistent.

A variable that has been declared persistent within a function will retain its
contents in memory between subsequent calls to the same function.  The
difference between persistent variables and global variables is that persistent
variables are local in scope to a particular function and are not visible
elsewhere.
@seealso{global}
@end deftypefn
properties
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} properties
Begin a properties block in a classdef definition.
@end deftypefn
return
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} return
Return from a function.
@seealso{function}
@end deftypefn
switch
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} switch @var{statement}
Begin a switch block.

@example
@group
yesno = "yes";

switch (yesno)
  case @{"Yes" "yes" "YES" "y" "Y"@}
    value = 1;
  case @{"No" "no" "NO" "n" "N"@}
    value = 0;
  otherwise
    error ("invalid value");
endswitch
@end group
@end example
@seealso{if, case, otherwise}
@end deftypefn
try
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} try
Begin a try-catch block.

If an error occurs within a try block, then the catch code will be run and
execution will proceed after the catch block (though it is often recommended to
use the lasterr function to re-throw the error after cleanup is completed).
@seealso{catch, unwind_protect}
@end deftypefn
until
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} until (@var{cond})
End a do-until loop.  See @code{do} for an example.
@seealso{do}
@end deftypefn
unwind_protect
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} unwind_protect
Begin an unwind_protect block.

If an error occurs within the first part of an unwind_protect block the
commands within the unwind_protect_cleanup block are executed before the error
is thrown.  If an error is not thrown, then the unwind_protect_cleanup block is
still executed.  In other words, the unwind_protect_cleanup code is guaranteed
to execute regardless of success or failure in the unwind_protect block.
@seealso{unwind_protect_cleanup, try}
@end deftypefn
unwind_protect_cleanup
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} unwind_protect_cleanup
Begin the cleanup section of an unwind_protect block.
@seealso{unwind_protect}
@end deftypefn
varargin
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} varargin
Pass an arbitrary number of arguments into a function.
@seealso{varargout, nargin, isargout, nargout, nthargout}
@end deftypefn
varargout
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} varargout
Pass an arbitrary number of arguments out of a function.
@seealso{varargin, nargin, isargout, nargout, nthargout}
@end deftypefn
while
@c libinterp/parse-tree/oct-parse.yy
-*- texinfo -*-
@deftypefn {} {} while
Begin a while loop.

@example
@group
i = 0;
while (i < 10)
  i++
endwhile
@end group
@end example
@seealso{do, endwhile, for, until}
@end deftypefn
