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

@c The following macro marks words that aspell should ignore during
@c spellchecking.  Within Texinfo it has no effect as it merely replaces
@c the macro call with the argument itself.

@macro nospell {arg}
\arg\
@end macro

@c The following macro works around the Info/plain text expansion of @code{XXX}
@c which is `XXX'.  This looks particularly bad when the macro body is
@c single or double-quoted text, such as a property value `"position"'
@ifinfo
@macro qcode{arg}
\arg\
@end macro
@end ifinfo
@ifnotinfo
@macro qcode{arg}
@code{\arg\}
@end macro
@end ifnotinfo

@c The following macro is used for the on-line help system, but we don't
@c want lots of `See also: foo, bar, and baz' strings cluttering the
@c printed manual (that information should be in the supporting text for
@c each group of functions and variables).
@c
@c Implementation Note:
@c For TeX, @vskip produces a nice separation.
@c For Texinfo, '@sp 1' should work, but in practice produces ugly results
@c for HTML.  We use a simple blank line to produce the correct
@c behavior.
@c
@c We use @xseealso now because Texinfo introduced its own @seealso
@c command.  But instead of modifying all source files, we'll have the
@c munge-texi script convert @seealso to @xseealso.

@macro xseealso {args}
@iftex
@vskip 2pt
@end iftex
@ifnottex

@end ifnottex
@ifnotinfo
@noindent
@strong{See also:} \args\.
@end ifnotinfo
@ifinfo
@noindent
See also: \args\.
@end ifinfo
@end macro

@c The following macro works around a situation where the Info/plain text
@c expansion of the @code{XXX} macro is `XXX'.  The use of the apostrophe
@c can be confusing if the code segment itself ends with a transpose operator.
@ifinfo
@macro tcode{arg}
\arg\
@end macro
@end ifinfo
@ifnotinfo
@macro tcode{arg}
@code{\arg\}
@end macro
@end ifnotinfo

@c FIXME: someday, when Texinfo 5.X is standard, we might replace this with
@c @backslashchar, which is a new addition to Texinfo.

@macro xbackslashchar
\\
@end macro

@c These may be useful for all, not just for octave.texi.
@tex
  \ifx\rgbDarkRed\thisisundefined
    \def\rgbDarkRed{0.50 0.09 0.12}
  \fi
  \ifx\linkcolor\thisisundefined
    \relax
  \else
    \global\def\linkcolor{\rgbDarkRed}
  \fi
  \ifx\urlcolor\thisisundefined
    \relax
  \else
    \global\def\urlcolor{\rgbDarkRed}
  \fi
  \ifx\urefurlonlylinktrue\thisisundefined
    \relax
  \else
    \global\urefurlonlylinktrue
  \fi
@end tex

@c Make the apostrophe in code examples cut-and-paste friendly.
@codequoteundirected on
__delaunayn__
@c __delaunayn__ libinterp/dldfcn/__delaunayn__.cc
@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
@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
@deftypefn {} {} __fltk_uigetfile__ (@dots{})
Undocumented internal function.
@end deftypefn
__glpk__
@c __glpk__ libinterp/dldfcn/__glpk__.cc
@deftypefn {} {[@var{values}] =} __glpk__ (@var{args})
Undocumented internal function.
@end deftypefn
__fltk_check__
@c __fltk_check__ libinterp/dldfcn/__init_fltk__.cc
@deftypefn {} {} __fltk_check__ ()
Undocumented internal function.  Calls Fl::check ()
@end deftypefn
__init_fltk__
@c __init_fltk__ libinterp/dldfcn/__init_fltk__.cc
@deftypefn {} {} __init_fltk__ ()
Undocumented internal function.
@end deftypefn
__init_gnuplot__
@c __init_gnuplot__ libinterp/dldfcn/__init_gnuplot__.cc
@deftypefn {} {} __init_gnuplot__ ()
Undocumented internal function.
@end deftypefn
__have_gnuplot__
@c __have_gnuplot__ libinterp/dldfcn/__init_gnuplot__.cc
@deftypefn {} {@var{gnuplot_available} =} __have_gnuplot__ ()
Undocumented internal function.
@end deftypefn
__ode15__
@c __ode15__ libinterp/dldfcn/__ode15__.cc
@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
@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
@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}).
@xseealso{symamd, colamd}
@end deftypefn
audiodevinfo
@c audiodevinfo libinterp/dldfcn/audiodevinfo.cc
@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
@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
@deftypefn {} {@var{data} =} __recorder_getaudiodata__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_channels__
@c __recorder_get_channels__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {@var{n} =} __recorder_get_channels__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_fs__
@c __recorder_get_fs__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {@var{fs} =} __recorder_get_fs__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_id__
@c __recorder_get_id__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {@var{id} =} __recorder_get_id__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_get_nbits__
@c __recorder_get_nbits__ libinterp/dldfcn/audiodevinfo.cc
@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
@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
@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
@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
@deftypefn {} {@var{data} =} __recorder_get_userdata__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_isrecording__
@c __recorder_isrecording__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __recorder_isrecording__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_pause__
@c __recorder_pause__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __recorder_pause__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_recordblocking__
@c __recorder_recordblocking__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __recorder_recordblocking__ (@var{recorder}, @var{seconds})
Undocumented internal function.
@end deftypefn
__recorder_record__
@c __recorder_record__ libinterp/dldfcn/audiodevinfo.cc
@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
@deftypefn {} {} __recorder_resume__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__recorder_set_fs__
@c __recorder_set_fs__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __recorder_set_fs__ (@var{recorder}, @var{fs})
Undocumented internal function.
@end deftypefn
__recorder_set_tag__
@c __recorder_set_tag__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __recorder_set_tag__ (@var{recorder}, @var{tag})
Undocumented internal function.
@end deftypefn
__recorder_set_userdata__
@c __recorder_set_userdata__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __recorder_set_userdata__ (@var{recorder}, @var{data})
Undocumented internal function.
@end deftypefn
__recorder_stop__
@c __recorder_stop__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __recorder_stop__ (@var{recorder})
Undocumented internal function.
@end deftypefn
__player_audioplayer__
@c __player_audioplayer__ libinterp/dldfcn/audiodevinfo.cc
@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
@deftypefn {} {@var{n} =} __player_get_channels__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_get_fs__
@c __player_get_fs__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {@var{fs} =} __player_get_fs__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_get_id__
@c __player_get_id__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {@var{id} =} __player_get_id__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_get_nbits__
@c __player_get_nbits__ libinterp/dldfcn/audiodevinfo.cc
@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
@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
@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
@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
@deftypefn {} {@var{data} =} __player_get_userdata__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_isplaying__
@c __player_isplaying__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __player_isplaying__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_pause__
@c __player_pause__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __player_pause__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_playblocking__
@c __player_playblocking__ libinterp/dldfcn/audiodevinfo.cc
@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
@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
@deftypefn {} {} __player_resume__ (@var{player})
Undocumented internal function.
@end deftypefn
__player_set_fs__
@c __player_set_fs__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __player_set_fs__ (@var{player}, @var{fs})
Undocumented internal function.
@end deftypefn
__player_set_tag__
@c __player_set_tag__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __player_set_tag__ (@var{player}, @var{tag})
Undocumented internal function.
@end deftypefn
__player_set_userdata__
@c __player_set_userdata__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __player_set_userdata__ (@var{player}, @var{data})
Undocumented internal function.
@end deftypefn
__player_stop__
@c __player_stop__ libinterp/dldfcn/audiodevinfo.cc
@deftypefn {} {} __player_stop__ (@var{player})
Undocumented internal function.
@end deftypefn
audioread
@c audioread libinterp/dldfcn/audioread.cc
@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.
@xseealso{audiowrite, audioformats, audioinfo}
@end deftypefn
audiowrite
@c audiowrite libinterp/dldfcn/audioread.cc
@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
@xseealso{audioread, audioformats, audioinfo}
@end deftypefn
audioinfo
@c audioinfo libinterp/dldfcn/audioread.cc
@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
@xseealso{audioread, audiowrite}
@end deftypefn
audioformats
@c audioformats libinterp/dldfcn/audioread.cc
@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}.
@xseealso{audioread, audiowrite}
@end deftypefn
ccolamd
@c ccolamd libinterp/dldfcn/ccolamd.cc
@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.
@xseealso{colamd, csymamd}
@end deftypefn
csymamd
@c csymamd libinterp/dldfcn/ccolamd.cc
@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.
@xseealso{symamd, ccolamd}
@end deftypefn
chol
@c chol libinterp/dldfcn/chol.cc
@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.
@xseealso{hess, lu, qr, qz, schur, svd, ichol, cholinv, chol2inv, cholupdate, cholinsert, choldelete, cholshift}
@end deftypefn
cholinv
@c cholinv libinterp/dldfcn/chol.cc
@deftypefn {} {} cholinv (@var{A})
Compute the inverse of the symmetric positive definite matrix @var{A} using
the Cholesky@tie{}factorization.
@xseealso{chol, chol2inv, inv}
@end deftypefn
chol2inv
@c chol2inv libinterp/dldfcn/chol.cc
@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}.
@xseealso{chol, cholinv, inv}
@end deftypefn
cholupdate
@c cholupdate libinterp/dldfcn/chol.cc
@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.
@xseealso{chol, cholinsert, choldelete, cholshift}
@end deftypefn
cholinsert
@c cholinsert libinterp/dldfcn/chol.cc
@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.
@xseealso{chol, cholupdate, choldelete, cholshift}
@end deftypefn
choldelete
@c choldelete libinterp/dldfcn/chol.cc
@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]}.
@xseealso{chol, cholupdate, cholinsert, cholshift}
@end deftypefn
cholshift
@c cholshift libinterp/dldfcn/chol.cc
@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}}.  @*

@xseealso{chol, cholupdate, cholinsert, choldelete}
@end deftypefn
colamd
@c colamd libinterp/dldfcn/colamd.cc
@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})
@xseealso{colperm, symamd, ccolamd}
@end deftypefn
symamd
@c symamd libinterp/dldfcn/colamd.cc
@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})
@xseealso{colperm, colamd}
@end deftypefn
etree
@c etree libinterp/dldfcn/colamd.cc
@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
@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.
@xseealso{convhull, delaunayn, voronoin}
@end deftypefn
dmperm
@c dmperm libinterp/dldfcn/dmperm.cc
@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.
@xseealso{colamd, ccolamd}
@end deftypefn
sprank
@c sprank libinterp/dldfcn/dmperm.cc
@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})}.
@xseealso{dmperm}
@end deftypefn
fftw
@c fftw libinterp/dldfcn/fftw.cc
@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.

@xseealso{fft, ifft, fft2, ifft2, fftn, ifftn}
@end deftypefn
gzip
@c gzip libinterp/dldfcn/gzip.cc
@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.
@xseealso{gunzip, unpack, bzip2, zip, tar}
@end deftypefn
bzip2
@c bzip2 libinterp/dldfcn/gzip.cc
@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.
@xseealso{bunzip2, unpack, gzip, zip, tar}
@end deftypefn
qr
@c qr libinterp/dldfcn/qr.cc
@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)}.

@xseealso{chol, hess, lu, qz, schur, svd, qrupdate, qrinsert, qrdelete, qrshift}
@end deftypefn
qrupdate
@c qrupdate libinterp/dldfcn/qr.cc
@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).

@xseealso{qr, qrinsert, qrdelete, qrshift}
@end deftypefn
qrinsert
@c qrinsert libinterp/dldfcn/qr.cc
@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.
@xseealso{qr, qrupdate, qrdelete, qrshift}
@end deftypefn
qrdelete
@c qrdelete libinterp/dldfcn/qr.cc
@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.
@xseealso{qr, qrupdate, qrinsert, qrshift}
@end deftypefn
qrshift
@c qrshift libinterp/dldfcn/qr.cc
@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}}.  @*

@xseealso{qr, qrupdate, qrinsert, qrdelete}
@end deftypefn
symbfact
@c symbfact libinterp/dldfcn/symbfact.cc
@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
@xseealso{chol, etree, treelayout}
@end deftypefn
symrcm
@c symrcm libinterp/dldfcn/symrcm.cc
@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.

@xseealso{colperm, colamd, symamd}
@end deftypefn
daspk_options
@c daspk_options libinterp/corefcn/DASPK-opts.cc
@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
@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
@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
@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
@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
@deftypefn {} {} isguirunning ()
Return true if Octave is running in GUI mode and false otherwise.
@xseealso{have_window_system}
@end deftypefn
argv
@c argv libinterp/octave.cc
@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
@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.
@xseealso{program_name}
@end deftypefn
program_name
@c program_name libinterp/octave.cc
@deftypefn {} {} program_name ()
Return the last component of the value returned by
@code{program_invocation_name}.
@xseealso{program_invocation_name}
@end deftypefn
sparse_auto_mutate
@c sparse_auto_mutate libinterp/octave-value/ov-base.cc
@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
@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.
@xseealso{double, single, char}
@end deftypefn
iscell
@c iscell libinterp/octave-value/ov-cell.cc
@deftypefn {} {} iscell (@var{x})
Return true if @var{x} is a cell array object.
@xseealso{ismatrix, isstruct, iscellstr, isa}
@end deftypefn
cell
@c cell libinterp/octave-value/ov-cell.cc
@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.
@xseealso{cellstr, mat2cell, num2cell, struct2cell}
@end deftypefn
iscellstr
@c iscellstr libinterp/octave-value/ov-cell.cc
@deftypefn {} {} iscellstr (@var{cell})
Return true if every element of the cell array @var{cell} is a character
string.
@xseealso{ischar, isstring}
@end deftypefn
cellstr
@c cellstr libinterp/octave-value/ov-cell.cc
@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}.
@xseealso{cell, char}
@end deftypefn
struct2cell
@c struct2cell libinterp/octave-value/ov-cell.cc
@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

@xseealso{cell2struct, fieldnames}
@end deftypefn
class
@c class libinterp/octave-value/ov-class.cc
@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.
@xseealso{typeinfo, isa}
@end deftypefn
isa
@c isa libinterp/octave-value/ov-class.cc
@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.

@xseealso{class, typeinfo}
@end deftypefn
__parent_classes__
@c __parent_classes__ libinterp/octave-value/ov-class.cc
@deftypefn {} {} __parent_classes__ (@var{x})
Undocumented internal function.
@end deftypefn
isobject
@c isobject libinterp/octave-value/ov-class.cc
@deftypefn {} {} isobject (@var{x})
Return true if @var{x} is a class object.
@xseealso{class, typeinfo, isa, ismethod, isprop}
@end deftypefn
ismethod
@c ismethod libinterp/octave-value/ov-class.cc
@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}.
@xseealso{isprop, isobject}
@end deftypefn
__methods__
@c __methods__ libinterp/octave-value/ov-class.cc
@deftypefn  {} {} __methods__ (@var{x})
@deftypefnx {} {} __methods__ ("classname")
Internal function.

Implements @code{methods} for Octave class objects and classnames.
@xseealso{methods}
@end deftypefn
superiorto
@c superiorto libinterp/octave-value/ov-class.cc
@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.
@xseealso{inferiorto}
@end deftypefn
inferiorto
@c inferiorto libinterp/octave-value/ov-class.cc
@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.
@xseealso{superiorto}
@end deftypefn
__meta_get_package__
@c __meta_get_package__ libinterp/octave-value/ov-classdef.cc
@deftypefn {} {} __meta_get_package__ ()
Undocumented internal function.
@end deftypefn
__superclass_reference__
@c __superclass_reference__ libinterp/octave-value/ov-classdef.cc
@deftypefn {} {} __superclass_reference__ ()
Undocumented internal function.
@end deftypefn
__meta_class_query__
@c __meta_class_query__ libinterp/octave-value/ov-classdef.cc
@deftypefn {} {} __meta_class_query__ ()
Undocumented internal function.
@end deftypefn
metaclass
@c metaclass libinterp/octave-value/ov-classdef.cc
@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
@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.

@xseealso{func2str, str2func}
@end deftypefn
func2str
@c func2str libinterp/octave-value/ov-fcn-handle.cc
@deftypefn {} {} func2str (@var{fcn_handle})
Return a string containing the name of the function referenced by the
function handle @var{fcn_handle}.
@xseealso{str2func, functions}
@end deftypefn
str2func
@c str2func libinterp/octave-value/ov-fcn-handle.cc
@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.
@xseealso{func2str, inline, functions}
@end deftypefn
is_function_handle
@c is_function_handle libinterp/octave-value/ov-fcn-handle.cc
@deftypefn {} {} is_function_handle (@var{x})
Return true if @var{x} is a function handle.
@xseealso{isa, typeinfo, class, functions}
@end deftypefn
inline
@c inline libinterp/octave-value/ov-fcn-inline.cc
@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}.
@xseealso{argnames, formula, vectorize, str2func}
@end deftypefn
formula
@c formula libinterp/octave-value/ov-fcn-inline.cc
@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})}.
@xseealso{char, argnames, inline, vectorize}
@end deftypefn
argnames
@c argnames libinterp/octave-value/ov-fcn-inline.cc
@deftypefn {} {} argnames (@var{fun})
Return a cell array of character strings containing the names of the
arguments of the inline function @var{fun}.
@xseealso{inline, formula, vectorize}
@end deftypefn
vectorize
@c vectorize libinterp/octave-value/ov-fcn-inline.cc
@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
@xseealso{inline, formula, argnames}
@end deftypefn
__java_init__
@c __java_init__ libinterp/octave-value/ov-java.cc
@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
@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
@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

@xseealso{javaMethod, javaArray}
@end deftypefn
javaMethod
@c javaMethod libinterp/octave-value/ov-java.cc
@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.

@xseealso{methods, javaObject}
@end deftypefn
__java_get__
@c __java_get__ libinterp/octave-value/ov-java.cc
@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

@xseealso{__java_set__, javaMethod, javaObject}
@end deftypefn
__java_set__
@c __java_set__ libinterp/octave-value/ov-java.cc
@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

@xseealso{__java_get__, javaMethod, javaObject}
@end deftypefn
__java2mat__
@c __java2mat__ libinterp/octave-value/ov-java.cc
@deftypefn {} {} __java2mat__ (@var{javaobj})
Undocumented internal function.
@end deftypefn
java_matrix_autoconversion
@c java_matrix_autoconversion libinterp/octave-value/ov-java.cc
@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.
@xseealso{java_unsigned_autoconversion, debug_java}
@end deftypefn
java_unsigned_autoconversion
@c java_unsigned_autoconversion libinterp/octave-value/ov-java.cc
@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.
@xseealso{java_matrix_autoconversion, debug_java}
@end deftypefn
debug_java
@c debug_java libinterp/octave-value/ov-java.cc
@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.
@xseealso{java_matrix_autoconversion, java_unsigned_autoconversion}
@end deftypefn
isjava
@c isjava libinterp/octave-value/ov-java.cc
@deftypefn {} {} isjava (@var{x})
Return true if @var{x} is a Java object.
@xseealso{class, typeinfo, isa, javaObject}
@end deftypefn
isnull
@c isnull libinterp/octave-value/ov-null-mat.cc
@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
@xseealso{isempty, isindex}
@end deftypefn
onCleanup
@c onCleanup libinterp/octave-value/ov-oncleanup.cc
@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
@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}.
@xseealso{cell2struct, fieldnames, getfield, setfield, rmfield, isfield, orderfields, isstruct, structfun}
@end deftypefn
isstruct
@c isstruct libinterp/octave-value/ov-struct.cc
@deftypefn {} {} isstruct (@var{x})
Return true if @var{x} is a structure or a structure array.
@xseealso{ismatrix, iscell, isa}
@end deftypefn
__fieldnames__
@c __fieldnames__ libinterp/octave-value/ov-struct.cc
@deftypefn  {} {} __fieldnames__ (@var{struct})
@deftypefnx {} {} __fieldnames__ (@var{obj})
Internal function.

Implements @code{fieldnames()} for structures and Octave objects.
@xseealso{fieldnames}
@end deftypefn
isfield
@c isfield libinterp/octave-value/ov-struct.cc
@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.
@xseealso{fieldnames}
@end deftypefn
numfields
@c numfields libinterp/octave-value/ov-struct.cc
@deftypefn {} {} numfields (@var{s})
Return the number of fields of the structure @var{s}.
@xseealso{fieldnames}
@end deftypefn
cell2struct
@c cell2struct libinterp/octave-value/ov-struct.cc
@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
@xseealso{struct2cell, cell2mat, struct}
@end deftypefn
rmfield
@c rmfield libinterp/octave-value/ov-struct.cc
@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.
@xseealso{orderfields, fieldnames, isfield}
@end deftypefn
struct_levels_to_print
@c struct_levels_to_print libinterp/octave-value/ov-struct.cc
@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.
@xseealso{print_struct_array_contents}
@end deftypefn
print_struct_array_contents
@c print_struct_array_contents libinterp/octave-value/ov-struct.cc
@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.
@xseealso{struct_levels_to_print}
@end deftypefn
typeinfo
@c typeinfo libinterp/octave-value/ov-typeinfo.cc
@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.
@xseealso{class, isa}
@end deftypefn
__dump_typeinfo__
@c __dump_typeinfo__ libinterp/octave-value/ov-typeinfo.cc
@deftypefn {} {} __dump_typeinfo__ ()
Undocumented internal function.
@end deftypefn
nargin
@c nargin libinterp/octave-value/ov-usr-fcn.cc
@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.
@xseealso{nargout, narginchk, varargin, inputname}
@end deftypefn
nargout
@c nargout libinterp/octave-value/ov-usr-fcn.cc
@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.
@xseealso{nargin, varargout, isargout, nthargout}
@end deftypefn
optimize_subsasgn_calls
@c optimize_subsasgn_calls libinterp/octave-value/ov-usr-fcn.cc
@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.
@xseealso{subsasgn}
@end deftypefn
isargout
@c isargout libinterp/octave-value/ov-usr-fcn.cc
@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.
@xseealso{nargout, varargout, nthargout}
@end deftypefn
double
@c double libinterp/octave-value/ov.cc
@deftypefn {} {} double (@var{x})
Convert @var{x} to double precision type.
@xseealso{single}
@end deftypefn
single
@c single libinterp/octave-value/ov.cc
@deftypefn {} {} single (@var{x})
Convert @var{x} to single precision type.
@xseealso{double}
@end deftypefn
int8
@c int8 libinterp/octave-value/ov.cc
@deftypefn {} {} int8 (@var{x})
Convert @var{x} to 8-bit integer type.
@xseealso{uint8, int16, uint16, int32, uint32, int64, uint64}
@end deftypefn
int16
@c int16 libinterp/octave-value/ov.cc
@deftypefn {} {} int16 (@var{x})
Convert @var{x} to 16-bit integer type.
@xseealso{int8, uint8, uint16, int32, uint32, int64, uint64}
@end deftypefn
int32
@c int32 libinterp/octave-value/ov.cc
@deftypefn {} {} int32 (@var{x})
Convert @var{x} to 32-bit integer type.
@xseealso{int8, uint8, int16, uint16, uint32, int64, uint64}
@end deftypefn
int64
@c int64 libinterp/octave-value/ov.cc
@deftypefn {} {} int64 (@var{x})
Convert @var{x} to 64-bit integer type.
@xseealso{int8, uint8, int16, uint16, int32, uint32, uint64}
@end deftypefn
uint8
@c uint8 libinterp/octave-value/ov.cc
@deftypefn {} {} uint8 (@var{x})
Convert @var{x} to unsigned 8-bit integer type.
@xseealso{int8, int16, uint16, int32, uint32, int64, uint64}
@end deftypefn
uint16
@c uint16 libinterp/octave-value/ov.cc
@deftypefn {} {} uint16 (@var{x})
Convert @var{x} to unsigned 16-bit integer type.
@xseealso{int8, uint8, int16, int32, uint32, int64, uint64}
@end deftypefn
uint32
@c uint32 libinterp/octave-value/ov.cc
@deftypefn {} {} uint32 (@var{x})
Convert @var{x} to unsigned 32-bit integer type.
@xseealso{int8, uint8, int16, uint16, int32, int64, uint64}
@end deftypefn
uint64
@c uint64 libinterp/octave-value/ov.cc
@deftypefn {} {} uint64 (@var{x})
Convert @var{x} to unsigned 64-bit integer type.
@xseealso{int8, uint8, int16, uint16, int32, uint32, int64}
@end deftypefn
sizeof
@c sizeof libinterp/octave-value/ov.cc
@deftypefn {} {} sizeof (@var{val})
Return the size of @var{val} in bytes.
@xseealso{whos}
@end deftypefn
subsref
@c subsref libinterp/octave-value/ov.cc
@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}.
@xseealso{subsasgn, substruct}
@end deftypefn
subsasgn
@c subsasgn libinterp/octave-value/ov.cc
@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}.
@xseealso{subsref, substruct, optimize_subsasgn_calls}
@end deftypefn
is_sq_string
@c is_sq_string libinterp/octave-value/ov.cc
@deftypefn {} {} is_sq_string (@var{x})
Return true if @var{x} is a single-quoted character string.
@xseealso{is_dq_string, ischar}
@end deftypefn
is_dq_string
@c is_dq_string libinterp/octave-value/ov.cc
@deftypefn {} {} is_dq_string (@var{x})
Return true if @var{x} is a double-quoted character string.
@xseealso{is_sq_string, ischar}
@end deftypefn
disable_permutation_matrix
@c disable_permutation_matrix libinterp/octave-value/ov.cc
@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.
@xseealso{disable_range, disable_diagonal_matrix}
@end deftypefn
disable_diagonal_matrix
@c disable_diagonal_matrix libinterp/octave-value/ov.cc
@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.
@xseealso{disable_range, disable_permutation_matrix}
@end deftypefn
disable_range
@c disable_range libinterp/octave-value/ov.cc
@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.
@xseealso{disable_diagonal_matrix, disable_permutation_matrix}
@end deftypefn
iskeyword
@c iskeyword libinterp/parse-tree/lex.ll
@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.
@xseealso{isvarname, exist}
@end deftypefn
autoload
@c autoload libinterp/parse-tree/oct-parse.yy
@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.

@xseealso{PKG_ADD}
@end deftypefn
mfilename
@c mfilename libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{inputname, dbstack}
@end deftypefn
source
@c source libinterp/parse-tree/oct-parse.yy
@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"}).
@xseealso{run}
@end deftypefn
feval
@c feval libinterp/parse-tree/oct-parse.yy
@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
@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
@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.
@xseealso{evalin, evalc, assignin, feval}
@end deftypefn
assignin
@c assignin libinterp/parse-tree/oct-parse.yy
@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"}.
@xseealso{evalin}
@end deftypefn
evalin
@c evalin libinterp/parse-tree/oct-parse.yy
@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"}.
@xseealso{eval, assignin}
@end deftypefn
evalc
@c evalc libinterp/parse-tree/oct-parse.yy
@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
@xseealso{eval, diary}
@end deftypefn
__parser_debug_flag__
@c __parser_debug_flag__ libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{__lexer_debug_flag__}
@end deftypefn
__parse_file__
@c __parse_file__ libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} __parse_file__ (@var{file}, @var{verbose})
Undocumented internal function.
@end deftypefn
__profiler_enable__
@c __profiler_enable__ libinterp/parse-tree/profiler.cc
@deftypefn {} {} __profiler_enable__ ()
Undocumented internal function.
@end deftypefn
__profiler_reset__
@c __profiler_reset__ libinterp/parse-tree/profiler.cc
@deftypefn {} {} __profiler_reset__ ()
Undocumented internal function.
@end deftypefn
__profiler_data__
@c __profiler_data__ libinterp/parse-tree/profiler.cc
@deftypefn {} {} __profiler_data__ ()
Undocumented internal function.
@end deftypefn
end
@c end libinterp/parse-tree/pt-eval.cc
@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
@xseealso{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
@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.

@xseealso{max_stack_depth}
@end deftypefn
whos_line_format
@c whos_line_format libinterp/parse-tree/pt-eval.cc
@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.
@xseealso{whos}
@end deftypefn
silent_functions
@c silent_functions libinterp/parse-tree/pt-eval.cc
@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
@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
@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.
@xseealso{echo, PS1, PS2}
@end deftypefn
echo
@c echo libinterp/parse-tree/pt-eval.cc
@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.

@xseealso{PS4}
@end deftypefn
jit_failcnt
@c jit_failcnt libinterp/parse-tree/pt-jit.cc
@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.
@xseealso{jit_enable, jit_startcnt, debug_jit}
@end deftypefn
debug_jit
@c debug_jit libinterp/parse-tree/pt-jit.cc
@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.
@xseealso{jit_enable, jit_startcnt}
@end deftypefn
jit_enable
@c jit_enable libinterp/parse-tree/pt-jit.cc
@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.
@xseealso{jit_startcnt, debug_jit}
@end deftypefn
jit_startcnt
@c jit_startcnt libinterp/parse-tree/pt-jit.cc
@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.
@xseealso{jit_enable, jit_failcnt, debug_jit}
@end deftypefn
__betainc__
@c __betainc__ libinterp/corefcn/__betainc__.cc
@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
@deftypefn {} {} __contourc__ (@var{x}, @var{y}, @var{z}, @var{levels})
Undocumented internal function.
@end deftypefn
__dsearchn__
@c __dsearchn__ libinterp/corefcn/__dsearchn__.cc
@deftypefn {} {[@var{idx}, @var{d}] =} dsearch (@var{x}, @var{xi})
Undocumented internal function.
@end deftypefn
__expint__
@c __expint__ libinterp/corefcn/__expint__.cc
@deftypefn {} {@var{y} =} __expint__ (@var{x})
Continued fraction expansion for the exponential integral.
@end deftypefn
__gammainc__
@c __gammainc__ libinterp/corefcn/__gammainc__.cc
@deftypefn {} {@var{y} =} __gammainc__ (@var{x}, @var{a})
Continued fraction for incomplete gamma function.
@end deftypefn
__ichol0__
@c __ichol0__ libinterp/corefcn/__ichol__.cc
@deftypefn {} {@var{L} =} __ichol0__ (@var{A}, @var{michol})
Undocumented internal function.
@end deftypefn
__icholt__
@c __icholt__ libinterp/corefcn/__ichol__.cc
@deftypefn {} {@var{L} =} __icholt__ (@var{A}, @var{droptol}, @var{michol})
Undocumented internal function.
@end deftypefn
__ilu0__
@c __ilu0__ libinterp/corefcn/__ilu__.cc
@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
@deftypefn {} {[@var{L}, @var{U}] =} __iluc__ (@var{A}, @var{droptol}, @var{milu})
Undocumented internal function.
@end deftypefn
__ilutp__
@c __ilutp__ libinterp/corefcn/__ilu__.cc
@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
@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
@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.

@xseealso{imfinfo, imformats, imread, imwrite}
@end deftypefn
__magick_write__
@c __magick_write__ libinterp/corefcn/__magick_read__.cc
@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.

@xseealso{imfinfo, imformats, imread, imwrite}
@end deftypefn
__magick_ping__
@c __magick_ping__ libinterp/corefcn/__magick_read__.cc
@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.

@xseealso{imfinfo}
@end deftypefn
__magick_finfo__
@c __magick_finfo__ libinterp/corefcn/__magick_read__.cc
@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.

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

@xseealso{imfinfo, imformats, imread, imwrite}
@end deftypefn
__pchip_deriv__
@c __pchip_deriv__ libinterp/corefcn/__pchip_deriv__.cc
@deftypefn {} {} __pchip_deriv__ (@var{x}, @var{y}, @var{dim})
Undocumented internal function.
@end deftypefn
__qp__
@c __qp__ libinterp/corefcn/__qp__.cc
@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
@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
@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

@xseealso{bessely, besseli, besselk, besselh}
@end deftypefn
bessely
@c bessely libinterp/corefcn/besselj.cc
@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

@xseealso{besselj, besseli, besselk, besselh}
@end deftypefn
besseli
@c besseli libinterp/corefcn/besselj.cc
@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

@xseealso{besselk, besselj, bessely, besselh}
@end deftypefn
besselk
@c besselk libinterp/corefcn/besselj.cc
@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

@xseealso{besseli, besselj, bessely, besselh}
@end deftypefn
besselh
@c besselh libinterp/corefcn/besselj.cc
@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

@xseealso{besselj, bessely, besseli, besselk}
@end deftypefn
airy
@c airy libinterp/corefcn/besselj.cc
@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
@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]
@xseealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax}
@end deftypefn
bitor
@c bitor libinterp/corefcn/bitfcns.cc
@deftypefn {} {} bitor (@var{x}, @var{y})
Return the bitwise OR of non-negative integers @var{x} and @var{y}.

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

@xseealso{bitand, bitor, bitset, bitget, bitcmp, bitshift, intmax, flintmax}
@end deftypefn
bitshift
@c bitshift libinterp/corefcn/bitfcns.cc
@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
@xseealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, intmax, flintmax}
@end deftypefn
flintmax
@c flintmax libinterp/corefcn/bitfcns.cc
@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

@xseealso{intmax, realmax, realmin}
@end deftypefn
intmax
@c intmax libinterp/corefcn/bitfcns.cc
@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

@xseealso{intmin, flintmax}
@end deftypefn
intmin
@c intmin libinterp/corefcn/bitfcns.cc
@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

@xseealso{intmax, flintmax}
@end deftypefn
sizemax
@c sizemax libinterp/corefcn/bitfcns.cc
@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}.
@xseealso{intmax}
@end deftypefn
bsxfun
@c bsxfun libinterp/corefcn/bsxfun.cc
@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.
@xseealso{arrayfun, cellfun}
@end deftypefn
max_stack_depth
@c max_stack_depth libinterp/corefcn/call-stack.cc
@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.

@xseealso{max_recursion_depth}
@end deftypefn
who
@c who libinterp/corefcn/call-stack.cc
@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.
@xseealso{whos, isglobal, isvarname, exist, regexp}
@end deftypefn
whos
@c whos libinterp/corefcn/call-stack.cc
@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.
@xseealso{who, whos_line_format}
@end deftypefn
cellfun
@c cellfun libinterp/corefcn/cellfun.cc
@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

@xseealso{arrayfun, structfun, spfun}
@end deftypefn
arrayfun
@c arrayfun libinterp/corefcn/cellfun.cc
@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

@xseealso{spfun, cellfun, structfun}
@end deftypefn
num2cell
@c num2cell libinterp/corefcn/cellfun.cc
@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

@xseealso{mat2cell}
@end deftypefn
mat2cell
@c mat2cell libinterp/corefcn/cellfun.cc
@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

@xseealso{num2cell, cell2mat}
@end deftypefn
cellslices
@c cellslices libinterp/corefcn/cellfun.cc
@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.
@xseealso{cell2mat, cellindexmat, cellfun}
@end deftypefn
cellindexmat
@c cellindexmat libinterp/corefcn/cellfun.cc
@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.
@xseealso{cellslices, cellfun}
@end deftypefn
colloc
@c colloc libinterp/corefcn/colloc.cc
@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
@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.
@xseealso{conv, convn}
@end deftypefn
convn
@c convn libinterp/corefcn/conv2.cc
@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

@xseealso{conv2, conv}
@end deftypefn
daspk
@c daspk libinterp/corefcn/daspk.cc
@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}.
@xseealso{dassl}
@end deftypefn
dasrt
@c dasrt libinterp/corefcn/dasrt.cc
@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}.
@xseealso{dasrt_options, daspk, dasrt, lsode}
@end deftypefn
dassl
@c dassl libinterp/corefcn/dassl.cc
@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}.
@xseealso{daspk, dasrt, lsode}
@end deftypefn
all
@c all libinterp/corefcn/data.cc
@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}.
@xseealso{any}
@end deftypefn
any
@c any libinterp/corefcn/data.cc
@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
@xseealso{all}
@end deftypefn
atan2
@c atan2 libinterp/corefcn/data.cc
@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}))}.
@xseealso{tan, tand, tanh, atanh}
@end deftypefn
hypot
@c hypot libinterp/corefcn/data.cc
@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
@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
@xseealso{pow2, log, log10, exp}
@end deftypefn
rem
@c rem libinterp/corefcn/data.cc
@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.
@xseealso{mod}
@end deftypefn
mod
@c mod libinterp/corefcn/data.cc
@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.
@xseealso{rem}
@end deftypefn
cumprod
@c cumprod libinterp/corefcn/data.cc
@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
@xseealso{prod, cumsum}
@end deftypefn
cumsum
@c cumsum libinterp/corefcn/data.cc
@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"}.
@xseealso{sum, cumprod}
@end deftypefn
diag
@c diag libinterp/corefcn/data.cc
@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
@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.
@xseealso{cumprod, sum}
@end deftypefn
horzcat
@c horzcat libinterp/corefcn/data.cc
@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
@xseealso{cat, vertcat}
@end deftypefn
vertcat
@c vertcat libinterp/corefcn/data.cc
@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
@xseealso{cat, horzcat}
@end deftypefn
cat
@c cat libinterp/corefcn/data.cc
@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
@xseealso{horzcat, vertcat}
@end deftypefn
permute
@c permute libinterp/corefcn/data.cc
@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
@xseealso{ipermute}
@end deftypefn
ipermute
@c ipermute libinterp/corefcn/data.cc
@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}.
@xseealso{permute}
@end deftypefn
length
@c length libinterp/corefcn/data.cc
@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}))}}).
@xseealso{numel, size}
@end deftypefn
ndims
@c ndims libinterp/corefcn/data.cc
@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
@xseealso{size}
@end deftypefn
numel
@c numel libinterp/corefcn/data.cc
@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}.
@xseealso{size, length, ndims}
@end deftypefn
size
@c size libinterp/corefcn/data.cc
@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

@xseealso{numel, ndims, length, rows, columns, size_equal, common_size}
@end deftypefn
size_equal
@c size_equal libinterp/corefcn/data.cc
@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.
@xseealso{size, numel, ndims, common_size}
@end deftypefn
nnz
@c nnz libinterp/corefcn/data.cc
@deftypefn {} {@var{n} =} nnz (@var{a})
Return the number of nonzero elements in @var{a}.
@xseealso{nzmax, nonzeros, find}
@end deftypefn
nzmax
@c nzmax libinterp/corefcn/data.cc
@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.
@xseealso{nnz, spalloc, sparse}
@end deftypefn
rows
@c rows libinterp/corefcn/data.cc
@deftypefn {} {} rows (@var{a})
Return the number of rows of @var{a}.  This is equivalent to
@code{size (@var{a}, 1)}.
@xseealso{columns, size, length, numel, isscalar, isvector, ismatrix}
@end deftypefn
columns
@c columns libinterp/corefcn/data.cc
@deftypefn {} {} columns (@var{a})
Return the number of columns of @var{a}.  This is equivalent to
@code{size (@var{a}, 2)}.
@xseealso{rows, size, length, numel, isscalar, isvector, ismatrix}
@end deftypefn
sum
@c sum libinterp/corefcn/data.cc
@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.
@xseealso{cumsum, sumsq, prod}
@end deftypefn
sumsq
@c sumsq libinterp/corefcn/data.cc
@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.
@xseealso{sum, prod}
@end deftypefn
islogical
@c islogical libinterp/corefcn/data.cc
@deftypefn  {} {} islogical (@var{x})
@deftypefnx {} {} isbool (@var{x})
Return true if @var{x} is a logical object.
@xseealso{ischar, isfloat, isinteger, isstring, isnumeric, isa}
@end deftypefn
isinteger
@c isinteger libinterp/corefcn/data.cc
@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.
@xseealso{isfloat, ischar, islogical, isstring, isnumeric, isa}
@end deftypefn
iscomplex
@c iscomplex libinterp/corefcn/data.cc
@deftypefn {} {} iscomplex (@var{x})
Return true if @var{x} is a complex-valued numeric object.
@xseealso{isreal, isnumeric, ischar, isfloat, islogical, isstring, isa}
@end deftypefn
isfloat
@c isfloat libinterp/corefcn/data.cc
@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.
@xseealso{isinteger, ischar, islogical, isnumeric, isstring, isa}
@end deftypefn
complex
@c complex libinterp/corefcn/data.cc
@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
@xseealso{real, imag, iscomplex, abs, arg}
@end deftypefn
isreal
@c isreal libinterp/corefcn/data.cc
@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.
@xseealso{iscomplex, isnumeric, isa}
@end deftypefn
isempty
@c isempty libinterp/corefcn/data.cc
@deftypefn {} {} isempty (@var{a})
Return true if @var{a} is an empty matrix (any one of its dimensions is
zero).
@xseealso{isnull, isa}
@end deftypefn
isnumeric
@c isnumeric libinterp/corefcn/data.cc
@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.
@xseealso{isinteger, isfloat, isreal, iscomplex, ischar, islogical, isstring, iscell, isstruct, isa}
@end deftypefn
isscalar
@c isscalar libinterp/corefcn/data.cc
@deftypefn {} {} isscalar (@var{x})
Return true if @var{x} is a scalar, i.e., @code{size (@var{x})} returns
@code{[1 1]}.
@xseealso{isvector, ismatrix}
@end deftypefn
isvector
@c isvector libinterp/corefcn/data.cc
@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.
@xseealso{isscalar, ismatrix, size, rows, columns, length}
@end deftypefn
isrow
@c isrow libinterp/corefcn/data.cc
@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.
@xseealso{iscolumn, isscalar, isvector, ismatrix}
@end deftypefn
iscolumn
@c iscolumn libinterp/corefcn/data.cc
@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.
@xseealso{isrow, isscalar, isvector, ismatrix}
@end deftypefn
ismatrix
@c ismatrix libinterp/corefcn/data.cc
@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.
@xseealso{isscalar, isvector, iscell, isstruct, issparse, isa}
@end deftypefn
issquare
@c issquare libinterp/corefcn/data.cc
@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.
@xseealso{isscalar, isvector, ismatrix, size}
@end deftypefn
ones
@c ones libinterp/corefcn/data.cc
@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
@xseealso{zeros}
@end deftypefn
zeros
@c zeros libinterp/corefcn/data.cc
@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
@xseealso{ones}
@end deftypefn
Inf
@c Inf libinterp/corefcn/data.cc
@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"}.
@xseealso{isinf, NaN}
@end deftypefn
NaN
@c NaN libinterp/corefcn/data.cc
@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"}.
@xseealso{isnan, Inf}
@end deftypefn
e
@c e libinterp/corefcn/data.cc
@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"}.
@xseealso{log, exp, pi, I}
@end deftypefn
eps
@c eps libinterp/corefcn/data.cc
@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"}.
@xseealso{realmax, realmin, intmax, flintmax}
@end deftypefn
pi
@c pi libinterp/corefcn/data.cc
@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"}.
@xseealso{e, I}
@end deftypefn
realmax
@c realmax libinterp/corefcn/data.cc
@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"}.
@xseealso{realmin, intmax, flintmax, eps}
@end deftypefn
realmin
@c realmin libinterp/corefcn/data.cc
@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"}.
@xseealso{realmax, intmin, eps}
@end deftypefn
I
@c I libinterp/corefcn/data.cc
@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"}.
@xseealso{e, pi, log, exp}
@end deftypefn
NA
@c NA libinterp/corefcn/data.cc
@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"}.
@xseealso{isna}
@end deftypefn
false
@c false libinterp/corefcn/data.cc
@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.
@xseealso{true}
@end deftypefn
true
@c true libinterp/corefcn/data.cc
@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.
@xseealso{false}
@end deftypefn
eye
@c eye libinterp/corefcn/data.cc
@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}.
@xseealso{speye, ones, zeros}
@end deftypefn
linspace
@c linspace libinterp/corefcn/data.cc
@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.
@xseealso{colon, logspace}
@end deftypefn
resize
@c resize libinterp/corefcn/data.cc
@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.
@xseealso{reshape, postpad, prepad, cat}
@end deftypefn
reshape
@c reshape libinterp/corefcn/data.cc
@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.
@xseealso{resize, vec, postpad, cat, squeeze}
@end deftypefn
vec
@c vec libinterp/corefcn/data.cc
@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})}.
@xseealso{vech, resize, cat}
@end deftypefn
squeeze
@c squeeze libinterp/corefcn/data.cc
@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.
@xseealso{reshape}
@end deftypefn
full
@c full libinterp/corefcn/data.cc
@deftypefn {} {@var{FM} =} full (@var{SM})
Return a full storage matrix from a sparse, diagonal, or permutation matrix,
or a range.
@xseealso{sparse, issparse}
@end deftypefn
norm
@c norm libinterp/corefcn/data.cc
@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.
@xseealso{normest, normest1, vecnorm, cond, svd}
@end deftypefn
not
@c not libinterp/corefcn/data.cc
@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}}}.
@xseealso{and, or, xor}
@end deftypefn
uplus
@c uplus libinterp/corefcn/data.cc
@deftypefn {} {} uplus (@var{x})
This function and @w{@tcode{+ @var{x}}} are equivalent.
@xseealso{uminus, plus, minus}
@end deftypefn
uminus
@c uminus libinterp/corefcn/data.cc
@deftypefn {} {} uminus (@var{x})
This function and @w{@tcode{- @var{x}}} are equivalent.
@xseealso{uplus, minus}
@end deftypefn
transpose
@c transpose libinterp/corefcn/data.cc
@deftypefn {} {} transpose (@var{x})
Return the transpose of @var{x}.

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

This function and @tcode{@var{x}'} are equivalent.
@xseealso{transpose}
@end deftypefn
plus
@c plus libinterp/corefcn/data.cc
@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

@xseealso{minus, uplus}
@end deftypefn
minus
@c minus libinterp/corefcn/data.cc
@deftypefn {} {} minus (@var{x}, @var{y})
This function and @w{@tcode{@var{x} - @var{y}}} are equivalent.
@xseealso{plus, uminus}
@end deftypefn
mtimes
@c mtimes libinterp/corefcn/data.cc
@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

@xseealso{times, plus, minus, rdivide, mrdivide, mldivide, mpower}
@end deftypefn
mrdivide
@c mrdivide libinterp/corefcn/data.cc
@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.
@xseealso{mldivide, rdivide, plus, minus}
@end deftypefn
mpower
@c mpower libinterp/corefcn/data.cc
@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.
@xseealso{power, mtimes, plus, minus}
@end deftypefn
mldivide
@c mldivide libinterp/corefcn/data.cc
@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.
@xseealso{mrdivide, ldivide, rdivide}
@end deftypefn
lt
@c lt libinterp/corefcn/data.cc
@deftypefn {} {} lt (@var{x}, @var{y})
This function is equivalent to @w{@code{@var{x} < @var{y}}}.
@xseealso{le, eq, ge, gt, ne}
@end deftypefn
le
@c le libinterp/corefcn/data.cc
@deftypefn {} {} le (@var{x}, @var{y})
This function is equivalent to @w{@code{@var{x} <= @var{y}}}.
@xseealso{eq, ge, gt, ne, lt}
@end deftypefn
eq
@c eq libinterp/corefcn/data.cc
@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}}}.
@xseealso{ne, isequal, le, ge, gt, ne, lt}
@end deftypefn
ge
@c ge libinterp/corefcn/data.cc
@deftypefn {} {} ge (@var{x}, @var{y})
This function is equivalent to @w{@code{@var{x} >= @var{y}}}.
@xseealso{le, eq, gt, ne, lt}
@end deftypefn
gt
@c gt libinterp/corefcn/data.cc
@deftypefn {} {} gt (@var{x}, @var{y})
This function is equivalent to @w{@code{@var{x} > @var{y}}}.
@xseealso{le, eq, ge, ne, lt}
@end deftypefn
ne
@c ne libinterp/corefcn/data.cc
@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}}}.
@xseealso{eq, isequal, le, ge, lt}
@end deftypefn
times
@c times libinterp/corefcn/data.cc
@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

@xseealso{mtimes, rdivide}
@end deftypefn
rdivide
@c rdivide libinterp/corefcn/data.cc
@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.
@xseealso{ldivide, mrdivide, times, plus}
@end deftypefn
power
@c power libinterp/corefcn/data.cc
@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.

@xseealso{mpower, realpow, realsqrt, cbrt, nthroot}
@end deftypefn
ldivide
@c ldivide libinterp/corefcn/data.cc
@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.
@xseealso{rdivide, mldivide, times, plus}
@end deftypefn
and
@c and libinterp/corefcn/data.cc
@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

@xseealso{or, not, xor}
@end deftypefn
or
@c or libinterp/corefcn/data.cc
@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

@xseealso{and, not, xor}
@end deftypefn
colon
@c colon libinterp/corefcn/data.cc
@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}}}.
@xseealso{linspace}
@end deftypefn
tic
@c tic libinterp/corefcn/data.cc
@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.
@xseealso{toc, cputime}
@end deftypefn
toc
@c toc libinterp/corefcn/data.cc
@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}.

@xseealso{tic, cputime}
@end deftypefn
cputime
@c cputime libinterp/corefcn/data.cc
@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.
@xseealso{tic, toc}
@end deftypefn
sort
@c sort libinterp/corefcn/data.cc
@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.
@xseealso{sortrows, issorted}
@end deftypefn
__sort_rows_idx__
@c __sort_rows_idx__ libinterp/corefcn/data.cc
@deftypefn {} {} __sort_rows_idx__ (@var{a}, @var{mode})
Undocumented internal function.
@end deftypefn
issorted
@c issorted libinterp/corefcn/data.cc
@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.
@xseealso{sort, sortrows}
@end deftypefn
nth_element
@c nth_element libinterp/corefcn/data.cc
@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}.
@xseealso{sort, min, max}
@end deftypefn
__accumarray_sum__
@c __accumarray_sum__ libinterp/corefcn/data.cc
@deftypefn {} {} __accumarray_sum__ (@var{idx}, @var{vals}, @var{n})
Undocumented internal function.
@end deftypefn
__accumarray_min__
@c __accumarray_min__ libinterp/corefcn/data.cc
@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
@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
@deftypefn {} {} __accumdim_sum__ (@var{idx}, @var{vals}, @var{dim}, @var{n})
Undocumented internal function.
@end deftypefn
merge
@c merge libinterp/corefcn/data.cc
@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.
@xseealso{logical, diff}
@end deftypefn
diff
@c diff libinterp/corefcn/data.cc
@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.
@xseealso{sort, merge}
@end deftypefn
repelems
@c repelems libinterp/corefcn/data.cc
@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
@xseealso{repmat, cat}
@end deftypefn
base64_encode
@c base64_encode libinterp/corefcn/data.cc
@deftypefn {} {@var{s} =} base64_encode (@var{x})
Encode a double matrix or array @var{x} into the base64 format string
@var{s}.

@xseealso{base64_decode}
@end deftypefn
base64_decode
@c base64_decode libinterp/corefcn/data.cc
@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.
@xseealso{base64_encode}
@end deftypefn
dbstop
@c dbstop libinterp/corefcn/debug.cc
@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.

@xseealso{dbclear, dbstatus, dbstep, debug_on_error, debug_on_warning, debug_on_interrupt}
@end deftypefn
dbclear
@c dbclear libinterp/corefcn/debug.cc
@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.
@xseealso{dbstop, dbstatus, dbwhere}
@end deftypefn
dbstatus
@c dbstatus libinterp/corefcn/debug.cc
@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}.

@xseealso{dbstop, dbclear, dbwhere, dblist, dbstack}
@end deftypefn
dbwhere
@c dbwhere libinterp/corefcn/debug.cc
@deftypefn {} {} dbwhere
In debugging mode, report the current file and line number where execution
is stopped.
@xseealso{dbstack, dblist, dbstatus, dbcont, dbstep, dbup, dbdown}
@end deftypefn
dbtype
@c dbtype libinterp/corefcn/debug.cc
@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.
@xseealso{dblist, dbwhere, dbstatus, dbstop}
@end deftypefn
dblist
@c dblist libinterp/corefcn/debug.cc
@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)
@xseealso{dbwhere, dbtype, dbstack}
@end deftypefn
dbstack
@c dbstack libinterp/corefcn/debug.cc
@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.
@xseealso{dbup, dbdown, dbwhere, dblist, dbstatus}
@end deftypefn
dbup
@c dbup libinterp/corefcn/debug.cc
@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.
@xseealso{dbstack, dbdown}
@end deftypefn
dbdown
@c dbdown libinterp/corefcn/debug.cc
@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.
@xseealso{dbstack, dbup}
@end deftypefn
dbstep
@c dbstep libinterp/corefcn/debug.cc
@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}.
@xseealso{dbcont, dbquit}
@end deftypefn
dbcont
@c dbcont libinterp/corefcn/debug.cc
@deftypefn {} {} dbcont
Leave command-line debugging mode and continue code execution normally.
@xseealso{dbstep, dbquit}
@end deftypefn
dbquit
@c dbquit libinterp/corefcn/debug.cc
@deftypefn {} {} dbquit
Quit debugging mode immediately without further code execution and return to
the Octave prompt.
@xseealso{dbcont, dbstep}
@end deftypefn
isdebugmode
@c isdebugmode libinterp/corefcn/debug.cc
@deftypefn {} {} isdebugmode ()
Return true if in debugging mode, otherwise false.
@xseealso{dbwhere, dbstack, dbstatus}
@end deftypefn
__db_next_breakpoint_quiet__
@c __db_next_breakpoint_quiet__ libinterp/corefcn/debug.cc
@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
@deftypefn {} {} OCTAVE_HOME ()
Return the name of the top-level Octave installation directory.
OCTAVE_HOME corresponds to the configuration variable @var{prefix}.
@xseealso{EXEC_PATH, IMAGE_PATH, OCTAVE_EXEC_HOME}
@end deftypefn
OCTAVE_EXEC_HOME
@c OCTAVE_EXEC_HOME libinterp/corefcn/defaults.cc
@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}.
@xseealso{EXEC_PATH, IMAGE_PATH, OCTAVE_HOME}
@end deftypefn
OCTAVE_VERSION
@c OCTAVE_VERSION libinterp/corefcn/defaults.cc
@deftypefn {} {} OCTAVE_VERSION ()
Return the version number of Octave as a string.
@xseealso{ver, version}
@end deftypefn
det
@c det libinterp/corefcn/det.cc
@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}.
@xseealso{cond, condest, rcond}
@end deftypefn
cd
@c cd libinterp/corefcn/dirfns.cc
@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.
@xseealso{pwd, mkdir, rmdir, dir, ls}
@end deftypefn
pwd
@c pwd libinterp/corefcn/dirfns.cc
@deftypefn  {} {} pwd ()
@deftypefnx {} {@var{dir} =} pwd ()
Return the current working directory.
@xseealso{cd, dir, ls, mkdir, rmdir}
@end deftypefn
readdir
@c readdir libinterp/corefcn/dirfns.cc
@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.
@xseealso{ls, dir, glob, what}
@end deftypefn
__mkdir__
@c __mkdir__ libinterp/corefcn/dirfns.cc
@deftypefn {} {} __mkdir__ (@var{parent}, @var{dir})
Internal function called by mkdir.m.
@xseealso{mkdir, rmdir, pwd, cd, umask}
@end deftypefn
rmdir
@c rmdir libinterp/corefcn/dirfns.cc
@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.

@xseealso{mkdir, confirm_recursive_rmdir, pwd}
@end deftypefn
link
@c link libinterp/corefcn/dirfns.cc
@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.
@xseealso{symlink, unlink, readlink, lstat}
@end deftypefn
symlink
@c symlink libinterp/corefcn/dirfns.cc
@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.
@xseealso{link, unlink, readlink, lstat}
@end deftypefn
readlink
@c readlink libinterp/corefcn/dirfns.cc
@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.
@xseealso{lstat, symlink, link, unlink, delete}
@end deftypefn
rename
@c rename libinterp/corefcn/dirfns.cc
@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.
@xseealso{movefile, copyfile, ls, dir}
@end deftypefn
glob
@c glob libinterp/corefcn/dirfns.cc
@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
@xseealso{ls, dir, readdir, what}
@end deftypefn
__wglob__
@c __wglob__ libinterp/corefcn/dirfns.cc
@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
@xseealso{glob, dir}
@end deftypefn
__fnmatch__
@c __fnmatch__ libinterp/corefcn/dirfns.cc
@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
@xseealso{glob, regexp}
@end deftypefn
filesep
@c filesep libinterp/corefcn/dirfns.cc
@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.
@xseealso{pathsep}
@end deftypefn
pathsep
@c pathsep libinterp/corefcn/dirfns.cc
@deftypefn {} {@var{val} =} pathsep ()
Query the character used to separate directories in a path.
@xseealso{filesep}
@end deftypefn
confirm_recursive_rmdir
@c confirm_recursive_rmdir libinterp/corefcn/dirfns.cc
@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.
@xseealso{rmdir}
@end deftypefn
have_window_system
@c have_window_system libinterp/corefcn/display.cc
@deftypefn {} {} have_window_system ()
Return true if a window system is available (X11, Windows, or Apple OS X)
and false otherwise.
@xseealso{isguirunning}
@end deftypefn
dlmread
@c dlmread libinterp/corefcn/dlmread.cc
@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"}.
@xseealso{csvread, textscan, dlmwrite}
@end deftypefn
dot
@c dot libinterp/corefcn/dot.cc
@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}}.
@xseealso{cross, divergence}
@end deftypefn
blkmm
@c blkmm libinterp/corefcn/dot.cc
@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
@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.
@xseealso{eigs, svd}
@end deftypefn
ellipj
@c ellipj libinterp/corefcn/ellipj.cc
@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.

@xseealso{ellipke}
@end deftypefn
EDITOR
@c EDITOR libinterp/corefcn/environment.cc
@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.

@xseealso{edit, edit_history}
@end deftypefn
EXEC_PATH
@c EXEC_PATH libinterp/corefcn/environment.cc
@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.

@xseealso{IMAGE_PATH, OCTAVE_HOME, OCTAVE_EXEC_HOME}
@end deftypefn
IMAGE_PATH
@c IMAGE_PATH libinterp/corefcn/environment.cc
@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.

@xseealso{EXEC_PATH, OCTAVE_HOME, OCTAVE_EXEC_HOME}
@end deftypefn
rethrow
@c rethrow libinterp/corefcn/error.cc
@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}.
@xseealso{lasterror, lasterr, error}
@end deftypefn
error
@c error libinterp/corefcn/error.cc
@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.
@xseealso{warning, lasterror}
@end deftypefn
warning
@c warning libinterp/corefcn/error.cc
@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.
@xseealso{warning_ids, lastwarn, error}
@end deftypefn
lasterror
@c lasterror libinterp/corefcn/error.cc
@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.
@xseealso{lasterr, error, lastwarn}
@end deftypefn
lasterr
@c lasterr libinterp/corefcn/error.cc
@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.
@xseealso{lasterror, error, lastwarn}
@end deftypefn
lastwarn
@c lastwarn libinterp/corefcn/error.cc
@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.
@xseealso{warning, lasterror, lasterr}
@end deftypefn
beep_on_error
@c beep_on_error libinterp/corefcn/error.cc
@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
@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.
@xseealso{debug_on_warning, debug_on_interrupt}
@end deftypefn
debug_on_warning
@c debug_on_warning libinterp/corefcn/error.cc
@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.
@xseealso{debug_on_error, debug_on_interrupt}
@end deftypefn
fft
@c fft libinterp/corefcn/fft.cc
@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.
@xseealso{ifft, fft2, fftn, fftw}
@end deftypefn
ifft
@c ifft libinterp/corefcn/fft.cc
@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.
@xseealso{fft, ifft2, ifftn, fftw}
@end deftypefn
fft2
@c fft2 libinterp/corefcn/fft2.cc
@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.
@xseealso{ifft2, fft, fftn, fftw}
@end deftypefn
ifft2
@c ifft2 libinterp/corefcn/fft2.cc
@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.
@xseealso{fft2, ifft, ifftn, fftw}
@end deftypefn
fftn
@c fftn libinterp/corefcn/fftn.cc
@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.
@xseealso{ifftn, fft, fft2, fftw}
@end deftypefn
ifftn
@c ifftn libinterp/corefcn/fftn.cc
@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.
@xseealso{fftn, ifft, ifft2, fftw}
@end deftypefn
fclose
@c fclose libinterp/corefcn/file-io.cc
@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.
@xseealso{fopen, fflush, freport}
@end deftypefn
fclear
@c fclear libinterp/corefcn/file-io.cc
@deftypefn {} {} fclear (@var{fid})
Clear the stream state for the file specified by the file descriptor
@var{fid}.
@xseealso{ferror, fopen}
@end deftypefn
fflush
@c fflush libinterp/corefcn/file-io.cc
@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}.
@xseealso{fopen, fclose}
@end deftypefn
fgetl
@c fgetl libinterp/corefcn/file-io.cc
@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}.
@xseealso{fgets, fscanf, fread, fopen}
@end deftypefn
fgets
@c fgets libinterp/corefcn/file-io.cc
@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}.
@xseealso{fputs, fgetl, fscanf, fread, fopen}
@end deftypefn
fskipl
@c fskipl libinterp/corefcn/file-io.cc
@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).
@xseealso{fgetl, fgets, fscanf, fopen}
@end deftypefn
fopen
@c fopen libinterp/corefcn/file-io.cc
@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.
@xseealso{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
@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
@xseealso{fopen, fclose, is_valid_file_id}
@end deftypefn
frewind
@c frewind libinterp/corefcn/file-io.cc
@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)}.
@xseealso{fseek, ftell, fopen}
@end deftypefn
fseek
@c fseek libinterp/corefcn/file-io.cc
@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.
@xseealso{fskipl, frewind, ftell, fopen, SEEK_SET, SEEK_CUR, SEEK_END}
@end deftypefn
ftell
@c ftell libinterp/corefcn/file-io.cc
@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}.
@xseealso{fseek, frewind, feof, fopen}
@end deftypefn
fprintf
@c fprintf libinterp/corefcn/file-io.cc
@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.
@xseealso{fputs, fdisp, fwrite, fscanf, printf, sprintf, fopen}
@end deftypefn
printf
@c printf libinterp/corefcn/file-io.cc
@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.
@xseealso{fprintf, sprintf, scanf}
@end deftypefn
fputs
@c fputs libinterp/corefcn/file-io.cc
@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.
@xseealso{fdisp, fprintf, fwrite, fopen}
@end deftypefn
puts
@c puts libinterp/corefcn/file-io.cc
@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.
@xseealso{fputs, disp}
@end deftypefn
sprintf
@c sprintf libinterp/corefcn/file-io.cc
@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.
@xseealso{printf, fprintf, sscanf}
@end deftypefn
fscanf
@c fscanf libinterp/corefcn/file-io.cc
@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
@xseealso{fgets, fgetl, fread, scanf, sscanf, fopen}
@end deftypefn
sscanf
@c sscanf libinterp/corefcn/file-io.cc
@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}.
@xseealso{fscanf, scanf, sprintf}
@end deftypefn
scanf
@c scanf libinterp/corefcn/file-io.cc
@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.
@xseealso{fscanf, sscanf, printf}
@end deftypefn
textscan
@c textscan libinterp/corefcn/file-io.cc
@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 empty 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.

@xseealso{dlmread, fscanf, load, strread, textread}
@end deftypefn
__textscan__
@c __textscan__ libinterp/corefcn/file-io.cc
@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
@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.
@xseealso{fwrite, fgets, fgetl, fscanf, fopen}
@end deftypefn
fwrite
@c fwrite libinterp/corefcn/file-io.cc
@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.
@xseealso{fread, fputs, fprintf, fopen}
@end deftypefn
feof
@c feof libinterp/corefcn/file-io.cc
@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.
@xseealso{fread, frewind, fseek, fclear, fopen}
@end deftypefn
ferror
@c ferror libinterp/corefcn/file-io.cc
@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.
@xseealso{fclear, fopen}
@end deftypefn
popen
@c popen libinterp/corefcn/file-io.cc
@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
@xseealso{popen2}
@end deftypefn
pclose
@c pclose libinterp/corefcn/file-io.cc
@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.
@xseealso{fclose, popen}
@end deftypefn
tempname
@c tempname libinterp/corefcn/file-io.cc
@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}.
@xseealso{mkstemp, tempdir, P_tmpdir, tmpfile}
@end deftypefn
tmpfile
@c tmpfile libinterp/corefcn/file-io.cc
@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.
@xseealso{tempname, mkstemp, tempdir, P_tmpdir}
@end deftypefn
mkstemp
@c mkstemp libinterp/corefcn/file-io.cc
@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.
@xseealso{tempname, tempdir, P_tmpdir, tmpfile, fopen}
@end deftypefn
umask
@c umask libinterp/corefcn/file-io.cc
@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}}.
@xseealso{fopen, mkdir, mkfifo}
@end deftypefn
P_tmpdir
@c P_tmpdir libinterp/corefcn/file-io.cc
@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.
@xseealso{tempdir, tempname, mkstemp, tmpfile}
@end deftypefn
SEEK_SET
@c SEEK_SET libinterp/corefcn/file-io.cc
@deftypefn {} {} SEEK_SET ()
Return the numerical value to pass to @code{fseek} to position the file pointer
relative to the beginning of the file.
@xseealso{SEEK_CUR, SEEK_END, fseek}
@end deftypefn
SEEK_CUR
@c SEEK_CUR libinterp/corefcn/file-io.cc
@deftypefn {} {} SEEK_CUR ()
Return the numerical value to pass to @code{fseek} to position the file pointer
relative to the current position.
@xseealso{SEEK_SET, SEEK_END, fseek}
@end deftypefn
SEEK_END
@c SEEK_END libinterp/corefcn/file-io.cc
@deftypefn {} {} SEEK_END ()
Return the numerical value to pass to @code{fseek} to position the file pointer
relative to the end of the file.
@xseealso{SEEK_SET, SEEK_CUR, fseek}
@end deftypefn
stdin
@c stdin libinterp/corefcn/file-io.cc
@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.
@xseealso{stdout, stderr}
@end deftypefn
stdout
@c stdout libinterp/corefcn/file-io.cc
@deftypefn {} {} stdout ()
Return the numeric value corresponding to the standard output stream.

Data written to the standard output may be filtered through the pager.
@xseealso{stdin, stderr, page_screen_output}
@end deftypefn
stderr
@c stderr libinterp/corefcn/file-io.cc
@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.
@xseealso{stdin, stdout}
@end deftypefn
filter
@c filter libinterp/corefcn/filter.cc
@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
@xseealso{filter2, fftfilt, freqz}
@end deftypefn
find
@c find libinterp/corefcn/find.cc
@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
@xseealso{nonzeros}
@end deftypefn
gcd
@c gcd libinterp/corefcn/gcd.cc
@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

@xseealso{lcm, factor, isprime}
@end deftypefn
getgrent
@c getgrent libinterp/corefcn/getgrent.cc
@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.
@xseealso{setgrent, endgrent}
@end deftypefn
getgrgid
@c getgrgid libinterp/corefcn/getgrent.cc
@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.
@xseealso{getgrnam}
@end deftypefn
getgrnam
@c getgrnam libinterp/corefcn/getgrent.cc
@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.
@xseealso{getgrgid}
@end deftypefn
setgrent
@c setgrent libinterp/corefcn/getgrent.cc
@deftypefn {} {} setgrent ()
Return the internal pointer to the beginning of the group database.
@xseealso{getgrent, endgrent}
@end deftypefn
endgrent
@c endgrent libinterp/corefcn/getgrent.cc
@deftypefn {} {} endgrent ()
Close the group database.
@xseealso{getgrent, setgrent}
@end deftypefn
getpwent
@c getpwent libinterp/corefcn/getpwent.cc
@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.
@xseealso{setpwent, endpwent}
@end deftypefn
getpwuid
@c getpwuid libinterp/corefcn/getpwent.cc
@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.
@xseealso{getpwnam}
@end deftypefn
getpwnam
@c getpwnam libinterp/corefcn/getpwent.cc
@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.
@xseealso{getpwuid}
@end deftypefn
setpwent
@c setpwent libinterp/corefcn/getpwent.cc
@deftypefn {} {} setpwent ()
Return the internal pointer to the beginning of the password database.
@xseealso{getpwent, endpwent}
@end deftypefn
endpwent
@c endpwent libinterp/corefcn/getpwent.cc
@deftypefn {} {} endpwent ()
Close the password database.
@xseealso{getpwent, setpwent}
@end deftypefn
getrusage
@c getrusage libinterp/corefcn/getrusage.cc
@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
@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.
@xseealso{planerot, qr}
@end deftypefn
__update_normals__
@c __update_normals__ libinterp/corefcn/graphics.cc
@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
@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.
@xseealso{isgraphics, isaxes, isfigure, ishandle}
@end deftypefn
__is_handle_visible__
@c __is_handle_visible__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __is_handle_visible__ (@var{h})
Undocumented internal function.
@end deftypefn
reset
@c reset libinterp/corefcn/graphics.cc
@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.
@xseealso{cla, clf, newplot}
@end deftypefn
set
@c set libinterp/corefcn/graphics.cc
@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"}.
@xseealso{get}
@end deftypefn
get
@c get libinterp/corefcn/graphics.cc
@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.
@xseealso{set}
@end deftypefn
__get__
@c __get__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __get__ (@var{h})
Undocumented internal function.
@end deftypefn
__go_figure__
@c __go_figure__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_figure__ (@var{fignum})
Undocumented internal function.
@end deftypefn
__calc_dimensions__
@c __calc_dimensions__ libinterp/corefcn/graphics.cc
@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
@deftypefn {} {} __go_axes__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_line__
@c __go_line__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_line__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_text__
@c __go_text__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_text__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_image__
@c __go_image__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_image__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_surface__
@c __go_surface__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_surface__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_patch__
@c __go_patch__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_patch__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_light__
@c __go_light__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_light__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_hggroup__
@c __go_hggroup__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_hggroup__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uimenu__
@c __go_uimenu__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_uimenu__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uicontrol__
@c __go_uicontrol__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_uicontrol__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uibuttongroup__
@c __go_uibuttongroup__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_uibuttongroup__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uipanel__
@c __go_uipanel__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_uipanel__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uicontextmenu__
@c __go_uicontextmenu__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_uicontextmenu__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uitable__
@c __go_uitable__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_uitable__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uitoolbar__
@c __go_uitoolbar__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_uitoolbar__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uipushtool__
@c __go_uipushtool__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_uipushtool__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_uitoggletool__
@c __go_uitoggletool__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_uitoggletool__ (@var{parent})
Undocumented internal function.
@end deftypefn
__go_delete__
@c __go_delete__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_delete__ (@var{h})
Undocumented internal function.
@end deftypefn
__go_handles__
@c __go_handles__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_handles__ (@var{show_hidden})
Undocumented internal function.
@end deftypefn
__go_figure_handles__
@c __go_figure_handles__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __go_figure_handles__ (@var{show_hidden})
Undocumented internal function.
@end deftypefn
__go_execute_callback__
@c __go_execute_callback__ libinterp/corefcn/graphics.cc
@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
@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
@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
@deftypefn {} {} available_graphics_toolkits ()
Return a cell array of registered graphics toolkits.
@xseealso{graphics_toolkit, register_graphics_toolkit}
@end deftypefn
register_graphics_toolkit
@c register_graphics_toolkit libinterp/corefcn/graphics.cc
@deftypefn {} {} register_graphics_toolkit (@var{toolkit})
List @var{toolkit} as an available graphics toolkit.
@xseealso{available_graphics_toolkits}
@end deftypefn
loaded_graphics_toolkits
@c loaded_graphics_toolkits libinterp/corefcn/graphics.cc
@deftypefn {} {} loaded_graphics_toolkits ()
Return a cell array of the currently loaded graphics toolkits.
@xseealso{available_graphics_toolkits}
@end deftypefn
__show_figure__
@c __show_figure__ libinterp/corefcn/graphics.cc
@deftypefn {} {} __show_figure__ (@var{n})
Undocumented internal function.
@end deftypefn
drawnow
@c drawnow libinterp/corefcn/graphics.cc
@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.
@xseealso{refresh}
@end deftypefn
addlistener
@c addlistener libinterp/corefcn/graphics.cc
@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

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

@xseealso{addlistener}
@end deftypefn
addproperty
@c addproperty libinterp/corefcn/graphics.cc
@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

@xseealso{addlistener, hggroup}
@end deftypefn
waitfor
@c waitfor libinterp/corefcn/graphics.cc
@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.
@xseealso{waitforbuttonpress, isequal}
@end deftypefn
__zoom__
@c __zoom__ libinterp/corefcn/graphics.cc
@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
@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
@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.

@xseealso{svd}
@end deftypefn
hash
@c hash libinterp/corefcn/hash.cc
@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
@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"}}.
@xseealso{get_help_text_from_file}
@end deftypefn
get_help_text_from_file
@c get_help_text_from_file libinterp/corefcn/help.cc
@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"}}.
@xseealso{get_help_text}
@end deftypefn
__operators__
@c __operators__ libinterp/corefcn/help.cc
@deftypefn {} {} __operators__ ()
Undocumented internal function.
@end deftypefn
__builtins__
@c __builtins__ libinterp/corefcn/help.cc
@deftypefn {} {} __builtins__ ()
Undocumented internal function.
@end deftypefn
localfunctions
@c localfunctions libinterp/corefcn/help.cc
@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.

@xseealso{functions}
@end deftypefn
__which__
@c __which__ libinterp/corefcn/help.cc
@deftypefn {} {} __which__ (@var{name}, @dots{})
Undocumented internal function.
@end deftypefn
__list_functions__
@c __list_functions__ libinterp/corefcn/help.cc
@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.
@xseealso{path}
@end deftypefn
built_in_docstrings_file
@c built_in_docstrings_file libinterp/corefcn/help.cc
@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
@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.
@xseealso{doc_cache_create, lookfor, info_program, doc, help, makeinfo_program}
@xseealso{lookfor}
@end deftypefn
info_file
@c info_file libinterp/corefcn/help.cc
@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.
@xseealso{info_program, doc, help, makeinfo_program}
@end deftypefn
info_program
@c info_program libinterp/corefcn/help.cc
@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.
@xseealso{info_file, doc, help, makeinfo_program}
@end deftypefn
makeinfo_program
@c makeinfo_program libinterp/corefcn/help.cc
@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.
@xseealso{texi_macros_file, info_file, info_program, doc, help}
@end deftypefn
suppress_verbose_help_message
@c suppress_verbose_help_message libinterp/corefcn/help.cc
@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
@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.
@xseealso{makeinfo_program}
@end deftypefn
hess
@c hess libinterp/corefcn/hess.cc
@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).
@xseealso{eig, chol, lu, qr, qz, schur, svd}
@end deftypefn
hex2num
@c hex2num libinterp/corefcn/hex2num.cc
@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
@xseealso{num2hex, hex2dec, dec2hex}
@end deftypefn
num2hex
@c num2hex libinterp/corefcn/hex2num.cc
@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.
@xseealso{hex2num, hex2dec, dec2hex}
@end deftypefn
input
@c input libinterp/corefcn/input.cc
@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.
@xseealso{yes_or_no, kbhit, pause, menu, listdlg}
@end deftypefn
yes_or_no
@c yes_or_no libinterp/corefcn/input.cc
@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.
@xseealso{input}
@end deftypefn
keyboard
@c keyboard libinterp/corefcn/input.cc
@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.
@xseealso{dbstop, dbcont, dbquit}
@end deftypefn
completion_matches
@c completion_matches libinterp/corefcn/input.cc
@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
@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.
@xseealso{readline_re_read_init_file}
@end deftypefn
readline_re_read_init_file
@c readline_re_read_init_file libinterp/corefcn/input.cc
@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.
@xseealso{readline_read_init_file}
@end deftypefn
add_input_event_hook
@c add_input_event_hook libinterp/corefcn/input.cc
@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.
@xseealso{remove_input_event_hook}
@end deftypefn
remove_input_event_hook
@c remove_input_event_hook libinterp/corefcn/input.cc
@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.
@xseealso{add_input_event_hook}
@end deftypefn
PS1
@c PS1 libinterp/corefcn/input.cc
@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.
@xseealso{PS2, PS4}
@end deftypefn
PS2
@c PS2 libinterp/corefcn/input.cc
@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.
@xseealso{PS1, PS4}
@end deftypefn
completion_append_char
@c completion_append_char libinterp/corefcn/input.cc
@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
@deftypefn  {} {} __request_drawnow__ ()
@deftypefnx {} {} __request_drawnow__ (@var{flag})
Undocumented internal function.
@end deftypefn
__gud_mode__
@c __gud_mode__ libinterp/corefcn/input.cc
@deftypefn {} {} __gud_mode__ ()
Undocumented internal function.
@end deftypefn
__mfile_encoding__
@c __mfile_encoding__ libinterp/corefcn/input.cc
@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
@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}.
@xseealso{ldivide, rdivide, pinv}
@end deftypefn
__version_info__
@c __version_info__ libinterp/corefcn/interpreter.cc
@deftypefn {} {retval =} __version_info__ (@var{name}, @var{version}, @var{release}, @var{date})
Undocumented internal function.
@end deftypefn
quit
@c quit libinterp/corefcn/interpreter.cc
@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}.
@xseealso{atexit}
@end deftypefn
atexit
@c atexit libinterp/corefcn/interpreter.cc
@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.
@xseealso{quit}
@end deftypefn
kron
@c kron libinterp/corefcn/kron.cc
@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
@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.
@xseealso{path, addpath}
@end deftypefn
rehash
@c rehash libinterp/corefcn/load-path.cc
@deftypefn {} {} rehash ()
Reinitialize Octave's load path directory cache.
@end deftypefn
command_line_path
@c command_line_path libinterp/corefcn/load-path.cc
@deftypefn {} {} command_line_path ()
Return the command line path variable.

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

@xseealso{path, addpath, rmpath, genpath, pathdef, savepath, pathsep}
@end deftypefn
__pathorig__
@c __pathorig__ libinterp/corefcn/load-path.cc
@deftypefn {} {@var{val} =} __pathorig__ ()
Undocumented internal function.
@end deftypefn
path
@c path libinterp/corefcn/load-path.cc
@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.
@xseealso{addpath, rmpath, genpath, pathdef, savepath, pathsep}
@end deftypefn
addpath
@c addpath libinterp/corefcn/load-path.cc
@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.

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

@xseealso{path, addpath, genpath, pathdef, savepath, pathsep}
@end deftypefn
__dump_load_path__
@c __dump_load_path__ libinterp/corefcn/load-path.cc
@deftypefn {} {} __dump_load_path__ ()
Undocumented internal function.
@end deftypefn
load
@c load libinterp/corefcn/load-save.cc
@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
@xseealso{save, dlmwrite, csvwrite, fwrite}
@end deftypefn
save
@c save libinterp/corefcn/load-save.cc
@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.
@xseealso{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
@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.
@xseealso{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
@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.
@xseealso{save, save_header_format_string, save_precision}
@end deftypefn
octave_core_file_limit
@c octave_core_file_limit libinterp/corefcn/load-save.cc
@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.
@xseealso{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
@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.
@xseealso{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
@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.
@xseealso{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
@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.
@xseealso{strftime, save_default_options}
@end deftypefn
lookup
@c lookup libinterp/corefcn/lookup.cc
@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
@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.

@xseealso{save_default_options}
@end deftypefn
lsode
@c lsode libinterp/corefcn/lsode.cc
@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}.
@xseealso{daspk, dassl, dasrt}
@end deftypefn
lu
@c lu libinterp/corefcn/lu.cc
@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.
@xseealso{luupdate, ilu, chol, hess, qr, qz, schur, svd}
@end deftypefn
luupdate
@c luupdate libinterp/corefcn/lu.cc
@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.
@xseealso{lu, cholupdate, qrupdate}
@end deftypefn
abs
@c abs libinterp/corefcn/mappers.cc
@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
@xseealso{arg}
@end deftypefn
acos
@c acos libinterp/corefcn/mappers.cc
@deftypefn {} {} acos (@var{x})
Compute the inverse cosine in radians for each element of @var{x}.
@xseealso{cos, acosd}
@end deftypefn
acosh
@c acosh libinterp/corefcn/mappers.cc
@deftypefn {} {} acosh (@var{x})
Compute the inverse hyperbolic cosine for each element of @var{x}.
@xseealso{cosh}
@end deftypefn
angle
@c angle libinterp/corefcn/mappers.cc
@deftypefn {} {} angle (@var{z})
See @code{arg}.
@xseealso{arg}
@end deftypefn
arg
@c arg libinterp/corefcn/mappers.cc
@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
@xseealso{abs}
@end deftypefn
asin
@c asin libinterp/corefcn/mappers.cc
@deftypefn {} {} asin (@var{x})
Compute the inverse sine in radians for each element of @var{x}.
@xseealso{sin, asind}
@end deftypefn
asinh
@c asinh libinterp/corefcn/mappers.cc
@deftypefn {} {} asinh (@var{x})
Compute the inverse hyperbolic sine for each element of @var{x}.
@xseealso{sinh}
@end deftypefn
atan
@c atan libinterp/corefcn/mappers.cc
@deftypefn {} {} atan (@var{x})
Compute the inverse tangent in radians for each element of @var{x}.
@xseealso{tan, atand}
@end deftypefn
atanh
@c atanh libinterp/corefcn/mappers.cc
@deftypefn {} {} atanh (@var{x})
Compute the inverse hyperbolic tangent for each element of @var{x}.
@xseealso{tanh}
@end deftypefn
cbrt
@c cbrt libinterp/corefcn/mappers.cc
@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.
@xseealso{nthroot}
@end deftypefn
ceil
@c ceil libinterp/corefcn/mappers.cc
@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
@xseealso{floor, round, fix}
@end deftypefn
conj
@c conj libinterp/corefcn/mappers.cc
@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
@xseealso{real, imag}
@end deftypefn
cos
@c cos libinterp/corefcn/mappers.cc
@deftypefn {} {} cos (@var{x})
Compute the cosine for each element of @var{x} in radians.
@xseealso{acos, cosd, cosh}
@end deftypefn
cosh
@c cosh libinterp/corefcn/mappers.cc
@deftypefn {} {} cosh (@var{x})
Compute the hyperbolic cosine for each element of @var{x}.
@xseealso{acosh, sinh, tanh}
@end deftypefn
erf
@c erf libinterp/corefcn/mappers.cc
@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
@xseealso{erfc, erfcx, erfi, dawson, erfinv, erfcinv}
@end deftypefn
erfinv
@c erfinv libinterp/corefcn/mappers.cc
@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
@xseealso{erf, erfc, erfcx, erfi, dawson, erfcinv}
@end deftypefn
erfcinv
@c erfcinv libinterp/corefcn/mappers.cc
@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
@xseealso{erfc, erf, erfcx, erfi, dawson, erfinv}
@end deftypefn
erfc
@c erfc libinterp/corefcn/mappers.cc
@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
@xseealso{erfcinv, erfcx, erfi, dawson, erf, erfinv}
@end deftypefn
erfcx
@c erfcx libinterp/corefcn/mappers.cc
@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
@xseealso{erfc, erf, erfi, dawson, erfinv, erfcinv}
@end deftypefn
erfi
@c erfi libinterp/corefcn/mappers.cc
@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
@xseealso{erfc, erf, erfcx, dawson, erfinv, erfcinv}
@end deftypefn
dawson
@c dawson libinterp/corefcn/mappers.cc
@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
@xseealso{erfc, erf, erfcx, erfi, erfinv, erfcinv}
@end deftypefn
exp
@c exp libinterp/corefcn/mappers.cc
@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}.
@xseealso{log}
@end deftypefn
expm1
@c expm1 libinterp/corefcn/mappers.cc
@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.
@xseealso{exp}
@end deftypefn
isfinite
@c isfinite libinterp/corefcn/mappers.cc
@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
@xseealso{isinf, isnan, isna}
@end deftypefn
fix
@c fix libinterp/corefcn/mappers.cc
@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
@xseealso{ceil, floor, round}
@end deftypefn
floor
@c floor libinterp/corefcn/mappers.cc
@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
@xseealso{ceil, round, fix}
@end deftypefn
gamma
@c gamma libinterp/corefcn/mappers.cc
@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}).}
@xseealso{gammainc, gammaln, factorial}
@end deftypefn
imag
@c imag libinterp/corefcn/mappers.cc
@deftypefn {} {} imag (@var{z})
Return the imaginary part of @var{z} as a real number.
@xseealso{real, conj}
@end deftypefn
isalnum
@c isalnum libinterp/corefcn/mappers.cc
@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})}).
@xseealso{isalpha, isdigit, ispunct, isspace, iscntrl}
@end deftypefn
isalpha
@c isalpha libinterp/corefcn/mappers.cc
@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})}).
@xseealso{isdigit, ispunct, isspace, iscntrl, isalnum, islower, isupper}
@end deftypefn
isascii
@c isascii libinterp/corefcn/mappers.cc
@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
@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.
@xseealso{ispunct, isspace, isalpha, isdigit}
@end deftypefn
isdigit
@c isdigit libinterp/corefcn/mappers.cc
@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.
@xseealso{isxdigit, isalpha, isletter, ispunct, isspace, iscntrl}
@end deftypefn
isinf
@c isinf libinterp/corefcn/mappers.cc
@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
@xseealso{isfinite, isnan, isna}
@end deftypefn
isgraph
@c isgraph libinterp/corefcn/mappers.cc
@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.
@xseealso{isprint}
@end deftypefn
islower
@c islower libinterp/corefcn/mappers.cc
@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.
@xseealso{isupper, isalpha, isletter, isalnum}
@end deftypefn
isna
@c isna libinterp/corefcn/mappers.cc
@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
@xseealso{isnan, isinf, isfinite}
@end deftypefn
isnan
@c isnan libinterp/corefcn/mappers.cc
@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
@xseealso{isna, isinf, isfinite}
@end deftypefn
isprint
@c isprint libinterp/corefcn/mappers.cc
@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.
@xseealso{isgraph}
@end deftypefn
ispunct
@c ispunct libinterp/corefcn/mappers.cc
@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.
@xseealso{isalpha, isdigit, isspace, iscntrl}
@end deftypefn
isspace
@c isspace libinterp/corefcn/mappers.cc
@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.
@xseealso{iscntrl, ispunct, isalpha, isdigit}
@end deftypefn
isupper
@c isupper libinterp/corefcn/mappers.cc
@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.
@xseealso{islower, isalpha, isletter, isalnum}
@end deftypefn
isxdigit
@c isxdigit libinterp/corefcn/mappers.cc
@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}).
@xseealso{isdigit}
@end deftypefn
lgamma
@c lgamma libinterp/corefcn/mappers.cc
@deftypefn  {} {} gammaln (@var{x})
@deftypefnx {} {} lgamma (@var{x})
Return the natural logarithm of the gamma function of @var{x}.
@xseealso{gamma, gammainc}
@end deftypefn
log
@c log libinterp/corefcn/mappers.cc
@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}.
@xseealso{exp, log1p, log2, log10, logspace}
@end deftypefn
log10
@c log10 libinterp/corefcn/mappers.cc
@deftypefn {} {} log10 (@var{x})
Compute the base-10 logarithm of each element of @var{x}.
@xseealso{log, log2, logspace, exp}
@end deftypefn
log1p
@c log1p libinterp/corefcn/mappers.cc
@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.
@xseealso{log, exp, expm1}
@end deftypefn
real
@c real libinterp/corefcn/mappers.cc
@deftypefn {} {} real (@var{z})
Return the real part of @var{z}.
@xseealso{imag, conj}
@end deftypefn
round
@c round libinterp/corefcn/mappers.cc
@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
@xseealso{ceil, floor, fix, roundb}
@end deftypefn
roundb
@c roundb libinterp/corefcn/mappers.cc
@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}.
@xseealso{round}
@end deftypefn
sign
@c sign libinterp/corefcn/mappers.cc
@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.
@xseealso{signbit}
@end deftypefn
signbit
@c signbit libinterp/corefcn/mappers.cc
@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.
@xseealso{sign}
@end deftypefn
sin
@c sin libinterp/corefcn/mappers.cc
@deftypefn {} {} sin (@var{x})
Compute the sine for each element of @var{x} in radians.
@xseealso{asin, sind, sinh}
@end deftypefn
sinh
@c sinh libinterp/corefcn/mappers.cc
@deftypefn {} {} sinh (@var{x})
Compute the hyperbolic sine for each element of @var{x}.
@xseealso{asinh, cosh, tanh}
@end deftypefn
sqrt
@c sqrt libinterp/corefcn/mappers.cc
@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}.
@xseealso{realsqrt, nthroot}
@end deftypefn
tan
@c tan libinterp/corefcn/mappers.cc
@deftypefn {} {} tan (@var{z})
Compute the tangent for each element of @var{x} in radians.
@xseealso{atan, tand, tanh}
@end deftypefn
tanh
@c tanh libinterp/corefcn/mappers.cc
@deftypefn {} {} tanh (@var{x})
Compute hyperbolic tangent for each element of @var{x}.
@xseealso{atanh, sinh, cosh}
@end deftypefn
tolower
@c tolower libinterp/corefcn/mappers.cc
@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
@xseealso{toupper}
@end deftypefn
toupper
@c toupper libinterp/corefcn/mappers.cc
@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
@xseealso{tolower}
@end deftypefn
matrix_type
@c matrix_type libinterp/corefcn/matrix_type.cc
@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
@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
@xseealso{max, cummin, cummax}
@end deftypefn
max
@c max libinterp/corefcn/max.cc
@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
@xseealso{min, cummax, cummin}
@end deftypefn
cummin
@c cummin libinterp/corefcn/max.cc
@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

@xseealso{cummax, min, max}
@end deftypefn
cummax
@c cummax libinterp/corefcn/max.cc
@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

@xseealso{cummin, max, min}
@end deftypefn
mgorth
@c mgorth libinterp/corefcn/mgorth.cc
@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
@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
@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.
@xseealso{run_history, history}
@end deftypefn
history
@c history libinterp/corefcn/oct-hist.cc
@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.
@xseealso{edit_history, run_history}
@end deftypefn
run_history
@c run_history libinterp/corefcn/oct-hist.cc
@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

@xseealso{edit_history, history}
@end deftypefn
history_control
@c history_control libinterp/corefcn/oct-hist.cc
@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}.
@xseealso{history_file, history_size, history_timestamp_format_string, history_save}
@end deftypefn
history_size
@c history_size libinterp/corefcn/oct-hist.cc
@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}}.
@xseealso{history_file, history_timestamp_format_string, history_save}
@end deftypefn
history_file
@c history_file libinterp/corefcn/oct-hist.cc
@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

@xseealso{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
@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.
@xseealso{strftime, history_file, history_size, history_save}
@end deftypefn
history_save
@c history_save libinterp/corefcn/oct-hist.cc
@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.
@xseealso{history_control, history_file, history_size, history_timestamp_format_string}
@end deftypefn
__octave_link_enabled__
@c __octave_link_enabled__ libinterp/corefcn/octave-link.cc
@deftypefn {} {} __octave_link_enabled__ ()
Undocumented internal function.
@end deftypefn
__octave_link_edit_file__
@c __octave_link_edit_file__ libinterp/corefcn/octave-link.cc
@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
@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
@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
@deftypefn {} {} __octave_link_list_dialog__ (@var{list}, @var{mode}, @var{size}, @var{initial}, @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
@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
@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
@deftypefn {} {} __octave_link_show_preferences__ ()
Undocumented internal function.
@end deftypefn
__octave_link_gui_preference__
@c __octave_link_gui_preference__ libinterp/corefcn/octave-link.cc
@deftypefn {} {} __octave_link_gui_preference__ ()
Undocumented internal function.
@end deftypefn
__octave_link_file_remove__
@c __octave_link_file_remove__ libinterp/corefcn/octave-link.cc
@deftypefn {} {} __octave_link_file_remove__ ()
Undocumented internal function.
@end deftypefn
__octave_link_file_renamed__
@c __octave_link_file_renamed__ libinterp/corefcn/octave-link.cc
@deftypefn {} {} __octave_link_file_renamed__ ()
Undocumented internal function.
@end deftypefn
openvar
@c openvar libinterp/corefcn/octave-link.cc
@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
@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
@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
@deftypefn {} {} __octave_link_unregister_doc__ (@var{filename})
Undocumented internal function.
@end deftypefn
ordschur
@c ordschur libinterp/corefcn/ordschur.cc
@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

@xseealso{schur, ordeig}
@end deftypefn
diary
@c diary libinterp/corefcn/pager.cc
@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.
@xseealso{history, evalc}
@end deftypefn
more
@c more libinterp/corefcn/pager.cc
@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}.
@xseealso{page_screen_output, page_output_immediately, PAGER, PAGER_FLAGS}
@end deftypefn
terminal_size
@c terminal_size libinterp/corefcn/pager.cc
@deftypefn {} {} terminal_size ()
Return a two-element row vector containing the current size of the terminal
window in characters (rows and columns).
@xseealso{list_in_columns}
@end deftypefn
page_output_immediately
@c page_output_immediately libinterp/corefcn/pager.cc
@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.
@xseealso{page_screen_output, more, PAGER, PAGER_FLAGS}
@end deftypefn
page_screen_output
@c page_screen_output libinterp/corefcn/pager.cc
@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.
@xseealso{more, page_output_immediately, PAGER, PAGER_FLAGS}
@end deftypefn
PAGER
@c PAGER libinterp/corefcn/pager.cc
@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.
@xseealso{PAGER_FLAGS, page_output_immediately, more, page_screen_output}
@end deftypefn
PAGER_FLAGS
@c PAGER_FLAGS libinterp/corefcn/pager.cc
@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.
@xseealso{PAGER, more, page_screen_output, page_output_immediately}
@end deftypefn
pinv
@c pinv libinterp/corefcn/pinv.cc
@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

@xseealso{inv, ldivide}
@end deftypefn
output_precision
@c output_precision libinterp/corefcn/pr-flt-fmt.cc
@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.

@xseealso{format, fixed_point_format}
@end deftypefn
rats
@c rats libinterp/corefcn/pr-output.cc
@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

@xseealso{rat, format}
@end deftypefn
disp
@c disp libinterp/corefcn/pr-output.cc
@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.
@xseealso{fdisp}
@end deftypefn
fdisp
@c fdisp libinterp/corefcn/pr-output.cc
@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.
@xseealso{disp}
@end deftypefn
display
@c display libinterp/corefcn/pr-output.cc
@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.

@xseealso{disp, class, subsref, subsasgn}
@end deftypefn
format
@c format libinterp/corefcn/pr-output.cc
@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.

@xseealso{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
@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.
@xseealso{format, output_precision}
@end deftypefn
print_empty_dimensions
@c print_empty_dimensions libinterp/corefcn/pr-output.cc
@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.
@xseealso{format}
@end deftypefn
split_long_rows
@c split_long_rows libinterp/corefcn/pr-output.cc
@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.
@xseealso{format}
@end deftypefn
psi
@c psi libinterp/corefcn/psi.cc
@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.

@xseealso{gamma, gammainc, gammaln}
@end deftypefn
quad
@c quad libinterp/corefcn/quad.cc
@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}.
@xseealso{quad_options, quadv, quadl, quadgk, quadcc, trapz, dblquad, triplequad}
@end deftypefn
quadcc
@c quadcc libinterp/corefcn/quadcc.cc
@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.
@xseealso{quad, quadv, quadl, quadgk, trapz, dblquad, triplequad}
@end deftypefn
qz
@c qz libinterp/corefcn/qz.cc
@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}.
@xseealso{eig, ordeig, balance, lu, chol, hess, qr, qzhess, schur, svd}
@end deftypefn
rand
@c rand libinterp/corefcn/rand.cc
@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.
@xseealso{randn, rande, randg, randp}
@end deftypefn
randn
@c randn libinterp/corefcn/rand.cc
@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/}

@xseealso{rand, rande, randg, randp}
@end deftypefn
rande
@c rande libinterp/corefcn/rand.cc
@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/}

@xseealso{rand, randn, randg, randp}
@end deftypefn
randg
@c randg libinterp/corefcn/rand.cc
@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.
@xseealso{rand, randn, rande, randp}
@end deftypefn
randp
@c randp libinterp/corefcn/rand.cc
@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.
@xseealso{rand, randn, rande, randg}
@end deftypefn
randperm
@c randperm libinterp/corefcn/rand.cc
@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.
@xseealso{perms}
@end deftypefn
rcond
@c rcond libinterp/corefcn/rcond.cc
@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.
@xseealso{cond, condest}
@end deftypefn
regexp
@c regexp libinterp/corefcn/regexp.cc
@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.
@xseealso{regexpi, strfind, regexprep}
@end deftypefn
regexpi
@c regexpi libinterp/corefcn/regexp.cc
@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.
@xseealso{regexp}
@end deftypefn
regexprep
@c regexprep libinterp/corefcn/regexp.cc
@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.
@xseealso{regexp, regexpi, strrep}
@end deftypefn
schur
@c schur libinterp/corefcn/schur.cc
@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}).
@xseealso{rsf2csf, ordschur, ordeig, lu, chol, hess, qr, qz, svd}
@end deftypefn
rsf2csf
@c rsf2csf libinterp/corefcn/schur.cc
@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.
@xseealso{schur}
@end deftypefn
__display_tokens__
@c __display_tokens__ libinterp/corefcn/settings.cc
@deftypefn {} {} __display_tokens__ ()
Query or set the internal variable that determines whether Octave's
lexer displays tokens as they are read.
@xseealso{__lexer_debug_flag__, __token_count__}
@end deftypefn
__token_count__
@c __token_count__ libinterp/corefcn/settings.cc
@deftypefn {} {} __token_count__ ()
Return the number of language tokens processed since Octave startup.
@xseealso{__lexer_debug_flag__, __display_tokens__}
@end deftypefn
__lexer_debug_flag__
@c __lexer_debug_flag__ libinterp/corefcn/settings.cc
@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.
@xseealso{__display_tokens__, __token_count__, __parse_debug_flag__}
@end deftypefn
SIG
@c SIG libinterp/corefcn/sighandlers.cc
@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
@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.
@xseealso{debug_on_error, debug_on_warning}
@end deftypefn
sighup_dumps_octave_core
@c sighup_dumps_octave_core libinterp/corefcn/sighandlers.cc
@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
@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
@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
@deftypefn {} {} issparse (@var{x})
Return true if @var{x} is a sparse matrix.
@xseealso{ismatrix}
@end deftypefn
sparse
@c sparse libinterp/corefcn/sparse.cc
@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
@xseealso{full, accumarray, spalloc, spdiags, speye, spones, sprand, sprandn, sprandsym, spconvert, spfun}
@end deftypefn
spalloc
@c spalloc libinterp/corefcn/sparse.cc
@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.
@xseealso{nzmax, sparse}
@end deftypefn
spparms
@c spparms libinterp/corefcn/spparms.cc
@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.
@xseealso{chol, colamd, lu, qr, symamd}
@end deftypefn
sqrtm
@c sqrtm libinterp/corefcn/sqrtm.cc
@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.
@xseealso{expm, logm}
@end deftypefn
strfind
@c strfind libinterp/corefcn/strfind.cc
@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
@xseealso{regexp, regexpi, find}
@end deftypefn
strrep
@c strrep libinterp/corefcn/strfind.cc
@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

@xseealso{regexprep, strfind}
@end deftypefn
char
@c char libinterp/corefcn/strfns.cc
@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
@xseealso{strvcat, cellstr}
@end deftypefn
strvcat
@c strvcat libinterp/corefcn/strfns.cc
@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
@xseealso{char, strcat, cstrcat}
@end deftypefn
ischar
@c ischar libinterp/corefcn/strfns.cc
@deftypefn {} {} ischar (@var{x})
Return true if @var{x} is a character array.
@xseealso{isfloat, isinteger, islogical, isnumeric, isstring, iscellstr, isa}
@end deftypefn
strcmp
@c strcmp libinterp/corefcn/strfns.cc
@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.
@xseealso{strcmpi, strncmp, strncmpi}
@end deftypefn
strncmp
@c strncmp libinterp/corefcn/strfns.cc
@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.
@xseealso{strncmpi, strcmp, strcmpi}
@end deftypefn
strcmpi
@c strcmpi libinterp/corefcn/strfns.cc
@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.
@xseealso{strcmp, strncmp, strncmpi}
@end deftypefn
strncmpi
@c strncmpi libinterp/corefcn/strfns.cc
@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.
@xseealso{strncmp, strcmp, strcmpi}
@end deftypefn
str2double
@c str2double libinterp/corefcn/strfns.cc
@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.
@xseealso{str2num}
@end deftypefn
__native2unicode__
@c __native2unicode__ libinterp/corefcn/strfns.cc
@deftypefn {} {@var{utf8_str} =} __native2unicode__ (@var{native_bytes}, @var{codepage})
Convert byte stream @var{native_bytes} to UTF-8 using @var{codepage}.

@xseealso{native2unicode, __unicode2native__}
@end deftypefn
__unicode2native__
@c __unicode2native__ libinterp/corefcn/strfns.cc
@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}.

@xseealso{unicode2native, __native2unicode__}
@end deftypefn
unicode_idx
@c unicode_idx libinterp/corefcn/strfns.cc
@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
@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

@xseealso{terminal_size}
@end deftypefn
sub2ind
@c sub2ind libinterp/corefcn/sub2ind.cc
@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
@xseealso{ind2sub, size}
@end deftypefn
ind2sub
@c ind2sub libinterp/corefcn/sub2ind.cc
@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
@xseealso{ind2sub, size}
@end deftypefn
svd
@c svd libinterp/corefcn/svd.cc
@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.
@xseealso{svd_driver, svds, eig, lu, chol, hess, qr, qz}
@end deftypefn
svd_driver
@c svd_driver libinterp/corefcn/svd.cc
@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"}.

@xseealso{svd}
@end deftypefn
sylvester
@c sylvester libinterp/corefcn/sylvester.cc
@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
@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
@deftypefn {} {[@var{scope}, @var{context}] =} __current_scope__ ()
Return the current scope and context as integers.
@xseealso{__dump_symtab_info__}
@end deftypefn
__dump_symtab_info__
@c __dump_symtab_info__ libinterp/corefcn/symtab.cc
@deftypefn  {} {} __dump_symtab_info__ ()
@deftypefnx {} {} __dump_symtab_info__ (@var{function})
Undocumented internal function.
@xseealso{__current_scope__}
@end deftypefn
__get_cmdline_fcn_txt__
@c __get_cmdline_fcn_txt__ libinterp/corefcn/symtab.cc
@deftypefn {} {} __get_cmdline_fcn_txt__ (@var{name})
Undocumented internal function.
@end deftypefn
dup2
@c dup2 libinterp/corefcn/syscalls.cc
@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.
@xseealso{fopen, fclose, fcntl}
@end deftypefn
exec
@c exec libinterp/corefcn/syscalls.cc
@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
@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.
@xseealso{popen, waitpid}
@end deftypefn
fcntl
@c fcntl libinterp/corefcn/syscalls.cc
@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.
@xseealso{fopen, dup2}
@end deftypefn
fork
@c fork libinterp/corefcn/syscalls.cc
@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
@deftypefn {} {pgid =} getpgrp ()
Return the process group id of the current process.
@end deftypefn
getpid
@c getpid libinterp/corefcn/syscalls.cc
@deftypefn {} {pid =} getpid ()
Return the process id of the current process.
@xseealso{getppid}
@end deftypefn
getppid
@c getppid libinterp/corefcn/syscalls.cc
@deftypefn {} {pid =} getppid ()
Return the process id of the parent process.
@xseealso{getpid}
@end deftypefn
getegid
@c getegid libinterp/corefcn/syscalls.cc
@deftypefn {} {egid =} getegid ()
Return the effective group id of the current process.
@xseealso{getgid}
@end deftypefn
getgid
@c getgid libinterp/corefcn/syscalls.cc
@deftypefn {} {gid =} getgid ()
Return the real group id of the current process.
@xseealso{getegid}
@end deftypefn
geteuid
@c geteuid libinterp/corefcn/syscalls.cc
@deftypefn {} {euid =} geteuid ()
Return the effective user id of the current process.
@xseealso{getuid}
@end deftypefn
getuid
@c getuid libinterp/corefcn/syscalls.cc
@deftypefn {} {uid =} getuid ()
Return the real user id of the current process.
@xseealso{geteuid}
@end deftypefn
kill
@c kill libinterp/corefcn/syscalls.cc
@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
@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}.
@xseealso{stat, symlink}
@end deftypefn
mkfifo
@c mkfifo libinterp/corefcn/syscalls.cc
@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.
@xseealso{pipe, umask}
@end deftypefn
pipe
@c pipe libinterp/corefcn/syscalls.cc
@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.
@xseealso{mkfifo}
@end deftypefn
stat
@c stat libinterp/corefcn/syscalls.cc
@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
@xseealso{lstat, ls, dir, isfile, isfolder}
@end deftypefn
S_ISREG
@c S_ISREG libinterp/corefcn/syscalls.cc
@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}.
@xseealso{stat, lstat}
@end deftypefn
S_ISDIR
@c S_ISDIR libinterp/corefcn/syscalls.cc
@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}.
@xseealso{stat, lstat}
@end deftypefn
S_ISCHR
@c S_ISCHR libinterp/corefcn/syscalls.cc
@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}.
@xseealso{stat, lstat}
@end deftypefn
S_ISBLK
@c S_ISBLK libinterp/corefcn/syscalls.cc
@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}.
@xseealso{stat, lstat}
@end deftypefn
S_ISFIFO
@c S_ISFIFO libinterp/corefcn/syscalls.cc
@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}.
@xseealso{stat, lstat}
@end deftypefn
S_ISLNK
@c S_ISLNK libinterp/corefcn/syscalls.cc
@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}.
@xseealso{stat, lstat}
@end deftypefn
S_ISSOCK
@c S_ISSOCK libinterp/corefcn/syscalls.cc
@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}.
@xseealso{stat, lstat}
@end deftypefn
gethostname
@c gethostname libinterp/corefcn/syscalls.cc
@deftypefn {} {} gethostname ()
Return the hostname of the system where Octave is running.
@end deftypefn
uname
@c uname libinterp/corefcn/syscalls.cc
@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
@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.
@xseealso{delete, rmdir}
@end deftypefn
waitpid
@c waitpid libinterp/corefcn/syscalls.cc
@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.
@xseealso{WCONTINUE, WCOREDUMP, WEXITSTATUS, WIFCONTINUED, WIFSIGNALED, WIFSTOPPED, WNOHANG, WSTOPSIG, WTERMSIG, WUNTRACED}
@end deftypefn
WIFEXITED
@c WIFEXITED libinterp/corefcn/syscalls.cc
@deftypefn {} {} WIFEXITED (@var{status})
Given @var{status} from a call to @code{waitpid}, return
true if the child terminated normally.
@xseealso{waitpid, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WEXITSTATUS
@c WEXITSTATUS libinterp/corefcn/syscalls.cc
@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.
@xseealso{waitpid, WIFEXITED, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WIFSIGNALED
@c WIFSIGNALED libinterp/corefcn/syscalls.cc
@deftypefn {} {} WIFSIGNALED (@var{status})
Given @var{status} from a call to @code{waitpid}, return
true if the child process was terminated by a signal.
@xseealso{waitpid, WIFEXITED, WEXITSTATUS, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WTERMSIG
@c WTERMSIG libinterp/corefcn/syscalls.cc
@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.
@xseealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WCOREDUMP
@c WCOREDUMP libinterp/corefcn/syscalls.cc
@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}).
@xseealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WIFSTOPPED
@c WIFSTOPPED libinterp/corefcn/syscalls.cc
@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)).
@xseealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WSTOPSIG, WIFCONTINUED}
@end deftypefn
WSTOPSIG
@c WSTOPSIG libinterp/corefcn/syscalls.cc
@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.
@xseealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WIFCONTINUED}
@end deftypefn
WIFCONTINUED
@c WIFCONTINUED libinterp/corefcn/syscalls.cc
@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}.
@xseealso{waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG}
@end deftypefn
canonicalize_file_name
@c canonicalize_file_name libinterp/corefcn/syscalls.cc
@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.
@xseealso{make_absolute_filename, is_absolute_filename, is_rooted_relative_filename}
@end deftypefn
F_DUPFD
@c F_DUPFD libinterp/corefcn/syscalls.cc
@deftypefn {} {} F_DUPFD ()
Return the numerical value to pass to @code{fcntl} to return
a duplicate file descriptor.
@xseealso{fcntl, F_GETFD, F_GETFL, F_SETFD, F_SETFL}
@end deftypefn
F_GETFD
@c F_GETFD libinterp/corefcn/syscalls.cc
@deftypefn {} {} F_GETFD ()
Return the numerical value to pass to @code{fcntl} to return
the file descriptor flags.
@xseealso{fcntl, F_DUPFD, F_GETFL, F_SETFD, F_SETFL}
@end deftypefn
F_GETFL
@c F_GETFL libinterp/corefcn/syscalls.cc
@deftypefn {} {} F_GETFL ()
Return the numerical value to pass to @code{fcntl} to return
the file status flags.
@xseealso{fcntl, F_DUPFD, F_GETFD, F_SETFD, F_SETFL}
@end deftypefn
F_SETFD
@c F_SETFD libinterp/corefcn/syscalls.cc
@deftypefn {} {} F_SETFD ()
Return the numerical value to pass to @code{fcntl} to set the file
descriptor flags.
@xseealso{fcntl, F_DUPFD, F_GETFD, F_GETFL, F_SETFL}
@end deftypefn
F_SETFL
@c F_SETFL libinterp/corefcn/syscalls.cc
@deftypefn {} {} F_SETFL ()
Return the numerical value to pass to @code{fcntl} to set the file
status flags.
@xseealso{fcntl, F_DUPFD, F_GETFD, F_GETFL, F_SETFD}
@end deftypefn
O_APPEND
@c O_APPEND libinterp/corefcn/syscalls.cc
@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.
@xseealso{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
@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.
@xseealso{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
@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.
@xseealso{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
@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.
@xseealso{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
@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.
@xseealso{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
@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.
@xseealso{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
@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.
@xseealso{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
@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
@xseealso{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
@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.
@xseealso{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
@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
@xseealso{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
@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.
@xseealso{waitpid, WUNTRACED, WCONTINUE}
@end deftypefn
WUNTRACED
@c WUNTRACED libinterp/corefcn/syscalls.cc
@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
@xseealso{waitpid, WNOHANG, WCONTINUE}
@end deftypefn
WCONTINUE
@c WCONTINUE libinterp/corefcn/syscalls.cc
@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.
@xseealso{waitpid, WNOHANG, WUNTRACED}
@end deftypefn
__open_with_system_app__
@c __open_with_system_app__ libinterp/corefcn/sysdep.cc
@deftypefn {} {} __open_with_system_app__ (@var{file})
Undocumented internal function.
@end deftypefn
clc
@c clc libinterp/corefcn/sysdep.cc
@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
@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.
@xseealso{setenv, unsetenv}
@end deftypefn
setenv
@c setenv libinterp/corefcn/sysdep.cc
@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.
@xseealso{unsetenv, getenv}
@end deftypefn
unsetenv
@c unsetenv libinterp/corefcn/sysdep.cc
@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.
@xseealso{setenv, getenv}
@end deftypefn
winqueryreg
@c winqueryreg libinterp/corefcn/sysdep.cc
@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
@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.
@xseealso{input, pause}
@end deftypefn
pause
@c pause libinterp/corefcn/sysdep.cc
@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.

@xseealso{kbhit}
@end deftypefn
isieee
@c isieee libinterp/corefcn/sysdep.cc
@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
@deftypefn {} {} native_float_format ()
Return the native floating point format as a string.
@end deftypefn
tilde_expand
@c tilde_expand libinterp/corefcn/sysdep.cc
@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
@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"))}
@xseealso{getenv}
@end deftypefn
__blas_version__
@c __blas_version__ libinterp/corefcn/sysdep.cc
@deftypefn {} {} __blas_version__ ()
Undocumented internal function.
@end deftypefn
__lapack_version__
@c __lapack_version__ libinterp/corefcn/sysdep.cc
@deftypefn {} {} __lapack_version__ ()
Undocumented internal function.
@end deftypefn
time
@c time libinterp/corefcn/time.cc
@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.
@xseealso{strftime, strptime, localtime, gmtime, mktime, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
gmtime
@c gmtime libinterp/corefcn/time.cc
@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
@xseealso{strftime, strptime, localtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
localtime
@c localtime libinterp/corefcn/time.cc
@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
@xseealso{strftime, strptime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
mktime
@c mktime libinterp/corefcn/time.cc
@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
@xseealso{strftime, strptime, localtime, gmtime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
strftime
@c strftime libinterp/corefcn/time.cc
@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
@xseealso{strptime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
strptime
@c strptime libinterp/corefcn/time.cc
@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.
@xseealso{strftime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday}
@end deftypefn
warranty
@c warranty libinterp/corefcn/toplev.cc
@deftypefn {} {} warranty ()
Describe the conditions for copying and distributing Octave.
@end deftypefn
system
@c system libinterp/corefcn/toplev.cc
@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.
@xseealso{unix, dos}
@end deftypefn
__octave_config_info__
@c __octave_config_info__ libinterp/corefcn/toplev.cc
@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.

@xseealso{computer}
@end deftypefn
tril
@c tril libinterp/corefcn/tril.cc
@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.
@xseealso{triu, istril, diag}
@end deftypefn
triu
@c triu libinterp/corefcn/tril.cc
@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.
@xseealso{tril, istriu, diag}
@end deftypefn
tsearch
@c tsearch libinterp/corefcn/tsearch.cc
@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.
@xseealso{delaunay, delaunayn}
@end deftypefn
typecast
@c typecast libinterp/corefcn/typecast.cc
@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
@xseealso{cast, bitpack, bitunpack, swapbytes}
@end deftypefn
bitpack
@c bitpack libinterp/corefcn/typecast.cc
@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.
@xseealso{bitunpack, typecast}
@end deftypefn
bitunpack
@c bitunpack libinterp/corefcn/typecast.cc
@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.
@xseealso{bitpack, typecast}
@end deftypefn
urlwrite
@c urlwrite libinterp/corefcn/urlwrite.cc
@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
@xseealso{urlread}
@end deftypefn
urlread
@c urlread libinterp/corefcn/urlwrite.cc
@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
@xseealso{urlwrite}
@end deftypefn
__ftp__
@c __ftp__ libinterp/corefcn/urlwrite.cc
@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
@deftypefn {} {} __ftp_pwd__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_cwd__
@c __ftp_cwd__ libinterp/corefcn/urlwrite.cc
@deftypefn {} {} __ftp_cwd__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_dir__
@c __ftp_dir__ libinterp/corefcn/urlwrite.cc
@deftypefn {} {} __ftp_dir__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_ascii__
@c __ftp_ascii__ libinterp/corefcn/urlwrite.cc
@deftypefn {} {} __ftp_ascii__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_binary__
@c __ftp_binary__ libinterp/corefcn/urlwrite.cc
@deftypefn {} {} __ftp_binary__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_close__
@c __ftp_close__ libinterp/corefcn/urlwrite.cc
@deftypefn {} {} __ftp_close__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_mode__
@c __ftp_mode__ libinterp/corefcn/urlwrite.cc
@deftypefn {} {} __ftp_mode__ (@var{handle})
Undocumented internal function
@end deftypefn
__ftp_delete__
@c __ftp_delete__ libinterp/corefcn/urlwrite.cc
@deftypefn {} {} __ftp_delete__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_rmdir__
@c __ftp_rmdir__ libinterp/corefcn/urlwrite.cc
@deftypefn {} {} __ftp_rmdir__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_mkdir__
@c __ftp_mkdir__ libinterp/corefcn/urlwrite.cc
@deftypefn {} {} __ftp_mkdir__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_rename__
@c __ftp_rename__ libinterp/corefcn/urlwrite.cc
@deftypefn {} {} __ftp_rename__ (@var{handle}, @var{path})
Undocumented internal function
@end deftypefn
__ftp_mput__
@c __ftp_mput__ libinterp/corefcn/urlwrite.cc
@deftypefn {} {} __ftp_mput__ (@var{handle}, @var{files})
Undocumented internal function
@end deftypefn
__ftp_mget__
@c __ftp_mget__ libinterp/corefcn/urlwrite.cc
@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
@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.
@xseealso{iskeyword, exist, who}
@end deftypefn
file_in_loadpath
@c file_in_loadpath libinterp/corefcn/utils.cc
@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.
@xseealso{file_in_path, dir_in_loadpath, path}
@end deftypefn
file_in_path
@c file_in_path libinterp/corefcn/utils.cc
@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.
@xseealso{file_in_loadpath, dir_in_loadpath, path}
@end deftypefn
do_string_escapes
@c do_string_escapes libinterp/corefcn/utils.cc
@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).
@xseealso{undo_string_escapes}
@end deftypefn
undo_string_escapes
@c undo_string_escapes libinterp/corefcn/utils.cc
@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.
@xseealso{do_string_escapes}
@end deftypefn
is_absolute_filename
@c is_absolute_filename libinterp/corefcn/utils.cc
@deftypefn {} {} is_absolute_filename (@var{file})
Return true if @var{file} is an absolute filename.
@xseealso{is_rooted_relative_filename, make_absolute_filename, isfolder}
@end deftypefn
is_rooted_relative_filename
@c is_rooted_relative_filename libinterp/corefcn/utils.cc
@deftypefn {} {} is_rooted_relative_filename (@var{file})
Return true if @var{file} is a rooted-relative filename.
@xseealso{is_absolute_filename, make_absolute_filename, isfolder}
@end deftypefn
make_absolute_filename
@c make_absolute_filename libinterp/corefcn/utils.cc
@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}.
@xseealso{canonicalize_file_name, is_absolute_filename, is_rooted_relative_filename, isfolder}
@end deftypefn
dir_in_loadpath
@c dir_in_loadpath libinterp/corefcn/utils.cc
@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.
@xseealso{file_in_path, file_in_loadpath, path}
@end deftypefn
errno
@c errno libinterp/corefcn/utils.cc
@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.

@xseealso{errno_list}
@end deftypefn
errno_list
@c errno_list libinterp/corefcn/utils.cc
@deftypefn {} {} errno_list ()
Return a structure containing the system-dependent errno values.
@xseealso{errno}
@end deftypefn
isindex
@c isindex libinterp/corefcn/utils.cc
@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
@deftypefn {} {} isstudent ()
Return true if running in the student edition of @sc{matlab}.

@code{isstudent} always returns false in Octave.
@xseealso{false}
@end deftypefn
isglobal
@c isglobal libinterp/corefcn/variables.cc
@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
@xseealso{isvarname, exist}
@end deftypefn
exist
@c exist libinterp/corefcn/variables.cc
@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.

@xseealso{file_in_loadpath, file_in_path, dir_in_loadpath, stat}
@end deftypefn
mlock
@c mlock libinterp/corefcn/variables.cc
@deftypefn {} {} mlock ()
Lock the current function into memory so that it can't be removed with
@code{clear}.
@xseealso{munlock, mislocked, persistent, clear}
@end deftypefn
munlock
@c munlock libinterp/corefcn/variables.cc
@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.
@xseealso{mlock, mislocked, persistent, clear}
@end deftypefn
mislocked
@c mislocked libinterp/corefcn/variables.cc
@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.
@xseealso{mlock, munlock, persistent, clear}
@end deftypefn
clear
@c clear libinterp/corefcn/variables.cc
@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.

@xseealso{who, whos, exist, mlock}
@end deftypefn
missing_function_hook
@c missing_function_hook libinterp/corefcn/variables.cc
@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.
@xseealso{missing_component_hook}
@end deftypefn
__varval__
@c __varval__ libinterp/corefcn/variables.cc
@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
@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.
@xseealso{missing_function_hook}
@end deftypefn
!
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} !
Logical 'not' operator.
@xseealso{~, not}
@end deftypefn
~
@c libinterp/parse-tree/oct-parse.yy
@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
@xseealso{!, not}
@end deftypefn
!=
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} !=
Logical 'not equals' operator.
@xseealso{~=, ne}
@end deftypefn
~=
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} ~=
Logical 'not equals' operator.
@xseealso{!=, ne}
@end deftypefn
"
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{'}
@end deftypefn
#
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} #
Begin comment character.
@xseealso{%, #@\{}
@end deftypefn
%
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} %
Begin comment character.
@xseealso{#, %@\{}
@end deftypefn
#@{
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{%@\{, #@\}, #}
@end deftypefn
%@{
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{#@\{, %@\}, %}
@end deftypefn
#@}
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{%@\}, #@\{, #}
@end deftypefn
%@}
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{#@\}, %@\{, %}
@end deftypefn
...
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} ...
Continuation marker.

Joins current line with following line before parsing.
@end deftypefn
&
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} &
Element by element logical 'and' operator.
@xseealso{&&, and}
@end deftypefn
&&
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} &&
Logical 'and' operator (with short-circuit evaluation).
@xseealso{&, and}
@end deftypefn
'
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{.', transpose, "}
@end deftypefn
(
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} (
Array index or function argument delimiter.
@end deftypefn
)
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {})
Array index or function argument delimiter.
@end deftypefn
*
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} *
Multiplication operator.
@xseealso{.*, times}
@end deftypefn
**
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{power, ^, .**, .^, realpow, realsqrt, cbrt, nthroot}
@end deftypefn
^
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{power, **, .^, .**, realpow, realsqrt, cbrt, nthroot}
@end deftypefn
+
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} +
Addition operator.
@xseealso{plus}
@end deftypefn
++
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} ++
Increment operator.

As in C, may be applied as a prefix or postfix operator.
@xseealso{--}
@end deftypefn
,
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} ,
Array index, function argument, or command separator.
@end deftypefn
-
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} -
Subtraction or unary negation operator.
@xseealso{minus}
@end deftypefn
--
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} --
Decrement operator.

As in C, may be applied as a prefix or postfix operator.
@xseealso{++}
@end deftypefn
.'
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} .'
Matrix transpose operator.

For complex matrices, computes the transpose, @emph{not} the complex conjugate
(Hermitian) transpose.
@xseealso{', transpose}
@end deftypefn
.*
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} .*
Element by element multiplication operator.
@xseealso{*, times}
@end deftypefn
.**
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{**, ^, .^, power, realpow, realsqrt, cbrt, nthroot}
@end deftypefn
.^
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{.**, ^, **, power, realpow, realsqrt, cbrt, nthroot}
@end deftypefn
./
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} ./
Element by element right division operator.
@xseealso{/, .\\, rdivide, mrdivide}
@end deftypefn
/
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} /
Right division operator.
@xseealso{./, \\, rdivide, mrdivide}
@end deftypefn
.\
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} .\
Element by element left division operator.
@xseealso{\\, ./, rdivide, mrdivide}
@end deftypefn
\
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} \
Left division operator.

Within double-quoted strings, @samp{\} is the line continuation marker used
to join the current line with the following line.
@xseealso{.\\, /, ldivide, mldivide}
@end deftypefn
:
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} :
Select entire rows or columns of matrices.
@end deftypefn
;
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} ;
Array row or command separator.
@xseealso{,}
@end deftypefn
<
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} <
'Less than' operator.
@xseealso{lt}
@end deftypefn
<=
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} <=
'Less than' or 'equals' operator.
@xseealso{le}
@end deftypefn
=
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} =
Assignment operator.
@end deftypefn
==
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} ==
Equality test operator.
@xseealso{eq}
@end deftypefn
>
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} >
'Greater than' operator.
@xseealso{gt}
@end deftypefn
>=
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} >=
'Greater than' or 'equals' operator.
@xseealso{ge}
@end deftypefn
[
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} [
Return list delimiter.
@xseealso{]}
@end deftypefn
]
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} ]
Return list delimiter.
@xseealso{[}
@end deftypefn
|
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} |
Element by element logical 'or' operator.
@xseealso{||, or}
@end deftypefn
||
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} ||
Logical 'or' (with short-circuit evaluation) operator.
@xseealso{|, or}
@end deftypefn
@@
@c libinterp/parse-tree/oct-parse.yy
@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.)
@xseealso{function, functions, func2str, str2func}
@end deftypefn
break
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} break
Exit the innermost enclosing do, while, or for loop.
@xseealso{do, while, for, parfor, continue}
@end deftypefn
case
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{switch}
@end deftypefn
catch
@c libinterp/parse-tree/oct-parse.yy
@deftypefn  {} {} catch
@deftypefnx {} {} catch @var{value}
Begin the cleanup part of a try-catch block.
@xseealso{try}
@end deftypefn
classdef
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} classdef
Begin a classdef block.
@xseealso{properties, methods, events, enumeration}
@end deftypefn
continue
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} continue
Jump to the end of the innermost enclosing do, while, or for loop.
@xseealso{break, do, while, for, parfor}
@end deftypefn
do
@c libinterp/parse-tree/oct-parse.yy
@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
@xseealso{for, until, while}
@end deftypefn
else
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} else
Alternate action for an if block.  See @code{if} for  an example.
@xseealso{if}
@end deftypefn
elseif
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} elseif (@var{condition})
Alternate conditional test for an if block.  See @code{if} for an example.
@xseealso{if}
@end deftypefn
end_try_catch
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} end_try_catch
Mark the end of a @code{try-catch} block.
@xseealso{try, catch}
@end deftypefn
end_unwind_protect
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} end_unwind_protect
Mark the end of an unwind_protect block.
@xseealso{unwind_protect}
@end deftypefn
endclassdef
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} endclassdef
Mark the end of a classdef definition.
@xseealso{classdef}
@end deftypefn
endenumeration
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} endenumeration
Mark the end of an enumeration block in a classdef definition.
@xseealso{enumeration}
@end deftypefn
endevents
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} endevents
Mark the end of an events block in a classdef definition.
@xseealso{events}
@end deftypefn
endfor
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} endfor
Mark the end of a for loop.  See @code{for} for an example.
@xseealso{for}
@end deftypefn
endfunction
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} endfunction
Mark the end of a function.
@xseealso{function}
@end deftypefn
endif
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} endif
Mark the end of an if block.  See @code{if} for an example.
@xseealso{if}
@end deftypefn
endmethods
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} endmethods
Mark the end of a methods block in a classdef definition.
@xseealso{methods}
@end deftypefn
endparfor
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} endparfor
Mark the end of a parfor loop.  See @code{parfor} for an example.
@xseealso{parfor}
@end deftypefn
endproperties
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} endproperties
Mark the end of a properties block in a classdef definition.
@xseealso{properties}
@end deftypefn
endswitch
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} endswitch
Mark the end of a switch block.  See @code{switch} for an example.
@xseealso{switch}
@end deftypefn
endwhile
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} endwhile
Mark the end of a while loop.  See @code{while} for an example.
@xseealso{do, while}
@end deftypefn
enumeration
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} enumeration
Begin an enumeration block in a classdef definition.
@end deftypefn
events
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} events
Begin an events block in a classdef definition.
@end deftypefn
for
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} for @var{i} = @var{range}
Begin a for loop.

@example
@group
for i = 1:10
  i
endfor
@end group
@end example
@xseealso{parfor, do, while}
@end deftypefn
function
@c libinterp/parse-tree/oct-parse.yy
@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

@xseealso{return}
@end deftypefn
global
@c libinterp/parse-tree/oct-parse.yy
@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
@xseealso{persistent}
@end deftypefn
if
@c libinterp/parse-tree/oct-parse.yy
@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
@xseealso{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 #@deftypefn {} {} methods
@c #Begin a methods block in a classdef definition.
@c #@end deftypefn
otherwise
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} otherwise
The default statement in a switch block which is executed when no other
case statements match the input.
@xseealso{switch, case}
@end deftypefn
parfor
@c libinterp/parse-tree/oct-parse.yy
@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
@xseealso{for, do, while}
@end deftypefn
persistent
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{global}
@end deftypefn
properties
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} properties
Begin a properties block in a classdef definition.
@end deftypefn
return
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} return
Return from a function.
@xseealso{function}
@end deftypefn
switch
@c libinterp/parse-tree/oct-parse.yy
@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
@xseealso{if, case, otherwise}
@end deftypefn
try
@c libinterp/parse-tree/oct-parse.yy
@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).
@xseealso{catch, unwind_protect}
@end deftypefn
until
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} until (@var{cond})
End a do-until loop.  See @code{do} for an example.
@xseealso{do}
@end deftypefn
unwind_protect
@c libinterp/parse-tree/oct-parse.yy
@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.
@xseealso{unwind_protect_cleanup, try}
@end deftypefn
unwind_protect_cleanup
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} unwind_protect_cleanup
Begin the cleanup section of an unwind_protect block.
@xseealso{unwind_protect}
@end deftypefn
varargin
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} varargin
Pass an arbitrary number of arguments into a function.
@xseealso{varargout, nargin, isargout, nargout, nthargout}
@end deftypefn
varargout
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} varargout
Pass an arbitrary number of arguments out of a function.
@xseealso{varargin, nargin, isargout, nargout, nthargout}
@end deftypefn
while
@c libinterp/parse-tree/oct-parse.yy
@deftypefn {} {} while
Begin a while loop.

@example
@group
i = 0;
while (i < 10)
  i++
endwhile
@end group
@end example
@xseealso{do, endwhile, for, until}
@end deftypefn
containers.Map
@c containers.Map scripts/+containers/Map.m
@deftypefn  {} {@var{m} =} containers.Map ()
@deftypefnx {} {@var{m} =} containers.Map (@var{keys}, @var{vals})
@deftypefnx {} {@var{m} =} containers.Map (@var{keys}, @var{vals}, @qcode{"UniformValues"}, @var{is_uniform})
@deftypefnx {} {@var{m} =} containers.Map (@qcode{"KeyType"}, @var{kt}, @qcode{"ValueType"}, @var{vt})

Create an object of the containers.Map class that stores a list of key/value
pairs.

@var{keys} is an array of @emph{unique} keys for the map.  The keys can be
numeric scalars or strings.  The type for numeric keys may be one of
@qcode{"double"}, @qcode{"single"}, @qcode{"int32"}, @qcode{"uint32"},
@qcode{"int64"}, or @qcode{"uint64"}.  Other numeric or logical keys will
be converted to @qcode{"double"}.  A single string key may be entered as is.
Multiple string keys are entered as a cell array of strings.

@var{vals} is an array of values for the map with the @emph{same} number
of elements as @var{keys}.

When called with no input arguments a default map is created with strings
as the key type and @qcode{"any"} as the value type.

The @qcode{"UniformValues"} option specifies whether the values of
the map must be strictly of the same type.  If @var{is_uniform} is true, any
values which would be added to the map are first validated to ensure they
are of the correct type.

When called with @qcode{"KeyType"} and @qcode{"ValueType"} arguments, create
an empty map with the specified types.  The inputs @var{kt} and @var{vt} are
the types for the keys and values of the map respectively.  Allowed values
for @var{kt} are @qcode{"char"}, @qcode{"double"}, @qcode{"single"},
@qcode{"int32"}, @qcode{"uint32"}, @qcode{"int64"}, @qcode{"uint64"}.
Allowed values for @var{vt} are @qcode{"any"}, @qcode{"char"},
@qcode{"double"}, @qcode{"single"}, @qcode{"int32"}, @qcode{"uint32"},
@qcode{"int64"}, @qcode{"uint64"}, @qcode{"logical"}.

The return value @var{m} is an object of the containers.Map class.
@xseealso{struct}
@end deftypefn
matlab.lang.makeUniqueStrings
@c matlab.lang.makeUniqueStrings scripts/+matlab/+lang/makeUniqueStrings.m
@deftypefn  {} {@var{uniqstr} =} matlab.lang.makeUniqueStrings (@var{str})
@deftypefnx {} {@var{uniqstr} =} matlab.lang.makeUniqueStrings (@var{str}, @var{ex})
@deftypefnx {} {@var{uniqstr} =} matlab.lang.makeUniqueStrings (@var{str}, @var{ex}, @var{maxlength})
@deftypefnx {} {[@var{uniqstr}, @var{ismodified}] =} matlab.lang.makeUniqueStrings (@dots{})

Construct a list of unique strings from a list of strings.

The input @var{str} must be a string or a cell array of strings.
The output @var{uniqstr} will be of the same type.

The algorithm makes two strings unique by appending an underscore
(@qcode{"_"} and a numeric count to the second string.

If @var{ex} is a string or a cell array of strings, @var{uniqstr} will
contain elements that are unique between themselves and with respect to
@var{ex}.

If @var{ex} is an index array or a logical array for @var{str} then it
selects the subset of @var{str} that are made unique.  Unselected elements
are not modified.

The optional input @var{maxlength} specifies the maximum length of any
string in @var{uniqstr}.  If an input string cannot be made unique without
exceeding @var{maxlength} an error is emitted.

The optional output @var{ismodified} is a logical array indicating whether
each element in @var{str} was modified to make it unique.

@xseealso{unique, matlab.lang.makeValidName}
@end deftypefn
matlab.lang.makeValidName
@c matlab.lang.makeValidName scripts/+matlab/+lang/makeValidName.m
@deftypefn  {} {@var{varname} =} matlab.lang.makeValidName (@var{str})
@deftypefnx {} {@var{varname} =} matlab.lang.makeValidName (@dots{}, @qcode{"ReplacementStyle"}, @var{rs})
@deftypefnx {} {@var{varname} =} matlab.lang.makeValidName (@dots{}, @qcode{"Prefix"}, @var{pfx})
@deftypefnx {} {[@var{varname}, @var{ismodified}] =} matlab.lang.makeValidName (@dots{})

Create valid variable name @var{varname} from @var{str}.

The input @var{str} must be a string or a cell array of strings.
The output @var{varname} will be of the same type.

A valid variable name is a sequence of letters, digits, and underscores that
does not begin with a digit.

The @qcode{"ReplacementStyle"} option specifies how invalid characters
are handled.  Acceptable values are

@table @asis
@item @qcode{"underscore"} (default)
Replace all invalid characters with an underscore (@qcode{"_"}).

@item @qcode{"delete"}
Remove any invalid character.

@item @qcode{"hex"}
Replace all invalid characters with their hexadecimal representation.
@end table

Whitespace characters are always removed @strong{prior} to the application
of the @qcode{"ReplacementStyle"}.  Lowercase letters following a whitespace
will be changed to uppercase.

The @qcode{"Prefix"} option specifies the string @var{pfx} to add as a
prefix to the input if it begins with a digit.  @var{pfx} must be a valid
variable name itself.  The default prefix is @qcode{"x"}.

The optional output @var{ismodified} is a logical array indicating whether
the respective element in @var{str} was a valid name or not.

@xseealso{iskeyword, isvarname, matlab.lang.makeUniqueStrings}
@end deftypefn
lin2mu
@c lin2mu scripts/audio/lin2mu.m
@deftypefn {} {@var{y} =} lin2mu (@var{x}, @var{n})
Convert audio data from linear to mu-law.

Mu-law values use 8-bit unsigned integers.  Linear values use @var{n}-bit
signed integers or floating point values in the range -1 @leq{} @var{x}
@leq{} 1 if @var{n} is 0.

If @var{n} is not specified it defaults to 0, 8, or 16 depending on
the range of values in @var{x}.
@xseealso{mu2lin}
@end deftypefn
mu2lin
@c mu2lin scripts/audio/mu2lin.m
@deftypefn {} {@var{y} =} mu2lin (@var{x}, @var{n})
Convert audio data from mu-law to linear.

Mu-law values are 8-bit unsigned integers.  Linear values use @var{n}-bit
signed integers or floating point values in the range -1 @leq{} @var{y}
@leq{} 1 if @var{n} is 0.

If @var{n} is not specified it defaults to 0.
@xseealso{lin2mu}
@end deftypefn
record
@c record scripts/audio/record.m
@deftypefn  {} {} record (@var{sec})
@deftypefnx {} {} record (@var{sec}, @var{fs})
Record @var{sec} seconds of audio from the system's default audio input at
a sampling rate of 8000 samples per second.

If the optional argument @var{fs} is given, it specifies the sampling rate
for recording.

For more control over audio recording, use the @code{audiorecorder} class.
@xseealso{sound, soundsc}
@end deftypefn
sound
@c sound scripts/audio/sound.m
@deftypefn  {} {} sound (@var{y})
@deftypefnx {} {} sound (@var{y}, @var{fs})
@deftypefnx {} {} sound (@var{y}, @var{fs}, @var{nbits})
Play audio data @var{y} at sample rate @var{fs} to the default audio
device.

The audio signal @var{y} can be a vector or a two-column array, representing
mono or stereo audio, respectively.

If @var{fs} is not given, a default sample rate of 8000 samples per second
is used.

The optional argument @var{nbits} specifies the bit depth to play to the
audio device and defaults to 8 bits.

For more control over audio playback, use the @code{audioplayer} class.
@xseealso{soundsc, record}
@end deftypefn
soundsc
@c soundsc scripts/audio/soundsc.m
@deftypefn  {} {} soundsc (@var{y})
@deftypefnx {} {} soundsc (@var{y}, @var{fs})
@deftypefnx {} {} soundsc (@var{y}, @var{fs}, @var{nbits})
@deftypefnx {} {} soundsc (@dots{}, [@var{ymin}, @var{ymax}])
Scale the audio data @var{y} and play it at sample rate @var{fs} to the
default audio device.

The audio signal @var{y} can be a vector or a two-column array, representing
mono or stereo audio, respectively.

If @var{fs} is not given, a default sample rate of 8000 samples per second
is used.

The optional argument @var{nbits} specifies the bit depth to play to the
audio device and defaults to 8 bits.

By default, @var{y} is automatically normalized to the range [-1, 1].  If
the range [@var{ymin}, @var{ymax}] is given, then elements of @var{y}
that fall within the range @var{ymin} @leq{} @var{y} @leq{} @var{ymax}
are scaled to the range [-1, 1] instead.

For more control over audio playback, use the @code{audioplayer} class.
@xseealso{sound, record}
@end deftypefn
@@audioplayer/__get_properties__
@c @audioplayer/__get_properties__ scripts/audio/@audioplayer/__get_properties__.m
@deftypefn {} {@var{properties} =} __get_properties__ (@var{player})
Return a struct containing all named properties of the audioplayer object
@var{player}.
@end deftypefn
@@audioplayer/audioplayer
@c @audioplayer/audioplayer scripts/audio/@audioplayer/audioplayer.m
@deftypefn  {} {@var{player} =} audioplayer (@var{y}, @var{fs})
@deftypefnx {} {@var{player} =} audioplayer (@var{y}, @var{fs}, @var{nbits})
@deftypefnx {} {@var{player} =} audioplayer (@var{y}, @var{fs}, @var{nbits}, @var{id})
@deftypefnx {} {@var{player} =} audioplayer (@var{recorder})
@deftypefnx {} {@var{player} =} audioplayer (@var{recorder}, @var{id})
Create an audioplayer object that will play back data @var{y} at sample
rate @var{fs}.

The optional arguments @var{nbits}, and @var{id} specify the bit depth and
player device id, respectively.  Device IDs may be found using the
audiodevinfo function.  Given an audioplayer object, use the data from the
object to initialize the player.

The signal @var{y} can be a vector or a two-dimensional array.

The following example will create an audioplayer object that will play
back one second of white noise at 44100 sample rate using 8 bits per
sample.

@example
@group
y = 0.25 * randn (2, 44100);
player = audioplayer (y, 44100, 8);
play (player);
@end group
@end example
@end deftypefn
@@audioplayer/disp
@c @audioplayer/disp scripts/audio/@audioplayer/disp.m
@deftypefn {} {} disp (@var{player})
Display the properties of the audioplayer object @var{player}.
@end deftypefn
@@audioplayer/get
@c @audioplayer/get scripts/audio/@audioplayer/get.m
@deftypefn  {} {@var{value} =} get (@var{player}, @var{name})
@deftypefnx {} {@var{values} =} get (@var{player})
Return the @var{value} of the property identified by @var{name}.

If @var{name} is a cell array return the values of the properties
identified by the elements of the cell array.  Given only the player
object, return a scalar structure with values of all properties of
@var{player}.  The field names of the structure correspond to property
names.
@end deftypefn
@@audioplayer/isplaying
@c @audioplayer/isplaying scripts/audio/@audioplayer/isplaying.m
@deftypefn {} {} isplaying (@var{player})
Return true if the audioplayer object @var{player} is currently playing back
audio and false otherwise.
@end deftypefn
@@audioplayer/pause
@c @audioplayer/pause scripts/audio/@audioplayer/pause.m
@deftypefn {} {} pause (@var{player})
Pause the audioplayer @var{player}.
@end deftypefn
@@audioplayer/play
@c @audioplayer/play scripts/audio/@audioplayer/play.m
@deftypefn  {} {} play (@var{player})
@deftypefnx {} {} play (@var{player}, @var{start})
@deftypefnx {} {} play (@var{player}, @var{limits})
Play audio stored in the audioplayer object @var{player} without blocking.

Given optional argument start, begin playing at @var{start} samples in the
recording.  Given a two-element vector @var{limits}, begin and end playing
at the number of samples specified by the elements of the vector.
@end deftypefn
@@audioplayer/playblocking
@c @audioplayer/playblocking scripts/audio/@audioplayer/playblocking.m
@deftypefn  {} {} playblocking (@var{player})
@deftypefnx {} {} playblocking (@var{player}, @var{start})
@deftypefnx {} {} playblocking (@var{player}, @var{limits})
Play audio stored in the audioplayer object @var{player} with blocking.

Given optional argument start, begin playing at @var{start} samples in the
recording.  Given a two-element vector @var{limits}, begin and end playing
at the number of samples specified by the elements of the vector.
@end deftypefn
@@audioplayer/resume
@c @audioplayer/resume scripts/audio/@audioplayer/resume.m
@deftypefn {} {} resume (@var{player})
Resume playback for the paused audioplayer object @var{player}.
@end deftypefn
@@audioplayer/set
@c @audioplayer/set scripts/audio/@audioplayer/set.m
@deftypefn  {} {} set (@var{player}, @var{name}, @var{value})
@deftypefnx {} {} set (@var{player}, @var{properties})
@deftypefnx {} {@var{properties} =} set (@var{player})
Set the value of property specified by @var{name} to a given @var{value}.

If @var{name} and @var{value} are cell arrays, set each property to the
corresponding value.  Given a structure of @var{properties} with fields
corresponding to property names, set the value of those properties to the
field values.  Given only the audioplayer object, return a structure of
settable properties.
@end deftypefn
@@audioplayer/stop
@c @audioplayer/stop scripts/audio/@audioplayer/stop.m
@deftypefn {} {} stop (@var{player})
Stop the playback for the audioplayer @var{player} and reset the
relevant variables to their starting values.
@end deftypefn
@@audioplayer/subsasgn
@c @audioplayer/subsasgn scripts/audio/@audioplayer/subsasgn.m
@deftypefn {} {@var{value} =} subsasgn (@var{player}, @var{idx}, @var{rhs})
Perform subscripted assignment on the audio player object @var{player}.

Assign the value of @var{rhs} to the player property named by @var{idx}.
@end deftypefn
@@audioplayer/subsref
@c @audioplayer/subsref scripts/audio/@audioplayer/subsref.m
@deftypefn {} {@var{value} =} subsref (@var{player}, @var{idx})
Perform subscripted selection on the audio player object @var{player}.

Return the player property value named by @var{idx}.
@end deftypefn
@@audiorecorder/__get_properties__
@c @audiorecorder/__get_properties__ scripts/audio/@audiorecorder/__get_properties__.m
@deftypefn {} {@var{properties} =} __get_properties__ (@var{recorder})
Return a struct containing all named properties of the recorder object
@var{recorder}.
@end deftypefn
@@audiorecorder/audiorecorder
@c @audiorecorder/audiorecorder scripts/audio/@audiorecorder/audiorecorder.m
@deftypefn  {} {@var{recorder} =} audiorecorder ()
@deftypefnx {} {@var{recorder} =} audiorecorder (@var{fs}, @var{nbits}, @var{channels})
@deftypefnx {} {@var{recorder} =} audiorecorder (@var{fs}, @var{nbits}, @var{channels}, @var{id})
Create an audiorecorder object recording 8 bit mono audio at 8000 Hz
sample rate.

The optional arguments @var{fs}, @var{nbits}, @var{channels}, and @var{id}
specify the sample rate, bit depth, number of channels and recording
device id, respectively.  Device IDs may be found using the audiodevinfo
function.
@end deftypefn
@@audiorecorder/disp
@c @audiorecorder/disp scripts/audio/@audiorecorder/disp.m
@deftypefn {} {} disp (@var{recorder})
Display the properties of the audiorecorder object @var{recorder}.
@end deftypefn
@@audiorecorder/get
@c @audiorecorder/get scripts/audio/@audiorecorder/get.m
@deftypefn  {} {@var{value} =} get (@var{recorder}, @var{name})
@deftypefnx {} {@var{values} =} get (@var{recorder})
Return the @var{value} of the property identified by @var{name}.

If @var{name} is a cell array, return the values of the properties
corresponding to the elements of the cell array.  Given only the recorder
object, return a scalar structure with values of all properties of
@var{recorder}.  The field names of the structure correspond to property
names.
@end deftypefn
@@audiorecorder/getaudiodata
@c @audiorecorder/getaudiodata scripts/audio/@audiorecorder/getaudiodata.m
@deftypefn  {} {@var{data} =} getaudiodata (@var{recorder})
@deftypefnx {} {@var{data} =} getaudiodata (@var{recorder}, @var{datatype})
Return recorder audio data as a matrix with values between -1.0 and 1.0
and with as many columns as there are channels in the recorder.

Given the optional argument @var{datatype}, convert the recorded data
to the specified type, which may be one of @qcode{"double"},
@qcode{"single"}, @qcode{"int16"}, @qcode{"int8"} or @qcode{"uint8"}.
@end deftypefn
@@audiorecorder/getplayer
@c @audiorecorder/getplayer scripts/audio/@audiorecorder/getplayer.m
@deftypefn {} {@var{player} =} getplayer (@var{recorder})
Return an audioplayer object with data recorded by the audiorecorder object
@var{recorder}.
@end deftypefn
@@audiorecorder/isrecording
@c @audiorecorder/isrecording scripts/audio/@audiorecorder/isrecording.m
@deftypefn {} {} isrecording (@var{recorder})
Return true if the audiorecorder object @var{recorder} is currently
recording audio and false otherwise.
@end deftypefn
@@audiorecorder/pause
@c @audiorecorder/pause scripts/audio/@audiorecorder/pause.m
@deftypefn {} {} pause (@var{recorder})
Pause recording with audiorecorder object @var{recorder}.
@end deftypefn
@@audiorecorder/play
@c @audiorecorder/play scripts/audio/@audiorecorder/play.m
@deftypefn  {} {@var{player} =} play (@var{recorder})
@deftypefnx {} {@var{player} =} play (@var{recorder}, @var{start})
@deftypefnx {} {@var{player} =} play (@var{recorder}, [@var{start}, @var{end}])
Play the audio recorded in @var{recorder} and return a corresponding
audioplayer object.

If the optional argument @var{start} is provided, begin playing
@var{start} seconds in to the recording.

If the optional argument @var{end} is provided, stop playing at
@var{end} seconds in the recording.
@end deftypefn
@@audiorecorder/record
@c @audiorecorder/record scripts/audio/@audiorecorder/record.m
@deftypefn  {} {} record (@var{recorder})
@deftypefnx {} {} record (@var{recorder}, @var{length})
Record audio without blocking using the audiorecorder object
@var{recorder} until stopped or paused by the @var{stop} or @var{pause}
method.

Given the optional argument @var{length}, record for @var{length} seconds.
@end deftypefn
@@audiorecorder/recordblocking
@c @audiorecorder/recordblocking scripts/audio/@audiorecorder/recordblocking.m
@deftypefn {} {} recordblocking (@var{recorder}, @var{length})
Record audio with blocking (synchronous I/O).

The length of the recording in seconds (@var{length}) must be specified.
@end deftypefn
@@audiorecorder/resume
@c @audiorecorder/resume scripts/audio/@audiorecorder/resume.m
@deftypefn {} {} resume (@var{recorder})
Resume recording with the paused audiorecorder object @var{recorder}.
@end deftypefn
@@audiorecorder/set
@c @audiorecorder/set scripts/audio/@audiorecorder/set.m
@deftypefn  {} {} set (@var{recorder}, @var{name}, @var{value})
@deftypefnx {} {} set (@var{recorder}, @var{properties})
@deftypefnx {} {@var{properties} =} set (@var{recorder})
Set the value of property specified by @var{name} to a given @var{value}.

If @var{name} and @var{value} are cell arrays of the same size, set each
property to a corresponding value.  Given a structure with fields
corresponding to property names, set the value of those properties to the
corresponding field values.  Given only the recorder object, return a
structure of settable properties.
@end deftypefn
@@audiorecorder/stop
@c @audiorecorder/stop scripts/audio/@audiorecorder/stop.m
@deftypefn {} {} stop (@var{recorder})
Stop the audiorecorder object @var{recorder} and clean up any audio streams.
@end deftypefn
@@audiorecorder/subsasgn
@c @audiorecorder/subsasgn scripts/audio/@audiorecorder/subsasgn.m
@deftypefn {} {@var{value} =} subsasgn (@var{recorder}, @var{idx}, @var{rhs})
Perform subscripted assignment on the audio recorder object @var{recorder}.

Assign the value of @var{rhs} to the recorder property named by @var{idx}.
@end deftypefn
@@audiorecorder/subsref
@c @audiorecorder/subsref scripts/audio/@audiorecorder/subsref.m
@deftypefn {} {@var{value} =} subsref (@var{recorder}, @var{idx})
Perform subscripted selection on the audio recorder object @var{recorder}.

Return the recorder property value named by @var{idx}.
@end deftypefn
chop
@c chop scripts/deprecated/chop.m
@deftypefn {} {} chop (@var{x}, @var{ndigits}, @var{base})

@code{chop} is deprecated and will be removed in Octave version 6.

Truncate elements of @var{x} to a length of @var{ndigits} such that the
resulting numbers are exactly divisible by @var{base}.

If @var{base} is not specified it defaults to 10.

@example
@group
format long
chop (-pi, 5, 10)
   @result{} -3.14200000000000
chop (-pi, 5, 5)
   @result{} -3.14150000000000
@end group
@end example
@end deftypefn
comma
@c comma scripts/deprecated/comma.m
@deftypefn {} {} ,
Array index, function argument, or command separator.
@xseealso{semicolon}
@end deftypefn
desktop
@c desktop scripts/deprecated/desktop.m
@deftypefn {} {@var{used} =} desktop ("-inuse")

@code{desktop} is deprecated and will be removed in Octave version 6.
Use @code{isguirunning} for the equivalent functionality.

Return true if the desktop (GUI) is currently in use.
@xseealso{isguirunning}
@end deftypefn
java2mat
@c java2mat scripts/deprecated/java2mat.m
@deftypefn {} {} java2mat (@var{javaobj})
@code{java2mat} is deprecated and will be removed in Octave version 6.

For the next two releases, use @code{__java2mat__} if necessary, and file
a bug report explaining your programming use of @code{java2mat} and how it
can't be done with other Octave functions.
@end deftypefn
output_max_field_width
@c output_max_field_width scripts/deprecated/output_max_field_width.m
@deftypefn  {} {@var{val} =} output_max_field_width ()
@deftypefnx {} {@var{old_val} =} output_max_field_width (@var{new_val})
@deftypefnx {} {} output_max_field_width (@var{new_val}, "local")

@code{output_max_field_width} is deprecated and will be removed in Octave
version 7.  Use @code{output_precision} instead.

Query or set the internal variable that specifies the maximum width
of a numeric output field.

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.
@xseealso{format, fixed_point_format, output_precision}
@end deftypefn
paren
@c paren scripts/deprecated/paren.m
@deftypefn  {} {} (
@deftypefnx {} {} )
Array index or function argument delimiter.
@end deftypefn
semicolon
@c semicolon scripts/deprecated/semicolon.m
@deftypefn {} {} ;
Array row or command separator.
@xseealso{comma}
@end deftypefn
tmpnam
@c tmpnam scripts/deprecated/tmpnam.m
@deftypefn  {} {@var{fname} =} tmpnam ()
@deftypefnx {} {@var{fname} =} tmpnam (@var{dir})
@deftypefnx {} {@var{fname} =} tmpnam (@var{dir}, @var{prefix})
@code{tmpnam} is deprecated and will be removed in Octave version 6.
Use @code{tempname} instead.

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{tmpnam},
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}.  The functions @code{tmpnam} and @code{tempname} are
equivalent with the latter provided for @sc{matlab} compatibility.

@strong{Caution}: @code{tmpnam} will be removed in Octave version 6, or
whatever the version number is two releases from 4.4. Use the equivalent
@code{tempname} in all new code.
@xseealso{tempname, mkstemp, tempdir, P_tmpdir, tmpfile}
@end deftypefn
toascii
@c toascii scripts/deprecated/toascii.m
@deftypefn {} {} toascii (@var{str})

@code{toascii} is deprecated and will be removed in Octave version 6.
Use @code{double} instead.

Return ASCII representation of @var{str} in a matrix.

For example:

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

@end example
@xseealso{double, char}
@end deftypefn
acosd
@c acosd scripts/elfun/acosd.m
@deftypefn {} {} acosd (@var{x})
Compute the inverse cosine in degrees for each element of @var{x}.
@xseealso{cosd, acos}
@end deftypefn
acot
@c acot scripts/elfun/acot.m
@deftypefn {} {} acot (@var{x})
Compute the inverse cotangent in radians for each element of @var{x}.
@xseealso{cot, acotd}
@end deftypefn
acotd
@c acotd scripts/elfun/acotd.m
@deftypefn {} {} acotd (@var{x})
Compute the inverse cotangent in degrees for each element of @var{x}.
@xseealso{cotd, acot}
@end deftypefn
acoth
@c acoth scripts/elfun/acoth.m
@deftypefn {} {} acoth (@var{x})
Compute the inverse hyperbolic cotangent of each element of @var{x}.
@xseealso{coth}
@end deftypefn
acsc
@c acsc scripts/elfun/acsc.m
@deftypefn {} {} acsc (@var{x})
Compute the inverse cosecant in radians for each element of @var{x}.
@xseealso{csc, acscd}
@end deftypefn
acscd
@c acscd scripts/elfun/acscd.m
@deftypefn {} {} acscd (@var{x})
Compute the inverse cosecant in degrees for each element of @var{x}.
@xseealso{cscd, acsc}
@end deftypefn
acsch
@c acsch scripts/elfun/acsch.m
@deftypefn {} {} acsch (@var{x})
Compute the inverse hyperbolic cosecant of each element of @var{x}.
@xseealso{csch}
@end deftypefn
asec
@c asec scripts/elfun/asec.m
@deftypefn {} {} asec (@var{x})
Compute the inverse secant in radians for each element of @var{x}.
@xseealso{sec, asecd}
@end deftypefn
asecd
@c asecd scripts/elfun/asecd.m
@deftypefn {} {} asecd (@var{x})
Compute the inverse secant in degrees for each element of @var{x}.
@xseealso{secd, asec}
@end deftypefn
asech
@c asech scripts/elfun/asech.m
@deftypefn {} {} asech (@var{x})
Compute the inverse hyperbolic secant of each element of @var{x}.
@xseealso{sech}
@end deftypefn
asind
@c asind scripts/elfun/asind.m
@deftypefn {} {} asind (@var{x})
Compute the inverse sine in degrees for each element of @var{x}.
@xseealso{sind, asin}
@end deftypefn
atan2d
@c atan2d scripts/elfun/atan2d.m
@deftypefn {} {} atan2d (@var{y}, @var{x})
Compute atan (@var{y} / @var{x}) in degrees for corresponding elements
from @var{y} and @var{x}.
@xseealso{tand, atan2}
@end deftypefn
atand
@c atand scripts/elfun/atand.m
@deftypefn {} {} atand (@var{x})
Compute the inverse tangent in degrees for each element of @var{x}.
@xseealso{tand, atan}
@end deftypefn
cosd
@c cosd scripts/elfun/cosd.m
@deftypefn {} {} cosd (@var{x})
Compute the cosine for each element of @var{x} in degrees.

Returns zero for elements where @code{(@var{x}-90)/180} is an integer.
@xseealso{acosd, cos}
@end deftypefn
cot
@c cot scripts/elfun/cot.m
@deftypefn {} {} cot (@var{x})
Compute the cotangent for each element of @var{x} in radians.
@xseealso{acot, cotd, coth}
@end deftypefn
cotd
@c cotd scripts/elfun/cotd.m
@deftypefn {} {} cotd (@var{x})
Compute the cotangent for each element of @var{x} in degrees.
@xseealso{acotd, cot}
@end deftypefn
coth
@c coth scripts/elfun/coth.m
@deftypefn {} {} coth (@var{x})
Compute the hyperbolic cotangent of each element of @var{x}.
@xseealso{acoth}
@end deftypefn
csc
@c csc scripts/elfun/csc.m
@deftypefn {} {} csc (@var{x})
Compute the cosecant for each element of @var{x} in radians.
@xseealso{acsc, cscd, csch}
@end deftypefn
cscd
@c cscd scripts/elfun/cscd.m
@deftypefn {} {} cscd (@var{x})
Compute the cosecant for each element of @var{x} in degrees.
@xseealso{acscd, csc}
@end deftypefn
csch
@c csch scripts/elfun/csch.m
@deftypefn {} {} csch (@var{x})
Compute the hyperbolic cosecant of each element of @var{x}.
@xseealso{acsch}
@end deftypefn
sec
@c sec scripts/elfun/sec.m
@deftypefn {} {} sec (@var{x})
Compute the secant for each element of @var{x} in radians.
@xseealso{asec, secd, sech}
@end deftypefn
secd
@c secd scripts/elfun/secd.m
@deftypefn {} {} secd (@var{x})
Compute the secant for each element of @var{x} in degrees.
@xseealso{asecd, sec}
@end deftypefn
sech
@c sech scripts/elfun/sech.m
@deftypefn {} {} sech (@var{x})
Compute the hyperbolic secant of each element of @var{x}.
@xseealso{asech}
@end deftypefn
sind
@c sind scripts/elfun/sind.m
@deftypefn {} {} sind (@var{x})
Compute the sine for each element of @var{x} in degrees.

Returns zero for elements where @code{@var{x}/180} is an integer.
@xseealso{asind, sin}
@end deftypefn
tand
@c tand scripts/elfun/tand.m
@deftypefn {} {} tand (@var{x})
Compute the tangent for each element of @var{x} in degrees.

Returns zero for elements where @code{@var{x}/180} is an integer and
@code{Inf} for elements where @code{(@var{x}-90)/180} is an integer.
@xseealso{atand, tan}
@end deftypefn
accumarray
@c accumarray scripts/general/accumarray.m
@deftypefn  {} {} accumarray (@var{subs}, @var{vals}, @var{sz}, @var{func}, @var{fillval}, @var{issparse})
@deftypefnx {} {} accumarray (@var{subs}, @var{vals}, @dots{})

Create an array by accumulating the elements of a vector into the
positions defined by their subscripts.

The subscripts are defined by the rows of the matrix @var{subs} and the
values by @var{vals}.  Each row of @var{subs} corresponds to one of the
values in @var{vals}.  If @var{vals} is a scalar, it will be used for each
of the row of @var{subs}.  If @var{subs} is a cell array of vectors, all
vectors must be of the same length, and the subscripts in the @var{k}th
vector must correspond to the @var{k}th dimension of the result.

The size of the matrix will be determined by the subscripts
themselves.  However, if @var{sz} is defined it determines the matrix
size.  The length of @var{sz} must correspond to the number of columns
in @var{subs}.  An exception is if @var{subs} has only one column, in
which case @var{sz} may be the dimensions of a vector and the
subscripts of @var{subs} are taken as the indices into it.

The default action of @code{accumarray} is to sum the elements with
the same subscripts.  This behavior can be modified by defining the
@var{func} function.  This should be a function or function handle
that accepts a column vector and returns a scalar.  The result of the
function should not depend on the order of the subscripts.

The elements of the returned array that have no subscripts associated
with them are set to zero.  Defining @var{fillval} to some other value
allows these values to be defined.  This behavior changes, however,
for certain values of @var{func}.  If @var{func} is @code{@@min}
(respectively, @code{@@max}) then the result will be filled with the
minimum (respectively, maximum) integer if @var{vals} is of integral
type, logical false (respectively, logical true) if @var{vals} is of
logical type, zero if @var{fillval} is zero and all values are
non-positive (respectively, non-negative), and NaN otherwise.

By default @code{accumarray} returns a full matrix.  If
@var{issparse} is logically true, then a sparse matrix is returned
instead.

The following @code{accumarray} example constructs a frequency table
that in the first column counts how many occurrences each number in
the second column has, taken from the vector @var{x}.  Note the usage
of @code{unique}  for assigning to all repeated elements of @var{x}
the same index (@pxref{XREFunique,,unique}).

@example
@group
@var{x} = [91, 92, 90, 92, 90, 89, 91, 89, 90, 100, 100, 100];
[@var{u}, ~, @var{j}] = unique (@var{x});
[accumarray(@var{j}', 1), @var{u}']
  @result{}  2    89
      3    90
      2    91
      2    92
      3   100
@end group
@end example

Another example, where the result is a multi-dimensional 3-D array and
the default value (zero) appears in the output:

@example
@group
accumarray ([1, 1, 1;
             2, 1, 2;
             2, 3, 2;
             2, 1, 2;
             2, 3, 2], 101:105)
@result{} ans(:,:,1) = [101, 0, 0; 0, 0, 0]
@result{} ans(:,:,2) = [0, 0, 0; 206, 0, 208]
@end group
@end example

The sparse option can be used as an alternative to the @code{sparse}
constructor (@pxref{XREFsparse,,sparse}).  Thus

@example
sparse (@var{i}, @var{j}, @var{sv})
@end example

@noindent
can be written with @code{accumarray} as

@example
accumarray ([@var{i}, @var{j}], @var{sv}', [], [], 0, true)
@end example

@noindent
For repeated indices, @code{sparse} adds the corresponding value.  To
take the minimum instead, use @code{min} as an accumulator function:

@example
accumarray ([@var{i}, @var{j}], @var{sv}', [], @@min, 0, true)
@end example

The complexity of accumarray in general for the non-sparse case is
generally O(M+N), where N is the number of subscripts and M is the
maximum subscript (linearized in multi-dimensional case).  If
@var{func} is one of @code{@@sum} (default), @code{@@max},
@code{@@min} or @code{@@(x) @{x@}}, an optimized code path is used.
Note that for general reduction function the interpreter overhead can
play a major part and it may be more efficient to do multiple
accumarray calls and compute the results in a vectorized manner.

@xseealso{accumdim, unique, sparse}
@end deftypefn
accumdim
@c accumdim scripts/general/accumdim.m
@deftypefn {} {} accumdim (@var{subs}, @var{vals}, @var{dim}, @var{n}, @var{func}, @var{fillval})
Create an array by accumulating the slices of an array into the
positions defined by their subscripts along a specified dimension.

The subscripts are defined by the index vector @var{subs}.
The dimension is specified by @var{dim}.  If not given, it defaults
to the first non-singleton dimension.  The length of @var{subs} must
be equal to @code{size (@var{vals}, @var{dim})}.

The extent of the result matrix in the working dimension will be
determined by the subscripts themselves.  However, if @var{n} is
defined it determines this extent.

The default action of @code{accumdim} is to sum the subarrays with the
same subscripts.  This behavior can be modified by defining the
@var{func} function.  This should be a function or function handle
that accepts an array and a dimension, and reduces the array along
this dimension.  As a special exception, the built-in @code{min} and
@code{max} functions can be used directly, and @code{accumdim}
accounts for the middle empty argument that is used in their calling.

The slices of the returned array that have no subscripts associated
with them are set to zero.  Defining @var{fillval} to some other
value allows these values to be defined.

An example of the use of @code{accumdim} is:

@example
@group
accumdim ([1, 2, 1, 2, 1], [ 7, -10,   4;
                            -5, -12,   8;
                           -12,   2,   8;
                           -10,   9,  -3;
                            -5,  -3, -13])
@result{} [-10,-11,-1;-15,-3,5]
@end group
@end example

@xseealso{accumarray}
@end deftypefn
bincoeff
@c bincoeff scripts/general/bincoeff.m
@deftypefn {} {} bincoeff (@var{n}, @var{k})
Return the binomial coefficient of @var{n} and @var{k}.

The binomial coefficient is defined as
@tex
$$
 {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
$$
@end tex
@ifnottex

@example
@group
 /   \
 | n |    n (n-1) (n-2) @dots{} (n-k+1)
 |   |  = -------------------------
 | k |               k!
 \   /
@end group
@end example

@end ifnottex
For example:

@example
@group
bincoeff (5, 2)
   @result{} 10
@end group
@end example

In most cases, the @code{nchoosek} function is faster for small
scalar integer arguments.  It also warns about loss of precision for
big arguments.

@xseealso{nchoosek}
@end deftypefn
bitcmp
@c bitcmp scripts/general/bitcmp.m
@deftypefn {} {} bitcmp (@var{A}, @var{k})
Return the @var{k}-bit complement of integers in @var{A}.

If @var{k} is omitted @code{k = log2 (flintmax) + 1} is assumed.

@example
@group
bitcmp (7,4)
  @result{} 8
dec2bin (11)
  @result{} 1011
dec2bin (bitcmp (11, 6))
  @result{} 110100
@end group
@end example

@xseealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, bitshift, flintmax}
@end deftypefn
bitget
@c bitget scripts/general/bitget.m
@deftypefn {} {@var{c} =} bitget (@var{A}, @var{n})
Return the status of bit(s) @var{n} of the unsigned integers in @var{A}.

The least significant bit is @var{n} = 1.

@example
@group
bitget (100, 8:-1:1)
@result{} 0  1  1  0  0  1  0  0
@end group
@end example
@xseealso{bitand, bitor, bitxor, bitset, bitcmp, bitshift, intmax, flintmax}
@end deftypefn
bitset
@c bitset scripts/general/bitset.m
@deftypefn  {} {@var{C} =} bitset (@var{A}, @var{n})
@deftypefnx {} {@var{C} =} bitset (@var{A}, @var{n}, @var{val})
Set or reset bit(s) @var{n} of the unsigned integers in @var{A}.

The least significant bit is @var{n} = 1.  @w{@var{val} = 0} resets bits and
@w{@var{val} = 1} sets bits.  If no @var{val} is specified it defaults to
1 (set bit).  All inputs must be the same size or scalars.

Example 1: Set multiple bits

@example
@group
x = bitset (1, 3:5)
  @result{} x =

   5    9   17

dec2bin (x)
  @result{}
     00101
     01001
     10001
@end group
@end example

Example 2: Reset and set bits

@example
@group
x = bitset ([15 14], 1, [0 1])
  @result{} x =

   14    15
@end group
@end example
@xseealso{bitand, bitor, bitxor, bitget, bitcmp, bitshift, intmax, flintmax}
@end deftypefn
blkdiag
@c blkdiag scripts/general/blkdiag.m
@deftypefn {} {} blkdiag (@var{A}, @var{B}, @var{C}, @dots{})
Build a block diagonal matrix from @var{A}, @var{B}, @var{C}, @dots{}

All arguments must be numeric and either two-dimensional matrices or
scalars.  If any argument is of type sparse, the output will also be sparse.
@xseealso{diag, horzcat, vertcat, sparse}
@end deftypefn
cart2pol
@c cart2pol scripts/general/cart2pol.m
@deftypefn  {} {[@var{theta}, @var{r}] =} cart2pol (@var{x}, @var{y})
@deftypefnx {} {[@var{theta}, @var{r}, @var{z}] =} cart2pol (@var{x}, @var{y}, @var{z})
@deftypefnx {} {[@var{theta}, @var{r}] =} cart2pol (@var{C})
@deftypefnx {} {[@var{theta}, @var{r}, @var{z}] =} cart2pol (@var{C})
@deftypefnx {} {@var{P} =} cart2pol (@dots{})

Transform Cartesian coordinates to polar or cylindrical coordinates.

The inputs @var{x}, @var{y} (, and @var{z}) must be the same shape, or
scalar.  If called with a single matrix argument then each row of @var{C}
represents the Cartesian coordinate (@var{x}, @var{y} (, @var{z})).

@var{theta} describes the angle relative to the positive x-axis.

@var{r} is the distance to the z-axis @w{(0, 0, z)}.

If only a single return argument is requested then return a matrix @var{P}
where each row represents one polar/(cylindrical) coordinate
(@var{theta}, @var{phi} (, @var{z})).
@xseealso{pol2cart, cart2sph, sph2cart}
@end deftypefn
cart2sph
@c cart2sph scripts/general/cart2sph.m
@deftypefn  {} {[@var{theta}, @var{phi}, @var{r}] =} cart2sph (@var{x}, @var{y}, @var{z})
@deftypefnx {} {[@var{theta}, @var{phi}, @var{r}] =} cart2sph (@var{C})
@deftypefnx {} {@var{S} =} cart2sph (@dots{})
Transform Cartesian coordinates to spherical coordinates.

The inputs @var{x}, @var{y}, and @var{z} must be the same shape, or scalar.
If called with a single matrix argument then each row of @var{C} represents
the Cartesian coordinate (@var{x}, @var{y}, @var{z}).

@var{theta} describes the angle relative to the positive x-axis.

@var{phi} is the angle relative to the xy-plane.

@var{r} is the distance to the origin @w{(0, 0, 0)}.

If only a single return argument is requested then return a matrix @var{S}
where each row represents one spherical coordinate
(@var{theta}, @var{phi}, @var{r}).
@xseealso{sph2cart, cart2pol, pol2cart}
@end deftypefn
cell2mat
@c cell2mat scripts/general/cell2mat.m
@deftypefn {} {@var{m} =} cell2mat (@var{c})
Convert the cell array @var{c} into a matrix by concatenating all
elements of @var{c} into a hyperrectangle.

Elements of @var{c} must be numeric, logical, or char matrices; or cell
arrays; or structs; and @code{cat} must be able to concatenate them
together.
@xseealso{mat2cell, num2cell}
@end deftypefn
celldisp
@c celldisp scripts/general/celldisp.m
@deftypefn  {} {} celldisp (@var{c})
@deftypefnx {} {} celldisp (@var{c}, @var{name})
Recursively display the contents of a cell array.

By default the values are displayed with the name of the variable @var{c}.
However, this name can be replaced with the variable @var{name}.  For
example:

@example
@group
c = @{1, 2, @{31, 32@}@};
celldisp (c, "b")
   @result{}
      b@{1@} =
       1
      b@{2@} =
       2
      b@{3@}@{1@} =
       31
      b@{3@}@{2@} =
       32
@end group
@end example

@xseealso{disp}
@end deftypefn
circshift
@c circshift scripts/general/circshift.m
@deftypefn  {} {@var{y} =} circshift (@var{x}, @var{n})
@deftypefnx {} {@var{y} =} circshift (@var{x}, @var{n}, @var{dim})
Circularly shift the values of the array @var{x}.

@var{n} must be a vector of integers no longer than the number of dimensions
in @var{x}.  The values of @var{n} can be either positive or negative, which
determines the direction in which the values of @var{x} are shifted.  If an
element of @var{n} is zero, then the corresponding dimension of @var{x} will
not be shifted.  If @var{n} is a scalar and no @var{dim} is specified then
the shift is applied to the first non-singular dimension.

If a scalar @var{dim} is given then operate along the specified dimension.
In this case @var{n} must be a scalar as well.

Examples:

@example
x = [1, 2, 3;
     4, 5, 6;
     7, 8, 9];
## positive shift on rows (1st non-singular dim)
circshift (x, 1)
  @result{}
       7   8   9
       1   2   3
       4   5   6
## negative shift on rows (1st non-singular dim)
circshift (x, -2)
  @result{}
       7   8   9
       1   2   3
       4   5   6
## no shift of rows, shift columns by 1 (2nd dimension)
circshift (x, [0,1])
  @result{}
       3   1   2
       6   4   5
       9   7   8
## shift columns (2nd dimension)
circshift (x, 1, 2)
  @result{}
       3   1   2
       6   4   5
       9   7   8
@end example
@xseealso{permute, ipermute, shiftdim}
@end deftypefn
common_size
@c common_size scripts/general/common_size.m
@deftypefn {} {[@var{err}, @var{yi}, @dots{}] =} common_size (@var{xi}, @dots{})
Determine if all input arguments are either scalar or of common size.

If true, @var{err} is zero, and @var{yi} is a matrix of the common size
with all entries equal to @var{xi} if this is a scalar or @var{xi}
otherwise.  If the inputs cannot be brought to a common size, @var{err} is
1, and @var{yi} is @var{xi}.  For example:

@example
@group
[err, a, b] = common_size ([1 2; 3 4], 5)
     @result{} err = 0
     @result{} a = [ 1, 2; 3, 4 ]
     @result{} b = [ 5, 5; 5, 5 ]
@end group
@end example

@noindent
This is useful for implementing functions where arguments can either be
scalars or of common size.
@xseealso{size, size_equal, numel, ndims}
@end deftypefn
cplxpair
@c cplxpair scripts/general/cplxpair.m
@deftypefn  {} {} cplxpair (@var{z})
@deftypefnx {} {} cplxpair (@var{z}, @var{tol})
@deftypefnx {} {} cplxpair (@var{z}, @var{tol}, @var{dim})
Sort the numbers @var{z} into complex conjugate pairs ordered by increasing
real part.

The negative imaginary complex numbers are placed first within each pair.
All real numbers (those with
@code{abs (imag (@var{z})) / abs (@var{z}) < @var{tol}}) are placed after
the complex pairs.

@var{tol} is a weighting factor in the range [0, 1) which determines the
tolerance of the matching.  The default value is @code{100 * eps} and the
resulting tolerance for a given complex pair is
@code{@var{tol} * abs (@var{z}(i)))}.

By default the complex pairs are sorted along the first non-singleton
dimension of @var{z}.  If @var{dim} is specified, then the complex pairs are
sorted along this dimension.

Signal an error if some complex numbers could not be paired.  Signal an
error if all complex numbers are not exact conjugates (to within @var{tol}).
Note that there is no defined order for pairs with identical real parts but
differing imaginary parts.
@c Set example in small font to prevent overfull line

@smallexample
cplxpair (exp (2i*pi*[0:4]'/5)) == exp (2i*pi*[3; 2; 4; 1; 0]/5)
@end smallexample
@end deftypefn
cumtrapz
@c cumtrapz scripts/general/cumtrapz.m
@deftypefn  {} {@var{q} =} cumtrapz (@var{y})
@deftypefnx {} {@var{q} =} cumtrapz (@var{x}, @var{y})
@deftypefnx {} {@var{q} =} cumtrapz (@dots{}, @var{dim})
Cumulative numerical integration of points @var{y} using the trapezoidal
method.

@w{@code{cumtrapz (@var{y})}} computes the cumulative integral of @var{y}
along the first non-singleton dimension.  Where @code{trapz} reports only
the overall integral sum, @code{cumtrapz} reports the current partial sum
value at each point of @var{y}.

When the argument @var{x} is omitted an equally spaced @var{x} vector with
unit spacing (1) is assumed.  @code{cumtrapz (@var{x}, @var{y})} evaluates
the integral with respect to the spacing in @var{x} and the values in
@var{y}.  This is useful if the points in @var{y} have been sampled
unevenly.

If the optional @var{dim} argument is given, operate along this dimension.

Application Note: If @var{x} is not specified then unit spacing will be
used.  To scale the integral to the correct value you must multiply by the
actual spacing value (deltaX).
@xseealso{trapz, cumsum}
@end deftypefn
curl
@c curl scripts/general/curl.m
@deftypefn  {} {[@var{cx}, @var{cy}, @var{cz}, @var{v}] =} curl (@var{x}, @var{y}, @var{z}, @var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {[@var{cz}, @var{v}] =} curl (@var{x}, @var{y}, @var{fx}, @var{fy})
@deftypefnx {} {[@dots{}] =} curl (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {[@dots{}] =} curl (@var{fx}, @var{fy})
@deftypefnx {} {@var{v} =} curl (@dots{})
Calculate curl of vector field given by the arrays @var{fx}, @var{fy}, and
@var{fz} or @var{fx}, @var{fy} respectively.
@tex
$$ curl F(x,y,z) = \left( {\partial{d} \over \partial{y}} F_z - {\partial{d} \over \partial{z}} F_y, {\partial{d} \over \partial{z}} F_x - {\partial{d} \over \partial{x}} F_z, {\partial{d} \over \partial{x}} F_y - {\partial{d} \over \partial{y}} F_x \right)$$
@end tex
@ifnottex

@example
@group
                  / d         d       d         d       d         d     \
curl F(x,y,z)  =  | -- Fz  -  -- Fy,  -- Fx  -  -- Fz,  -- Fy  -  -- Fx |
                  \ dy        dz      dz        dx      dx        dy    /
@end group
@end example

@end ifnottex
The coordinates of the vector field can be given by the arguments @var{x},
@var{y}, @var{z} or @var{x}, @var{y} respectively.  @var{v} calculates the
scalar component of the angular velocity vector in direction of the z-axis
for two-dimensional input.  For three-dimensional input the scalar
rotation is calculated at each grid point in direction of the vector field
at that point.
@xseealso{divergence, gradient, del2, cross}
@end deftypefn
dblquad
@c dblquad scripts/general/dblquad.m
@deftypefn  {} {} dblquad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb})
@deftypefnx {} {} dblquad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{tol})
@deftypefnx {} {} dblquad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{tol}, @var{quadf})
@deftypefnx {} {} dblquad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{tol}, @var{quadf}, @dots{})
Numerically evaluate the double integral of @var{f}.

@var{f} is a function handle, inline function, or string containing the name
of the function to evaluate.  The function @var{f} must have the form
@math{z = f(x,y)} where @var{x} is a vector and @var{y} is a scalar.  It
should return a vector of the same length and orientation as @var{x}.

@var{xa}, @var{ya} and @var{xb}, @var{yb} are the lower and upper limits of
integration for x and y respectively.  The underlying integrator determines
whether infinite bounds are accepted.

The optional argument @var{tol} defines the absolute tolerance used to
integrate each sub-integral.  The default value is 1e-6.

The optional argument @var{quadf} specifies which underlying integrator
function to use.  Any choice but @code{quad} is available and the default
is @code{quadcc}.

Additional arguments, are passed directly to @var{f}.  To use the default
value for @var{tol} or @var{quadf} one may pass @qcode{':'} or an empty
matrix ([]).
@xseealso{integral2, integral3, triplequad, quad, quadv, quadl, quadgk,
         quadcc, trapz}
@end deftypefn
deal
@c deal scripts/general/deal.m
@deftypefn  {} {[@var{r1}, @var{r2}, @dots{}, @var{rn}] =} deal (@var{a})
@deftypefnx {} {[@var{r1}, @var{r2}, @dots{}, @var{rn}] =} deal (@var{a1}, @var{a2}, @dots{}, @var{an})

Copy the input parameters into the corresponding output parameters.

If only a single input parameter is supplied, its value is copied to each
of the outputs.

For example,

@example
[a, b, c] = deal (x, y, z);
@end example

@noindent
is equivalent to

@example
@group
a = x;
b = y;
c = z;
@end group
@end example

@noindent
and

@example
[a, b, c] = deal (x);
@end example

@noindent
is equivalent to

@example
a = b = c = x;
@end example

Programming Note: @code{deal} is often used with comma separated lists
derived from cell arrays or structures.  This is unnecessary as the
interpreter can perform the same action without the overhead of a function
call.  For example:

@example
@group
c = @{[1 2], "Three", 4@};
[x, y, z] = c@{:@}
@result{}
   x =

      1   2

   y = Three
   z =  4
@end group
@end example
@xseealso{cell2struct, struct2cell, repmat}
@end deftypefn
deg2rad
@c deg2rad scripts/general/deg2rad.m
@deftypefn {} {@var{rad} =} deg2rad (@var{deg})

Convert degrees to radians.

The input @var{deg} must be a scalar, vector, or N-dimensional array of
double or single floating point values.  @var{deg} may be complex in which
case the real and imaginary components are converted separately.

The output @var{rad} is the same size and shape as @var{deg} with degrees
converted to radians using the conversion constant @code{pi/180}.

Example:

@example
@group
deg2rad ([0, 90, 180, 270, 360])
  @result{}  0.00000   1.57080   3.14159   4.71239   6.28319
@end group
@end example
@xseealso{rad2deg}
@end deftypefn
del2
@c del2 scripts/general/del2.m
@deftypefn  {} {@var{L} =} del2 (@var{M})
@deftypefnx {} {@var{L} =} del2 (@var{M}, @var{h})
@deftypefnx {} {@var{L} =} del2 (@var{M}, @var{dx}, @var{dy}, @dots{})

Calculate the discrete Laplace
@tex
operator $( \nabla^2 )$.
@end tex
@ifnottex
operator.
@end ifnottex

For a 2-dimensional matrix @var{M} this is defined as
@tex
$$L = {1 \over 4} \left( {d^2 \over dx^2} M(x,y) + {d^2 \over dy^2} M(x,y) \right)$$
@end tex
@ifnottex

@example
@group
      1    / d^2            d^2         \
L  = --- * | ---  M(x,y) +  ---  M(x,y) |
      4    \ dx^2           dy^2        /
@end group
@end example

@end ifnottex
For N-dimensional arrays the sum in parentheses is expanded to include
second derivatives over the additional higher dimensions.

The spacing between evaluation points may be defined by @var{h}, which is a
scalar defining the equidistant spacing in all dimensions.  Alternatively,
the spacing in each dimension may be defined separately by @var{dx},
@var{dy}, etc.  A scalar spacing argument defines equidistant spacing,
whereas a vector argument can be used to specify variable spacing.  The
length of the spacing vectors must match the respective dimension of
@var{M}.  The default spacing value is 1.

Dimensions with fewer than 3 data points are skipped.  Boundary points are
calculated from the linear extrapolation of interior points.

Example: Second derivative of 2*x^3

@example
@group
f = @@(x) 2*x.^3;
dd = @@(x) 12*x;
x = 1:6;
L = 4*del2 (f(x));
assert (L, dd (x));
@end group
@end example

@xseealso{gradient, diff}
@end deftypefn
divergence
@c divergence scripts/general/divergence.m
@deftypefn  {} {@var{div} =} divergence (@var{x}, @var{y}, @var{z}, @var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {@var{div} =} divergence (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {@var{div} =} divergence (@var{x}, @var{y}, @var{fx}, @var{fy})
@deftypefnx {} {@var{div} =} divergence (@var{fx}, @var{fy})
Calculate divergence of a vector field given by the arrays @var{fx},
@var{fy}, and @var{fz} or @var{fx}, @var{fy} respectively.

@tex
$$
div F(x,y,z) = \partial_x{F} + \partial_y{F} + \partial_z{F}
$$
@end tex
@ifnottex

@example
@group
                  d               d               d
div F(x,y,z)  =   -- F(x,y,z)  +  -- F(x,y,z)  +  -- F(x,y,z)
                  dx              dy              dz
@end group
@end example

@end ifnottex
The coordinates of the vector field can be given by the arguments @var{x},
@var{y}, @var{z} or @var{x}, @var{y} respectively.

@xseealso{curl, gradient, del2, dot}
@end deftypefn
flip
@c flip scripts/general/flip.m
@deftypefn  {} {} flip (@var{x})
@deftypefnx {} {} flip (@var{x}, @var{dim})
Return a copy of array @var{x} flipped across dimension @var{dim}.

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

Examples:

@example
## row vector
flip ([1  2  3  4])
      @result{}  4  3  2  1

## column vector
flip ([1; 2; 3; 4])
      @result{}  4
          3
          2
          1

## 2-D matrix along dimension 1
flip ([1 2; 3 4])
      @result{}  3  4
          1  2

## 2-D matrix along dimension 2
flip ([1 2; 3 4], 2)
      @result{}  2  1
          4  3
@end example

@xseealso{fliplr, flipud, rot90, rotdim, permute, transpose}
@end deftypefn
fliplr
@c fliplr scripts/general/fliplr.m
@deftypefn {} {} fliplr (@var{x})
Flip array left to right.

Return a copy of @var{x} with the order of the columns reversed.  In other
words, @var{x} is flipped left-to-right about a vertical axis.  For example:

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

@xseealso{flipud, flip, rot90, rotdim}
@end deftypefn
flipud
@c flipud scripts/general/flipud.m
@deftypefn {} {} flipud (@var{x})
Flip array upside down.

Return a copy of @var{x} with the order of the rows reversed.  In other
words, @var{x} is flipped upside-down about a horizontal axis.  For example:

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

@xseealso{fliplr, flip, rot90, rotdim}
@end deftypefn
gradient
@c gradient scripts/general/gradient.m
@deftypefn  {} {@var{dx} =} gradient (@var{m})
@deftypefnx {} {[@var{dx}, @var{dy}, @var{dz}, @dots{}] =} gradient (@var{m})
@deftypefnx {} {[@dots{}] =} gradient (@var{m}, @var{s})
@deftypefnx {} {[@dots{}] =} gradient (@var{m}, @var{x}, @var{y}, @var{z}, @dots{})
@deftypefnx {} {[@dots{}] =} gradient (@var{f}, @var{x0})
@deftypefnx {} {[@dots{}] =} gradient (@var{f}, @var{x0}, @var{s})
@deftypefnx {} {[@dots{}] =} gradient (@var{f}, @var{x0}, @var{x}, @var{y}, @dots{})

Calculate the gradient of sampled data or a function.

If @var{m} is a vector, calculate the one-dimensional gradient of @var{m}.
If @var{m} is a matrix the gradient is calculated for each dimension.

@code{[@var{dx}, @var{dy}] = gradient (@var{m})} calculates the
one-dimensional gradient for @var{x} and @var{y} direction if @var{m} is a
matrix.  Additional return arguments can be use for multi-dimensional
matrices.

A constant spacing between two points can be provided by the @var{s}
parameter.  If @var{s} is a scalar, it is assumed to be the spacing for all
dimensions.  Otherwise, separate values of the spacing can be supplied by
the @var{x}, @dots{} arguments.  Scalar values specify an equidistant
spacing.  Vector values for the @var{x}, @dots{} arguments specify the
coordinate for that dimension.  The length must match their respective
dimension of @var{m}.

At boundary points a linear extrapolation is applied.  Interior points
are calculated with the first approximation of the numerical gradient

@example
y'(i) = 1/(x(i+1)-x(i-1)) * (y(i-1)-y(i+1)).
@end example

If the first argument @var{f} is a function handle, the gradient of the
function at the points in @var{x0} is approximated using central difference.
For example, @code{gradient (@@cos, 0)} approximates the gradient of the
cosine function in the point @math{x0 = 0}.  As with sampled data, the
spacing values between the points from which the gradient is estimated can
be set via the @var{s} or @var{dx}, @var{dy}, @dots{} arguments.  By default
a spacing of 1 is used.
@xseealso{diff, del2}
@end deftypefn
idivide
@c idivide scripts/general/idivide.m
@deftypefn {} {} idivide (@var{x}, @var{y}, @var{op})
Integer division with different rounding rules.

The standard behavior of integer division such as @code{@var{a} ./ @var{b}}
is to round the result to the nearest integer.  This is not always the
desired behavior and @code{idivide} permits integer element-by-element
division to be performed with different treatment for the fractional
part of the division as determined by the @var{op} flag.  @var{op} is
a string with one of the values:

@table @asis
@item @qcode{"fix"}
Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
towards zero.

@item @qcode{"round"}
Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
towards the nearest integer.

@item @qcode{"floor"}
Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
towards negative infinity.

@item @qcode{"ceil"}
Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
towards positive infinity.
@end table

@noindent
If @var{op} is not given it defaults to @qcode{"fix"}.
An example demonstrating these rounding rules is

@example
@group
idivide (int8 ([-3, 3]), int8 (4), "fix")
  @result{}   0   0
idivide (int8 ([-3, 3]), int8 (4), "round")
  @result{}  -1   1
idivide (int8 ([-3, 3]), int8 (4), "floor")
  @result{}  -1   0
idivide (int8 ([-3, 3]), int8 (4), "ceil")
  @result{}   0   1
@end group
@end example

@xseealso{ldivide, rdivide}
@end deftypefn
int2str
@c int2str scripts/general/int2str.m
@deftypefn {} {} int2str (@var{n})
Convert an integer (or array of integers) to a string (or a character
array).

@example
@group
int2str (123)
  @result{} 123

s = int2str ([1, 2, 3; 4, 5, 6])
  @result{} s =
        1  2  3
        4  5  6

whos s
  @result{} Variables in the current scope:
        Attr Name        Size                     Bytes  Class
        ==== ====        ====                     =====  =====
             s           2x7                         14  char
     Total is 14 elements using 14 bytes
@end group
@end example

This function is not very flexible.  For better control over the
results, use @code{sprintf} (@pxref{Formatted Output}).

Programming Notes:

Non-integers are rounded to integers before display.  Only the real part
of complex numbers is displayed.

@xseealso{sprintf, num2str, mat2str}
@end deftypefn
integral
@c integral scripts/general/integral.m
@deftypefn  {} {@var{q} =} integral (@var{f}, @var{a}, @var{b})
@deftypefnx {} {@var{q} =} integral (@var{f}, @var{a}, @var{b}, @var{prop}, @var{val}, @dots{})

Numerically evaluate the integral of @var{f} from @var{a} to @var{b} using
adaptive quadrature.

@code{integral} is a wrapper for @code{quadcc} (general scalar integrands),
@code{quadgk} (integrals with specified integration paths), and @code{quadv}
(array-valued integrands) that is intended to provide @sc{matlab}
compatibility.  More control of the numerical integration may be achievable
by calling the various quadrature functions directly.

@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
return a vector of output values when given a vector of input values.

@var{a} and @var{b} are the lower and upper limits of integration.  Either
or both limits may be infinite or contain weak end singularities.  If either
or both limits are complex, @code{integral} will perform a straight line
path integral.  Alternatively, a complex domain path can be specified using
the @qcode{"Waypoints"} option (see below).

Additional optional parameters can be specified using
@qcode{"@var{property}", @var{value}} pairs.  Valid properties are:

@table @code
@item Waypoints
Specifies points to be used in defining subintervals of the quadrature
algorithm, or if @var{a}, @var{b}, or @var{waypoints} are complex then
the quadrature is calculated as a contour integral along a piecewise
continuous path.  For more detail see @code{quadgk}.

@item ArrayValued
@code{integral} expects @var{f} to return a scalar value unless
@var{arrayvalued} is specified as true.  This option will cause
@code{integral} to perform the integration over the entire array and return
@var{q} with the same dimensions as returned by @var{f}.  For more detail
see @code{quadv}.

@item AbsTol
Define the absolute error tolerance for the quadrature.  The default
absolute tolerance is 1e-10 (1e-5 for single).

@item RelTol
Define the relative error tolerance for the quadrature.  The default
relative tolerance is 1e-6 (1e-4 for single).
@end table

Adaptive quadrature is used to minimize the estimate of error until the
following is satisfied:
@tex
$$error \leq \max \left( AbsTol, RelTol\cdot\vert q\vert \right)$$
@end tex
@ifnottex

@example
@group
  @var{error} <= max (@var{AbsTol}, @var{RelTol}*|@var{q}|).
@end group
@end example

@end ifnottex

Known @sc{matlab} incompatibilities:

@enumerate
@item
If tolerances are left unspecified, and any integration limits or waypoints
are of type @code{single}, then Octave's integral functions automatically
reduce the default absolute and relative error tolerances as specified
above.  If tighter tolerances are desired they must be specified.
@sc{matlab} leaves the tighter tolerances appropriate for @code{double}
inputs in place regardless of the class of the integration limits.

@item
As a consequence of using @code{quadcc}, @code{quadgk}, and @code{quadv},
certain option combinations are not supported.  Currently,
@qcode{"ArrayValued"} cannot be combined with @qcode{"RelTol"} or
@qcode{"Waypoints"}.
@end enumerate

@xseealso{integral2, integral3, quad, quadgk, quadv, quadl, quadcc, trapz,
         dblquad, triplequad}
@end deftypefn
integral2
@c integral2 scripts/general/integral2.m
@deftypefn  {} {@var{q} =} integral2 (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb})
@deftypefnx {} {@var{q} =} integral2 (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {[@var{q}, @var{err}] =} integral2 (@dots{})

Numerically evaluate the two-dimensional integral of @var{f} using adaptive
quadrature over the two-dimensional domain defined by @var{xa}, @var{xb},
@var{ya}, @var{yb} (scalars may be finite or infinite).  Additionally,
@var{ya} and @var{yb} may be scalar functions of @var{x}, allowing for
integration over non-rectangular domains.

@var{f} is a function handle, inline function, or string containing the name
of the function to evaluate.  The function @var{f} must be of the form
@math{z = f(x,y)} where @var{x} is a vector and @var{y} is a scalar.  It
should return a vector of the same length and orientation as @var{x}.

Additional optional parameters can be specified using
@qcode{"@var{property}", @var{value}} pairs.  Valid properties are:

@table @code
@item AbsTol
Define the absolute error tolerance for the quadrature.  The default
value is 1e-10 (1e-5 for single).

@item RelTol
Define the relative error tolerance for the quadrature.  The default
value is 1e-6 (1e-4 for single).

@item Method
Specify the two-dimensional integration method to be used, with valid
options being @qcode{"auto"} (default), @qcode{"tiled"}, or
@qcode{"iterated"}.  When using @qcode{"auto"}, Octave will choose the
@qcode{"tiled"} method unless any of the integration limits are infinite.

@item Vectorized
Enable or disable vectorized integration.  A value of @code{false} forces
Octave to use only scalar inputs when calling the integrand, which enables
integrands @math{f(x,y)} that have not been vectorized and only accept
@var{x} and @var{y} as scalars to be used.  The default value is
@code{true}.
@end table

Adaptive quadrature is used to minimize the estimate of error until the
following is satisfied:
@tex
$$error \leq \max \left( AbsTol, RelTol\cdot\vert q\vert \right)$$
@end tex
@ifnottex

@example
@group
        @var{error} <= max (@var{AbsTol}, @var{RelTol}*|@var{q}|)
@end group
@end example

@end ifnottex

@var{err} is an approximate bound on the error in the integral
@code{abs (@var{q} - @var{I})}, where @var{I} is the exact value of the
integral.

Example 1 : integrate a rectangular region in x-y plane

@example
@group
@var{f} = @@(@var{x},@var{y}) 2*ones (size (@var{x}));
@var{q} = integral2 (@var{f}, 0, 1, 0, 1)
  @result{} @var{q} =  2
@end group
@end example

The result is a volume, which for this constant-value integrand, is just
@code{@var{Length} * @var{Width} * @var{Height}}.

Example 2 : integrate a triangular region in x-y plane

@example
@group
@var{f} = @@(@var{x},@var{y}) 2*ones (size (@var{x}));
@var{ymax} = @@(@var{x}) 1 - @var{x};
@var{q} = integral2 (@var{f}, 0, 1, 0, @var{ymax})
  @result{} @var{q} =  1
@end group
@end example

The result is a volume, which for this constant-value integrand, is the
Triangle Area x Height or
@code{1/2 * @var{Base} * @var{Width} * @var{Height}}.

Programming Notes: If there are singularities within the integration region
it is best to split the integral and place the singularities on the
boundary.

Known @sc{matlab} incompatibility: If tolerances are left unspecified, and
any integration limits are of type @code{single}, then Octave's integral
functions automatically reduce the default absolute and relative error
tolerances as specified above.  If tighter tolerances are desired they
must be specified.  @sc{matlab} leaves the tighter tolerances appropriate
for @code{double} inputs in place regardless of the class of the
integration limits.

Reference: @nospell{L.F. Shampine},
@cite{@sc{matlab} program for quadrature in 2D}, Applied Mathematics and
Computation, pp. 266--274, Vol 1, 2008.

@xseealso{quad2d, dblquad, integral, quad, quadgk, quadv, quadl, quadcc,
         trapz, integral3, triplequad}
@end deftypefn
integral3
@c integral3 scripts/general/integral3.m
@deftypefn  {} {@var{q} =} integral3 (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{za}, @var{zb})
@deftypefnx {} {@var{q} =} integral3 (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{za}, @var{zb}, @var{prop}, @var{val}, @dots{})

Numerically evaluate the three-dimensional integral of @var{f} using
adaptive quadrature over the three-dimensional domain defined by
@var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{za}, @var{zb} (scalars may
be finite or infinite).  Additionally, @var{ya} and @var{yb} may be
scalar functions of @var{x} and @var{za}, and @var{zb} maybe be scalar
functions of @var{x} and @var{y}, allowing for integration over
non-rectangular domains.

@var{f} is a function handle, inline function, or string containing the name
of the function to evaluate.  The function @var{f} must be of the form
@math{z = f(x,y)} where @var{x} is a vector and @var{y} is a scalar.  It
should return a vector of the same length and orientation as @var{x}.

Additional optional parameters can be specified using
@qcode{"@var{property}", @var{value}} pairs.  Valid properties are:

@table @code
@item AbsTol
Define the absolute error tolerance for the quadrature.  The default
value is 1e-10 (1e-5 for single).

@item RelTol
Define the relative error tolerance for the quadrature.  The default
value is 1e-6 (1e-4 for single).

@item Method
Specify the two-dimensional integration method to be used, with valid
options being @qcode{"auto"} (default), @qcode{"tiled"}, or
@qcode{"iterated"}.  When using @qcode{"auto"}, Octave will choose the
@qcode{"tiled"} method unless any of the integration limits are infinite.

@item Vectorized
Enable or disable vectorized integration.  A value of @code{false} forces
Octave to use only scalar inputs when calling the integrand, which enables
integrands @math{f(x,y)} that have not been vectorized and only accept
@var{x} and @var{y} as scalars to be used.  The default value is
@code{true}.
@end table

Adaptive quadrature is used to minimize the estimate of error until the
following is satisfied:
@tex
$$error \leq \max \left( AbsTol, RelTol\cdot\vert q\vert \right)$$
@end tex
@ifnottex

@example
@group
        @var{error} <= max (@var{AbsTol}, @var{RelTol}*|@var{q}|)
@end group
@end example

@end ifnottex

@var{err} is an approximate bound on the error in the integral
@code{abs (@var{q} - @var{I})}, where @var{I} is the exact value of the
integral.

Example 1 : integrate over a rectangular volume

@example
@group
@var{f} = @@(@var{x},@var{y},@var{z}) ones (size (@var{x}));
@var{q} = integral3 (@var{f}, 0, 1, 0, 1, 0, 1)
  @result{} @var{q} =  1.00000
@end group
@end example

For this constant-value integrand, the result is a volume which is just
@code{@var{Length} * @var{Width} * @var{Height}}.

Example 2 : integrate over a spherical volume

@example
@group
@var{f} = @@(@var{x},@var{y}) ones (size (@var{x}));
@var{ymax} = @@(@var{x}) sqrt (1 - @var{x}.^2);
@var{zmax} = @@(@var{x},@var{y}) sqrt (1 - @var{x}.^2 - @var{y}.^2);
@var{q} = integral3 (@var{f}, 0, 1, 0, @var{ymax}, 0, @var{zmax})
  @result{} @var{q} =  0.52360
@end group
@end example

For this constant-value integrand, the result is a volume which is 1/8th
of a unit sphere or @code{1/8 * 4/3 * pi}.

Programming Notes: If there are singularities within the integration region
it is best to split the integral and place the singularities on the
boundary.

Known @sc{matlab} incompatibility: If tolerances are left unspecified, and
any integration limits are of type @code{single}, then Octave's integral
functions automatically reduce the default absolute and relative error
tolerances as specified above.  If tighter tolerances are desired they
must be specified.  @sc{matlab} leaves the tighter tolerances appropriate
for @code{double} inputs in place regardless of the class of the
integration limits.

Reference: @nospell{L.F. Shampine},
@cite{@sc{matlab} program for quadrature in 2D}, Applied Mathematics and
Computation, pp. 266--274, Vol 1, 2008.

@xseealso{triplequad, integral, quad, quadgk, quadv, quadl,
         quadcc, trapz, integral2, quad2d, dblquad}
@end deftypefn
interp1
@c interp1 scripts/general/interp1.m
@deftypefn  {} {@var{yi} =} interp1 (@var{x}, @var{y}, @var{xi})
@deftypefnx {} {@var{yi} =} interp1 (@var{y}, @var{xi})
@deftypefnx {} {@var{yi} =} interp1 (@dots{}, @var{method})
@deftypefnx {} {@var{yi} =} interp1 (@dots{}, @var{extrap})
@deftypefnx {} {@var{yi} =} interp1 (@dots{}, "left")
@deftypefnx {} {@var{yi} =} interp1 (@dots{}, "right")
@deftypefnx {} {@var{pp} =} interp1 (@dots{}, "pp")

One-dimensional interpolation.

Interpolate input data to determine the value of @var{yi} at the points
@var{xi}.  If not specified, @var{x} is taken to be the indices of @var{y}
(@code{1:length (@var{y})}).  If @var{y} is a matrix or an N-dimensional
array, the interpolation is performed on each column of @var{y}.

The interpolation @var{method} is one of:

@table @asis
@item @qcode{"nearest"}
Return the nearest neighbor.

@item @qcode{"previous"}
Return the previous neighbor.

@item @qcode{"next"}
Return the next neighbor.

@item @qcode{"linear"} (default)
Linear interpolation from nearest neighbors.

@item @qcode{"pchip"}
Piecewise cubic Hermite interpolating polynomial---shape-preserving
interpolation with smooth first derivative.

@item @qcode{"cubic"}
Cubic interpolation (same as @qcode{"pchip"}).

@item @qcode{"spline"}
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

Adding '*' to the start of any method above forces @code{interp1}
to assume that @var{x} is uniformly spaced, and only @code{@var{x}(1)}
and @code{@var{x}(2)} are referenced.  This is usually faster,
and is never slower.  The default method is @qcode{"linear"}.

If @var{extrap} is the string @qcode{"extrap"}, then extrapolate values
beyond the endpoints using the current @var{method}.  If @var{extrap} is a
number, then replace values beyond the endpoints with that number.  When
unspecified, @var{extrap} defaults to @code{NA}.

If the string argument @qcode{"pp"} is specified, then @var{xi} should not
be supplied and @code{interp1} returns a piecewise polynomial object.  This
object can later be used with @code{ppval} to evaluate the interpolation.
There is an equivalence, such that @code{ppval (interp1 (@var{x},
@var{y}, @var{method}, @qcode{"pp"}), @var{xi}) == interp1 (@var{x},
@var{y}, @var{xi}, @var{method}, @qcode{"extrap"})}.

Duplicate points in @var{x} specify a discontinuous interpolant.  There
may be at most 2 consecutive points with the same value.
If @var{x} is increasing, the default discontinuous interpolant is
right-continuous.  If @var{x} is decreasing, the default discontinuous
interpolant is left-continuous.
The continuity condition of the interpolant may be specified by using
the options @qcode{"left"} or @qcode{"right"} to select a left-continuous
or right-continuous interpolant, respectively.
Discontinuous interpolation is only allowed for @qcode{"nearest"} and
@qcode{"linear"} methods; in all other cases, the @var{x}-values must be
unique.

An example of the use of @code{interp1} is

@example
@group
xf = [0:0.05:10];
yf = sin (2*pi*xf/5);
xp = [0:10];
yp = sin (2*pi*xp/5);
lin = interp1 (xp, yp, xf);
near = interp1 (xp, yp, xf, "nearest");
pch = interp1 (xp, yp, xf, "pchip");
spl = interp1 (xp, yp, xf, "spline");
plot (xf,yf,"r", xf,near,"g", xf,lin,"b", xf,pch,"c", xf,spl,"m",
      xp,yp,"r*");
legend ("original", "nearest", "linear", "pchip", "spline");
@end group
@end example

@xseealso{pchip, spline, interpft, interp2, interp3, interpn}
@end deftypefn
interp2
@c interp2 scripts/general/interp2.m
@deftypefn  {} {@var{zi} =} interp2 (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi})
@deftypefnx {} {@var{zi} =} interp2 (@var{z}, @var{xi}, @var{yi})
@deftypefnx {} {@var{zi} =} interp2 (@var{z}, @var{n})
@deftypefnx {} {@var{zi} =} interp2 (@var{z})
@deftypefnx {} {@var{zi} =} interp2 (@dots{}, @var{method})
@deftypefnx {} {@var{zi} =} interp2 (@dots{}, @var{method}, @var{extrap})

Two-dimensional interpolation.

Interpolate reference data @var{x}, @var{y}, @var{z} to determine @var{zi}
at the coordinates @var{xi}, @var{yi}.  The reference data @var{x}, @var{y}
can be matrices, as returned by @code{meshgrid}, in which case the sizes of
@var{x}, @var{y}, and @var{z} must be equal.  If @var{x}, @var{y} are
vectors describing a grid then @code{length (@var{x}) == columns (@var{z})}
and @code{length (@var{y}) == rows (@var{z})}.  In either case the input
data must be strictly monotonic.

If called without @var{x}, @var{y}, and just a single reference data matrix
@var{z}, the 2-D region
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})} is assumed.
This saves memory if the grid is regular and the distance between points is
not important.

If called with a single reference data matrix @var{z} and a refinement
value @var{n}, then perform interpolation over a grid where each original
interval has been recursively subdivided @var{n} times.  This results in
@code{2^@var{n}-1} additional points for every interval in the original
grid.  If @var{n} is omitted a value of 1 is used.  As an example, the
interval [0,1] with @code{@var{n}==2} results in a refined interval with
points at [0, 1/4, 1/2, 3/4, 1].

The interpolation @var{method} is one of:

@table @asis
@item @qcode{"nearest"}
Return the nearest neighbor.

@item @qcode{"linear"} (default)
Linear interpolation from nearest neighbors.

@item @qcode{"pchip"}
Piecewise cubic Hermite interpolating polynomial---shape-preserving
interpolation with smooth first derivative.

@item @qcode{"cubic"}
Cubic interpolation (same as @qcode{"pchip"}).

@item @qcode{"spline"}
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

@var{extrap} is a scalar number.  It replaces values beyond the endpoints
with @var{extrap}.  Note that if @var{extrap} is used, @var{method} must
be specified as well.  If @var{extrap} is omitted and the @var{method} is
@qcode{"spline"}, then the extrapolated values of the @qcode{"spline"} are
used.  Otherwise the default @var{extrap} value for any other @var{method}
is @qcode{"NA"}.
@xseealso{interp1, interp3, interpn, meshgrid}
@end deftypefn
interp3
@c interp3 scripts/general/interp3.m
@deftypefn  {} {@var{vi} =} interp3 (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {} {@var{vi} =} interp3 (@var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {} {@var{vi} =} interp3 (@var{v}, @var{n})
@deftypefnx {} {@var{vi} =} interp3 (@var{v})
@deftypefnx {} {@var{vi} =} interp3 (@dots{}, @var{method})
@deftypefnx {} {@var{vi} =} interp3 (@dots{}, @var{method}, @var{extrapval})

Three-dimensional interpolation.

Interpolate reference data @var{x}, @var{y}, @var{z}, @var{v} to determine
@var{vi} at the coordinates @var{xi}, @var{yi}, @var{zi}.  The reference
data @var{x}, @var{y}, @var{z} can be matrices, as returned by
@code{meshgrid}, in which case the sizes of @var{x}, @var{y}, @var{z}, and
@var{v} must be equal.  If @var{x}, @var{y}, @var{z} are vectors describing
a cubic grid then @code{length (@var{x}) == columns (@var{v})},
@code{length (@var{y}) == rows (@var{v})}, and
@code{length (@var{z}) == size (@var{v}, 3)}.  In either case the input
data must be strictly monotonic.

If called without @var{x}, @var{y}, @var{z}, and just a single reference
data matrix @var{v}, the 3-D region
@code{@var{x} = 1:columns (@var{v}), @var{y} = 1:rows (@var{v}),
@var{z} = 1:size (@var{v}, 3)} is assumed.
This saves memory if the grid is regular and the distance between points is
not important.

If called with a single reference data matrix @var{v} and a refinement
value @var{n}, then perform interpolation over a 3-D grid where each
original interval has been recursively subdivided @var{n} times.  This
results in @code{2^@var{n}-1} additional points for every interval in the
original grid.  If @var{n} is omitted a value of 1 is used.  As an
example, the interval [0,1] with @code{@var{n}==2} results in a refined
interval with points at [0, 1/4, 1/2, 3/4, 1].

The interpolation @var{method} is one of:

@table @asis
@item @qcode{"nearest"}
Return the nearest neighbor.

@item @qcode{"linear"} (default)
Linear interpolation from nearest neighbors.

@item @qcode{"cubic"}
Piecewise cubic Hermite interpolating polynomial---shape-preserving
interpolation with smooth first derivative (not implemented yet).

@item @qcode{"spline"}
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

@var{extrapval} is a scalar number.  It replaces values beyond the endpoints
with @var{extrapval}.  Note that if @var{extrapval} is used, @var{method}
must be specified as well.  If @var{extrapval} is omitted and the
@var{method} is @qcode{"spline"}, then the extrapolated values of the
@qcode{"spline"} are used.  Otherwise the default @var{extrapval} value for
any other @var{method} is @qcode{"NA"}.
@xseealso{interp1, interp2, interpn, meshgrid}
@end deftypefn
interpft
@c interpft scripts/general/interpft.m
@deftypefn  {} {} interpft (@var{x}, @var{n})
@deftypefnx {} {} interpft (@var{x}, @var{n}, @var{dim})

Fourier interpolation.

If @var{x} is a vector then @var{x} is resampled with @var{n} points.  The
data in @var{x} is assumed to be equispaced.  If @var{x} is a matrix or an
N-dimensional array, the interpolation is performed on each column of
@var{x}.

If @var{dim} is specified, then interpolate along the dimension @var{dim}.

@code{interpft} assumes that the interpolated function is periodic, and so
assumptions are made about the endpoints of the interpolation.
@xseealso{interp1}
@end deftypefn
interpn
@c interpn scripts/general/interpn.m
@deftypefn  {} {@var{vi} =} interpn (@var{x1}, @var{x2}, @dots{}, @var{v}, @var{y1}, @var{y2}, @dots{})
@deftypefnx {} {@var{vi} =} interpn (@var{v}, @var{y1}, @var{y2}, @dots{})
@deftypefnx {} {@var{vi} =} interpn (@var{v}, @var{m})
@deftypefnx {} {@var{vi} =} interpn (@var{v})
@deftypefnx {} {@var{vi} =} interpn (@dots{}, @var{method})
@deftypefnx {} {@var{vi} =} interpn (@dots{}, @var{method}, @var{extrapval})

Perform @var{n}-dimensional interpolation, where @var{n} is at least two.

Each element of the @var{n}-dimensional array @var{v} represents a value
at a location given by the parameters @var{x1}, @var{x2}, @dots{}, @var{xn}.
The parameters @var{x1}, @var{x2}, @dots{}, @var{xn} are either
@var{n}-dimensional arrays of the same size as the array @var{v} in
the @qcode{"ndgrid"} format or vectors.  The parameters @var{y1}, etc.
respect a similar format to @var{x1}, etc., and they represent the points
at which the array @var{vi} is interpolated.

If @var{x1}, @dots{}, @var{xn} are omitted, they are assumed to be
@code{x1 = 1 : size (@var{v}, 1)}, etc.  If @var{m} is specified, then
the interpolation adds a point half way between each of the interpolation
points.  This process is performed @var{m} times.  If only @var{v} is
specified, then @var{m} is assumed to be @code{1}.

The interpolation @var{method} is one of:

@table @asis
@item @qcode{"nearest"}
Return the nearest neighbor.

@item @qcode{"linear"} (default)
Linear interpolation from nearest neighbors.

@item @qcode{"pchip"}
Piecewise cubic Hermite interpolating polynomial---shape-preserving
interpolation with smooth first derivative (not implemented yet).

@item @qcode{"cubic"}
Cubic interpolation (same as @qcode{"pchip"} [not implemented yet]).

@item @qcode{"spline"}
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

The default method is @qcode{"linear"}.

@var{extrapval} is a scalar number.  It replaces values beyond the endpoints
with @var{extrapval}.  Note that if @var{extrapval} is used, @var{method}
must be specified as well.  If @var{extrapval} is omitted and the
@var{method} is @qcode{"spline"}, then the extrapolated values of the
@qcode{"spline"} are used.  Otherwise the default @var{extrapval} value for
any other @var{method} is @qcode{"NA"}.
@xseealso{interp1, interp2, interp3, spline, ndgrid}
@end deftypefn
isequal
@c isequal scripts/general/isequal.m
@deftypefn {} {} isequal (@var{x1}, @var{x2}, @dots{})
Return true if all of @var{x1}, @var{x2}, @dots{} are equal.
@xseealso{isequaln}
@end deftypefn
isequaln
@c isequaln scripts/general/isequaln.m
@deftypefn {} {} isequaln (@var{x1}, @var{x2}, @dots{})
Return true if all of @var{x1}, @var{x2}, @dots{} are equal under the
additional assumption that NaN == NaN (no comparison of NaN placeholders
in dataset).
@xseealso{isequal}
@end deftypefn
logspace
@c logspace scripts/general/logspace.m
@deftypefn  {} {} logspace (@var{a}, @var{b})
@deftypefnx {} {} logspace (@var{a}, @var{b}, @var{n})
@deftypefnx {} {} logspace (@var{a}, pi, @var{n})
Return a row vector with @var{n} elements logarithmically spaced from
@tex
$10^{a}$ to $10^{b}$.
@end tex
@ifnottex
10^@var{a} to 10^@var{b}.
@end ifnottex

If @var{n} is unspecified it defaults to 50.

If @var{b} is equal to
@tex
$\pi$,
@end tex
@ifnottex
pi,
@end ifnottex
the points are between
@tex
$10^{a}$ and $\pi$,
@end tex
@ifnottex
10^@var{a} and pi,
@end ifnottex
@emph{not}
@tex
$10^{a}$ and $10^{\pi}$,
@end tex
@ifnottex
10^@var{a} and 10^pi,
@end ifnottex
in order to be compatible with the corresponding @sc{matlab} function.

Also for compatibility with @sc{matlab}, return the right-hand side of
the range
@tex
($10^{b}$)
@end tex
@ifnottex
(10^@var{b})
@end ifnottex
when just a single value is requested.
@xseealso{linspace}
@end deftypefn
nextpow2
@c nextpow2 scripts/general/nextpow2.m
@deftypefn {} {@var{n} =} nextpow2 (@var{x})
Compute the exponent for the smallest power of two larger than the input.

For each element in the input array @var{x}, return the first integer
@var{n} such that
@tex
$2^n \ge |x|$.
@end tex
@ifnottex
2^n @geq{} abs (x).
@end ifnottex

@xseealso{pow2, log2}
@end deftypefn
num2str
@c num2str scripts/general/num2str.m
@deftypefn  {} {} num2str (@var{x})
@deftypefnx {} {} num2str (@var{x}, @var{precision})
@deftypefnx {} {} num2str (@var{x}, @var{format})
Convert a number (or array) to a string (or a character array).

The optional second argument may either give the number of significant
digits (@var{precision}) to be used in the output or a format template
string (@var{format}) as in @code{sprintf} (@pxref{Formatted Output}).
@code{num2str} can also process complex numbers.

Examples:

@example
@group
num2str (123.456)
  @result{} 123.456

num2str (123.456, 4)
  @result{} 123.5

s = num2str ([1, 1.34; 3, 3.56], "%5.1f")
  @result{} s =
       1.0  1.3
       3.0  3.6
whos s
  @result{} Variables in the current scope:
        Attr Name        Size                     Bytes  Class
        ==== ====        ====                     =====  =====
             s           2x8                         16  char
     Total is 16 elements using 16 bytes

num2str (1.234 + 27.3i)
  @result{} 1.234+27.3i
@end group
@end example

The @code{num2str} function is not very flexible.  For better control
over the results, use @code{sprintf} (@pxref{Formatted Output}).

Programming Notes:

For @sc{matlab} compatibility, leading spaces are stripped before returning
the string.

Integers larger than @code{flintmax} may not be displayed correctly.

For complex @var{x}, the format string may only contain one output
conversion specification and nothing else.  Otherwise, results will be
unpredictable.

Any optional @var{format} specified by the programmer is used without
modification.  This is in contrast to @sc{matlab} which tampers with the
@var{format} based on internal heuristics.
@xseealso{sprintf, int2str, mat2str}
@end deftypefn
pol2cart
@c pol2cart scripts/general/pol2cart.m
@deftypefn  {} {[@var{x}, @var{y}] =} pol2cart (@var{theta}, @var{r})
@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} pol2cart (@var{theta}, @var{r}, @var{z})
@deftypefnx {} {[@var{x}, @var{y}] =} pol2cart (@var{P})
@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} pol2cart (@var{P})
@deftypefnx {} {@var{C} =} pol2cart (@dots{})
Transform polar or cylindrical coordinates to Cartesian coordinates.

The inputs @var{theta}, @var{r}, (and @var{z}) must be the same shape, or
scalar.  If called with a single matrix argument then each row of @var{P}
represents the polar/(cylindrical) coordinate (@var{theta}, @var{r}
(, @var{z})).

@var{theta} describes the angle relative to the positive x-axis.

@var{r} is the distance to the z-axis (0, 0, z).

If only a single return argument is requested then return a matrix @var{C}
where each row represents one Cartesian coordinate
(@var{x}, @var{y} (, @var{z})).
@xseealso{cart2pol, sph2cart, cart2sph}
@end deftypefn
polyarea
@c polyarea scripts/general/polyarea.m
@deftypefn  {} {} polyarea (@var{x}, @var{y})
@deftypefnx {} {} polyarea (@var{x}, @var{y}, @var{dim})

Determine area of a polygon by triangle method.

The variables @var{x} and @var{y} define the vertex pairs, and must
therefore have the same shape.  They can be either vectors or arrays.  If
they are arrays then the columns of @var{x} and @var{y} are treated
separately and an area returned for each.

If the optional @var{dim} argument is given, then @code{polyarea} works
along this dimension of the arrays @var{x} and @var{y}.

@end deftypefn
postpad
@c postpad scripts/general/postpad.m
@deftypefn  {} {} postpad (@var{x}, @var{l})
@deftypefnx {} {} postpad (@var{x}, @var{l}, @var{c})
@deftypefnx {} {} postpad (@var{x}, @var{l}, @var{c}, @var{dim})
Append the scalar value @var{c} to the vector @var{x} until it is of length
@var{l}.  If @var{c} is not given, a value of 0 is used.

If @code{length (@var{x}) > @var{l}}, elements from the end of @var{x} are
removed until a vector of length @var{l} is obtained.

If @var{x} is a matrix, elements are appended or removed from each row.

If the optional argument @var{dim} is given, operate along this dimension.

If @var{dim} is larger than the dimensions of @var{x}, the result will have
@var{dim} dimensions.
@xseealso{prepad, cat, resize}
@end deftypefn
prepad
@c prepad scripts/general/prepad.m
@deftypefn  {} {} prepad (@var{x}, @var{l})
@deftypefnx {} {} prepad (@var{x}, @var{l}, @var{c})
@deftypefnx {} {} prepad (@var{x}, @var{l}, @var{c}, @var{dim})
Prepend the scalar value @var{c} to the vector @var{x} until it is of length
@var{l}.  If @var{c} is not given, a value of 0 is used.

If @code{length (@var{x}) > @var{l}}, elements from the beginning of @var{x}
are removed until a vector of length @var{l} is obtained.

If @var{x} is a matrix, elements are prepended or removed from each row.

If the optional argument @var{dim} is given, operate along this dimension.

If @var{dim} is larger than the dimensions of @var{x}, the result will have
@var{dim} dimensions.
@xseealso{postpad, cat, resize}
@end deftypefn
quad2d
@c quad2d scripts/general/quad2d.m
@deftypefn  {} {@var{q} =} quad2d (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb})
@deftypefnx {} {@var{q} =} quad2d (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {[@var{q}, @var{err}, @var{iter}] =} quad2d (@dots{})

Numerically evaluate the two-dimensional integral of @var{f} using adaptive
quadrature over the two-dimensional domain defined by @var{xa}, @var{xb},
@var{ya}, @var{yb} using tiled integration.  Additionally, @var{ya} and
@var{yb} may be scalar functions of @var{x}, allowing for the integration
over non-rectangular domains.

@var{f} is a function handle, inline function, or string containing the name
of the function to evaluate.  The function @var{f} must be of the form
@math{z = f(x,y)} where @var{x} is a vector and @var{y} is a scalar.  It
should return a vector of the same length and orientation as @var{x}.

Additional optional parameters can be specified using
@qcode{"@var{property}", @var{value}} pairs.  Valid properties are:

@table @code
@item AbsTol
Define the absolute error tolerance for the quadrature.  The default
value is 1e-10 (1e-5 for single).

@item RelTol
Define the relative error tolerance for the quadrature.  The default
value is 1e-6 (1e-4 for single).

@item MaxFunEvals
The maximum number of function calls to the vectorized function @var{f}.
The default value is 5000.

@item Singular
Enable/disable transforms to weaken singularities on the edge of the
integration domain.  The default value is @var{true}.

@item Vectorized
Option to disable vectorized integration, forcing Octave to use only scalar
inputs when calling the integrand.  The default value is @var{false}.

@item FailurePlot
If @code{quad2d} fails to converge to the desired error tolerance before
MaxFunEvals is reached, a plot of the areas that still need refinement
is created.  The default value is @var{false}.
@end table

Adaptive quadrature is used to minimize the estimate of error until the
following is satisfied:
@tex
$$error \leq \max \left( AbsTol, RelTol\cdot\vert q\vert \right)$$
@end tex
@ifnottex

@example
@group
        @var{error} <= max (@var{AbsTol}, @var{RelTol}*|@var{q}|)
@end group
@end example

@end ifnottex

The optional output @var{err} is an approximate bound on the error in the
integral @code{abs (@var{q} - @var{I})}, where @var{I} is the exact value
of the integral.  The optional output @var{iter} is the number of vectorized
function calls to the function @var{f} that were used.

Example 1 : integrate a rectangular region in x-y plane

@example
@group
@var{f} = @@(@var{x},@var{y}) 2*ones (size (@var{x}));
@var{q} = quad2d (@var{f}, 0, 1, 0, 1)
  @result{} @var{q} =  2
@end group
@end example

The result is a volume, which for this constant-value integrand, is just
@code{@var{Length} * @var{Width} * @var{Height}}.

Example 2 : integrate a triangular region in x-y plane

@example
@group
@var{f} = @@(@var{x},@var{y}) 2*ones (size (@var{x}));
@var{ymax} = @@(@var{x}) 1 - @var{x};
@var{q} = quad2d (@var{f}, 0, 1, 0, @var{ymax})
  @result{} @var{q} =  1
@end group
@end example

The result is a volume, which for this constant-value integrand, is the
Triangle Area x Height or
@code{1/2 * @var{Base} * @var{Width} * @var{Height}}.

Programming Notes: If there are singularities within the integration region
it is best to split the integral and place the singularities on the
boundary.

Known @sc{matlab} incompatibility: If tolerances are left unspecified, and
any integration limits are of type @code{single}, then Octave's integral
functions automatically reduce the default absolute and relative error
tolerances as specified above.  If tighter tolerances are desired they
must be specified.  @sc{matlab} leaves the tighter tolerances appropriate
for @code{double} inputs in place regardless of the class of the
integration limits.

Reference: @nospell{L.F. Shampine},
@cite{@sc{matlab} program for quadrature in 2D}, Applied Mathematics and
Computation, pp. 266--274, Vol 1, 2008.

@xseealso{integral2, dblquad, integral, quad, quadgk, quadv, quadl, quadcc,
         trapz, integral3, triplequad}
@end deftypefn
quadgk
@c quadgk scripts/general/quadgk.m
@deftypefn  {} {@var{q} =} quadgk (@var{f}, @var{a}, @var{b})
@deftypefnx {} {@var{q} =} quadgk (@var{f}, @var{a}, @var{b}, @var{abstol})
@deftypefnx {} {@var{q} =} quadgk (@var{f}, @var{a}, @var{b}, @var{abstol}, @var{trace})
@deftypefnx {} {@var{q} =} quadgk (@var{f}, @var{a}, @var{b}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {[@var{q}, @var{err}] =} quadgk (@dots{})

Numerically evaluate the integral of @var{f} from @var{a} to @var{b}
using adaptive @nospell{Gauss-Konrod} 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
return a vector of output values when given a vector of input values.

@var{a} and @var{b} are the lower and upper limits of integration.  Either
or both limits may be infinite or contain weak end singularities.  Variable
transformation will be used to treat any infinite intervals and weaken the
singularities.  For example:

@example
quadgk (@@(x) 1 ./ (sqrt (x) .* (x + 1)), 0, Inf)
@end example

@noindent
Note that the formulation of the integrand uses the element-by-element
operator @code{./} and all user functions to @code{quadgk} should do the
same.

The optional argument @var{tol} defines the absolute tolerance used to stop
the integration procedure.  The default value is 1e-10 (1e-5 for single).

The algorithm used by @code{quadgk} involves subdividing the integration
interval and evaluating each subinterval.  If @var{trace} is true then after
computing each of these partial integrals display: (1) the number of
subintervals at this step, (2) the current estimate of the error @var{err},
(3) the current estimate for the integral @var{q}.

Alternatively, properties of @code{quadgk} can be passed to the function as
pairs @qcode{"@var{prop}", @var{val}}.  Valid properties are

@table @code
@item AbsTol
Define the absolute error tolerance for the quadrature.  The default
absolute tolerance is 1e-10 (1e-5 for single).

@item RelTol
Define the relative error tolerance for the quadrature.  The default
relative tolerance is 1e-6 (1e-4 for single).

@item MaxIntervalCount
@code{quadgk} initially subdivides the interval on which to perform the
quadrature into 10 intervals.  Subintervals that have an unacceptable error
are subdivided and re-evaluated.  If the number of subintervals exceeds 650
subintervals at any point then a poor convergence is signaled and the
current estimate of the integral is returned.  The property
@qcode{"MaxIntervalCount"} can be used to alter the number of subintervals
that can exist before exiting.

@item WayPoints
Discontinuities in the first derivative of the function to integrate can be
flagged with the @qcode{"WayPoints"} property.  This forces the ends of a
subinterval to fall on the breakpoints of the function and can result in
significantly improved estimation of the error in the integral, faster
computation, or both.  For example,

@example
quadgk (@@(x) abs (1 - x.^2), 0, 2, "Waypoints", 1)
@end example

@noindent
signals the breakpoint in the integrand at @code{@var{x} = 1}.

@item Trace
If logically true @code{quadgk} prints information on the convergence of the
quadrature at each iteration.
@end table

If any of @var{a}, @var{b}, or @var{waypoints} is complex then the
quadrature is treated as a contour integral along a piecewise continuous
path defined by the above.  In this case the integral is assumed to have no
edge singularities.  For example,

@example
@group
quadgk (@@(z) log (z), 1+1i, 1+1i, "WayPoints",
        [1-1i, -1,-1i, -1+1i])
@end group
@end example

@noindent
integrates @code{log (z)} along the square defined by
@code{[1+1i, 1-1i, -1-1i, -1+1i]}.

The result of the integration is returned in @var{q}.

@var{err} is an approximate bound on the error in the integral
@code{abs (@var{q} - @var{I})}, where @var{I} is the exact value of the
integral.

Reference: @nospell{L.F. Shampine},
@cite{"Vectorized adaptive quadrature in @sc{matlab}"}, Journal of
Computational and Applied Mathematics, pp. 131--140, Vol 211, Issue 2,
Feb 2008.

@xseealso{quad, quadv, quadl, quadcc, trapz, dblquad, triplequad, integral,
          integral2, integral3}
@end deftypefn
quadl
@c quadl scripts/general/quadl.m
@deftypefn  {} {@var{q} =} quadl (@var{f}, @var{a}, @var{b})
@deftypefnx {} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol})
@deftypefnx {} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace})
@deftypefnx {} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace}, @var{p1}, @var{p2}, @dots{})
@deftypefnx {} {[@var{q}, @var{nfun}] =} quadl (@dots{})

Numerically evaluate the integral of @var{f} from @var{a} to @var{b} using
an adaptive @nospell{Lobatto} rule.

@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
return a vector of output values when given a vector of input values.

@var{a} and @var{b} are the lower and upper limits of integration.  Both
limits must be finite.

The optional argument @var{tol} defines the absolute tolerance with which
to perform the integration.  The default value is 1e-6.

The algorithm used by @code{quadl} involves recursively subdividing the
integration interval.  If @var{trace} is defined then for each subinterval
display: (1) the total number of function evaluations, (2) the left end of
the subinterval, (3) the length of the subinterval, (4) the approximation of
the integral over the subinterval.

Additional arguments @var{p1}, etc., are passed directly to the function
@var{f}.  To use default values for @var{tol} and @var{trace}, one may pass
empty matrices ([]).

The result of the integration is returned in @var{q}.

The optional output @var{nfun} indicates the total number of function
evaluations performed.

Reference: @nospell{W. Gander and W. Gautschi}, @cite{Adaptive Quadrature -
Revisited}, BIT Vol. 40, No. 1, March 2000, pp. 84--101.
@url{https://www.inf.ethz.ch/personal/gander/}
@xseealso{quad, quadv, quadgk, quadcc, trapz, dblquad, triplequad, integral,
         integral2, integral3}
@end deftypefn
quadv
@c quadv scripts/general/quadv.m
@deftypefn  {} {@var{q} =} quadv (@var{f}, @var{a}, @var{b})
@deftypefnx {} {@var{q} =} quadv (@var{f}, @var{a}, @var{b}, @var{tol})
@deftypefnx {} {@var{q} =} quadv (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace})
@deftypefnx {} {@var{q} =} quadv (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace}, @var{p1}, @var{p2}, @dots{})
@deftypefnx {} {[@var{q}, @var{nfun}] =} quadv (@dots{})

Numerically evaluate the integral of @var{f} from @var{a} to @var{b}
using an adaptive Simpson's rule.

@var{f} is a function handle, inline function, or string containing the name
of the function to evaluate.  @code{quadv} is a vectorized version of
@code{quad} and the function defined by @var{f} must accept a scalar or
vector as input and return a scalar, vector, or array as output.

@var{a} and @var{b} are the lower and upper limits of integration.  Both
limits must be finite.

The optional argument @var{tol} defines the absolute tolerance used to stop
the adaptation procedure.  The default value is 1e-6.

The algorithm used by @code{quadv} involves recursively subdividing the
integration interval and applying Simpson's rule on each subinterval.
If @var{trace} is true then after computing each of these partial
integrals display: (1) the total number of function evaluations,
(2) the left end of the subinterval, (3) the length of the subinterval,
(4) the approximation of the integral over the subinterval.

Additional arguments @var{p1}, etc., are passed directly to the function
@var{f}.  To use default values for @var{tol} and @var{trace}, one may pass
empty matrices ([]).

The result of the integration is returned in @var{q}.

The optional output @var{nfun} indicates the total number of function
evaluations performed.

Note: @code{quadv} is written in Octave's scripting language and can be
used recursively in @code{dblquad} and @code{triplequad}, unlike the
@code{quad} function.
@xseealso{quad, quadl, quadgk, quadcc, trapz, dblquad, triplequad, integral,
         integral2, integral3}
@end deftypefn
rad2deg
@c rad2deg scripts/general/rad2deg.m
@deftypefn {} {@var{deg} =} rad2deg (@var{rad})

Convert radians to degrees.

The input @var{rad} must be a scalar, vector, or N-dimensional array of
double or single floating point values.  @var{rad} may be complex in which
case the real and imaginary components are converted separately.

The output @var{deg} is the same size and shape as @var{rad} with radians
converted to degrees using the conversion constant @code{180/pi}.

Example:

@example
@group
rad2deg ([0, pi/2, pi, 3/2*pi, 2*pi])
  @result{}  0    90   180   270   360
@end group
@end example
@xseealso{deg2rad}
@end deftypefn
randi
@c randi scripts/general/randi.m
@deftypefn  {} {} randi (@var{imax})
@deftypefnx {} {} randi (@var{imax}, @var{n})
@deftypefnx {} {} randi (@var{imax}, @var{m}, @var{n}, @dots{})
@deftypefnx {} {} randi ([@var{imin} @var{imax}], @dots{})
@deftypefnx {} {} randi (@dots{}, "@var{class}")
Return random integers in the range 1:@var{imax}.

Additional arguments determine the shape of the return matrix.  When no
arguments are specified a single random integer is returned.  If one
argument @var{n} is specified then a square matrix @w{(@var{n} x @var{n})}
is returned.  Two or more arguments will return a multi-dimensional matrix
@w{(@var{m} x @var{n} x @dots{})}.

The integer range may optionally be described by a two element matrix with a
lower and upper bound in which case the returned integers will be on the
interval @w{[@var{imin}, @var{imax}]}.

The optional argument @var{class} will return a matrix of the requested
type.  The default is @qcode{"double"}.

The following example returns 150 integers in the range 1--10.

@example
ri = randi (10, 150, 1)
@end example

Implementation Note: @code{randi} relies internally on @code{rand} which
uses class @qcode{"double"} to represent numbers.  This limits the maximum
integer (@var{imax}) and range (@var{imax} - @var{imin}) to the value
returned by the @code{flintmax} function.  For IEEE floating point numbers
this value is @w{@math{2^{53} - 1}}.

@xseealso{rand}
@end deftypefn
rat
@c rat scripts/general/rat.m
@deftypefn  {} {@var{s} =} rat (@var{x})
@deftypefnx {} {@var{s} =} rat (@var{x}, @var{tol})
@deftypefnx {} {[@var{n}, @var{d}] =} rat (@dots{})

Find a rational approximation of @var{x} to within the tolerance defined by
@var{tol}.

If unspecified, the default tolerance is @code{1e-6 * norm (@var{x}(:), 1)}.

When called with one output argument, return a string containing a
continued fraction expansion (multiple terms).

When called with two output arguments, return numeric matrices for the
numerator and denominator of a fractional representation of @var{x} such
that @code{@var{x} = @var{n} ./ @var{d}}.

For example:

@example
@group
s = rat (pi)
@result{} s = 3 + 1/(7 + 1/16)

[n, d] = rat (pi)
@result{} n =  355
@result{} d =  113

n / d - pi
@result{} 0.00000026676
@end group
@end example

Programming Note: With one output @code{rat} produces a string which is a
continued fraction expansion.  To produce a string which is a simple
fraction (one numerator, one denominator) use @code{rats}.

@xseealso{rats, format}
@end deftypefn
repelem
@c repelem scripts/general/repelem.m
@deftypefn  {} {@var{xxx} =} repelem (@var{x}, @var{R})
@deftypefnx {} {@var{xxx} =} repelem (@var{x}, @var{R_1}, @dots{}, @var{R_n})
Construct an array of repeated elements from @var{x} and repeat
instructions @var{R_1}, @dots{}.

@var{x} must be a scalar, vector, or N-dimensional array.

A repeat instruction @var{R_j} must either be a scalar or a vector.  If the
instruction is a scalar then each component of @var{x} in dimension @var{j}
is repeated @var{R_j} times.  If the instruction is a vector then it must
have the same number of elements as the corresponding dimension @var{j} of
@var{x}.  In this case, the @var{k}th component of dimension @var{j} is
repeated @code{@var{R_j}(@var{k})} times.

If @var{x} is a scalar or vector then @code{repelem} may be called with just
a single repeat instruction @var{R} and @code{repelem} will return a vector
with the same orientation as the input.

If @var{x} is a matrix then at least two @var{R_j}s must be specified.

Note: Using @code{repelem} with a vector @var{x} and a vector for @var{R_j}
is equivalent to Run Length Decoding.

Examples:

@example
@group
A = [1 2 3 4 5];
B = [2 1 0 1 2];
repelem (A, B)
  @result{}   1   1   2   4   5   5
@end group
@end example

@example
@group
A = magic (3)
  @result{} A =
       8   1   6
       3   5   7
       4   9   2
B1 = [1 2 3];
B2 = 2;
repelem (A, B1, B2)
  @result{}     8   8   1   1   6   6
         3   3   5   5   7   7
         3   3   5   5   7   7
         4   4   9   9   2   2
         4   4   9   9   2   2
         4   4   9   9   2   2
@end group
@end example

More @var{R_j} may be specified than the number of dimensions of @var{x}.
Any excess @var{R_j} must be scalars (because @var{x}'s size in those
dimensions is only 1), and @var{x} will be replicated in those dimensions
accordingly.

@example
@group
A = [1 2 3 4 5];
B1 = 2;
B2 = [2 1 3 0 2];
B3 = 3;
repelem (A, B1, B2, B3)
  @result{}    ans(:,:,1) =
           1   1   2   3   3   3   5   5
           1   1   2   3   3   3   5   5

        ans(:,:,2) =

           1   1   2   3   3   3   5   5
           1   1   2   3   3   3   5   5

        ans(:,:,3) =
           1   1   2   3   3   3   5   5
           1   1   2   3   3   3   5   5
@end group
@end example

@var{R_j} must be specified in order.  A placeholder of 1 may be used for
dimensions which do not need replication.

@example
@group
repelem ([-1, 0; 0, 1], 1, 2, 1, 2)
  @result{}  ans(:,:,1,1) =
        -1  -1   0   0
         0   0   1   1

      ans(:,:,1,2) =
        -1  -1   0   0
         0   0   1   1
@end group
@end example

If fewer @var{R_j} are given than the number of dimensions in @var{x},
@code{repelem} will assume @var{R_j} is 1 for those dimensions.

@example
A = cat (3, [-1 0; 0 1], [-1 0; 0 1])
  @result{}  ans(:,:,1) =
        -1   0
         0   1

      ans(:,:,2) =
        -1   0
         0   1

repelem (A,2,3)
  @result{}  ans(:,:,1) =
        -1  -1  -1   0   0   0
        -1  -1  -1   0   0   0
         0   0   0   1   1   1
         0   0   0   1   1   1

      ans(:,:,2) =
        -1  -1  -1   0   0   0
        -1  -1  -1   0   0   0
         0   0   0   1   1   1
         0   0   0   1   1   1
@end example

@code{repelem} preserves the class of @var{x}, and works with strings,
cell arrays, NA, and NAN inputs.  If any @var{R_j} is 0 the output will
be an empty array.

@example
@group
repelem ("Octave", 2, 3)
  @result{}    OOOccctttaaavvveee
        OOOccctttaaavvveee

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

@xseealso{cat, kron, repmat}
@end deftypefn
repmat
@c repmat scripts/general/repmat.m
@deftypefn  {} {} repmat (@var{A}, @var{m})
@deftypefnx {} {} repmat (@var{A}, @var{m}, @var{n})
@deftypefnx {} {} repmat (@var{A}, @var{m}, @var{n}, @var{p} @dots{})
@deftypefnx {} {} repmat (@var{A}, [@var{m} @var{n}])
@deftypefnx {} {} repmat (@var{A}, [@var{m} @var{n} @var{p} @dots{}])
Repeat matrix or N-D array.

Form a block matrix of size @var{m} by @var{n}, with a copy of matrix
@var{A} as each element.

If @var{n} is not specified, form an @var{m} by @var{m} block matrix.  For
copying along more than two dimensions, specify the number of times to copy
across each dimension @var{m}, @var{n}, @var{p}, @dots{}, in a vector in the
second argument.

@xseealso{bsxfun, kron, repelems}
@end deftypefn
rot90
@c rot90 scripts/general/rot90.m
@deftypefn  {} {} rot90 (@var{A})
@deftypefnx {} {} rot90 (@var{A}, @var{k})
Rotate array by 90 degree increments.

Return a copy of @var{A} with the elements rotated counterclockwise in
90-degree increments.

The second argument is optional, and specifies how many 90-degree rotations
are to be applied (the default value is 1).  Negative values of @var{k}
rotate the matrix in a clockwise direction.
For example,

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

@noindent
rotates the given matrix clockwise by 90 degrees.  The following are all
equivalent statements:

@example
@group
rot90 ([1, 2; 3, 4], -1)
rot90 ([1, 2; 3, 4], 3)
rot90 ([1, 2; 3, 4], 7)
@end group
@end example

The rotation is always performed on the plane of the first two dimensions,
i.e., rows and columns.  To perform a rotation on any other plane, use
@code{rotdim}.

@xseealso{rotdim, fliplr, flipud, flip}
@end deftypefn
rotdim
@c rotdim scripts/general/rotdim.m
@deftypefn  {} {} rotdim (@var{x})
@deftypefnx {} {} rotdim (@var{x}, @var{n})
@deftypefnx {} {} rotdim (@var{x}, @var{n}, @var{plane})
Return a copy of @var{x} with the elements rotated counterclockwise in
90-degree increments.

The second argument @var{n} is optional, and specifies how many 90-degree
rotations are to be applied (the default value is 1).  Negative values of
@var{n} rotate the matrix in a clockwise direction.

The third argument is also optional and defines the plane of the rotation.
If present, @var{plane} is a two element vector containing two different
valid dimensions of the matrix.  When @var{plane} is not given the first two
non-singleton dimensions are used.

For example,

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

@noindent
rotates the given matrix clockwise by 90 degrees.  The following are all
equivalent statements:

@example
@group
rotdim ([1, 2; 3, 4], -1, [1, 2])
rotdim ([1, 2; 3, 4], 3, [1, 2])
rotdim ([1, 2; 3, 4], 7, [1, 2])
@end group
@end example
@xseealso{rot90, fliplr, flipud, flip}
@end deftypefn
shift
@c shift scripts/general/shift.m
@deftypefn  {} {} shift (@var{x}, @var{b})
@deftypefnx {} {} shift (@var{x}, @var{b}, @var{dim})
If @var{x} is a vector, perform a circular shift of length @var{b} of
the elements of @var{x}.

If @var{x} is a matrix, do the same for each column of @var{x}.

If the optional @var{dim} argument is given, operate along this dimension.
@end deftypefn
shiftdim
@c shiftdim scripts/general/shiftdim.m
@deftypefn  {} {@var{y} =} shiftdim (@var{x}, @var{n})
@deftypefnx {} {[@var{y}, @var{ns}] =} shiftdim (@var{x})
Shift the dimensions of @var{x} by @var{n}, where @var{n} must be
an integer scalar.

When @var{n} is positive, the dimensions of @var{x} are shifted to the left,
with the leading dimensions circulated to the end.  If @var{n} is negative,
then the dimensions of @var{x} are shifted to the right, with @var{n}
leading singleton dimensions added.

Called with a single argument, @code{shiftdim}, removes the leading
singleton dimensions, returning the number of dimensions removed in the
second output argument @var{ns}.

For example:

@example
@group
x = ones (1, 2, 3);
size (shiftdim (x, -1))
  @result{}   1   1   2   3
size (shiftdim (x, 1))
  @result{}   2   3
[b, ns] = shiftdim (x)
  @result{} b =
        1   1   1
        1   1   1
  @result{} ns = 1
@end group
@end example
@xseealso{reshape, permute, ipermute, circshift, squeeze}
@end deftypefn
sortrows
@c sortrows scripts/general/sortrows.m
@deftypefn  {} {[@var{s}, @var{i}] =} sortrows (@var{A})
@deftypefnx {} {[@var{s}, @var{i}] =} sortrows (@var{A}, @var{c})
Sort the rows of the matrix @var{A} according to the order of the columns
specified in @var{c}.

By default (@var{c} omitted, or a particular column unspecified in @var{c})
an ascending sort order is used.  However, if elements of @var{c} are
negative then the corresponding column is sorted in descending order.  If
the elements of @var{A} are strings then a lexicographical sort is used.

Example: sort by column 2 in descending order, then 3 in ascending order

@example
@group
x = [ 7, 1, 4;
      8, 3, 5;
      9, 3, 6 ];
sortrows (x, [-2, 3])
   @result{} 8  3  5
      9  3  6
      7  1  4
@end group
@end example

@xseealso{sort}
@end deftypefn
sph2cart
@c sph2cart scripts/general/sph2cart.m
@deftypefn  {} {[@var{x}, @var{y}, @var{z}] =} sph2cart (@var{theta}, @var{phi}, @var{r})
@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} sph2cart (@var{S})
@deftypefnx {} {@var{C} =} sph2cart (@dots{})
Transform spherical coordinates to Cartesian coordinates.

The inputs @var{theta}, @var{phi}, and @var{r} must be the same shape, or
scalar.  If called with a single matrix argument then each row of @var{S}
represents the spherical coordinate (@var{theta}, @var{phi}, @var{r}).

@var{theta} describes the angle relative to the positive x-axis.

@var{phi} is the angle relative to the xy-plane.

@var{r} is the distance to the origin @w{(0, 0, 0)}.

If only a single return argument is requested then return a matrix @var{C}
where each row represents one Cartesian coordinate
(@var{x}, @var{y}, @var{z}).
@xseealso{cart2sph, pol2cart, cart2pol}
@end deftypefn
structfun
@c structfun scripts/general/structfun.m
@deftypefn  {} {} structfun (@var{func}, @var{S})
@deftypefnx {} {[@var{A}, @dots{}] =} structfun (@dots{})
@deftypefnx {} {} structfun (@dots{}, "ErrorHandler", @var{errfunc})
@deftypefnx {} {} structfun (@dots{}, "UniformOutput", @var{val})

Evaluate the function named @var{name} on the fields of the structure
@var{S}.  The fields of @var{S} are passed to the function @var{func}
individually.

@code{structfun} accepts an arbitrary function @var{func} in the form of an
inline function, function handle, or the name of a function (in a character
string).  In the case of a character string argument, the function must
accept a single argument named @var{x}, and it must return a string value.
If the function returns more than one argument, they are returned as
separate output variables.

If the parameter @qcode{"UniformOutput"} is set to true (the default), then
the function must return a single element which will be concatenated into
the return value.  If @qcode{"UniformOutput"} is false, the outputs are
placed into a structure with the same fieldnames as the input structure.

@example
@group
s.name1 = "John Smith";
s.name2 = "Jill Jones";
structfun (@@(x) regexp (x, '(\w+)$', "matches")@{1@}, s,
           "UniformOutput", false)
  @result{} scalar structure containing the fields:
       name1 = Smith
       name2 = Jones
@end group
@end example

Given the parameter @qcode{"ErrorHandler"}, @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{se}, @dots{})
@end example

@noindent
where there is an additional input argument to @var{errfunc} relative to
@var{func}, given by @nospell{@var{se}}.  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 an
example on how to use an error handler, @pxref{XREFcellfun,,cellfun}.

@xseealso{cellfun, arrayfun, spfun}
@end deftypefn
subsindex
@c subsindex scripts/general/subsindex.m
@deftypefn {} {@var{idx} =} subsindex (@var{obj})
Convert an object to an index vector.

When @var{obj} is a class object defined with a class constructor, then
@code{subsindex} is the overloading method that allows the conversion of
this class object to a valid indexing vector.  It is important to note that
@code{subsindex} must return a zero-based real integer vector of the class
@qcode{"double"}.  For example, if the class constructor were

@example
@group
function obj = myclass (a)
  obj = class (struct ("a", a), "myclass");
endfunction
@end group
@end example

@noindent
then the @code{subsindex} function

@example
@group
function idx = subsindex (obj)
  idx = double (obj.a) - 1.0;
endfunction
@end group
@end example

@noindent
could be used as follows

@example
@group
a = myclass (1:4);
b = 1:10;
b(a)
@result{} 1  2  3  4
@end group
@end example

@xseealso{class, subsref, subsasgn}
@end deftypefn
trapz
@c trapz scripts/general/trapz.m
@deftypefn  {} {@var{q} =} trapz (@var{y})
@deftypefnx {} {@var{q} =} trapz (@var{x}, @var{y})
@deftypefnx {} {@var{q} =} trapz (@dots{}, @var{dim})

Numerically evaluate the integral of points @var{y} using the trapezoidal
method.

@w{@code{trapz (@var{y})}} computes the integral of @var{y} along the first
non-singleton dimension.  When the argument @var{x} is omitted an equally
spaced @var{x} vector with unit spacing (1) is assumed.
@code{trapz (@var{x}, @var{y})} evaluates the integral with respect to the
spacing in @var{x} and the values in @var{y}.  This is useful if the points
in @var{y} have been sampled unevenly.

If the optional @var{dim} argument is given, operate along this dimension.

Application Note: If @var{x} is not specified then unit spacing will be
used.  To scale the integral to the correct value you must multiply by the
actual spacing value (deltaX).  As an example, the integral of @math{x^3}
over the range [0, 1] is @math{x^4/4} or 0.25.  The following code uses
@code{trapz} to calculate the integral in three different ways.

@example
@group
x = 0:0.1:1;
y = x.^3;
## No scaling
q = trapz (y)
  @result{} q = 2.5250
## Approximation to integral by scaling
q * 0.1
  @result{} 0.25250
## Same result by specifying @var{x}
trapz (x, y)
  @result{} 0.25250
@end group
@end example

@xseealso{cumtrapz}
@end deftypefn
triplequad
@c triplequad scripts/general/triplequad.m
@deftypefn  {} {} triplequad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{za}, @var{zb})
@deftypefnx {} {} triplequad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{za}, @var{zb}, @var{tol})
@deftypefnx {} {} triplequad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{za}, @var{zb}, @var{tol}, @var{quadf})
@deftypefnx {} {} triplequad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{za}, @var{zb}, @var{tol}, @var{quadf}, @dots{})
Numerically evaluate the triple integral of @var{f}.

@var{f} is a function handle, inline function, or string containing the name
of the function to evaluate.  The function @var{f} must have the form
@math{w = f(x,y,z)} where either @var{x} or @var{y} is a vector and the
remaining inputs are scalars.  It should return a vector of the same length
and orientation as @var{x} or @var{y}.

@var{xa}, @var{ya}, @var{za} and @var{xb}, @var{yb}, @var{zb} are the lower
and upper limits of integration for x, y, and z respectively.  The
underlying integrator determines whether infinite bounds are accepted.

The optional argument @var{tol} defines the absolute tolerance used to
integrate each sub-integral.  The default value is 1e-6.

The optional argument @var{quadf} specifies which underlying integrator
function to use.  Any choice but @code{quad} is available and the default
is @code{quadcc}.

Additional arguments, are passed directly to @var{f}.  To use the default
value for @var{tol} or @var{quadf} one may pass @qcode{':'} or an empty
matrix ([]).
@xseealso{integral3, integral2, dblquad, quad, quadv, quadl, quadgk, quadcc,
         trapz}
@end deftypefn
xor
@c xor scripts/general/xor.m
@deftypefn  {} {@var{z} =} xor (@var{x}, @var{y})
@deftypefnx {} {@var{z} =} xor (@var{x1}, @var{x2}, @dots{})
Return the @dfn{exclusive or} of @var{x} and @var{y}.

For boolean expressions @var{x} and @var{y},
@code{xor (@var{x}, @var{y})} is true if and only if one of @var{x} or
@var{y} is true.  Otherwise, if @var{x} and @var{y} are both true or both
false, @code{xor} returns false.

The truth table for the xor operation is

@multitable @columnfractions 0.44 .03 .05 .03 0.44
@item @tab @var{x} @tab @var{y} @tab @var{z} @tab
@item @tab - @tab - @tab - @tab
@item @tab 0 @tab 0 @tab 0 @tab
@item @tab 1 @tab 0 @tab 1 @tab
@item @tab 0 @tab 1 @tab 1 @tab
@item @tab 1 @tab 1 @tab 0 @tab
@end multitable

If more than two arguments are given the xor operation is applied
cumulatively from left to right:

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

@xseealso{and, or, not}
@end deftypefn
convhull
@c convhull scripts/geometry/convhull.m
@deftypefn  {} {@var{H} =} convhull (@var{x}, @var{y})
@deftypefnx {} {@var{H} =} convhull (@var{x}, @var{y}, @var{z})
@deftypefnx {} {@var{H} =} convhull (@var{x})
@deftypefnx {} {@var{H} =} convhull (@dots{}, @var{options})
@deftypefnx {} {[@var{H}, @var{V}] =} convhull (@dots{})
Compute the convex hull of a 2-D or 3-D set of points.

The hull @var{H} is a linear index vector into the original set of points
that specifies which points form the enclosing hull.  For 2-D inputs only,
the output is ordered in a counterclockwise manner around the hull.

The input @var{x} may also be a matrix with two or three columns where the
first column contains x-data, the second y-data, and the optional third
column contains z-data.

An optional final 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 option is @code{@{"Qt"@}}.

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.

@xseealso{convhulln, delaunay, voronoi}
@end deftypefn
delaunay
@c delaunay scripts/geometry/delaunay.m
@deftypefn  {} {@var{tri} =} delaunay (@var{x}, @var{y})
@deftypefnx {} {@var{tetr} =} delaunay (@var{x}, @var{y}, @var{z})
@deftypefnx {} {@var{tri} =} delaunay (@var{x})
@deftypefnx {} {@var{tri} =} delaunay (@dots{}, @var{options})
Compute the Delaunay triangulation for a 2-D or 3-D set of points.

For 2-D sets, the return value @var{tri} is a set of triangles which
satisfies the Delaunay circum-circle criterion, i.e., no data point from
[@var{x}, @var{y}] is within the circum-circle of the defining triangle.
The set of triangles @var{tri} is a matrix of size [n, 3].  Each row defines
a triangle and the three columns are the three vertices of the triangle.
The value of @code{@var{tri}(i,j)} is an index into @var{x} and @var{y} for
the location of the j-th vertex of the i-th triangle.

For 3-D sets, the return value @var{tetr} is a set of tetrahedrons which
satisfies the Delaunay circum-circle criterion, i.e., no data point from
[@var{x}, @var{y}, @var{z}] is within the circum-circle of the defining
tetrahedron.  The set of tetrahedrons is a matrix of size [n, 4].  Each row
defines a tetrahedron and the four columns are the four vertices of the
tetrahedron.  The value of @code{@var{tetr}(i,j)} is an index into @var{x},
@var{y}, @var{z} for the location of the j-th vertex of the i-th
tetrahedron.

The input @var{x} may also be a matrix with two or three columns where the
first column contains x-data, the second y-data, and the optional third
column contains z-data.

An optional final 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 are @code{@{"Qt", "Qbb", "Qc", "Qz"@}}.

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.

@example
@group
x = rand (1, 10);
y = rand (1, 10);
tri = delaunay (x, y);
triplot (tri, x, y);
hold on;
plot (x, y, "r*");
axis ([0,1,0,1]);
@end group
@end example
@xseealso{delaunayn, convhull, voronoi, triplot, trimesh, tetramesh, trisurf}
@end deftypefn
delaunayn
@c delaunayn scripts/geometry/delaunayn.m
@deftypefn  {} {@var{T} =} delaunayn (@var{pts})
@deftypefnx {} {@var{T} =} delaunayn (@var{pts}, @var{options})
Compute the Delaunay triangulation for an N-dimensional set of points.

The Delaunay triangulation is a tessellation of the convex hull of a set of
points such that no N-sphere defined by the N-triangles contains any other
points from the set.

The input matrix @var{pts} of size [n, dim] contains n points in a space of
dimension dim.  The return matrix @var{T} has size [m, dim+1].  Each row of
@var{T} contains a set of indices back into the original set of points
@var{pts} which describes a simplex of dimension dim.  For example, a 2-D
simplex is a triangle and 3-D simplex is a tetrahedron.

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 2-D and 3-D: @var{options} = @code{@{"Qt", "Qbb", "Qc", "Qz"@}}

@item 4-D and higher: @var{options} = @code{@{"Qt", "Qbb", "Qc", "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.

@xseealso{delaunay, convhulln, voronoin, trimesh, tetramesh}
@end deftypefn
dsearch
@c dsearch scripts/geometry/dsearch.m
@deftypefn  {} {@var{idx} =} dsearch (@var{x}, @var{y}, @var{tri}, @var{xi}, @var{yi})
@deftypefnx {} {@var{idx} =} dsearch (@var{x}, @var{y}, @var{tri}, @var{xi}, @var{yi}, @var{s})
Return the index @var{idx} of the closest point in @code{@var{x}, @var{y}}
to the elements @code{[@var{xi}(:), @var{yi}(:)]}.

The variable @var{s} is accepted for compatibility but is ignored.
@xseealso{dsearchn, tsearch}
@end deftypefn
dsearchn
@c dsearchn scripts/geometry/dsearchn.m
@deftypefn  {} {@var{idx} =} dsearchn (@var{x}, @var{tri}, @var{xi})
@deftypefnx {} {@var{idx} =} dsearchn (@var{x}, @var{tri}, @var{xi}, @var{outval})
@deftypefnx {} {@var{idx} =} dsearchn (@var{x}, @var{xi})
@deftypefnx {} {[@var{idx}, @var{d}] =} dsearchn (@dots{})
Return the index @var{idx} of the closest point in @var{x} to the elements
@var{xi}.

If @var{outval} is supplied, then the values of @var{xi} that are not
contained within one of the simplices @var{tri} are set to @var{outval}.
Generally, @var{tri} is returned from @code{delaunayn (@var{x})}.
@xseealso{dsearch, tsearch}
@end deftypefn
griddata
@c griddata scripts/geometry/griddata.m
@deftypefn  {} {@var{zi} =} griddata (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi})
@deftypefnx {} {@var{zi} =} griddata (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi}, @var{method})
@deftypefnx {} {[@var{xi}, @var{yi}, @var{zi}] =} griddata (@dots{})

Generate a regular mesh from irregular data using interpolation.

The function is defined by @code{@var{z} = f (@var{x}, @var{y})}.  Inputs
@code{@var{x}, @var{y}, @var{z}} are vectors of the same length or
@code{@var{x}, @var{y}} are vectors and @code{@var{z}} is matrix.

The interpolation points are all @code{(@var{xi}, @var{yi})}.  If @var{xi},
@var{yi} are vectors then they are made into a 2-D mesh.

The interpolation method can be @qcode{"nearest"}, @qcode{"cubic"} or
@qcode{"linear"}.  If method is omitted it defaults to @qcode{"linear"}.
@xseealso{griddata3, griddatan, delaunay}
@end deftypefn
griddata3
@c griddata3 scripts/geometry/griddata3.m
@deftypefn  {} {@var{vi} =} griddata3 (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {} {@var{vi} =} griddata3 (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi}, @var{method})
@deftypefnx {} {@var{vi} =} griddata3 (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi}, @var{method}, @var{options})

Generate a regular mesh from irregular data using interpolation.

The function is defined by @code{@var{v} = f (@var{x}, @var{y}, @var{z})}.
The interpolation points are specified by @var{xi}, @var{yi}, @var{zi}.

The interpolation method can be @qcode{"nearest"} or @qcode{"linear"}.
If method is omitted it defaults to @qcode{"linear"}.

The optional argument @var{options} is passed directly to Qhull when
computing the Delaunay triangulation used for interpolation.  See
@code{delaunayn} for information on the defaults and how to pass different
values.
@xseealso{griddata, griddatan, delaunayn}
@end deftypefn
griddatan
@c griddatan scripts/geometry/griddatan.m
@deftypefn  {} {@var{yi} =} griddatan (@var{x}, @var{y}, @var{xi})
@deftypefnx {} {@var{yi} =} griddatan (@var{x}, @var{y}, @var{xi}, @var{method})
@deftypefnx {} {@var{yi} =} griddatan (@var{x}, @var{y}, @var{xi}, @var{method}, @var{options})

Generate a regular mesh from irregular data using interpolation.

The function is defined by @code{@var{y} = f (@var{x})}.
The interpolation points are all @var{xi}.

The interpolation method can be @qcode{"nearest"} or @qcode{"linear"}.
If method is omitted it defaults to @qcode{"linear"}.

The optional argument @var{options} is passed directly to Qhull when
computing the Delaunay triangulation used for interpolation.  See
@code{delaunayn} for information on the defaults and how to pass different
values.
@xseealso{griddata, griddata3, delaunayn}
@end deftypefn
inpolygon
@c inpolygon scripts/geometry/inpolygon.m
@deftypefn  {} {@var{in} =} inpolygon (@var{x}, @var{y}, @var{xv}, @var{yv})
@deftypefnx {} {[@var{in}, @var{on}] =} inpolygon (@var{x}, @var{y}, @var{xv}, @var{yv})

For a polygon defined by vertex points @code{(@var{xv}, @var{yv})}, return
true if the points @code{(@var{x}, @var{y})} are inside (or on the boundary)
of the polygon; Otherwise, return false.

The input variables @var{x} and @var{y}, must have the same dimension.

The optional output @var{on} returns true if the points are exactly on the
polygon edge, and false otherwise.
@xseealso{delaunay}
@end deftypefn
rectint
@c rectint scripts/geometry/rectint.m
@deftypefn {} {@var{area} =} rectint (@var{a}, @var{b})
Compute area or volume of intersection of rectangles or N-D boxes.

Compute the area of intersection of rectangles in @var{a} and rectangles in
@var{b}.  N-dimensional boxes are supported in which case the volume, or
hypervolume is computed according to the number of dimensions.

2-dimensional rectangles are defined as @code{[xpos ypos width height]}
where xpos and ypos are the position of the bottom left corner.  Higher
dimensions are supported where the coordinates for the minimum value of each
dimension follow the length of the box in that dimension, e.g.,
@code{[xpos ypos zpos kpos @dots{} width height depth k_length @dots{}]}.

Each row of @var{a} and @var{b} define a rectangle, and if both define
multiple rectangles, then the output, @var{area}, is a matrix where the i-th
row corresponds to the i-th row of a and the j-th column corresponds to the
j-th row of b.

@xseealso{polyarea}
@end deftypefn
tsearchn
@c tsearchn scripts/geometry/tsearchn.m
@deftypefn  {} {@var{idx} =} tsearchn (@var{x}, @var{t}, @var{xi})
@deftypefnx {} {[@var{idx}, @var{p}] =} tsearchn (@var{x}, @var{t}, @var{xi})
Search for the enclosing Delaunay convex hull.

For @code{@var{t} = delaunayn (@var{x})}, finds the index in @var{t}
containing the points @var{xi}.  For points outside the convex hull,
@var{idx} is NaN.

If requested @code{tsearchn} also returns the Barycentric coordinates
@var{p} of the enclosing triangles.
@xseealso{delaunay, delaunayn}
@end deftypefn
voronoi
@c voronoi scripts/geometry/voronoi.m
@deftypefn  {} {} voronoi (@var{x}, @var{y})
@deftypefnx {} {} voronoi (@var{x}, @var{y}, @var{options})
@deftypefnx {} {} voronoi (@dots{}, "linespec")
@deftypefnx {} {} voronoi (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} voronoi (@dots{})
@deftypefnx {} {[@var{vx}, @var{vy}] =} voronoi (@dots{})
Plot the Voronoi diagram of points @code{(@var{x}, @var{y})}.

The Voronoi facets with points at infinity are not drawn.

The @var{options} 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}.

If @qcode{"linespec"} is given it is used to set the color and line style of
the plot.

If an axes graphics handle @var{hax} is supplied then the Voronoi diagram is
drawn on the specified axes rather than in a new figure.

If a single output argument is requested then the Voronoi diagram will be
plotted and a graphics handle @var{h} to the plot is returned.

[@var{vx}, @var{vy}] = voronoi (@dots{}) returns the Voronoi vertices
instead of plotting the diagram.

@example
@group
x = rand (10, 1);
y = rand (size (x));
h = convhull (x, y);
[vx, vy] = voronoi (x, y);
plot (vx, vy, "-b", x, y, "o", x(h), y(h), "-g");
legend ("", "points", "hull");
@end group
@end example

@xseealso{voronoin, delaunay, convhull}
@end deftypefn
voronoin
@c voronoin scripts/geometry/voronoin.m
@deftypefn  {} {[@var{C}, @var{F}] =} voronoin (@var{pts})
@deftypefnx {} {[@var{C}, @var{F}] =} voronoin (@var{pts}, @var{options})
Compute N-dimensional Voronoi facets.

The input matrix @var{pts} of size [n, dim] contains n points in a space of
dimension dim.

@var{C} contains the points of the Voronoi facets.  The list @var{F}
contains, for each facet, the indices of the Voronoi points.

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 2-D and 3-D: @var{options} = @code{@{"Qbb"@}}

@item 4-D and higher: @var{options} = @code{@{"Qbb", "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.

@xseealso{voronoi, convhulln, delaunayn}
@end deftypefn
dialog
@c dialog scripts/gui/dialog.m
@deftypefn  {} {@var{h} =} dialog ()
@deftypefnx {} {@var{h} =} dialog ("@var{property}", @var{value}, @dots{})

Create an empty modal dialog window to which other uicontrols can be added.

The dialog box is a figure object with properties as recommended for a
dialog box.

The default properties differing from a figure are:

@table @asis
@item buttondownfcn
@code{if isempty (allchild(gcbf)), close (gcbf), endif}

@item colormap
[]

@item color
defaultuicontrolbackgroundcolor

@item dockcontrols
off

@item handlevisibility
callback

@item integerhandle
off

@item inverthardcopy
off

@item menubar
none

@item numbertitle
off

@item paperpositionmode
auto

@item resize
off

@item windowstyle
modal

@end table


Multiple property-value pairs may be specified for the dialog object, but
they must appear in pairs.

The return value @var{h} is a graphics handle to the created figure.

Example:

@example
@group
## create an empty dialog window titled "Dialog Example"
h = dialog ("name", "Dialog Example");

## create a button (default style)
b = uicontrol (h, "string", "OK",
                  "position", [10 10 150 40],
                  "callback", "delete (gcf)");

## wait for dialog to resume or close
uiwait (h);
@end group
@end example

@xseealso{errordlg, msgbox, questdlg, warndlg, figure, uiwait}
@end deftypefn
errordlg
@c errordlg scripts/gui/errordlg.m
@deftypefn  {} {} errordlg ()
@deftypefnx {} {} errordlg (@var{msg})
@deftypefnx {} {} errordlg (@var{msg}, @var{title})
@deftypefnx {} {} errordlg (@var{msg}, @var{title}, @var{opt})
@deftypefnx {} {@var{h} =} errordlg (@dots{})
Display an error dialog box with error message @var{msg} and caption
@var{title}.

The default error message is @qcode{"This is the default error string.@:"}
and the default caption is @qcode{"Error Dialog"}.

The error message may have multiple lines separated by newline characters
("\n"), or it may be a cellstr array with one element for each line.

The third optional argument @var{opt} controls the behavior of the dialog.
See @code{msgbox} for details.

The return value @var{h} is a handle to the figure object used for
building the dialog.

Examples:

@example
@group
errordlg ("Some fancy error occurred.");
errordlg ("Some fancy error\nwith two lines.");
errordlg (@{"Some fancy error", "with two lines."@});
errordlg ("Some fancy error occurred.", "Fancy caption");
@end group
@end example

@xseealso{helpdlg, warndlg, msgbox, inputdlg, listdlg, questdlg}
@end deftypefn
getappdata
@c getappdata scripts/gui/getappdata.m
@deftypefn  {} {@var{value} =} getappdata (@var{h}, @var{name})
@deftypefnx {} {@var{appdata} =} getappdata (@var{h})
Return the @var{value} of the application data @var{name} for the graphics
object with handle @var{h}.

@var{h} may also be a vector of graphics handles.  If no second argument
@var{name} is given then @code{getappdata} returns a structure,
@var{appdata}, whose fields correspond to the appdata properties.

@xseealso{setappdata, isappdata, rmappdata, guidata, get, set, getpref, setpref}
@end deftypefn
guidata
@c guidata scripts/gui/guidata.m
@deftypefn  {} {@var{data} =} guidata (@var{h})
@deftypefnx {} {} guidata (@var{h}, @var{data})
Query or set user-custom GUI data.

The GUI data is stored in the figure handle @var{h}.  If @var{h} is not a
figure handle then it's parent figure will be used for storage.

@var{data} must be a single object which means it is usually preferable
for it to be a data container such as a cell array or struct so that
additional data items can be added easily.

@xseealso{getappdata, setappdata, get, set, getpref, setpref}
@end deftypefn
guihandles
@c guihandles scripts/gui/guihandles.m
@deftypefn  {} {@var{hdata} =} guihandles (@var{h})
@deftypefnx {} {@var{hdata} =} guihandles
Return a structure of object handles for the figure associated with
handle @var{h}.

If no handle is specified the current figure returned by @code{gcf} is used.

The fieldname for each entry of @var{hdata} is taken from the @qcode{"tag"}
property of the graphic object.  If the tag is empty then the handle is not
returned.  If there are multiple graphic objects with the same tag then
the entry in @var{hdata} will be a vector of handles.  @code{guihandles}
includes all possible handles, including those for
which @qcode{"HandleVisibility"} is @qcode{"off"}.
@xseealso{guidata, findobj, findall, allchild}
@end deftypefn
helpdlg
@c helpdlg scripts/gui/helpdlg.m
@deftypefn  {} {} helpdlg ()
@deftypefnx {} {} helpdlg (@var{msg})
@deftypefnx {} {} helpdlg (@var{msg}, @var{title})
@deftypefnx {} {@var{h} =} helpdlg (@dots{})
Display a help dialog box with help message @var{msg} and caption
@var{title}.

The default help message is @qcode{"This is the default help string.@:"}
and the default caption is @qcode{"Help Dialog"}.

The help message may have multiple lines separated by newline characters
("\n"), or it may be a cellstr array with one element for each line.

The return value @var{h} is a handle to the figure object used for
building the dialog.

Examples:

@example
@group
helpdlg ("Some helpful text for the user.");
helpdlg ("Some helpful text\nwith two lines.");
helpdlg (@{"Some helpful text", "with two lines."@});
helpdlg ("Some helpful text for the user.", "Fancy caption");
@end group
@end example

@xseealso{errordlg, warndlg, msgbox, inputdlg, listdlg, questdlg}
@end deftypefn
inputdlg
@c inputdlg scripts/gui/inputdlg.m
@deftypefn  {} {@var{cstr} =} inputdlg (@var{prompt})
@deftypefnx {} {@var{cstr} =} inputdlg (@var{prompt}, @var{title})
@deftypefnx {} {@var{cstr} =} inputdlg (@var{prompt}, @var{title}, @var{rowscols})
@deftypefnx {} {@var{cstr} =} inputdlg (@var{prompt}, @var{title}, @var{rowscols}, @var{defaults})
@deftypefnx {} {@var{cstr} =} inputdlg (@var{prompt}, @var{title}, @var{rowscols}, @var{defaults}, @var{options})
Return user input from a multi-textfield dialog box in a cell array of
strings, or an empty cell array if the dialog is closed by the Cancel
button.

Inputs:

@table @var
@item prompt
A cell array with strings labeling each text field.  This input is required.

@item title
String to use for the caption of the dialog.  The default is
@qcode{"Input Dialog"}.

@item rowscols
Specifies the size of the text fields and can take three forms:

@enumerate
@item a scalar value which defines the number of rows used for each text
field.

@item a vector which defines the individual number of rows used for each
text field.

@item a matrix which defines the individual number of rows and columns used
for each text field.  In the matrix each row describes a single text field.
The first column specifies the number of input rows to use and the second
column specifies the text field width.
@end enumerate

@item defaults
A list of default values to place in each text field.  It must be a cell
array of strings with the same size as @var{prompt}.

@item options
Not supported, only for @sc{matlab} compatibility.
@end table

Example:

@example
@group
prompt = @{"Width", "Height", "Depth"@};
defaults = @{"1.10", "2.20", "3.30"@};
rowscols = [1,10; 2,20; 3,30];
dims = inputdlg (prompt, "Enter Box Dimensions", ...
                 rowscols, defaults);
@end group
@end example

@xseealso{errordlg, helpdlg, listdlg, msgbox, questdlg, warndlg}
@end deftypefn
isappdata
@c isappdata scripts/gui/isappdata.m
@deftypefn {} {@var{valid} =} isappdata (@var{h}, @var{name})
Return true if the named application data, @var{name}, exists for the
graphics object with handle @var{h}.

@var{h} may also be a vector of graphics handles.
@xseealso{getappdata, setappdata, rmappdata, guidata, get, set, getpref, setpref}
@end deftypefn
listdlg
@c listdlg scripts/gui/listdlg.m
@deftypefn {} {[@var{sel}, @var{ok}] =} listdlg (@var{key}, @var{value}, @dots{})
Return user inputs from a list dialog box in a vector of selection indices
(@var{sel}) and a flag indicating how the user closed the dialog box
(@var{ok}).

The indices in @var{sel} are 1-based.

The value of @var{ok} is 1 if the user closed the box with the OK button,
otherwise it is 0 and @var{sel} is empty.

Input arguments are specified in form of @var{key}, @var{value} pairs.
The @qcode{"ListString"} argument pair @strong{must} be specified.

Valid @var{key} and @var{value} pairs are:

@table @asis
@item @qcode{"ListString"}
a cell array of strings specifying the items to list in the dialog.

@item @qcode{"SelectionMode"}
can be either @qcode{"Single"} (only one item may be selected at a time) or
@qcode{"Multiple"} (default).

@item @qcode{"ListSize"}
a two-element vector @code{[@var{width}, @var{height}]} specifying the size
of the list field in pixels.  The default is [160, 300].

@item @qcode{"InitialValue"}
a vector containing 1-based indices of elements which will be pre-selected
when the list dialog is first displayed.
The default is 1 (first item).

@item @qcode{"Name"}
a string to be used as the dialog caption.  Default is "".

@item @qcode{"PromptString"}
a cell array of strings to be displayed above the list of items.
Default is @{@}.

@item @qcode{"OKString"}
a string used to label the OK button.  Default is @qcode{"OK"}.

@item @qcode{"CancelString"}
a string used to label the Cancel button.  Default is @qcode{"Cancel"}.
@end table

Example:

@example
@group
my_options = @{"An item", "another", "yet another"@};
[sel, ok] = listdlg ("ListString", my_options,
                     "SelectionMode", "Multiple");
if (ok == 1)
  disp ("You selected:");
  for i = 1:numel (sel)
    disp (sprintf ("\t%s", my_options@{sel(i)@}));
  endfor
else
  disp ("You cancelled.");
endif
@end group
@end example

@xseealso{menu, errordlg, helpdlg, inputdlg, msgbox, questdlg, warndlg}
@end deftypefn
movegui
@c movegui scripts/gui/movegui.m
@deftypefn  {} {} movegui
@deftypefnx {} {} movegui (@var{h})
@deftypefnx {} {} movegui (@var{pos})
@deftypefnx {} {} movegui (@var{h}, @var{pos})
@deftypefnx {} {} movegui (@var{h}, @var{event})
@deftypefnx {} {} movegui (@var{h}, @var{event}, @var{pos})
Move a figure specified by figure handle @var{h} to a position on the screen
defined by @var{pos}.

@var{h} is a figure handle, or a handle to a graphics object.  In the latter
case, its parent figure will be used.  If unspecified, @var{h} will be
set to the handle of the relevant figure if a callback is being executed
(@code{gcbf}), otherwise it will be set to the handle of the current figure
(@code{gcf}).

@var{pos} is either a two-value numeric vector or a string.  If @var{pos} is
numeric then it must be of the form @code{[h, v]} specifying the horizontal
and vertical offsets of the figure with respect to the screen.  A positive
value indicates the offset between the left (or bottom for the vertical
component) of the screen, and the left (or bottom) of the figure.  A
negative value indicates the offset between the right (or top) of the screen
and the right (or top) of the figure.

Possible values for @var{pos} as a string are

@table @code
@item north
Top center of the screen.

@item south
Bottom center of the screen.

@item east
Right center of the screen.

@item west
Left center of the screen.

@item northeast
Top right of the screen.

@item northwest
Top left of the screen.

@item southeast
Bottom right of the screen.

@item southwest
Bottom left of the screen.

@item center
Center of the screen.

@item onscreen (default)
The figure will be minimally moved to be entirely visible on the screen,
with a 30 pixel extra padding from the sides of the screen.  This is the
default value if none is provided.
@end table

@var{event} contains event data that will be ignored.  This construct
facilitates a call to movegui from a callback.

@end deftypefn
msgbox
@c msgbox scripts/gui/msgbox.m
@deftypefn  {} {@var{h} =} msgbox (@var{msg})
@deftypefnx {} {@var{h} =} msgbox (@var{msg}, @var{title})
@deftypefnx {} {@var{h} =} msgbox (@var{msg}, @var{title}, @var{icon})
@deftypefnx {} {@var{h} =} msgbox (@var{msg}, @var{title}, "custom", @var{cdata})
@deftypefnx {} {@var{h} =} msgbox (@var{msg}, @var{title}, "custom", @var{cdata}, @var{colormap})
@deftypefnx {} {@var{h} =} msgbox (@dots{}, @var{opt})
Display @var{msg} using a message dialog box.

The message may have multiple lines separated by newline characters ("\n"),
or it may be a cellstr array with one element for each line.

The optional input @var{title} (character string) can be used to decorate
the dialog caption.

The optional argument @var{icon} selects a dialog icon.
It can be one of @qcode{"none"} (default), @qcode{"error"}, @qcode{"help"},
@qcode{"warn"}, or @qcode{"custom"}.  The latter must be followed by an
image array @var{cdata}, and for indexed images the associated colormap.

The final optional argument @var{opt} controls the behavior of the dialog.
If @var{opt} is a string, it may be one of

@table @asis
@item @qcode{"non-modal"} (default)
The dialog is normal.

@item @qcode{"modal"}
The dialog is displayed @qcode{"modal"} which means it prevents users from
interacting with any other GUI element until the dialog has been closed.

@item @qcode{"replace"}
If any dialogs already exist with the same title, the most recent is reused
and all others are closed.  The resulting dialog is set @qcode{"non-modal"}.
@end table

If @var{opt} is a structure, it must contain fields @qcode{"WindowStyle"}
and @qcode{"Interpreter"}:

@table @asis
@item @qcode{"WindowStyle"}
The value must be @qcode{"non-modal"}, @qcode{"modal"}, or
@qcode{"replace"}.  See above.

@item @qcode{"Interpreter"}
Controls the @qcode{"interpreter"} property of the text object used for
displaying the message.  The value must be @qcode{"tex"} (default),
@qcode{"none"}, or @qcode{"latex"}.
@end table

The return value @var{h} is a handle to the figure object used for building
the dialog.

Examples:

@example
@group
msgbox ("Some message for the user.");
msgbox ("Some message\nwith two lines.");
msgbox (@{"Some message", "with two lines."@});
msgbox ("Some message for the user.", "Fancy caption");

## A message dialog box with error icon
msgbox ("Some message for the user.", "Fancy caption", "error");
@end group
@end example

@xseealso{errordlg, helpdlg, inputdlg, listdlg, questdlg, warndlg}
@end deftypefn
questdlg
@c questdlg scripts/gui/questdlg.m
@deftypefn  {} {@var{btn} =} questdlg (@var{msg})
@deftypefnx {} {@var{btn} =} questdlg (@var{msg}, @var{title})
@deftypefnx {} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{default})
@deftypefnx {} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{default})
@deftypefnx {} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{btn3}, @var{default})
Display @var{msg} using a question dialog box and return the caption of
the activated button.

The message may have multiple lines separated by newline characters ("\n"),
or it may be a cellstr array with one element for each line.

The optional @var{title} (character string) can be used to specify the
dialog caption.  It defaults to @qcode{"Question Dialog"}.

The dialog may contain two or three buttons which will all close the dialog.

The string @var{default} identifies the default button, which is activated
by pressing the @key{ENTER} key.  It must match one of the strings given
in @var{btn1}, @var{btn2}, or @var{btn3}.

If only @var{msg} and @var{title} are specified, three buttons with the
default captions @qcode{"Yes"}, @qcode{"No"}, and @qcode{"Cancel"} are used.

If only two button captions, @var{btn1} and @var{btn2}, are specified the
dialog will have only these two buttons.

Examples:

@example
@group
btn = questdlg ("Close Octave?", "Some fancy title", ...
                "Yes", "No", "No");
if (strcmp (btn, "Yes"))
  exit ();
endif
@end group
@end example

@xseealso{errordlg, helpdlg, inputdlg, listdlg, msgbox, warndlg}
@end deftypefn
rmappdata
@c rmappdata scripts/gui/rmappdata.m
@deftypefn  {} {} rmappdata (@var{h}, @var{name})
@deftypefnx {} {} rmappdata (@var{h}, @var{name1}, @var{name2}, @dots{})
Delete the application data @var{name} from the graphics object with handle
@var{h}.

@var{h} may also be a vector of graphics handles.  Multiple application data
names may be supplied to delete several properties at once.

@xseealso{setappdata, getappdata, isappdata}
@end deftypefn
setappdata
@c setappdata scripts/gui/setappdata.m
@deftypefn  {} {} setappdata (@var{h}, @var{name}, @var{value})
@deftypefnx {} {} setappdata (@var{h}, @var{name1}, @var{value1}, @var{name2}, @var{value3}, @dots{})
@deftypefnx {} {} setappdata (@var{h}, @{@var{name1}, @var{name2}, @dots{}@}, @{@var{value1}, @var{value2}, @dots{}@})
Set the application data @var{name} to @var{value} for the graphics object
with handle @var{h}.

@var{h} may also be a vector of graphics handles.  If the application data
with the specified @var{name} does not exist, it is created.

Multiple @var{name}/@var{value} pairs can be specified.  Alternatively, a
cell array of @var{names} and a corresponding cell array of @var{values} can
be specified.

@xseealso{getappdata, isappdata, rmappdata, guidata, get, set, getpref, setpref}
@end deftypefn
uibuttongroup
@c uibuttongroup scripts/gui/uibuttongroup.m
@deftypefn  {} {@var{hui} =} uibuttongroup (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uibuttongroup (@var{parent}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} uibuttongroup (@var{h})

Create a uibuttongroup object and return a handle to it.

A uibuttongroup is used to group uicontrol objects.

If @var{parent} is omitted then a uibuttongroup for the current figure is
created.  If no figure is available, a new figure is created first.

If @var{parent} is given then a uibuttongroup relative to @var{parent} is
created.

Any provided property value pairs will override the default values of the
created uibuttongroup object.

The full list of properties is documented at @ref{Uibuttongroup Properties}.

Examples:

@example
@group
## Create figure and panel on it
f = figure;
## Create a button group
gp = uibuttongroup (f, "Position", [ 0 0.5 1 1])
## Create a buttons in the group
b1 = uicontrol (gp, "style", "radiobutton", ...
                "string", "Choice 1", ...
                "Position", [ 10 150 100 50 ]);
b2 = uicontrol (gp, "style", "radiobutton", ...
                "string", "Choice 2", ...
                "Position", [ 10 50 100 30 ]);
## Create a button not in the group
b3 = uicontrol (f, "style", "radiobutton", ...
                "string", "Not in the group", ...
                "Position", [ 10 50 100 50 ]);
@end group
@end example

When called with a single argument @var{h} which is a handle to an existing
uibuttongroup object, switch the focus to the specified uibuttongroup.  This
functionality is not currently implemented.
@xseealso{figure, uipanel}
@end deftypefn
uicontextmenu
@c uicontextmenu scripts/gui/uicontextmenu.m
@deftypefn  {} {@var{hui} =} uicontextmenu (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uicontextmenu (@var{h}, @var{property}, @var{value}, @dots{})

Create a uicontextmenu object and return a handle to it.

If @var{h} is omitted then a uicontextmenu for the current figure is
created.  If no figure is available, a new figure is created first.

If @var{h} is given then a uicontextmenu relative to @var{h} is created.

Any provided property value pairs will override the default values of the
created uicontextmenu object.

The full list of properties is documented at @ref{Uicontextmenu Properties}.

Examples:

@example
@group
## create figure and uicontextmenu
f = figure ();
c = uicontextmenu (f);

## create menus in the context menu
m1 = uimenu ("parent", c, "label", "Menu item 1", ...
             "callback", "disp('menu item 1')");
m2 = uimenu ("parent", c, "label", "Menu item 2", ...
             "callback", "disp('menu item 2')");

## set the context menu for the figure
set (f, "uicontextmenu", c);
@end group
@end example
@xseealso{figure, uimenu}
@end deftypefn
uicontrol
@c uicontrol scripts/gui/uicontrol.m
@deftypefn  {} {@var{hui} =} uicontrol (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uicontrol (@var{parent}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} uicontrol (@var{h})

Create a uicontrol object and return a handle to it.

A uicontrol object is used to create simple interactive controls such as
push buttons, checkboxes, edit and list controls.

If @var{parent} is omitted then a uicontrol for the current figure is
created.  If no figure is available, a new figure is created first.

If @var{parent} is given then a uicontrol relative to @var{parent} is
created.

Any provided property value pairs will override the default values of the
created uicontrol object.

The full list of properties is documented at @ref{Uicontrol Properties}.

The type of uicontrol created is specified by the @var{style} property.  If
no style property is provided, a push button will be created.

Valid styles for uicontrol are:

@table @asis
@item @qcode{"checkbox"}
Create a checkbox control that allows user on/off selection.

@item @qcode{"edit"}
Create an edit control that allows user input of single or multiple lines
of text.

@item @qcode{"listbox"}
Create a listbox control that displays a list of items and allows user
selection of single or multiple items.

@item @qcode{"popupmenu"}
Create a popupmenu control that displays a list of options that can be
selected when the user clicks on the control.

@item @qcode{"pushbutton"}
Create a push button control that allows user to press to cause an action.

@item @qcode{"radiobutton"}
Create a radio button control intended to be used for mutually exclusive
input in a group of radiobutton controls.

@item @qcode{"slider"}
Create a slider control that allows user selection from a range of values
by sliding knob on the control.

@item @qcode{"text"}
Create a static text control to display single or multiple lines of text.

@item @qcode{"togglebutton"}
Create a toggle button control that appears like a push button but allows
the user to select between two states.

@end table

Examples:

@example
@group
## Create figure and panel on it
f = figure;
## Create a button (default style)
b1 = uicontrol (f, "string", "A Button", ...
                   "position", [10 10 150 40]);
## Create an edit control
e1 = uicontrol (f, "style", "edit", "string", "editable text", ...
                   "position", [10 60 300 40]);
## Create a checkbox
c1 = uicontrol (f, "style", "checkbox", "string", "a checkbox", ...
                   "position", [10 120 150 40]);
@end group
@end example

When called with a single argument @var{h} which is a handle to an existing
uicontrol object, switch the keyboard focus to the specified
uicontrol.  As a result, the uicontrol object will receive keyboard
events that can be processed using the @qcode{"keypressfcn"} callback.
@xseealso{figure, uipanel}
@end deftypefn
uigetdir
@c uigetdir scripts/gui/uigetdir.m
@deftypefn  {} {@var{dirname} =} uigetdir ()
@deftypefnx {} {@var{dirname} =} uigetdir (@var{init_path})
@deftypefnx {} {@var{dirname} =} uigetdir (@var{init_path}, @var{dialog_name})
Open a GUI dialog for selecting a directory.

If @var{init_path} is not given the current working directory is used.

@var{dialog_name} may be used to customize the dialog title.
@xseealso{uigetfile, uiputfile}
@end deftypefn
uigetfile
@c uigetfile scripts/gui/uigetfile.m
@deftypefn  {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uigetfile ()
@deftypefnx {} {[@dots{}] =} uigetfile (@var{flt})
@deftypefnx {} {[@dots{}] =} uigetfile (@var{flt}, @var{dialog_name})
@deftypefnx {} {[@dots{}] =} uigetfile (@var{flt}, @var{dialog_name}, @var{default_file})
@deftypefnx {} {[@dots{}] =} uigetfile (@dots{}, "Position", [@var{px} @var{py}])
@deftypefnx {} {[@dots{}] =} uigetfile (@dots{}, "MultiSelect", @var{mode})

Open a GUI dialog for selecting a file and return the filename @var{fname},
the path to this file @var{fpath}, and the filter index @var{fltidx}.

@var{flt} contains a (list of) file filter string(s) in one of the following
formats:

@table @asis
@item @qcode{"/path/to/filename.ext"}
If a filename is given then the file extension is extracted and used as
filter.  In addition, the path is selected as current path and the filename
is selected as default file.  Example: @code{uigetfile ("myfun.m")}

@item A single file extension @qcode{"*.ext"}
Example: @code{uigetfile ("*.ext")}

@item A 2-column cell array
containing a file extension in the first column and a brief description in
the second column.
Example: @code{uigetfile (@{"*.ext", "My Description";"*.xyz",
"XYZ-Format"@})}

The filter string can also contain a semicolon separated list of filter
extensions.
Example: @code{uigetfile (@{"*.gif;*.png;*.jpg", "Supported Picture
Formats"@})}

@item A directory name or path name
If the folder name of path name contains a trailing file separator, the
contents of that folder will be displayed.  If no trailing file separator
is present the parent directory is listed.  The substring to the right of
the rightmost file separator (if any) will be interpreted as a file or
directory name and if that file or directory exists it will be highlighted.
If the path name or directory name is wholly or partly nonexistent, the
current working directory will be displayed.
No filter will be active.
@end table

@var{dialog_name} can be used to customize the dialog title.

If @var{default_file} is given then it will be selected in the GUI dialog.
If, in addition, a path is given it is also used as current path.

The screen position of the GUI dialog can be set using the
@qcode{"Position"} key and a 2-element vector containing the pixel
coordinates.  Two or more files can be selected when setting the
@qcode{"MultiSelect"} key to @qcode{"on"}.  In that case @var{fname} is a
cell array containing the files.
@xseealso{uiputfile, uigetdir}
@end deftypefn
uimenu
@c uimenu scripts/gui/uimenu.m
@deftypefn  {} {@var{hui} =} uimenu (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uimenu (@var{h}, @var{property}, @var{value}, @dots{})
Create a uimenu object and return a handle to it.

If @var{h} is omitted then a top-level menu for the current figure is
created.  If @var{h} is given then a submenu relative to @var{h} is created.

uimenu objects have the following specific properties:

@table @asis
@item @qcode{"accelerator"}
A string containing the key combination together with CTRL to execute this
menu entry (e.g., @qcode{"x"} for CTRL+x).

@item @qcode{"callback"}
Is the function called when this menu entry is executed.  It can be either a
function string (e.g., @qcode{"myfun"}), a function handle (e.g., @@myfun)
or a cell array containing the function handle and arguments for the
callback function (e.g., @{@@myfun, arg1, arg2@}).

@item @qcode{"checked"}
Can be set @qcode{"on"} or @qcode{"off"}.  Sets a mark at this menu entry.

@item @qcode{"enable"}
Can be set @qcode{"on"} or @qcode{"off"}.  If disabled the menu entry
cannot be selected and it is grayed out.

@item @qcode{"foregroundcolor"}
A color value setting the text color for this menu entry.

@item @qcode{"label"}
A string containing the label for this menu entry.  A @qcode{"&"}-symbol
can be used to mark the @qcode{"accelerator"} character (e.g.,
@nospell{@qcode{"E&xit"}})

@item @qcode{"position"}
An scalar value containing the relative menu position.  The entry with the
lowest value is at the first position starting from left or top.

@item @qcode{"separator"}
Can be set @qcode{"on"} or @qcode{"off"}.  If enabled it draws a separator
line above the current position.  It is ignored for top level entries.

@end table

The full list of properties is documented at @ref{Uimenu Properties}.

Examples:

@example
@group
f = uimenu ("label", "&File", "accelerator", "f");
e = uimenu ("label", "&Edit", "accelerator", "e");
uimenu (f, "label", "Close", "accelerator", "q", ...
           "callback", "close (gcf)");
uimenu (e, "label", "Toggle &Grid", "accelerator", "g", ...
           "callback", "grid (gca)");
@end group
@end example
@xseealso{figure}
@end deftypefn
uipanel
@c uipanel scripts/gui/uipanel.m
@deftypefn  {} {} uipanel (@var{property}, @var{value}, @dots{})
@deftypefnx {} {} uipanel (@var{parent}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uipanel (@dots{})

Create a uipanel object.

uipanels are used as containers to group other uicontrol objects.

If @var{parent} is omitted then a uipanel for the current figure is
created.  If no figure is available, a new figure is created first.

If @var{parent} is given then a uipanel relative to @var{parent} is created.

Any provided property value pairs will override the default values of the
created uipanel object.

The full list of properties is documented at @ref{Uipanel Properties}.

The optional return value @var{hui} is a graphics handle to the created
uipanel object.

Examples:

@example
@group
## create figure and panel on it
f = figure;
p = uipanel ("title", "Panel Title", "position", [.25 .25 .5 .5]);

## add two buttons to the panel
b1 = uicontrol ("parent", p, "string", "A Button", ...
                "position", [18 10 150 36]);
b2 = uicontrol ("parent", p, "string", "Another Button", ...
                "position",[18 60 150 36]);

@end group
@end example
@xseealso{figure, uicontrol}
@end deftypefn
uipushtool
@c uipushtool scripts/gui/uipushtool.m
@deftypefn  {} {} uipushtool (@var{property}, @var{value}, @dots{})
@deftypefnx {} {} uipushtool (@var{parent}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uipushtool (@dots{})

Create a uipushtool object.

uipushtools are buttons that appear on a figure toolbar.  The button is
created with a border that is shown when the user hovers over the button.
An image can be set using the cdata property.

If @var{parent} is omitted then a uipushtool for the current figure is
created.  If no figure is available, a new figure is created first.  If a
figure is available, but does not contain a uitoolbar, a uitoolbar will be
created.

If @var{parent} is given then a uipushtool is created on the @var{parent}
uitoolbar.

Any provided property value pairs will override the default values of the
created uipushtool object.

The full list of properties is documented at @ref{Uipushtool Properties}.

The optional return value @var{hui} is a graphics handle to the created
uipushtool object.

Examples:

@example
@group
% create figure without a default toolbar
f = figure ("toolbar", "none");
% create empty toolbar
t = uitoolbar (f);
% create a 19x19x3 black square
img=zeros(19,19,3);
% add pushtool button to toolbar
b = uipushtool (t, "cdata", img);
@end group
@end example
@xseealso{figure, uitoolbar, uitoggletool}
@end deftypefn
uiputfile
@c uiputfile scripts/gui/uiputfile.m
@deftypefn  {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile ()
@deftypefnx {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt})
@deftypefnx {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt}, @var{dialog_name})
@deftypefnx {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt}, @var{dialog_name}, @var{default_file})
Open a GUI dialog for selecting a file.

@var{flt} contains a (list of) file filter string(s) in one of the following
formats:

@table @asis
@item @qcode{"/path/to/filename.ext"}
If a filename is given the file extension is extracted and used as filter.
In addition the path is selected as current path and the filename is
selected as default file.  Example: @code{uiputfile ("myfun.m")}

@item @qcode{"*.ext"}
A single file extension.
Example: @code{uiputfile ("*.ext")}

@item @code{@{"*.ext", "My Description"@}}
A 2-column cell array containing the file extension in the 1st column and
a brief description in the 2nd column.
Example: @code{uiputfile (@{"*.ext","My Description";"*.xyz",
"XYZ-Format"@})}
@end table

The filter string can also contain a semicolon separated list of filter
extensions.
Example: @code{uiputfile (@{"*.gif;*.png;*.jpg",
"Supported Picture Formats"@})}

@var{dialog_name} can be used to customize the dialog title.
If @var{default_file} is given it is preselected in the GUI dialog.
If, in addition, a path is given it is also used as current path.
@xseealso{uigetfile, uigetdir}
@end deftypefn
uiresume
@c uiresume scripts/gui/uiresume.m
@deftypefn {} {} uiresume (@var{h})
Resume program execution suspended with @code{uiwait}.

The handle @var{h} must be the same as the on specified in @code{uiwait}.
If the handle is invalid or there is no @code{uiwait} call pending for the
figure with handle @var{h}, this function does nothing.
@xseealso{uiwait}
@end deftypefn
uitable
@c uitable scripts/gui/uitable.m
@deftypefn  {} {@var{hui} =} uitable (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uitable (@var{parent}, @var{property}, @var{value}, @dots{})
Create a uitable object and return a handle to it.

A uitable object is used to show tables of data in a figure window.

If @var{parent} is omitted then a uitable for the current figure is
created.  If no figure is available, a new figure is created first.

If @var{parent} is given then a uitable relative to @var{parent} is
created.

Any provided property value pairs will override the default values of the
created uitable object.

The full list of properties is documented at @ref{Uitable Properties}.

Examples:

@example
@group
## Create figure and place a table on it
f = figure ();
m = magic (8);
t = uitable (f, "Data", m, "ColumnWidth", @{ 40 @});
@end group

@group
## Create a table with labeled rows and columns
f = figure ();
d = reshape (1:9, [3, 3]);
row_names = @{ "Row1", "Row2", "Row3" @};
col_names = @{ "Col1", "Col2", "Col3" @};
t = uitable (f, "Data", d, ...
             "RowName", row_names, "ColumnName", col_names);

p = get (t, "Position");
e = get (t, "Extent");
p(3:4) = e(3:4);
set (t, "Position", p);
@end group

## Long demo with callbacks
function uitable_demo ()
  f = figure ("Name", "uitable Demo", "Menu", "none", ...
              "Position", [10 10 1000 680]);

  ## A basic example
  d = @{ "char"   , "A string";
        "double" , 12.3456789;
        "complex", 1+2i;
        "bool"   , true;
        "single" , single (12.3456789);
        "int8"   , int8 (-128);
        "uint8"  , uint8 (128);
        "int16"  , int16 (-32768);
        "uint16" , uint16 (32768);
        "int32"  , int32 (-2147483648);
        "uint32" , uint32 (2147483648);
        "int64"  , int64 (-2147483649);
        "uint64" , uint64 (2147843649)@};

  popup_options = @{"A", "B", "C", "D", "E"@};

  columnformat_options = @{ "[]", "char", "pop-up", "numeric", ...
                           "short", "short e", "short eng", ...
                           "short g", "long", "long e", ...
                           "long eng", "long g", "bank", "+", ...
                           "rat", "logical"@};
  columnformat_values = columnformat_options;
  columnformat_values@{1@} = "";
  columnformat_values@{3@} = popup_options;

  default_data = repmat (d(:,2), 1, columns (columnformat_options));
  b_add = uicontrol (f, "Position", [285 630 600 50], ...
            "UserData", [rows(d), 1], ...
            "Style", "pushbutton", ...
            "String", "Set data at selected point to selected datatype");

  l_type_table = uicontrol (f, "Position", [ 0 603 120 25 ], ...
      "String", "Datatype Table:", ...
      "Style", "text");
  t_type_table = uitable (f, "Position", [ 0 530 1000 70 ], ...
      "Data", transpose (d(:, 2)), ...
      "ColumnName", transpose (d(:, 1)), ...
      "RowName", "Value", ...
      "CellSelectionCallback", ...
           @@(x, y) set (b_add, "UserData", y.Indices ));

  l_point_table = uicontrol (f, "Position", [ 0 640 60 25 ], ...
      "String", "Point:", ...
      "Style", "text");
  t_point_table = uitable (f, "Position", [ 80 630 160 42 ], ...
      "RowName", [], ...
      "ColumnName", @{"x", "y"@}, ...
      "Data", [ 1, 1 ], ...
      "ColumnEditable", true);

  l_editable_table = uicontrol (f, "Position", [ 0 502 200 25 ], ...
      "Style", "text", ...
      "String", "Set Data Columns Editable:");
  t_editable_table = ...
    uitable (f, "Position", [ 0 434 1000 65 ], ...
                "Data", repmat (false, 1, columns (default_data)), ...
                "ColumnEditable", true);

  l_format_table = uicontrol (f, "Position", [ 0 406 200 25 ], ...
      "Style", "text", ...
      "String", "Set Data Column Format:");
  t_format_table = ...
    uitable (f, "Position", [ 0 338 1000 65 ], ...
                "Data", columnformat_options, ...
                "ColumnEditable", true, ...
                "ColumnFormat", arrayfun (@@(x) @{columnformat_options@}, ...
                                          1:columns (columnformat_options)));

  l_data_table = uicontrol (f, "Style", "text", ...
                               "String", "Data:", ...
                               "Position", [ 0 310 60 25 ]);
  t_data_table = uitable (f, "Position", [ 0 15 1000 290 ], ...
      "Data", default_data, ...
      "ColumnFormat", columnformat_values);

  set (t_format_table, ...
       "CellEditCallback", ...
       @@(x, y) update_column_format (y.NewData, y.Indices, ...
                                      t_data_table, popup_options));
  set (t_point_table, "CellEditCallback", ...
       @@(x, y) validate_point_table (x, y, t_data_table));
  set (t_editable_table, "CellEditCallback", ...
       @@(x,y) set (t_data_table, ...
                    "ColumnEditable", get (t_editable_table, "Data")));
  set (b_add, ...
       "Callback", @@(x, y) update_data (b_add, t_point_table, ...
                                         t_type_table, t_data_table));
  set (t_data_table, "CellSelectionCallback", ...
       @@(x, y) update_point_table (y.Indices, t_point_table));
endfunction

function validate_point_table (h, dat, t_data_table)
  if (! (dat.NewData > 0 && ...
    dat.NewData < size (get (t_data_table, "Data"), dat.Indices(1, 1)) + 1))

    d = get (h, "Data");
    d(dat.Indices) = 1;
    set (h, "Data", d);
  endif
endfunction

function update_column_format (format, indices, t_data_table, ...
                               popup_options)
  cf = get (t_data_table, "ColumnFormat");
  if (strcmp (format, "[]"))
    format = "";
  elseif (strcmp (format, "pop-up"))
    format = popup_options;
  endif
  cf@{indices(1,2)@} = format;
  set (t_data_table, "ColumnFormat", cf);
endfunction

function update_point_table (indices, t_point_table)
  if (isempty (indices))
    indices = [1, 1];
  endif
  set (t_point_table, "Data", indices(1,:));
endfunction

function update_data (b_add, t_point_table, t_type_table, ...
                      t_data_table)
  indices = get (b_add, "UserData");
  if (isempty (indices))
    indices = [1, 1];
  endif
  d = get (t_data_table, "Data");
  t_type_table_data = get (t_type_table, "Data");
  p = get (t_point_table, "Data");
  d(p(1,2), p(1,1)) = t_type_table_data(indices(1,2));
  set (t_data_table, "Data", d);
endfunction
@end example

@xseealso{figure, uicontrol}
@end deftypefn
uitoggletool
@c uitoggletool scripts/gui/uitoggletool.m
@deftypefn  {} {} uitoggletool (@var{property}, @var{value}, @dots{})
@deftypefnx {} {} uitoggletool (@var{parent}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uitoggletool (@dots{})

Create a uitoggletool object.

uitoggletool are togglebuttons that appear on a figure toolbar.  The
button is created with a border that is shown when the user hovers over
the button.  An image can be set using the cdata property.

If @var{parent} is omitted then a uitoggletool for the current figure is
created.  If no figure is available, a new figure is created first.  If a
figure is available, but does not contain a uitoolbar, a uitoolbar will be
created.

If @var{parent} is given then a uitoggletool is created on the
@var{parent} uitoolbar.

Any provided property value pairs will override the default values of the
created uitoggletool object.

The full list of properties is documented at @ref{Uitoggletool Properties}.

The optional return value @var{hui} is a graphics handle to the created
uitoggletool object.

Examples:

@example
@group
% create figure without a default toolbar
f = figure ("toolbar", "none");
% create empty toolbar
t = uitoolbar (f);
% create a 19x19x3 black square
img=zeros(19,19,3);
% add uitoggletool button to toolbar
b = uitoggletool (t, "cdata", img);
@end group
@end example
@xseealso{figure, uitoolbar, uipushtool}
@end deftypefn
uitoolbar
@c uitoolbar scripts/gui/uitoolbar.m
@deftypefn  {} {} uitoolbar (@var{property}, @var{value}, @dots{})
@deftypefnx {} {} uitoolbar (@var{parent}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uitoolbar (@dots{})

Create a uitoolbar object.  A uitoolbar displays uitoggletool and uipushtool
buttons.

If @var{parent} is omitted then a uitoolbar for the current figure is
created.  If no figure is available, a new figure is created first.

If @var{parent} is given then a uitoolbar relative to @var{parent} is
created.

Any provided property value pairs will override the default values of the
created uitoolbar object.

The full list of properties is documented at @ref{Uitoolbar Properties}.

The optional return value @var{hui} is a graphics handle to the created
uitoolbar object.

Examples:

@example
@group
% create figure without a default toolbar
f = figure ("toolbar", "none");
% create empty toolbar
t = uitoolbar (f);
@end group
@end example
@xseealso{figure, uitoggletool, uipushtool}
@end deftypefn
uiwait
@c uiwait scripts/gui/uiwait.m
@deftypefn  {} {} uiwait
@deftypefnx {} {} uiwait (@var{h})
@deftypefnx {} {} uiwait (@var{h}, @var{timeout})
Suspend program execution until the figure with handle @var{h} is deleted
or @code{uiresume} is called.

When no figure handle is specified this function uses the current figure.
If the figure handle is invalid or there is no current figure, this
functions returns immediately.

When specified, @var{timeout} defines the number of seconds to wait
for the figure deletion or the @code{uiresume} call.  The timeout value
must be at least 1.  If a smaller value is specified, a warning is issued
and a timeout value of 1 is used instead.  If a non-integer value is
specified, it is truncated towards 0.  If @var{timeout} is not specified,
the program execution is suspended indefinitely.
@xseealso{uiresume, waitfor}
@end deftypefn
waitbar
@c waitbar scripts/gui/waitbar.m
@deftypefn  {} {@var{h} =} waitbar (@var{frac})
@deftypefnx {} {@var{h} =} waitbar (@var{frac}, @var{msg})
@deftypefnx {} {@var{h} =} waitbar (@dots{}, "createcancelbtn", @var{fcn}, @dots{})
@deftypefnx {} {@var{h} =} waitbar (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} waitbar (@var{frac})
@deftypefnx {} {} waitbar (@var{frac}, @var{h})
@deftypefnx {} {} waitbar (@var{frac}, @var{h}, @var{msg})
Return a handle @var{h} to a new progress indicator ("waitbar") object.

The waitbar is filled to fraction @var{frac} which must be in the range
[0, 1].

The optional message @var{msg} is centered and displayed above the waitbar.

A cancel button can be added to the bottom of the waitbar using the
@qcode{"createcancelbtn"} property of waitbar figures.  The action to be
executed when the user presses the button is specified using a string or
function handle @var{fcn}.

The appearance of the waitbar figure window can be configured by passing
@var{prop}/@var{val} pairs to the function.

When called with a single input the current waitbar, if it exists, is
updated to the new value @var{frac}.  If there are multiple outstanding
waitbars they can be updated individually by passing the handle @var{h}
of the specific waitbar to modify.

@xseealso{delete}
@end deftypefn
waitforbuttonpress
@c waitforbuttonpress scripts/gui/waitforbuttonpress.m
@deftypefn  {} {} waitforbuttonpress ()
@deftypefnx {} {@var{b} =} waitforbuttonpress ()
Wait for mouse click or key press over the current figure window.

The return value of @var{b} is 0 if a mouse button was pressed or 1 if a
key was pressed.
@xseealso{waitfor, ginput, kbhit}
@end deftypefn
warndlg
@c warndlg scripts/gui/warndlg.m
@deftypefn  {} {} warndlg ()
@deftypefnx {} {} warndlg (@var{msg})
@deftypefnx {} {} warndlg (@var{msg}, @var{title})
@deftypefnx {} {} warndlg (@var{msg}, @var{title}, @var{opt})
@deftypefnx {} {@var{h} =} warndlg (@dots{})
Display a warning dialog box with warning message @var{msg} and caption
@var{title}.

The default warning message is
@qcode{"This is the default warning string.@:"} and the default caption is
@qcode{"Warning Dialog"}.

The warning message may have multiple lines separated by newline characters
("\n"), or it may be a cellstr array with one element for each line.

The third optional argument @var{opt} controls the behavior of the dialog.
See @code{msgbox} for details.

The return value @var{h} is a handle to the figure object used for
building the dialog.

Examples:

@example
@group
warndlg ("Some warning text for the user.");
warndlg ("Some warning text\nwith two lines.");
warndlg (@{"Some warning text", "with two lines."@});
warndlg ("Some warning text for the user.", "Fancy caption");
@end group
@end example

@xseealso{errordlg, helpdlg, msgbox, inputdlg, listdlg, questdlg}
@end deftypefn
__gripe_missing_component__
@c __gripe_missing_component__ scripts/help/__gripe_missing_component__.m
@deftypefn {} {} __gripe_missing_component__ (@var{caller}, @var{component})
Undocumented internal function.
@end deftypefn
__makeinfo__
@c __makeinfo__ scripts/help/__makeinfo__.m
@deftypefn  {} {[@var{retval}, @var{status}] =} __makeinfo__ (@var{text}, @var{output_type})
@deftypefnx {} {[@var{retval}, @var{status}] =} __makeinfo__ (@var{text}, @var{output_type}, @var{fsee_also})
Undocumented internal function.
@end deftypefn
__unimplemented__
@c __unimplemented__ scripts/help/__unimplemented__.m
@deftypefn {} {@var{txt} =} __unimplemented__ (@var{fcn})
Return specific help text for the unimplemented function @var{fcn}.

This is usually a suggestion for an existing compatible function to use in
place of @var{fcn}.

This function is not called by users, but by the Octave interpreter when it
fails to recognize an input string as a valid function name.  See
@code{missing_function_hook} for using a different handler for this event.
@xseealso{missing_function_hook}
@end deftypefn
ans
@c ans scripts/help/ans.m
@defvr {Automatic Variable} ans
The most recently computed result that was not explicitly assigned to a
variable.

For example, after the expression

@example
3^2 + 4^2
@end example

@noindent
is evaluated, the value returned by @code{ans} is 25.
@end defvr
bessel
@c bessel scripts/help/bessel.m
@deftypefn  {} {[@var{J}, @var{ierr}] =} besselj (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {} {[@var{Y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {} {[@var{I}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {} {[@var{K}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {} {[@var{H}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt})
Compute Bessel or Hankel functions of various kinds.

All functions begin with the prefix @qcode{"bessel"}.  The list of
functions is:

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

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

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

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

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

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

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

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

@enumerate 0
@item
Normal return.

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

@item
Overflow, return @code{Inf}.

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

@item
Loss of significance by argument reduction, output may be inaccurate.

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

@xseealso{besselj, bessely, besseli, besselk, besselh}
@end deftypefn
debug
@c debug scripts/help/debug.m
@deftypefn {} {} debug ()
Summary of debugging commands.

For more information on each command and available options use
@code{help CMD}.

The debugging commands available in Octave are

@table @code
@item dbstop
Add a breakpoint.

@item dbclear
Remove a breakpoint.

@item dbstatus
List all breakpoints.

@item dbwhere
Report the current file and line number where execution is stopped.

@item dbtype
Display the code of the function being debugged, enumerating
the line numbers.

@item dblist
List 10 lines of code centered around the line number where execution is
stopped.

@item  dbstep
@itemx dbnext
Execute (step) one or more lines, follow execution into (step into) a
function call, or execute until the end of a function (step out), and
re-enter debug mode.

@item dbcont
Continue normal code execution from the debug prompt.

@item dbquit
Quit debugging mode immediately and return to the main prompt.

@item dbstack
Print a backtrace of the execution stack.

@item dbup
Move up the execution stack.

@item dbdown
Move down the execution stack.

@item keyboard
Force entry into debug mode from an m-file.

@item debug_on_error
Configure whether Octave enters debug mode when it encounters an error.

@item debug_on_warning
Configure whether Octave enters debug mode when it encounters a warning.

@item debug_on_interrupt
Configure whether Octave enters debug mode when it encounters an interrupt.

@item isdebugmode
Return true if in debug mode.
@end table

@noindent
When Octave encounters a breakpoint, or other reason to enter debug mode,
the prompt changes to @qcode{"debug>"}.  The workspace of the function
where the breakpoint was encountered becomes available and any Octave
command that is valid in that workspace context may be executed.

@xseealso{dbstop, dbclear, dbstatus, dbwhere, dbtype, dbcont, dbquit,
dbstack, dbup, dbdown, keyboard, debug_on_error, debug_on_warning,
debug_on_interrupt, isdebugmode}
@end deftypefn
doc
@c doc scripts/help/doc.m
@deftypefn  {} {} doc @var{function_name}
@deftypefnx {} {} doc
Display documentation for the function @var{function_name} directly from an
online version of the printed manual, using the GNU Info browser.

If invoked without an argument, the manual is shown from the beginning.

For example, the command @kbd{doc rand} starts the GNU Info browser at the
@code{rand} node in the online version of the manual.

Once the GNU Info browser is running, help for using it is available using
the command @kbd{C-h}.
@xseealso{help}
@end deftypefn
doc_cache_create
@c doc_cache_create scripts/help/doc_cache_create.m
@deftypefn  {} {} doc_cache_create (@var{out_file}, @var{directory})
@deftypefnx {} {} doc_cache_create (@var{out_file})
@deftypefnx {} {} doc_cache_create ()
Generate documentation cache for all functions in @var{directory}.

A documentation cache is generated for all functions in @var{directory}
which may be a single string or a cell array of strings.  The cache is used
to speed up the function @code{lookfor}.

The cache is saved in the file @var{out_file} which defaults to the value
@file{doc-cache} if not given.

If no directory is given (or it is the empty matrix), a cache for built-in
functions, operators, and keywords is generated.

@xseealso{doc_cache_file, lookfor, path}
@end deftypefn
error_ids
@c error_ids scripts/help/error_ids.m
@cindex error ids

@table @code
@item Octave:invalid-context
Indicates the error was generated by an operation that cannot be executed in
the scope from which it was called.  For example, the function
@code{print_usage ()} when called from the Octave prompt raises this error.

@item Octave:invalid-input-arg
Indicates that a function was called with invalid input arguments.

@item Octave:invalid-fun-call
Indicates that a function was called in an incorrect way, e.g., wrong number
of input arguments.

@item Octave:invalid-indexing
Indicates that a data-type was indexed incorrectly, e.g., real-value index
for arrays, nonexistent field of a structure.

@item Octave:bad-alloc
Indicates that memory couldn't be allocated.

@item Octave:undefined-function
Indicates a call to a function that is not defined.  The function may exist
but Octave is unable to find it in the search path.

@end table

get_first_help_sentence
@c get_first_help_sentence scripts/help/get_first_help_sentence.m
@deftypefn  {} {@var{text} =} get_first_help_sentence (@var{name})
@deftypefnx {} {@var{text} =} get_first_help_sentence (@var{name}, @var{max_len})
@deftypefnx {} {[@var{text}, @var{status}] =} get_first_help_sentence (@dots{})
Return the first sentence of a function's help text.

The first sentence is defined as the text after the function declaration
until either the first period (".") or the first appearance of two
consecutive newlines ("\n\n").  The text is truncated to a maximum length of
@var{max_len}, which defaults to 80.  If the text must be truncated the last
three characters of the text are replaced with @qcode{"..."} to indicate
that more text was available.

The optional output argument @var{status} returns the status reported by
@code{makeinfo}.  If only one output argument is requested, and @var{status}
is nonzero, a warning is displayed.

As an example, the first sentence of this help text is

@example
@group
get_first_help_sentence ("get_first_help_sentence")
@print{} ans = Return the first sentence of a function's help text.
@end group
@end example
@end deftypefn
help
@c help scripts/help/help.m
@deftypefn  {} {} help @var{name}
@deftypefnx {} {} help --list
@deftypefnx {} {} help .
@deftypefnx {} {} help
Display the help text for @var{name}.

For example, the command @kbd{help help} prints a short message describing
the @code{help} command.

Given the single argument @code{--list}, list all operators, keywords,
built-in functions, and loadable functions available in the current session
of Octave.

Given the single argument @code{.}, list all operators available in the
current session of Octave.

If invoked without any arguments, @code{help} displays instructions on how
to access help from the command line.

The help command can provide information about most operators, but
@var{name} must be enclosed by single or double quotes to prevent
the Octave interpreter from acting on @var{name}.  For example,
@code{help "+"} displays help on the addition operator.
@xseealso{doc, lookfor, which, info}
@end deftypefn
lookfor
@c lookfor scripts/help/lookfor.m
@deftypefn  {} {} lookfor @var{str}
@deftypefnx {} {} lookfor -all @var{str}
@deftypefnx {} {[@var{fcn}, @var{help1str}] =} lookfor (@var{str})
@deftypefnx {} {[@var{fcn}, @var{help1str}] =} lookfor ("-all", @var{str})
Search for the string @var{str} in the documentation of all functions in the
current function search path.

By default, @code{lookfor} looks for @var{str} in just the first sentence of
the help string for each function found.  The entire help text of each
function can be searched by using the @qcode{"-all"} argument.  All searches
are case insensitive.

When called with no output arguments, @code{lookfor} prints the list of
matching functions to the terminal.  Otherwise, the output argument
@var{fcns} contains the function names and @var{help1str} contains the first
sentence from the help string of each function.

Programming Note: The ability of @code{lookfor} to correctly identify the
first sentence of the help text is dependent on the format of the function's
help.  All Octave core functions are correctly formatted, but the same can
not be guaranteed for external packages and user-supplied functions.
Therefore, the use of the @qcode{"-all"} argument may be necessary to find
related functions that are not a part of Octave.

The speed of lookup is greatly enhanced by having a cached documentation
file.  See @code{doc_cache_create} for more information.
@xseealso{help, doc, which, path, doc_cache_create}
@end deftypefn
print_usage
@c print_usage scripts/help/print_usage.m
@deftypefn  {} {} print_usage ()
@deftypefnx {} {} print_usage (@var{name})
Print the usage message for the function @var{name}.

When called with no input arguments the @code{print_usage} function displays
the usage message of the currently executing function.
@xseealso{help}
@end deftypefn
slash
@c slash scripts/help/slash.m
@documentencoding UTF-8
@defvr {Documentation} slash
Backslash and slash perform various sorts of division.

@table @asis
@item @code{\} Matrix Left Division (``backslash'')
Solve systems of equations
@iftex
$Ax = b$ for $x$.
@end iftex
@ifnottex
Ax = b for x.
@end ifnottex
@code{A \ b} is conceptually equivalent to @code{inv (A) * b} but is
computed more efficiently and accurately, without forming the matrix
inverse directly.

Example:

@example
@group
A = [1 2; 3 4];
b = [4; 2];
x = A \ b
  @result{} x =
       -6
        5
isequal (A*x, b)
  @result{} 1
@end group
@end example

If the system is not square, or if the matrix is singular, a minimum-norm
solution is computed (@code{norm (A*x - b)}).

For dense matrices, backslash uses the Gaussian Elimination algorithm
with partial pivoting.  For sparse matrices, backslash uses a direct
method to compute an LU factorization (@pxref{XREFlu,,lu}).  The direct
method tries to minimize ``fill-in'' of zeros but it could nonetheless use a
lot of memory; if this is a concern, consider an iterative method
(@pxref{XREFcgs,,cgs} or @pxref{XREFgmres,,gmres}).

@item @code{/} Matrix Right Division
The forward slash notation can be used to solve systems of the form
@iftex
$AB = C$ for $A$
@end iftex
@ifnottex
AB = C for A
@end ifnottex
using @code{A = C / B}.

@item @code{./} and @code{.\} Component-wise ``Hadamard'' Division
The ``dot slash'' operators perform element-by-element division, for
example:

@example
@group
A = [1 10 12; 24 30 42];
B = [1 5 4; 6 6 7];
A ./ B
  @result{}
       1   2   3
       4   5   6
@end group
@end example

If the sizes are not the same, ``broadcasting'' may apply
(@pxref{Broadcasting}):

@example
@group
420 ./ B
  @result{}
       420    84   105
        70    70    60
[20; 42] ./ B
  @result{}
       20    4    5
        7    7    6
@end group
@end example

@end table

@xseealso{mldivide, mrdivide, ldivide, rdivide, linsolve}
@end defvr
type
@c type scripts/help/type.m
@deftypefn  {} {} type @var{name} @dots{}
@deftypefnx {} {} type -q @var{name} @dots{}
@deftypefnx {} {text =} type ("@var{name}", @dots{})
Display the contents of @var{name} which may be a file, function (m-file),
variable, operator, or keyword.

@code{type} normally prepends a header line describing the category of
@var{name} such as function or variable; The @option{-q} option suppresses
this behavior.

If no output variable is used the contents are displayed on screen.
Otherwise, a cell array of strings is returned, where each element
corresponds to the contents of each requested function.
@end deftypefn
warning_ids
@c warning_ids scripts/help/warning_ids.m
@cindex warning ids

@table @code
@item Octave:abbreviated-property-match
By default, the @code{Octave:abbreviated-property-match} warning is enabled.

@item Octave:addpath-pkg
If the @code{Octave:addpath-pkg} warning is enabled,
Octave will warn when a package directory (i.e., +package_name) is added
to the @code{path}.  Typically, only the parent directory which contains the
package directory should be added to the load path.
By default, the @code{Octave:addpath-pkg} warning is enabled.

@item Octave:array-as-logical
If the @code{Octave:array-as-logical} warning is enabled,
Octave will warn when an array of size greater than 1x1 is used
as a truth value in an if, while or until statement.
By default, the @code{Octave:array-as-logical} warning is disabled.

@item Octave:array-to-scalar
If the @code{Octave:array-to-scalar} warning is enabled, Octave will
warn when an implicit conversion from an array to a scalar value is
attempted.
By default, the @code{Octave:array-to-scalar} warning is disabled.

@item Octave:array-to-vector
If the @code{Octave:array-to-vector} warning is enabled, Octave will
warn when an implicit conversion from an array to a vector value is
attempted.
By default, the @code{Octave:array-to-vector} warning is disabled.

@item Octave:assign-as-truth-value
If the @code{Octave:assign-as-truth-value} warning is
enabled, a warning is issued for statements like

@example
@group
if (s = t)
  @dots{}
@end group
@end example

@noindent
since such statements are not common, and it is likely that the intent
was to write

@example
@group
if (s == t)
  @dots{}
@end group
@end example

@noindent
instead.

There are times when it is useful to write code that contains
assignments within the condition of a @code{while} or @code{if}
statement.  For example, statements like

@example
@group
while (c = getc ())
  @dots{}
@end group
@end example

@noindent
are common in C programming.

It is possible to avoid all warnings about such statements by
disabling the @code{Octave:assign-as-truth-value} warning,
but that may also let real errors like

@example
@group
if (x = 1)  # intended to test (x == 1)!
  @dots{}
@end group
@end example

@noindent
slip by.

In such cases, it is possible suppress errors for specific statements by
writing them with an extra set of parentheses.  For example, writing the
previous example as

@example
@group
while ((c = getc ()))
  @dots{}
@end group
@end example

@noindent
will prevent the warning from being printed for this statement, while
allowing Octave to warn about other assignments used in conditional
contexts.

By default, the @code{Octave:assign-as-truth-value} warning is enabled.

@item Octave:associativity-change
If the @code{Octave:associativity-change} warning is
enabled, Octave will warn about possible changes in the meaning of
some code due to changes in associativity for some operators.
Associativity changes have typically been made for @sc{matlab}
compatibility.
By default, the @code{Octave:associativity-change} warning is enabled.

@item Octave:autoload-relative-file-name
If the @code{Octave:autoload-relative-file-name} is enabled,
Octave will warn when parsing autoload() function calls with relative
paths to function files.  This usually happens when using autoload()
calls in PKG_ADD files, when the PKG_ADD file is not in the same
directory as the .oct file referred to by the autoload() command.
By default, the @code{Octave:autoload-relative-file-name} warning is
enabled.

@item Octave:built-in-variable-assignment
By default, the @code{Octave:built-in-variable-assignment} warning is
enabled.

@item Octave:deprecated-function
If the @code{Octave:deprecated-function} warning is enabled, a
warning is issued when Octave encounters a function that is obsolete and
scheduled for removal from Octave.
By default, the @code{Octave:deprecated-function} warning is enabled.

@item Octave:deprecated-keyword
If the @code{Octave:deprecated-keyword} warning is enabled, a
warning is issued when Octave encounters a keyword that is obsolete and
scheduled for removal from Octave.
By default, the @code{Octave:deprecated-keyword} warning is enabled.

@item Octave:deprecated-property
If the @code{Octave:deprecated-property} warning is enabled, a
warning is issued when Octave encounters a graphics property that
is obsolete and scheduled for removal from Octave.
By default, the @code{Octave:deprecated-property} warning is enabled.

@item Octave:divide-by-zero
If the @code{Octave:divide-by-zero} warning is enabled, a
warning is issued when Octave encounters a division by zero.
By default, the @code{Octave:divide-by-zero} warning is enabled.

@item Octave:eigs:UnconvergedEigenvalues
If the @code{Octave:eigs:UnconvergedEigenvalues} warning is enabled then
the eigs function will issue a warning if the number of calculated
eigenvalues is less than the number of requested eigenvalues.
By default, the @code{Octave:eigs:UnconvergedEigenvalues} warning is
enabled.

@item Octave:erase:chararray
If the @code{Octave:erase:chararray} warning is enabled then the erase
function will issue a warning if the input pattern is a character array
rather than a string or cell array of strings.
By default, the @code{Octave:erase:chararray} warning is enabled.

@item Octave:data-file-in-path
If the @code{Octave:data-file-in-path} warning is enabled, a warning is
issued when Octave does not find the target of a file operation such as
@code{load} or @code{fopen} directly, but is able to locate the file in
Octave's search @code{path} for files.  The warning could indicate that a
different file target than the programmer intended is being used.
By default, the @code{Octave:data-file-in-path} warning is enabled.

@item Octave:function-name-clash
If the @code{Octave:function-name-clash} warning is enabled, a
warning is issued when Octave finds that the name of a function
defined in a function file differs from the name of the file.  (If
the names disagree, the name declared inside the file is ignored.)
By default, the @code{Octave:function-name-clash} warning is enabled.

@item Octave:future-time-stamp
If the @code{Octave:future-time-stamp} warning is enabled, Octave
will print a warning if it finds a function file with a time stamp
that is in the future.
By default, the @code{Octave:future-time-stamp} warning is enabled.

@item Octave:glyph-render
By default, the @code{Octave:glyph-render} warning is enabled.

@item Octave:imag-to-real
If the @code{Octave:imag-to-real} warning is enabled, a warning is
printed for implicit conversions of complex numbers to real numbers.
By default, the @code{Octave:imag-to-real} warning is disabled.

@item Octave:language-extension
Print warnings when using features that are unique to the Octave
language and that may still be missing in @sc{matlab}.
By default, the @code{Octave:language-extension} warning is disabled.
The @option{--traditional} or @option{--braindead} startup options for
Octave may also be of use, @pxref{Command Line Options}.

@item Octave:legacy-function
If the @code{Octave:legacy-function} warning is enabled, a
warning is issued when Octave encounters a function that @sc{matlab} has
suggested should be avoided.  The function may become obsolete at some
point in the future and removed, in which case the warning will change to
@code{Octave:deprecated-function}, and the function will continue to exist
for two further versions of Octave before being removed.
By default, the @code{Octave:legacy-function} warning is enabled.

@item Octave:logical-conversion
By default, the @code{Octave:logical-conversion} warning is enabled.

@item Octave:lu:sparse_input
If the @code{Octave:lu:sparse_input} warning is enabled, Octave
will warn when the lu function is called with a sparse input and less than
four output arguments.  In this case, sparsity-preserving column
permutations are not performed and the result may be inaccurate.
By default, the @code{Octave:lu:sparse_input} warning is enabled.

@item Octave:missing-glyph
By default, the @code{Octave:missing-glyph} warning is enabled.

@item Octave:missing-semicolon
If the @code{Octave:missing-semicolon} warning is enabled, Octave
will warn when statements in function definitions don't end in
semicolons.
By default the @code{Octave:missing-semicolon} warning is disabled.

@item Octave:mixed-string-concat
If the @code{Octave:mixed-string-concat} warning is enabled, print a
warning when concatenating a mixture of double and single quoted strings.
By default, the @code{Octave:mixed-string-concat} warning is disabled.

@item  Octave:nearly-singular-matrix
@itemx Octave:singular-matrix
These warnings are emitted if a (nearly) singular matrix is inverted.
By default, the @code{Octave:nearly-singular-matrix} and
@code{Octave:singular-matrix} warnings are enabled.

@item Octave:neg-dim-as-zero
If the @code{Octave:neg-dim-as-zero} warning is enabled, print a warning
for expressions like

@example
eye (-1)
@end example

@noindent
By default, the @code{Octave:neg-dim-as-zero} warning is disabled.

@item Octave:nested-functions-coerced
By default, the @code{Octave:nested-functions-coerced} warning is enabled.

@item Octave:noninteger-range-as-index
By default, the @code{Octave:noninteger-range-as-index} warning is enabled.

@item Octave:num-to-str
If the @code{Octave:num-to-str} warning is enable, a warning is
printed for implicit conversions of numbers to their UTF-8 encoded character
equivalents when strings are constructed using a mixture of strings and
numbers in matrix notation.  For example,

@example
@group
[ "f", 111, 111 ]
@result{} "foo"
@end group
@end example

@noindent
elicits a warning if the @code{Octave:num-to-str} warning is
enabled.  By default, the @code{Octave:num-to-str} warning is enabled.

@item Octave:possible-matlab-short-circuit-operator
If the @code{Octave:possible-matlab-short-circuit-operator} warning
is enabled, Octave will warn about using the not short circuiting
operators @code{&} and @code{|} inside @code{if} or @code{while}
conditions.  They normally never short circuit, but they do short
circuit when used in a condition.
By default, the @code{Octave:possible-matlab-short-circuit-operator} warning
is enabled.

@item Octave:precedence-change
If the @code{Octave:precedence-change} warning is enabled, Octave
will warn about possible changes in the meaning of some code due to
changes in precedence for some operators.  Precedence changes have
typically been made for @sc{matlab} compatibility.
By default, the @code{Octave:precedence-change} warning is enabled.

@item Octave:recursive-path-search
By default, the @code{Octave:recursive-path-search} warning is enabled.

@item Octave:remove-init-dir
The @code{path} function changes the search path that Octave uses
to find functions.  It is possible to set the path to a value which
excludes Octave's own built-in functions.  If the
@code{Octave:remove-init-dir} warning is enabled then Octave will warn
when the @code{path} function has been used in a way that may render
Octave unworkable.
By default, the @code{Octave:remove-init-dir} warning is enabled.

@item Octave:reload-forces-clear
If several functions have been loaded from the same file, Octave must
clear all the functions before any one of them can be reloaded.  If
the @code{Octave:reload-forces-clear} warning is enabled, Octave will
warn you when this happens, and print a list of the additional
functions that it is forced to clear.
By default, the @code{Octave:reload-forces-clear} warning is enabled.

@item Octave:resize-on-range-error
If the @code{Octave:resize-on-range-error} warning is enabled, print a
warning when a matrix is resized by an indexed assignment with
indices outside the current bounds.
By default, the @code{Octave:resize-on-range-error} warning is disabled.

@item Octave:separator-insert
Print warning if commas or semicolons might be inserted
automatically in literal matrices.
By default, the @code{Octave:separator-insert} warning is disabled.

@item Octave:shadowed-function
By default, the @code{Octave:shadowed-function} warning is enabled.

@item Octave:single-quote-string
Print warning if a single quote character is used to introduce a
string constant.
By default, the @code{Octave:single-quote-string} warning is disabled.

@item Octave:sqrtm:SingularMatrix
By default, the @code{Octave:sqrtm:SingularMatrix} warning is enabled.

@item Octave:str-to-num
If the @code{Octave:str-to-num} warning is enabled, a warning is printed
for implicit conversions of strings to their numeric UTF-8 encoded byte
sequences.  For example,

@example
@group
"abc" + 0
@result{} 97 98 99
@end group
@end example

@noindent
elicits a warning if the @code{Octave:str-to-num} warning is enabled.
By default, the @code{Octave:str-to-num} warning is disabled.

@item Octave:variable-switch-label
If the @code{Octave:variable-switch-label} warning is enabled, Octave
will print a warning if a switch label is not a constant or constant
expression.
By default, the @code{Octave:variable-switch-label} warning is disabled.
@end table

which
@c which scripts/help/which.m
@deftypefn {} {} which name @dots{}
Display the type of each @var{name}.

If @var{name} is defined from a function file, the full name of the file is
also displayed.
@xseealso{help, lookfor}
@end deftypefn
autumn
@c autumn scripts/image/autumn.m
@deftypefn  {} {@var{map} =} autumn ()
@deftypefnx {} {@var{map} =} autumn (@var{n})
Create color colormap.
This colormap ranges from red through orange to yellow.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
bone
@c bone scripts/image/bone.m
@deftypefn  {} {@var{map} =} bone ()
@deftypefnx {} {@var{map} =} bone (@var{n})
Create color colormap.  This colormap varies from black to white with
gray-blue shades.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
brighten
@c brighten scripts/image/brighten.m
@deftypefn  {} {@var{map_out} =} brighten (@var{beta})
@deftypefnx {} {@var{map_out} =} brighten (@var{map}, @var{beta})
@deftypefnx {} {@var{map_out} =} brighten (@var{h}, @var{beta})
@deftypefnx {} {} brighten (@dots{})
Brighten or darken a colormap.

The argument @var{beta} must be a scalar between -1 and 1, where a negative
value darkens and a positive value brightens the colormap.

If the @var{map} argument is omitted, the function is applied to the current
colormap.

The first argument can also be a valid graphics handle @var{h}, in which
case @code{brighten} is applied to the colormap associated with this handle.

If no output is specified then the result is written to the current
colormap.
@xseealso{colormap, contrast}
@end deftypefn
cmpermute
@c cmpermute scripts/image/cmpermute.m
@deftypefn  {} {[@var{Y}, @var{newmap}] =} cmpermute (@var{X}, @var{map})
@deftypefnx {} {[@var{Y}, @var{newmap}] =} cmpermute (@var{X}, @var{map}, @var{index})
Reorder colors in a colormap.

When called with only two arguments, @code{cmpermute} randomly rearranges
the colormap @var{map} and returns a new colormap @var{newmap}.  It also
returns the indexed image @var{Y} which is the equivalent of the original
input image @var{X} when displayed using @var{newmap}.

When called with an optional third argument the order of colors in the new
colormap is defined by @var{index}.

@strong{Caution:} @var{index} should not have repeated elements or the
function will fail.

@end deftypefn
cmunique
@c cmunique scripts/image/cmunique.m
@deftypefn  {} {[@var{Y}, @var{newmap}] =} cmunique (@var{X}, @var{map})
@deftypefnx {} {[@var{Y}, @var{newmap}] =} cmunique (@var{RGB})
@deftypefnx {} {[@var{Y}, @var{newmap}] =} cmunique (@var{I})
Convert an input image @var{X} to an output indexed image @var{Y} which uses
the smallest colormap possible @var{newmap}.

When the input is an indexed image (@var{X} with colormap @var{map}) the
output is a colormap @var{newmap} from which any repeated rows have been
eliminated.  The output image, @var{Y}, is the original input image with
the indices adjusted to match the new, possibly smaller, colormap.

When the input is an RGB image (an @nospell{MxNx3} array), the output
colormap will contain one entry for every unique color in the original
image.  In the worst case the new map could have as many rows as the
number of pixels in the original image.

When the input is a grayscale image @var{I}, the output colormap will
contain one entry for every unique intensity value in the original image.
In the worst case the new map could have as many rows as the number of
pixels in the original image.

Implementation Details:

@var{newmap} is always an Mx3 matrix, even if the input image is
an intensity grayscale image @var{I} (all three RGB planes are
assigned the same value).

The output image is of class uint8 if the size of the new colormap is
less than or equal to 256.  Otherwise, the output image is of class double.

@xseealso{rgb2ind, gray2ind}
@end deftypefn
colorcube
@c colorcube scripts/image/colorcube.m
@deftypefn  {} {@var{map} =} colorcube ()
@deftypefnx {} {@var{map} =} colorcube (@var{n})
Create color colormap.  This colormap is composed of as many equally
spaced colors (not grays) in the RGB color space as possible.

If there are not a perfect number @var{n} of regularly spaced colors then
the remaining entries in the colormap are gradients of pure red, green,
blue, and gray.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
colormap
@c colormap scripts/image/colormap.m
@deftypefn  {} {@var{cmap} =} colormap ()
@deftypefnx {} {@var{cmap} =} colormap (@var{map})
@deftypefnx {} {@var{cmap} =} colormap (@qcode{"default"})
@deftypefnx {} {@var{cmap} =} colormap (@var{map_name})
@deftypefnx {} {@var{cmap} =} colormap (@var{hax}, @dots{})
@deftypefnx {} {} colormap @var{map_name}
Query or set the current colormap.

With no input arguments, @code{colormap} returns the current color map.

@code{colormap (@var{map})} sets the current colormap to @var{map}.  The
colormap should be an @var{n} row by 3 column matrix.  The columns
contain red, green, and blue intensities respectively.  All entries
must be between 0 and 1 inclusive.  The new colormap is returned.

@code{colormap (@qcode{"default"})} restores the default colormap (the
@code{viridis} map with 64 entries).  The default colormap is returned.

The map may also be specified by a string, @var{map_name}, which
is the name of a function that returns a colormap.

If the first argument @var{hax} is an axes handle, then the colormap for
those axes is queried or set.

For convenience, it is also possible to use this function with the
command form, @code{colormap @var{map_name}}.

The list of built-in colormaps is:

@c FIXME: It would be nice to display the actual colormap as an image
@c        in the PDF version of the documentation.
@multitable @columnfractions 0.15 .85
@headitem Map @tab Description
@item viridis @tab default
@item jet @tab colormap traversing blue, cyan, green, yellow, red.
@item cubehelix @tab colormap traversing black, blue, green, red, white with increasing intensity.
@item hsv @tab cyclic colormap traversing Hue, Saturation, Value space.
@item rainbow @tab colormap traversing red, yellow, blue, green, violet.
@item ------------- @tab ---------------------------------------------------------------------------------------------
@item hot @tab colormap traversing black, red, orange, yellow, white.
@item cool @tab colormap traversing cyan, purple, magenta.
@item spring @tab colormap traversing magenta to yellow.
@item summer @tab colormap traversing green to yellow.
@item autumn @tab colormap traversing red, orange, yellow.
@item winter @tab colormap traversing blue to green.
@item ------------- @tab ---------------------------------------------------------------------------------------------
@item gray @tab colormap traversing black to white in shades of gray.
@item bone @tab colormap traversing black, gray-blue, white.
@item copper @tab colormap traversing black to light copper.
@item pink @tab colormap traversing black, gray-pink, white.
@item ocean @tab colormap traversing black, dark-blue, white.
@item ------------- @tab ---------------------------------------------------------------------------------------------
@item colorcube @tab equally spaced colors in RGB color space.
@item flag @tab cyclic 4-color map of red, white, blue, black.
@item lines @tab cyclic colormap with colors from axes @qcode{"ColorOrder"} property.
@item prism @tab cyclic 6-color map of red, orange, yellow, green, blue, violet.
@item ------------- @tab ---------------------------------------------------------------------------------------------
@item white @tab all white colormap (no colors).
@end multitable
@xseealso{viridis, jet, cubehelix, hsv, rainbow, hot, cool, spring, summer, autumn, winter, gray, bone, copper, pink, ocean, colorcube, flag, lines, prism, white}
@end deftypefn
contrast
@c contrast scripts/image/contrast.m
@deftypefn  {} {@var{cmap} =} contrast (@var{x})
@deftypefnx {} {@var{cmap} =} contrast (@var{x}, @var{n})
Return a gray colormap that maximizes the contrast in an image.

The returned colormap will have @var{n} rows.  If @var{n} is not defined
then the size of the current colormap is used.
@xseealso{colormap, brighten}
@end deftypefn
cool
@c cool scripts/image/cool.m
@deftypefn  {} {@var{map} =} cool ()
@deftypefnx {} {@var{map} =} cool (@var{n})
Create color colormap.  The colormap varies from cyan to magenta.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
copper
@c copper scripts/image/copper.m
@deftypefn  {} {@var{map} =} copper ()
@deftypefnx {} {@var{map} =} copper (@var{n})
Create color colormap.  This colormap varies from black to a light copper
tone.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
cubehelix
@c cubehelix scripts/image/cubehelix.m
@deftypefn  {} {@var{map} =} cubehelix ()
@deftypefnx {} {@var{map} =} cubehelix (@var{n})
Create cubehelix colormap.

This colormap varies from black to white going though blue, green, and red
tones while maintaining a monotonically increasing perception of intensity.
This is achieved by traversing a color cube from black to white through
a helix, hence the name cubehelix, while taking into account the perceived
brightness of each channel according to the NTSC specifications from 1953.

@example
rgbplot (cubehelix (256))
@end example

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.

Reference: Green, D. A., 2011,
@cite{"A @nospell{colour} scheme for the display of astronomical intensity
images"}, Bulletin of the Astronomical Society of India, 39, 289.

@xseealso{colormap}
@end deftypefn
flag
@c flag scripts/image/flag.m
@deftypefn  {} {@var{map} =} flag ()
@deftypefnx {} {@var{map} =} flag (@var{n})
Create color colormap.  This colormap cycles through red, white, blue, and
black with each index change.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
frame2im
@c frame2im scripts/image/frame2im.m
@deftypefn {} {[@var{x}, @var{map}] =} frame2im (@var{frame})
Convert movie frame to indexed image.

A movie frame is simply a struct with the fields @qcode{"cdata"} and
@qcode{"colormap"}.

Support for N-dimensional images or movies is given when @var{frame} is a
struct array.  In such cases, @var{x} will be a @nospell{MxNx1xK or MxNx3xK}
for indexed and RGB movies respectively, with each frame concatenated
along the 4th dimension.

@xseealso{im2frame, getframe}
@end deftypefn
getframe
@c getframe scripts/image/getframe.m
@deftypefn  {} {@var{frame} =} getframe ()
@deftypefnx {} {@var{frame} =} getframe (@var{hax})
@deftypefnx {} {@var{frame} =} getframe (@var{hfig})
@deftypefnx {} {@var{frame} =} getframe (@dots{}, @var{rect})

Capture a figure or axes as a movie frame structure.

Without an argument, capture the current axes excluding ticklabels, title,
and x/y/zlabels.  The returned structure @var{frame} has a field
@code{cdata}, which contains the actual image data in the form of an
@nospell{NxMx3} (RGB) uint8 matrix, and a field @code{colormap} which is
provided for @sc{matlab} compatibility but is always empty.

If the first argument @var{hax} is an axes handle, then capture this axes,
rather than the current axes returned by @code{gca}.

If the first argument @var{hfig} is a figure handle then the entire
corresponding figure canvas is captured.

Finally, if a second argument @var{rect} is provided it must be a
four-element vector ([left bottom width height]) defining the region inside
the figure to be captured.  Regardless of the figure @qcode{"units"}
property, @var{rect} must be defined in @strong{pixels}.

@xseealso{im2frame, frame2im, movie}
@end deftypefn
gray
@c gray scripts/image/gray.m
@deftypefn  {} {@var{map} =} gray ()
@deftypefnx {} {@var{map} =} gray (@var{n})
Create gray colormap.  This colormap varies from black to white with shades
of gray.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
gray2ind
@c gray2ind scripts/image/gray2ind.m
@deftypefn  {} {@var{img} =} gray2ind (@var{I})
@deftypefnx {} {@var{img} =} gray2ind (@var{I}, @var{n})
@deftypefnx {} {@var{img} =} gray2ind (@var{BW})
@deftypefnx {} {@var{img} =} gray2ind (@var{BW}, @var{n})
@deftypefnx {} {[@var{img}, @var{map}] =} gray2ind (@dots{})
Convert a grayscale or binary intensity image to an indexed image.

The indexed image will consist of @var{n} different intensity values.
If not given @var{n} defaults to 64 for grayscale images or 2 for binary
black and white images.

The output @var{img} is of class uint8 if @var{n} is less than or equal to
256; Otherwise the return class is uint16.
@xseealso{ind2gray, rgb2ind}
@end deftypefn
hot
@c hot scripts/image/hot.m
@deftypefn  {} {@var{map} =} hot ()
@deftypefnx {} {@var{map} =} hot (@var{n})
Create color colormap.  This colormap ranges from black through dark red,
red, orange, yellow, to white.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
hsv
@c hsv scripts/image/hsv.m
@deftypefn {} {} hsv (@var{n})
Create color colormap.  This colormap begins with red, changes through
yellow, green, cyan, blue, and magenta, before returning to red.

It is useful for displaying periodic functions.  The map is obtained by
linearly varying the hue through all possible values while keeping constant
maximum saturation and value.  The equivalent code is
@code{hsv2rgb ([(0:N-1)'/N, ones(N,2)])}.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
hsv2rgb
@c hsv2rgb scripts/image/hsv2rgb.m
@deftypefn  {} {@var{rgb_map} =} hsv2rgb (@var{hsv_map})
@deftypefnx {} {@var{rgb_img} =} hsv2rgb (@var{hsv_img})
Transform a colormap or image from HSV to RGB color space.

A color in HSV space is represented by hue, saturation and value
(brightness) levels in a cylindrical coordinate system.  Hue is the
azimuth and describes the dominant color.  Saturation is the radial
distance and gives the amount of hue mixed into the color.  Value is
the height and is the amount of light in the color.

The input can be both a colormap or RGB image.  In the case of floating
point input, values are expected to be on the [0 1] range.  In the case
of hue (azimuth), since the value corresponds to an angle,
@code{mod (h, 1)} is used.

@example
@group
>> hsv2rgb ([0.5 1 1])
@result{} ans = 0 1 1

>> hsv2rgb ([2.5 1 1])
@result{} ans = 0 1 1

>> hsv2rgb ([3.5 1 1])
@result{} ans = 0 1 1
@end group
@end example

Output class and size will be the same as input.

@xseealso{rgb2hsv, ind2rgb}
@end deftypefn
im2double
@c im2double scripts/image/im2double.m
@deftypefn  {} {} im2double (@var{img})
@deftypefnx {} {} im2double (@var{img}, "indexed")
Convert image to double precision.

The conversion of @var{img} to double precision, is dependent
on the type of input image.  The following input classes are
supported:

@table @samp
@item uint8, uint16, and int16
The range of values from the class is scaled to the interval [0 1].

@item logical
True and false values are assigned a value of 0 and 1 respectively.

@item single
Values are cast to double.

@item double
Returns the same image.

@end table

If @var{img} is an indexed image, then the second argument should be
the string @qcode{"indexed"}.  If so, then @var{img} must either be
of floating point class, or unsigned integer class and it will simply
be cast to double.  If it is an integer class, a +1 offset is applied.

@xseealso{double}
@end deftypefn
im2frame
@c im2frame scripts/image/im2frame.m
@deftypefn  {} {} im2frame (@var{rgb})
@deftypefnx {} {} im2frame (@var{x}, @var{map})
Convert image to movie frame.

A movie frame is simply a struct with the fields @qcode{"cdata"} and
@qcode{"colormap"}.

Support for N-dimensional images is given when each image projection,
matrix sizes of @nospell{MxN and MxNx3} for RGB images, is concatenated
along the fourth dimension.  In such cases, the returned value is a struct
array.

@xseealso{frame2im}
@end deftypefn
image
@c image scripts/image/image.m
@deftypefn  {} {} image (@var{img})
@deftypefnx {} {} image (@var{x}, @var{y}, @var{img})
@deftypefnx {} {} image (@dots{}, "@var{prop}", @var{val}, @dots{})
@deftypefnx {} {} image ("@var{prop1}", @var{val1}, @dots{})
@deftypefnx {} {@var{h} =} image (@dots{})
Display a matrix as an indexed color image.

The elements of @var{img} are indices into the current colormap.

@var{x} and @var{y} are optional 2-element vectors, @w{@code{[min, max]}},
which specify the coordinates of the centers of the corner pixels.
If a range is specified as @w{@code{[max, min]}} then the image will be
reversed along that axis.  For convenience, @var{x} and @var{y} may be
specified as N-element vectors matching the length of the data in @var{img}.
However, only the first and last elements will be used to determine the axis
limits.

Multiple property/value pairs may be specified for the image object, but
they must appear in pairs.

The optional return value @var{h} is a graphics handle to the image.

Implementation Note: The origin (0, 0) for images is located in the
upper left.  For ordinary plots, the origin is located in the lower
left.  Octave handles this inversion by plotting the data normally,
and then reversing the direction of the y-axis by setting the
@code{ydir} property to @qcode{"reverse"}.  This has implications whenever
an image and an ordinary plot need to be overlaid.  The recommended
solution is to display the image and then plot the reversed ydata
using, for example, @code{flipud (ydata)}.

Calling Forms: The @code{image} function can be called in two forms:
High-Level and Low-Level.  When invoked with normal options, the High-Level
form is used which first calls @code{newplot} to prepare the graphic figure
and axes.  When the only inputs to @code{image} are property/value pairs
the Low-Level form is used which creates a new instance of an image object
and inserts it in the current axes.

Graphic Properties: The full list of properties is documented at
@ref{Image Properties,,Image Properties}.
@xseealso{imshow, imagesc, colormap}
@end deftypefn
imagesc
@c imagesc scripts/image/imagesc.m
@deftypefn  {} {} imagesc (@var{img})
@deftypefnx {} {} imagesc (@var{x}, @var{y}, @var{img})
@deftypefnx {} {} imagesc (@dots{}, @var{climits})
@deftypefnx {} {} imagesc (@dots{}, "@var{prop}", @var{val}, @dots{})
@deftypefnx {} {} imagesc ("@var{prop1}", @var{val1}, @dots{})
@deftypefnx {} {} imagesc (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} imagesc (@dots{})
Display a scaled version of the matrix @var{img} as a color image.

The colormap is scaled so that the entries of the matrix occupy the entire
colormap.  If @code{@var{climits} = [@var{lo}, @var{hi}]} is given, then
that range is set to the @qcode{"clim"} of the current axes.

@var{x} and @var{y} are optional 2-element vectors, @w{@code{[min, max]}},
which specify the coordinates of the centers of the corner pixels.
If a range is specified as @w{@code{[max, min]}} then the image will be
reversed along that axis.  For convenience, @var{x} and @var{y} may be
specified as N-element vectors matching the length of the data in @var{img}.
However, only the first and last elements will be used to determine
the image limits.

The optional return value @var{h} is a graphics handle to the image.

Calling Forms: The @code{imagesc} function can be called in two forms:
High-Level and Low-Level.  When invoked with normal options, the High-Level
form is used which first calls @code{newplot} to prepare the graphic figure
and axes.  When the only inputs to @code{image} are property/value pairs
the Low-Level form is used which creates a new instance of an image object
and inserts it in the current axes.

@xseealso{image, imshow, caxis}
@end deftypefn
imfinfo
@c imfinfo scripts/image/imfinfo.m
@deftypefn  {} {@var{info} =} imfinfo (@var{filename})
@deftypefnx {} {@var{info} =} imfinfo (@var{url})
@deftypefnx {} {@var{info} =} imfinfo (@dots{}, @var{ext})
Read image information from a file.

@code{imfinfo} returns a structure containing information about the image
stored in the file @var{filename}.  If there is no file @var{filename},
and @var{ext} was specified, it will look for a file named @var{filename}
and extension @var{ext}, i.e., a file named @var{filename}.@var{ext}.

The output structure @var{info} contains the following fields:

@table @samp
@item Filename
The full name of the image file.

@item FileModDate
Date of last modification to the file.

@item FileSize
Number of bytes of the image on disk

@item Format
Image format (e.g., @qcode{"jpeg"}).

@item Height
Image height in pixels.

@item Width
Image Width in pixels.

@item BitDepth
Number of bits per channel per pixel.

@item ColorType
Image type.  Value is @qcode{"grayscale"}, @qcode{"indexed"},
@qcode{"truecolor"}, @qcode{"CMYK"}, or @qcode{"undefined"}.

@item XResolution
X resolution of the image.

@item YResolution
Y resolution of the image.

@item ResolutionUnit
Units of image resolution.  Value is @qcode{"Inch"},
@qcode{"Centimeter"}, or @qcode{"undefined"}.

@item DelayTime
Time in @nospell{1/100ths} of a second (0 to 65535) which must expire before
displaying the next image in an animated sequence.

@item LoopCount
Number of iterations to loop an animation.

@item ByteOrder
Endian option for formats that support it.  Value is
@qcode{"little-endian"}, @qcode{"big-endian"}, or @qcode{"undefined"}.

@item Gamma
Gamma level of the image.  The same color image displayed on two different
workstations may look different due to differences in the display monitor.

@item Quality
JPEG/MIFF/PNG compression level.  Value is an integer in the range [0 100].

@item DisposalMethod
Only valid for GIF images, control how successive frames are rendered (how
the preceding frame is disposed of) when creating a GIF animation.  Values
can be @qcode{"doNotSpecify"}, @qcode{"leaveInPlace"}, @qcode{"restoreBG"},
or @qcode{"restorePrevious"}.  For non-GIF files, value is an empty string.

@item Chromaticities
Value is a 1x8 Matrix with the x,y chromaticity values for white, red,
green, and blue points, in that order.

@item Comment
Image comment.

@item Compression
Compression type.  Value can be @qcode{"none"}, @qcode{"bzip"},
@qcode{"fax3"}, @qcode{"fax4"}, @qcode{"jpeg"}, @qcode{"lzw"},
@qcode{"rle"}, @qcode{"deflate"}, @qcode{"lzma"}, @qcode{"jpeg2000"},
@qcode{"jbig2"}, @qcode{"jbig2"}, or @qcode{"undefined"}.

@item Colormap
Colormap for each image.

@item Orientation
The orientation of the image with respect to the rows and columns.  Value
is an integer between 1 and 8 as defined in the TIFF 6 specifications, and
for @sc{matlab} compatibility.

@item Software
Name and version of the software or firmware of the camera or image input
device used to generate the image.

@item Make
The manufacturer of the recording equipment.  This is the manufacture of the
@nospell{DSC}, scanner, video digitizer or other equipment that generated
the image.

@item Model
The model name or model number of the recording equipment as mentioned on
the field @qcode{"Make"}.

@item DateTime
The date and time of image creation as defined by the Exif standard, i.e.,
it is the date and time the file was changed.

@item ImageDescription
The title of the image as defined by the Exif standard.

@item Artist
Name of the camera owner, photographer or image creator.

@item Copyright
Copyright notice of the person or organization claiming rights to the image.

@item DigitalCamera
A struct with information retrieved from the Exif tag.

@item GPSInfo
A struct with geotagging information retrieved from the Exif tag.
@end table

@xseealso{imread, imwrite, imshow, imformats}
@end deftypefn
imformats
@c imformats scripts/image/imformats.m
@deftypefn  {} {} imformats ()
@deftypefnx {} {@var{formats} =} imformats (@var{ext})
@deftypefnx {} {@var{formats} =} imformats (@var{format})
@deftypefnx {} {@var{formats} =} imformats ("add", @var{format})
@deftypefnx {} {@var{formats} =} imformats ("remove", @var{ext})
@deftypefnx {} {@var{formats} =} imformats ("update", @var{ext}, @var{format})
@deftypefnx {} {@var{formats} =} imformats ("factory")
Manage supported image formats.

@var{formats} is a structure with information about each supported file
format, or from a specific format @var{ext}, the value displayed on the
field @var{ext}.  It contains the following fields:

@table @asis
@item ext
The name of the file format.  This may match the file extension but Octave
will automatically detect the file format.

@item description
A long description of the file format.

@item @nospell{isa}
A function handle to confirm if a file is of the specified format.

@item write
A function handle to write if a file is of the specified format.

@item read
A function handle to open files the specified format.

@item info
A function handle to obtain image information of the specified format.

@item alpha
Logical value if format supports alpha channel (transparency or matte).

@item multipage
Logical value if format supports multipage (multiple images per file).
@end table

It is possible to change the way Octave manages file formats with the
options @qcode{"add"}, @qcode{"remove"}, and @qcode{"update"}, and supplying
a structure @var{format} with the required fields.  The option
@qcode{"factory"} resets the configuration to the default.

This can be used by Octave packages to extend the image reading capabilities
Octave, through use of the PKG_ADD and PKG_DEL commands.

@xseealso{imfinfo, imread, imwrite}
@end deftypefn
imread
@c imread scripts/image/imread.m
@deftypefn  {} {[@var{img}, @var{map}, @var{alpha}] =} imread (@var{filename})
@deftypefnx {} {[@dots{}] =} imread (@var{url})
@deftypefnx {} {[@dots{}] =} imread (@dots{}, @var{ext})
@deftypefnx {} {[@dots{}] =} imread (@dots{}, @var{idx})
@deftypefnx {} {[@dots{}] =} imread (@dots{}, @var{param1}, @var{value1}, @dots{})
Read images from various file formats.

Read an image as a matrix from the file @var{filename} or from the online
resource @var{url}.  If neither is given, but @var{ext} was specified, look
for a file with the extension @var{ext}.

The size and class of the output depends on the format of the image.  A
color image is returned as an @nospell{MxNx3} matrix.  Grayscale and
black-and-white images are of size @nospell{MxN}@.  Multipage images will
have an additional 4th dimension.

The bit depth of the image determines the class of the output:
@qcode{"uint8"}, @qcode{"uint16"}, or @qcode{"single"} for grayscale and
color, and @qcode{"logical"} for black-and-white.  Note that indexed images
always return the indexes for a colormap, independent of whether @var{map}
is a requested output.  To obtain the actual RGB image, use @code{ind2rgb}.
When more than one indexed image is being read, @var{map} is obtained from
the first.  In some rare cases this may be incorrect and @code{imfinfo} can
be used to obtain the colormap of each image.

See the Octave manual for more information in representing images.

Some file formats, such as TIFF and GIF, are able to store multiple images
in a single file.  @var{idx} can be a scalar or vector specifying the
index of the images to read.  By default, Octave will read only the first
page.

Depending on the file format, it is possible to configure the reading of
images with @var{parameter}, @var{value} pairs.  The following options are
supported:

@table @asis
@item @qcode{"Frames"} or @qcode{"Index"}
This is an alternative method to specify @var{idx}.  When specifying it
in this way, its value can also be the string @qcode{"all"}.

@item @qcode{"Info"}
This option exists for @sc{matlab} compatibility, but has no effect.  For
maximum performance when reading multiple images from a single file, use
the @qcode{"Index"} option.

@item @qcode{"PixelRegion"}
Controls the image region that is read.  The value must be a cell array with
two arrays of 3 elements @code{@{[@var{rows}], [@var{cols}]@}}.  The
elements in the array are the start, increment, and end pixel to be read.
If the increment value is omitted it defaults to 1.  For example, the
following are all equivalent:

@example
@group
imread (filename, "PixelRegion", @{[200 600], [300 700]@});
imread (filename, "PixelRegion", @{[200 1 600], [300 1 700]@});
imread (filename)(200:600, 300:700);
@end group
@end example

@end table

@xseealso{imwrite, imfinfo, imformats}
@end deftypefn
imshow
@c imshow scripts/image/imshow.m
@deftypefn  {} {} imshow (@var{im})
@deftypefnx {} {} imshow (@var{im}, @var{limits})
@deftypefnx {} {} imshow (@var{im}, @var{map})
@deftypefnx {} {} imshow (@var{rgb}, @dots{})
@deftypefnx {} {} imshow (@var{filename})
@deftypefnx {} {} imshow (@dots{}, @var{string_param1}, @var{value1}, @dots{})
@deftypefnx {} {@var{h} =} imshow (@dots{})
Display the image @var{im}, where @var{im} can be a 2-dimensional
(grayscale image) or a 3-dimensional (RGB image) matrix.

If @var{limits} is a 2-element vector @code{[@var{low}, @var{high}]}, the
image is shown using a display range between @var{low} and @var{high}.  If
an empty matrix is passed for @var{limits}, the display range is computed
as the range between the minimal and the maximal value in the image.

If @var{map} is a valid color map, the image will be shown as an indexed
image using the supplied color map.

If a filename is given instead of an image, the file will be read and shown.

If given, the parameter @var{string_param1} has value @var{value1}.
@var{string_param1} can be any of the following:

@table @asis
@item @qcode{"displayrange"}
@var{value1} is the display range as described above.

@item @qcode{"colormap"}
@var{value1} is the colormap to use when displaying an indexed image.

@item @qcode{"xdata"}
If @var{value1} is a 2-element vector, it must contain horizontal image
limits in the form [xfirst, xlast], where xfirst and xlast are the
abscissa of the centers of the corner pixels.  Otherwise @var{value1}
 must be a vector and only the first and last elements will be used
for xfirst and xlast respectively.

@item @qcode{"ydata"}
If @var{value1} is a 2-element vector, it must contain vertical image
limits in the form [yfirst, ylast], where yfirst and ylast are the ordinates
of the center of the corner pixels.  Otherwise @var{value1} must be a vector
and only the first and last elements will be used for yfirst and ylast
respectively.

@end table

The optional return value @var{h} is a graphics handle to the image.
@xseealso{image, imagesc, colormap, gray2ind, rgb2ind}
@end deftypefn
imwrite
@c imwrite scripts/image/imwrite.m
@deftypefn  {} {} imwrite (@var{img}, @var{filename})
@deftypefnx {} {} imwrite (@var{img}, @var{filename}, @var{ext})
@deftypefnx {} {} imwrite (@var{img}, @var{map}, @var{filename})
@deftypefnx {} {} imwrite (@dots{}, @var{param1}, @var{val1}, @dots{})
Write images in various file formats.

The image @var{img} can be a binary, grayscale, RGB, or multi-dimensional
image.  The size and class of @var{img} should be the same as what should
be expected when reading it with @code{imread}: the 3rd and 4th dimensions
reserved for color space, and multiple pages respectively.  If it's an
indexed image, the colormap @var{map} must also be specified.

If @var{ext} is not supplied, the file extension of @var{filename} is used
to determine the format.  The actual supported formats are dependent on
options made during the build of Octave.  Use @code{imformats} to check
the support of the different image formats.

Depending on the file format, it is possible to configure the writing of
images with @var{param}, @var{val} pairs.  The following options are
supported:

@table @samp
@item Alpha
Alpha (transparency) channel for the image.  This must be a matrix with
same class, and number of rows and columns of @var{img}.  In case of a
multipage image, the size of the 4th dimension must also match and the third
dimension must be a singleton.  By default, image will be completely opaque.

@item Compression
Compression to use one the image.  Can be one of the following: "none"
(default), "bzip", "fax3", "fax4", "jpeg", "lzw", "rle", or "deflate".
Note that not all compression types are available for all image formats
in which it defaults to your @nospell{Magick} library.

@item DelayTime
For formats that accept animations (such as GIF), controls for how long a
frame is displayed until it moves to the next one.  The value must be scalar
(which will applied to all frames in @var{img}), or a vector of length
equal to the number of frames in @var{im}.  The value is in seconds, must
be between 0 and 655.35, and defaults to 0.5.

@item DisposalMethod
For formats that accept animations (such as GIF), controls what happens to
a frame before drawing the next one.  Its value can be one of the
following strings: "doNotSpecify" (default); "leaveInPlace"; "restoreBG";
and "restorePrevious", or a cell array of those string with length equal
to the number of frames in @var{img}.

@item LoopCount
For formats that accept animations (such as GIF), controls how many times
the sequence is repeated.  A value of Inf means an infinite loop (default),
a value of 0 or 1 that the sequence is played only once (loops zero times),
while a value of 2 or above loops that number of times (looping twice means
it plays the complete sequence 3 times).  This option is ignored when there
is only a single image at the end of writing the file.

@item Quality
Set the quality of the compression.  The value should be an integer
between 0 and 100, with larger values indicating higher visual quality and
lower compression.  Defaults to 75.

@item WriteMode
Some file formats, such as TIFF and GIF, are able to store multiple images
in a single file.  This option specifies if @var{img} should be appended
to the file (if it exists) or if a new file should be created for it
(possibly overwriting an existing file).  The value should be the string
@qcode{"Overwrite"} (default), or @qcode{"Append"}.

Despite this option, the most efficient method of writing a multipage
image is to pass a 4 dimensional @var{img} to @code{imwrite}, the same
matrix that could be expected when using @code{imread} with the option
@qcode{"Index"} set to @qcode{"all"}.

@end table

@xseealso{imread, imfinfo, imformats}
@end deftypefn
ind2gray
@c ind2gray scripts/image/ind2gray.m
@deftypefn {} {@var{I} =} ind2gray (@var{x}, @var{map})
Convert a color indexed image to a grayscale intensity image.

The image @var{x} must be an indexed image which will be converted using the
colormap @var{map}.  If @var{map} does not contain enough colors for the
image, pixels in @var{x} outside the range are mapped to the last color in
the map before conversion to grayscale.

The output @var{I} is of the same class as the input @var{x} and may be
one of @code{uint8}, @code{uint16}, @code{single}, or @code{double}.

Implementation Note: There are several ways of converting colors to
grayscale intensities.  This functions uses the luminance value obtained
from @code{rgb2gray} which is @code{I = 0.299*R + 0.587*G + 0.114*B}.
Other possibilities include the value component from @code{rgb2hsv} or
using a single color channel from @code{ind2rgb}.
@xseealso{gray2ind, ind2rgb}
@end deftypefn
ind2rgb
@c ind2rgb scripts/image/ind2rgb.m
@deftypefn  {} {@var{rgb} =} ind2rgb (@var{x}, @var{map})
@deftypefnx {} {[@var{R}, @var{G}, @var{B}] =} ind2rgb (@var{x}, @var{map})
Convert an indexed image to red, green, and blue color components.

The image @var{x} must be an indexed image which will be converted using the
colormap @var{map}.  If @var{map} does not contain enough colors for the
image, pixels in @var{x} outside the range are mapped to the last color in
the map.

The output may be a single RGB image (@nospell{MxNx3} matrix where M and N
are the original image @var{x} dimensions, one for each of the red, green
and blue channels).  Alternatively, the individual red, green, and blue
color matrices of size @nospell{MxN} may be returned.

Multi-dimensional indexed images (of size @nospell{MxNx1xK}) are also
supported.

@xseealso{rgb2ind, ind2gray, hsv2rgb}
@end deftypefn
iscolormap
@c iscolormap scripts/image/iscolormap.m
@deftypefn {} {} iscolormap (@var{cmap})
Return true if @var{cmap} is a colormap.

A colormap is a real matrix, of class single or double, with 3 columns.
Each row represents a single color.  The 3 columns contain red, green,
and blue intensities respectively.

All values in a colormap should be in the [0 1] range but this is not
enforced.  Each function must decide what to do for values outside this
range.

@xseealso{colormap, rgbplot}
@end deftypefn
jet
@c jet scripts/image/jet.m
@deftypefn  {} {@var{map} =} jet ()
@deftypefnx {} {@var{map} =} jet (@var{n})
Create color colormap.  This colormap ranges from dark blue through blue,
cyan, green, yellow, red, to dark red.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
lines
@c lines scripts/image/lines.m
@deftypefn  {} {@var{map} =} lines ()
@deftypefnx {} {@var{map} =} lines (@var{n})
Create color colormap.  This colormap is composed of the list of colors
in the current axes @qcode{"ColorOrder"} property.  The default is blue,
orange, yellow, purple, green, light blue, and dark red.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
movie
@c movie scripts/image/movie.m
@deftypefn  {} {} movie (@var{mov})
@deftypefnx {} {} movie (@var{mov}, @var{n})
@deftypefnx {} {} movie (@var{mov}, @var{n}, @var{fps})
@deftypefnx {} {} movie (@var{h}, @dots{})
Play a movie defined by an array of frame structures.

The movie @var{mov} must be a struct array of frames with fields
@qcode{"cdata"} and @qcode{"colormap"}, as returned by the @code{getframe}
function.  By default all images are displayed once, at 12 fps, in the
current axes.

The optional argument @var{n} is a scalar or vector of integers that
controls the number of times the movie is displayed and which particular
frames are shown:

@table @asis
@item First element:

@table @asis
@item @var{n}(1) > 0
Play the movie @var{n}(1) times.

@item @var{n}(1) < 0
Play the movie @code{abs (@var{n}(1)} times alternatively in forward and
backward order.
@end table

@item Other elements (if any):
Indices of the frames in @var{mov} that will be displayed.
@end table

If the first argument is a handle to a figure or axes @var{h}, the movie is
played in that figure or axes instead of the current axes.

@xseealso{getframe, im2frame, frame2im}
@end deftypefn
ocean
@c ocean scripts/image/ocean.m
@deftypefn  {} {@var{map} =} ocean ()
@deftypefnx {} {@var{map} =} ocean (@var{n})
Create color colormap.  This colormap varies from black to white with shades
of blue.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
pink
@c pink scripts/image/pink.m
@deftypefn  {} {@var{map} =} pink ()
@deftypefnx {} {@var{map} =} pink (@var{n})
Create color colormap.  This colormap varies from black to white with
shades of gray-pink.

This colormap gives a sepia tone when used on grayscale images.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
prism
@c prism scripts/image/prism.m
@deftypefn  {} {@var{map} =} prism ()
@deftypefnx {} {@var{map} =} prism (@var{n})
Create color colormap.  This colormap cycles through red, orange, yellow,
green, blue and violet with each index change.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
rainbow
@c rainbow scripts/image/rainbow.m
@deftypefn  {} {@var{map} =} rainbow ()
@deftypefnx {} {@var{map} =} rainbow (@var{n})
Create color colormap.  This colormap ranges from red through orange,
yellow, green, blue, to violet.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
rgb2gray
@c rgb2gray scripts/image/rgb2gray.m
@deftypefn  {} {@var{I} =} rgb2gray (@var{rgb_img})
@deftypefnx {} {@var{gray_map} =} rgb2gray (@var{rgb_map})
Transform an image or colormap from red-green-blue (RGB) color space to
a grayscale intensity image.

The input may be of class uint8, int8, uint16, int16, single, or double.
The output is of the same class as the input.

Implementation Note:
The grayscale intensity is calculated as

@example
@group
@var{I} = 0.298936*@var{R} + 0.587043*@var{G} + 0.114021*@var{B}
@end group
@end example

@noindent
which corresponds to the luminance channel when RGB is translated to
@nospell{YIQ} as documented in @url{https://en.wikipedia.org/wiki/YIQ}.
@xseealso{rgb2hsv, rgb2ind}
@end deftypefn
rgb2hsv
@c rgb2hsv scripts/image/rgb2hsv.m
@deftypefn  {} {@var{hsv_map} =} rgb2hsv (@var{rgb_map})
@deftypefnx {} {@var{hsv_img} =} rgb2hsv (@var{rgb_img})
Transform a colormap or image from RGB to HSV color space.

A color in the RGB space consists of red, green, and blue intensities.

A color in HSV space is represented by hue, saturation and value
(brightness) levels in a cylindrical coordinate system.  Hue is the
azimuth and describes the dominant color.  Saturation is the radial
distance and gives the amount of hue mixed into the color.  Value is
the height and is the amount of light in the color.

Output class and size will be the same as input.

@xseealso{hsv2rgb, rgb2ind, rgb2gray}
@end deftypefn
rgb2ind
@c rgb2ind scripts/image/rgb2ind.m
@deftypefn  {} {[@var{x}, @var{map}] =} rgb2ind (@var{rgb})
@deftypefnx {} {[@var{x}, @var{map}] =} rgb2ind (@var{R}, @var{G}, @var{B})
Convert an image in red-green-blue (RGB) color space to an indexed image.

The input image @var{rgb} can be specified as a single matrix of size
@nospell{MxNx3}, or as three separate variables, @var{R}, @var{G}, and
@var{B}, its three color channels, red, green, and blue.

It outputs an indexed image @var{x} and a colormap @var{map} to interpret
an image exactly the same as the input.  No dithering or other form of color
quantization is performed.  The output class of the indexed image @var{x}
can be uint8, uint16 or double, whichever is required to specify the
number of unique colors in the image (which will be equal to the number
of rows in @var{map}) in order.

Multi-dimensional indexed images (of size @nospell{MxNx3xK}) are also
supported, both via a single input (@var{rgb}) or its three color channels
as separate variables.

@xseealso{ind2rgb, rgb2hsv, rgb2gray}
@end deftypefn
rgbplot
@c rgbplot scripts/image/rgbplot.m
@deftypefn  {} {} rgbplot (@var{cmap})
@deftypefnx {} {} rgbplot (@var{cmap}, @var{style})
@deftypefnx {} {@var{h} =} rgbplot (@dots{})
Plot the components of a colormap.

Two different @var{style}s are available for displaying the @var{cmap}:

@table @asis
@item profile (default)
Plot the RGB line profile of the colormap for each of the channels (red,
green and blue) with the plot lines colored appropriately.  Each line
represents the intensity of an RGB component across the colormap.

@item composite
Draw the colormap across the X-axis so that the actual index colors are
visible rather than the individual color components.

@end table

The optional return value @var{h} is a graphics handle to the created plot.

Run @code{demo rgbplot} to see an example of @code{rgbplot} and each style
option.
@xseealso{colormap}
@end deftypefn
spinmap
@c spinmap scripts/image/spinmap.m
@deftypefn  {} {} spinmap ()
@deftypefnx {} {} spinmap (@var{t})
@deftypefnx {} {} spinmap (@var{t}, @var{inc})
@deftypefnx {} {} spinmap ("inf")
Cycle the colormap for @var{t} seconds with a color increment of @var{inc}.

Both parameters are optional.  The default cycle time is 5 seconds and the
default increment is 2.  If the option @qcode{"inf"} is given then cycle
continuously until @kbd{Control-C} is pressed.

When rotating, the original color 1 becomes color 2, color 2 becomes
color 3, etc.  A positive or negative increment is allowed and a higher
value of @var{inc} will cause faster cycling through the colormap.
@xseealso{colormap}
@end deftypefn
spring
@c spring scripts/image/spring.m
@deftypefn  {} {@var{map} =} spring ()
@deftypefnx {} {@var{map} =} spring (@var{n})
Create color colormap.  This colormap varies from magenta to yellow.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
summer
@c summer scripts/image/summer.m
@deftypefn  {} {@var{map} =} summer ()
@deftypefnx {} {@var{map} =} summer (@var{n})
Create color colormap.  This colormap varies from green to yellow.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
viridis
@c viridis scripts/image/viridis.m
@deftypefn  {} {@var{map} =} viridis ()
@deftypefnx {} {@var{map} =} viridis (@var{n})
Create color colormap.  This colormap ranges from dark purplish-blue through
blue, green, to yellow.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
white
@c white scripts/image/white.m
@deftypefn  {} {@var{map} =} white ()
@deftypefnx {} {@var{map} =} white (@var{n})
Create color colormap.  This colormap is completely white.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
winter
@c winter scripts/image/winter.m
@deftypefn  {} {@var{map} =} winter ()
@deftypefnx {} {@var{map} =} winter (@var{n})
Create color colormap.  This colormap varies from blue to green.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@xseealso{colormap}
@end deftypefn
beep
@c beep scripts/io/beep.m
@deftypefn {} {} beep ()
Produce a beep from the speaker (or visual bell).

This function sends the alarm character @qcode{"@xbackslashchar{}a"} to
the terminal.  Depending on the user's configuration this may produce an
audible beep, a visual bell, or nothing at all.
@xseealso{puts, fputs, printf, fprintf}
@end deftypefn
csvread
@c csvread scripts/io/csvread.m
@deftypefn  {} {@var{x} =} csvread (@var{filename})
@deftypefnx {} {@var{x} =} csvread (@var{filename}, @var{dlm_opt1}, @dots{})
Read the comma-separated-value (CSV) file @var{filename} into the matrix
@var{x}.

Note: only CSV files containing numeric data can be read.

This function is equivalent to

@example
@var{x} = dlmread (@var{filename}, "," , @var{dlm_opt1}, @dots{})
@end example

Any optional arguments are passed directly to @code{dlmread}
(@pxref{XREFdlmread,,dlmread}).
@xseealso{dlmread, textscan, csvwrite, dlmwrite}
@end deftypefn
csvwrite
@c csvwrite scripts/io/csvwrite.m
@deftypefn  {} {} csvwrite (@var{filename}, @var{x})
@deftypefnx {} {} csvwrite (@var{filename}, @var{x}, @var{dlm_opt1}, @dots{})
Write the numeric matrix @var{x} to the file @var{filename} in
@w{comma-separated-value} (CSV) format.

This function is equivalent to

@example
dlmwrite (@var{filename}, @var{x}, ",", @var{dlm_opt1}, @dots{})
@end example

Any optional arguments are passed directly to @code{dlmwrite}
(@pxref{XREFdlmwrite,,dlmwrite}).
@xseealso{csvread, dlmwrite, dlmread}
@end deftypefn
dlmwrite
@c dlmwrite scripts/io/dlmwrite.m
@deftypefn  {} {} dlmwrite (@var{file}, @var{M})
@deftypefnx {} {} dlmwrite (@var{file}, @var{M}, @var{delim}, @var{r}, @var{c})
@deftypefnx {} {} dlmwrite (@var{file}, @var{M}, @var{key}, @var{val} @dots{})
@deftypefnx {} {} dlmwrite (@var{file}, @var{M}, "-append", @dots{})
@deftypefnx {} {} dlmwrite (@var{fid}, @dots{})
Write the numeric matrix @var{M} to the text file @var{file} using a
delimiter.

@var{file} should be a filename or a writable file ID given by @code{fopen}.

The parameter @var{delim} specifies the delimiter to use to separate values
on a row.  If no delimiter is specified the comma character @samp{,} is
used.

The value of @var{r} specifies the number of delimiter-only lines to add to
the start of the file.

The value of @var{c} specifies the number of delimiters to prepend to each
line of data.

If the argument @qcode{"-append"} is given, append to the end of @var{file}.

In addition, the following keyword value pairs may appear at the end of
the argument list:

@table @asis
@item @qcode{"append"}
Either @qcode{"on"} or @qcode{"off"}.  See @qcode{"-append"} above.

@item @qcode{"delimiter"}
See @var{delim} above.

@item @qcode{"newline"}
The character(s) to separate each row.  Three special cases exist for this
option.  @qcode{"unix"} is changed into @qcode{"@xbackslashchar{}n"},
@qcode{"pc"} is changed into @qcode{"@xbackslashchar{}r@xbackslashchar{}n"},
and @qcode{"mac"} is changed into @qcode{"@xbackslashchar{}r"}.  Any other
value is used directly as the newline separator.

@item @qcode{"roffset"}
See @var{r} above.

@item @qcode{"coffset"}
See @var{c} above.

@item @qcode{"precision"}
The precision to use when writing the file.  It can either be a format
string (as used by fprintf) or a number of significant digits.
@end table

@example
dlmwrite ("file.csv", reshape (1:16, 4, 4));
@end example

@example
dlmwrite ("file.tex", a, "delimiter", "&", "newline", "\n")
@end example

@xseealso{dlmread, csvread, csvwrite}
@end deftypefn
fileread
@c fileread scripts/io/fileread.m
@deftypefn {} {@var{str} =} fileread (@var{filename})
Read the contents of @var{filename} and return it as a string.
@xseealso{fread, fscanf, importdata, textscan, type}
@end deftypefn
importdata
@c importdata scripts/io/importdata.m
@deftypefn  {} {@var{A} =} importdata (@var{fname})
@deftypefnx {} {@var{A} =} importdata (@var{fname}, @var{delimiter})
@deftypefnx {} {@var{A} =} importdata (@var{fname}, @var{delimiter}, @var{header_rows})
@deftypefnx {} {[@var{A}, @var{delimiter}] =} importdata (@dots{})
@deftypefnx {} {[@var{A}, @var{delimiter}, @var{header_rows}] =} importdata (@dots{})
Import data from the file @var{fname}.

Input parameters:

@itemize
@item @var{fname}
The name of the file containing data.

@item @var{delimiter}
The character separating columns of data.  Use @code{\t} for tab.
(Only valid for ASCII files)

@item @var{header_rows}
The number of header rows before the data begins.  (Only valid for ASCII
files)
@end itemize

Different file types are supported:

@itemize
@item ASCII table

Import ASCII table using the specified number of header rows and the
specified delimiter.

@item Image file

@item @sc{matlab} file

@item Spreadsheet files (depending on external software)

@item WAV file

@end itemize

@xseealso{textscan, dlmread, csvread, load}
@end deftypefn
is_valid_file_id
@c is_valid_file_id scripts/io/is_valid_file_id.m
@deftypefn {} {} is_valid_file_id (@var{fid})
Return true if @var{fid} refers to an open file.
@xseealso{freport, fopen}
@end deftypefn
javaArray
@c javaArray scripts/java/javaArray.m
@deftypefn  {} {@var{jary} =} javaArray (@var{classname}, @var{sz})
@deftypefnx {} {@var{jary} =} javaArray (@var{classname}, @var{m}, @var{n}, @dots{})

Create a Java array of size @var{sz} with elements of class @var{classname}.

@var{classname} may be a Java object representing a class or a string
containing the fully qualified class name.  The size of the object may
also be specified with individual integer arguments @var{m}, @var{n}, etc.

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

Sample code:

@example
@group
jary = javaArray ("java.lang.String", 2, 2);
jary(1,1) = "Hello";
@end group
@end example
@xseealso{javaObject}
@end deftypefn
java_get
@c java_get scripts/java/java_get.m
@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 following two statements are
equivalent

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

@xseealso{java_set, javaMethod, javaObject}
@end deftypefn
java_set
@c java_set scripts/java/java_set.m
@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 following two statements are
equivalent

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

@xseealso{java_get, javaMethod, javaObject}
@end deftypefn
javaaddpath
@c javaaddpath scripts/java/javaaddpath.m
@deftypefn  {} {} javaaddpath (@var{clspath})
@deftypefnx {} {} javaaddpath (@var{clspath1}, @dots{})
Add @var{clspath} to the dynamic class path of the Java virtual machine.

@var{clspath} may either be a directory where @file{.class} files are
found, or a @file{.jar} file containing Java classes.  Multiple paths may
be added at once by specifying additional arguments.
@xseealso{javarmpath, javaclasspath}
@end deftypefn
javachk
@c javachk scripts/java/javachk.m
@deftypefn  {} {} javachk (@var{feature})
@deftypefnx {} {} javachk (@var{feature}, @var{caller})
@deftypefnx {} {@var{msg} =} javachk (@dots{})
Check for the presence of the Java @var{feature} in the current session.
Return an error structure if @var{feature} is not available, not enabled,
or not recognized.

Possible recognized features are:

@table @asis
@item @nospell{@qcode{"awt"}}
Abstract Window Toolkit for GUIs.

@item @qcode{"desktop"}
Interactive desktop is running.

@item @qcode{"jvm"}
Java Virtual Machine.

@item @qcode{"swing"}
Swing components for lightweight GUIs.
@end table

If @var{feature} is not supported, a scalar struct with field
@qcode{"message"} and @qcode{"identifier"} is returned.  The field
@qcode{"message"} contains an error message mentioning @var{feature} as
well as the optional user-specified @var{caller}.  This structure is
suitable for passing in to the @code{error} function.

If @var{feature} is supported and available, an empty struct array is
returned with fields @qcode{"message"} and @qcode{"identifier"}.

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

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

@xseealso{usejava, error}
@end deftypefn
javaclasspath
@c javaclasspath scripts/java/javaclasspath.m
@deftypefn  {} {} javaclasspath ()
@deftypefnx {} {@var{dpath} =} javaclasspath ()
@deftypefnx {} {[@var{dpath}, @var{spath}] =} javaclasspath ()
@deftypefnx {} {@var{clspath} =} javaclasspath (@var{what})
Return the class path of the Java virtual machine in the form of a cell
array of strings.

If called with no inputs:

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

@item If one output value @var{dpath} is requested, the result is the
dynamic classpath.

@item If two output values@var{dpath} and @var{spath} are requested, the
first variable will contain the dynamic classpath and the second will
contain the static classpath.
@end itemize

If called with a single input parameter @var{what}:

@table @asis
@item @qcode{"-dynamic"}
Return the dynamic classpath.

@item @qcode{"-static"}
Return the static classpath.

@item @qcode{"-all"}
Return both the static and dynamic classpath in a single cellstr.
@end table
@xseealso{javaaddpath, javarmpath}
@end deftypefn
javamem
@c javamem scripts/java/javamem.m
@deftypefn  {} {} javamem ()
@deftypefnx {} {@var{jmem} =} javamem ()
Show the current memory usage of the Java virtual machine (JVM) and run the
garbage collector.

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

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

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

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

@nospell{-Xms64m}

@nospell{-Xmx512m}

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

@qcode{"Total memory"} is what the operating system has currently assigned
to the JVM and depends on actual and active memory usage.
@qcode{"Free memory"} is self-explanatory.  During operation of Java-based
Octave functions the amount of Total and Free memory will vary, due to
Java's own cleaning up and your operating system's memory management.
@end deftypefn
javarmpath
@c javarmpath scripts/java/javarmpath.m
@deftypefn  {} {} javarmpath (@var{clspath})
@deftypefnx {} {} javarmpath (@var{clspath1}, @dots{})
Remove @var{clspath} from the dynamic class path of the Java virtual
machine.

@var{clspath} may either be a directory where @file{.class} files are found,
or a @file{.jar} file containing Java classes.  Multiple paths may be
removed at once by specifying additional arguments.
@xseealso{javaaddpath, javaclasspath}
@end deftypefn
usejava
@c usejava scripts/java/usejava.m
@deftypefn {} {} usejava (@var{feature})
Return true if the Java element @var{feature} is available.

Possible features are:

@table @asis
@item @nospell{@qcode{"awt"}}
Abstract Window Toolkit for GUIs.

@item @qcode{"desktop"}
Interactive desktop is running.

@item @qcode{"jvm"}
Java Virtual Machine.

@item @qcode{"swing"}
Swing components for lightweight GUIs.
@end table

@code{usejava} determines if specific Java features are available in an
Octave session.  This function is provided for scripts which may alter
their behavior based on the availability of Java.  The feature
@qcode{"desktop"} always returns @code{false} as Octave has no Java-based
desktop.  Other features may be available if Octave was compiled with the
Java Interface and Java is installed.
@xseealso{javachk}
@end deftypefn
findstr
@c findstr scripts/legacy/findstr.m
@deftypefn  {} {} findstr (@var{s}, @var{t})
@deftypefnx {} {} findstr (@var{s}, @var{t}, @var{overlap})

This function is obsolete.  Use @code{strfind} instead.

Return the vector of all positions in the longer of the two strings @var{s}
and @var{t} where an occurrence of the shorter of the two starts.

If the optional argument @var{overlap} is true (default), the returned
vector can include overlapping positions.  For example:

@example
@group
findstr ("ababab", "a")
     @result{} [1, 3, 5];
findstr ("abababa", "aba", 0)
     @result{} [1, 5]
@end group
@end example

@strong{Caution:} @code{findstr} is obsolete.  Use @code{strfind} in all new
code.
@xseealso{strfind, strmatch, strcmp, strncmp, strcmpi, strncmpi, find}
@end deftypefn
flipdim
@c flipdim scripts/legacy/flipdim.m
@deftypefn  {} {} flipdim (@var{x})
@deftypefnx {} {} flipdim (@var{x}, @var{dim})
This function is obsolete.  Use @code{flip} instead.
@xseealso{flip, fliplr, flipud, rot90, rotdim}
@end deftypefn
genvarname
@c genvarname scripts/legacy/genvarname.m
@deftypefn  {} {@var{varname} =} genvarname (@var{str})
@deftypefnx {} {@var{varname} =} genvarname (@var{str}, @var{exclusions})

This function is obsolete.  Use @code{matlab.lang.makeValidName} or
@code{matlab.lang.makeUniqueStrings} instead.

Create valid unique variable name(s) from @var{str}.

If @var{str} is a cellstr, then a unique variable is created for each cell
in @var{str}.

@example
@group
genvarname (@{"foo", "foo"@})
  @result{}
     @{
       [1,1] = foo
       [1,2] = foo1
     @}
@end group
@end example

If @var{exclusions} is given, then the variable(s) will be unique to each
other and to @var{exclusions} (@var{exclusions} may be either a string or a
cellstr).

@example
@group
x = 3.141;
genvarname ("x", who ())
  @result{} x1
@end group
@end example

Note that the result is a char array or cell array of strings, not the
variables themselves.  To define a variable, @code{eval()} can be used.
The following trivial example sets @code{x} to 42.

@example
@group
name = genvarname ("x");
eval ([name " = 42"]);
  @result{} x =  42
@end group
@end example

This can be useful for creating unique struct field names.

@example
@group
x = struct ();
for i = 1:3
  x.(genvarname ("a", fieldnames (x))) = i;
endfor
  @result{} x =
     @{
       a =  1
       a1 =  2
       a2 =  3
     @}
@end group
@end example

Since variable names may only contain letters, digits, and underscores,
@code{genvarname} will replace any sequence of disallowed characters with
an underscore.  Also, variables may not begin with a digit; in this case
an @samp{x} is added before the variable name.

Variable names beginning and ending with two underscores @qcode{"__"} are
valid, but they are used internally by Octave and should generally be
avoided; therefore, @code{genvarname} will not generate such names.

@code{genvarname} will also ensure that returned names do not clash with
keywords such as @qcode{"for"} and @qcode{"if"}.  A number will be
appended if necessary.  Note, however, that this does @strong{not} include
function names such as @qcode{"sin"}.  Such names should be included in
@var{exclusions} if necessary.
@xseealso{matlab.lang.makeValidName, matlab.lang.makeUniqueStrings,
namelengthmax, isvarname, iskeyword, exist, who, tempname, eval}
@end deftypefn
isdir
@c isdir scripts/legacy/isdir.m
@deftypefn {} {} isdir (@var{f})

This function is not recommended.  Use @code{isfolder} or
@code{file_in_loadpath} instead.

Return true if @var{f} is a directory and false otherwise.

Compatibility Note: The @sc{matlab} function of the same name will also
search for @var{f} in the load path directories.  To emulate this behavior
use

@example
@var{tf} = ! isempty (file_in_loadpath (@var{f}))
@end example

@xseealso{isfolder, file_in_loadpath, exist, stat, is_absolute_filename, is_rooted_relative_filename}
@end deftypefn
isequalwithequalnans
@c isequalwithequalnans scripts/legacy/isequalwithequalnans.m
@deftypefn {} isequalwithequalnans (@var{x1}, @var{x2}, @dots{})
This function is obsolete.  Use @code{isequaln} instead.
@xseealso{isequaln}
@end deftypefn
isstr
@c isstr scripts/legacy/isstr.m
@deftypefn {} {} isstr (@var{x})
This function is obsolete.  Use @code{ischar} instead.
@xseealso{ischar}
@end deftypefn
setstr
@c setstr scripts/legacy/setstr.m
@deftypefn {} {@var{s} =} setstr (@var{x})
This function is obsolete.  Use @code{char} instead.
@xseealso{char}
@end deftypefn
strmatch
@c strmatch scripts/legacy/strmatch.m
@deftypefn  {} {} strmatch (@var{s}, @var{A})
@deftypefnx {} {} strmatch (@var{s}, @var{A}, "exact")

This function is obsolete.  Use an alternative such as @code{strncmp}
or @code{strcmp} instead.

Return indices of entries of @var{A} which begin with the string @var{s}.

The second argument @var{A} must be a string, character matrix, or a cell
array of strings.

If the third argument @qcode{"exact"} is not given, then @var{s} only
needs to match @var{A} up to the length of @var{s}.  Trailing spaces and
nulls in @var{s} and @var{A} are ignored when matching.

For example:

@example
@group
strmatch ("apple", "apple juice")
     @result{} 1

strmatch ("apple", ["apple  "; "apple juice"; "an apple"])
     @result{} [1; 2]

strmatch ("apple", ["apple  "; "apple juice"; "an apple"], "exact")
     @result{} [1]
@end group
@end example

@strong{Caution:} @code{strmatch} is obsolete.  Use @code{strncmp} (normal
case) or @code{strcmp} (@qcode{"exact"} case) in all new code.  Other
replacement possibilities, depending on application, include @code{regexp}
or @code{validatestring}.
@xseealso{strncmp, strcmp, regexp, strfind, validatestring}
@end deftypefn
strread
@c strread scripts/legacy/strread.m
@deftypefn  {} {[@var{a}, @dots{}] =} strread (@var{str})
@deftypefnx {} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format})
@deftypefnx {} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{format_repeat})
@deftypefnx {} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{prop1}, @var{value1}, @dots{})
@deftypefnx {} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{format_repeat}, @var{prop1}, @var{value1}, @dots{})

This function is obsolete.  Use @code{textscan} instead.

Read data from a string.

The string @var{str} is split into words that are repeatedly matched to the
specifiers in @var{format}.  The first word is matched to the first
specifier, the second to the second specifier and so forth.  If there are
more words than specifiers, the process is repeated until all words have
been processed.

The string @var{format} describes how the words in @var{str} should be
parsed.  It may contain any combination of the following specifiers:

@table @code
@item %s
The word is parsed as a string.

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

@item  %d
@itemx %u
The word is parsed as a number and converted to int32.

@item  %*
@itemx %*f
@itemx %*s
The word is skipped.

For %s and %d, %f, %n, %u and the associated %*s @dots{} specifiers an
optional width can be specified as %Ns, etc.@: where N is an integer > 1.
For %f, format specifiers like %N.Mf are allowed.

@item literals
In addition the format may contain literal character strings; these will be
skipped during reading.
@end table

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

By default, @var{format} is @t{"%f"}, meaning that numbers are read from
@var{str}.  This will do if @var{str} contains only numeric fields.

For example, the string

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

@noindent
can be read using

@example
[@var{a}, @var{b}, @var{c}] = strread (@var{str}, "%s %s %f");
@end example

Optional numeric argument @var{format_repeat} can be used for limiting the
number of items read:

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

@item N
Read N times @var{nargout} items.  0 (zero) is an acceptable value for
@var{format_repeat}.
@end table

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

@table @asis
@item @qcode{"commentstyle"}
Parts of @var{str} are considered comments and will be skipped.
@var{value} is the comment style and can be any of the following.

@itemize
@item @qcode{"shell"}
Everything from @code{#} characters to the nearest end-of-line is skipped.

@item @qcode{"c"}
Everything between @code{/*} and @code{*/} is skipped.

@item @qcode{"c++"}
Everything from @code{//} characters to the nearest end-of-line is skipped.

@item @qcode{"matlab"}
Everything from @code{%} characters to the nearest end-of-line is skipped.

@item user-supplied.  Two options:
(1) One string, or 1x1 cell string: Skip everything to the right of it;
(2) 2x1 cell string array: Everything between the left and right strings
is skipped.
@end itemize

@item @qcode{"delimiter"}
Any character in @var{value} will be used to split @var{str} into words
(default value = any whitespace).  Note that whitespace is implicitly added
to the set of delimiter characters unless a @qcode{"%s"} format conversion
specifier is supplied; see @qcode{"whitespace"} parameter below.  The set
of delimiter characters cannot be empty; if needed Octave substitutes a
space as delimiter.

@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 default is zero.

@item @qcode{"multipledelimsasone"}
Treat a series of consecutive delimiters, without whitespace in between,
as a single delimiter.  Consecutive delimiter series need not be vertically
@qcode{"aligned"}.

@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 @var{value} true (1, default), ignore read errors and return normally.
If false (0), return an error.

@item @qcode{"whitespace"}
Any character in @var{value} will be interpreted as whitespace and trimmed;
the string defining whitespace must be enclosed in double quotes for proper
processing of special characters like @qcode{"@xbackslashchar{}t"}.  In
each data field, multiple consecutive whitespace characters are collapsed
into one space and leading and trailing whitespace is removed.  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).  Whitespace is always added to the set of delimiter
characters unless at least one @qcode{"%s"} format conversion specifier is
supplied; in that case only whitespace explicitly specified in
@qcode{"delimiter"} is retained as delimiter and removed from the set of
whitespace characters.  If whitespace characters are to be kept as-is (in
e.g., strings), specify an empty value (i.e., @qcode{""}) for
@qcode{"whitespace"}; obviously, whitespace cannot be a delimiter then.

@end table

When the number of words in @var{str} doesn't match an exact multiple of
the number of format conversion specifiers, strread's behavior depends on
the last character of @var{str}:

@table @asis
@item last character = @qcode{"@xbackslashchar{}n"}
Data columns are padded with empty fields or NaN so that all columns have
equal length

@item last character is not @qcode{"@xbackslashchar{}n"}
Data columns are not padded; strread returns columns of unequal length

@end table

@xseealso{textscan, sscanf}
@end deftypefn
textread
@c textread scripts/legacy/textread.m
@deftypefn  {} {[@var{a}, @dots{}] =} textread (@var{filename})
@deftypefnx {} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format})
@deftypefnx {} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format}, @var{n})
@deftypefnx {} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format}, @var{prop1}, @var{value1}, @dots{})
@deftypefnx {} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format}, @var{n}, @var{prop1}, @var{value1}, @dots{})

This function is obsolete.  Use @code{textscan} instead.

Read data from a text file.

The file @var{filename} is read and parsed according to @var{format}.  The
function behaves like @code{strread} except it works by parsing a file
instead of a string.  See the documentation of @code{strread} for details.

In addition to the options supported by @code{strread}, this function
supports two more:

@itemize
@item @qcode{"headerlines"}:
The first @var{value} number of lines of @var{filename} are skipped.

@item @qcode{"endofline"}:
Specify a single character or
@qcode{"@xbackslashchar{}r@xbackslashchar{}n"}.  If no value is given, it
will be inferred from the file.  If set to @qcode{""} (empty string) EOLs
are ignored as delimiters.
@end itemize

The optional input @var{n} (format repeat count) specifies the number of
times the format string is to be used or the number of lines to be read,
whichever happens first while reading.  The former is equivalent to
requesting that the data output vectors should be of length @var{N}.
Note that when reading files with format strings referring to multiple
lines, @var{n} should rather be the number of lines to be read than the
number of format string uses.

If the format string is empty (not just omitted) and the file contains only
numeric data (excluding headerlines), textread will return a rectangular
matrix with the number of columns matching the number of numeric fields on
the first data line of the file.  Empty fields are returned as zero values.

Examples:

@example
@group
  Assume a data file like:
  1 a 2 b
  3 c 4 d
  5 e
@end group
@end example

@example
@group
  [a, b] = textread (f, "%f %s")
  returns two columns of data, one with doubles, the other a
  cellstr array:
  a = [1; 2; 3; 4; 5]
  b = @{"a"; "b"; "c"; "d"; "e"@}
@end group
@end example

@example
@group
  [a, b] = textread (f, "%f %s", 3)
  (read data into two culumns, try to use the format string
  three times)
  returns
  a = [1; 2; 3]
  b = @{"a"; "b"; "c"@}

@end group
@end example

@example
@group
  With a data file like:
  1
  a
  2
  b

  [a, b] = textread (f, "%f %s", 2)
  returns a = 1 and b = @{"a"@}; i.e., the format string is used
  only once because the format string refers to 2 lines of the
  data file.  To obtain 2x1 data output columns, specify N = 4
  (number of data lines containing all requested data) rather
  than 2.
@end group
@end example

@xseealso{textscan, load, dlmread, fscanf, strread}
@end deftypefn
bandwidth
@c bandwidth scripts/linear-algebra/bandwidth.m
@deftypefn  {} {@var{bw} =} bandwidth (@var{A}, @var{type})
@deftypefnx {} {[@var{lower}, @var{upper}] =} bandwidth (@var{A})
Compute the bandwidth of @var{A}.

The @var{type} argument is the string @qcode{"lower"} for the lower
bandwidth and @qcode{"upper"} for the upper bandwidth.  If no @var{type} is
specified return both the lower and upper bandwidth of @var{A}.

The lower/upper bandwidth of a matrix is the number of
subdiagonals/superdiagonals with nonzero entries.

@xseealso{isbanded, isdiag, istril, istriu}
@end deftypefn
commutation_matrix
@c commutation_matrix scripts/linear-algebra/commutation_matrix.m
@deftypefn {} {} commutation_matrix (@var{m}, @var{n})
Return the commutation matrix
@tex
 $K_{m,n}$
@end tex
@ifnottex
K(m,n)
@end ifnottex
which is the unique
@tex
 $m n \times m n$
@end tex
@ifnottex
@var{m}*@var{n} by @var{m}*@var{n}
@end ifnottex
matrix such that
@tex
 $K_{m,n} \cdot {\rm vec} (A) = {\rm vec} (A^T)$
@end tex
@ifnottex
@math{K(m,n) * vec(A) = vec(A')}
@end ifnottex
for all
@tex
 $m\times n$
@end tex
@ifnottex
@math{m} by @math{n}
@end ifnottex
matrices
@tex
 $A$.
@end tex
@ifnottex
@math{A}.
@end ifnottex

If only one argument @var{m} is given,
@tex
 $K_{m,m}$
@end tex
@ifnottex
@math{K(m,m)}
@end ifnottex
is returned.

See @nospell{Magnus and Neudecker} (1988), @cite{Matrix Differential
Calculus with Applications in Statistics and Econometrics.}
@end deftypefn
cond
@c cond scripts/linear-algebra/cond.m
@deftypefn  {} {} cond (@var{A})
@deftypefnx {} {} cond (@var{A}, @var{p})
Compute the @var{p}-norm condition number of a matrix with respect to
inversion.

@code{cond (@var{A})} is defined as
@tex
$ {\parallel A \parallel_p * \parallel A^{-1} \parallel_p .} $
@end tex
@ifnottex
@code{norm (@var{A}, @var{p}) * norm (inv (@var{A}), @var{p})}.
@end ifnottex

By default, @code{@var{p} = 2} is used which implies a (relatively slow)
singular value decomposition.  Other possible selections are
@code{@var{p} = 1, Inf, "fro"} which are generally faster.  See @code{norm}
for a full discussion of possible @var{p} values.

The condition number of a matrix quantifies the sensitivity of the matrix
inversion operation when small changes are made to matrix elements.  Ideally
the condition number will be close to 1.  When the number is large this
indicates small changes (such as underflow or round-off error) will produce
large changes in the resulting output.  In such cases the solution results
from numerical computing are not likely to be accurate.
@xseealso{condest, rcond, condeig, norm, svd}
@end deftypefn
condeig
@c condeig scripts/linear-algebra/condeig.m
@deftypefn  {} {@var{c} =} condeig (@var{a})
@deftypefnx {} {[@var{v}, @var{lambda}, @var{c}] =} condeig (@var{a})
Compute condition numbers of a matrix with respect to eigenvalues.

The condition numbers are the reciprocals of the cosines of the angles
between the left and right eigenvectors; Large values indicate that the
matrix has multiple distinct eigenvalues.

The input @var{a} must be a square numeric matrix.

The outputs are:

@itemize @bullet
@item
@var{c} is a vector of condition numbers for the eigenvalues of
@var{a}.

@item
@var{v} is the matrix of right eigenvectors of @var{a}.  The result is
equivalent to calling @code{[@var{v}, @var{lambda}] = eig (@var{a})}.

@item
@var{lambda} is the diagonal matrix of eigenvalues of @var{a}.  The
result is equivalent to calling
@code{[@var{v}, @var{lambda}] = eig (@var{a})}.
@end itemize

Example

@example
@group
a = [1, 2; 3, 4];
c = condeig (a)
  @result{} c =
       1.0150
       1.0150
@end group
@end example
@xseealso{eig, cond, balance}
@end deftypefn
condest
@c condest scripts/linear-algebra/condest.m
@deftypefn  {} {@var{cest} =} condest (@var{A})
@deftypefnx {} {@var{cest} =} condest (@var{A}, @var{t})
@deftypefnx {} {@var{cest} =} condest (@var{A}, @var{solvefun}, @var{t}, @var{p1}, @var{p2}, @dots{})
@deftypefnx {} {@var{cest} =} condest (@var{Afcn}, @var{solvefun}, @var{t}, @var{p1}, @var{p2}, @dots{})
@deftypefnx {} {[@var{cest}, @var{v}] =} condest (@dots{})

Estimate the 1-norm condition number of a square matrix @var{A} using
@var{t} test vectors and a randomized 1-norm estimator.

The optional input @var{t} specifies the number of test vectors (default 5).

If the matrix is not explicit, e.g., when estimating the condition number of
@var{A} given an LU@tie{}factorization, @code{condest} uses the following
functions:

@itemize @minus
@item @var{Afcn} which must return

@itemize @bullet
@item
the dimension @var{n} of @var{a}, if @var{flag} is @qcode{"dim"}

@item
true if @var{a} is a real operator, if @var{flag} is @qcode{"real"}

@item
the result @code{@var{a} * @var{x}}, if @var{flag} is "notransp"

@item
the result @code{@var{a}' * @var{x}}, if @var{flag} is "transp"
@end itemize

@item @var{solvefun} which must return

@itemize @bullet
@item
the dimension @var{n} of @var{a}, if @var{flag} is @qcode{"dim"}

@item
true if @var{a} is a real operator, if @var{flag} is @qcode{"real"}

@item
the result @code{@var{a} \ @var{x}}, if @var{flag} is "notransp"

@item
the result @code{@var{a}' \ @var{x}}, if @var{flag} is "transp"
@end itemize
@end itemize

The parameters @var{p1}, @var{p2}, @dots{} are arguments of
@code{@var{Afcn} (@var{flag}, @var{x}, @var{p1}, @var{p2}, @dots{})}
and @code{@var{solvefcn} (@var{flag}, @var{x}, @var{p1}, @var{p2},
@dots{})}.

The principal output is the 1-norm condition number estimate @var{cest}.

The optional second output is an approximate null vector when @var{cest} is
large; it satisfies the equation
@code{norm (A*v, 1) == norm (A, 1) * norm (@var{v}, 1) / @var{est}}.

Algorithm Note: @code{condest} uses a randomized algorithm to approximate
the 1-norms.  Therefore, if consistent results are required, the
@qcode{"state"} of the random generator should be fixed before invoking
@code{condest}.

References:

@itemize
@item
@nospell{N.J. Higham and F. Tisseur}, @cite{A Block Algorithm
for Matrix 1-Norm Estimation, with an Application to 1-Norm
Pseudospectra}. SIMAX vol 21, no 4, pp 1185--1201.
@url{https://dx.doi.org/10.1137/S0895479899356080}

@item
@nospell{N.J. Higham and F. Tisseur}, @cite{A Block Algorithm
for Matrix 1-Norm Estimation, with an Application to 1-Norm
Pseudospectra}. @url{https://citeseer.ist.psu.edu/223007.html}
@end itemize

@xseealso{cond, norm, normest1, normest}
@end deftypefn
cross
@c cross scripts/linear-algebra/cross.m
@deftypefn  {} {} cross (@var{x}, @var{y})
@deftypefnx {} {} cross (@var{x}, @var{y}, @var{dim})
Compute the vector cross product of two 3-dimensional vectors @var{x} and
@var{y}.

If @var{x} and @var{y} are matrices, the cross product is applied along the
first dimension with three elements.

The optional argument  @var{dim} forces the cross product to be calculated
along the specified dimension.

Example Code:

@example
@group
cross ([1, 1, 0], [0, 1, 1])
  @result{}
       1   -1   1
@end group
@end example

@xseealso{dot, curl, divergence}
@end deftypefn
duplication_matrix
@c duplication_matrix scripts/linear-algebra/duplication_matrix.m
@deftypefn {} {} duplication_matrix (@var{n})
Return the duplication matrix
@tex
 $D_n$
@end tex
@ifnottex
@nospell{@math{Dn}}
@end ifnottex
which is the unique
@tex
 $n^2 \times n(n+1)/2$
@end tex
@ifnottex
@math{n^2} by @math{n*(n+1)/2}
@end ifnottex
matrix such that
@tex
 $D_n * {\rm vech} (A) = {\rm vec} (A)$
@end tex
@ifnottex
@nospell{@math{Dn vech (A) = vec (A)}}
@end ifnottex
for all symmetric
@tex
 $n \times n$
@end tex
@ifnottex
@math{n} by @math{n}
@end ifnottex
matrices
@tex
 $A$.
@end tex
@ifnottex
@math{A}.
@end ifnottex

See @nospell{Magnus and Neudecker} (1988), @cite{Matrix Differential
Calculus with Applications in Statistics and Econometrics.}
@end deftypefn
expm
@c expm scripts/linear-algebra/expm.m
@deftypefn {} {} expm (@var{A})
Return the exponential of a matrix.

The matrix exponential is defined as the infinite Taylor series
@tex
$$
 \exp (A) = I + A + {A^2 \over 2!} + {A^3 \over 3!} + \cdots
$$
@end tex
@ifnottex

@example
expm (A) = I + A + A^2/2! + A^3/3! + @dots{}
@end example

@end ifnottex
However, the Taylor series is @emph{not} the way to compute the matrix
exponential; see @nospell{Moler and Van Loan}, @cite{Nineteen Dubious Ways
to Compute the Exponential of a Matrix}, SIAM Review, 1978.  This routine
uses Ward's diagonal Pad@'e approximation method with three step
preconditioning (SIAM Journal on Numerical Analysis, 1977).  Diagonal
Pad@'e approximations are rational polynomials of matrices
@tex
$D_q(A)^{-1}N_q(A)$
@end tex
@ifnottex

@example
@group
     -1
D (A)   N (A)
@end group
@end example

@end ifnottex
whose Taylor series matches the first
@tex
$2 q + 1 $
@end tex
@ifnottex
@code{2q+1}
@end ifnottex
terms of the Taylor series above; direct evaluation of the Taylor series
(with the same preconditioning steps) may be desirable in lieu of the
Pad@'e approximation when
@tex
$D_q(A)$
@end tex
@ifnottex
@code{Dq(A)}
@end ifnottex
is ill-conditioned.
@xseealso{logm, sqrtm}
@end deftypefn
gls
@c gls scripts/linear-algebra/gls.m
@deftypefn {} {[@var{beta}, @var{v}, @var{r}] =} gls (@var{y}, @var{x}, @var{o})
Generalized least squares (GLS) model.

Perform a generalized least squares estimation for the multivariate model
@tex
$@var{y} = @var{x}\,@var{b} + @var{e}$
@end tex
@ifnottex
@w{@math{@var{y} = @var{x}*@var{B} + @var{E}}}
@end ifnottex
where
@tex
$@var{y}$ is a $t \times p$ matrix, $@var{x}$ is a $t \times k$ matrix,
$@var{b}$ is a $k \times p$ matrix and $@var{e}$ is a $t \times p$ matrix.
@end tex
@ifnottex
@var{y} is a @math{t}-by-@math{p} matrix, @var{x} is a
@math{t}-by-@math{k} matrix, @var{b} is a @math{k}-by-@math{p} matrix
and @var{e} is a @math{t}-by-@math{p} matrix.
@end ifnottex

@noindent
Each row of @var{y} is a @math{p}-variate observation in which each column
represents a variable.  Likewise, the rows of @var{x} represent
@math{k}-variate observations or possibly designed values.  Furthermore,
the collection of observations @var{x} must be of adequate rank, @math{k},
otherwise @var{b} cannot be uniquely estimated.

The observation errors, @var{e}, are assumed to originate from an
underlying @math{p}-variate distribution with zero mean but possibly
heteroscedastic observations.  That is, in general,
@tex
$\bar{@var{e}} = 0$ and cov(vec(@var{e})) = $s^2@var{o}$
@end tex
@ifnottex
@code{@math{mean (@var{e}) = 0}} and
@code{@math{cov (vec (@var{e})) = (@math{s}^2)*@var{o}}}
@end ifnottex
in which @math{s} is a scalar and @var{o} is a
@tex
@math{t \, p \times t \, p}
@end tex
@ifnottex
@math{t*p}-by-@math{t*p}
@end ifnottex
matrix.

The return values @var{beta}, @var{v}, and @var{r} are
defined as follows.

@table @var
@item beta
The GLS estimator for matrix @var{b}.

@item v
The GLS estimator for scalar @math{s^2}.

@item r
The matrix of GLS residuals, @math{@var{r} = @var{y} - @var{x}*@var{beta}}.
@end table
@xseealso{ols}
@end deftypefn
housh
@c housh scripts/linear-algebra/housh.m
@deftypefn {} {[@var{housv}, @var{beta}, @var{zer}] =} housh (@var{x}, @var{j}, @var{z})
Compute Householder reflection vector @var{housv} to reflect @var{x} to be
the j-th column of identity, i.e.,

@example
@group
(I - beta*housv*housv')x =  norm (x)*e(j) if x(j) < 0,
(I - beta*housv*housv')x = -norm (x)*e(j) if x(j) >= 0
@end group
@end example

@noindent
Inputs

@table @var
@item x
vector

@item j
index into vector

@item z
threshold for zero  (usually should be the number 0)
@end table

@noindent
Outputs (see @nospell{Golub and Van Loan}):

@table @var
@item beta
If beta = 0, then no reflection need be applied (@nospell{zer} set to 0)

@item housv
householder vector
@end table
@end deftypefn
isbanded
@c isbanded scripts/linear-algebra/isbanded.m
@deftypefn {} {} isbanded (@var{A}, @var{lower}, @var{upper})
Return true if @var{A} is a matrix with entries confined between
@var{lower} diagonals below the main diagonal and @var{upper} diagonals
above the main diagonal.

@var{lower} and @var{upper} must be non-negative integers.
@xseealso{isdiag, istril, istriu, bandwidth}
@end deftypefn
isdefinite
@c isdefinite scripts/linear-algebra/isdefinite.m
@deftypefn  {} {} isdefinite (@var{A})
@deftypefnx {} {} isdefinite (@var{A}, @var{tol})
Return true if @var{A} is symmetric positive definite matrix within the
tolerance specified by @var{tol}.

If @var{tol} is omitted, use a tolerance of
@code{100 * eps * norm (@var{A}, "fro")}.

Background: A positive definite matrix has eigenvalues which are all
greater than zero.  A positive semi-definite matrix has eigenvalues which
are all greater than or equal to zero.  The matrix @var{A} is very likely to
be positive semi-definite if the following two conditions hold for a
suitably small tolerance @var{tol}.

@example
@group
isdefinite (@var{A}) @result{} 0
isdefinite (@var{A} + 5*@var{tol}, @var{tol}) @result{} 1
@end group
@end example
@xseealso{issymmetric, ishermitian}
@end deftypefn
isdiag
@c isdiag scripts/linear-algebra/isdiag.m
@deftypefn {} {} isdiag (@var{A})
Return true if @var{A} is a diagonal matrix.
@xseealso{isbanded, istril, istriu, diag, bandwidth}
@end deftypefn
ishermitian
@c ishermitian scripts/linear-algebra/ishermitian.m
@deftypefn  {} {} ishermitian (@var{A})
@deftypefnx {} {} ishermitian (@var{A}, @var{tol})
@deftypefnx {} {} ishermitian (@var{A}, @qcode{"skew"})
@deftypefnx {} {} ishermitian (@var{A}, @qcode{"skew"}, @var{tol})
Return true if @var{A} is a Hermitian or skew-Hermitian matrix within the
tolerance specified by @var{tol}.

The default tolerance is zero (uses faster code).

The type of symmetry to check may be specified with the additional input
@qcode{"nonskew"} (default) for regular Hermitian or @qcode{"skew"} for
skew-Hermitian.

Background: A matrix is Hermitian if the complex conjugate transpose of the
matrix is equal to the original matrix: @w{@tcode{@var{A} == @var{A}'}}.  If
a tolerance is given then the calculation is
@code{norm (@var{A} - @var{A}', Inf) / norm (@var{A}, Inf) < @var{tol}}.

A matrix is skew-Hermitian if the complex conjugate transpose of the matrix
is equal to the negative of the original matrix:
@w{@tcode{@var{A} == -@var{A}'}}.  If a
tolerance is given then the calculation is
@code{norm (@var{A} + @var{A}', Inf) / norm (@var{A}, Inf) < @var{tol}}.
@xseealso{issymmetric, isdefinite}
@end deftypefn
issymmetric
@c issymmetric scripts/linear-algebra/issymmetric.m
@deftypefn  {} {} issymmetric (@var{A})
@deftypefnx {} {} issymmetric (@var{A}, @var{tol})
@deftypefnx {} {} issymmetric (@var{A}, @qcode{"skew"})
@deftypefnx {} {} issymmetric (@var{A}, @qcode{"skew"}, @var{tol})
Return true if @var{A} is a symmetric or skew-symmetric matrix within the
tolerance specified by @var{tol}.

The default tolerance is zero (uses faster code).

The type of symmetry to check may be specified with the additional input
@qcode{"nonskew"} (default) for regular symmetry or @qcode{"skew"} for
skew-symmetry.

Background: A matrix is symmetric if the transpose of the matrix is equal
to the original matrix: @w{@tcode{@var{A} == @var{A}.'}}.  If a tolerance
is given then symmetry is determined by
@code{norm (@var{A} - @var{A}.', Inf) / norm (@var{A}, Inf) < @var{tol}}.

A matrix is skew-symmetric if the transpose of the matrix is equal to the
negative of the original matrix: @w{@tcode{@var{A} == -@var{A}.'}}.  If a
tolerance is given then skew-symmetry is determined by
@code{norm (@var{A} + @var{A}.', Inf) / norm (@var{A}, Inf) < @var{tol}}.
@xseealso{ishermitian, isdefinite}
@end deftypefn
istril
@c istril scripts/linear-algebra/istril.m
@deftypefn {} {} istril (@var{A})
Return true if @var{A} is a lower triangular matrix.

A lower triangular matrix has nonzero entries only on the main diagonal and
below.
@xseealso{istriu, isbanded, isdiag, tril, bandwidth}
@end deftypefn
istriu
@c istriu scripts/linear-algebra/istriu.m
@deftypefn {} {} istriu (@var{A})
Return true if @var{A} is an upper triangular matrix.

An upper triangular matrix has nonzero entries only on the main diagonal and
above.
@xseealso{isdiag, isbanded, istril, triu, bandwidth}
@end deftypefn
krylov
@c krylov scripts/linear-algebra/krylov.m
@deftypefn {} {[@var{u}, @var{h}, @var{nu}] =} krylov (@var{A}, @var{V}, @var{k}, @var{eps1}, @var{pflg})
Construct an orthogonal basis @var{u} of a block Krylov subspace.

The block Krylov subspace has the following form:

@example
[v a*v a^2*v @dots{} a^(k+1)*v]
@end example

@noindent
The construction is made with Householder reflections to guard against loss
of orthogonality.

If @var{V} is a vector, then @var{h} contains the Hessenberg matrix
such that @nospell{@tcode{a*u == u*h+rk*ek'}}, in which
@code{rk = a*u(:,k)-u*h(:,k)}, and @nospell{@tcode{ek'}} is the vector
@code{[0, 0, @dots{}, 1]} of length @var{k}.  Otherwise, @var{h} is
meaningless.

If @var{V} is a vector and @var{k} is greater than @code{length (A) - 1},
then @var{h} contains the Hessenberg matrix such that @code{a*u == u*h}.

The value of @var{nu} is the dimension of the span of the Krylov subspace
(based on @var{eps1}).

If @var{b} is a vector and @var{k} is greater than @var{m-1}, then @var{h}
contains the Hessenberg decomposition of @var{A}.

The optional parameter @var{eps1} is the threshold for zero.  The default
value is 1e-12.

If the optional parameter @var{pflg} is nonzero, row pivoting is used to
improve numerical behavior.  The default value is 0.

Reference: @nospell{A. Hodel, P. Misra}, @cite{Partial Pivoting in the
Computation of Krylov Subspaces of Large Sparse Systems}, Proceedings of
the 42nd IEEE Conference on Decision and Control, December 2003.
@end deftypefn
linsolve
@c linsolve scripts/linear-algebra/linsolve.m
@deftypefn  {} {@var{x} =} linsolve (@var{A}, @var{b})
@deftypefnx {} {@var{x} =} linsolve (@var{A}, @var{b}, @var{opts})
@deftypefnx {} {[@var{x}, @var{R}] =} linsolve (@dots{})
Solve the linear system @code{A*x = b}.

With no options, this function is equivalent to the left division operator
@w{(@code{x = A \ b})} or the matrix-left-divide function
@w{(@code{x = mldivide (A, b)})}.

Octave ordinarily examines the properties of the matrix @var{A} and chooses
a solver that best matches the matrix.  By passing a structure @var{opts}
to @code{linsolve} you can inform Octave directly about the matrix @var{A}.
In this case Octave will skip the matrix examination and proceed directly
to solving the linear system.

@strong{Warning:} If the matrix @var{A} does not have the properties listed
in the @var{opts} structure then the result will not be accurate AND no
warning will be given.  When in doubt, let Octave examine the matrix and
choose the appropriate solver as this step takes little time and the result
is cached so that it is only done once per linear system.

Possible @var{opts} fields (set value to true/false):

@table @asis
@item LT
@var{A} is lower triangular

@item UT
@var{A} is upper triangular

@item UHESS
@var{A} is upper Hessenberg (currently makes no difference)

@item SYM
@var{A} is symmetric or complex Hermitian (currently makes no difference)

@item POSDEF
@var{A} is positive definite

@item RECT
@var{A} is general rectangular (currently makes no difference)

@item TRANSA
  Solve @code{A'*x = b} if true rather than @code{A*x = b}
@end table

The optional second output @var{R} is the inverse condition number of
@var{A} (zero if matrix is singular).
@xseealso{mldivide, matrix_type, rcond}
@end deftypefn
logm
@c logm scripts/linear-algebra/logm.m
@deftypefn  {} {@var{s} =} logm (@var{A})
@deftypefnx {} {@var{s} =} logm (@var{A}, @var{opt_iters})
@deftypefnx {} {[@var{s}, @var{iters}] =} logm (@dots{})
Compute the matrix logarithm of the square matrix @var{A}.

The implementation utilizes a Pad@'e approximant and the identity

@example
logm (@var{A}) = 2^k * logm (@var{A}^(1 / 2^k))
@end example

The optional input @var{opt_iters} is the maximum number of square roots
to compute and defaults to 100.

The optional output @var{iters} is the number of square roots actually
computed.
@xseealso{expm, sqrtm}
@end deftypefn
lscov
@c lscov scripts/linear-algebra/lscov.m
@deftypefn  {} {@var{x} =} lscov (@var{A}, @var{b})
@deftypefnx {} {@var{x} =} lscov (@var{A}, @var{b}, @var{V})
@deftypefnx {} {@var{x} =} lscov (@var{A}, @var{b}, @var{V}, @var{alg})
@deftypefnx {} {[@var{x}, @var{stdx}, @var{mse}, @var{S}] =} lscov (@dots{})

Compute a generalized linear least squares fit.

Estimate @var{x} under the model @var{b} = @var{A}@var{x} + @var{w}, where
the noise @var{w} is assumed to follow a normal distribution with covariance
matrix @math{{\sigma^2} V}.

If the size of the coefficient matrix @var{A} is n-by-p, the size of the
vector/array of constant terms @var{b} must be n-by-k.

The optional input argument @var{V} may be an n-element vector of positive
weights (inverse variances), or an n-by-n symmetric positive semi-definite
matrix representing the covariance of @var{b}.  If @var{V} is not supplied,
the ordinary least squares solution is returned.

The @var{alg} input argument, a guidance on solution method to use, is
currently ignored.

Besides the least-squares estimate matrix @var{x} (p-by-k), the function
also returns @var{stdx} (p-by-k), the error standard deviation of estimated
@var{x}; @var{mse} (k-by-1), the estimated data error covariance scale
factors (@math{\sigma^2}); and @var{S} (p-by-p, or p-by-p-by-k if k > 1),
the error covariance of @var{x}.

Reference: @nospell{Golub and Van Loan} (1996),
@cite{Matrix Computations (3rd Ed.)}, Johns Hopkins, Section 5.6.3

@xseealso{ols, gls, lsqnonneg}
@end deftypefn
normest
@c normest scripts/linear-algebra/normest.m
@deftypefn  {} {@var{nest} =} normest (@var{A})
@deftypefnx {} {@var{nest} =} normest (@var{A}, @var{tol})
@deftypefnx {} {[@var{nest}, @var{iter}] =} normest (@dots{})
Estimate the 2-norm of the matrix @var{A} using a power series analysis.

This is typically used for large matrices, where the cost of calculating
@code{norm (@var{A})} is prohibitive and an approximation to the 2-norm is
acceptable.

@var{tol} is the tolerance to which the 2-norm is calculated.  By default
@var{tol} is 1e-6.

The optional output @var{iter} returns the number of iterations that were
required for @code{normest} to converge.
@xseealso{normest1, norm, cond, condest}
@end deftypefn
normest1
@c normest1 scripts/linear-algebra/normest1.m
@deftypefn  {} {@var{nest} =} normest1 (@var{A})
@deftypefnx {} {@var{nest} =} normest1 (@var{A}, @var{t})
@deftypefnx {} {@var{nest} =} normest1 (@var{A}, @var{t}, @var{x0})
@deftypefnx {} {@var{nest} =} normest1 (@var{Afun}, @var{t}, @var{x0}, @var{p1}, @var{p2}, @dots{})
@deftypefnx {} {[@var{nest}, @var{v}] =} normest1 (@var{A}, @dots{})
@deftypefnx {} {[@var{nest}, @var{v}, @var{w}] =} normest1 (@var{A}, @dots{})
@deftypefnx {} {[@var{nest}, @var{v}, @var{w}, @var{iter}] =} normest1 (@var{A}, @dots{})
Estimate the 1-norm of the matrix @var{A} using a block algorithm.

@code{normest1} is best for large sparse matrices where only an estimate of
the norm is required.  For small to medium sized matrices, consider using
@code{norm (@var{A}, 1)}.  In addition, @code{normest1} can be used for the
estimate of the 1-norm of a linear operator @var{A} when matrix-vector
products @code{@var{A} * @var{x}} and @code{@var{A}' * @var{x}} can be
cheaply computed.  In this case, instead of the matrix @var{A}, a function
@code{@var{Afun} (@var{flag}, @var{x})} is used; it must return:

@itemize @bullet
@item
the dimension @var{n} of @var{A}, if @var{flag} is @qcode{"dim"}

@item
true if @var{A} is a real operator, if @var{flag} is @qcode{"real"}

@item
the result @code{@var{A} * @var{x}}, if @var{flag} is @qcode{"notransp"}

@item
the result @code{@var{A}' * @var{x}}, if @var{flag} is @qcode{"transp"}
@end itemize

A typical case is @var{A} defined by @code{@var{b} ^ @var{m}}, in which the
result @code{@var{A} * @var{x}} can be computed without even forming
explicitly @code{@var{b} ^ @var{m}} by:

@example
@group
@var{y} = @var{x};
for @var{i} = 1:@var{m}
  @var{y} = @var{b} * @var{y};
endfor
@end group
@end example

The parameters @var{p1}, @var{p2}, @dots{} are arguments of
@code{@var{Afun} (@var{flag}, @var{x}, @var{p1}, @var{p2}, @dots{})}.

The default value for @var{t} is 2.  The algorithm requires matrix-matrix
products with sizes @var{n} x @var{n} and @var{n} x @var{t}.

The initial matrix @var{x0} should have columns of unit 1-norm.  The default
initial matrix @var{x0} has the first column
@code{ones (@var{n}, 1) / @var{n}} and, if @var{t} > 1, the remaining
columns with random elements @code{-1 / @var{n}}, @code{1 / @var{n}},
divided by @var{n}.

On output, @var{nest} is the desired estimate, @var{v} and @var{w}
are vectors such that @code{@var{w} = @var{A} * @var{v}}, with
@code{norm (@var{w}, 1)} = @code{@var{c} * norm (@var{v}, 1)}.  @var{iter}
contains in @code{@var{iter}(1)} the number of iterations (the maximum is
hardcoded to 5) and in @code{@var{iter}(2)} the total number of products
@code{@var{A} * @var{x}} or @code{@var{A}' * @var{x}} performed by the
algorithm.

Algorithm Note: @code{normest1} uses random numbers during evaluation.
Therefore, if consistent results are required, the @qcode{"state"} of the
random generator should be fixed before invoking @code{normest1}.

Reference: @nospell{N. J. Higham and F. Tisseur},
@cite{A block algorithm for matrix 1-norm estimation, with and
application to 1-norm @nospell{pseudospectra}},
@nospell{SIAM J. Matrix Anal. Appl.},
pp. 1185--1201, Vol 21, No. 4, 2000.

@xseealso{normest, norm, cond, condest}
@end deftypefn
null
@c null scripts/linear-algebra/null.m
@deftypefn  {} {} null (@var{A})
@deftypefnx {} {} null (@var{A}, @var{tol})
Return an orthonormal basis of the null space of @var{A}.

The dimension of the null space is taken as the number of singular values of
@var{A} not greater than @var{tol}.  If the argument @var{tol} is missing,
it is computed as

@example
max (size (@var{A})) * max (svd (@var{A})) * eps
@end example
@xseealso{orth}
@end deftypefn
ols
@c ols scripts/linear-algebra/ols.m
@deftypefn {} {[@var{beta}, @var{sigma}, @var{r}] =} ols (@var{y}, @var{x})
Ordinary least squares (OLS) estimation.

OLS applies to the multivariate model
@tex
$@var{y} = @var{x}\,@var{b} + @var{e}$
@end tex
@ifnottex
@w{@math{@var{y} = @var{x}*@var{b} + @var{e}}}
@end ifnottex
where
@tex
$@var{y}$ is a $t \times p$ matrix, $@var{x}$ is a $t \times k$ matrix,
$@var{b}$ is a $k \times p$ matrix, and $@var{e}$ is a $t \times p$ matrix.
@end tex
@ifnottex
@math{@var{y}} is a @math{t}-by-@math{p} matrix, @math{@var{x}} is a
@math{t}-by-@math{k} matrix, @var{b} is a @math{k}-by-@math{p} matrix, and
@var{e} is a @math{t}-by-@math{p} matrix.
@end ifnottex

Each row of @var{y} is a @math{p}-variate observation in which each column
represents a variable.  Likewise, the rows of @var{x} represent
@math{k}-variate observations or possibly designed values.  Furthermore,
the collection of observations @var{x} must be of adequate rank, @math{k},
otherwise @var{b} cannot be uniquely estimated.

The observation errors, @var{e}, are assumed to originate from an
underlying @math{p}-variate distribution with zero mean and
@math{p}-by-@math{p} covariance matrix @var{S}, both constant conditioned
on @var{x}.  Furthermore, the matrix @var{S} is constant with respect to
each observation such that
@tex
$\bar{@var{e}} = 0$ and cov(vec(@var{e})) =  kron(@var{s},@var{I}).
@end tex
@ifnottex
@code{mean (@var{e}) = 0} and
@code{cov (vec (@var{e})) = kron (@var{s}, @var{I})}.
@end ifnottex
(For cases
that don't meet this criteria, such as autocorrelated errors, see
generalized least squares, gls, for more efficient estimations.)

The return values @var{beta}, @var{sigma}, and @var{r} are defined as
follows.

@table @var
@item beta
The OLS estimator for matrix @var{b}.
@tex
@var{beta} is calculated directly via $(@var{x}^T@var{x})^{-1} @var{x}^T
@var{y}$ if the matrix $@var{x}^T@var{x}$ is of full rank.
@end tex
@ifnottex
@var{beta} is calculated directly via
@code{inv (@var{x}'*@var{x}) * @var{x}' * @var{y}} if the matrix
@code{@var{x}'*@var{x}} is of full rank.
@end ifnottex
Otherwise, @code{@var{beta} = pinv (@var{x}) * @var{y}} where
@code{pinv (@var{x})} denotes the pseudoinverse of @var{x}.

@item sigma
The OLS estimator for the matrix @var{s},

@example
@group
@var{sigma} = (@var{y}-@var{x}*@var{beta})' * (@var{y}-@var{x}*@var{beta}) / (@math{t}-rank(@var{x}))
@end group
@end example

@item r
The matrix of OLS residuals, @code{@var{r} = @var{y} - @var{x}*@var{beta}}.
@end table
@xseealso{gls, pinv}
@end deftypefn
ordeig
@c ordeig scripts/linear-algebra/ordeig.m
@deftypefn  {} {@var{lambda} =} ordeig (@var{A})
@deftypefnx {} {@var{lambda} =} ordeig (@var{A}, @var{B})
Return the eigenvalues of quasi-triangular matrices in their order of
appearance in the matrix @var{A}.

The quasi-triangular matrix @var{A} is usually the result of a Schur
factorization.  If called with a second input @var{B} then the generalized
eigenvalues of the pair @var{A}, @var{B} are returned in the order of
appearance of the matrix @code{@var{A}-@var{lambda}*@var{B}}.  The pair
@var{A}, @var{B} is usually the result of a QZ decomposition.

@xseealso{ordschur, eig, schur, qz}
@end deftypefn
orth
@c orth scripts/linear-algebra/orth.m
@deftypefn  {} {} orth (@var{A})
@deftypefnx {} {} orth (@var{A}, @var{tol})
Return an orthonormal basis of the range space of @var{A}.

The dimension of the range space is taken as the number of singular values
of @var{A} greater than @var{tol}.  If the argument @var{tol} is missing, it
is computed as

@example
max (size (@var{A})) * max (svd (@var{A})) * eps
@end example
@xseealso{null}
@end deftypefn
planerot
@c planerot scripts/linear-algebra/planerot.m
@deftypefn {} {[@var{G}, @var{y}] =} planerot (@var{x})
Compute the Givens rotation matrix for the two-element column vector
@var{x}.

@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(1)\cr x(2)}\right] = \left[\matrix{\ast\cr 0}\right]
$$
@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{y} = @var{G} * [@var{x}(1); @var{x}(2)] @equiv{} [*; 0]
@end example

@end ifnottex

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.
@xseealso{givens, qr}
@end deftypefn
qzhess
@c qzhess scripts/linear-algebra/qzhess.m
@deftypefn {} {[@var{aa}, @var{bb}, @var{q}, @var{z}] =} qzhess (@var{A}, @var{B})
Compute the Hessenberg-triangular decomposition of the matrix pencil
@code{(@var{A}, @var{B})}, returning
@code{@var{aa} = @var{q} * @var{A} * @var{z}},
@code{@var{bb} = @var{q} * @var{B} * @var{z}}, with @var{q} and @var{z}
orthogonal.

For example:

@example
@group
[aa, bb, q, z] = qzhess ([1, 2; 3, 4], [5, 6; 7, 8])
  @result{} aa =
      -3.02244  -4.41741
       0.92998   0.69749
  @result{} bb =
      -8.60233  -9.99730
       0.00000  -0.23250
  @result{} q =
      -0.58124  -0.81373
      -0.81373   0.58124
  @result{} z =
     Diagonal Matrix
       1   0
       0   1
@end group
@end example

The Hessenberg-triangular decomposition is the first step in
@nospell{Moler and Stewart's} QZ@tie{}decomposition algorithm.

Algorithm taken from @nospell{Golub and Van Loan},
@cite{Matrix Computations, 2nd edition}.

@xseealso{lu, chol, hess, qr, qz, schur, svd}
@end deftypefn
rank
@c rank scripts/linear-algebra/rank.m
@deftypefn  {} {} rank (@var{A})
@deftypefnx {} {} rank (@var{A}, @var{tol})
Compute the rank of matrix @var{A}, using the singular value decomposition.

The rank is taken to be the number of singular values of @var{A} that are
greater than the specified tolerance @var{tol}.  If the second argument is
omitted, it is taken to be

@example
tol = max (size (@var{A})) * sigma(1) * eps;
@end example

@noindent
where @code{eps} is machine precision and @code{sigma(1)} is the largest
singular value of @var{A}.

The rank of a matrix is the number of linearly independent rows or columns
and equals the dimension of the row and column space.  The function
@code{orth} may be used to compute an orthonormal basis of the column space.

For testing if a system @code{@var{A}*@var{x} = @var{b}} of linear equations
is solvable, one can use

@example
rank (@var{A}) == rank ([@var{A} @var{b}])
@end example

In this case, @code{@var{x} = @var{A} \ @var{b}} finds a particular solution
@var{x}.  The general solution is @var{x} plus the null space of matrix
@var{A}.  The function @code{null} may be used to compute a basis of the
null space.

Example:

@example
@group
A = [1 2 3
     4 5 6
     7 8 9];
rank (A)
  @result{} 2
@end group
@end example

@noindent
In this example, the number of linearly independent rows is only 2 because
the final row is a linear combination of the first two rows:

@example
A(3,:) == -A(1,:) + 2 * A(2,:)
@end example

@xseealso{null, orth, sprank, svd, eps}
@end deftypefn
rref
@c rref scripts/linear-algebra/rref.m
@deftypefn  {} {} rref (@var{A})
@deftypefnx {} {} rref (@var{A}, @var{tol})
@deftypefnx {} {[@var{r}, @var{k}] =} rref (@dots{})
Return the reduced row echelon form of @var{A}.

@var{tol} defaults to
@code{eps * max (size (@var{A})) * norm (@var{A}, inf)}.

The optional return argument @var{k} contains the vector of
"bound variables", which are those columns on which elimination has been
performed.

@end deftypefn
subspace
@c subspace scripts/linear-algebra/subspace.m
@deftypefn {} {@var{angle} =} subspace (@var{A}, @var{B})
Determine the largest principal angle between two subspaces
spanned by the columns of matrices @var{A} and @var{B}.
@end deftypefn
trace
@c trace scripts/linear-algebra/trace.m
@deftypefn {} {} trace (@var{A})
Compute the trace of @var{A}, the sum of the elements along the main
diagonal.

The implementation is straightforward: @code{sum (diag (@var{A}))}.
@xseealso{eig}
@end deftypefn
vech
@c vech scripts/linear-algebra/vech.m
@deftypefn {} {} vech (@var{x})
Return the vector obtained by eliminating all superdiagonal elements of
the square matrix @var{x} and stacking the result one column above the
other.

This has uses in matrix calculus where the underlying matrix is symmetric
and it would be pointless to keep values above the main diagonal.
@xseealso{vec}
@end deftypefn
vecnorm
@c vecnorm scripts/linear-algebra/vecnorm.m
@deftypefn  {} {@var{n} =} vecnorm (@var{A})
@deftypefnx {} {@var{n} =} vecnorm (@var{A}, @var{p})
@deftypefnx {} {@var{n} =} vecnorm (@var{A}, @var{p}, @var{dim})
Return the p-norm of the elements of @var{A} along dimension @var{dim}.

The p-norm of a vector is defined as

@tex
$$ {\Vert A \Vert}_p  = \left[ \sum_{i=1}^N {| A_i |}^p \right] ^ {1/p} $$
@end tex
@ifnottex

@example
@var{p-norm} (@var{A}, @var{p}) = sum (abs (@var{A}) .^ @var{p})) ^ (1/@var{p})
@end example

@end ifnottex
If @var{p} is omitted it defaults to 2 (Euclidean norm).  @var{p} can be
@code{Inf} (absolute value of largest element).

If @var{dim} is omitted the first non-singleton dimension is used.

@xseealso{norm}
@end deftypefn
bug_report
@c bug_report scripts/miscellaneous/bug_report.m
@deftypefn {} {} bug_report ()
Display information about how to submit bug reports for Octave.
@end deftypefn
bunzip2
@c bunzip2 scripts/miscellaneous/bunzip2.m
@deftypefn  {} {} bunzip2 (@var{bzfile})
@deftypefnx {} {} bunzip2 (@var{bzfile}, @var{dir})
@deftypefnx {} {@var{filelist} =} bunzip2 (@dots{})
Unpack the bzip2 archive @var{bzfile}.

If @var{dir} is specified the files are unpacked in this directory rather
than the one where @var{bzfile} is located.

The optional output @var{filelist} is a list of the uncompressed files.
@xseealso{bzip2, unpack, gunzip, unzip, untar}
@end deftypefn
cast
@c cast scripts/miscellaneous/cast.m
@deftypefn {} {} cast (@var{val}, "@var{type}")
Convert @var{val} to data type @var{type}.

Both @var{val} and @var{type} are typically one of the following built-in
classes:

@example
@group
"double"
"single"
"logical"
"char"
"int8"
"int16"
"int32"
"int64"
"uint8"
"uint16"
"uint32"
"uint64"
@end group
@end example

The value @var{val} may be modified to fit within the range of the new type.

Examples:

@example
@group
cast (-5, "uint8")
   @result{} 0
cast (300, "int8")
   @result{} 127
@end group
@end example

Programming Note: This function relies on the object @var{val} having a
conversion method named @var{type}.  User-defined classes may implement only
a subset of the full list of types shown above.  In that case, it may be
necessary to call cast twice in order to reach the desired type.
For example, the conversion to double is nearly always implemented, but
the conversion to uint8 might not be.  In that case, the following code will
work

@example
cast (cast (@var{user_defined_val}, "double"), "uint8")
@end example

@xseealso{typecast, int8, uint8, int16, uint16, int32, uint32, int64, uint64, double, single, logical, char, class, typeinfo}
@end deftypefn
citation
@c citation scripts/miscellaneous/citation.m
@deftypefn  {} {} citation
@deftypefnx {} {} citation @var{package}
Display instructions for citing GNU Octave or its packages in publications.

When called without an argument, display information on how to cite the core
GNU Octave system.

When given a package name @var{package}, display information on citing the
specific named package.  Note that some packages may not yet have
instructions on how to cite them.

The GNU Octave developers and its active community of package authors have
invested a lot of time and effort in creating GNU Octave as it is today.
Please give credit where credit is due and cite GNU Octave and its packages
when you use them.

@end deftypefn
clearvars
@c clearvars scripts/miscellaneous/clearvars.m
@deftypefn  {} {} clearvars
@deftypefnx {} {} clearvars @var{pattern} @dots{}
@deftypefnx {} {} clearvars -regexp @var{pattern} @dots{}
@deftypefnx {} {} clearvars @dots{} -except @var{pattern} @dots{}
@deftypefnx {} {} clearvars @dots{} -except -regexp @var{pattern} @dots{}
@deftypefnx {} {} clearvars -global @dots{}
Delete the variables matching the given @var{pattern}s from memory.

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

If the @option{-regexp} option is given then subsequent patterns are treated
as regular expressions and any matches will be cleared.

If the @option{-except} option is given then subsequent patterns select
variables that will @strong{not} be cleared.

If the @option{-global} option is given then all patterns will be applied
to global variables rather than local variables.

When called with no arguments, @code{clearvars} deletes all local variables.

Example Code:

Clear all variables starting with @qcode{'x'} and the specific variable
@qcode{"foobar"}

@example
clearvars x* foobar
@end example

Clear the specific variable @qcode{"foobar"} and use regular expressions to
clear all variables starting with @qcode{'x'} or @qcode{'y'}.

@example
clearvars foobar -regexp ^x ^y
@end example

Clear all variables except for @qcode{"foobar"}

@example
clearvars -except foobar
@end example

Clear all variables beginning with @qcode{"foo"}, except for those ending
in @qcode{"bar"}

@example
clearvars foo* -except -regexp bar$
@end example

@xseealso{clear, who, whos, exist}
@end deftypefn
compare_versions
@c compare_versions scripts/miscellaneous/compare_versions.m
@deftypefn {} {} compare_versions (@var{v1}, @var{v2}, @var{operator})
Compare two version strings using the given @var{operator}.

This function assumes that versions @var{v1} and @var{v2} are arbitrarily
long strings made of numeric and period characters possibly followed by an
arbitrary string (e.g., @qcode{"1.2.3"}, @qcode{"0.3"}, @qcode{"0.1.2+"},
or @qcode{"1.2.3.4-test1"}).

The version is first split into numeric and character portions and then
the parts are padded to be the same length (i.e., @qcode{"1.1"} would be
padded to be @qcode{"1.1.0"} when being compared with @qcode{"1.1.1"}, and
separately, the character parts of the strings are padded with nulls).

The operator can be any logical operator from the set

@itemize @bullet
@item
@qcode{"=="}
equal

@item
@qcode{"<"}
less than

@item
@qcode{"<="}
less than or equal to

@item
@qcode{">"}
greater than

@item
@qcode{">="}
greater than or equal to

@item
@qcode{"!="}
not equal

@item
@qcode{"~="}
not equal
@end itemize

Note that version @qcode{"1.1-test2"} will compare as greater than
@qcode{"1.1-test10"}.  Also, since the numeric part is compared first,
@qcode{"a"} compares less than @qcode{"1a"} because the second string
starts with a numeric part even though @code{double ("a")} is greater than
@code{double ("1").}
@end deftypefn
computer
@c computer scripts/miscellaneous/computer.m
@deftypefn  {} {} computer ()
@deftypefnx {} {@var{c} =} computer ()
@deftypefnx {} {[@var{c}, @var{maxsize}] =} computer ()
@deftypefnx {} {[@var{c}, @var{maxsize}, @var{endian}] =} computer ()
@deftypefnx {} {@var{arch} =} computer ("arch")
Print or return a string of the form @var{cpu}-@var{vendor}-@var{os} that
identifies the type of computer that Octave is running on.

If invoked with an output argument, the value is returned instead of
printed.  For example:

@example
@group
computer ()
   @print{} x86_64-pc-linux-gnu

mycomp = computer ()
   @result{} mycomp = x86_64-pc-linux-gnu
@end group
@end example

If two output arguments are requested, also return the maximum number of
elements for an array.  This will depend on whether Octave has been
compiled with 32-bit or 64-bit index vectors.

If three output arguments are requested, also return the byte order of the
current system as a character (@qcode{"B"} for big-endian or @qcode{"L"}
for little-endian).

If the argument @qcode{"arch"} is specified, return a string indicating the
architecture of the computer on which Octave is running.
@xseealso{isunix, ismac, ispc}
@end deftypefn
copyfile
@c copyfile scripts/miscellaneous/copyfile.m
@deftypefn  {} {} copyfile @var{f1} @var{f2}
@deftypefnx {} {} copyfile @var{f1} @var{f2} f
@deftypefnx {} {} copyfile (@var{f1}, @var{f2})
@deftypefnx {} {} copyfile (@var{f1}, @var{f2}, 'f')
@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} copyfile (@dots{})
Copy the source file(s) or directory @var{f1} to the destination @var{f2}.

The name @var{f1} may contain globbing patterns, or may be a cell array of
strings.  If @var{f1} expands to multiple filenames, @var{f2} must be a
directory.

When the force flag @qcode{'f'} is given any existing files will be
overwritten without prompting.

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.  Note that the status code is exactly opposite that of the
@code{system} command.
@xseealso{movefile, rename, unlink, delete, glob}
@end deftypefn
delete
@c delete scripts/miscellaneous/delete.m
@deftypefn  {} {} delete (@var{file})
@deftypefnx {} {} delete (@var{file1}, @var{file2}, @dots{})
@deftypefnx {} {} delete (@var{handle})
Delete the named file or graphics handle.

@var{file} may contain globbing patterns such as @samp{*}.  Multiple files
to be deleted may be specified in the same function call.

@var{handle} may be a scalar or vector of graphic handles to delete.

Programming Note: Deleting graphics objects is the proper way to remove
features from a plot without clearing the entire figure.
@xseealso{clf, cla, unlink, rmdir}
@end deftypefn
dir
@c dir scripts/miscellaneous/dir.m
@deftypefn  {} {} dir
@deftypefnx {} {} dir (@var{directory})
@deftypefnx {} {[@var{list}] =} dir (@var{directory})
Display file listing for directory @var{directory}.

If @var{directory} is not specified then list the present working directory.

If a return value is requested, return a structure array with the fields

@table @asis
@item name
File or directory name.

@item folder
Location of file or directory

@item date
Timestamp of file modification (string value).

@item bytes
File size in bytes.

@item isdir
True if name is a directory.

@item datenum
Timestamp of file modification as serial date number (double).

@item statinfo
Information structure returned from @code{stat}.
@end table

If @var{directory} is a filename, rather than a directory, then return
information about the named file.  @var{directory} may also be a list rather
than a single directory or file.

@var{directory} is subject to shell expansion if it contains any wildcard
characters @samp{*}, @samp{?}, @samp{[]}.  To find a literal example of a
wildcard character the wildcard must be escaped using the backslash operator
@samp{\}.

Note that for symbolic links, @code{dir} returns information about the
file that the symbolic link points to rather than the link itself.
However, if the link points to a nonexistent file, @code{dir} returns
information about the link.
@xseealso{ls, readdir, glob, what, stat, lstat}
@end deftypefn
dos
@c dos scripts/miscellaneous/dos.m
@deftypefn  {} {} dos ("@var{command}")
@deftypefnx {} {@var{status} =} dos ("@var{command}")
@deftypefnx {} {[@var{status}, @var{text}] =} dos ("@var{command"})
@deftypefnx {} {[@dots{}] =} dos ("@var{command}", "-echo")
Execute a system command if running under a Windows-like operating system,
otherwise do nothing.

Octave waits for the external command to finish before returning the exit
status of the program in @var{status} and any output in @var{text}.

When called with no output argument, or the @qcode{"-echo"} argument is
given, then @var{text} is also sent to standard output.
@xseealso{unix, system, isunix, ismac, ispc}
@end deftypefn
edit
@c edit scripts/miscellaneous/edit.m
@deftypefn  {} {} edit @var{name}
@deftypefnx {} {} edit @var{field} @var{value}
@deftypefnx {} {@var{value} =} edit ("get", @var{field})
@deftypefnx {} {@var{value} =} edit ("get", "all")
Edit the named function, or change editor settings.

If @code{edit} is called with the name of a file or function as its
argument it will be opened in the text editor defined by @env{EDITOR}.

@itemize @bullet
@item
If the function @var{name} is available in a file on your path and that
file is modifiable, then it will be edited in place.  If it is a system
function, then it will first be copied to the directory @env{HOME} (see
below) and then edited.  If no file is found, then the m-file variant,
ending with @qcode{".m"}, will be considered.  If still no file is found,
then variants with a leading @qcode{"@@"} and then with both a leading
@qcode{"@@"} and trailing @qcode{".m"} will be considered.

@item
If @var{name} is the name of a function defined in the interpreter but not
in an m-file, then an m-file will be created in @env{HOME} to contain that
function along with its current definition.

@item
If @code{@var{name}.cc} is specified, then it will search for
@code{@var{name}.cc} in the path and try to modify it, otherwise it will
create a new @file{.cc} file in the current directory.  If @var{name}
happens to be an m-file or interpreter defined function, then the text of
that function will be inserted into the .cc file as a comment.

@item
If @file{@var{name}.ext} is on your path then it will be edited, otherwise
the editor will be started with @file{@var{name}.ext} in the current
directory as the filename.  If @file{@var{name}.ext} is not modifiable,
it will be copied to @env{HOME} before editing.

@strong{Warning:} You may need to clear @var{name} before the new definition
is available.  If you are editing a .cc file, you will need to execute
@code{mkoctfile @file{@var{name}.cc}} before the definition will be
available.
@end itemize

If @code{edit} is called with @var{field} and @var{value} variables, the
value of the control field @var{field} will be set to @var{value}.

If an output argument is requested and the first input argument is
@code{get} then @code{edit} will return the value of the control field
@var{field}.  If the control field does not exist, edit will return a
structure containing all fields and values.  Thus, @code{edit ("get",
@qcode{"all"})} returns a complete control structure.

The following control fields are used:

@table @samp
@item home
This is the location of user local m-files.  Be sure it is in your path.
The default is @file{~/octave}.

@item author
This is the name to put after the "## Author:" field of new functions.  By
default it guesses from the @code{gecos} field of the password database.

@item email
This is the e-mail address to list after the name in the author field.  By
default it guesses @code{<$LOGNAME@@$HOSTNAME>}, and if @code{$HOSTNAME}
is not defined it uses @code{uname -n}.  You probably want to override
this.  Be sure to use the format @code{@email{user@@host}}.

@item license

@table @samp
@item gpl
GNU General Public License (default).

@item bsd
BSD-style license without advertising clause.

@item pd
Public domain.

@item "text"
Your own default copyright and license.
@end table

Unless you specify @samp{pd}, edit will prepend the copyright statement
with "Copyright (C) YYYY Author".

@item mode
This value determines whether the editor should be started in async mode
(editor is started in the background and Octave continues) or sync mode
(Octave waits until the editor exits).  Set it to @qcode{"sync"} to start
the editor in sync mode.  The default is @qcode{"async"}
(@pxref{XREFsystem,,system}).

@item editinplace
Determines whether files should be edited in place, without regard to
whether they are modifiable or not.  The default is @code{false}.
@end table
@end deftypefn
fact
@c fact scripts/miscellaneous/fact.m
@deftypefn  {} {} fact
@deftypefnx {} {@var{truth} =} fact ()
Display an amazing and random fact about the world's greatest hacker.
@end deftypefn
fieldnames
@c fieldnames scripts/miscellaneous/fieldnames.m
@deftypefn  {} {@var{names} =} fieldnames (@var{struct})
@deftypefnx {} {@var{names} =} fieldnames (@var{obj})
@deftypefnx {} {@var{names} =} fieldnames (@var{javaobj})
@deftypefnx {} {@var{names} =} fieldnames ("@var{javaclassname}")
Return a cell array of strings with the names of the fields in the
specified input.

When the input is a structure @var{struct}, the names are the elements of
the structure.

When the input is an Octave object @var{obj}, the names are the public
properties of the object.

When the input is a Java object @var{javaobj} or a string containing the
name of a Java class @var{javaclassname}, the names are the public fields
(data members) of the object or class.
@xseealso{numfields, isfield, orderfields, struct, methods}
@end deftypefn
fileattrib
@c fileattrib scripts/miscellaneous/fileattrib.m
@deftypefn  {} {} fileattrib (@var{file})
@deftypefnx {} {} fileattrib ()
@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} fileattrib (@dots{})
Return information about @var{file}.

If successful, @var{status} is 1 and @var{msg} is a structure with the
following fields:

@table @code
@item Name
Full name of @var{file}.

@item archive
True if @var{file} is an archive (Windows).

@item system
True if @var{file} is a system file (Windows).

@item hidden
True if @var{file} is a hidden file (Windows).

@item directory
True if @var{file} is a directory.

@item  UserRead
@itemx GroupRead
@itemx OtherRead
True if the user (group; other users) has read permission for @var{file}.

@item  UserWrite
@itemx GroupWrite
@itemx OtherWrite
True if the user (group; other users) has write permission for @var{file}.

@item  UserExecute
@itemx GroupExecute
@itemx OtherExecute
True if the user (group; other users) has execute permission for @var{file}.
@end table

If an attribute does not apply (i.e., archive on a Unix system) then the
field is set to NaN.

If @code{attrib} fails, @var{msg} is a non-empty string containing an
error message and @var{msg_id} is the non-empty string @qcode{"fileattrib"}.

With no input arguments, return information about the current directory.

If @var{file} contains globbing characters, return information about all
the matching files.
@xseealso{glob}
@end deftypefn
fileparts
@c fileparts scripts/miscellaneous/fileparts.m
@deftypefn {} {[@var{dir}, @var{name}, @var{ext}] =} fileparts (@var{filename})
Return the directory, name, and extension components of @var{filename}.

The input @var{filename} is a string which is parsed.  There is no attempt
to check whether the filename or directory specified actually exists.
@xseealso{fullfile, filesep}
@end deftypefn
fullfile
@c fullfile scripts/miscellaneous/fullfile.m
@deftypefn  {} {@var{filename} =} fullfile (@var{dir1}, @var{dir2}, @dots{}, @var{file})
@deftypefnx {} {@var{filenames} =} fullfile (@dots{}, @var{files})
Build complete filename from separate parts.

Joins any number of path components intelligently.  The return value is
the concatenation of each component with exactly one file separator
between each non empty part and at most one leading and/or trailing file
separator.

If the last component part is a cell array, returns a cell array of
filepaths, one for each element in the last component, e.g.:

@example
@group
fullfile ("/home/username", "data", @{"f1.csv", "f2.csv", "f3.csv"@})
  @result{}
      @{
        [1,1] = /home/username/data/f1.csv
        [1,2] = /home/username/data/f2.csv
        [1,3] = /home/username/data/f3.csv
      @}
@end group
@end example

On Windows systems, while forward slash file separators do work, they are
replaced by backslashes; in addition drive letters are stripped of leading
file separators to obtain a valid file path.

Note: @code{fullfile} does not perform any validation of the resulting full
filename.
@xseealso{fileparts, filesep}
@end deftypefn
getfield
@c getfield scripts/miscellaneous/getfield.m
@deftypefn  {} {@var{val} =} getfield (@var{s}, @var{field})
@deftypefnx {} {@var{val} =} getfield (@var{s}, @var{sidx1}, @var{field1}, @var{fidx1}, @dots{})
Get the value of the field named @var{field} from a structure or nested
structure @var{s}.

If @var{s} is a structure array then @var{sidx} selects an element of the
structure array, @var{field} specifies the field name of the selected
element, and @var{fidx} selects which element of the field (in the case of
an array or cell array).  See @code{setfield} for a more complete
description of the syntax.

@xseealso{setfield, rmfield, orderfields, isfield, fieldnames, isstruct, struct}
@end deftypefn
grabcode
@c grabcode scripts/miscellaneous/grabcode.m
@deftypefn  {} {} grabcode (@var{url})
@deftypefnx {} {} grabcode (@var{filename})
@deftypefnx {} {@var{code_str} =} grabcode (@dots{})

Grab the code from a report created by the @code{publish} function.

The grabbed code inside the published report must be enclosed by the
strings @samp{##### SOURCE BEGIN #####} and @samp{##### SOURCE END #####}.
The @code{publish} function creates this format automatically.

If no return value is requested the code is saved to a temporary file and
opened in the default editor.  NOTE: The temporary file must be saved under
a new or the code will be lost.

If an output is requested the grabbed code will be returned as string
@var{code_str}.

Example:

@example
@group
publish ("my_script.m");
grabcode ("html/my_script.html");
@end group
@end example

The example above publishes @file{my_script.m} to the default location
@file{html/my_script.html}.  Next, the published Octave script is grabbed to
edit its content in a new temporary file.

@xseealso{publish}
@end deftypefn
gunzip
@c gunzip scripts/miscellaneous/gunzip.m
@deftypefn  {} {} gunzip (@var{gzfile})
@deftypefnx {} {} gunzip (@var{gzfile}, @var{dir})
@deftypefnx {} {@var{filelist} =} gunzip (@dots{})
Unpack the gzip archive @var{gzfile}.

If @var{gzfile} is a directory, all gzfiles in the directory will be
recursively unpacked.

If @var{dir} is specified the files are unpacked in this directory rather
than the one where @var{gzfile} is located.

The optional output @var{filelist} is a list of the uncompressed files.
@xseealso{gzip, unpack, bunzip2, unzip, untar}
@end deftypefn
info
@c info scripts/miscellaneous/info.m
@deftypefn {} {} info ()
Display contact information for the GNU Octave community.
@end deftypefn
inputParser
@c inputParser scripts/miscellaneous/inputParser.m
@deftypefn {} {@var{p} =} inputParser ()
Create object @var{p} of the inputParser class.

This class is designed to allow easy parsing of function arguments.  The
class supports four types of arguments:

@enumerate
@item mandatory (see @code{addRequired});

@item optional (see @code{addOptional});

@item named (see @code{addParameter});

@item switch (see @code{addSwitch}).
@end enumerate

After defining the function API with these methods, the supplied arguments
can be parsed with the @code{parse} method and the parsing results
accessed with the @code{Results} accessor.

@end deftypefn
@deftypefn {} {} inputParser.Parameters
Return list of parameter names already defined.

@end deftypefn
@deftypefn {} {} inputParser.Results
Return structure with argument names as fieldnames and corresponding values.

@end deftypefn
@deftypefn {} {} inputParser.Unmatched
Return structure similar to @code{Results}, but for unmatched parameters.
See the @code{KeepUnmatched} property.

@end deftypefn
@deftypefn {} {} inputParser.UsingDefaults
Return cell array with the names of arguments that are using default values.

@end deftypefn
@deftypefn {} {} inputParser.CaseSensitive = @var{boolean}
Set whether matching of argument names should be case sensitive.  Defaults
to false.

@end deftypefn
@deftypefn {} {} inputParser.FunctionName = @var{name}
Set function name to be used in error messages; Defaults to empty string.

@end deftypefn
@deftypefn {} {} inputParser.KeepUnmatched = @var{boolean}
Set whether an error should be given for non-defined arguments.  Defaults to
false.  If set to true, the extra arguments can be accessed through
@code{Unmatched} after the @code{parse} method.  Note that since
@code{Switch} and @code{Parameter} arguments can be mixed, it is
not possible to know the unmatched type.  If argument is found unmatched
it is assumed to be of the @code{Parameter} type and it is expected to
be followed by a value.

@end deftypefn
@deftypefn {} {} inputParser.StructExpand = @var{boolean}
Set whether a structure can be passed to the function instead of
parameter/value pairs.  Defaults to true.

The following example shows how to use this class:

@example
function check (varargin)
@c The next two comments need to be indented by one for alignment
  p = inputParser ();                      # create object
  p.FunctionName = "check";                # set function name
  p.addRequired ("pack", @@ischar);         # mandatory argument
  p.addOptional ("path", pwd(), @@ischar);  # optional argument

  ## create a function handle to anonymous functions for validators
  val_mat = @@(x) isvector (x) && all (x <= 1) && all (x >= 0);
  p.addOptional ("mat", [0 0], val_mat);

  ## create two arguments of type "Parameter"
  val_type = @@(x) any (strcmp (x, @{"linear", "quadratic"@}));
  p.addParameter ("type", "linear", val_type);
  val_verb = @@(x) any (strcmp (x, @{"low", "medium", "high"@}));
  p.addParameter ("tolerance", "low", val_verb);

  ## create a switch type of argument
  p.addSwitch ("verbose");

  p.parse (varargin@{:@});  # Run created parser on inputs

  ## the rest of the function can access inputs by using p.Results.
  ## for example, get the tolerance input with p.Results.tolerance
endfunction
@end example

@example
@group
check ("mech");           # valid, use defaults for other arguments
check ();                 # error, one argument is mandatory
check (1);                # error, since ! ischar
check ("mech", "~/dev");  # valid, use defaults for other arguments

check ("mech", "~/dev", [0 1 0 0], "type", "linear");  # valid

## following is also valid.  Note how the Switch argument type can
## be mixed into or before the Parameter argument type (but it
## must still appear after any Optional argument).
check ("mech", "~/dev", [0 1 0 0], "verbose", "tolerance", "high");

## following returns an error since not all optional arguments,
## `path' and `mat', were given before the named argument `type'.
check ("mech", "~/dev", "type", "linear");
@end group
@end example

@emph{Note 1}: A function can have any mixture of the four API types but
they must appear in a specific order.  @code{Required} arguments must be
first and can be followed by any @code{Optional} arguments.  Only
the @code{Parameter} and @code{Switch} arguments may be mixed
together and they must appear at the end.

@emph{Note 2}: If both @code{Optional} and @code{Parameter} arguments
are mixed in a function API then once a string Optional argument fails to
validate it will be considered the end of the @code{Optional}
arguments.  The remaining arguments will be compared against any
@code{Parameter} or @code{Switch} arguments.

@xseealso{nargin, validateattributes, validatestring, varargin}
@end deftypefn
inputname
@c inputname scripts/miscellaneous/inputname.m
@deftypefn  {} {} inputname (@var{n})
@deftypefnx {} {} inputname (@var{n}, @var{ids_only})
Return the name of the @var{n}-th argument to the calling function.

If the argument is not a simple variable name, return an empty string.  As
an example, a reference to a field in a structure such as @code{s.field} is
not a simple name and will return @qcode{""}.

@code{inputname} is only useful within a function.  When used at the command
line it always returns an empty string.

By default, return an empty string if the @var{n}-th argument is not
a valid variable name.  If the optional argument @var{ids_only} is
false, return the text of the argument even if it is not a valid
variable name.
@xseealso{nargin, nthargout}
@end deftypefn
isdeployed
@c isdeployed scripts/miscellaneous/isdeployed.m
@deftypefn {} {} isdeployed ()
Return true if the current program has been compiled and is running
separately from the Octave interpreter and false if it is running in
the Octave interpreter.

Currently, this function always returns false in Octave.
@end deftypefn
isfile
@c isfile scripts/miscellaneous/isfile.m
@deftypefn {} {@var{tf} =} isfile (@var{f})
Return true if @var{f} is a regular file and false otherwise.

If @var{f} is a cell array of strings, @var{tf} is a logical array of the
same size.
@xseealso{isfolder, exist, stat, is_absolute_filename, is_rooted_relative_filename}
@end deftypefn
isfolder
@c isfolder scripts/miscellaneous/isfolder.m
@deftypefn  {} {} isfolder (@var{f})
@deftypefnx {} {@var{tf} =} isfolder (@var{f})
Return true if @var{f} is a directory and false otherwise.

If @var{f} is a cell array of strings, @var{tf} is a logical array of the
same size.
@xseealso{isfile, exist, stat, is_absolute_filename, is_rooted_relative_filename}
@end deftypefn
ismac
@c ismac scripts/miscellaneous/ismac.m
@deftypefn {} {} ismac ()
Return true if Octave is running on a Mac OS X system and false otherwise.
@xseealso{isunix, ispc}
@end deftypefn
ispc
@c ispc scripts/miscellaneous/ispc.m
@deftypefn {} {} ispc ()
Return true if Octave is running on a Windows system and false otherwise.
@xseealso{isunix, ismac}
@end deftypefn
isunix
@c isunix scripts/miscellaneous/isunix.m
@deftypefn {} {} isunix ()
Return true if Octave is running on a Unix-like system and false otherwise.
@xseealso{ismac, ispc}
@end deftypefn
license
@c license scripts/miscellaneous/license.m
@deftypefn  {} {} license
@deftypefnx {} {} license inuse
@deftypefnx {} {} license inuse @var{feature}
@deftypefnx {} {} license ("inuse")
@deftypefnx {} {@var{retval} =} license ("inuse")
@deftypefnx {} {@var{retval} =} license ("test", @var{feature})
@deftypefnx {} {@var{retval} =} license ("checkout", @var{feature})
@deftypefnx {} {[@var{retval}, @var{errmsg}] =} license ("checkout", @var{feature})
Get license information for Octave and Octave packages.

GNU Octave is free software distributed under the GNU General Public
License (GPL), and a license manager makes no sense.  This function is
provided only for @sc{matlab} compatibility.

When called with no extra input arguments, it returns the Octave license,
otherwise the first input defines the operation mode and must be one of
the following strings: @code{inuse}, @code{test}, and @code{checkout}.
The optional @var{feature} argument can either be @qcode{"octave"} (core),
or an Octave package.

@table @asis
@item @qcode{"inuse"}
Returns a list of loaded features, i.e., octave and the list of loaded
packages.  If an output is requested, it returns a struct array with
the fields @qcode{"feature"}, and @qcode{"user"}.

@item @qcode{"test"}
Return true if the specified @var{feature} is installed, false otherwise.

An optional third argument @qcode{"enable"} or @qcode{"disable"} is
accepted but ignored.

@item @qcode{"checkout"}
Return true if the specified @var{feature} is installed, false otherwise.
An optional second output will have an error message if a package is not
installed.

@end table

@xseealso{pkg, ver, version}
@end deftypefn
list_primes
@c list_primes scripts/miscellaneous/list_primes.m
@deftypefn  {} {} list_primes ()
@deftypefnx {} {} list_primes (@var{n})
List the first @var{n} primes.

If @var{n} is unspecified, the first 25 primes are listed.
@xseealso{primes, isprime}
@end deftypefn
loadobj
@c loadobj scripts/miscellaneous/loadobj.m
@deftypefn {} {@var{b} =} loadobj (@var{a})
Method of a class to manipulate an object after loading it from a file.

The function @code{loadobj} is called when the object @var{a} is loaded
using the @code{load} function.  An example of the use of @code{saveobj}
might be to add fields to an object that don't make sense to be saved.
For example:

@example
@group
function b = loadobj (a)
  b = a;
  b.addmissingfield = addfield (b);
endfunction
@end group
@end example

@xseealso{saveobj, class}
@end deftypefn
ls
@c ls scripts/miscellaneous/ls.m
@deftypefn  {} {} ls
@deftypefnx {} {} ls @var{filenames}
@deftypefnx {} {} ls @var{options}
@deftypefnx {} {} ls @var{options} @var{filenames}
@deftypefnx {} {@var{list} =} ls (@dots{})

List directory contents.

The @code{ls} command is implemented by calling the native operating
system's directory listing command---available @var{options} will vary from
system to system.

Filenames are subject to shell expansion if they contain any wildcard
characters @samp{*}, @samp{?}, @samp{[]}.  To find a literal example of a
wildcard character the wildcard must be escaped using the backslash operator
@samp{\}.

If the optional output @var{list} is requested then @code{ls} returns a
character array with one row for each file/directory name.

Example usage on a UNIX-like system:

@example
@group
ls -l
     @print{} total 12
     @print{} -rw-r--r--   1 jwe  users  4488 Aug 19 04:02 foo.m
     @print{} -rw-r--r--   1 jwe  users  1315 Aug 17 23:14 bar.m
@end group
@end example

@xseealso{dir, readdir, glob, what, stat, filesep, ls_command}
@end deftypefn
ls_command
@c ls_command scripts/miscellaneous/ls_command.m
@deftypefn  {} {@var{val} =} ls_command ()
@deftypefnx {} {@var{old_val} =} ls_command (@var{new_val})
Query or set the shell command used by Octave's @code{ls} command.
@xseealso{ls}
@end deftypefn
menu
@c menu scripts/miscellaneous/menu.m
@deftypefn  {} {@var{choice} =} menu (@var{title}, @var{opt1}, @dots{})
@deftypefnx {} {@var{choice} =} menu (@var{title}, @{@var{opt1}, @dots{}@})
Display a menu with heading @var{title} and options @var{opt1}, @dots{},
and wait for user input.

If the GUI is running, the menu is displayed graphically using
@code{listdlg}.  Otherwise, the title and menu options are printed on the
console.

@var{title} is a string and the options may be input as individual strings
or as a cell array of strings.

The return value @var{choice} is the number of the option selected by the
user counting from 1.  If the user aborts the dialog or makes an invalid
selection then 0 is returned.

This function is useful for interactive programs.  There is no limit to the
number of options that may be passed in, but it may be confusing to present
more than will fit easily on one screen.
@xseealso{input, listdlg}
@end deftypefn
methods
@c methods scripts/miscellaneous/methods.m
@deftypefn  {} {} methods (@var{obj})
@deftypefnx {} {} methods ("@var{classname}")
@deftypefnx {} {@var{mtds} =} methods (@dots{})
List the names of the public methods for the object @var{obj} or the
named class @var{classname}.

@var{obj} may be an Octave class object or a Java object.
@var{classname} may be the name of an Octave class or a Java class.

When called with no output arguments, @code{methods} prints the list of
method names to the screen.  Otherwise, the output argument @var{mtds}
contains the list in a cell array of strings.
@xseealso{fieldnames}
@end deftypefn
mex
@c mex scripts/miscellaneous/mex.m
@deftypefn {} {} mex [options] file @dots{}
Compile source code written in C, C++, or Fortran, to a MEX file.

This is equivalent to @code{mkoctfile --mex [options] file}.
@xseealso{mkoctfile, mexext}
@end deftypefn
mexext
@c mexext scripts/miscellaneous/mexext.m
@deftypefn {} {} mexext ()
Return the filename extension used for MEX files.
@xseealso{mex}
@end deftypefn
mkdir
@c mkdir scripts/miscellaneous/mkdir.m
@deftypefn  {} {} mkdir @var{dirname}
@deftypefnx {} {} mkdir @var{parent} @var{dirname}
@deftypefnx {} {} mkdir (@var{dirname})
@deftypefnx {} {} mkdir (@var{parent}, @var{dirname})
@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} mkdir (@dots{})
Create a directory named @var{dirname} in the directory @var{parent},
creating any intermediate directories if necessary.

If @var{dirname} is a relative path, and no @var{parent} directory is
specified, then the present working directory is used.

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

When creating a directory permissions will be set to
@w{@code{0777 - UMASK}}.

@xseealso{rmdir, pwd, cd, umask}
@end deftypefn
mkoctfile
@c mkoctfile scripts/miscellaneous/mkoctfile.m
@deftypefn  {} {} mkoctfile [-options] file @dots{}
@deftypefnx {} {[@var{output}, @var{status}] =} mkoctfile (@dots{})

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

@code{mkoctfile} can be called from the shell prompt or from the Octave
prompt.  Calling it from the Octave prompt simply delegates the call to
the shell prompt.  The output is stored in the @var{output} variable and
the exit status in the @var{status} variable.

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

@table @samp
@item -I DIR
Add the include directory DIR to compile commands.

@item -D DEF
Add the definition DEF to the compiler call.

@item -l LIB
Add the library LIB to the link command.

@item -L DIR
Add the library directory DIR to the link command.

@item  -M
@itemx --depend
Generate dependency files (.d) for C and C++ source files.

@item -R DIR
Add the run-time path to the link command.

@item @nospell{-Wl,@dots{}}
Pass options to the linker like @nospell{"-Wl,-rpath=@dots{}"}.
The quotes are needed since commas are interpreted as command
separators.

@item -W@dots{}
Pass options to the assembler like @nospell{"-Wa,OPTION"}.

@item -c
Compile but do not link.

@item -g
Enable debugging options for compilers.

@item  -o FILE
@itemx --output FILE
Output filename.  Default extension is .oct (or .mex if @samp{--mex} is
specified) unless linking a stand-alone executable.

@item  -p VAR
@itemx --print VAR
Print configuration variable VAR@.  There are three categories of
variables:

Octave configuration variables that users may override with environment
variables.  These are used in commands that @code{mkoctfile} executes.

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

Octave configuration variables as above, but currently unused by
@code{mkoctfile}.

@example
@group
   AR
   DEPEND_EXTRA_SED_PATTERN
   DEPEND_FLAGS
   FFTW3F_LDFLAGS
   FFTW3F_LIBS
   FFTW3_LDFLAGS
   FFTW3_LIBS
   FFTW_LIBS
   FLIBS
   LIBS
   RANLIB
   READLINE_LIBS
@end group
@end example

Octave configuration variables that are provided for informational
purposes only.  Except for @samp{OCTAVE_HOME} and @samp{OCTAVE_EXEC_HOME},
users may not override these variables.

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

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

@item --link-stand-alone
Link a stand-alone executable file.

@item --mex
Assume we are creating a MEX file.  Set the default output extension to
".mex".

@item  -s
@itemx --strip
Strip the output file.

@item  -v
@itemx --verbose
Echo commands as they are executed.

@item file
The file to compile or link.  Recognized file types are:

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

@end table
@end deftypefn
movefile
@c movefile scripts/miscellaneous/movefile.m
@deftypefn  {} {} movefile @var{f1}
@deftypefnx {} {} movefile @var{f1} @var{f2}
@deftypefnx {} {} movefile @var{f1} @var{f2} f
@deftypefnx {} {} movefile (@var{f1})
@deftypefnx {} {} movefile (@var{f1}, @var{f2})
@deftypefnx {} {} movefile (@var{f1}, @var{f2}, 'f')
@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} movefile (@dots{})
Move the source file or directory @var{f1} to the destination @var{f2}.

The name @var{f1} may contain globbing patterns, or may be a cell array of
strings.  If @var{f1} expands to multiple filenames, @var{f2} must be a
directory.

If no destination @var{f2} is specified then the destination is the present
working directory.  If @var{f2} is a filename then @var{f1} is renamed to
@var{f2}.

When the force flag @qcode{'f'} is given any existing files will be
overwritten without prompting.

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.  Note that the status code is exactly opposite that of the
@code{system} command.
@xseealso{rename, copyfile, unlink, delete, glob}
@end deftypefn
namelengthmax
@c namelengthmax scripts/miscellaneous/namelengthmax.m
@deftypefn {} {} namelengthmax ()
Return the @sc{matlab} compatible maximum variable name length.

Octave is capable of storing strings up to @math{2^{31} - 1} in length.
However for @sc{matlab} compatibility all variable, function, and structure
field names should be shorter than the length returned by
@code{namelengthmax}.  In particular, variables stored to a @sc{matlab} file
format (@file{*.mat}) will have their names truncated to this length.
@end deftypefn
nargchk
@c nargchk scripts/miscellaneous/nargchk.m
@deftypefn  {} {@var{msgstr} =} nargchk (@var{minargs}, @var{maxargs}, @var{nargs})
@deftypefnx {} {@var{msgstr} =} nargchk (@var{minargs}, @var{maxargs}, @var{nargs}, "string")
@deftypefnx {} {@var{msgstruct} =} nargchk (@var{minargs}, @var{maxargs}, @var{nargs}, "struct")
Return an appropriate error message string (or structure) if the number of
inputs requested is invalid.

This is useful for checking to see that the number of input arguments
supplied to a function is within an acceptable range.

@strong{Caution}: @code{nargchk} is scheduled for deprecation.  Use
@code{narginchk} in all new code.
@xseealso{narginchk, nargoutchk, error, nargin, nargout}
@end deftypefn
narginchk
@c narginchk scripts/miscellaneous/narginchk.m
@deftypefn {} {} narginchk (@var{minargs}, @var{maxargs})
Check for correct number of input arguments.

Generate an error message if the number of arguments in the calling function
is outside the range @var{minargs} and @var{maxargs}.  Otherwise, do
nothing.

Both @var{minargs} and @var{maxargs} must be scalar numeric values.  Zero,
Inf, and negative values are all allowed, and @var{minargs} and
@var{maxargs} may be equal.

Note that this function evaluates @code{nargin} on the caller.

@xseealso{nargoutchk, error, nargout, nargin}
@end deftypefn
nargoutchk
@c nargoutchk scripts/miscellaneous/nargoutchk.m
@deftypefn  {} {} nargoutchk (@var{minargs}, @var{maxargs})
@deftypefnx {} {@var{msgstr} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs})
@deftypefnx {} {@var{msgstr} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs}, "string")
@deftypefnx {} {@var{msgstruct} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs}, "struct")
Check for correct number of output arguments.

In the first form, return an error if the number of arguments is not between
@var{minargs} and @var{maxargs}.  Otherwise, do nothing.  Note that this
function evaluates the value of @code{nargout} on the caller so its value
must have not been tampered with.

Both @var{minargs} and @var{maxargs} must be numeric scalars.  Zero, Inf,
and negative are all valid, and they can have the same value.

For backwards compatibility, the other forms return an appropriate error
message string (or structure) if the number of outputs requested is
invalid.

This is useful for checking to that the number of output arguments supplied
to a function is within an acceptable range.
@xseealso{narginchk, error, nargout, nargin}
@end deftypefn
news
@c news scripts/miscellaneous/news.m
@deftypefn  {} {} news
@deftypefnx {} {} news @var{package}
Display the current NEWS file for Octave or an installed package.

When called without an argument, display the NEWS file for Octave.

When given a package name @var{package}, display the current NEWS file for
that package.
@xseealso{ver, pkg}
@end deftypefn
nthargout
@c nthargout scripts/miscellaneous/nthargout.m
@deftypefn  {} {} nthargout (@var{n}, @var{func}, @dots{})
@deftypefnx {} {} nthargout (@var{n}, @var{ntot}, @var{func}, @dots{})
Return the @var{n}th output argument of the function specified by the
function handle or string @var{func}.

Any additional arguments are passed directly to @var{func}.  The total
number of arguments to call @var{func} with can be passed in @var{ntot}; by
default @var{ntot} is @var{n}.  The input @var{n} can also be a vector of
indices of the output, in which case the output will be a cell array of the
requested output arguments.

The intended use @code{nthargout} is to avoid intermediate variables.  For
example, when finding the indices of the maximum entry of a matrix, the
following two compositions of nthargout

@example
@group
@var{m} = magic (5);
cell2mat (nthargout ([1, 2], @@ind2sub, size (@var{m}),
                     nthargout (2, @@max, @var{m}(:))))
@result{} 5   3
@end group
@end example

@noindent
are completely equivalent to the following lines:

@example
@group
@var{m} = magic (5);
[~, idx] = max (@var{M}(:));
[i, j] = ind2sub (size (@var{m}), idx);
[i, j]
@result{} 5   3
@end group
@end example

It can also be helpful to have all output arguments in a single cell in the
following manner:

@example
@var{USV} = nthargout ([1:3], @@svd, hilb (5));
@end example

@xseealso{nargin, nargout, varargin, varargout, isargout}
@end deftypefn
open
@c open scripts/miscellaneous/open.m
@deftypefn  {} {} open @var{file}
@deftypefnx {} {@var{output} =} open (@var{file})
Open the file @var{file} in Octave or in an external application based on
the file type as determined by the filename extension.

By default, recognized file types are

@table @code
@item .m
Open file in the editor.  No @var{output} value is returned.

@item  .mat
@itemx octave-workspace
Open the data file with @code{load}.  If no return value @var{output}
is requested, variables are loaded in the base workspace.  Otherwise
@var{output} will be a structure containing loaded data.
@xref{XREFload, , load function}.

@item .ofig
Open the figure with hgload.  @xref{XREFhgload, , hgload function}.

@item .fig, .ofig
Load the figure

@item .exe
Execute the program (on Windows systems only).  No @var{output} value
is returned.
@end table

Custom file extensions may also be handled if a function @code{openxxx},
where @code{xxx} is the extension, is found in the load path.  The function
must accept the file name as input.  For example, in order to load
@nospell{@qcode{".dat"}} data files in the base workspace, as is done by
default for @qcode{".mat"} files, one may define
@nospell{@qcode{"opendat.m"}} with the following contents:

@example
@group
function retval = opendat (fname)
  evalin ("base", sprintf ("load ('%s');", fname));
endfunction
@end group
@end example

Other file types are opened in the appropriate external application.
@end deftypefn
orderfields
@c orderfields scripts/miscellaneous/orderfields.m
@deftypefn  {} {@var{sout} =} orderfields (@var{s1})
@deftypefnx {} {@var{sout} =} orderfields (@var{s1}, @var{s2})
@deftypefnx {} {@var{sout} =} orderfields (@var{s1}, @{@var{cellstr}@})
@deftypefnx {} {@var{sout} =} orderfields (@var{s1}, @var{p})
@deftypefnx {} {[@var{sout}, @var{p}] =} orderfields (@dots{})
Return a @emph{copy} of @var{s1} with fields arranged alphabetically, or as
specified by the second input.

Given one input struct @var{s1}, arrange field names alphabetically.

If a second struct argument is given, arrange field names in @var{s1} as
they appear in @var{s2}.  The second argument may also specify the order
in a cell array of strings @var{cellstr}.  The second argument may also
be a permutation vector.

The optional second output argument @var{p} is the permutation vector which
converts the original name order to the new name order.

Examples:

@example
@group
s = struct ("d", 4, "b", 2, "a", 1, "c", 3);
t1 = orderfields (s)
  @result{} t1 =
       scalar structure containing the fields:
         a =  1
         b =  2
         c =  3
         d =  4
@end group
@end example

@example
@group
t = struct ("d", @{@}, "c", @{@}, "b", @{@}, "a", @{@});
t2 = orderfields (s, t)
  @result{} t2 =
       scalar structure containing the fields:
         d =  4
         c =  3
         b =  2
         a =  1
@end group
@end example

@example
@group
t3 = orderfields (s, [3, 2, 4, 1])
  @result{} t3 =
       scalar structure containing the fields:
         a =  1
         b =  2
         c =  3
         d =  4
@end group
@end example

@example
@group
[t4, p] = orderfields (s, @{"d", "c", "b", "a"@})
  @result{} t4 =
       scalar structure containing the fields:
         d =  4
         c =  3
         b =  2
         a =  1
     p =
        1
        4
        2
        3
@end group
@end example

@xseealso{fieldnames, getfield, setfield, rmfield, isfield, isstruct, struct}
@end deftypefn
pack
@c pack scripts/miscellaneous/pack.m
@deftypefn {} {} pack ()
Consolidate workspace memory in @sc{matlab}.

This function is provided for compatibility, but does nothing in Octave.
@xseealso{clear}
@end deftypefn
parseparams
@c parseparams scripts/miscellaneous/parseparams.m
@deftypefn  {} {[@var{reg}, @var{prop}] =} parseparams (@var{params})
@deftypefnx {} {[@var{reg}, @var{var1}, @dots{}] =} parseparams (@var{params}, @var{name1}, @var{default1}, @dots{})
Return in @var{reg} the cell elements of @var{param} up to the first
string element and in @var{prop} all remaining elements beginning with the
first string element.

For example:

@example
@group
[reg, prop] = parseparams (@{1, 2, "linewidth", 10@})
reg =
@{
  [1,1] = 1
  [1,2] = 2
@}
prop =
@{
  [1,1] = linewidth
  [1,2] = 10
@}
@end group
@end example

The parseparams function may be used to separate regular numeric arguments
from additional arguments given as property/value pairs of the
@var{varargin} cell array.

In the second form of the call, available options are specified directly
with their default values given as name-value pairs.  If @var{params} do
not form name-value pairs, or if an option occurs that does not match any
of the available options, an error occurs.

When called from an m-file function, the error is prefixed with the name
of the caller function.

The matching of options is case-insensitive.

@xseealso{varargin, inputParser}
@end deftypefn
perl
@c perl scripts/miscellaneous/perl.m
@deftypefn  {} {@var{output} =} perl (@var{scriptfile})
@deftypefnx {} {@var{output} =} perl (@var{scriptfile}, @var{argument1}, @var{argument2}, @dots{})
@deftypefnx {} {[@var{output}, @var{status}] =} perl (@dots{})
Invoke Perl script @var{scriptfile}, possibly with a list of command line
arguments.

Return output in @var{output} and optional status in @var{status}.  If
@var{scriptfile} is not an absolute filename it is searched for in the
current directory and then in the Octave loadpath.
@xseealso{system, python}
@end deftypefn
publish
@c publish scripts/miscellaneous/publish.m
@deftypefn  {} {} publish (@var{file})
@deftypefnx {} {} publish (@var{file}, @var{output_format})
@deftypefnx {} {} publish (@var{file}, @var{option1}, @var{value1}, @dots{})
@deftypefnx {} {} publish (@var{file}, @var{options})
@deftypefnx {} {@var{output_file} =} publish (@var{file}, @dots{})

Generate a report from the Octave script file @var{file} in one of several
output formats.

The generated reports interpret any Publishing Markup in comments, which is
explained in detail in the GNU Octave manual.  Assume the following example,
using some Publishing Markup, to be the contents of the script file
@file{pub_example.m}:

@example
@group
## Headline title
#
# Some *bold*, _italic_, or |monospaced| Text with
# a <https://www.octave.org link to *GNU Octave*>.
##

# "Real" Octave commands to be evaluated
sombrero ()

%% @sc{matlab} comment style ('%') is supported as well
%
% * Bulleted list item 1
% * Bulleted list item 2
%
% # Numbered list item 1
% # Numbered list item 2
@end group
@end example

To publish this script file, type @code{publish ("pub_example.m")}.

With only @var{file} given, a HTML report is generated in a subdirectory
@file{html} relative to the current working directory.  The Octave commands
are evaluated in a separate context and any figures created while executing
the script file are included in the report.  All formatting syntax of
@var{file} is treated according to the specified output format and included
in the report.

Using @code{publish (@var{file}, @var{output_format})} is equivalent to the
function call using a structure

@example
@group
@var{options}.format = @var{output_format};
publish (@var{file}, @var{options})
@end group
@end example

@noindent
which is described below.  The same holds for using option/value pairs

@example
@group
@var{options}.@var{option1} = @var{value1};
publish (@var{file}, @var{options})
@end group
@end example

The structure @var{options} can have the following field names.  If a field
name is not specified, the default value is used:

@itemize @bullet
@item
@samp{format} --- Output format of the published script file, one of

@samp{html} (default), @samp{doc}, @samp{latex}, @samp{ppt},
@samp{pdf}, or @samp{xml}.

The output formats @samp{doc}, @samp{ppt}, and @samp{xml} are not currently
supported.  To generate a @samp{doc} report, open a generated @samp{html}
report with your office suite.

In Octave custom formats are supported by implementing all callback
subfunctions in a function file named
@samp{__publish_<custom format>_output__.m}.  To obtain a template for the
HTML format type:

@example
@group
edit (fullfile (fileparts (which ("publish")), ...
      "private", "__publish_html_output__.m"))
@end group
@end example

@item
@samp{outputDir} --- Full path of the directory where the generated report
will be located.  If no directory is given, the report is generated in a
subdirectory @file{html} relative to the current working directory.

@item
@samp{stylesheet} --- Not supported, only for @sc{matlab} compatibility.

@item
@samp{createThumbnail} --- Not supported, only for @sc{matlab}
compatibility.

@item
@samp{figureSnapMethod} --- Not supported, only for @sc{matlab}
compatibility.

@item
@samp{imageFormat} --- Desired format for any images produced while
evaluating the code.  The allowed image formats depend on the output format:

@itemize @bullet
@item @samp{html}, @samp{xml} --- @samp{png} (default), any image format
supported by Octave

@item @samp{latex} --- @samp{epsc2} (default), any image format supported by
Octave

@item @samp{pdf} --- @samp{jpg} (default) or @samp{bmp}, note @sc{matlab}
uses  @samp{bmp} as default

@item @samp{doc} or @samp{ppt} --- @samp{png} (default), @samp{jpg},
@samp{bmp}, or @samp{tiff}
@end itemize

@item
@samp{maxWidth} and @samp{maxHeight} --- Maximum width (height) of the
produced images in pixels.  An empty value means no restriction.  Both
values must be set in order for the option to work properly.

@samp{[]} (default), integer value @geq{} 0

@item
@samp{useNewFigure} --- Use a new figure window for figures created by the
evaluated code.  This avoids side effects with already opened figure
windows.

@samp{true} (default) or @samp{false}

@item
@samp{evalCode} --- Evaluate code of the Octave source file

@samp{true} (default) or @samp{false}

@item
@samp{catchError} --- Catch errors while evaluating code and continue

@samp{true} (default) or @samp{false}

@item
@samp{codeToEvaluate} --- Octave commands that should be evaluated prior to
publishing the script file.  These Octave commands do not appear in the
generated report.

@item
@samp{maxOutputLines} --- Maximum number of output lines from code
evaluation which are included in output.

@samp{Inf} (default) or integer value > 0

@item
@samp{showCode} --- Show the evaluated Octave commands in the generated
report

@samp{true} (default) or @samp{false}
@end itemize

The option output @var{output_file} is a string with path and file name
of the generated report.

@xseealso{grabcode}
@end deftypefn
python
@c python scripts/miscellaneous/python.m
@deftypefn  {} {@var{output} =} python (@var{scriptfile})
@deftypefnx {} {@var{output} =} python (@var{scriptfile}, @var{argument1}, @var{argument2}, @dots{})
@deftypefnx {} {[@var{output}, @var{status}] =} python (@dots{})
Invoke Python script @var{scriptfile}, possibly with a list of command line
arguments.

Return output in @var{output} and optional status in @var{status}.  If
@var{scriptfile} is not an absolute filename it is searched for in the
current directory and then in the Octave loadpath.
@xseealso{system, perl}
@end deftypefn
recycle
@c recycle scripts/miscellaneous/recycle.m
@deftypefn  {} {@var{val} =} recycle ()
@deftypefnx {} {@var{old_val} =} recycle (@var{new_val})
Query or set the preference for recycling deleted files.

When recycling is enabled, commands which would permanently erase files
instead move them to a temporary location (such as the directory labeled
Trash).

Programming Note: This function is provided for @sc{matlab} compatibility,
but recycling is not implemented in Octave.  To help avoid accidental data
loss an error will be raised if an attempt is made to enable file recycling.
@xseealso{delete, rmdir}
@end deftypefn
run
@c run scripts/miscellaneous/run.m
@deftypefn  {} {} run @var{script}
@deftypefnx {} {} run ("@var{script}")
Run @var{script} in the current workspace.

Scripts which reside in directories specified in Octave's load path, and
which end with the extension @file{".m"}, can be run simply by typing
their name.  For scripts not located on the load path, use @code{run}.

The filename @var{script} can be a bare, fully qualified, or relative
filename and with or without a file extension.  If no extension is
specified, Octave will first search for a script with the @file{".m"}
extension before falling back to the script name without an extension.

Implementation Note: If @var{script} includes a path component, then
@code{run} first changes the working directory to the directory where
@var{script} is found.  Next, the script is executed.  Finally, @code{run}
returns to the original working directory unless @var{script} has
specifically changed directories.
@xseealso{path, addpath, source}
@end deftypefn
saveobj
@c saveobj scripts/miscellaneous/saveobj.m
@deftypefn {} {@var{b} =} saveobj (@var{a})
Method of a class to manipulate an object prior to saving it to a file.

The function @code{saveobj} is called when the object @var{a} is saved
using the @code{save} function.  An example of the use of @code{saveobj}
might be to remove fields of the object that don't make sense to be saved
or it might be used to ensure that certain fields of the object are
initialized before the object is saved.  For example:

@example
@group
function b = saveobj (a)
  b = a;
  if (isempty (b.field))
     b.field = initfield (b);
  endif
endfunction
@end group
@end example

@xseealso{loadobj, class}
@end deftypefn
setfield
@c setfield scripts/miscellaneous/setfield.m
@deftypefn  {} {@var{sout} =} setfield (@var{s}, @var{field}, @var{val})
@deftypefnx {} {@var{sout} =} setfield (@var{s}, @var{sidx1}, @var{field1}, @var{fidx1}, @var{sidx2}, @var{field2}, @var{fidx2}, @dots{}, @var{val})

Return a @emph{copy} of the structure @var{s} with the field member
@var{field} set to the value @var{val}.

For example:

@example
@group
@var{s} = struct ();
@var{s} = setfield (@var{s}, "foo bar", 42);
@end group
@end example

@noindent
This is equivalent to

@example
@var{s}.("foo bar") = 42;
@end example

@noindent
Note that ordinary structure syntax @code{@var{s}.foo bar = 42} cannot be
used here, as the field name is not a valid Octave identifier because of
the space character.  Using arbitrary strings for field names is
incompatible with @sc{matlab}, and this usage will emit a warning if the
warning ID @code{Octave:language-extension} is enabled.
@xref{XREFwarning_ids,,warning_ids}.

With the second calling form, set a field of a structure array.  The
input @var{sidx} selects an element of the structure array, @var{field}
specifies the field name of the selected element, and @var{fidx} selects
which element of the field (in the case of an array or cell array).
The @var{sidx}, @var{field}, and @var{fidx} inputs can be repeated to
address nested structure array elements.  The structure array index and
field element index must be cell arrays while the field name must be a
string.

For example:

@example
@group
@var{s} = struct ("baz", 42);
setfield (@var{s}, @{1@}, "foo", @{1@}, "bar", 54)
@result{}
  ans =
    scalar structure containing the fields:
      baz =  42
      foo =
        scalar structure containing the fields:
          bar =  54
@end group
@end example

The example begins with an ordinary scalar structure to which a nested
scalar structure is added.  In all cases, if the structure index @var{sidx}
is not specified it defaults to 1 (scalar structure).  Thus, the example
above could be written more concisely as
@code{setfield (@var{s}, "foo", "bar", 54)}

Finally, an example with nested structure arrays:

@example
@group
@var{sa}.foo = 1;
@var{sa} = setfield (@var{sa}, @{2@}, "bar", @{3@}, "baz", @{1, 4@}, 5);
@var{sa}(2).bar(3)
@result{}
  ans =
    scalar structure containing the fields:
      baz =  0   0   0   5
@end group
@end example

Here @var{sa} is a structure array whose field at elements 1 and 2 is in
turn another structure array whose third element is a simple scalar
structure.  The terminal scalar structure has a field which contains a
matrix value.

Note that the same result as in the above example could be achieved by:

@example
@group
@var{sa}.foo = 1;
@var{sa}(2).bar(3).baz(1,4) = 5
@end group
@end example
@xseealso{getfield, rmfield, orderfields, isfield, fieldnames, isstruct, struct}
@end deftypefn
substruct
@c substruct scripts/miscellaneous/substruct.m
@deftypefn {} {} substruct (@var{type}, @var{subs}, @dots{})
Create a subscript structure for use with @code{subsref} or @code{subsasgn}.

For example:

@example
@group
idx = substruct ("()", @{3, ":"@})
  @result{} idx =
       scalar structure containing the fields:
         type = ()
         subs =
         @{
           [1,1] =  3
           [1,2] = :
         @}
x = [1, 2, 3;
     4, 5, 6;
     7, 8, 9];
subsref (x, idx)
  @result{}   7   8   9
@end group
@end example
@xseealso{subsref, subsasgn}
@end deftypefn
swapbytes
@c swapbytes scripts/miscellaneous/swapbytes.m
@deftypefn {} {} swapbytes (@var{x})
Swap the byte order on values, converting from little endian to big endian
and vice versa.

For example:

@example
@group
swapbytes (uint16 (1:4))
@result{}   256   512   768  1024
@end group
@end example

@xseealso{typecast, cast}
@end deftypefn
symvar
@c symvar scripts/miscellaneous/symvar.m
@deftypefn {} {@var{vars} =} symvar (@var{str})
Identify the symbolic variable names in the string @var{str}.

Common constant names such as @code{i}, @code{j}, @code{pi}, @code{Inf} and
Octave functions such as @code{sin} or @code{plot} are ignored.

Any names identified are returned in a cell array of strings.  The array is
empty if no variables were found.

Example:

@example
@group
symvar ("x^2 + y^2 == 4")
@result{} @{
     [1,1] = x
     [2,1] = y
   @}
@end group
@end example
@end deftypefn
tar
@c tar scripts/miscellaneous/tar.m
@deftypefn  {} {@var{filelist} =} tar (@var{tarfile}, @var{files})
@deftypefnx {} {@var{filelist} =} tar (@var{tarfile}, @var{files}, @var{rootdir})
Pack the list of files and directories specified in @var{files} into the
TAR archive @var{tarfile}.

@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.
Directories are recursively traversed and all files are added to the
archive.

If @var{rootdir} is defined then any files without absolute pathnames are
located relative to @var{rootdir} rather than the current directory.

The optional output @var{filelist} is a list of the files that were included
in the archive.
@xseealso{untar, unpack, bzip2, gzip, zip}
@end deftypefn
tempdir
@c tempdir scripts/miscellaneous/tempdir.m
@deftypefn {} {@var{dir} =} tempdir ()
Return the name of the host system's directory for temporary files.

The directory name is taken first from the environment variable
@env{TMPDIR}.  If that does not exist the system default returned by
@code{P_tmpdir} is used.
@xseealso{P_tmpdir, tempname, mkstemp, tmpfile}
@end deftypefn
unix
@c unix scripts/miscellaneous/unix.m
@deftypefn  {} {} unix ("@var{command}")
@deftypefnx {} {@var{status} =} unix ("@var{command}")
@deftypefnx {} {[@var{status}, @var{text}] =} unix ("@var{command}")
@deftypefnx {} {[@dots{}] =} unix ("@var{command}", "-echo")
Execute a system command if running under a Unix-like operating system,
otherwise do nothing.

Octave waits for the external command to finish before returning the exit
status of the program in @var{status} and any output in @var{text}.

When called with no output argument, or the @qcode{"-echo"} argument is
given, then @var{text} is also sent to standard output.
@xseealso{dos, system, isunix, ismac, ispc}
@end deftypefn
unpack
@c unpack scripts/miscellaneous/unpack.m
@deftypefn  {} {@var{files} =} unpack (@var{file})
@deftypefnx {} {@var{files} =} unpack (@var{file}, @var{dir})
@deftypefnx {} {@var{files} =} unpack (@var{file}, @var{dir}, @var{filetype})
Unpack the archive @var{file} based on its extension to the directory
@var{dir}.

If @var{file} is a list of strings, then each file is unpacked
individually.  Shell wildcards in the filename such as @samp{*} or
@samp{?} are accepted and expanded.

If @var{dir} is not specified or is empty (@code{[]}), it defaults to the
current directory.  If a directory is in the file list, then @var{filetype}
must also be specified.

The specific archive filetype is inferred from the extension of the file.
The @var{filetype} may also be specified directly using a string which
corresponds to a known extension.

Valid filetype extensions:

@table @code
@item  @nospell{bz}
@itemx @nospell{bz2}
bzip archive

@item @nospell{gz}
gzip archive

@item tar
tar archive

@item  tarbz
@itemx tarbz2
@itemx tbz
@itemx tbz2
tar + bzip archive

@item  targz
@itemx tgz
tar + gzip archive

@item z
compress archive

@item zip
zip archive
@end table

The optional return value is a list of @var{files} unpacked.
@xseealso{bunzip2, gunzip, unzip, untar, bzip2, gzip, zip, tar}
@end deftypefn
untar
@c untar scripts/miscellaneous/untar.m
@deftypefn  {} {} untar (@var{tarfile})
@deftypefnx {} {} untar (@var{tarfile}, @var{dir})
@deftypefnx {} {@var{filelist} =} untar (@dots{})
Unpack the TAR archive @var{tarfile}.

If @var{dir} is specified the files are unpacked in this directory rather
than the one where @var{tarfile} is located.

The optional output @var{filelist} is a list of the uncompressed files.
@xseealso{tar, unpack, bunzip2, gunzip, unzip}
@end deftypefn
unzip
@c unzip scripts/miscellaneous/unzip.m
@deftypefn  {} {} unzip (@var{zipfile})
@deftypefnx {} {} unzip (@var{zipfile}, @var{dir})
@deftypefnx {} {@var{filelist} =} unzip (@dots{})
Unpack the ZIP archive @var{zipfile}.

If @var{dir} is specified the files are unpacked in this directory rather
than the one where @var{zipfile} is located.

The optional output @var{filelist} is a list of the uncompressed files.
@xseealso{zip, unpack, bunzip2, gunzip, untar}
@end deftypefn
validateattributes
@c validateattributes scripts/miscellaneous/validateattributes.m
@deftypefn  {} {} validateattributes (@var{A}, @var{classes}, @var{attributes})
@deftypefnx {} {} validateattributes (@var{A}, @var{classes}, @var{attributes}, @var{arg_idx})
@deftypefnx {} {} validateattributes (@var{A}, @var{classes}, @var{attributes}, @var{func_name})
@deftypefnx {} {} validateattributes (@var{A}, @var{classes}, @var{attributes}, @var{func_name}, @var{arg_name})
@deftypefnx {} {} validateattributes (@var{A}, @var{classes}, @var{attributes}, @var{func_name}, @var{arg_name}, @var{arg_idx})
Check validity of input argument.

Confirms that the argument @var{A} is valid by belonging to one of
@var{classes}, and holding all of the @var{attributes}.  If it does not,
an error is thrown, with a message formatted accordingly.  The error
message can be made further complete by the function name @var{fun_name},
the argument name @var{arg_name}, and its position in the input
@var{arg_idx}.

@var{classes} must be a cell array of strings (an empty cell array is
allowed) with the name of classes (remember that a class name is case
sensitive).  In addition to the class name, the following categories
names are also valid:

@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

@var{attributes} must be a cell array with names of checks for @var{A}.
Some of them require an additional value to be supplied right after the
name (see details for each below).

@table @asis
@item @qcode{"<="}
All values are less than or equal to the following value in
@var{attributes}.

@item @qcode{"<"}
All values are less than the following value in @var{attributes}.

@item @qcode{">="}
All values are greater than or equal to the following value in
@var{attributes}.

@item @qcode{">"}
All values are greater than the following value in @var{attributes}.

@item @qcode{"2d"}
A 2-dimensional matrix.  Note that vectors and empty matrices have
2 dimensions, one of them being of length 1, or both length 0.

@item @qcode{"3d"}
Has no more than 3 dimensions.  A 2-dimensional matrix is a 3-D matrix
whose 3rd dimension is of length 1.

@item @qcode{"binary"}
All values are either 1 or 0.

@item @qcode{"column"}
Values are arranged in a single column.

@item @qcode{"decreasing"}
No value is @var{NaN}, and each is less than the preceding one.

@item @qcode{"diag"}
Value is a diagonal matrix.

@item @qcode{"even"}
All values are even numbers.

@item @qcode{"finite"}
All values are finite.

@item @qcode{"increasing"}
No value is @var{NaN}, and each is greater than the preceding one.

@item @qcode{"integer"}
All values are integer.  This is different than using @code{isinteger}
which only checks its an integer type.  This checks that each value in
@var{A} is an integer value, i.e., it has no decimal part.

@item @qcode{"ncols"}
Has exactly as many columns as the next value in @var{attributes}.

@item @qcode{"ndims"}
Has exactly as many dimensions as the next value in @var{attributes}.

@item @qcode{"nondecreasing"}
No value is @var{NaN}, and each is greater than or equal to the preceding
one.

@item @qcode{"nonempty"}
It is not empty.

@item @qcode{"nonincreasing"}
No value is @var{NaN}, and each is less than or equal to the preceding one.

@item @qcode{"nonnan"}
No value is a @code{NaN}.

@item @nospell{@qcode{"nonnegative"}}
All values are non negative.

@item @qcode{"nonsparse"}
It is not a sparse matrix.

@item @qcode{"nonzero"}
No value is zero.

@item @qcode{"nrows"}
Has exactly as many rows as the next value in @var{attributes}.

@item @qcode{"numel"}
Has exactly as many elements as the next value in @var{attributes}.

@item @qcode{"odd"}
All values are odd numbers.

@item @qcode{"positive"}
All values are positive.

@item @qcode{"real"}
It is a non-complex matrix.

@item @qcode{"row"}
Values are arranged in a single row.

@item @qcode{"scalar"}
It is a scalar.

@item @qcode{"size"}
Its size has length equal to the values of the next in @var{attributes}.
The next value must is an array with the length for each dimension.  To
ignore the check for a certain dimension, the value of @code{NaN} can be
used.

@item @qcode{"square"}
Is a square matrix.

@item @qcode{"vector"}
Values are arranged in a single vector (column or vector).

@end table

@xseealso{isa, validatestring, inputParser}
@end deftypefn
ver
@c ver scripts/miscellaneous/ver.m
@deftypefn  {} {} ver
@deftypefnx {} {} ver Octave
@deftypefnx {} {} ver @var{package}
@deftypefnx {} {v =} ver (@dots{})

Display a header containing the current Octave version number, license
string, and operating system.  The header is followed by a list of installed
packages, versions, and installation directories.

Use the package name @var{package} or Octave to limit the listing to a
desired component.

When called with an output argument, return a vector of structures
describing Octave and each installed package.  The structure includes the
following fields.

@table @code
@item Name
Package name.

@item Version
Version of the package.

@item Release
Release of the package.

@item Date
Date of the version/release.
@end table

@xseealso{version, usejava, pkg}
@end deftypefn
version
@c version scripts/miscellaneous/version.m
@deftypefn  {} {@var{v} =} version ()
@deftypefnx {} {[@var{v}, @var{d}] =} version ()
@deftypefnx {} {@var{v} =} version (@var{feature})
Get version information for Octave.

If called without input argument, the first return value @var{v} gives the
version number of Octave as a string.  The second return value @var{d} holds
the release date as a string.

The following options can be passed for @var{feature}:

@table @asis
@item @qcode{"-date"}
for the release date of the running build,

@item @qcode{"-description"}
for a description of the release (always an empty string),

@item @qcode{"-release"}
for the name of the running build (always an empty string),

@item @qcode{"-java"}
for version information of the Java @nospell{VM},

@item @qcode{"-fftw"}
for version information for the linked @sc{fftw},

@item @qcode{"-blas"}
for version information for the linked @sc{blas},

@item @qcode{"-lapack"}
for version information for the linked @sc{lapack}.

@item @qcode{"-hgid"}
the mercurial ID of the sources used to build Octave.
@end table

The variant with no input and output argument is an alias for the function
@w{@env{OCTAVE_VERSION}} provided for compatibility.
@xseealso{OCTAVE_VERSION, ver}
@end deftypefn
what
@c what scripts/miscellaneous/what.m
@deftypefn  {} {} what
@deftypefnx {} {} what @var{dir}
@deftypefnx {} {w =} what (@var{dir})
List the Octave specific files in directory @var{dir}.

If @var{dir} is not specified then the current directory is used.

If a return argument is requested, the files found are returned in the
structure @var{w}.  The structure contains the following fields:

@table @asis
@item path
Full path to directory @var{dir}

@item m
Cell array of m-files

@item mat
Cell array of mat files

@item mex
Cell array of mex files

@item oct
Cell array of oct files

@item mdl
Cell array of mdl files

@item slx
Cell array of slx files

@item p
Cell array of p-files

@item classes
Cell array of class directories (@file{@@@var{classname}/})

@item packages
Cell array of package directories (@file{+@var{pkgname}/})
@end table

Compatibility Note: Octave does not support mdl, slx, and p files; nor does
it support package directories.  @code{what} will always return an empty
list for these categories.
@xseealso{which, ls, exist}
@end deftypefn
zip
@c zip scripts/miscellaneous/zip.m
@deftypefn  {} {@var{filelist} =} zip (@var{zipfile}, @var{files})
@deftypefnx {} {@var{filelist} =} zip (@var{zipfile}, @var{files}, @var{rootdir})
Compress the list of files and directories specified in @var{files} into the
ZIP archive @var{zipfile}.

@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.  Directories are recursively traversed and all files are
compressed and added to the archive.

If @var{rootdir} is defined then any files without absolute pathnames are
located relative to @var{rootdir} rather than the current directory.

The optional output @var{filelist} is a list of the files that were included
in the archive.
@xseealso{unzip, unpack, bzip2, gzip, tar}
@end deftypefn
decic
@c decic scripts/ode/decic.m
@deftypefn  {} {[@var{y0_new}, @var{yp0_new}] =} decic (@var{fun}, @var{t0}, @var{y0}, @var{fixed_y0}, @var{yp0}, @var{fixed_yp0})
@deftypefnx {} {[@var{y0_new}, @var{yp0_new}] =} decic (@var{fun}, @var{t0}, @var{y0}, @var{fixed_y0}, @var{yp0}, @var{fixed_yp0}, @var{options})
@deftypefnx {} {[@var{y0_new}, @var{yp0_new}, @var{resnorm}] =} decic (@dots{})

Compute consistent implicit ODE initial conditions @var{y0_new} and
@var{yp0_new} given initial guesses @var{y0} and @var{yp0}.

A maximum of @code{length (@var{y0})} components between @var{fixed_y0} and
@var{fixed_yp0} may be chosen as fixed values.

@var{fun} is a function handle.  The function must accept three inputs where
the first is time @var{t}, the second is a column vector of unknowns
@var{y}, and the third is a column vector of unknowns @var{yp}.

@var{t0} is the initial time such that
@code{@var{fun}(@var{t0}, @var{y0_new}, @var{yp0_new}) = 0}, specified as a
scalar.

@var{y0} is a vector used as the initial guess for @var{y}.

@var{fixed_y0} is a vector which specifies the components of @var{y0} to
hold fixed.  Choose a maximum of @code{length (@var{y0})} components between
@var{fixed_y0} and @var{fixed_yp0} as fixed values.
Set @var{fixed_y0}(i) component to 1 if you want to fix the value of
@var{y0}(i).
Set @var{fixed_y0}(i) component to 0 if you want to allow the value of
@var{y0}(i) to change.

@var{yp0} is a vector used as the initial guess for @var{yp}.

@var{fixed_yp0} is a vector which specifies the components of @var{yp0} to
hold fixed.  Choose a maximum of @code{length (@var{yp0})} components
between @var{fixed_y0} and @var{fixed_yp0} as fixed values.
Set @var{fixed_yp0}(i) component to 1 if you want to fix the value of
@var{yp0}(i).
Set @var{fixed_yp0}(i) component to 0 if you want to allow the value of
@var{yp0}(i) to change.

The optional seventh argument @var{options} is a structure array.  Use
@code{odeset} to generate this structure.  The relevant options are
@code{RelTol} and @code{AbsTol} which specify the error thresholds used to
compute the initial conditions.

The function typically returns two outputs.  Variable @var{y0_new} is a
column vector and contains the consistent initial value of @var{y}.  The
output @var{yp0_new} is a column vector and contains the consistent initial
value of @var{yp}.

The optional third output @var{resnorm} is the norm of the vector of
residuals.  If @var{resnorm} is small, @code{decic} has successfully
computed the initial conditions.  If the value of @var{resnorm} is large,
use @code{RelTol} and @code{AbsTol} to adjust it.

Example: Compute initial conditions for @nospell{Robertson's} equations:

@smallexample
@group
function r = robertson_dae (@var{t}, @var{y}, @var{yp})
  r = [ -(@var{yp}(1) + 0.04*@var{y}(1) - 1e4*@var{y}(2)*@var{y}(3))
        -(@var{yp}(2) - 0.04*@var{y}(1) + 1e4*@var{y}(2)*@var{y}(3) + 3e7*@var{y}(2)^2)
@var{y}(1) + @var{y}(2) + @var{y}(3) - 1 ];
endfunction
@end group
[@var{y0_new},@var{yp0_new}] = decic (@@robertson_dae, 0, [1; 0; 0], [1; 1; 0],
[-1e-4; 1; 0], [0; 0; 0]);
@end smallexample
@xseealso{ode15i, odeset}
@end deftypefn
ode15i
@c ode15i scripts/ode/ode15i.m
@deftypefn  {} {[@var{t}, @var{y}] =} ode15i (@var{fun}, @var{trange}, @var{y0}, @var{yp0})
@deftypefnx {} {[@var{t}, @var{y}] =} ode15i (@var{fun}, @var{trange}, @var{y0}, @var{yp0}, @var{ode_opt})
@deftypefnx {} {[@var{t}, @var{y}, @var{te}, @var{ye}, @var{ie}] =} ode15i (@dots{})
@deftypefnx {} {@var{solution} =} ode15i (@dots{})
@deftypefnx {} {} ode15i (@dots{})
Solve a set of fully-implicit Ordinary Differential Equations (ODEs) or
index 1 Differential Algebraic Equations (DAEs).

@code{ode15i} uses a variable step, variable order BDF (Backward
Differentiation Formula) method that ranges from order 1 to 5.

@var{fun} is a function handle, inline function, or string containing the
name of the function that defines the ODE: @code{0 = f(t,y,yp)}.  The
function must accept three inputs where the first is time @var{t}, the
second is the function value @var{y} (a column vector), and the third
is the derivative value @var{yp} (a column vector).

@var{trange} specifies the time interval over which the ODE will be
evaluated.  Typically, it is a two-element vector specifying the initial and
final times (@code{[tinit, tfinal]}).  If there are more than two elements
then the solution will also be evaluated at these intermediate time
instances.

@var{y0} and @var{yp0} contain the initial values for the unknowns @var{y}
and @var{yp}.  If they are row vectors then the solution @var{y} will be a
matrix in which each column is the solution for the corresponding initial
value in @var{y0} and @var{yp0}.

@var{y0} and @var{yp0} must be consistent initial conditions, meaning that
@code{f(t,y0,yp0) = 0} is satisfied.  The function @code{decic} may be used
to compute consistent initial conditions given initial guesses.

The optional fifth argument @var{ode_opt} specifies non-default options to
the ODE solver.  It is a structure generated by @code{odeset}.

The function typically returns two outputs.  Variable @var{t} is a
column vector and contains the times where the solution was found.  The
output @var{y} is a matrix in which each column refers to a different
unknown of the problem and each row corresponds to a time in @var{t}.

The output can also be returned as a structure @var{solution} which has a
field @var{x} containing a row vector of times where the solution was
evaluated and a field @var{y} containing the solution matrix such that each
column corresponds to a time in @var{x}.  Use
@w{@code{fieldnames (@var{solution})}} to see the other fields and
additional information returned.

If no output arguments are requested, and no @code{OutputFcn} is specified
in @var{ode_opt}, then the @code{OutputFcn} is set to @code{odeplot} and the
results of the solver are plotted immediately.

If using the @qcode{"Events"} option then three additional outputs may be
returned.  @var{te} holds the time when an Event function returned a zero.
@var{ye} holds the value of the solution at time @var{te}.  @var{ie}
contains an index indicating which Event function was triggered in the case
of multiple Event functions.

Example: Solve @nospell{Robertson's} equations:

@smallexample
@group
function r = robertson_dae (@var{t}, @var{y}, @var{yp})
  r = [ -(@var{yp}(1) + 0.04*@var{y}(1) - 1e4*@var{y}(2)*@var{y}(3))
        -(@var{yp}(2) - 0.04*@var{y}(1) + 1e4*@var{y}(2)*@var{y}(3) + 3e7*@var{y}(2)^2)
@var{y}(1) + @var{y}(2) + @var{y}(3) - 1 ];
endfunction
[@var{t},@var{y}] = ode15i (@@robertson_dae, [0, 1e3], [1; 0; 0], [-1e-4; 1e-4; 0]);
@end group
@end smallexample
@xseealso{decic, odeset, odeget}
@end deftypefn
ode15s
@c ode15s scripts/ode/ode15s.m
@deftypefn  {} {[@var{t}, @var{y}] =} ode15s (@var{fun}, @var{trange}, @var{y0})
@deftypefnx {} {[@var{t}, @var{y}] =} ode15s (@var{fun}, @var{trange}, @var{y0}, @var{ode_opt})
@deftypefnx {} {[@var{t}, @var{y}, @var{te}, @var{ye}, @var{ie}] =} ode15s (@dots{})
@deftypefnx {} {@var{solution} =} ode15s (@dots{})
@deftypefnx {} {} ode15s (@dots{})
Solve a set of stiff Ordinary Differential Equations (ODEs) or stiff
semi-explicit index 1 Differential Algebraic Equations (DAEs).

@code{ode15s} uses a variable step, variable order BDF (Backward
Differentiation Formula) method that ranges from order 1 to 5.

@var{fun} is a function handle, inline function, or string containing the
name of the function that defines the ODE: @code{y' = f(t,y)}.  The function
must accept two inputs where the first is time @var{t} and the second is a
column vector of unknowns @var{y}.

@var{trange} specifies the time interval over which the ODE will be
evaluated.  Typically, it is a two-element vector specifying the initial and
final times (@code{[tinit, tfinal]}).  If there are more than two elements
then the solution will also be evaluated at these intermediate time
instances.

@var{init} contains the initial value for the unknowns.  If it is a row
vector then the solution @var{y} will be a matrix in which each column is
the solution for the corresponding initial value in @var{init}.

The optional fourth argument @var{ode_opt} specifies non-default options to
the ODE solver.  It is a structure generated by @code{odeset}.

The function typically returns two outputs.  Variable @var{t} is a
column vector and contains the times where the solution was found.  The
output @var{y} is a matrix in which each column refers to a different
unknown of the problem and each row corresponds to a time in @var{t}.

The output can also be returned as a structure @var{solution} which has a
field @var{x} containing a row vector of times where the solution was
evaluated and a field @var{y} containing the solution matrix such that each
column corresponds to a time in @var{x}.  Use
@w{@code{fieldnames (@var{solution})}} to see the other fields and
additional information returned.

If no output arguments are requested, and no @code{OutputFcn} is specified
in @var{ode_opt}, then the @code{OutputFcn} is set to @code{odeplot} and the
results of the solver are plotted immediately.

If using the @qcode{"Events"} option then three additional outputs may be
returned.  @var{te} holds the time when an Event function returned a zero.
@var{ye} holds the value of the solution at time @var{te}.  @var{ie}
contains an index indicating which Event function was triggered in the case
of multiple Event functions.

Example: Solve @nospell{Robertson's} equations:

@smallexample
@group
function r = robertson_dae (@var{t}, @var{y})
  r = [ -0.04*@var{y}(1) + 1e4*@var{y}(2)*@var{y}(3)
         0.04*@var{y}(1) - 1e4*@var{y}(2)*@var{y}(3) - 3e7*@var{y}(2)^2
@var{y}(1) + @var{y}(2) + @var{y}(3) - 1 ];
endfunction
opt = odeset ("Mass", [1 0 0; 0 1 0; 0 0 0], "MStateDependence", "none");
[@var{t},@var{y}] = ode15s (@@robertson_dae, [0, 1e3], [1; 0; 0], opt);
@end group
@end smallexample
@xseealso{decic, odeset, odeget, ode23, ode45}
@end deftypefn
ode23
@c ode23 scripts/ode/ode23.m
@deftypefn  {} {[@var{t}, @var{y}] =} ode23 (@var{fun}, @var{trange}, @var{init})
@deftypefnx {} {[@var{t}, @var{y}] =} ode23 (@var{fun}, @var{trange}, @var{init}, @var{ode_opt})
@deftypefnx {} {[@var{t}, @var{y}, @var{te}, @var{ye}, @var{ie}] =} ode23 (@dots{})
@deftypefnx {} {@var{solution} =} ode23 (@dots{})
@deftypefnx {} {} ode23 (@dots{})

Solve a set of non-stiff Ordinary Differential Equations (non-stiff ODEs)
with the well known explicit @nospell{Bogacki-Shampine} method of order 3.

@var{fun} is a function handle, inline function, or string containing the
name of the function that defines the ODE: @code{y' = f(t,y)}.  The function
must accept two inputs where the first is time @var{t} and the second is a
column vector of unknowns @var{y}.

@var{trange} specifies the time interval over which the ODE will be
evaluated.  Typically, it is a two-element vector specifying the initial and
final times (@code{[tinit, tfinal]}).  If there are more than two elements
then the solution will also be evaluated at these intermediate time
instances.

By default, @code{ode23} uses an adaptive timestep with the
@code{integrate_adaptive} algorithm.  The tolerance for the timestep
computation may be changed by using the options @qcode{"RelTol"} and
@qcode{"AbsTol"}.

@var{init} contains the initial value for the unknowns.  If it is a row
vector then the solution @var{y} will be a matrix in which each column is
the solution for the corresponding initial value in @var{init}.

The optional fourth argument @var{ode_opt} specifies non-default options to
the ODE solver.  It is a structure generated by @code{odeset}.

The function typically returns two outputs.  Variable @var{t} is a
column vector and contains the times where the solution was found.  The
output @var{y} is a matrix in which each column refers to a different
unknown of the problem and each row corresponds to a time in @var{t}.

The output can also be returned as a structure @var{solution} which has a
field @var{x} containing a row vector of times where the solution was
evaluated and a field @var{y} containing the solution matrix such that each
column corresponds to a time in @var{x}.  Use
@w{@code{fieldnames (@var{solution})}} to see the other fields and
additional information returned.

If no output arguments are requested, and no @code{OutputFcn} is specified
in @var{ode_opt}, then the @code{OutputFcn} is set to @code{odeplot} and the
results of the solver are plotted immediately.

If using the @qcode{"Events"} option then three additional outputs may be
returned.  @var{te} holds the time when an Event function returned a zero.
@var{ye} holds the value of the solution at time @var{te}.  @var{ie}
contains an index indicating which Event function was triggered in the case
of multiple Event functions.

Example: Solve the @nospell{Van der Pol} equation

@example
@group
fvdp = @@(@var{t},@var{y}) [@var{y}(2); (1 - @var{y}(1)^2) * @var{y}(2) - @var{y}(1)];
[@var{t},@var{y}] = ode23 (fvdp, [0, 20], [2, 0]);
@end group
@end example

Reference: For the definition of this method see
@url{https://en.wikipedia.org/wiki/List_of_Runge%E2%80%93Kutta_methods}.
@xseealso{odeset, odeget, ode45, ode15s}
@end deftypefn
ode45
@c ode45 scripts/ode/ode45.m
@deftypefn  {} {[@var{t}, @var{y}] =} ode45 (@var{fun}, @var{trange}, @var{init})
@deftypefnx {} {[@var{t}, @var{y}] =} ode45 (@var{fun}, @var{trange}, @var{init}, @var{ode_opt})
@deftypefnx {} {[@var{t}, @var{y}, @var{te}, @var{ye}, @var{ie}] =} ode45 (@dots{})
@deftypefnx {} {@var{solution} =} ode45 (@dots{})
@deftypefnx {} {} ode45 (@dots{})

Solve a set of non-stiff Ordinary Differential Equations (non-stiff ODEs)
with the well known explicit @nospell{Dormand-Prince} method of order 4.

@var{fun} is a function handle, inline function, or string containing the
name of the function that defines the ODE: @code{y' = f(t,y)}.  The function
must accept two inputs where the first is time @var{t} and the second is a
column vector of unknowns @var{y}.

@var{trange} specifies the time interval over which the ODE will be
evaluated.  Typically, it is a two-element vector specifying the initial and
final times (@code{[tinit, tfinal]}).  If there are more than two elements
then the solution will also be evaluated at these intermediate time
instances.

By default, @code{ode45} uses an adaptive timestep with the
@code{integrate_adaptive} algorithm.  The tolerance for the timestep
computation may be changed by using the options @qcode{"RelTol"} and
@qcode{"AbsTol"}.

@var{init} contains the initial value for the unknowns.  If it is a row
vector then the solution @var{y} will be a matrix in which each column is
the solution for the corresponding initial value in @var{init}.

The optional fourth argument @var{ode_opt} specifies non-default options to
the ODE solver.  It is a structure generated by @code{odeset}.

The function typically returns two outputs.  Variable @var{t} is a
column vector and contains the times where the solution was found.  The
output @var{y} is a matrix in which each column refers to a different
unknown of the problem and each row corresponds to a time in @var{t}.

The output can also be returned as a structure @var{solution} which has a
field @var{x} containing a row vector of times where the solution was
evaluated and a field @var{y} containing the solution matrix such that each
column corresponds to a time in @var{x}.  Use
@w{@code{fieldnames (@var{solution})}} to see the other fields and
additional information returned.

If no output arguments are requested, and no @code{OutputFcn} is specified
in @var{ode_opt}, then the @code{OutputFcn} is set to @code{odeplot} and the
results of the solver are plotted immediately.

If using the @qcode{"Events"} option then three additional outputs may be
returned.  @var{te} holds the time when an Event function returned a zero.
@var{ye} holds the value of the solution at time @var{te}.  @var{ie}
contains an index indicating which Event function was triggered in the case
of multiple Event functions.

Example: Solve the @nospell{Van der Pol} equation

@example
@group
fvdp = @@(@var{t},@var{y}) [@var{y}(2); (1 - @var{y}(1)^2) * @var{y}(2) - @var{y}(1)];
[@var{t},@var{y}] = ode45 (fvdp, [0, 20], [2, 0]);
@end group
@end example
@xseealso{odeset, odeget, ode23, ode15s}
@end deftypefn
odeget
@c odeget scripts/ode/odeget.m
@deftypefn  {} {@var{val} =} odeget (@var{ode_opt}, @var{field})
@deftypefnx {} {@var{val} =} odeget (@var{ode_opt}, @var{field}, @var{default})

Query the value of the property @var{field} in the ODE options structure
@var{ode_opt}.

If called with two input arguments and the first input argument
@var{ode_opt} is an ODE option structure and the second input argument
@var{field} is a string specifying an option name, then return the option
value @var{val} corresponding to @var{field} from @var{ode_opt}.

If called with an optional third input argument, and @var{field} is
not set in the structure @var{ode_opt}, then return the default value
@var{default} instead.
@xseealso{odeset}
@end deftypefn
odeplot
@c odeplot scripts/ode/odeplot.m
@deftypefn {} {@var{stop_solve} =} odeplot (@var{t}, @var{y}, @var{flag})

Open a new figure window and plot the solution of an ode problem at each
time step during the integration.

The types and values of the input parameters @var{t} and @var{y} depend on
the input @var{flag} that is of type string.  Valid values of @var{flag}
are:

@table @option
@item @qcode{"init"}
The input @var{t} must be a column vector of length 2 with the first and
last time step (@code{[@var{tfirst} @var{tlast}]}.  The input @var{y}
contains the initial conditions for the ode problem (@var{y0}).

@item @qcode{""}
The input @var{t} must be a scalar double specifying the time for which
the solution in input @var{y} was calculated.

@item @qcode{"done"}
The inputs should be empty, but are ignored if they are present.
@end table

@code{odeplot} always returns false, i.e., don't stop the ode solver.

Example: solve an anonymous implementation of the
@nospell{@qcode{"Van der Pol"}} equation and display the results while
solving.

@example
@group
fvdp = @@(t,y) [y(2); (1 - y(1)^2) * y(2) - y(1)];

opt = odeset ("OutputFcn", @@odeplot, "RelTol", 1e-6);
sol = ode45 (fvdp, [0 20], [2 0], opt);
@end group
@end example

Background Information:
This function is called by an ode solver function if it was specified in
the @qcode{"OutputFcn"} property of an options structure created with
@code{odeset}.  The ode solver will initially call the function with the
syntax @code{odeplot ([@var{tfirst}, @var{tlast}], @var{y0}, "init")}.  The
function initializes internal variables, creates a new figure window, and
sets the x limits of the plot.  Subsequently, at each time step during the
integration the ode solver calls @code{odeplot (@var{t}, @var{y}, [])}.
At the end of the solution the ode solver calls
@code{odeplot ([], [], "done")} so that odeplot can perform any clean-up
actions required.
@xseealso{odeset, odeget, ode23, ode45}
@end deftypefn
odeset
@c odeset scripts/ode/odeset.m
@deftypefn  {} {@var{odestruct} =} odeset ()
@deftypefnx {} {@var{odestruct} =} odeset (@var{"field1"}, @var{value1}, @var{"field2"}, @var{value2}, @dots{})
@deftypefnx {} {@var{odestruct} =} odeset (@var{oldstruct}, @var{"field1"}, @var{value1}, @var{"field2"}, @var{value2}, @dots{})
@deftypefnx {} {@var{odestruct} =} odeset (@var{oldstruct}, @var{newstruct})
@deftypefnx {} {} odeset ()

Create or modify an ODE options structure.

When called with no input argument and one output argument, return a new ODE
options structure that contains all possible fields initialized to their
default values.  If no output argument is requested, display a list of
the common ODE solver options along with their default value.

If called with name-value input argument pairs @var{"field1"},
@var{"value1"}, @var{"field2"}, @var{"value2"}, @dots{} return a new
ODE options structure with all the most common option fields
initialized, @strong{and} set the values of the fields @var{"field1"},
@var{"field2"}, @dots{} to the values @var{value1}, @var{value2},
@dots{}.

If called with an input structure @var{oldstruct} then overwrite the
values of the options @var{"field1"}, @var{"field2"}, @dots{} with
new values @var{value1}, @var{value2}, @dots{} and return the
modified structure.

When called with two input ODE options structures @var{oldstruct} and
@var{newstruct} overwrite all values from the structure
@var{oldstruct} with new values from the structure @var{newstruct}.
Empty values in @var{newstruct} will not overwrite values in
@var{oldstruct}.

The most commonly used ODE options, which are always assigned a value
by @code{odeset}, are the following:

@table @asis
@item @code{AbsTol}: positive scalar | vector, def. @code{1e-6}
Absolute error tolerance.

@item @code{BDF}: @{@qcode{"off"}@} | @qcode{"on"}
Use BDF formulas in implicit multistep methods.
@emph{Note}: This option is not yet implemented.

@item @code{Events}: function_handle
Event function.  An event function must have the form
@code{[value, isterminal, direction] = my_events_f (t, y)}

@item @code{InitialSlope}: vector
Consistent initial slope vector for DAE solvers.

@item @code{InitialStep}: positive scalar
Initial time step size.

@item @code{Jacobian}: matrix | function_handle
Jacobian matrix, specified as a constant matrix or a function of
time and state.

@item @code{JConstant}: @{@qcode{"off"}@} | @qcode{"on"}
Specify whether the Jacobian is a constant matrix or depends on the
state.

@item @code{JPattern}: sparse matrix
If the Jacobian matrix is sparse and non-constant but maintains a
constant sparsity pattern, specify the sparsity pattern.

@item @code{Mass}: matrix | function_handle
Mass matrix, specified as a constant matrix or a function of
time and state.

@item @code{MassSingular}: @{@qcode{"maybe"}@} | @qcode{"yes"} | @qcode{"on"}
Specify whether the mass matrix is singular.

@item @code{MaxOrder}: @{@qcode{5}@} | @qcode{4} | @qcode{3} | @qcode{2} | @qcode{1}
Maximum order of formula.

@item @code{MaxStep}: positive scalar
Maximum time step value.

@item @code{MStateDependence}: @{@qcode{"weak"}@} | @qcode{"none"} | @qcode{"strong"}
Specify whether the mass matrix depends on the state or only on time.

@item @code{MvPattern}: sparse matrix
If the mass matrix is sparse and non-constant but maintains a
constant sparsity pattern, specify the sparsity pattern.
@emph{Note}: This option is not yet implemented.

@item @code{NonNegative}: scalar | vector
Specify elements of the state vector that are expected to remain
non-negative during the simulation.

@item @code{NormControl}: @{@qcode{"off"}@} | @qcode{"on"}
Control error relative to the 2-norm of the solution, rather than its
absolute value.

@item @code{OutputFcn}: function_handle
Function to monitor the state during the simulation.  For the form of
the function to use see @code{odeplot}.

@item @code{OutputSel}: scalar | vector
Indices of elements of the state vector to be passed to the output
monitoring function.

@item @code{Refine}: positive scalar
Specify whether output should be returned only at the end of each
time step or also at intermediate time instances.  The value should be
a scalar indicating the number of equally spaced time points to use
within each timestep at which to return output.
@emph{Note}: This option is not yet implemented.

@item @code{RelTol}: positive scalar
Relative error tolerance.

@item @code{Stats}: @{@qcode{"off"}@} | @qcode{"on"}
Print solver statistics after simulation.

@item @code{Vectorized}: @{@qcode{"off"}@} | @qcode{"on"}
Specify whether @code{odefun} can be passed multiple values of the
state at once.

@end table

Field names that are not in the above list are also accepted and
added to the result structure.

@xseealso{odeget}
@end deftypefn
__all_opts__
@c __all_opts__ scripts/optimization/__all_opts__.m
@deftypefn {} {@var{names} =} __all_opts__ (@dots{})
Internal function.

Query all options from all known optimization functions and return a
list of possible values.
@end deftypefn
fminbnd
@c fminbnd scripts/optimization/fminbnd.m
@deftypefn  {} {@var{x} =} fminbnd (@var{fun}, @var{a}, @var{b})
@deftypefnx {} {@var{x} =} fminbnd (@var{fun}, @var{a}, @var{b}, @var{options})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fminbnd (@dots{})
Find a minimum point of a univariate function.

@var{fun} must be a function handle or name.

The starting interval is specified by @var{a} (left boundary) and @var{b}
(right boundary).  The endpoints must be finite.

@var{options} is a structure specifying additional parameters which
control the algorithm.  Currently, @code{fminbnd} recognizes these options:
@qcode{"Display"}, @qcode{"FunValCheck"}, @qcode{"MaxFunEvals"},
@qcode{"MaxIter"}, @qcode{"OutputFcn"}, @qcode{"TolX"}.

@qcode{"MaxFunEvals"} proscribes the maximum number of function evaluations
before optimization is halted.  The default value is 500.
The value must be a positive integer.

@qcode{"MaxIter"} proscribes the maximum number of algorithm iterations
before optimization is halted.  The default value is 500.
The value must be a positive integer.

@qcode{"TolX"} specifies the termination tolerance for the solution @var{x}.
The default is @code{1e-4}.

For a description of the other options, see @ref{XREFoptimset,,optimset}.
To initialize an options structure with default values for @code{fminbnd}
use @code{options = optimset ("fminbnd")}.

On exit, the function returns @var{x}, the approximate minimum point, and
@var{fval}, the function evaluated @var{x}.

The third output @var{info} reports whether the algorithm succeeded and may
take one of the following values:

@itemize
@item 1
The algorithm converged to a solution.

@item 0
Iteration limit (either @code{MaxIter} or @code{MaxFunEvals}) exceeded.

@item -1
The algorithm was terminated by a user @code{OutputFcn}.
@end itemize

Programming Notes: The search for a minimum is restricted to be in the
finite interval bound by @var{a} and @var{b}.  If you have only one initial
point to begin searching from then you will need to use an unconstrained
minimization algorithm such as @code{fminunc} or @code{fminsearch}.
@code{fminbnd} internally uses a Golden Section search strategy.
@xseealso{fzero, fminunc, fminsearch, optimset}
@end deftypefn
fminsearch
@c fminsearch scripts/optimization/fminsearch.m
@deftypefn  {} {@var{x} =} fminsearch (@var{fun}, @var{x0})
@deftypefnx {} {@var{x} =} fminsearch (@var{fun}, @var{x0}, @var{options})
@deftypefnx {} {@var{x} =} fminsearch (@var{problem})
@deftypefnx {} {[@var{x}, @var{fval}, @var{exitflag}, @var{output}] =} fminsearch (@dots{})

Find a value of @var{x} which minimizes the multi-variable function
@var{fun}.

The search begins at the point @var{x0} and iterates using the
@nospell{Nelder & Mead} Simplex algorithm (a derivative-free method).  This
algorithm is better-suited to functions which have discontinuities or for
which a gradient-based search such as @code{fminunc} fails.

Options for the search are provided in the parameter @var{options} using the
function @code{optimset}.  Currently, @code{fminsearch} accepts the options:
@qcode{"Display"}, @qcode{"FunValCheck"},@qcode{"MaxFunEvals"},
@qcode{"MaxIter"}, @qcode{"OutputFcn"}, @qcode{"TolFun"}, @qcode{"TolX"}.

@qcode{"MaxFunEvals"} proscribes the maximum number of function evaluations
before optimization is halted.  The default value is
@code{200 * number_of_variables}, i.e., @code{200 * length (@var{x0})}.
The value must be a positive integer.

@qcode{"MaxIter"} proscribes the maximum number of algorithm iterations
before optimization is halted.  The default value is
@code{200 * number_of_variables}, i.e., @code{200 * length (@var{x0})}.
The value must be a positive integer.

For a description of the other options, see @code{optimset}.  To initialize
an options structure with default values for @code{fminsearch} use
@code{options = optimset ("fminsearch")}.

@code{fminsearch} may also be called with a single structure argument
with the following fields:

@table @code
@item objective
The objective function.

@item x0
The initial point.

@item solver
Must be set to @qcode{"fminsearch"}.

@item options
A structure returned from @code{optimset} or an empty matrix to
indicate that defaults should be used.
@end table

@noindent
The field @code{options} is optional.  All others are required.

On exit, the function returns @var{x}, the minimum point, and @var{fval},
the function value at the minimum.

The third output @var{exitflag} reports whether the algorithm succeeded and
may take one of the following values:

@table @asis
@item 1
if the algorithm converged
(size of the simplex is smaller than @code{TolX} @strong{AND} the step in
function value between iterations is smaller than @code{TolFun}).

@item 0
if the maximum number of iterations or the maximum number of function
evaluations are exceeded.

@item -1
if the iteration is stopped by the @qcode{"OutputFcn"}.
@end table

The fourth output is a structure @var{output} containing runtime
about the algorithm.  Fields in the structure are @code{funcCount}
containing the number of function calls to @var{fun}, @code{iterations}
containing the number of iteration steps, @code{algorithm} with the name of
the search algorithm (always:
@nospell{@qcode{"Nelder-Mead simplex direct search"}}), and @code{message}
with the exit message.

Example:

@example
fminsearch (@@(x) (x(1)-5).^2+(x(2)-8).^4, [0;0])
@end example

Note: If you need to find the minimum of a single variable function it is
probably better to use @code{fminbnd}.
@xseealso{fminbnd, fminunc, optimset}
@end deftypefn
fminunc
@c fminunc scripts/optimization/fminunc.m
@deftypefn  {} {} fminunc (@var{fcn}, @var{x0})
@deftypefnx {} {} fminunc (@var{fcn}, @var{x0}, @var{options})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}, @var{grad}, @var{hess}] =} fminunc (@var{fcn}, @dots{})
Solve an unconstrained optimization problem defined by the function
@var{fcn}.

@var{fcn} should accept a vector (array) defining the unknown variables, and
return the objective function value, optionally with gradient.
@code{fminunc} attempts to determine a vector @var{x} such that
@code{@var{fcn} (@var{x})} is a local minimum.

@var{x0} determines a starting guess.  The shape of @var{x0} is preserved in
all calls to @var{fcn}, but otherwise is treated as a column vector.

@var{options} is a structure specifying additional parameters which
control the algorithm.  Currently, @code{fminunc} recognizes these options:
@qcode{"AutoScaling"}, @qcode{"FinDiffType"}, @qcode{"FunValCheck"},
@qcode{"GradObj"}, @qcode{"MaxFunEvals"}, @qcode{"MaxIter"},
@qcode{"OutputFcn"}, @qcode{"TolFun"}, @qcode{"TolX"}, @qcode{"TypicalX"}.

If @qcode{"AutoScaling"} is @qcode{"on"}, the variables will be
automatically scaled according to the column norms of the (estimated)
Jacobian.  As a result, @qcode{"TolFun"} becomes scaling-independent.  By
default, this option is @qcode{"off"} because it may sometimes deliver
unexpected (though mathematically correct) results.

If @qcode{"GradObj"} is @qcode{"on"}, it specifies that @var{fcn}---when
called with two output arguments---also returns the Jacobian matrix of
partial first derivatives at the requested point.

@qcode{"MaxFunEvals"} proscribes the maximum number of function evaluations
before optimization is halted.  The default value is
@code{100 * number_of_variables}, i.e., @code{100 * length (@var{x0})}.
The value must be a positive integer.

@qcode{"MaxIter"} proscribes the maximum number of algorithm iterations
before optimization is halted.  The default value is 400.
The value must be a positive integer.

@qcode{"TolX"} specifies the termination tolerance for the unknown variables
@var{x}, while @qcode{"TolFun"} is a tolerance for the objective function
value @var{fval}.  The default is @code{1e-6} for both options.

For a description of the other options, see @code{optimset}.

On return, @var{x} is the location of the minimum and @var{fval} contains
the value of the objective function at @var{x}.

@var{info} may be one of the following values:

@table @asis
@item 1
Converged to a solution point.  Relative gradient error is less than
specified by @code{TolFun}.

@item 2
Last relative step size was less than @code{TolX}.

@item 3
Last relative change in function value was less than @code{TolFun}.

@item 0
Iteration limit exceeded---either maximum number of algorithm iterations
@code{MaxIter} or maximum number of function evaluations @code{MaxFunEvals}.

@item -1
Algorithm terminated by @code{OutputFcn}.

@item -3
The trust region radius became excessively small.
@end table

Optionally, @code{fminunc} can return a structure with convergence
statistics (@var{output}), the output gradient (@var{grad}) at the
solution @var{x}, and approximate Hessian (@var{hess}) at the solution
@var{x}.

Application Notes: If the objective function is a single nonlinear equation
of one variable then using @code{fminbnd} is usually a better choice.

The algorithm used by @code{fminunc} is a gradient search which depends
on the objective function being differentiable.  If the function has
discontinuities it may be better to use a derivative-free algorithm such as
@code{fminsearch}.
@xseealso{fminbnd, fminsearch, optimset}
@end deftypefn
fsolve
@c fsolve scripts/optimization/fsolve.m
@deftypefn  {} {} fsolve (@var{fcn}, @var{x0})
@deftypefnx {} {} fsolve (@var{fcn}, @var{x0}, @var{options})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}, @var{fjac}] =} fsolve (@dots{})
Solve a system of nonlinear equations defined by the function @var{fcn}.

@var{fcn} should accept a vector (array) defining the unknown variables,
and return a vector of left-hand sides of the equations.  Right-hand sides
are defined to be zeros.  In other words, this function attempts to
determine a vector @var{x} such that @code{@var{fcn} (@var{x})} gives
(approximately) all zeros.

@var{x0} is an initial guess for the solution.  The shape of @var{x0} is
preserved in all calls to @var{fcn}, but otherwise is treated as a column
vector.

@var{options} is a structure specifying additional parameters which
control the algorithm.  Currently, @code{fsolve} recognizes these options:
@qcode{"AutoScaling"}, @qcode{"ComplexEqn"}, @qcode{"FinDiffType"},
@qcode{"FunValCheck"}, @qcode{"Jacobian"}, @qcode{"MaxFunEvals"},
@qcode{"MaxIter"}, @qcode{"OutputFcn"}, @qcode{"TolFun"}, @qcode{"TolX"},
@qcode{"TypicalX"}, and @qcode{"Updating"}.

If @qcode{"AutoScaling"} is @qcode{"on"}, the variables will be
automatically scaled according to the column norms of the (estimated)
Jacobian.  As a result, @qcode{"TolFun"} becomes scaling-independent.  By
default, this option is @qcode{"off"} because it may sometimes deliver
unexpected (though mathematically correct) results.

If @qcode{"ComplexEqn"} is @qcode{"on"}, @code{fsolve} will attempt to solve
complex equations in complex variables, assuming that the equations possess
a complex derivative (i.e., are holomorphic).  If this is not what you want,
you should unpack the real and imaginary parts of the system to get a real
system.

If @qcode{"Jacobian"} is @qcode{"on"}, it specifies that @var{fcn}---when
called with 2 output arguments---also returns the Jacobian matrix of
right-hand sides at the requested point.

@qcode{"MaxFunEvals"} proscribes the maximum number of function evaluations
before optimization is halted.  The default value is
@code{100 * number_of_variables}, i.e., @code{100 * length (@var{x0})}.
The value must be a positive integer.

If @qcode{"Updating"} is @qcode{"on"}, the function will attempt to use
@nospell{Broyden} updates to update the Jacobian, in order to reduce the
number of Jacobian calculations.  If your user function always calculates
the Jacobian (regardless of number of output arguments) then this option
provides no advantage and should be disabled.

@qcode{"TolX"} specifies the termination tolerance in the unknown variables,
while @qcode{"TolFun"} is a tolerance for equations.  Default is @code{1e-6}
for both @qcode{"TolX"} and @qcode{"TolFun"}.

For a description of the other options, see @code{optimset}.  To initialize
an options structure with default values for @code{fsolve} use
@code{options = optimset ("fsolve")}.

The first output @var{x} is the solution while the second output @var{fval}
contains the value of the function @var{fcn} evaluated at @var{x} (ideally
a vector of all zeros).

The third output @var{info} reports whether the algorithm succeeded and may
take one of the following values:

@table @asis
@item 1
Converged to a solution point.  Relative residual error is less than
specified by @code{TolFun}.

@item 2
Last relative step size was less than @code{TolX}.

@item 3
Last relative decrease in residual was less than @code{TolFun}.

@item 0
Iteration limit (either @code{MaxIter} or @code{MaxFunEvals}) exceeded.

@item -1
Stopped by @code{OutputFcn}.

@item -3
The trust region radius became excessively small.
@end table

@var{output} is a structure containing runtime information about the
@code{fsolve} algorithm.  Fields in the structure are:

@table @code
@item iterations
 Number of iterations through loop.

@item successful
 Number of successful iterations.

@item @nospell{funcCount}
 Number of function evaluations.

@end table

The final output @var{fjac} contains the value of the Jacobian evaluated
at @var{x}.

Note: If you only have a single nonlinear equation of one variable, using
@code{fzero} is usually a much better idea.

Note about user-supplied Jacobians:
As an inherent property of the algorithm, a Jacobian is always requested for
a solution vector whose residual vector is already known, and it is the last
accepted successful step.  Often this will be one of the last two calls, but
not always.  If the savings by reusing intermediate results from residual
calculation in Jacobian calculation are significant, the best strategy is to
employ @code{OutputFcn}: After a vector is evaluated for residuals, if
@code{OutputFcn} is called with that vector, then the intermediate results
should be saved for future Jacobian evaluation, and should be kept until a
Jacobian evaluation is requested or until @code{OutputFcn} is called with a
different vector, in which case they should be dropped in favor of this most
recent vector.  A short example how this can be achieved follows:

@example
function [fval, fjac] = user_func (x, optimvalues, state)
persistent sav = [], sav0 = [];
if (nargin == 1)
  ## evaluation call
  if (nargout == 1)
    sav0.x = x; # mark saved vector
    ## calculate fval, save results to sav0.
  elseif (nargout == 2)
    ## calculate fjac using sav.
  endif
else
  ## outputfcn call.
  if (all (x == sav0.x))
    sav = sav0;
  endif
  ## maybe output iteration status, etc.
endif
endfunction

## @dots{}

fsolve (@@user_func, x0, optimset ("OutputFcn", @@user_func, @dots{}))
@end example
@xseealso{fzero, optimset}
@end deftypefn
fzero
@c fzero scripts/optimization/fzero.m
@deftypefn  {} {} fzero (@var{fun}, @var{x0})
@deftypefnx {} {} fzero (@var{fun}, @var{x0}, @var{options})
@deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fzero (@dots{})
Find a zero of a univariate function.

@var{fun} is a function handle, inline function, or string containing the
name of the function to evaluate.

@var{x0} should be a two-element vector specifying two points which
bracket a zero.  In other words, there must be a change in sign of the
function between @var{x0}(1) and @var{x0}(2).  More mathematically, the
following must hold

@example
sign (@var{fun}(@var{x0}(1))) * sign (@var{fun}(@var{x0}(2))) <= 0
@end example

If @var{x0} is a single scalar then several nearby and distant values are
probed in an attempt to obtain a valid bracketing.  If this is not
successful, the function fails.

@var{options} is a structure specifying additional options.  Currently,
@code{fzero} recognizes these options:
@qcode{"FunValCheck"}, @qcode{"MaxFunEvals"}, @qcode{"MaxIter"},
@qcode{"OutputFcn"}, and @qcode{"TolX"}.

@qcode{"MaxFunEvals"} proscribes the maximum number of function evaluations
before the search is halted.  The default value is @code{Inf}.
The value must be a positive integer.

@qcode{"MaxIter"} proscribes the maximum number of algorithm iterations
before the search is halted.  The default value is @code{Inf}.
The value must be a positive integer.

@qcode{"TolX"} specifies the termination tolerance for the solution @var{x}.
The default value is @code{eps}.

For a description of the other options, see @ref{XREFoptimset,,optimset}.
To initialize an options structure with default values for @code{fzero} use
@code{options = optimset ("fzero")}.

On exit, the function returns @var{x}, the approximate zero point, and
@var{fval}, the function evaluated at @var{x}.

The third output @var{info} reports whether the algorithm succeeded and
may take one of the following values:

@itemize
@item 1
 The algorithm converged to a solution.

@item 0
 Maximum number of iterations or function evaluations has been reached.

@item -1
The algorithm has been terminated by a user @code{OutputFcn}.

@item -5
The algorithm may have converged to a singular point.
@end itemize

@var{output} is a structure containing runtime information about the
@code{fzero} algorithm.  Fields in the structure are:

@itemize
@item iterations
 Number of iterations through loop.

@item @nospell{funcCount}
 Number of function evaluations.

@item algorithm
 The string @qcode{"bisection, interpolation"}.

@item bracketx
 A two-element vector with the final bracketing of the zero along the
x-axis.

@item brackety
 A two-element vector with the final bracketing of the zero along the
y-axis.
@end itemize
@xseealso{optimset, fsolve}
@end deftypefn
glpk
@c glpk scripts/optimization/glpk.m
@deftypefn {} {[@var{xopt}, @var{fmin}, @var{errnum}, @var{extra}] =} glpk (@var{c}, @var{A}, @var{b}, @var{lb}, @var{ub}, @var{ctype}, @var{vartype}, @var{sense}, @var{param})
Solve a linear program using the GNU @sc{glpk} library.

Given three arguments, @code{glpk} solves the following standard LP:
@tex
$$
  \min_x C^T x
$$
@end tex
@ifnottex

@example
min C'*x
@end example

@end ifnottex
subject to
@tex
$$
  Ax = b \qquad x \geq 0
$$
@end tex
@ifnottex

@example
@group
A*x  = b
  x >= 0
@end group
@end example

@end ifnottex
but may also solve problems of the form
@tex
$$
  [ \min_x | \max_x ] C^T x
$$
@end tex
@ifnottex

@example
[ min | max ] C'*x
@end example

@end ifnottex
subject to
@tex
$$
 Ax [ = | \leq | \geq ] b \qquad LB \leq x \leq UB
$$
@end tex
@ifnottex

@example
@group
A*x [ "=" | "<=" | ">=" ] b
  x >= LB
  x <= UB
@end group
@end example

@end ifnottex

Input arguments:

@table @var
@item c
A column array containing the objective function coefficients.

@item A
A matrix containing the constraints coefficients.

@item b
A column array containing the right-hand side value for each constraint in
the constraint matrix.

@item lb
An array containing the lower bound on each of the variables.  If @var{lb}
is not supplied, the default lower bound for the variables is zero.

@item ub
An array containing the upper bound on each of the variables.  If @var{ub}
is not supplied, the default upper bound is assumed to be infinite.

@item ctype
An array of characters containing the sense of each constraint in the
constraint matrix.  Each element of the array may be one of the following
values

@table @asis
@item @qcode{"F"}
A free (unbounded) constraint (the constraint is ignored).

@item @qcode{"U"}
An inequality constraint with an upper bound (@code{A(i,:)*x <= b(i)}).

@item @qcode{"S"}
An equality constraint (@code{A(i,:)*x = b(i)}).

@item @qcode{"L"}
An inequality with a lower bound (@code{A(i,:)*x >= b(i)}).

@item @qcode{"D"}
An inequality constraint with both upper and lower bounds
(@code{A(i,:)*x >= -b(i)}) @emph{and} (@code{A(i,:)*x <= b(i)}).
@end table

@item vartype
A column array containing the types of the variables.

@table @asis
@item @qcode{"C"}
A continuous variable.

@item @qcode{"I"}
An integer variable.
@end table

@item sense
If @var{sense} is 1, the problem is a minimization.  If @var{sense} is -1,
the problem is a maximization.  The default value is 1.

@item param
A structure containing the following parameters used to define the
behavior of solver.  Missing elements in the structure take on default
values, so you only need to set the elements that you wish to change from
the default.

Integer parameters:

@table @code
@item msglev (default: 1)
Level of messages output by solver routines:

@table @asis
@item 0 (@w{@code{GLP_MSG_OFF}})
No output.

@item 1 (@w{@code{GLP_MSG_ERR}})
Error and warning messages only.

@item 2 (@w{@code{GLP_MSG_ON}})
Normal output.

@item 3 (@w{@code{GLP_MSG_ALL}})
Full output (includes informational messages).
@end table

@item scale (default: 16)
Scaling option.  The values can be combined with the bitwise OR operator and
may be the following:

@table @asis
@item 1 (@w{@code{GLP_SF_GM}})
Geometric mean scaling.

@item 16 (@w{@code{GLP_SF_EQ}})
Equilibration scaling.

@item 32 (@w{@code{GLP_SF_2N}})
Round scale factors to power of two.

@item 64 (@w{@code{GLP_SF_SKIP}})
Skip if problem is well scaled.
@end table

Alternatively, a value of 128 (@w{@env{GLP_SF_AUTO}}) may be also
specified, in which case the routine chooses the scaling options
automatically.

@item dual (default: 1)
Simplex method option:

@table @asis
@item 1 (@w{@code{GLP_PRIMAL}})
Use two-phase primal simplex.

@item 2 (@w{@code{GLP_DUALP}})
Use two-phase dual simplex, and if it fails, switch to the primal simplex.

@item 3 (@w{@code{GLP_DUAL}})
Use two-phase dual simplex.
@end table

@item price (default: 34)
Pricing option (for both primal and dual simplex):

@table @asis
@item 17 (@w{@code{GLP_PT_STD}})
Textbook pricing.

@item 34 (@w{@code{GLP_PT_PSE}})
Steepest edge pricing.
@end table

@item itlim (default: intmax)
Simplex iterations limit.  It is decreased by one each time when one simplex
iteration has been performed, and reaching zero value signals the solver to
stop the search.

@item outfrq (default: 200)
Output frequency, in iterations.  This parameter specifies how frequently
the solver sends information about the solution to the standard output.

@item branch (default: 4)
Branching technique option (for MIP only):

@table @asis
@item 1 (@w{@code{GLP_BR_FFV}})
First fractional variable.

@item 2 (@w{@code{GLP_BR_LFV}})
Last fractional variable.

@item 3 (@w{@code{GLP_BR_MFV}})
Most fractional variable.

@item 4 (@w{@code{GLP_BR_DTH}})
Heuristic by @nospell{Driebeck and Tomlin}.

@item 5 (@w{@code{GLP_BR_PCH}})
Hybrid @nospell{pseudocost} heuristic.
@end table

@item btrack (default: 4)
Backtracking technique option (for MIP only):

@table @asis
@item 1 (@w{@code{GLP_BT_DFS}})
Depth first search.

@item 2 (@w{@code{GLP_BT_BFS}})
Breadth first search.

@item 3 (@w{@code{GLP_BT_BLB}})
Best local bound.

@item 4 (@w{@code{GLP_BT_BPH}})
Best projection heuristic.
@end table

@item presol (default: 1)
If this flag is set, the simplex solver uses the built-in LP presolver.
Otherwise the LP presolver is not used.

@item lpsolver (default: 1)
Select which solver to use.  If the problem is a MIP problem this flag
will be ignored.

@table @asis
@item 1
Revised simplex method.

@item 2
Interior point method.
@end table

@item rtest (default: 34)
Ratio test technique:

@table @asis
@item 17 (@w{@code{GLP_RT_STD}})
Standard ("textbook").

@item 34 (@w{@code{GLP_RT_HAR}})
Harris' two-pass ratio test.
@end table

@item tmlim (default: intmax)
Searching time limit, in milliseconds.

@item outdly (default: 0)
Output delay, in seconds.  This parameter specifies how long the solver
should delay sending information about the solution to the standard output.

@item save (default: 0)
If this parameter is nonzero, save a copy of the problem in @nospell{CPLEX}
LP format to the file @file{"outpb.lp"}.  There is currently no way to
change the name of the output file.
@end table

Real parameters:

@table @code
@item tolbnd (default: 1e-7)
Relative tolerance used to check if the current basic solution is primal
feasible.  It is not recommended that you change this parameter unless you
have a detailed understanding of its purpose.

@item toldj (default: 1e-7)
Absolute tolerance used to check if the current basic solution is dual
feasible.  It is not recommended that you change this parameter unless you
have a detailed understanding of its purpose.

@item tolpiv (default: 1e-10)
Relative tolerance used to choose eligible pivotal elements of the simplex
table.  It is not recommended that you change this parameter unless you have
a detailed understanding of its purpose.

@item objll (default: -DBL_MAX)
Lower limit of the objective function.  If the objective function reaches
this limit and continues decreasing, the solver stops the search.  This
parameter is used in the dual simplex method only.

@item objul (default: +DBL_MAX)
Upper limit of the objective function.  If the objective function reaches
this limit and continues increasing, the solver stops the search.  This
parameter is used in the dual simplex only.

@item tolint (default: 1e-5)
Relative tolerance used to check if the current basic solution is integer
feasible.  It is not recommended that you change this parameter unless you
have a detailed understanding of its purpose.

@item tolobj (default: 1e-7)
Relative tolerance used to check if the value of the objective function is
not better than in the best known integer feasible solution.  It is not
recommended that you change this parameter unless you have a detailed
understanding of its purpose.
@end table
@end table

Output values:

@table @var
@item xopt
The optimizer (the value of the decision variables at the optimum).

@item fopt
The optimum value of the objective function.

@item errnum
Error code.

@table @asis
@item 0
No error.

@item 1 (@w{@code{GLP_EBADB}})
Invalid basis.

@item 2 (@w{@code{GLP_ESING}})
Singular matrix.

@item 3 (@w{@code{GLP_ECOND}})
Ill-conditioned matrix.

@item 4 (@w{@code{GLP_EBOUND}})
Invalid bounds.

@item 5 (@w{@code{GLP_EFAIL}})
Solver failed.

@item 6 (@w{@code{GLP_EOBJLL}})
Objective function lower limit reached.

@item 7 (@w{@code{GLP_EOBJUL}})
Objective function upper limit reached.

@item 8 (@w{@code{GLP_EITLIM}})
Iterations limit exhausted.

@item 9 (@w{@code{GLP_ETMLIM}})
Time limit exhausted.

@item 10 (@w{@code{GLP_ENOPFS}})
No primal feasible solution.

@item 11 (@w{@code{GLP_ENODFS}})
No dual feasible solution.

@item 12 (@w{@code{GLP_EROOT}})
Root LP optimum not provided.

@item 13 (@w{@code{GLP_ESTOP}})
Search terminated by application.

@item 14 (@w{@code{GLP_EMIPGAP}})
Relative MIP gap tolerance reached.

@item 15 (@w{@code{GLP_ENOFEAS}})
No primal/dual feasible solution.

@item 16 (@w{@code{GLP_ENOCVG}})
No convergence.

@item 17 (@w{@code{GLP_EINSTAB}})
Numerical instability.

@item 18 (@w{@code{GLP_EDATA}})
Invalid data.

@item 19 (@w{@code{GLP_ERANGE}})
Result out of range.
@end table

@item extra
A data structure containing the following fields:

@table @code
@item lambda
Dual variables.

@item redcosts
Reduced Costs.

@item time
Time (in seconds) used for solving LP/MIP problem.

@item status
Status of the optimization.

@table @asis
@item 1 (@w{@code{GLP_UNDEF}})
Solution status is undefined.

@item 2 (@w{@code{GLP_FEAS}})
Solution is feasible.

@item 3 (@w{@code{GLP_INFEAS}})
Solution is infeasible.

@item 4 (@w{@code{GLP_NOFEAS}})
Problem has no feasible solution.

@item 5 (@w{@code{GLP_OPT}})
Solution is optimal.

@item 6 (@w{@code{GLP_UNBND}})
Problem has no unbounded solution.
@end table
@end table
@end table

Example:

@example
@group
c = [10, 6, 4]';
A = [ 1, 1, 1;
     10, 4, 5;
      2, 2, 6];
b = [100, 600, 300]';
lb = [0, 0, 0]';
ub = [];
ctype = "UUU";
vartype = "CCC";
s = -1;

param.msglev = 1;
param.itlim = 100;

[xmin, fmin, status, extra] = ...
   glpk (c, A, b, lb, ub, ctype, vartype, s, param);
@end group
@end example
@end deftypefn
humps
@c humps scripts/optimization/humps.m
@deftypefn  {} {@var{y} =} humps (@var{x})
@deftypefnx {} {[@var{x}, @var{y}] =} humps (@var{x})
Evaluate a function with multiple minima, maxima, and zero crossings.

The output @var{y} is the evaluation of the rational function:

@tex
$$y = -{ {1200x^4 - 2880x^3 + 2036x^2 - 340x - 88} \over {200x^4 - 480x^3 + 406x^2 - 138x - 17} }$$
@end tex
@ifnottex

@example
@group
        1200*@var{x}^4 - 2880*@var{x}^3 + 2036*@var{x}^2 - 348*@var{x} - 88
 @var{y} = - ---------------------------------------------
         200*@var{x}^4 - 480*@var{x}^3 + 406*@var{x}^2 - 138*@var{x} + 17
@end group
@end example

@end ifnottex

@var{x} may be a scalar, vector or array.  If @var{x} is omitted, the
default range [0:0.05:1] is used.

When called with two output arguments, [@var{x}, @var{y}], @var{x} will
contain the input values, and @var{y} will contain the output from
@code{humps}.

Programming Notes: @code{humps} has two local maxima located near @var{x} =
0.300 and 0.893, a local minimum near @var{x} = 0.637, and zeros near
@var{x} = -0.132 and 1.300.  @code{humps} is a useful function for testing
algorithms which find zeros or local minima and maxima.

Try @code{demo humps} to see a plot of the @code{humps} function.
@xseealso{fzero, fminbnd, fminunc, fminsearch}
@end deftypefn
lsqnonneg
@c lsqnonneg scripts/optimization/lsqnonneg.m
@deftypefn  {} {@var{x} =} lsqnonneg (@var{c}, @var{d})
@deftypefnx {} {@var{x} =} lsqnonneg (@var{c}, @var{d}, @var{x0})
@deftypefnx {} {@var{x} =} lsqnonneg (@var{c}, @var{d}, @var{x0}, @var{options})
@deftypefnx {} {[@var{x}, @var{resnorm}] =} lsqnonneg (@dots{})
@deftypefnx {} {[@var{x}, @var{resnorm}, @var{residual}] =} lsqnonneg (@dots{})
@deftypefnx {} {[@var{x}, @var{resnorm}, @var{residual}, @var{exitflag}] =} lsqnonneg (@dots{})
@deftypefnx {} {[@var{x}, @var{resnorm}, @var{residual}, @var{exitflag}, @var{output}] =} lsqnonneg (@dots{})
@deftypefnx {} {[@var{x}, @var{resnorm}, @var{residual}, @var{exitflag}, @var{output}, @var{lambda}] =} lsqnonneg (@dots{})

Minimize @code{norm (@var{c}*@var{x} - @var{d})} subject to
@code{@var{x} >= 0}.

@var{c} and @var{d} must be real matrices.

@var{x0} is an optional initial guess for the solution @var{x}.

@var{options} is an options structure to change the behavior of the
algorithm (@pxref{XREFoptimset,,optimset}).  @code{lsqnonneg} recognizes
these options: @qcode{"MaxIter"}, @qcode{"TolX"}.

Outputs:

@table @var
@item resnorm
The squared 2-norm of the residual: @code{norm (@var{c}*@var{x}-@var{d})^2}

@item residual
The residual: @code{@var{d}-@var{c}*@var{x}}

@item exitflag
An indicator of convergence.  0 indicates that the iteration count was
exceeded, and therefore convergence was not reached; >0 indicates that the
algorithm converged.  (The algorithm is stable and will converge given
enough iterations.)

@item output
A structure with two fields:

@itemize @bullet
@item @qcode{"algorithm"}: The algorithm used (@qcode{"nnls"})

@item @qcode{"iterations"}: The number of iterations taken.
@end itemize

@item lambda
@c FIXME: Something is output from the function, but what is it?
Undocumented output
@end table
@xseealso{pqpnonneg, lscov, optimset}
@end deftypefn
optimget
@c optimget scripts/optimization/optimget.m
@deftypefn  {} {} optimget (@var{options}, @var{parname})
@deftypefnx {} {} optimget (@var{options}, @var{parname}, @var{default})
Return the specific option @var{parname} from the optimization options
structure @var{options} created by @code{optimset}.

If @var{parname} is not defined then return @var{default} if supplied,
otherwise return an empty matrix.
@xseealso{optimset}
@end deftypefn
optimset
@c optimset scripts/optimization/optimset.m
@deftypefn  {} {} optimset ()
@deftypefnx {} {@var{options} =} optimset ()
@deftypefnx {} {@var{options} =} optimset (@var{par}, @var{val}, @dots{})
@deftypefnx {} {@var{options} =} optimset (@var{old}, @var{par}, @var{val}, @dots{})
@deftypefnx {} {@var{options} =} optimset (@var{old}, @var{new})
Create options structure for optimization functions.

When called without any input or output arguments, @code{optimset} prints
a list of all valid optimization parameters.

When called with one output and no inputs, return an options structure with
all valid option parameters initialized to @code{[]}.

When called with a list of parameter/value pairs, return an options
structure with only the named parameters initialized.

When the first input is an existing options structure @var{old}, the values
are updated from either the @var{par}/@var{val} list or from the options
structure @var{new}.

Valid parameters are:

@table @asis
@item AutoScaling

@item ComplexEqn

@item Display
Request verbose display of results from optimizations.  Values are:

@table @asis
@item @qcode{"off"} [default]
No display.

@item @qcode{"iter"}
Display intermediate results for every loop iteration.

@item @qcode{"final"}
Display the result of the final loop iteration.

@item @qcode{"notify"}
Display the result of the final loop iteration if the function has
failed to converge.
@end table

@item FinDiffType

@item FunValCheck
When enabled, display an error if the objective function returns an invalid
value (a complex number, NaN, or Inf).  Must be set to @qcode{"on"} or
@qcode{"off"} [default].  Note: the functions @code{fzero} and
@code{fminbnd} correctly handle Inf values and only complex values or NaN
will cause an error in this case.

@item GradObj
When set to @qcode{"on"}, the function to be minimized must return a
second argument which is the gradient, or first derivative, of the
function at the point @var{x}.  If set to @qcode{"off"} [default], the
gradient is computed via finite differences.

@item Jacobian
When set to @qcode{"on"}, the function to be minimized must return a
second argument which is the Jacobian, or first derivative, of the
function at the point @var{x}.  If set to @qcode{"off"} [default], the
Jacobian is computed via finite differences.

@item MaxFunEvals
Maximum number of function evaluations before optimization stops.
Must be a positive integer.

@item MaxIter
Maximum number of algorithm iterations before optimization stops.
Must be a positive integer.

@item OutputFcn
A user-defined function executed once per algorithm iteration.

@item TolFun
Termination criterion for the function output.  If the difference in the
calculated objective function between one algorithm iteration and the next
is less than @code{TolFun} the optimization stops.  Must be a positive
scalar.

@item TolX
Termination criterion for the function input.  If the difference in @var{x},
the current search point, between one algorithm iteration and the next is
less than @code{TolX} the optimization stops.  Must be a positive scalar.

@item TypicalX

@item Updating
@end table
@xseealso{optimget}
@end deftypefn
pqpnonneg
@c pqpnonneg scripts/optimization/pqpnonneg.m
@deftypefn  {} {@var{x} =} pqpnonneg (@var{c}, @var{d})
@deftypefnx {} {@var{x} =} pqpnonneg (@var{c}, @var{d}, @var{x0})
@deftypefnx {} {@var{x} =} pqpnonneg (@var{c}, @var{d}, @var{x0}, @var{options})
@deftypefnx {} {[@var{x}, @var{minval}] =} pqpnonneg (@dots{})
@deftypefnx {} {[@var{x}, @var{minval}, @var{exitflag}] =} pqpnonneg (@dots{})
@deftypefnx {} {[@var{x}, @var{minval}, @var{exitflag}, @var{output}] =} pqpnonneg (@dots{})
@deftypefnx {} {[@var{x}, @var{minval}, @var{exitflag}, @var{output}, @var{lambda}] =} pqpnonneg (@dots{})

Minimize @code{1/2*@var{x}'*@var{c}*@var{x} + @var{d}'*@var{x}} subject to
@code{@var{x} >= 0}.

@var{c} and @var{d} must be real matrices, and @var{c} must be symmetric and
positive definite.

@var{x0} is an optional initial guess for the solution @var{x}.

@var{options} is an options structure to change the behavior of the
algorithm (@pxref{XREFoptimset,,optimset}).  @code{pqpnonneg} recognizes
one option: @qcode{"MaxIter"}.

Outputs:

@table @var

@item x
The solution matrix

@item minval
The minimum attained model value,
@code{1/2*@var{xmin}'*@var{c}*@var{xmin} + @var{d}'*@var{xmin}}

@item exitflag
An indicator of convergence.  0 indicates that the iteration count was
exceeded, and therefore convergence was not reached; >0 indicates that the
algorithm converged.  (The algorithm is stable and will converge given
enough iterations.)

@item output
A structure with two fields:

@itemize @bullet
@item @qcode{"algorithm"}: The algorithm used (@nospell{@qcode{"nnls"}})

@item @qcode{"iterations"}: The number of iterations taken.
@end itemize

@item lambda
@c FIXME: Something is output from the function, but what is it?
Undocumented output
@end table
@xseealso{lsqnonneg, qp, optimset}
@end deftypefn
qp
@c qp scripts/optimization/qp.m
@deftypefn  {} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H})
@deftypefnx {} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q})
@deftypefnx {} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q}, @var{A}, @var{b})
@deftypefnx {} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q}, @var{A}, @var{b}, @var{lb}, @var{ub})
@deftypefnx {} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q}, @var{A}, @var{b}, @var{lb}, @var{ub}, @var{A_lb}, @var{A_in}, @var{A_ub})
@deftypefnx {} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@dots{}, @var{options})
Solve a quadratic program (QP).

Solve the quadratic program defined by
@tex
$$
 \min_x {1 \over 2} x^T H x + x^T q
$$
@end tex
@ifnottex

@example
@group
min 0.5 x'*H*x + x'*q
 x
@end group
@end example

@end ifnottex
subject to
@tex
$$
 A x = b \qquad lb \leq x \leq ub \qquad A_{lb} \leq A_{in} x \leq A_{ub}
$$
@end tex
@ifnottex

@example
@group
A*x = b
lb <= x <= ub
A_lb <= A_in*x <= A_ub
@end group
@end example

@end ifnottex
@noindent
using a null-space active-set method.

Any bound (@var{A}, @var{b}, @var{lb}, @var{ub}, @var{A_in}, @var{A_lb},
@var{A_ub}) may be set to the empty matrix (@code{[]}) if not present.  The
constraints @var{A} and @var{A_in} are matrices with each row representing
a single constraint.  The other bounds are scalars or vectors depending on
the number of constraints.  The algorithm is faster if the initial guess is
feasible.

@table @var
@item options
An optional structure containing the following parameter(s) used to define
the behavior of the solver.  Missing elements in the structure take on
default values, so you only need to set the elements that you wish to
change from the default.

@table @code
@item MaxIter (default: 200)
Maximum number of iterations.
@end table
@end table

@table @var
@item info
Structure containing run-time information about the algorithm.  The
following fields are defined:

@table @code
@item solveiter
The number of iterations required to find the solution.

@item info
An integer indicating the status of the solution.

@table @asis
@item 0
The problem is feasible and convex.  Global solution found.

@item 1
The problem is not convex.  Local solution found.

@item 2
The problem is not convex and unbounded.

@item 3
Maximum number of iterations reached.

@item 6
The problem is infeasible.
@end table
@end table
@end table
@end deftypefn
sqp
@c sqp scripts/optimization/sqp.m
@deftypefn  {} {[@var{x}, @var{obj}, @var{info}, @var{iter}, @var{nf}, @var{lambda}] =} sqp (@var{x0}, @var{phi})
@deftypefnx {} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g})
@deftypefnx {} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g}, @var{h})
@deftypefnx {} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g}, @var{h}, @var{lb}, @var{ub})
@deftypefnx {} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g}, @var{h}, @var{lb}, @var{ub}, @var{maxiter})
@deftypefnx {} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g}, @var{h}, @var{lb}, @var{ub}, @var{maxiter}, @var{tol})
Minimize an objective function using sequential quadratic programming (SQP).

Solve the nonlinear program
@tex
$$
\min_x \phi (x)
$$
@end tex
@ifnottex

@example
@group
min phi (x)
 x
@end group
@end example

@end ifnottex
subject to
@tex
$$
 g(x) = 0 \qquad h(x) \geq 0 \qquad lb \leq x \leq ub
$$
@end tex
@ifnottex

@example
@group
g(x)  = 0
h(x) >= 0
lb <= x <= ub
@end group
@end example

@end ifnottex
@noindent
using a sequential quadratic programming method.

The first argument is the initial guess for the vector @var{x0}.

The second argument is a function handle pointing to the objective function
@var{phi}.  The objective function must accept one vector argument and
return a scalar.

The second argument may also be a 2- or 3-element cell array of function
handles.  The first element should point to the objective function, the
second should point to a function that computes the gradient of the
objective function, and the third should point to a function that computes
the Hessian of the objective function.  If the gradient function is not
supplied, the gradient is computed by finite differences.  If the Hessian
function is not supplied, a BFGS update formula is used to approximate the
Hessian.

When supplied, the gradient function @code{@var{phi}@{2@}} must accept one
vector argument and return a vector.  When supplied, the Hessian function
@code{@var{phi}@{3@}} must accept one vector argument and return a matrix.

The third and fourth arguments @var{g} and @var{h} are function handles
pointing to functions that compute the equality constraints and the
inequality constraints, respectively.  If the problem does not have
equality (or inequality) constraints, then use an empty matrix ([]) for
@var{g} (or @var{h}).  When supplied, these equality and inequality
constraint functions must accept one vector argument and return a vector.

The third and fourth arguments may also be 2-element cell arrays of
function handles.  The first element should point to the constraint
function and the second should point to a function that computes the
gradient of the constraint function:
@tex
$$
 \Bigg( {\partial f(x) \over \partial x_1},
        {\partial f(x) \over \partial x_2}, \ldots,
        {\partial f(x) \over \partial x_N} \Bigg)^T
$$
@end tex
@ifnottex

@example
@group
            [ d f(x)   d f(x)        d f(x) ]
transpose ( [ ------   -----   ...   ------ ] )
            [  dx_1     dx_2          dx_N  ]
@end group
@end example

@end ifnottex
The fifth and sixth arguments, @var{lb} and @var{ub}, contain lower and
upper bounds on @var{x}.  These must be consistent with the equality and
inequality constraints @var{g} and @var{h}.  If the arguments are vectors
then @var{x}(i) is bound by @var{lb}(i) and @var{ub}(i).  A bound can also
be a scalar in which case all elements of @var{x} will share the same
bound.  If only one bound (lb, ub) is specified then the other will
default to (-@var{realmax}, +@var{realmax}).

The seventh argument @var{maxiter} specifies the maximum number of
iterations.  The default value is 100.

The eighth argument @var{tol} specifies the tolerance for the stopping
criteria.  The default value is @code{sqrt (eps)}.

The value returned in @var{info} may be one of the following:

@table @asis
@item 101
The algorithm terminated normally.
All constraints meet the specified tolerance.

@item 102
The BFGS update failed.

@item 103
The maximum number of iterations was reached.

@item 104
The stepsize has become too small, i.e.,
@tex
$\Delta x,$
@end tex
@ifnottex
delta @var{x},
@end ifnottex
is less than @code{@var{tol} * norm (x)}.
@end table

An example of calling @code{sqp}:

@example
function r = g (x)
  r = [ sumsq(x)-10;
        x(2)*x(3)-5*x(4)*x(5);
        x(1)^3+x(2)^3+1 ];
endfunction

function obj = phi (x)
  obj = exp (prod (x)) - 0.5*(x(1)^3+x(2)^3+1)^2;
endfunction

x0 = [-1.8; 1.7; 1.9; -0.8; -0.8];

[x, obj, info, iter, nf, lambda] = sqp (x0, @@phi, @@g, [])

x =

  -1.71714
   1.59571
   1.82725
  -0.76364
  -0.76364

obj = 0.053950
info = 101
iter = 8
nf = 10
lambda =

  -0.0401627
   0.0379578
  -0.0052227
@end example

@xseealso{qp}
@end deftypefn
import
@c import scripts/path/import.m
@deftypefn  {} {} import PACKAGE.FUNCTION
@deftypefnx {} {} import PACKAGE.CLASS
@deftypefnx {} {} import PACKAGE.*
@deftypefnx {} {} import
@deftypefnx {} {@var{list} =} import

Import function or classes into the current scope.

@strong{Warning:} This functionality is not yet implemented, and invoking
the function will emit an error.

When invoked with the name of a PACKAGE and a FUNCTION or CLASS name, that
name is made available in the current code without having to use namespace
qualifiers.  This can facilitate the readability of the code, and require
less typing by programmers.

Example

@example
@group
import containers.Map;

m = Map (@{"A", "B"@}, @{[1], [2]@});
@end group
@end example

When called with no inputs and no outputs @code{import} prints a list of
any import definitions.

When called with no inputs and one output, a cell array of strings
@var{list} is returned with any import definitions.

@end deftypefn
matlabroot
@c matlabroot scripts/path/matlabroot.m
@deftypefn {} {} matlabroot ()
Return the name of the top-level Octave installation directory.

This is an alias for the function @w{@code{OCTAVE_HOME}} provided for
compatibility.
@xseealso{OCTAVE_HOME}
@end deftypefn
pathdef
@c pathdef scripts/path/pathdef.m
@deftypefn {} {@var{val} =} pathdef ()
Return the default path for Octave.

The path information is extracted from one of four sources.
The possible sources, in order of preference, are:

@enumerate
@item @file{.octaverc}

@item @file{~/.octaverc}

@item @file{<OCTAVE_HOME>/@dots{}/<version>/m/startup/octaverc}

@item Octave's path prior to changes by any octaverc file.
@end enumerate
@xseealso{path, addpath, rmpath, genpath, savepath}
@end deftypefn
savepath
@c savepath scripts/path/savepath.m
@deftypefn  {} {} savepath ()
@deftypefnx {} {} savepath (@var{file})
@deftypefnx {} {@var{status} =} savepath (@dots{})
Save the unique portion of the current function search path that is
not set during Octave's initialization process to @var{file}.

If @var{file} is omitted, Octave looks in the current directory for a
project-specific @file{.octaverc} file in which to save the path
information.  If no such file is present then the user's configuration file
@file{~/.octaverc} is used.

If successful, @code{savepath} returns 0.

The @code{savepath} function makes it simple to customize a user's
configuration file to restore the working paths necessary for a particular
instance of Octave.  Assuming no filename is specified, Octave will
automatically restore the saved directory paths from the appropriate
@file{.octaverc} file when starting up.  If a filename has been specified
then the paths may be restored manually by calling @code{source @var{file}}.
@xseealso{path, addpath, rmpath, genpath, pathdef}
@end deftypefn
pkg
@c pkg scripts/pkg/pkg.m
@deftypefn  {} {} pkg @var{command} @var{pkg_name}
@deftypefnx {} {} pkg @var{command} @var{option} @var{pkg_name}
@deftypefnx {} {[@var{out1}, @dots{}] =} pkg (@var{command}, @dots{} )
Manage or query packages (groups of add-on functions) for Octave.

Different actions are available depending on the value of @var{command}
and on return arguments.

Available commands:

@table @samp

@item install
Install named packages.  For example,

@example
pkg install image-1.0.0.tar.gz
@end example

@noindent
installs the package found in the file @file{image-1.0.0.tar.gz}.  The
file containing the package can be an url, e.g.

@example
pkg install 'http://somewebsite.org/image-1.0.0.tar.gz'
@end example

@noindent
installs the package found in the given url.  This
requires an internet connection and the cURL library.

@noindent
@emph{Security risk}: no verification of the package is performed
before the installation.  It has the same security issues as manually
downloading the package from the given url and installing it.

@noindent
@emph{No support}: the GNU Octave community is not responsible for
packages installed from foreign sites.  For support or for
reporting bugs you need to contact the maintainers of the installed
package directly (see the @file{DESCRIPTION} file of the package)

The @var{option} variable can contain options that affect the manner
in which a package is installed.  These options can be one or more of

@table @code
@item -nodeps
The package manager will disable dependency checking.  With this option it
is possible to install a package even when it depends on another package
which is not installed on the system.  @strong{Use this option with care.}

@item -local
A local installation (package available only to current user) is forced,
even if the user has system privileges.

@item -global
A global installation (package available to all users) is forced, even if
the user doesn't normally have system privileges.

@item -forge
Install a package directly from the Octave Forge repository.  This
requires an internet connection and the cURL library.

@emph{Security risk}: no verification of the package is performed
before the installation.  There are no signature for packages, or
checksums to confirm the correct file was downloaded.  It has the
same security issues as manually downloading the package from the
Octave Forge repository and installing it.

@item -verbose
The package manager will print the output of all commands as
they are performed.
@end table

@item update
Check installed Octave Forge packages against repository and update any
outdated items.  This requires an internet connection and the cURL library.
Usage:

@example
pkg update
@end example

@noindent
To update a single package use @code{pkg install -forge}

@item uninstall
Uninstall named packages.  For example,

@example
pkg uninstall image
@end example

@noindent
removes the @code{image} package from the system.  If another installed
package depends on the @code{image} package an error will be issued.
The package can be uninstalled anyway by using the @option{-nodeps} option.

@item load
Add named packages to the path.  After loading a package it is
possible to use the functions provided by the package.  For example,

@example
pkg load image
@end example

@noindent
adds the @code{image} package to the path.

@item unload
Remove named packages from the path.  After unloading a package it is
no longer possible to use the functions provided by the package.

@item list
Show the list of currently installed packages.  For example,

@example
pkg list
@end example

@noindent
will produce a short report with the package name, version, and installation
directory for each installed package.  Supply a package name to limit
reporting to a particular package.  For example:

@example
pkg list image
@end example

If a single return argument is requested then @code{pkg} returns a cell
array where each element is a structure with information on a single
package.

@example
installed_packages = pkg ("list")
@end example

If two output arguments are requested @code{pkg} splits the list of
installed packages into those which were installed by the current user,
and those which were installed by the system administrator.

@example
[user_packages, system_packages] = pkg ("list")
@end example

The @qcode{"-forge"} option lists packages available at the Octave Forge
repository.  This requires an internet connection and the cURL library.
For example:

@example
oct_forge_pkgs = pkg ("list", "-forge")
@end example

@item describe
Show a short description of installed packages.  With the option
@qcode{"-verbose"} also list functions provided by the package.  For
example,

@example
pkg describe -verbose
@end example

@noindent
will describe all installed packages and the functions they provide.
Display can be limited to a set of packages:

@example
## describe control and signal packages
pkg describe control signal
@end example

If one output is requested a cell of structure containing the
description and list of functions of each package is returned as
output rather than printed on screen:

@example
desc = pkg ("describe", "secs1d", "image")
@end example

@noindent
If any of the requested packages is not installed, @code{pkg} returns an
error, unless a second output is requested:

@example
[desc, flag] = pkg ("describe", "secs1d", "image")
@end example

@noindent
@var{flag} will take one of the values @qcode{"Not installed"},
@qcode{"Loaded"}, or
@qcode{"Not loaded"} for each of the named packages.

@item prefix
Set the installation prefix directory.  For example,

@example
pkg prefix ~/my_octave_packages
@end example

@noindent
sets the installation prefix to @file{~/my_octave_packages}.
Packages will be installed in this directory.

It is possible to get the current installation prefix by requesting an
output argument.  For example:

@example
pfx = pkg ("prefix")
@end example

The location in which to install the architecture dependent files can be
independently specified with an addition argument.  For example:

@example
pkg prefix ~/my_octave_packages ~/my_arch_dep_pkgs
@end example

@item local_list
Set the file in which to look for information on locally
installed packages.  Locally installed packages are those that are
available only to the current user.  For example:

@example
pkg local_list ~/.octave_packages
@end example

It is possible to get the current value of local_list with the following

@example
pkg local_list
@end example

@item global_list
Set the file in which to look for information on globally
installed packages.  Globally installed packages are those that are
available to all users.  For example:

@example
pkg global_list /usr/share/octave/octave_packages
@end example

It is possible to get the current value of global_list with the following

@example
pkg global_list
@end example

@item build
Build a binary form of a package or packages.  The binary file produced
will itself be an Octave package that can be installed normally with
@code{pkg}.  The form of the command to build a binary package is

@example
pkg build builddir image-1.0.0.tar.gz @dots{}
@end example

@noindent
where @code{builddir} is the name of a directory where the temporary
installation will be produced and the binary packages will be found.
The options @option{-verbose} and @option{-nodeps} are respected, while
all other options are ignored.

@item rebuild
Rebuild the package database from the installed directories.  This can
be used in cases where the package database has been corrupted.

@end table
@xseealso{ver, news}
@end deftypefn
__clabel__
@c __clabel__ scripts/plot/appearance/__clabel__.m
@deftypefn {} {@var{h} =} __clabel__ (@var{c}, @var{v}, @var{hparent}, @var{label_spacing}, @var{z}, @var{varargin})
Undocumented internal function.
@end deftypefn
__getlegenddata__
@c __getlegenddata__ scripts/plot/appearance/__getlegenddata__.m
@deftypefn {} {[@var{hplots}, @var{strings}] =} __getlegenddata__ (@var{hlegend})
Undocumented internal function.
@end deftypefn
__rotate_around_axis__
@c __rotate_around_axis__ scripts/plot/appearance/__rotate_around_axis__.m
@deftypefn {} {[@var{xr}, @var{yr}, @var{zr}] =} __rotate_around_axis__ (@var{x}, @var{y}, @var{z}, @var{angle}, @var{dir}, @var{origin})
Rotate the points given by X, Y, Z about an axis by ANGLE degrees.
The axis is specified by the vector DIR and the point ORIGIN.
@end deftypefn
annotation
@c annotation scripts/plot/appearance/annotation.m
@deftypefn  {} {} annotation (@var{type})
@deftypefnx {} {} annotation ("line", @var{x}, @var{y})
@deftypefnx {} {} annotation ("arrow", @var{x}, @var{y})
@deftypefnx {} {} annotation ("doublearrow", @var{x}, @var{y})
@deftypefnx {} {} annotation ("textarrow", @var{x}, @var{y})
@deftypefnx {} {} annotation ("textbox", @var{pos})
@deftypefnx {} {} annotation ("rectangle", @var{pos})
@deftypefnx {} {} annotation ("ellipse", @var{pos})
@deftypefnx {} {} annotation (@dots{}, @var{prop}, @var{val})
@deftypefnx {} {} annotation (@var{hf}, @dots{})
@deftypefnx {} {@var{h} =} annotation (@dots{})
Draw annotations to emphasize parts of a figure.

You may build a default annotation by specifying only the @var{type}
of the annotation.

Otherwise you can select the type of annotation and then set its position
using either @var{x} and @var{y} coordinates for line-based annotations or a
position vector @var{pos} for others.  In either case, coordinates are
interpreted using the @qcode{"units"} property of the annotation object.
The default is @qcode{"normalized"}, which means the lower left hand corner
of the figure has coordinates @samp{[0 0]} and the upper right hand corner
@samp{[1 1]}.

If the first argument @var{hf} is a figure handle, then plot into this
figure, rather than the current figure returned by @code{gcf}.

Further arguments can be provided in the form of @var{prop}/@var{val} pairs
to customize the annotation appearance.

The optional return value @var{h} is a graphics handle to the created
annotation object.  This can be used with the @code{set} function to
customize an existing annotation object.

All annotation objects share two properties:

@itemize
@item @qcode{"units"}: the units in which coordinates are interpreted.@*
Its value may be one of @qcode{"centimeters"} | @qcode{"characters"} |
@qcode{"inches"} | @qcode{"@{normalized@}"} | @qcode{"pixels"} |
@qcode{"points"}.

@item @qcode{"position"}: a four-element vector [x0 y0 width height].@*
The vector specifies the coordinates (x0,y0) of the origin of the annotation
object, its width, and its height.  The width and height may be negative,
depending on the orientation of the object.

@end itemize

Valid annotation types and their specific properties are described
below:

@table @asis
@item @qcode{"line"}
Constructs a line.  @var{x} and @var{y} must be two-element vectors
specifying the x and y coordinates of the two ends of the line.

The line can be customized using @qcode{"linewidth"}, @qcode{"linestyle"},
and @qcode{"color"} properties the same way as for @code{line} objects.

@item @qcode{"arrow"}
Construct an arrow.  The second point in vectors @var{x} and @var{y}
specifies the arrowhead coordinates.

Besides line properties, the arrowhead can be customized using
@qcode{"headlength"}, @qcode{"headwidth"}, and @qcode{"headstyle"}
properties.  Supported values for @qcode{"headstyle"} property are:
[@qcode{"diamond"} | @qcode{"ellipse"} | @qcode{"plain"} |
@qcode{"rectangle"} | @qcode{"vback1"} | @qcode{"@{vback2@}"} |
@qcode{"vback3"}]

@item @qcode{"doublearrow"}
Construct a double arrow.  Vectors @var{x} and @var{y} specify the
arrowhead coordinates.

The line and the arrowhead can be customized as for arrow annotations, but
some property names are duplicated:
@qcode{"head1length"}/@qcode{"head2length"},
@qcode{"head1width"}/@qcode{"head2width"}, etc.  The index 1 marks the
properties of the arrowhead at the first point in @var{x} and @var{y}
coordinates.

@item @qcode{"textarrow"}
Construct an arrow with a text label at the opposite end from the arrowhead.

Use the @qcode{"string"} property to change the text string.
The line and the arrowhead can be customized as for arrow annotations, and
the text can be customized using the same properties as @code{text} graphics
objects.  Note, however, that some text property names are prefixed with
"text" to distinguish them from arrow properties:
@qcode{"textbackgroundcolor"}, @qcode{"textcolor"},
@qcode{"textedgecolor"}, @qcode{"textlinewidth"},
@qcode{"textmargin"}, @qcode{"textrotation"}.

@item @qcode{"textbox"}
Construct a box with text inside.  @var{pos} specifies the
@qcode{"position"} property of the annotation.

Use the @qcode{"string"} property to change the text string.
You may use @qcode{"backgroundcolor"}, @qcode{"edgecolor"},
@qcode{"linestyle"}, and @qcode{"linewidth"} properties to customize
the box background color and edge appearance.  A limited set of @code{text}
objects properties are also available; Besides @qcode{"font@dots{}"}
properties, you may also use @qcode{"horizontalalignment"} and
@qcode{"verticalalignment"} to position the text inside the box.

Finally, the @qcode{"fitboxtotext"} property controls the actual extent of
the box.  If @qcode{"on"} (the default) the box limits are fitted to the
text extent.

@item @qcode{"rectangle"}
Construct a rectangle.  @var{pos} specifies the @qcode{"position"} property
of the annotation.

You may use @qcode{"facecolor"}, @qcode{"color"}, @qcode{"linestyle"}, and
@qcode{"linewidth"} properties to customize the rectangle background color
and edge appearance.

@item @qcode{"ellipse"}
Construct an ellipse.  @var{pos} specifies the @qcode{"position"} property
of the annotation.

See @qcode{"rectangle"} annotations for customization.
@end table

@xseealso{xlabel, ylabel, zlabel, title, text, gtext, legend, colorbar}
@end deftypefn
axis
@c axis scripts/plot/appearance/axis.m
@deftypefn  {} {} axis ()
@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi}])
@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi} @var{y_lo} @var{y_hi}])
@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi} @var{y_lo} @var{y_hi} @var{z_lo} @var{z_hi}])
@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi} @var{y_lo} @var{y_hi} @var{z_lo} @var{z_hi} @var{c_lo} @var{c_hi}])
@deftypefnx {} {} axis (@var{option})
@deftypefnx {} {} axis (@var{option1}, @var{option2}, @dots{})
@deftypefnx {} {} axis (@var{hax}, @dots{})
@deftypefnx {} {@var{limits} =} axis ()
Set axis limits and appearance.

The argument @var{limits} should be a 2-, 4-, 6-, or 8-element vector.  The
first and second elements specify the lower and upper limits for the
x-axis.  The third and fourth specify the limits for the y-axis, the fifth
and sixth specify the limits for the z-axis, and the seventh and eighth
specify the limits for the color axis.  The special values -Inf and Inf may
be used to indicate that the limit should be automatically computed based
on the data in the axes.

Without any arguments, @code{axis} turns autoscaling on.

With one output argument, @code{@var{limits} = axis} returns the current
axis limits.

The vector argument specifying limits is optional, and additional string
arguments may be used to specify various axis properties.

The following options control the aspect ratio of the axes.

@table @asis
@item @qcode{"square"}
Force a square axis aspect ratio.

@item @qcode{"equal"}
Force x-axis unit distance to equal y-axis (and z-axis) unit distance.

@item @qcode{"normal"}
Restore default aspect ratio.
@end table

@noindent
The following options control the way axis limits are interpreted.

@table @asis
@item  @qcode{"auto"}
@itemx @qcode{"auto[xyz]"}
Set the specified axes to have nice limits around the data or all if no
axes are specified.

@item @qcode{"manual"}
Fix the current axes limits.

@item @qcode{"tight"}
Fix axes to the limits of the data.

@item @qcode{"image"}
Equivalent to @qcode{"tight"} and @qcode{"equal"}.

@item @nospell{@qcode{"vis3d"}}
Set aspect ratio modes to @qcode{"manual"} for rotation without stretching.
@end table

@noindent
The following options affect the appearance of tick marks.

@table @asis
@item @qcode{"tic[xyz]"}
Turn tick marks on for all axes, or turn them on for the specified axes and
off for the remainder.

@item @qcode{"label[xyz]"}
Turn tick labels on for all axes, or turn them on for the specified axes
and off for the remainder.

@item @qcode{"nolabel"}
Turn tick labels off for all axes.
@end table

Note: If there are no tick marks for an axes then there can be no labels.

@noindent
The following options affect the direction of increasing values on the axes.

@table @asis
@item @qcode{"xy"}
Default y-axis, larger values are near the top.

@item @qcode{"ij"}
Reverse y-axis, smaller values are near the top.
@end table

@noindent
The following options affects the visibility of the axes.

@table @asis
@item @qcode{"on"}
Make the axes visible.

@item @qcode{"off"}
Hide the axes.
@end table

If the first argument @var{hax} is an axes handle, then operate on this
axes rather than the current axes returned by @code{gca}.

Example 1: set X/Y limits and force a square aspect ratio

@example
axis ([1, 2, 3, 4], "square");
@end example

Example 2: enable tick marks on all axes,
           enable tick mark labels only on the y-axis

@example
axis ("tic", "labely");
@end example

@xseealso{xlim, ylim, zlim, caxis, daspect, pbaspect, box, grid}
@end deftypefn
box
@c box scripts/plot/appearance/box.m
@deftypefn  {} {} box
@deftypefnx {} {} box on
@deftypefnx {} {} box off
@deftypefnx {} {} box (@var{hax}, @dots{})
Control display of the axes border.

The argument may be either @qcode{"on"} or @qcode{"off"}.  If it is
omitted, the current box state is toggled.

If the first argument @var{hax} is an axes handle, then operate on this
axes rather than the current axes returned by @code{gca}.
@xseealso{axis, grid}
@end deftypefn
camlookat
@c camlookat scripts/plot/appearance/camlookat.m
@deftypefn  {} {} camlookat ()
@deftypefnx {} {} camlookat (@var{h})
@deftypefnx {} {} camlookat (@var{handle_list})
@deftypefnx {} {} camlookat (@var{hax})
Move the camera and adjust its properties to look at objects.

When the input is a handle @var{h}, the camera is set to point toward the
center of the bounding box of @var{h}.  The camera's position is adjusted so
the bounding box approximately fills the field of view.

This command fixes the camera's viewing direction
(@code{camtarget() - campos()}), camera up vector (@pxref{XREFcamup,,camup})
and viewing angle (@pxref{XREFcamva,,camva}).  The camera target
(@pxref{XREFcamtarget,,camtarget}) and camera position
(@pxref{XREFcampos,,campos}) are changed.


If the argument is a list @var{handle_list}, then a single bounding box for
all the objects is computed and the camera is then adjusted as above.

If the argument is an axis object @var{hax}, then the children of the axis
are used as @var{handle_list}.  When called with no inputs, it uses the
current axis (@pxref{XREFgca,,gca}).

@xseealso{camorbit, camzoom, camroll}
@end deftypefn
camorbit
@c camorbit scripts/plot/appearance/camorbit.m
@deftypefn  {} {} camorbit (@var{theta}, @var{phi})
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, @var{coorsys})
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, @var{coorsys}, @var{dir})
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data")
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", "z")
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", "x")
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", "y")
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", [@var{x} @var{y} @var{z}])
@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "camera")
@deftypefnx {} {} camorbit (@var{hax}, @dots{})
Rotate the camera up/down and left/right around its target.

Move the camera @var{phi} degrees up and @var{theta} degrees to the right,
as if it were in an orbit around its target.
Example:

@example
@group
@c doctest: +SKIP
sphere ()
camorbit (30, 20)
@end group
@end example

These rotations are centered around the camera target
(@pxref{XREFcamtarget,,camtarget}).
First the camera position is pitched up or down by rotating it @var{phi}
degrees around an axis orthogonal to both the viewing direction
(specifically @code{camtarget() - campos()}) and the camera ``up vector''
(@pxref{XREFcamup,,camup}).
Example:

@example
@group
@c doctest: +SKIP
camorbit (0, 20)
@end group
@end example

The second rotation depends on the coordinate system @var{coorsys} and
direction @var{dir} inputs.
The default for @var{coorsys} is @qcode{"data"}.  In this case, the camera
is yawed left or right by rotating it @var{theta} degrees around an axis
specified by @var{dir}.
The default for @var{dir} is @qcode{"z"}, corresponding to the vector
@code{[0, 0, 1]}.
Example:

@example
@group
@c doctest: +SKIP
camorbit (30, 0)
@end group
@end example

When @var{coorsys} is set to @qcode{"camera"}, the camera is moved left or
right by rotating it around an axis parallel to the camera up vector
(@pxref{XREFcamup,,camup}).
The input @var{dir} should not be specified in this case.
Example:

@example
@group
@c doctest: +SKIP
camorbit (30, 0, "camera")
@end group
@end example

(Note: the rotation by @var{phi} is unaffected by @qcode{"camera"}.)

The @code{camorbit} command modifies two camera properties:
@pxref{XREFcampos,,campos} and @pxref{XREFcamup,,camup}.

By default, this command affects the current axis; alternatively, an axis
can be specified by the optional argument @var{hax}.

@xseealso{camzoom, camroll, camlookat}
@end deftypefn
campos
@c campos scripts/plot/appearance/campos.m
@deftypefn  {} {@var{P} =} campos ()
@deftypefnx {} {} campos ([@var{x} @var{y} @var{z}])
@deftypefnx {} {@var{mode} =} campos ("mode")
@deftypefnx {} {} campos (@var{mode})
@deftypefnx {} {} campos (@var{ax}, @dots{})
Set or get the camera position.

The default camera position is determined automatically based on the scene.
For example, to get the camera position:

@example
@group
hf = figure();
peaks()
p = campos ()
  @result{} p =
      -27.394  -35.701   64.079
@end group
@end example

We can then move the camera further up the z-axis:

@example
@group
campos (p + [0 0 10])
campos ()
  @result{} ans =
      -27.394  -35.701   74.079
@end group
@end example

Having made that change, the camera position @var{mode} is now manual:

@example
@group
campos ("mode")
  @result{} manual
@end group
@end example

We can set it back to automatic:

@example
@group
campos ("auto")
campos ()
  @result{} ans =
      -27.394  -35.701   64.079
close (hf)
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{ax}.

@xseealso{camup, camtarget, camva}
@end deftypefn
camroll
@c camroll scripts/plot/appearance/camroll.m
@deftypefn  {} {} camroll (@var{theta})
@deftypefnx {} {} camroll (@var{ax}, @var{theta})
Roll the camera.

Roll the camera clockwise by @var{theta} degrees.
For example, the following command will roll the camera by
30 degrees clockwise (to the right); this will cause the scene
to appear to roll by 30 degrees to the left:

@example
@group
@c doctest: +SKIP
peaks ()
camroll (30)
@end group
@end example

Roll the camera back:

@example
@group
@c doctest: +SKIP
camroll (-30)
@end group
@end example

The following command restores the default camera roll:

@example
@group
@c doctest: +SKIP
camup ("auto")
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{ax}.

@xseealso{camzoom, camorbit, camlookat, camup}
@end deftypefn
camtarget
@c camtarget scripts/plot/appearance/camtarget.m
@deftypefn  {} {@var{T} =} camtarget ()
@deftypefnx {} {} camtarget ([@var{x} @var{y} @var{z}])
@deftypefnx {} {@var{mode} =} camtarget ("mode")
@deftypefnx {} {} camtarget (@var{mode})
@deftypefnx {} {} camtarget (@var{ax}, @dots{})
Set or get where the camera is pointed.

The camera target is a point in space where the camera is pointing.
Usually, it is determined automatically based on the scene:

@example
@group
hf = figure();
sphere (36)
v = camtarget ()
  @result{} v =
      0   0   0
@end group
@end example

We can turn the camera to point at a new target:

@example
@group
camtarget ([1 1 1])
camtarget ()
  @result{}   1   1   1
@end group
@end example

Having done so, the camera target @var{mode} is manual:

@example
@group
camtarget ("mode")
  @result{} manual
@end group
@end example

This means, for example, adding new objects to the scene will not retarget
the camera:

@example
@group
hold on;
peaks ()
camtarget ()
  @result{}   1   1   1
@end group
@end example

We can reset it to be automatic:

@example
@group
@c doctest: +XFAIL
@c https://savannah.gnu.org/bugs/?44503
camtarget ("auto")
camtarget ()
  @result{}   0   0   0.76426
close (hf)
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{ax}.

@xseealso{campos, camup, camva}
@end deftypefn
camup
@c camup scripts/plot/appearance/camup.m
@deftypefn  {} {@var{up} =} camup ()
@deftypefnx {} {} camup ([@var{x} @var{y} @var{z}])
@deftypefnx {} {@var{mode} =} camup ("mode")
@deftypefnx {} {} camup (@var{mode})
@deftypefnx {} {} camup (@var{ax}, @dots{})
Set or get the camera up vector.

By default, the camera is oriented so that ``up'' corresponds to the
positive z-axis:

@example
@group
hf = figure ();
sphere (36)
v = camup ()
  @result{} v =
      0   0   1
@end group
@end example

Specifying a new ``up vector'' rolls the camera and sets the mode to manual:

@example
@group
camup ([1 1 0])
camup ()
  @result{}   1   1   0
camup ("mode")
  @result{} manual
@end group
@end example

Modifying the up vector does not modify the camera target
(@pxref{XREFcamtarget,,camtarget}).  Thus, the camera up vector might not be
orthogonal to the direction of the camera's view:

@example
@group
camup ([1 2 3])
dot (camup (), camtarget () - campos ())
  @result{} 6...
@end group
@end example

A consequence is that ``pulling back'' on the up vector does not pitch the
camera view (as that would require changing the target).  Setting the up
vector is thus typically used only to roll the camera.  A more intuitive
command for this purpose is @pxref{XREFcamroll,,camroll}.

Finally, we can reset the up vector to automatic mode:

@example
@group
camup ("auto")
camup ()
  @result{}   0   0   1
close (hf)
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{ax}.

@xseealso{campos, camtarget, camva}
@end deftypefn
camva
@c camva scripts/plot/appearance/camva.m
@deftypefn  {} {@var{a} =} camva ()
@deftypefnx {} {} camva (@var{a})
@deftypefnx {} {@var{mode} =} camva ("mode")
@deftypefnx {} {} camva (@var{mode})
@deftypefnx {} {} camva (@var{ax}, @dots{})
Set or get the camera viewing angle.

The camera has a viewing angle which determines how much can be seen.  By
default this is:

@example
@group
hf = figure();
sphere (36)
a = camva ()
  @result{} a =  10.340
@end group
@end example

To get a wider-angle view, we could double the viewing angle.  This will
also set the mode to manual:

@example
@group
camva (2*a)
camva ("mode")
  @result{} manual
@end group
@end example

We can set it back to automatic:

@example
@group
camva ("auto")
camva ("mode")
  @result{} auto
camva ()
  @result{} ans =  10.340
close (hf)
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{ax}.

@xseealso{campos, camtarget, camup}
@end deftypefn
camzoom
@c camzoom scripts/plot/appearance/camzoom.m
@deftypefn  {} {} camzoom (@var{zf})
@deftypefnx {} {} camzoom (@var{ax}, @var{zf})
Zoom the camera in or out.

A value of @var{zf} larger than 1 ``zooms in'' such that the scene appears
magnified:

@example
@group
hf = figure ();
sphere (36)
camzoom (1.2)
@end group
@end example

A value smaller than 1 ``zooms out'' so the camera can see more of the
scene:

@example
@group
camzoom (0.5)
@end group
@end example

Technically speaking, zooming affects the ``viewing angle''.  The following
command resets to the default zoom:

@example
@group
camva ("auto")
close (hf)
@end group
@end example

By default, these commands affect the current axis; alternatively, an axis
can be specified by the optional argument @var{ax}.

@xseealso{camroll, camorbit, camlookat, camva}
@end deftypefn
caxis
@c caxis scripts/plot/appearance/caxis.m
@deftypefn  {} {} caxis ([cmin cmax])
@deftypefnx {} {} caxis ("auto")
@deftypefnx {} {} caxis ("manual")
@deftypefnx {} {} caxis (@var{hax}, @dots{})
@deftypefnx {} {@var{limits} =} caxis ()
Query or set color axis limits for plots.

The limits argument should be a 2-element vector specifying the lower and
upper limits to assign to the first and last value in the colormap.  Data
values outside this range are clamped to the first and last colormap
entries.

If the @qcode{"auto"} option is given then automatic colormap limits are
applied.  The automatic algorithm sets @var{cmin} to the minimum data value
and @var{cmax} to the maximum data value.  If @qcode{"manual"} is specified
then the @qcode{"climmode"} property is set to @qcode{"manual"} and the
numeric values in the @qcode{"clim"} property are used for limits.

If the first argument @var{hax} is an axes handle, then operate on
this axes rather than the current axes returned by @code{gca}.

Called without arguments the current color axis limits are returned.

Programming Note: The color axis affects the display of image, patch, and
surface graphics objects, but @strong{only} if the @qcode{"cdata"} property
has indexed data and the @qcode{"cdatamapping"} property is set to
@qcode{"scaled"}.  Graphic objects with true color @code{cdata}, or
@qcode{"direct"} @code{cdatamapping} are not affected.
@xseealso{colormap, axis}
@end deftypefn
clabel
@c clabel scripts/plot/appearance/clabel.m
@deftypefn  {} {} clabel (@var{c}, @var{h})
@deftypefnx {} {} clabel (@var{c}, @var{h}, @var{v})
@deftypefnx {} {} clabel (@var{c}, @var{h}, "manual")
@deftypefnx {} {} clabel (@var{c})
@deftypefnx {} {} clabel (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@var{h} =} clabel (@dots{})
Add labels to the contours of a contour plot.

The contour levels are specified by the contour matrix @var{c} which is
returned by @code{contour}, @code{contourc}, @code{contourf}, and
@code{contour3}.  Contour labels are rotated to match the local line
orientation and centered on the line.  The position of labels along the
contour line is chosen randomly.

If the argument @var{h} is a handle to a contour group object, then label
this plot rather than the one in the current axes returned by @code{gca}.

By default, all contours are labeled.  However, the contours to label can be
specified by the vector @var{v}.  If the @qcode{"manual"} argument is
given then the contours to label can be selected with the mouse.

Additional property/value pairs that are valid properties of text objects
can be given and are passed to the underlying text objects.  Moreover,
the contour group property @qcode{"LabelSpacing"} is available which
determines the spacing between labels on a contour to be specified.  The
default is 144 points, or 2 inches.

The optional return value @var{h} is a vector of graphics handles to
the text objects representing each label.
The @qcode{"userdata"} property of the text objects contains the numerical
value of the contour label.

An example of the use of @code{clabel} is

@example
@group
[c, h] = contour (peaks (), -4 : 6);
clabel (c, h, -4:2:6, "fontsize", 12);
@end group
@end example

@xseealso{contour, contourf, contour3, meshc, surfc, text}
@end deftypefn
daspect
@c daspect scripts/plot/appearance/daspect.m
@deftypefn  {} {@var{data_aspect_ratio} =} daspect ()
@deftypefnx {} {} daspect (@var{data_aspect_ratio})
@deftypefnx {} {} daspect (@var{mode})
@deftypefnx {} {@var{data_aspect_ratio_mode} =} daspect ("mode")
@deftypefnx {} {} daspect (@var{hax}, @dots{})
Query or set the data aspect ratio of the current axes.

The aspect ratio is a normalized 3-element vector representing the span of
the x, y, and z-axis limits.

@code{daspect (@var{mode})}

Set the data aspect ratio mode of the current axes.  @var{mode} is
either @qcode{"auto"} or @qcode{"manual"}.

@code{daspect (@qcode{"mode"})}

Return the data aspect ratio mode of the current axes.

@code{daspect (@var{hax}, @dots{})}

Operate on the axes in handle @var{hax} instead of the current axes.

@xseealso{axis, pbaspect, xlim, ylim, zlim}
@end deftypefn
datetick
@c datetick scripts/plot/appearance/datetick.m
@deftypefn  {} {} datetick ()
@deftypefnx {} {} datetick (@var{axis_str})
@deftypefnx {} {} datetick (@var{date_format})
@deftypefnx {} {} datetick (@var{axis_str}, @var{date_format})
@deftypefnx {} {} datetick (@dots{}, "keeplimits")
@deftypefnx {} {} datetick (@dots{}, "keepticks")
@deftypefnx {} {} datetick (@var{hax}, @dots{})
Add date-formatted tick labels to an axis.

The axis to apply the ticks to is determined by @var{axis_str} which can
take the values @qcode{"x"}, @qcode{"y"}, or @qcode{"z"}.  The default
value is @qcode{"x"}.

The formatting of the labels is determined by the variable
@var{date_format}, which can either be a string or positive integer that
@code{datestr} accepts.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

@xseealso{datenum, datestr}
@end deftypefn
diffuse
@c diffuse scripts/plot/appearance/diffuse.m
@deftypefn {} {} diffuse (@var{sx}, @var{sy}, @var{sz}, @var{lv})
Calculate the diffuse reflection strength of a surface defined by the normal
vector elements @var{sx}, @var{sy}, @var{sz}.

The light source location vector @var{lv} can be given as a 2-element vector
[azimuth, elevation] in degrees or as a 3-element vector [x, y, z].
@xseealso{specular, surfl}
@end deftypefn
grid
@c grid scripts/plot/appearance/grid.m
@deftypefn  {} {} grid
@deftypefnx {} {} grid on
@deftypefnx {} {} grid off
@deftypefnx {} {} grid minor
@deftypefnx {} {} grid minor on
@deftypefnx {} {} grid minor off
@deftypefnx {} {} grid (@var{hax}, @dots{})
Control the display of plot grid lines.

The function state input may be either @qcode{"on"} or @qcode{"off"}.
If it is omitted, the current grid state is toggled.

When the first argument is @qcode{"minor"} all subsequent commands
modify the minor grid rather than the major grid.

If the first argument @var{hax} is an axes handle, then operate on
this axes rather than the current axes returned by @code{gca}.

To control the grid lines for an individual axes use the @code{set}
function.  For example:

@example
set (gca, "ygrid", "on");
@end example
@xseealso{axis, box}
@end deftypefn
gtext
@c gtext scripts/plot/appearance/gtext.m
@deftypefn  {} {} gtext (@var{s})
@deftypefnx {} {} gtext (@{@var{s1}, @var{s2}, @dots{}@})
@deftypefnx {} {} gtext (@{@var{s1}; @var{s2}; @dots{}@})
@deftypefnx {} {} gtext (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@var{h} =} gtext (@dots{})
Place text on the current figure using the mouse.

The text is defined by the string @var{s}.  If @var{s} is a cell string
organized as a row vector then each string of the cell array is written to a
separate line.  If @var{s} is organized as a column vector then one string
element of the cell array is placed for every mouse click.

Optional property/value pairs are passed directly to the underlying text
objects.

The optional return value @var{h} is a graphics handle to the created
text object(s).
@xseealso{ginput, text}
@end deftypefn
hidden
@c hidden scripts/plot/appearance/hidden.m
@deftypefn  {} {} hidden
@deftypefnx {} {} hidden on
@deftypefnx {} {} hidden off
@deftypefnx {} {@var{mode} =} hidden (@dots{})
Control mesh hidden line removal.

When called with no argument the hidden line removal state is toggled.

When called with one of the modes @qcode{"on"} or @qcode{"off"} the state
is set accordingly.

The optional output argument @var{mode} is the current state.

Hidden Line Removal determines what graphic objects behind a mesh plot
are visible.  The default is for the mesh to be opaque and lines behind
the mesh are not visible.  If hidden line removal is turned off then
objects behind the mesh can be seen through the faces (openings) of the
mesh, although the mesh grid lines are still opaque.

@xseealso{mesh, meshc, meshz, ezmesh, ezmeshc, trimesh, waterfall}
@end deftypefn
legend
@c legend scripts/plot/appearance/legend.m
@deftypefn  {} {} legend ()
@deftypefnx {} {} legend (@var{str1}, @var{str2}, @dots{})
@deftypefnx {} {} legend (@var{charmat})
@deftypefnx {} {} legend (@{@var{cellstr}@})
@deftypefnx {} {} legend (@dots{}, "location", @var{pos})
@deftypefnx {} {} legend (@dots{}, "orientation", @var{orient})
@deftypefnx {} {} legend (@var{hax}, @dots{})
@deftypefnx {} {} legend (@var{hobjs}, @dots{})
@deftypefnx {} {} legend (@var{hax}, @var{hobjs}, @dots{})
@deftypefnx {} {} legend ("@var{option}")
@deftypefnx {} {} legend (@dots{}, @{@var{cellstr}@}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {[@var{hleg}, @var{hleg_obj}, @var{hplot}, @var{labels}] =} legend (@dots{})

Display a legend for the current axes using the specified strings as labels.

Legend entries may be specified as individual character string arguments,
a character array, or a cell array of character strings.  When label names
might be confused with options to @code{legend}, the labels should be
protected by specifying them as a cell array of strings.

If the first argument @var{hax} is an axes handle, then add a legend to this
axes, rather than the current axes returned by @code{gca}.

Legend labels are associated with the axes' children; The first label is
assigned to the first object that was plotted in the axes, the second label
to the next object plotted, etc.  To label specific data objects, without
labeling all objects, provide their graphic handles in the input
@var{hobjs}.

The optional parameter @var{pos} specifies the location of the legend as
follows:

@multitable @columnfractions 0.06 0.14 0.80
@headitem @tab pos @tab location of the legend
@item @tab north @tab center top
@item @tab south @tab center bottom
@item @tab east @tab right center
@item @tab west @tab left center
@item @tab northeast @tab right top (default)
@item @tab northwest @tab left top
@item @tab southeast @tab right bottom
@item @tab southwest @tab left bottom
@sp 1
@item @tab outside @tab can be appended to any location string @*
@item @tab         @tab which will place the legend outside the axes
@end multitable

The optional parameter @var{orient} determines if the legend elements are
placed vertically or horizontally.  The allowed values are
@qcode{"vertical"} (default) or @qcode{"horizontal"}.

The following customizations are available using @var{option}:

@table @asis
@item @qcode{"show"}
  Show legend on the plot

@item @qcode{"hide"}
  Hide legend on the plot

@item @qcode{"toggle"}
  Toggle between @qcode{"hide"} and @qcode{"show"}

@item @qcode{"boxon"}
  Show a box around legend (default)

@item @qcode{"boxoff"}
  Hide the box around legend

@item @qcode{"right"}
  Place label text to the right of the keys (default)

@item @qcode{"left"}
  Place label text to the left of the keys

@item @qcode{"off"}
  Delete the legend object
@end table

The @code{legend} function creates a graphics object which has various
properties that can be manipulated with @code{get}/@code{set}.
Alternatively, properties can be set directly when calling @code{legend} by
including @var{property}/@var{value} pairs.  If using this calling form, the
labels must be specified as a cell array of strings.

The optional output values are

@table @var
@item hleg
  The graphics handle of the legend object.

@item hleg_obj
  Graphics handles to the text, patch, and line objects which form the
  legend.

@item hplot
  Graphics handles to the plot objects which were used in making the legend.

@item labels
  A cell array of strings of the labels in the legend.
@end table

Implementation Note: The legend label text is either provided in the call to
@code{legend} or is taken from the @code{DisplayName} property of the
graphics objects.  Only data objects, such as line, patch, and surface, have
this property whereas axes, figures, etc.@: do not so they are never present
in a legend.  If no labels or @code{DisplayName} properties are available,
then the label text is simply @qcode{"data1"}, @qcode{"data2"}, @dots{},
@nospell{@qcode{"dataN"}}.  No more than 20 data labels will be
automatically generated.  To label more, call @code{legend} explicitly and
provide all labels.

The legend @code{FontSize} property is initially set to 90% of the axes
@code{FontSize} to which it is attached.  Use @code{set} to override this
if necessary.

A legend is implemented as an additional axes object with the @code{tag}
property set to @qcode{"legend"}.  Properties of the legend object may be
manipulated directly by using @code{set}.
@end deftypefn
lighting
@c lighting scripts/plot/appearance/lighting.m
@deftypefn  {} {} lighting (@var{type})
@deftypefnx {} {} lighting (@var{hax}, @var{type})
Set the lighting of patch or surface graphic objects.

Valid arguments for @var{type} are

@table @asis
@item @qcode{"flat"}
Draw objects with faceted lighting effects.

@item @qcode{"gouraud"}
Draw objects with linear interpolation of the lighting effects between the
vertices.

@item @qcode{"none"}
Draw objects without light and shadow effects.
@end table

If the first argument @var{hax} is an axes handle, then change the lighting
effects of objects in this axes, rather than the current axes returned by
@code{gca}.

The lighting effects are only visible if at least one light object is
present and visible in the same axes.

@xseealso{light, fill, mesh, patch, pcolor, surf, surface, shading}
@end deftypefn
material
@c material scripts/plot/appearance/material.m
@deftypefn  {} {} material shiny
@deftypefnx {} {} material dull
@deftypefnx {} {} material metal
@deftypefnx {} {} material default
@deftypefnx {} {} material ([@var{as}, @var{ds}, @var{ss}])
@deftypefnx {} {} material ([@var{as}, @var{ds}, @var{ss}, @var{se}])
@deftypefnx {} {} material ([@var{as}, @var{ds}, @var{ss}, @var{se}, @var{scr}])
@deftypefnx {} {} material (@var{hlist}, @dots{})
@deftypefnx {} {@var{mtypes} =} material ()
@deftypefnx {} {@var{refl_props} =} material (@var{mtype_string})
Set reflectance properties for the lighting of surfaces and patches.

This function changes the ambient, diffuse, and specular strengths, as well
as the specular exponent and specular color reflectance, of all
@code{patch} and @code{surface} objects in the current axes.  This can be
used to simulate, to some extent, the reflectance properties of certain
materials when used with @code{light}.

When called with a string, the aforementioned properties are set
according to the values in the following table:

@multitable @columnfractions .0 .2 .15 .15 .15 .15 .15 .0
@headitem @tab @var{mtype} @tab ambient- strength @tab diffuse-
strength @tab specular- strength @tab specular- exponent @tab specular-
color- reflectance @tab
@item @tab @qcode{"shiny"} @tab 0.3 @tab 0.6 @tab 0.9 @tab 20 @tab 1.0 @tab
@item @tab @qcode{"dull"} @tab 0.3 @tab 0.8 @tab 0.0 @tab 10 @tab 1.0 @tab
@item @tab @qcode{"metal"} @tab 0.3 @tab 0.3 @tab 1.0 @tab 25 @tab 0.5 @tab
@item @tab @qcode{"default"} @tab @qcode{"default"} @tab @qcode{"default"} @tab @qcode{"default"} @tab
@qcode{"default"} @tab @qcode{"default"} @tab
@end multitable

When called with a vector of three elements, the ambient, diffuse, and
specular strengths of all @code{patch} and @code{surface} objects in the
current axes are updated.  An optional fourth vector element updates the
specular exponent, and an optional fifth vector element updates the
specular color reflectance.

A list of graphic handles can also be passed as the first argument.  In
this case, the properties of these handles and all child @code{patch} and
@code{surface} objects will be updated.

Additionally, @code{material} can be called with a single output argument.
If called without input arguments, a column cell vector @var{mtypes} with
the strings for all available materials is returned.  If the one input
argument @var{mtype_string} is the name of a material, a 1x5 cell vector
@var{refl_props} with the reflectance properties of that material is
returned.  In both cases, no graphic properties are changed.

@xseealso{light, fill, mesh, patch, pcolor, surf, surface}
@end deftypefn
orient
@c orient scripts/plot/appearance/orient.m
@deftypefn  {} {} orient (@var{orientation})
@deftypefnx {} {} orient (@var{hfig}, @var{orientation})
@deftypefnx {} {@var{orientation} =} orient ()
@deftypefnx {} {@var{orientation} =} orient (@var{hfig})
Query or set the print orientation for figure @var{hfig}.

Valid values for @var{orientation} are @qcode{"portrait"},
@qcode{"landscape"}, and @qcode{"tall"}.

The @qcode{"landscape"} option changes the orientation so the plot width
is larger than the plot height.  The @qcode{"paperposition"} is also
modified so that the plot fills the page, while leaving a 0.25 inch border.

The @qcode{"tall"} option sets the orientation to @qcode{"portrait"} and
fills the page with the plot, while leaving a 0.25 inch border.

The @qcode{"portrait"} option (default) changes the orientation so the plot
height is larger than the plot width.  It also restores the default
@qcode{"paperposition"} property.

When called with no arguments, return the current print orientation.

If the argument @var{hfig} is omitted, then operate on the current figure
returned by @code{gcf}.
@xseealso{print, saveas}
@end deftypefn
pbaspect
@c pbaspect scripts/plot/appearance/pbaspect.m
@deftypefn  {} {@var{plot_box_aspect_ratio} =} pbaspect ( )
@deftypefnx {} {} pbaspect (@var{plot_box_aspect_ratio})
@deftypefnx {} {} pbaspect (@var{mode})
@deftypefnx {} {@var{plot_box_aspect_ratio_mode} =} pbaspect ("mode")
@deftypefnx {} {} pbaspect (@var{hax}, @dots{})

Query or set the plot box aspect ratio of the current axes.

The aspect ratio is a normalized 3-element vector representing the rendered
lengths of the x, y, and z axes.

@code{pbaspect(@var{mode})}

Set the plot box aspect ratio mode of the current axes.  @var{mode} is
either @qcode{"auto"} or @qcode{"manual"}.

@code{pbaspect ("mode")}

Return the plot box aspect ratio mode of the current axes.

@code{pbaspect (@var{hax}, @dots{})}

Operate on the axes in handle @var{hax} instead of the current axes.

@xseealso{axis, daspect, xlim, ylim, zlim}
@end deftypefn
rticks
@c rticks scripts/plot/appearance/rticks.m
@deftypefn  {} {@var{tickval} =} rticks
@deftypefnx {} {} rticks (@var{tickval})
@deftypefnx {} {@dots{} =} rticks (@var{hax}, @dots{})
Query or set the tick values on the r-axis of the current axis.

When called without argument, return the current tick locations as specified
in the @qcode{"rtick"} axes property.  These locations can be changed by
calling @code{rticks} with a vector of tick values.  Note: ascending order
is not required.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

Requesting a return value when calling @code{rticks} to set a property value
will result in an error.

NOTE: Octave does not currently implement polaraxes objects.  It is
therefore not possible to query or set a @qcode{"mode"} for the
@qcode{"rtick"} property as can be done with the equivalent functions for
@var{x}, @var{y}, and @var{z} axes.

@xseealso{thetaticks, xticks, yticks, zticks, polar, get, set}
@end deftypefn
shading
@c shading scripts/plot/appearance/shading.m
@deftypefn  {} {} shading (@var{type})
@deftypefnx {} {} shading (@var{hax}, @var{type})
Set the shading of patch or surface graphic objects.

Valid arguments for @var{type} are

@table @asis
@item @qcode{"flat"}
Single colored patches with invisible edges.

@item @qcode{"faceted"}
Single colored patches with black edges.

@item @qcode{"interp"}
Colors between patch vertices are interpolated and the patch edges are
invisible.
@end table

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.
@xseealso{fill, mesh, patch, pcolor, surf, surface, hidden, lighting}
@end deftypefn
specular
@c specular scripts/plot/appearance/specular.m
@deftypefn  {} {} specular (@var{sx}, @var{sy}, @var{sz}, @var{lv}, @var{vv})
@deftypefnx {} {} specular (@var{sx}, @var{sy}, @var{sz}, @var{lv}, @var{vv}, @var{se})
Calculate the specular reflection strength of a surface defined by the
normal vector elements @var{sx}, @var{sy}, @var{sz} using Phong's
approximation.

The light source location and viewer location vectors are specified using
parameters @var{lv} and @var{vv} respectively.  The location vectors can
given as 2-element vectors [azimuth, elevation] in degrees or as 3-element
vectors [x, y, z].

An optional sixth argument specifies the specular exponent (spread)
@var{se}.  If not given, @var{se} defaults to 10.
@xseealso{diffuse, surfl}
@end deftypefn
text
@c text scripts/plot/appearance/text.m
@deftypefn  {} {} text (@var{x}, @var{y}, @var{string})
@deftypefnx {} {} text (@var{x}, @var{y}, @var{z}, @var{string})
@deftypefnx {} {} text (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@var{h} =} text (@dots{})
Create a text object with text @var{string} at position @var{x}, @var{y},
(@var{z}) on the current axes.

Multiple locations can be specified if @var{x}, @var{y}, (@var{z}) are
vectors.  Multiple strings can be specified with a character matrix or
a cell array of strings.

Optional property/value pairs may be used to control the appearance of the
text.

The optional return value @var{h} is a vector of graphics handles to the
created text objects.

Programming Note: The full list of properties is documented at
@ref{Text Properties,,Text Properties}.
@xseealso{gtext, title, xlabel, ylabel, zlabel}
@end deftypefn
thetaticks
@c thetaticks scripts/plot/appearance/thetaticks.m
@deftypefn  {} {@var{tickval} =} thetaticks
@deftypefnx {} {} thetaticks (@var{tickval})
@deftypefnx {} {@dots{} =} thetaticks (@var{hax}, @dots{})
Query or set the tick values on the theta-axis of the current axis.

When called without argument, return the current tick locations as specified
in the @qcode{"ttick"} axes property.  These locations can be changed by
calling @code{thetaticks} with a vector of tick values.  Note: ascending
order is not required.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

Requesting a return value when calling @code{thetaticks} to set a property
value will result in an error.

NOTE: Octave does not currently implement polaraxes objects.  It is
therefore not possible to query or set a @qcode{"mode"} for the
@qcode{"thetatick"} property as can be done with the equivalent functions
for @var{x}, @var{y}, and @var{z} axes.

@xseealso{rticks, xticks, yticks, zticks, polar, get, set}
@end deftypefn
title
@c title scripts/plot/appearance/title.m
@deftypefn  {} {} title (@var{string})
@deftypefnx {} {} title (@var{string}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} title (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} title (@dots{})
Specify the string used as a title for the current axis.

An optional list of @var{property}/@var{value} pairs can be used to change
the appearance of the created title text object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created text
object.
@xseealso{xlabel, ylabel, zlabel, text}
@end deftypefn
view
@c view scripts/plot/appearance/view.m
@deftypefn  {} {} view (@var{azimuth}, @var{elevation})
@deftypefnx {} {} view ([@var{azimuth} @var{elevation}])
@deftypefnx {} {} view ([@var{x} @var{y} @var{z}])
@deftypefnx {} {} view (2)
@deftypefnx {} {} view (3)
@deftypefnx {} {} view (@var{hax}, @dots{})
@deftypefnx {} {[@var{azimuth}, @var{elevation}] =} view ()
Query or set the viewpoint for the current axes.

The parameters @var{azimuth} and @var{elevation} can be given as two
arguments or as 2-element vector.  The viewpoint can also be specified with
Cartesian coordinates @var{x}, @var{y}, and @var{z}.

The call @code{view (2)} sets the viewpoint to @w{@var{azimuth} = 0}
and @w{@var{elevation} = 90}, which is the default for 2-D graphs.

The call @code{view (3)} sets the viewpoint to @w{@var{azimuth} = -37.5}
and @w{@var{elevation} = 30}, which is the default for 3-D graphs.

If the first argument @var{hax} is an axes handle, then operate on
this axes rather than the current axes returned by @code{gca}.

If no inputs are given, return the current @var{azimuth} and
@var{elevation}.
@end deftypefn
whitebg
@c whitebg scripts/plot/appearance/whitebg.m
@deftypefn  {} {} whitebg ()
@deftypefnx {} {} whitebg (@var{color})
@deftypefnx {} {} whitebg ("none")
@deftypefnx {} {} whitebg (@var{hfig})
@deftypefnx {} {} whitebg (@var{hfig}, @var{color})
@deftypefnx {} {} whitebg (@var{hfig}, "none")
Invert the colors in the current color scheme.

The root properties are also inverted such that all subsequent plots will
use the new color scheme.

If the optional argument @var{color} is present then the background color
is set to @var{color} rather than inverted.  @var{color} may be a string
representing one of the eight known colors or an RGB triplet.  The special
string argument @qcode{"none"} restores the plot to the factory default
colors.

If the first argument @var{hfig} is a figure handle or list of figure
handles, then operate on these figures rather than the current figure
returned by @code{gcf}.  The root properties will not be changed unless 0
is in the list of figures.

Programming Note: @code{whitebg} operates by changing the color properties
of the children of the specified figures.  Only objects with a single color
are affected.  For example, a patch with a single @qcode{"FaceColor"} will
be changed, but a patch with shading (@qcode{"interp"}) will not be
modified.  For inversion, the new color is simply the inversion in RGB
space: @code{@var{cnew} = [1-@var{R} 1-@var{G} 1-@var{B}]}.  When a color
is specified, the axes and figure are set to the new color, and the color
of child objects are then adjusted to have some contrast (visibility)
against the new background.
@xseealso{reset, get, set}
@end deftypefn
xlabel
@c xlabel scripts/plot/appearance/xlabel.m
@deftypefn  {} {} xlabel (@var{string})
@deftypefnx {} {} xlabel (@var{string}, @var{property}, @var{val}, @dots{})
@deftypefnx {} {} xlabel (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} xlabel (@dots{})
Specify the string used to label the x-axis of the current axis.

An optional list of @var{property}/@var{value} pairs can be used to change
the properties of the created text label.

If the first argument @var{hax} is an axes handle, then operate on
this axes rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created text
object.
@xseealso{ylabel, zlabel, datetick, title, text}
@end deftypefn
xlim
@c xlim scripts/plot/appearance/xlim.m
@deftypefn  {} {@var{xlimits} =} xlim ()
@deftypefnx {} {@var{xmode} =} xlim ("mode")
@deftypefnx {} {} xlim ([@var{x_lo} @var{x_hi}])
@deftypefnx {} {} xlim ("auto")
@deftypefnx {} {} xlim ("manual")
@deftypefnx {} {} xlim (@var{hax}, @dots{})
Query or set the limits of the x-axis for the current plot.

Called without arguments @code{xlim} returns the x-axis limits of the
current plot.

With the input query @qcode{"mode"}, return the current x-limit calculation
mode which is either @qcode{"auto"} or @qcode{"manual"}.

If passed a 2-element vector [@var{x_lo} @var{x_hi}], the limits of the
x-axis are set to these values and the mode is set to @qcode{"manual"}.
The special values -Inf and Inf can be used to indicate that either
the lower axis limit or upper axis limit should be automatically calculated.

The current plotting mode can be changed by using either @qcode{"auto"}
or @qcode{"manual"} as the argument.

If the first argument @var{hax} is an axes handle, then operate on
this axes rather than the current axes returned by @code{gca}.

Programming Note: The @code{xlim} function operates by modifying the
@qcode{"xlim"} and @qcode{"xlimmode"} properties of an axes object.  These
properties can be directly inspected and altered with @code{get}/@code{set}.
@xseealso{ylim, zlim, axis, set, get, gca}
@end deftypefn
xticks
@c xticks scripts/plot/appearance/xticks.m
@deftypefn  {} {@var{tickval} =} xticks
@deftypefnx {} {@var{mode} =} xticks ("mode")
@deftypefnx {} {} xticks (@var{tickval})
@deftypefnx {} {} xticks ("auto")
@deftypefnx {} {} xticks ("manual")
@deftypefnx {} {@dots{} =} xticks (@var{hax}, @dots{})
Query or set the tick values on the x-axis of the current axis.

When called without an argument, return the current tick locations as
specified in the @qcode{"xtick"} axes property.  These locations can be
changed by calling @code{xticks} with a vector of tick values.  Note:
ascending order is not required.

When called with argument @qcode{"mode"}, @code{xticks} returns the current
value of the axes property @qcode{"xtickmode"}.  This property can be
changed by calling @code{xticks} with either @qcode{"auto"} (algorithm
determines tick positions) or @qcode{"manual"} (tick values remain fixed
regardless of axes resizing or rotation).  Note: Specifying xtick values
will also set the property @qcode{"xtickmode"} to @qcode{"manual"}.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

Requesting a return value when calling @code{xticks} to set a property value
will result in an error.

@xseealso{xticklabels, yticks, zticks, rticks, thetaticks, get, set}
@end deftypefn
xticklabels
@c xticklabels scripts/plot/appearance/xticklabels.m
@deftypefn  {} {@var{tickval} =} xticklabels
@deftypefnx {} {@var{mode} =} xticklabels ("mode")
@deftypefnx {} {} xticklabels (@var{tickval})
@deftypefnx {} {} xticklabels ("auto")
@deftypefnx {} {} xticklabels ("manual")
@deftypefnx {} {@dots{} =} xticklabels (@var{hax}, @dots{})
Query or set the tick labels on the x-axis of the current axis.

When called without an argument, return a cell array of strings of the
current tick labels as specified in the @qcode{"xticklabel"} axes property.
These labels can be changed by calling @code{xticklabels} with a cell array
of strings.  Note: a vector of numbers will be mapped to a cell array of
strings.  If fewer labels are specified than the current number of ticks,
blank labels will be appended to the array.

When called with argument @qcode{"mode"}, @code{xticklabels} returns the
current value of the axes property @qcode{"xticklabelmode"}.  This property
can be changed by calling @code{xticklabels} with either @qcode{"auto"}
(algorithm determines tick labels) or @qcode{"manual"} (tick labels remain
fixed).  Note: Specifying xticklabel values will also set the
@qcode{"xticklabelmode"} and @qcode{"xticks"} properties to
@qcode{"manual"}.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

Requesting a return value when calling @code{xticklabels} to set a property
value will result in an error.

@xseealso{xticks, yticklabels, zticklabels, get, set}
@end deftypefn
ylabel
@c ylabel scripts/plot/appearance/ylabel.m
@deftypefn  {} {} ylabel (@var{string})
@deftypefnx {} {} ylabel (@var{string}, @var{property}, @var{val}, @dots{})
@deftypefnx {} {} ylabel (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ylabel (@dots{})
Specify the string used to label the y-axis of the current axis.

If @var{hax} is specified then label the axis defined by @var{hax}.

An optional list of @var{property}/@var{value} pairs can be used to change
the properties of the created text label.

If the first argument @var{hax} is an axes handle, then operate on
this axes rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created text
object.
@xseealso{xlabel, zlabel, datetick, title, text}
@end deftypefn
ylim
@c ylim scripts/plot/appearance/ylim.m
@deftypefn  {} {@var{ylimits} =} ylim ()
@deftypefnx {} {@var{xmode} =} ylim ("mode")
@deftypefnx {} {} ylim ([@var{y_lo} @var{y_hi}])
@deftypefnx {} {} ylim ("auto")
@deftypefnx {} {} ylim ("manual")
@deftypefnx {} {} ylim (@var{hax}, @dots{})
Query or set the limits of the y-axis for the current plot.

Called without arguments @code{ylim} returns the y-axis limits of the
current plot.

With the input query @qcode{"mode"}, return the current y-limit calculation
mode which is either @qcode{"auto"} or @qcode{"manual"}.

If passed a 2-element vector [@var{y_lo} @var{y_hi}], the limits of the
y-axis are set to these values and the mode is set to @qcode{"manual"}.
The special values -Inf and Inf can be used to indicate that either
the lower axis limit or upper axis limit should be automatically calculated.

The current plotting mode can be changed by using either @qcode{"auto"}
or @qcode{"manual"} as the argument.

If the first argument @var{hax} is an axes handle, then operate on
this axes rather than the current axes returned by @code{gca}.

Programming Note: The @code{ylim} function operates by modifying the
@qcode{"ylim"} and @qcode{"ylimmode"} properties of an axes object.  These
properties can be directly inspected and altered with @code{get}/@code{set}.
@xseealso{xlim, zlim, axis, set, get, gca}
@end deftypefn
yticks
@c yticks scripts/plot/appearance/yticks.m
@deftypefn  {} {@var{tickval} =} yticks
@deftypefnx {} {@var{mode} =} yticks ("mode")
@deftypefnx {} {} yticks (@var{tickval})
@deftypefnx {} {} yticks ("auto")
@deftypefnx {} {} yticks ("manual")
@deftypefnx {} {@dots{} =} yticks (@var{hax}, @dots{})
Query or set the tick values on the y-axis of the current axis.

When called without an argument, return the current tick locations as
specified in the @qcode{"ytick"} axes property.  These locations can be
changed by calling @code{yticks} with a vector of tick values.  Note:
ascending order is not required.

When called with argument @qcode{"mode"}, @code{yticks} returns the current
value of the axes property @qcode{"ytickmode"}.  This property can be
changed by calling @code{yticks} with either @qcode{"auto"} (algorithm
determines tick positions) or @qcode{"manual"} (tick values remain fixed
regardless of axes resizing or rotation).  Note: Specifying ytick values
will also set the property @qcode{"ytickmode"} to @qcode{"manual"}.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

Requesting a return value when calling @code{yticks} to set a property value
will result in an error.

@xseealso{yticklabels, xticks, zticks, rticks, thetaticks, get, set}
@end deftypefn
yticklabels
@c yticklabels scripts/plot/appearance/yticklabels.m
@deftypefn  {} {@var{tickval} =} yticklabels
@deftypefnx {} {@var{mode} =} yticklabels ("mode")
@deftypefnx {} {} yticklabels (@var{tickval})
@deftypefnx {} {} yticklabels ("auto")
@deftypefnx {} {} yticklabels ("manual")
@deftypefnx {} {@dots{} =} yticklabels (@var{hax}, @dots{})
Query or set the tick labels on the x-axis of the current axis.

When called without an argument, return a cell array of strings of the
current tick labels as specified in the @qcode{"yticklabel"} axes property.
These labels can be changed by calling @code{yticklabels} with a cell array
of strings.  Note: a vector of numbers will be mapped to a cell array of
strings.  If fewer labels are specified than the current number of ticks,
blank labels will be appended to the array.

When called with argument @qcode{"mode"}, @code{yticklabels} returns the
current value of the axes property @qcode{"yticklabelmode"}.  This property
can be changed by calling @code{yticklabels} with either @qcode{"auto"}
(algorithm determines tick labels) or @qcode{"manual"} (tick labels remain
fixed).  Note: Specifying yticklabel values will also set the
@qcode{"yticklabelmode"} and @qcode{"yticks"} properties to
@qcode{"manual"}.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

Requesting a return value when calling @code{xticklabels} to set a property
value will result in an error.

@xseealso{yticks, xticklabels, zticklabels, get, set}
@end deftypefn
zlabel
@c zlabel scripts/plot/appearance/zlabel.m
@deftypefn  {} {} zlabel (@var{string})
@deftypefnx {} {} zlabel (@var{string}, @var{property}, @var{val}, @dots{})
@deftypefnx {} {} zlabel (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} zlabel (@dots{})
Specify the string used to label the z-axis of the current axis.

An optional list of @var{property}/@var{value} pairs can be used to change
the properties of the created text label.

If the first argument @var{hax} is an axes handle, then operate on
this axes rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created text
object.
@xseealso{xlabel, ylabel, datetick, title, text}
@end deftypefn
Author: jwe
zlim
@c zlim scripts/plot/appearance/zlim.m
@deftypefn  {} {@var{zlimits} =} zlim ()
@deftypefnx {} {@var{xmode} =} zlim ("mode")
@deftypefnx {} {} zlim ([@var{z_lo} @var{z_hi}])
@deftypefnx {} {} zlim ("auto")
@deftypefnx {} {} zlim ("manual")
@deftypefnx {} {} zlim (@var{hax}, @dots{})
Query or set the limits of the z-axis for the current plot.

Called without arguments @code{zlim} returns the z-axis limits of the
current plot.

With the input query @qcode{"mode"}, return the current z-limit calculation
mode which is either @qcode{"auto"} or @qcode{"manual"}.

If passed a 2-element vector [@var{z_lo} @var{z_hi}], the limits of the
z-axis are set to these values and the mode is set to @qcode{"manual"}.
The special values -Inf and Inf can be used to indicate that either
the lower axis limit or upper axis limit should be automatically calculated.

The current plotting mode can be changed by using either @qcode{"auto"}
or @qcode{"manual"} as the argument.

If the first argument @var{hax} is an axes handle, then operate on
this axes rather than the current axes returned by @code{gca}.

Programming Note: The @code{zlim} function operates by modifying the
@qcode{"zlim"} and @qcode{"zlimmode"} properties of an axes object.  These
properties can be directly inspected and altered with @code{get}/@code{set}.
@xseealso{xlim, ylim, axis, set, get, gca}
@end deftypefn
zticks
@c zticks scripts/plot/appearance/zticks.m
@deftypefn  {} {@var{tickval} =} zticks
@deftypefnx {} {@var{mode} =} zticks ("mode")
@deftypefnx {} {} zticks (@var{tickval})
@deftypefnx {} {} zticks ("auto")
@deftypefnx {} {} zticks ("manual")
@deftypefnx {} {@dots{} =} zticks (@var{hax}, @dots{})
Query or set the tick values on the z-axis of the current axis.

When called without an argument, return the current tick locations as
specified in the @qcode{"ztick"} axes property.  These locations can be
changed by calling @code{zticks} with a vector of tick values.  Note:
ascending order is not required.

When called with argument @qcode{"mode"}, @code{zticks} returns the current
value of the axes property @qcode{"ztickmode"}.  This property can be
changed by calling @code{zticks} with either @qcode{"auto"} (algorithm
determines tick positions) or @qcode{"manual"} (tick values remain fixed
regardless of axes resizing or rotation).  Note: Specifying ztick values
will also set the property @qcode{"ztickmode"} to @qcode{"manual"}.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

Requesting a return value when calling @code{zticks} to set a property value
will result in an error.

@xseealso{zticklabels, xticks, yticks, rticks, thetaticks, get, set}
@end deftypefn
zticklabels
@c zticklabels scripts/plot/appearance/zticklabels.m
@deftypefn  {} {@var{tickval} =} zticklabels
@deftypefnx {} {@var{mode} =} zticklabels ("mode")
@deftypefnx {} {} zticklabels (@var{tickval})
@deftypefnx {} {} zticklabels ("auto")
@deftypefnx {} {} zticklabels ("manual")
@deftypefnx {} {@dots{} =} zticklabels (@var{hax}, @dots{})
Query or set the tick labels on the x-axis of the current axis.

When called without an argument, return a cell array of strings of the
current tick labels as specified in the @qcode{"zticklabel"} axes property.
These labels can be changed by calling @code{zticklabels} with a cell array
of strings.  Note: a vector of numbers will be mapped to a cell array of
strings.  If fewer labels are specified than the current number of ticks,
blank labels will be appended to the array.

When called with argument @qcode{"mode"}, @code{zticklabels} returns the
current value of the axes property @qcode{"zticklabelmode"}.  This property
can be changed by calling @code{zticklabels} with either @qcode{"auto"}
(algorithm determines tick labels) or @qcode{"manual"} (tick labels remain
fixed).  Note: Specifying zticklabel values will also set the
@qcode{"zticklabelmode"} and @qcode{"zticks"} properties to
@qcode{"manual"}.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

Requesting a return value when calling @code{xticklabels} to set a property
value will result in an error.

@xseealso{zticks, xticklabels, zticklabels, get, set}
@end deftypefn
area
@c area scripts/plot/draw/area.m
@deftypefn  {} {} area (@var{y})
@deftypefnx {} {} area (@var{x}, @var{y})
@deftypefnx {} {} area (@dots{}, @var{lvl})
@deftypefnx {} {} area (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} area (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} area (@dots{})
Area plot of the columns of @var{y}.

This plot shows the contributions of each column value to the row sum.
It is functionally similar to @code{plot (@var{x}, cumsum (@var{y}, 2))},
except that the area under the curve is shaded.

If the @var{x} argument is omitted it defaults to @code{1:rows (@var{y})}.
A value @var{lvl} can be defined that determines where the base level of
the shading under the curve should be defined.  The default level is 0.

Additional property/value pairs are passed directly to the underlying patch
object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the hggroup
object comprising the area patch objects.  The @qcode{"BaseValue"} property
of the hggroup can be used to adjust the level where shading begins.

Example: Verify identity sin^2 + cos^2 = 1

@example
@group
t = linspace (0, 2*pi, 100)';
y = [sin(t).^2, cos(t).^2];
area (t, y);
legend ("sin^2", "cos^2", "location", "NorthEastOutside");
@end group
@end example
@xseealso{plot, patch}
@end deftypefn
bar
@c bar scripts/plot/draw/bar.m
@deftypefn  {} {} bar (@var{y})
@deftypefnx {} {} bar (@var{x}, @var{y})
@deftypefnx {} {} bar (@dots{}, @var{w})
@deftypefnx {} {} bar (@dots{}, @var{style})
@deftypefnx {} {} bar (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} bar (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} bar (@dots{}, @var{prop}, @var{val}, @dots{})
Produce a bar graph from two vectors of X-Y data.

If only one argument is given, @var{y}, it is taken as a vector of Y values
and the X coordinates are the range @code{1:numel (@var{y})}.

The optional input @var{w} controls the width of the bars.  A value of
1.0 will cause each bar to exactly touch any adjacent bars.
The default width is 0.8.

If @var{y} is a matrix, then each column of @var{y} is taken to be a
separate bar graph plotted on the same graph.  By default the columns
are plotted side-by-side.  This behavior can be changed by the @var{style}
argument which can take the following values:

@table @asis
@item @qcode{"grouped"} (default)
Side-by-side bars with a gap between bars and centered over the
X-coordinate.

@item  @qcode{"stacked"}
Bars are stacked so that each X value has a single bar composed of
multiple segments.

@item @qcode{"hist"}
Side-by-side bars with no gap between bars and centered over the
X-coordinate.

@item @qcode{"histc"}
Side-by-side bars with no gap between bars and left-aligned to the
X-coordinate.
@end table

Optional property/value pairs are passed directly to the underlying patch
objects.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of handles to the created
"bar series" hggroups with one handle per column of the variable @var{y}.
This series makes it possible to change a common element in one bar series
object and have the change reflected in the other "bar series".
For example,

@example
@group
h = bar (rand (5, 10));
set (h(1), "basevalue", 0.5);
@end group
@end example

@noindent
changes the position on the base of all of the bar series.

The following example modifies the face and edge colors using
property/value pairs.

@example
bar (randn (1, 100), "facecolor", "r", "edgecolor", "b");
@end example

@noindent
The color of the bars is taken from the figure's colormap, such that

@example
@group
bar (rand (10, 3));
colormap (summer (64));
@end group
@end example

@noindent
will change the colors used for the bars.  The color of bars can also be set
manually using the @qcode{"facecolor"} property as shown below.

@example
@group
h = bar (rand (10, 3));
set (h(1), "facecolor", "r")
set (h(2), "facecolor", "g")
set (h(3), "facecolor", "b")
@end group
@end example

@xseealso{barh, hist, pie, plot, patch}
@end deftypefn
barh
@c barh scripts/plot/draw/barh.m
@deftypefn  {} {} barh (@var{y})
@deftypefnx {} {} barh (@var{x}, @var{y})
@deftypefnx {} {} barh (@dots{}, @var{w})
@deftypefnx {} {} barh (@dots{}, @var{style})
@deftypefnx {} {} barh (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} barh (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} barh (@dots{}, @var{prop}, @var{val}, @dots{})
Produce a horizontal bar graph from two vectors of X-Y data.

If only one argument is given, it is taken as a vector of Y values
and the X coordinates are the range @code{1:numel (@var{y})}.

The optional input @var{w} controls the width of the bars.  A value of
1.0 will cause each bar to exactly touch any adjacent bars.
The default width is 0.8.

If @var{y} is a matrix, then each column of @var{y} is taken to be a
separate bar graph plotted on the same graph.  By default the columns
are plotted side-by-side.  This behavior can be changed by the @var{style}
argument which can take the following values:

@table @asis
@item @qcode{"grouped"} (default)
Side-by-side bars with a gap between bars and centered over the
Y-coordinate.

@item  @qcode{"stacked"}
Bars are stacked so that each Y value has a single bar composed of
multiple segments.

@item @qcode{"hist"}
Side-by-side bars with no gap between bars and centered over the
Y-coordinate.

@item @qcode{"histc"}
Side-by-side bars with no gap between bars and left-aligned to the
Y-coordinate.
@end table

Optional property/value pairs are passed directly to the underlying patch
objects.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
bar series hggroup.  For a description of the use of the
bar series, @pxref{XREFbar,,bar}.
@xseealso{bar, hist, pie, plot, patch}
@end deftypefn
camlight
@c camlight scripts/plot/draw/camlight.m
@deftypefn  {} {} camlight {}
@deftypefnx {} {} camlight right
@deftypefnx {} {} camlight left
@deftypefnx {} {} camlight headlight
@deftypefnx {} {} camlight (@var{az}, @var{el})
@deftypefnx {} {} camlight (@dots{}, @var{style})
@deftypefnx {} {} camlight (@var{hl}, @dots{})
@deftypefnx {} {} camlight (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} camlight (@dots{})
Add a light object to a figure using a simple interface.

When called with no arguments, a light object is added to the current plot
and is placed slightly above and to the right of the camera's current
position: this is equivalent to @code{camlight right}.  The commands
@code{camlight left} and @code{camlight headlight} behave similarly with
the placement being either left of the camera position or centered on the
camera position.

For more control, the light position can be specified by an azimuthal
rotation @var{az} and an elevation angle @var{el}, both in degrees,
relative to the current properties of the camera.

The optional string @var{style} specifies whether the light is a local point
source (@qcode{"local"}, the default) or placed at infinite distance
(@qcode{"infinite"}).

If the first argument @var{hl} is a handle to a light object, then act on
this light object rather than creating a new object.

If the first argument @var{hax} is an axes handle, then create a new light
object in this axes, rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the light object.
This can be used to move or further change properties of the light object.

Examples:

Add a light object to a plot

@example
@group
@c doctest: +SKIP
sphere (36);
camlight
@end group
@end example

Position the light source exactly

@example
@group
@c doctest: +SKIP
camlight (45, 30);
@end group
@end example

Here the light is first pitched upwards (@pxref{XREFcamup,,camup}) from the
camera position (@pxref{XREFcampos,,campos}) by 30 degrees.  It is then
yawed by 45 degrees to the right.  Both rotations are centered around the
camera target (@pxref{XREFcamtarget,,camtarget}).

Return a handle to further manipulate the light object

@example
@group
@c doctest: +SKIP
clf
sphere (36);
hl = camlight ("left");
set (hl, "color", "r");
@end group
@end example

@xseealso{light}
@end deftypefn
colorbar
@c colorbar scripts/plot/draw/colorbar.m
@deftypefn  {} {} colorbar
@deftypefnx {} {} colorbar (@dots{}, @var{loc})
@deftypefnx {} {} colorbar (@var{delete_option})
@deftypefnx {} {} colorbar (@var{hcb}, @dots{})
@deftypefnx {} {} colorbar (@var{hax}, @dots{})
@deftypefnx {} {} colorbar (@dots{}, "peer", @var{hax}, @dots{})
@deftypefnx {} {} colorbar (@dots{}, "location", @var{loc}, @dots{})
@deftypefnx {} {} colorbar (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@var{h} =} colorbar (@dots{})
Add a colorbar to the current axes.

A colorbar displays the current colormap along with numerical rulings
so that the color scale can be interpreted.

The optional input @var{loc} determines the location of the colorbar.  If
present, it must be the last argument to @code{colorbar}.  Valid values for
@var{loc} are

@table @asis
@item @qcode{"EastOutside"}
Place the colorbar outside the plot to the right.  This is the default.

@item @qcode{"East"}
Place the colorbar inside the plot to the right.

@item @qcode{"WestOutside"}
Place the colorbar outside the plot to the left.

@item @qcode{"West"}
Place the colorbar inside the plot to the left.

@item @qcode{"NorthOutside"}
Place the colorbar above the plot.

@item @qcode{"North"}
Place the colorbar at the top of the plot.

@item @qcode{"SouthOutside"}
Place the colorbar under the plot.

@item @qcode{"South"}
Place the colorbar at the bottom of the plot.
@end table

To remove a colorbar from a plot use any one of the following keywords for
the @var{delete_option}: @qcode{"off"}, @qcode{"delete"}, @qcode{"hide"}.

If the first argument @var{hax} is an axes handle, then the colorbar is
added to this axes, rather than the current axes returned by @code{gca}.
Alternatively, If the argument @qcode{"peer"} is given, then the following
argument is treated as the axes handle in which to add the colorbar.  The
@qcode{"peer"} calling syntax may be removed in the future and is not
recommended.

If the first argument @var{hcb} is a handle to a colorbar object, then
operate on this colorbar directly.

Additional property/value pairs are passed directly to the underlying axes
object.

The optional return value @var{h} is a graphics handle to the created
colorbar object.

Implementation Note: A colorbar is created as an additional axes object
with the @qcode{"tag"} property set to @qcode{"colorbar"}.  The created
object has the extra property @qcode{"location"} which controls the
positioning of the colorbar.
@xseealso{colormap}
@end deftypefn
comet
@c comet scripts/plot/draw/comet.m
@deftypefn  {} {} comet (@var{y})
@deftypefnx {} {} comet (@var{x}, @var{y})
@deftypefnx {} {} comet (@var{x}, @var{y}, @var{p})
@deftypefnx {} {} comet (@var{hax}, @dots{})
Produce a simple comet style animation along the trajectory provided by
the input coordinate vectors (@var{x}, @var{y}).

If @var{x} is not specified it defaults to the indices of @var{y}.

The speed of the comet may be controlled by @var{p}, which represents the
time each point is displayed before moving to the next one.  The default for
@var{p} is 0.1 seconds.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.
@xseealso{comet3}
@end deftypefn
comet3
@c comet3 scripts/plot/draw/comet3.m
@deftypefn  {} {} comet3 (@var{z})
@deftypefnx {} {} comet3 (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} comet3 (@var{x}, @var{y}, @var{z}, @var{p})
@deftypefnx {} {} comet3 (@var{hax}, @dots{})
Produce a simple comet style animation along the trajectory provided by
the input coordinate vectors (@var{x}, @var{y}, @var{z}).

If only @var{z} is specified then @var{x}, @var{y} default to the indices
of @var{z}.

The speed of the comet may be controlled by @var{p}, which represents the
time each point is displayed before moving to the next one.  The default for
@var{p} is 0.1 seconds.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.
@xseealso{comet}
@end deftypefn
compass
@c compass scripts/plot/draw/compass.m
@deftypefn  {} {} compass (@var{u}, @var{v})
@deftypefnx {} {} compass (@var{z})
@deftypefnx {} {} compass (@dots{}, @var{style})
@deftypefnx {} {} compass (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} compass (@dots{})

Plot the @code{(@var{u}, @var{v})} components of a vector field emanating
from the origin of a polar plot.

The arrow representing each vector has one end at the origin and the tip at
[@var{u}(i), @var{v}(i)].  If a single complex argument @var{z} is given,
then @code{@var{u} = real (@var{z})} and @code{@var{v} = imag (@var{z})}.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to the
line objects representing the drawn vectors.

@example
@group
a = toeplitz ([1;randn(9,1)], [1,randn(1,9)]);
compass (eig (a));
@end group
@end example

@xseealso{polar, feather, quiver, rose, plot}
@end deftypefn
contour
@c contour scripts/plot/draw/contour.m
@deftypefn  {} {} contour (@var{z})
@deftypefnx {} {} contour (@var{z}, @var{vn})
@deftypefnx {} {} contour (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} contour (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {} {} contour (@dots{}, @var{style})
@deftypefnx {} {} contour (@var{hax}, @dots{})
@deftypefnx {} {[@var{c}, @var{h}] =} contour (@dots{})
Create a 2-D contour plot.

Plot level curves (contour lines) of the matrix @var{z}, using the
contour matrix @var{c} computed by @code{contourc} from the same
arguments; see the latter for their interpretation.

The appearance of contour lines can be defined with a line style @var{style}
in the same manner as @code{plot}.  Only line style and color are used;
Any markers defined by @var{style} are ignored.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional output @var{c} contains the contour levels in @code{contourc}
format.

The optional return value @var{h} is a graphics handle to the hggroup
comprising the contour lines.

Example:

@example
@group
x = 0:3;
y = 0:2;
z = y' * x;
contour (x, y, z, 2:3)
@end group
@end example

@xseealso{ezcontour, contourc, contourf, contour3, clabel, meshc, surfc, caxis, colormap, plot}

@end deftypefn
contour3
@c contour3 scripts/plot/draw/contour3.m
@deftypefn  {} {} contour3 (@var{z})
@deftypefnx {} {} contour3 (@var{z}, @var{vn})
@deftypefnx {} {} contour3 (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} contour3 (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {} {} contour3 (@dots{}, @var{style})
@deftypefnx {} {} contour3 (@var{hax}, @dots{})
@deftypefnx {} {[@var{c}, @var{h}] =} contour3 (@dots{})
Create a 3-D contour plot.

@code{contour3} plots level curves (contour lines) of the matrix @var{z}
at a Z level corresponding to each contour.  This is in contrast to
@code{contour} which plots all of the contour lines at the same Z level
and produces a 2-D plot.

The level curves are taken from the contour matrix @var{c} computed by
@code{contourc} for the same arguments; see the latter for their
interpretation.

The appearance of contour lines can be defined with a line style @var{style}
in the same manner as @code{plot}.  Only line style and color are used;
Any markers defined by @var{style} are ignored.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional output @var{c} are the contour levels in @code{contourc}
format.

The optional return value @var{h} is a graphics handle to the hggroup
comprising the contour lines.

Example:

@example
@group
contour3 (peaks (19));
colormap cool;
hold on;
surf (peaks (19), "facecolor", "none", "edgecolor", "black");
@end group
@end example

@xseealso{contour, contourc, contourf, clabel, meshc, surfc, caxis, colormap, plot}
@end deftypefn
contourc
@c contourc scripts/plot/draw/contourc.m
@deftypefn  {} {[@var{c}, @var{lev}] =} contourc (@var{z})
@deftypefnx {} {[@var{c}, @var{lev}] =} contourc (@var{z}, @var{vn})
@deftypefnx {} {[@var{c}, @var{lev}] =} contourc (@var{x}, @var{y}, @var{z})
@deftypefnx {} {[@var{c}, @var{lev}] =} contourc (@var{x}, @var{y}, @var{z}, @var{vn})
Compute contour lines (isolines of constant Z value).

The matrix @var{z} contains height values above the rectangular grid
determined by @var{x} and @var{y}.  If only a single input @var{z} is
provided then @var{x} is taken to be @code{1:columns (@var{z})} and @var{y}
is taken to be @code{1:rows (@var{z})}.  The minimum data size is 2x2.

The optional input @var{vn} is either a scalar denoting the number of
contour lines to compute or a vector containing the Z values where lines
will be computed.  When @var{vn} is a vector the number of contour lines
is @code{numel (@var{vn})}.  However, to compute a single contour line
at a given value use @code{@var{vn} = [val, val]}.  If @var{vn} is omitted
it defaults to 10.

The return value @var{c} is a 2x@var{n} matrix containing the
contour lines in the following format

@example
@group
@var{c} = [lev1, x1, x2, @dots{}, levn, x1, x2, ...
     len1, y1, y2, @dots{}, lenn, y1, y2, @dots{}]
@end group
@end example

@noindent
in which contour line @var{n} has a level (height) of @var{levn} and
length of @var{lenn}.

The optional return value @var{lev} is a vector with the Z values of
the contour levels.

Example:

@example
@group
x = 0:2;
y = x;
z = x' * y;
c = contourc (x, y, z, 2:3)
  @result{} c =
        2.0000   1.0000   1.0000   2.0000   2.0000   3.0000   1.5000   2.0000
        4.0000   2.0000   2.0000   1.0000   1.0000   2.0000   2.0000   1.5000
@end group
@end example
@xseealso{contour, contourf, contour3, clabel}
@end deftypefn
contourf
@c contourf scripts/plot/draw/contourf.m
@deftypefn  {} {} contourf (@var{z})
@deftypefnx {} {} contourf (@var{z}, @var{vn})
@deftypefnx {} {} contourf (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} contourf (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {} {} contourf (@dots{}, @var{style})
@deftypefnx {} {} contourf (@var{hax}, @dots{})
@deftypefnx {} {[@var{c}, @var{h}] =} contourf (@dots{})
Create a 2-D contour plot with filled intervals.

Plot level curves (contour lines) of the matrix @var{z} and fill the region
between lines with colors from the current colormap.

The level curves are taken from the contour matrix @var{c} computed by
@code{contourc} for the same arguments; see the latter for their
interpretation.

The appearance of contour lines can be defined with a line style @var{style}
in the same manner as @code{plot}.  Only line style and color are used;
Any markers defined by @var{style} are ignored.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional output @var{c} contains the contour levels in @code{contourc}
format.

The optional return value @var{h} is a graphics handle to the hggroup
comprising the contour lines.

The following example plots filled contours of the @code{peaks} function.

@example
@group
[x, y, z] = peaks (50);
contourf (x, y, z, -7:9)
@end group
@end example
@xseealso{ezcontourf, contour, contourc, contour3, clabel, meshc, surfc, caxis, colormap, plot}
@end deftypefn
cylinder
@c cylinder scripts/plot/draw/cylinder.m
@deftypefn  {} {} cylinder
@deftypefnx {} {} cylinder (@var{r})
@deftypefnx {} {} cylinder (@var{r}, @var{n})
@deftypefnx {} {} cylinder (@var{hax}, @dots{})
@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} cylinder (@dots{})
Plot a 3-D unit cylinder.

The optional input @var{r} is a vector specifying the radius along the
unit z-axis.  The default is [1 1] indicating radius 1 at @code{Z == 0}
and at @code{Z == 1}.

The optional input @var{n} determines the number of faces around the
circumference of the cylinder.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

If outputs are requested @code{cylinder} returns three matrices in
@code{meshgrid} format, such that @code{surf (@var{x}, @var{y}, @var{z})}
generates a unit cylinder.

Example:

@example
@group
[x, y, z] = cylinder (10:-1:0, 50);
surf (x, y, z);
title ("a cone");
@end group
@end example
@xseealso{ellipsoid, rectangle, sphere}
@end deftypefn
ellipsoid
@c ellipsoid scripts/plot/draw/ellipsoid.m
@deftypefn  {} {} ellipsoid (@var{xc}, @var{yc}, @var{zc}, @var{xr}, @var{yr}, @var{zr}, @var{n})
@deftypefnx {} {} ellipsoid (@dots{}, @var{n})
@deftypefnx {} {} ellipsoid (@var{hax}, @dots{})
@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} ellipsoid (@dots{})
Plot a 3-D ellipsoid.

The inputs @var{xc}, @var{yc}, @var{zc} specify the center of the ellipsoid.
The inputs @var{xr}, @var{yr}, @var{zr} specify the semi-major axis lengths.

The optional input @var{n} determines the number of faces around the
circumference of the cylinder.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

If outputs are requested @code{ellipsoid} returns three matrices in
@code{meshgrid} format, such that @code{surf (@var{x}, @var{y}, @var{z})}
generates the ellipsoid.
@xseealso{cylinder, rectangle, sphere}
@end deftypefn
errorbar
@c errorbar scripts/plot/draw/errorbar.m
@deftypefn  {} {} errorbar (@var{y}, @var{ey})
@deftypefnx {} {} errorbar (@var{y}, @dots{}, @var{fmt})
@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{ey})
@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {} {} errorbar (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {} {} errorbar (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} errorbar (@dots{})
Create a 2-D plot with errorbars.

Many different combinations of arguments are possible.  The simplest form is

@example
errorbar (@var{y}, @var{ey})
@end example

@noindent
where the first argument is taken as the set of @var{y} coordinates, the
second argument @var{ey} are the errors around the @var{y} values, and the
@var{x} coordinates are taken to be the indices of the elements
(@code{1:numel (@var{y})}).

The general form of the function is

@example
errorbar (@var{x}, @var{y}, @var{err1}, @dots{}, @var{fmt}, @dots{})
@end example

@noindent
After the @var{x} and @var{y} arguments there can be 1, 2, or 4
parameters specifying the error values depending on the nature of the error
values and the plot format @var{fmt}.

@table @asis
@item @var{err} (scalar)
When the error is a scalar all points share the same error value.
The errorbars are symmetric and are drawn from @var{data}-@var{err} to
@var{data}+@var{err}.
The @var{fmt} argument determines whether @var{err} is in the x-direction,
y-direction (default), or both.

@item @var{err} (vector or matrix)
Each data point has a particular error value.
The errorbars are symmetric and are drawn from @var{data}(n)-@var{err}(n) to
@var{data}(n)+@var{err}(n).

@item @var{lerr}, @var{uerr} (scalar)
The errors have a single low-side value and a single upper-side value.
The errorbars are not symmetric and are drawn from @var{data}-@var{lerr} to
@var{data}+@var{uerr}.

@item @var{lerr}, @var{uerr} (vector or matrix)
Each data point has a low-side error and an upper-side error.
The errorbars are not symmetric and are drawn from
@var{data}(n)-@var{lerr}(n) to @var{data}(n)+@var{uerr}(n).
@end table

Any number of data sets (@var{x1},@var{y1}, @var{x2},@var{y2}, @dots{}) may
appear as long as they are separated by a format string @var{fmt}.

If @var{y} is a matrix, @var{x} and the error parameters must also be
matrices having the same dimensions.  The columns of @var{y} are plotted
versus the corresponding columns of @var{x} and errorbars are taken from
the corresponding columns of the error parameters.

If @var{fmt} is missing, the yerrorbars ("~") plot style is assumed.

If the @var{fmt} argument is supplied then it is interpreted, as in normal
plots, to specify the line style, marker, and color.  In addition,
@var{fmt} may include an errorbar style which @strong{must precede} the
ordinary format codes.  The following errorbar styles are supported:

@table @samp
@item ~
Set yerrorbars plot style (default).

@item >
Set xerrorbars plot style.

@item ~>
Set xyerrorbars plot style.

@item #~
Set yboxes plot style.

@item #
Set xboxes plot style.

@item #~>
Set xyboxes plot style.
@end table

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a handle to the hggroup object
representing the data plot and errorbars.

Note: For compatibility with @sc{matlab} a line is drawn through all data
points.  However, most scientific errorbar plots are a scatter plot of
points with errorbars.  To accomplish this, add a marker style to the
@var{fmt} argument such as @qcode{"."}.  Alternatively, remove the line
by modifying the returned graphic handle with
@code{set (h, "linestyle", "none")}.

Examples:

@example
errorbar (@var{x}, @var{y}, @var{ex}, ">.r")
@end example

@noindent
produces an xerrorbar plot of @var{y} versus @var{x} with @var{x}
errorbars drawn from @var{x}-@var{ex} to @var{x}+@var{ex}.  The marker
@qcode{"."} is used so no connecting line is drawn and the errorbars
appear in red.

@example
@group
errorbar (@var{x}, @var{y1}, @var{ey}, "~",
          @var{x}, @var{y2}, @var{ly}, @var{uy})
@end group
@end example

@noindent
produces yerrorbar plots with @var{y1} and @var{y2} versus @var{x}.
Errorbars for @var{y1} are drawn from @var{y1}-@var{ey} to
@var{y1}+@var{ey}, errorbars for @var{y2} from @var{y2}-@var{ly} to
@var{y2}+@var{uy}.

@example
@group
errorbar (@var{x}, @var{y}, @var{lx}, @var{ux},
          @var{ly}, @var{uy}, "~>")
@end group
@end example

@noindent
produces an xyerrorbar plot of @var{y} versus @var{x} in which
@var{x} errorbars are drawn from @var{x}-@var{lx} to @var{x}+@var{ux}
and @var{y} errorbars from @var{y}-@var{ly} to @var{y}+@var{uy}.
@xseealso{semilogxerr, semilogyerr, loglogerr, plot}
@end deftypefn
ezcontour
@c ezcontour scripts/plot/draw/ezcontour.m
@deftypefn  {} {} ezcontour (@var{f})
@deftypefnx {} {} ezcontour (@dots{}, @var{dom})
@deftypefnx {} {} ezcontour (@dots{}, @var{n})
@deftypefnx {} {} ezcontour (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ezcontour (@dots{})

Plot the contour lines of a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezcontour (f, [-3, 3]);
@end group
@end example

@xseealso{contour, ezcontourf, ezplot, ezmeshc, ezsurfc}
@end deftypefn
ezcontourf
@c ezcontourf scripts/plot/draw/ezcontourf.m
@deftypefn  {} {} ezcontourf (@var{f})
@deftypefnx {} {} ezcontourf (@dots{}, @var{dom})
@deftypefnx {} {} ezcontourf (@dots{}, @var{n})
@deftypefnx {} {} ezcontourf (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ezcontourf (@dots{})

Plot the filled contour lines of a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezcontourf (f, [-3, 3]);
@end group
@end example

@xseealso{contourf, ezcontour, ezplot, ezmeshc, ezsurfc}
@end deftypefn
ezmesh
@c ezmesh scripts/plot/draw/ezmesh.m
@deftypefn  {} {} ezmesh (@var{f})
@deftypefnx {} {} ezmesh (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {} ezmesh (@dots{}, @var{dom})
@deftypefnx {} {} ezmesh (@dots{}, @var{n})
@deftypefnx {} {} ezmesh (@dots{}, "circ")
@deftypefnx {} {} ezmesh (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ezmesh (@dots{})

Plot the mesh defined by a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If three functions are passed, then plot the parametrically defined
function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}),
@var{fz}(@var{s}, @var{t})]}.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the argument @qcode{"circ"} is given, then the function is plotted over
a disk centered on the middle of the domain @var{dom}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Example 1: 2-argument function

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezmesh (f, [-3, 3]);
@end group
@end example

Example 2: parametrically defined function

@example
@group
fx = @@(s,t) cos (s) .* cos (t);
fy = @@(s,t) sin (s) .* cos (t);
fz = @@(s,t) sin (t);
ezmesh (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20);
@end group
@end example

@xseealso{mesh, ezmeshc, ezplot, ezsurf, ezsurfc, hidden}
@end deftypefn
ezmeshc
@c ezmeshc scripts/plot/draw/ezmeshc.m
@deftypefn  {} {} ezmeshc (@var{f})
@deftypefnx {} {} ezmeshc (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {} ezmeshc (@dots{}, @var{dom})
@deftypefnx {} {} ezmeshc (@dots{}, @var{n})
@deftypefnx {} {} ezmeshc (@dots{}, "circ")
@deftypefnx {} {} ezmeshc (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ezmeshc (@dots{})

Plot the mesh and contour lines defined by a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If three functions are passed, then plot the parametrically defined
function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}),
@var{fz}(@var{s}, @var{t})]}.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the argument @qcode{"circ"} is given, then the function is plotted over
a disk centered on the middle of the domain @var{dom}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle for the created mesh plot and a second handle for the created contour
plot.

Example: 2-argument function

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezmeshc (f, [-3, 3]);
@end group
@end example

@xseealso{meshc, ezmesh, ezplot, ezsurf, ezsurfc, hidden}
@end deftypefn
ezplot
@c ezplot scripts/plot/draw/ezplot.m
@deftypefn  {} {} ezplot (@var{f})
@deftypefnx {} {} ezplot (@var{f2v})
@deftypefnx {} {} ezplot (@var{fx}, @var{fy})
@deftypefnx {} {} ezplot (@dots{}, @var{dom})
@deftypefnx {} {} ezplot (@dots{}, @var{n})
@deftypefnx {} {} ezplot (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ezplot (@dots{})

Plot the 2-D curve defined by the function @var{f}.

The function @var{f} may be a string, inline function, or function handle
and can have either one or two variables.  If @var{f} has one variable, then
the function is plotted over the domain @code{-2*pi < @var{x} < 2*pi}
with 500 points.

If @var{f2v} is a function of two variables then the implicit function
@code{@var{f}(@var{x},@var{y}) = 0} is calculated over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

For example:

@example
ezplot (@@(@var{x}, @var{y}) @var{x}.^2 - @var{y}.^2 - 1)
@end example

If two functions are passed as inputs then the parametric function

@example
@group
@var{x} = @var{fx} (@var{t})
@var{y} = @var{fy} (@var{t})
@end group
@end example

@noindent
is plotted over the domain @code{-2*pi <= @var{t} <= 2*pi} with 500 points.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}, or @var{t} for a parametric plot.  If
@var{dom} is a four element vector, then the minimum and maximum values are
@code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in plotting
the function.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the created line objects.

@xseealso{plot, ezplot3, ezpolar, ezcontour, ezcontourf, ezmesh, ezmeshc, ezsurf, ezsurfc}
@end deftypefn
ezplot3
@c ezplot3 scripts/plot/draw/ezplot3.m
@deftypefn  {} {} ezplot3 (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {} ezplot3 (@dots{}, @var{dom})
@deftypefnx {} {} ezplot3 (@dots{}, @var{n})
@deftypefnx {} {} ezplot3 (@dots{}, "animate")
@deftypefnx {} {} ezplot3 (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ezplot3 (@dots{})

Plot a parametrically defined curve in three dimensions.

@var{fx}, @var{fy}, and @var{fz} are strings, inline functions,
or function handles with one argument defining the function.  By
default the plot is over the domain @code{0 <= @var{t} <= 2*pi}
with 500 points.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of @var{t}.

@var{n} is a scalar defining the number of points to use in plotting the
function.

If the @qcode{"animate"} option is given then the plotting is animated
in the style of @code{comet3}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

@example
@group
fx = @@(t) cos (t);
fy = @@(t) sin (t);
fz = @@(t) t;
ezplot3 (fx, fy, fz, [0, 10*pi], 100);
@end group
@end example

@xseealso{plot3, comet3, ezplot, ezmesh, ezsurf}
@end deftypefn
ezpolar
@c ezpolar scripts/plot/draw/ezpolar.m
@deftypefn  {} {} ezpolar (@var{f})
@deftypefnx {} {} ezpolar (@dots{}, @var{dom})
@deftypefnx {} {} ezpolar (@dots{}, @var{n})
@deftypefnx {} {} ezpolar (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ezpolar (@dots{})

Plot a 2-D function in polar coordinates.

The function @var{f} is a string, inline function, or function handle with
a single argument.  The expected form of the function is
@code{@var{rho} = @var{f}(@var{theta})}.
By default the plot is over the domain @code{0 <= @var{theta} <= 2*pi}
with 500 points.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of @var{theta}.

@var{n} is a scalar defining the number of points to use in plotting
the function.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

@example
ezpolar (@@(t) sin (5/4 * t), [0, 8*pi]);
@end example

@xseealso{polar, ezplot}
@end deftypefn
ezsurf
@c ezsurf scripts/plot/draw/ezsurf.m
@deftypefn  {} {} ezsurf (@var{f})
@deftypefnx {} {} ezsurf (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {} ezsurf (@dots{}, @var{dom})
@deftypefnx {} {} ezsurf (@dots{}, @var{n})
@deftypefnx {} {} ezsurf (@dots{}, "circ")
@deftypefnx {} {} ezsurf (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ezsurf (@dots{})

Plot the surface defined by a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If three functions are passed, then plot the parametrically defined
function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}),
@var{fz}(@var{s}, @var{t})]}.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the argument @qcode{"circ"} is given, then the function is plotted over
a disk centered on the middle of the domain @var{dom}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Example 1: 2-argument function

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezsurf (f, [-3, 3]);
@end group
@end example

Example 2: parametrically defined function

@example
@group
fx = @@(s,t) cos (s) .* cos (t);
fy = @@(s,t) sin (s) .* cos (t);
fz = @@(s,t) sin (t);
ezsurf (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20);
@end group
@end example

@xseealso{surf, ezsurfc, ezplot, ezmesh, ezmeshc, shading}
@end deftypefn
ezsurfc
@c ezsurfc scripts/plot/draw/ezsurfc.m
@deftypefn  {} {} ezsurfc (@var{f})
@deftypefnx {} {} ezsurfc (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {} {} ezsurfc (@dots{}, @var{dom})
@deftypefnx {} {} ezsurfc (@dots{}, @var{n})
@deftypefnx {} {} ezsurfc (@dots{}, "circ")
@deftypefnx {} {} ezsurfc (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ezsurfc (@dots{})

Plot the surface and contour lines defined by a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If three functions are passed, then plot the parametrically defined
function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}),
@var{fz}(@var{s}, @var{t})]}.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the argument @qcode{"circ"} is given, then the function is plotted over
a disk centered on the middle of the domain @var{dom}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle for the created surface plot and a second handle for the created
contour plot.

Example:

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezsurfc (f, [-3, 3]);
@end group
@end example

@xseealso{surfc, ezsurf, ezplot, ezmesh, ezmeshc, shading}
@end deftypefn
feather
@c feather scripts/plot/draw/feather.m
@deftypefn  {} {} feather (@var{u}, @var{v})
@deftypefnx {} {} feather (@var{z})
@deftypefnx {} {} feather (@dots{}, @var{style})
@deftypefnx {} {} feather (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} feather (@dots{})

Plot the @code{(@var{u}, @var{v})} components of a vector field emanating
from equidistant points on the x-axis.

If a single complex argument @var{z} is given, then
@code{@var{u} = real (@var{z})} and @code{@var{v} = imag (@var{z})}.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to the
line objects representing the drawn vectors.

@example
@group
phi = [0 : 15 : 360] * pi/180;
feather (sin (phi), cos (phi));
@end group
@end example

@xseealso{plot, quiver, compass}
@end deftypefn
fill
@c fill scripts/plot/draw/fill.m
@deftypefn  {} {} fill (@var{x}, @var{y}, @var{c})
@deftypefnx {} {} fill (@var{x1}, @var{y1}, @var{c1}, @var{x2}, @var{y2}, @var{c2})
@deftypefnx {} {} fill (@dots{}, @var{prop}, @var{val})
@deftypefnx {} {} fill (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} fill (@dots{})
Create one or more filled 2-D polygons.

The inputs @var{x} and @var{y} are the coordinates of the polygon vertices.
If the inputs are matrices then the rows represent different vertices and
each column produces a different polygon.  @code{fill} will close any open
polygons before plotting.

The input @var{c} determines the color of the polygon.  The simplest form
is a single color specification such as a @code{plot} format or an
RGB-triple.  In this case the polygon(s) will have one unique color.  If
@var{c} is a vector or matrix then the color data is first scaled using
@code{caxis} and then indexed into the current colormap.  A row vector will
color each polygon (a column from matrices @var{x} and @var{y}) with a
single computed color.  A matrix @var{c} of the same size as @var{x} and
@var{y} will compute the color of each vertex and then interpolate the face
color between the vertices.

Multiple property/value pairs for the underlying patch object may be
specified, but they must appear in pairs.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the created patch objects.

Example: red square

@example
@group
vertices = [0 0
            1 0
            1 1
            0 1];
fill (vertices(:,1), vertices(:,2), "r");
axis ([-0.5 1.5, -0.5 1.5])
axis equal
@end group
@end example

@xseealso{patch, caxis, colormap}
@end deftypefn
fplot
@c fplot scripts/plot/draw/fplot.m
@deftypefn  {} {} fplot (@var{fn})
@deftypefnx {} {} fplot (@var{fn}, @var{limits})
@deftypefnx {} {} fplot (@dots{}, @var{tol})
@deftypefnx {} {} fplot (@dots{}, @var{n})
@deftypefnx {} {} fplot (@dots{}, @var{fmt})
@deftypefnx {} {} fplot (@dots{}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} fplot (@var{hax}, @dots{})
@deftypefnx {} {[@var{x}, @var{y}] =} fplot (@dots{})
Plot a function @var{fn} within the range defined by @var{limits}.

@var{fn} is a function handle, inline function, or string containing the
name of the function to evaluate.

The limits of the plot are of the form @w{@code{[@var{xlo}, @var{xhi}]}} or
@w{@code{[@var{xlo}, @var{xhi}, @var{ylo}, @var{yhi}]}}.  If no limits
are specified the default is @code{[-5, 5]}.

The next three arguments are all optional and any number of them may be
given in any order.

@var{tol} is the relative tolerance to use for the plot and defaults
to 2e-3 (.2%).

@var{n} is the minimum number of points to use.  When @var{n} is specified,
the maximum stepsize will be @code{(@var{xhi} - @var{xlo}) / @var{n}}.  More
than @var{n} points may still be used in order to meet the relative
tolerance requirement.

The @var{fmt} argument specifies the linestyle to be used by the plot
command.

Multiple property-value pairs may also be specified, but they must appear
in pairs.  These arguments are applied to the line objects drawn by
@code{plot}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

With no output arguments, the results are immediately plotted.  With two
output arguments, the 2-D plot data is returned.  The data can subsequently
be plotted manually with @code{plot (@var{x}, @var{y})}.

Example:

@example
@group
fplot (@@cos, [0, 2*pi])
fplot ("[cos(x), sin(x)]", [0, 2*pi])
@end group
@end example

Programming Notes:

@code{fplot} works best with continuous functions.  Functions with
discontinuities are unlikely to plot well.  This restriction may be removed
in the future.

@code{fplot} performance is better when the function accepts and returns a
vector argument.  Consider this when writing user-defined functions and use
element-by-element operators such as @code{.*}, @code{./}, etc.  See the
function @code{vectorize} for potentially converting inline or anonymous
functions to vectorized versions.

@xseealso{ezplot, plot, vectorize}
@end deftypefn
hist
@c hist scripts/plot/draw/hist.m
@deftypefn  {} {} hist (@var{y})
@deftypefnx {} {} hist (@var{y}, @var{nbins})
@deftypefnx {} {} hist (@var{y}, @var{x})
@deftypefnx {} {} hist (@var{y}, @var{x}, @var{norm})
@deftypefnx {} {} hist (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} hist (@var{hax}, @dots{})
@deftypefnx {} {[@var{nn}, @var{xx}] =} hist (@dots{})
Produce histogram counts or plots.

With one vector input argument, @var{y}, plot a histogram of the values
with 10 bins.  The range of the histogram bins is determined by the
range of the data (difference between maximum and minimum value in @var{y}).
Extreme values are lumped into the first and last bins.  If @var{y} is a
matrix then plot a histogram where each bin contains one bar per input
column of @var{y}.

If the optional second argument is a scalar, @var{nbins}, it defines the
number of bins.

If the optional second argument is a vector, @var{x}, it defines the centers
of the bins.  The width of the bins is determined from the adjacent values
in the vector.  The total number of bins is @code{numel (@var{x})}.

If a third argument is provided, the histogram is normalized such that
the sum of the bars is equal to @var{norm}.

The histogram's appearance may be modified by specifying property/value
pairs.  For example, the face and edge color may be modified:

@example
@group
hist (randn (1, 100), 25, "facecolor", "r", "edgecolor", "b");
@end group
@end example

@noindent
The histogram's colors also depend upon the current colormap.

@example
@group
hist (rand (10, 3));
colormap (summer ());
@end group
@end example

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

If an output is requested then no plot is made.  Instead, return the values
@var{nn} (numbers of elements) and @var{xx} (bin centers) such that
@code{bar (@var{xx}, @var{nn})} will plot the histogram.

@xseealso{histc, bar, pie, rose}
@end deftypefn
isocaps
@c isocaps scripts/plot/draw/isocaps.m
@deftypefn  {} {@var{fvc} =} isocaps (@var{v}, @var{isoval})
@deftypefnx {} {@var{fvc} =} isocaps (@var{v})
@deftypefnx {} {@var{fvc} =} isocaps (@var{x}, @var{y}, @var{z}, @var{v}, @var{isoval})
@deftypefnx {} {@var{fvc} =} isocaps (@var{x}, @var{y}, @var{z}, @var{v})
@deftypefnx {} {@var{fvc} =} isocaps (@dots{}, @var{which_caps})
@deftypefnx {} {@var{fvc} =} isocaps (@dots{}, @var{which_plane})
@deftypefnx {} {@var{fvc} =} isocaps (@dots{}, @qcode{"verbose"})
@deftypefnx {} {[@var{faces}, @var{vertices}, @var{fvcdata}] =} isocaps (@dots{})
@deftypefnx {} {} isocaps (@dots{})

Create end-caps for isosurfaces of 3-D data.

This function places caps at the open ends of isosurfaces.

The input argument @var{v} is a three-dimensional array that contains data
sampled over a volume.

The input @var{isoval} is a scalar that specifies the value for the
isosurface.  If @var{isoval} is omitted or empty, a @nospell{"good"} value
for an isosurface is determined from @var{v}.

When called with a single output argument, @code{isocaps} returns a
structure array @var{fvc} with the fields: @code{faces}, @code{vertices},
and @code{facevertexcdata}.  The results are computed at the points
@code{[@var{x}, @var{y}, @var{z}] = meshgrid (1:l, 1:m, 1:n)} where
@code{[l, m, n] = size (@var{v})}.  The output @var{fvc} can be used
directly as input to the @code{patch} function.

If called with additional input arguments @var{x}, @var{y}, and @var{z}
that are three-dimensional arrays with the same size as @var{v} or
vectors with lengths corresponding to the dimensions of @var{v}, then the
volume data is taken at the specified points.  If @var{x}, @var{y}, or
@var{z} are empty, the grid corresponds to the indices (@code{1:n}) in
the respective direction (@pxref{XREFmeshgrid,,meshgrid}).

The optional parameter @var{which_caps} can have one of the following
string values which defines how the data will be enclosed:

@table @asis
@item @qcode{"above"}, @qcode{"a"} (default)
for end-caps that enclose the data above @var{isoval}.

@item @qcode{"below"}, @qcode{"b"}
for end-caps that enclose the data below @var{isoval}.
@end table

The optional parameter @var{which_plane} can have one of the following
string values to define which end-cap should be drawn:

@table @asis
@item @qcode{"all"} (default)
for all of the end-caps.

@item @qcode{"xmin"}
for end-caps at the lower x-plane of the data.

@item @qcode{"xmax"}
for end-caps at the upper x-plane of the data.

@item @qcode{"ymin"}
for end-caps at the lower y-plane of the data.

@item @qcode{"ymax"}
for end-caps at the upper y-plane of the data.

@item @qcode{"zmin"}
for end-caps at the lower z-plane of the data.

@item @qcode{"zmax"}
for end-caps at the upper z-plane of the data.
@end table

The string input argument @qcode{"verbose"} is supported for @sc{matlab}
compatibility, but has no effect.

If called with two or three output arguments, the data for faces
@var{faces}, vertices @var{vertices}, and the color data
@var{facevertexcdata} are returned in separate arrays instead of a single
structure.

If called with no output argument, the end-caps are drawn directly in the
current figure with the @code{patch} command.

@xseealso{isosurface, isonormals, patch}
@end deftypefn
isocolors
@c isocolors scripts/plot/draw/isocolors.m
@deftypefn  {} {@var{cdat} =} isocolors (@var{c}, @var{v})
@deftypefnx {} {@var{cdat} =} isocolors (@var{x}, @var{y}, @var{z}, @var{c}, @var{v})
@deftypefnx {} {@var{cdat} =} isocolors (@var{x}, @var{y}, @var{z}, @var{r}, @var{g}, @var{b}, @var{v})
@deftypefnx {} {@var{cdat} =} isocolors (@var{r}, @var{g}, @var{b}, @var{v})
@deftypefnx {} {@var{cdat} =} isocolors (@dots{}, @var{p})
@deftypefnx {} {} isocolors (@dots{})

Compute isosurface colors.

If called with one output argument, and the first input argument @var{c}
is a three-dimensional array that contains indexed color values, and the
second input argument @var{v} are the vertices of an isosurface geometry,
then return a matrix @var{cdat} with color data information for the geometry
at computed points @code{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}.  The output
argument @var{cdat} can be used to manually set the
@qcode{"FaceVertexCData"} property of an isosurface patch object.

If called with additional input arguments @var{x}, @var{y} and @var{z} which
are three-dimensional arrays of the same size as @var{c} then the
color data is taken at those specified points.

Instead of indexed color data @var{c}, @code{isocolors} can also be called
with RGB values @var{r}, @var{g}, @var{b}.  If input arguments @var{x},
@var{y}, @var{z} are not given then @code{meshgrid} computed values are
used.

Optionally, a patch handle @var{p} can be given as the last input argument
to all function call variations and the vertex data will be extracted
from the isosurface patch object.  Finally, if no output argument is given
then the colors of the patch given by the patch handle @var{p} are changed.

@xseealso{isosurface, isonormals}
@end deftypefn
isonormals
@c isonormals scripts/plot/draw/isonormals.m
@deftypefn  {} {@var{vn} =} isonormals (@var{val}, @var{vert})
@deftypefnx {} {@var{vn} =} isonormals (@var{val}, @var{hp})
@deftypefnx {} {@var{vn} =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{vert})
@deftypefnx {} {@var{vn} =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{hp})
@deftypefnx {} {@var{vn} =} isonormals (@dots{}, "negate")
@deftypefnx {} {} isonormals (@var{val}, @var{hp})
@deftypefnx {} {} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{hp})
@deftypefnx {} {} isonormals (@dots{}, "negate")

Calculate normals to an isosurface.

The vertex normals @var{vn} are calculated from the gradient of the
3-dimensional array @var{val} (size: lxmxn) containing the data for an
isosurface geometry.  The normals point towards smaller values in @var{val}.

If called with one output argument @var{vn}, and the second input argument
@var{vert} holds the vertices of an isosurface, then the normals @var{vn}
are calculated at the vertices @var{vert} on a grid given by
@code{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}.  The output argument
@var{vn} has the same size as @var{vert} and can be used to set the
@qcode{"VertexNormals"} property of the corresponding patch.

If called with additional input arguments @var{x}, @var{y}, and @var{z},
which are 3-dimensional arrays with the same size as @var{val},
then the volume data is taken at these points.  Instead of the vertex data
@var{vert}, a patch handle @var{hp} can be passed to the function.

If the last input argument is the string @qcode{"negate"}, compute the
reverse vector normals of an isosurface geometry (i.e., pointed towards
larger values in @var{val}).

If no output argument is given, the property @qcode{"VertexNormals"} of
the patch associated with the patch handle @var{hp} is changed directly.

@xseealso{isosurface, isocolors, smooth3}
@end deftypefn
isosurface
@c isosurface scripts/plot/draw/isosurface.m
@deftypefn  {} {@var{fv} =} isosurface (@var{v}, @var{isoval})
@deftypefnx {} {@var{fv} =} isosurface (@var{v})
@deftypefnx {} {@var{fv} =} isosurface (@var{x}, @var{y}, @var{z}, @var{v}, @var{isoval})
@deftypefnx {} {@var{fv} =} isosurface (@var{x}, @var{y}, @var{z}, @var{v})
@deftypefnx {} {@var{fvc} =} isosurface (@dots{}, @var{col})
@deftypefnx {} {@var{fv} =} isosurface (@dots{}, "noshare")
@deftypefnx {} {@var{fv} =} isosurface (@dots{}, "verbose")
@deftypefnx {} {[@var{f}, @var{v}] =} isosurface (@dots{})
@deftypefnx {} {[@var{f}, @var{v}, @var{c}] =} isosurface (@dots{})
@deftypefnx {} {} isosurface (@dots{})

Calculate isosurface of 3-D volume data.

An isosurface connects points with the same value and is analogous to a
contour plot, but in three dimensions.

The input argument @var{v} is a three-dimensional array that contains data
sampled over a volume.

The input @var{isoval} is a scalar that specifies the value for the
isosurface.  If @var{isoval} is omitted or empty, a @nospell{"good"} value
for an isosurface is determined from @var{v}.

When called with a single output argument @code{isosurface} returns a
structure array @var{fv} that contains the fields @var{faces} and
@var{vertices} computed at the points
@code{[@var{x}, @var{y}, @var{z}] = meshgrid (1:l, 1:m, 1:n)} where
@code{[l, m, n] = size (@var{v})}.  The output @var{fv} can be
used directly as input to the @code{patch} function.

If called with additional input arguments @var{x}, @var{y}, and @var{z}
that are three-dimensional arrays with the same size as @var{v} or
vectors with lengths corresponding to the dimensions of @var{v}, then the
volume data is taken at the specified points.  If @var{x}, @var{y}, or
@var{z} are empty, the grid corresponds to the indices (@code{1:n}) in
the respective direction (@pxref{XREFmeshgrid,,meshgrid}).

The optional input argument @var{col}, which is a three-dimensional array
of the same size as @var{v}, specifies coloring of the isosurface.  The
color data is interpolated, as necessary, to match @var{isoval}.  The
output structure array, in this case, has the additional field
@var{facevertexcdata}.

If given the string input argument @qcode{"noshare"}, vertices may be
returned multiple times for different faces.  The default behavior is to
eliminate vertices shared by adjacent faces with @code{unique} which may be
time consuming.

The string input argument @qcode{"verbose"} is supported for @sc{matlab}
compatibility, but has no effect.

Any string arguments must be passed after the other arguments.

If called with two or three output arguments, return the information about
the faces @var{f}, vertices @var{v}, and color data @var{c} as separate
arrays instead of a single structure array.

If called with no output argument, the isosurface geometry is directly
plotted with the @code{patch} command and a light object is added to
the axes if not yet present.

For example,

@example
@group
[x, y, z] = meshgrid (1:5, 1:5, 1:5);
v = rand (5, 5, 5);
isosurface (x, y, z, v, .5);
@end group
@end example

@noindent
will directly draw a random isosurface geometry in a graphics window.

An example of an isosurface geometry with different additional coloring:
@c Set example in small font to prevent overfull line

@smallexample
N = 15;    # Increase number of vertices in each direction
iso = .4;  # Change isovalue to .1 to display a sphere
lin = linspace (0, 2, N);
[x, y, z] = meshgrid (lin, lin, lin);
v = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2);
figure ();

subplot (2,2,1); view (-38, 20);
[f, vert] = isosurface (x, y, z, v, iso);
p = patch ("Faces", f, "Vertices", vert, "EdgeColor", "none");
pbaspect ([1 1 1]);
isonormals (x, y, z, v, p)
set (p, "FaceColor", "green", "FaceLighting", "gouraud");
light ("Position", [1 1 5]);

subplot (2,2,2); view (-38, 20);
p = patch ("Faces", f, "Vertices", vert, "EdgeColor", "blue");
pbaspect ([1 1 1]);
isonormals (x, y, z, v, p)
set (p, "FaceColor", "none", "EdgeLighting", "gouraud");
light ("Position", [1 1 5]);

subplot (2,2,3); view (-38, 20);
[f, vert, c] = isosurface (x, y, z, v, iso, y);
p = patch ("Faces", f, "Vertices", vert, "FaceVertexCData", c, ...
           "FaceColor", "interp", "EdgeColor", "none");
pbaspect ([1 1 1]);
isonormals (x, y, z, v, p)
set (p, "FaceLighting", "gouraud");
light ("Position", [1 1 5]);

subplot (2,2,4); view (-38, 20);
p = patch ("Faces", f, "Vertices", vert, "FaceVertexCData", c, ...
           "FaceColor", "interp", "EdgeColor", "blue");
pbaspect ([1 1 1]);
isonormals (x, y, z, v, p)
set (p, "FaceLighting", "gouraud");
light ("Position", [1 1 5]);
@end smallexample

@xseealso{isonormals, isocolors, isocaps, smooth3, reducevolume, reducepatch, patch}
@end deftypefn
light
@c light scripts/plot/draw/light.m
@deftypefn  {} {} light ()
@deftypefnx {} {} light (@dots{}, "@var{prop}", @var{val}, @dots{})
@deftypefnx {} {} light (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} light (@dots{})
Create a light object in the current axes or for axes @var{hax}.

When a light object is present in an axes object, and the properties
@qcode{"EdgeLighting"} or @qcode{"FaceLighting"} of a @code{patch} or
@code{surface} object are set to a value other than @qcode{"none"}, these
objects are drawn with lighting effects.  Supported values for Lighting
properties are @qcode{"none"} (no lighting effects), @qcode{"flat"} (faceted
look of the objects), and @qcode{"gouraud"} (linear interpolation of the
lighting effects between the vertices).  If the lighting mode is set to
@qcode{"flat"}, the @qcode{"FaceNormals"} property is used for lighting.
For @qcode{"gouraud"}, the @qcode{"VertexNormals"} property is used.

Up to eight light objects are supported per axes.  (Implementation
dependent)

Lighting is only supported for OpenGL graphic toolkits (i.e., @qcode{"fltk"}
and @qcode{"qt"}).

A light object has the following properties which alter the appearance of
the plot.

@table @asis
@item @qcode{"Color":} The color of the light can be passed as an
RGB-vector (e.g., @code{[1 0 0]} for red) or as a string (e.g., @qcode{"r"}
for red).  The default color is white (@code{[1 1 1]}).

@item @qcode{"Position":} The direction from which the light emanates as a
1x3-vector.  The default direction is @code{[1 0 1]}.

@item @qcode{"Style":} This string defines whether the light emanates from a
light source at infinite distance (@qcode{"infinite"}) or from a local point
source (@qcode{"local"}).  The default is @qcode{"infinite"}.
@end table

If the first argument @var{hax} is an axes handle, then add the light object
to this axes, rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created light
object.

Programming Note: The full list of properties is documented at
@ref{Light Properties,,Light Properties}.
@xseealso{lighting, material, patch, surface}
@end deftypefn
line
@c line scripts/plot/draw/line.m
@deftypefn  {} {} line ()
@deftypefnx {} {} line (@var{x}, @var{y})
@deftypefnx {} {} line (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} line ("xdata", @var{x}, "ydata", @var{y})
@deftypefnx {} {} line ("xdata", @var{x}, "ydata", @var{y}, "zdata", @var{z})
@deftypefnx {} {} line (@dots{}, @var{property}, @var{value})
@deftypefnx {} {} line (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} line (@dots{})
Create a line object from @var{x} and @var{y} (and possibly @var{z}) and
insert it in the current axes.

In the standard calling form the data @var{x}, @var{y}, and @var{z} may be
scalars, vectors, or matrices.  In the case of matrix inputs, @code{line}
will attempt to orient scalars and vectors so the results can be plotted.
This requires that one of the dimensions of the vector match either the
number of rows or the number of columns of the matrix.

In the low-level calling form (50% higher performance) where the data is
specified by name (@code{line ("xdata", @var{x}, @dots{})}) the data must be
vectors.  If no data is specified (@code{line ()}) then
@w{@code{@var{x} == @var{y} = [0, 1]}}.

Multiple property-value pairs may be specified for the line object, but they
must appear in pairs.

If called with only @var{property}/@var{value} pairs then any unspecified
properties use their default values as specified on the root object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle (or vector of
handles) to the line objects created.

Programming Note: The full list of properties is documented at
@ref{Line Properties,,Line Properties}.

The function @code{line} differs from @code{plot} in that line objects are
inserted in to the current axes without first clearing the plot.
@xseealso{image, patch, rectangle, surface, text}
@end deftypefn
loglog
@c loglog scripts/plot/draw/loglog.m
@deftypefn  {} {} loglog (@var{y})
@deftypefnx {} {} loglog (@var{x}, @var{y})
@deftypefnx {} {} loglog (@var{x}, @var{y}, @var{prop}, @var{value}, @dots{})
@deftypefnx {} {} loglog (@var{x}, @var{y}, @var{fmt})
@deftypefnx {} {} loglog (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} loglog (@dots{})
Produce a 2-D plot using logarithmic scales for both axes.

See the documentation of @code{plot} for a description of the arguments
that @code{loglog} will accept.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.
@xseealso{plot, semilogx, semilogy}
@end deftypefn
loglogerr
@c loglogerr scripts/plot/draw/loglogerr.m
@deftypefn  {} {} loglogerr (@var{y}, @var{ey})
@deftypefnx {} {} loglogerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {} {} loglogerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {} {} loglogerr (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} loglogerr (@dots{})
Produce 2-D plots on a double logarithm axis with errorbars.

Many different combinations of arguments are possible.  The most common
form is

@example
loglogerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a double logarithm plot of @var{y} versus @var{x}
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}.  @xref{XREFerrorbar,,errorbar}, for available
formats and additional information.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.
@xseealso{errorbar, semilogxerr, semilogyerr}
@end deftypefn
mesh
@c mesh scripts/plot/draw/mesh.m
@deftypefn  {} {} mesh (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} mesh (@var{z})
@deftypefnx {} {} mesh (@dots{}, @var{c})
@deftypefnx {} {} mesh (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} mesh (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} mesh (@dots{})
Plot a 3-D wireframe mesh.

The wireframe mesh is plotted using rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@xseealso{ezmesh, meshc, meshz, trimesh, contour, surf, surface, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
meshc
@c meshc scripts/plot/draw/meshc.m
@deftypefn  {} {} meshc (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} meshc (@var{z})
@deftypefnx {} {} meshc (@dots{}, @var{c})
@deftypefnx {} {} meshc (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} meshc (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} meshc (@dots{})
Plot a 3-D wireframe mesh with underlying contour lines.

The wireframe mesh is plotted using rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle to the created surface object and to the created contour plot.

@xseealso{ezmeshc, mesh, meshz, contour, surfc, surface, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
meshz
@c meshz scripts/plot/draw/meshz.m
@deftypefn  {} {} meshz (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} meshz (@var{z})
@deftypefnx {} {} meshz (@dots{}, @var{c})
@deftypefnx {} {} meshz (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} meshz (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} meshz (@dots{})
Plot a 3-D wireframe mesh with a surrounding curtain.

The wireframe mesh is plotted using rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@xseealso{mesh, meshc, contour, surf, surface, waterfall, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
pareto
@c pareto scripts/plot/draw/pareto.m
@deftypefn  {} {} pareto (@var{y})
@deftypefnx {} {} pareto (@var{y}, @var{x})
@deftypefnx {} {} pareto (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} pareto (@dots{})
Draw a Pareto chart.

A Pareto chart is a bar graph that arranges information in such a way
that priorities for process improvement can be established; It organizes
and displays information to show the relative importance of data.  The chart
is similar to the histogram or bar chart, except that the bars are arranged
in decreasing magnitude from left to right along the x-axis.

The fundamental idea (Pareto principle) behind the use of Pareto
diagrams is that the majority of an effect is due to a small subset of the
causes.  For quality improvement, the first few contributing causes
(leftmost bars as presented on the diagram) to a problem usually account for
the majority of the result.  Thus, targeting these "major causes" for
elimination results in the most cost-effective improvement scheme.

Typically only the magnitude data @var{y} is present in which case
@var{x} is taken to be the range @code{1 : length (@var{y})}.  If @var{x}
is given it may be a string array, a cell array of strings, or a numerical
vector.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle for the created bar plot and a second handle for the created line
plot.

An example of the use of @code{pareto} is

@example
@group
Cheese = @{"Cheddar", "Swiss", "Camembert", ...
          "Munster", "Stilton", "Blue"@};
Sold = [105, 30, 70, 10, 15, 20];
pareto (Sold, Cheese);
@end group
@end example
@xseealso{bar, barh, hist, pie, plot}
@end deftypefn
patch
@c patch scripts/plot/draw/patch.m
@deftypefn  {} {} patch ()
@deftypefnx {} {} patch (@var{x}, @var{y}, @var{c})
@deftypefnx {} {} patch (@var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {} {} patch ("Faces", @var{faces}, "Vertices", @var{verts}, @dots{})
@deftypefnx {} {} patch (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} patch (@dots{}, @var{propstruct}, @dots{})
@deftypefnx {} {} patch (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} patch (@dots{})
Create patch object in the current axes with vertices at locations
(@var{x}, @var{y}) and of color @var{c}.

If the vertices are matrices of size @nospell{MxN} then each polygon patch
has M vertices and a total of N polygons will be created.  If some polygons
do not have M vertices use NaN to represent "no vertex".  If the @var{z}
input is present then 3-D patches will be created.

The color argument @var{c} can take many forms.  To create polygons
which all share a single color use a string value (e.g., @qcode{"r"} for
red), a scalar value which is scaled by @code{caxis} and indexed into the
current colormap, or a 3-element RGB vector with the precise TrueColor.

If @var{c} is a vector of length N then the ith polygon will have a color
determined by scaling entry @var{c}(i) according to @code{caxis} and then
indexing into the current colormap.  More complicated coloring situations
require directly manipulating patch property/value pairs.

Instead of specifying polygons by matrices @var{x} and @var{y}, it is
possible to present a unique list of vertices and then a list of polygon
faces created from those vertices.  In this case the
@qcode{"Vertices"} matrix will be an @nospell{Nx2} (2-D patch) or
@nospell{Nx3} (3-D patch).  The @nospell{MxN} @qcode{"Faces"} matrix
describes M polygons having N vertices---each row describes a
single polygon and each column entry is an index into the
@qcode{"Vertices"} matrix to identify a vertex.  The patch object
can be created by directly passing the property/value pairs
@qcode{"Vertices"}/@var{verts}, @qcode{"Faces"}/@var{faces} as
inputs.

Instead of using property/value pairs, any property can be set by passing a
structure @var{propstruct} with the respective field names.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created patch
object.

Programming Note: The full list of properties is documented at
@ref{Patch Properties,,Patch Properties}.  Useful patch properties include:
@qcode{"cdata"}, @qcode{"edgecolor"}, @qcode{"facecolor"}, @qcode{"faces"},
and @qcode{"facevertexcdata"}.
@xseealso{fill, get, set}
@end deftypefn
pcolor
@c pcolor scripts/plot/draw/pcolor.m
@deftypefn  {} {} pcolor (@var{x}, @var{y}, @var{c})
@deftypefnx {} {} pcolor (@var{c})
@deftypefnx {} {} pcolor (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} pcolor (@dots{})
Produce a 2-D density plot.

A @code{pcolor} plot draws rectangles with colors from the matrix @var{c}
over the two-dimensional region represented by the matrices @var{x} and
@var{y}.  @var{x} and @var{y} are the coordinates of the mesh's vertices
and are typically the output of @code{meshgrid}.  If @var{x} and @var{y} are
vectors, then a typical vertex is (@var{x}(j), @var{y}(i), @var{c}(i,j)).
Thus, columns of @var{c} correspond to different @var{x} values and rows
of @var{c} correspond to different @var{y} values.

The values in @var{c} are scaled to span the range of the current
colormap.  Limits may be placed on the color axis by the command
@code{caxis}, or by setting the @code{clim} property of the parent axis.

The face color of each cell of the mesh is determined by interpolating
the values of @var{c} for each of the cell's vertices; Contrast this with
@code{imagesc} which renders one cell for each element of @var{c}.

@code{shading} modifies an attribute determining the manner by which the
face color of each cell is interpolated from the values of @var{c},
and the visibility of the cells' edges.  By default the attribute is
@qcode{"faceted"}, which renders a single color for each cell's face with
the edge visible.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@xseealso{caxis, shading, meshgrid, contour, imagesc}
@end deftypefn
peaks
@c peaks scripts/plot/draw/peaks.m
@deftypefn  {} {} peaks ()
@deftypefnx {} {} peaks (@var{n})
@deftypefnx {} {} peaks (@var{x}, @var{y})
@deftypefnx {} {@var{z} =} peaks (@dots{})
@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} peaks (@dots{})
Plot a function with lots of local maxima and minima.

The function has the form

@tex
$$f(x,y) = 3 (1 - x) ^ 2 e ^ {\left(-x^2 - (y+1)^2\right)} - 10 \left({x \over 5} - x^3 - y^5\right) - {1 \over 3} e^{\left(-(x+1)^2 - y^2\right)}$$
@end tex
@ifnottex
@verbatim
f(x,y) = 3*(1-x)^2*exp(-x^2 - (y+1)^2) ...
         - 10*(x/5 - x^3 - y^5)*exp(-x^2-y^2) ...
         - 1/3*exp(-(x+1)^2 - y^2)
@end verbatim
@end ifnottex

Called without a return argument, @code{peaks} plots the surface of the
above function using @code{surf}.

If @var{n} is a scalar, @code{peaks} plots the value of the above
function on an @var{n}-by-@var{n} mesh over the range [-3,3].  The
default value for @var{n} is 49.

If @var{n} is a vector, then it represents the grid values over which
to calculate the function.  If @var{x} and @var{y} are specified then
the function value is calculated over the specified grid of vertices.

When called with output arguments, return the data for the function
evaluated over the meshgrid.  This can subsequently be plotted with
@code{surf (@var{x}, @var{y}, @var{z})}.

@xseealso{sombrero, meshgrid, mesh, surf}
@end deftypefn
pie
@c pie scripts/plot/draw/pie.m
@deftypefn  {} {} pie (@var{x})
@deftypefnx {} {} pie (@dots{}, @var{explode})
@deftypefnx {} {} pie (@dots{}, @var{labels})
@deftypefnx {} {} pie (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} pie (@dots{})
Plot a 2-D pie chart.

When called with a single vector argument, produce a pie chart of the
elements in @var{x}.  The size of the ith slice is the percentage that the
element @var{x}i represents of the total sum of @var{x}:
@code{pct = @var{x}(i) / sum (@var{x})}.

The optional input @var{explode} is a vector of the same length as @var{x}
that, if nonzero, "explodes" the slice from the pie chart.

The optional input @var{labels} is a cell array of strings of the same
length as @var{x} specifying the label for each slice.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a list of handles to the patch
and text objects generating the plot.

Note: If @code{sum (@var{x}) @leq{} 1} then the elements of @var{x} are
interpreted as percentages directly and are not normalized by @code{sum
(x)}.  Furthermore, if the sum is less than 1 then there will be a missing
slice in the pie plot to represent the missing, unspecified percentage.

@xseealso{pie3, bar, hist, rose}
@end deftypefn
pie3
@c pie3 scripts/plot/draw/pie3.m
@deftypefn  {} {} pie3 (@var{x})
@deftypefnx {} {} pie3 (@dots{}, @var{explode})
@deftypefnx {} {} pie3 (@dots{}, @var{labels})
@deftypefnx {} {} pie3 (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} pie3 (@dots{})
Plot a 3-D pie chart.

Called with a single vector argument, produces a 3-D pie chart of the
elements in @var{x}.  The size of the ith slice is the percentage that the
element @var{x}i represents of the total sum of @var{x}:
@code{pct = @var{x}(i) / sum (@var{x})}.

The optional input @var{explode} is a vector of the same length as @var{x}
that, if nonzero, "explodes" the slice from the pie chart.

The optional input @var{labels} is a cell array of strings of the same
length as @var{x} specifying the label for each slice.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a list of graphics handles to the
patch, surface, and text objects generating the plot.

Note: If @code{sum (@var{x}) @leq{} 1} then the elements of @var{x} are
interpreted as percentages directly and are not normalized by @code{sum
(x)}.  Furthermore, if the sum is less than 1 then there will be a missing
slice in the pie plot to represent the missing, unspecified percentage.

@xseealso{pie, bar, hist, rose}
@end deftypefn
plot
@c plot scripts/plot/draw/plot.m
@deftypefn  {} {} plot (@var{y})
@deftypefnx {} {} plot (@var{x}, @var{y})
@deftypefnx {} {} plot (@var{x}, @var{y}, @var{fmt})
@deftypefnx {} {} plot (@dots{}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} plot (@var{x1}, @var{y1}, @dots{}, @var{xn}, @var{yn})
@deftypefnx {} {} plot (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} plot (@dots{})
Produce 2-D plots.

Many different combinations of arguments are possible.  The simplest
form is

@example
plot (@var{y})
@end example

@noindent
where the argument is taken as the set of @var{y} coordinates and the
@var{x} coordinates are taken to be the range @code{1:numel (@var{y})}.

If more than one argument is given, they are interpreted as

@example
plot (@var{y}, @var{property}, @var{value}, @dots{})
@end example

@noindent
or

@example
plot (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@end example

@noindent
or

@example
plot (@var{x}, @var{y}, @var{fmt}, @dots{})
@end example

@noindent
and so on.  Any number of argument sets may appear.  The @var{x} and
@var{y} values are interpreted as follows:

@itemize @bullet
@item
If a single data argument is supplied, it is taken as the set of @var{y}
coordinates and the @var{x} coordinates are taken to be the indices of
the elements, starting with 1.

@item
If @var{x} and @var{y} are scalars, a single point is plotted.

@item
@code{squeeze()} is applied to arguments with more than two dimensions,
but no more than two singleton dimensions.

@item
If both arguments are vectors, the elements of @var{y} are plotted versus
the elements of @var{x}.

@item
If @var{x} is a vector and @var{y} is a matrix, then
the columns (or rows) of @var{y} are plotted versus @var{x}.
(using whichever combination matches, with columns tried first.)

@item
If the @var{x} is a matrix and @var{y} is a vector,
@var{y} is plotted versus the columns (or rows) of @var{x}.
(using whichever combination matches, with columns tried first.)

@item
If both arguments are matrices, the columns of @var{y} are plotted
versus the columns of @var{x}.  In this case, both matrices must have
the same number of rows and columns and no attempt is made to transpose
the arguments to make the number of rows match.
@end itemize

Multiple property-value pairs may be specified, but they must appear
in pairs.  These arguments are applied to the line objects drawn by
@code{plot}.  Useful properties to modify are @qcode{"linestyle"},
@qcode{"linewidth"}, @qcode{"color"}, @qcode{"marker"},
@qcode{"markersize"}, @qcode{"markeredgecolor"}, @qcode{"markerfacecolor"}.
@xref{Line Properties}.

The @var{fmt} format argument can also be used to control the plot style.
It is a string composed of four optional parts:
"<linestyle><marker><color><;displayname;>".
When a marker is specified, but no linestyle, only the markers are
plotted.  Similarly, if a linestyle is specified, but no marker, then
only lines are drawn.  If both are specified then lines and markers will
be plotted.  If no @var{fmt} and no @var{property}/@var{value} pairs are
given, then the default plot style is solid lines with no markers and the
color determined by the @qcode{"colororder"} property of the current axes.

Format arguments:

@table @asis
@item linestyle

@multitable @columnfractions 0.06 0.94
@item @samp{-}  @tab Use solid lines (default).
@item @samp{--} @tab Use dashed lines.
@item @samp{:}  @tab Use dotted lines.
@item @samp{-.} @tab Use dash-dotted lines.
@end multitable

@item marker

@multitable @columnfractions 0.06 0.94
@item @samp{+} @tab crosshair
@item @samp{o} @tab circle
@item @samp{*} @tab star
@item @samp{.} @tab point
@item @samp{x} @tab cross
@item @samp{s} @tab square
@item @samp{d} @tab diamond
@item @samp{^} @tab upward-facing triangle
@item @samp{v} @tab downward-facing triangle
@item @samp{>} @tab right-facing triangle
@item @samp{<} @tab left-facing triangle
@item @samp{p} @tab pentagram
@item @samp{h} @tab hexagram
@end multitable

@item color

@multitable @columnfractions 0.06 0.94
@item @samp{k} @tab blacK
@item @samp{r} @tab Red
@item @samp{g} @tab Green
@item @samp{b} @tab Blue
@item @samp{y} @tab Yellow
@item @samp{m} @tab Magenta
@item @samp{c} @tab Cyan
@item @samp{w} @tab White
@end multitable

@item @qcode{";displayname;"}
Here @qcode{"displayname"} is the label to use for the plot legend.
@end table

The @var{fmt} argument may also be used to assign legend labels.
To do so, include the desired label between semicolons after the
formatting sequence described above, e.g., @qcode{"+b;Key Title;"}.
Note that the last semicolon is required and Octave will generate
an error if it is left out.

Here are some plot examples:

@example
plot (x, y, "or", x, y2, x, y3, "m", x, y4, "+")
@end example

This command will plot @code{y} with red circles, @code{y2} with solid
lines, @code{y3} with solid magenta lines, and @code{y4} with points
displayed as @samp{+}.

@example
plot (b, "*", "markersize", 10)
@end example

This command will plot the data in the variable @code{b},
with points displayed as @samp{*} and a marker size of 10.

@example
@group
t = 0:0.1:6.3;
plot (t, cos(t), "-;cos(t);", t, sin(t), "-b;sin(t);");
@end group
@end example

This will plot the cosine and sine functions and label them accordingly
in the legend.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the created line objects.

To save a plot, in one of several image formats such as PostScript
or PNG, use the @code{print} command.

@xseealso{axis, box, grid, hold, legend, title, xlabel, ylabel, xlim, ylim, ezplot, errorbar, fplot, line, plot3, polar, loglog, semilogx, semilogy, subplot}
@end deftypefn
plot3
@c plot3 scripts/plot/draw/plot3.m
@deftypefn  {} {} plot3 (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} plot3 (@var{x}, @var{y}, @var{z}, @var{prop}, @var{value}, @dots{})
@deftypefnx {} {} plot3 (@var{x}, @var{y}, @var{z}, @var{fmt})
@deftypefnx {} {} plot3 (@var{x}, @var{cplx})
@deftypefnx {} {} plot3 (@var{cplx})
@deftypefnx {} {} plot3 (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} plot3 (@dots{})
Produce 3-D plots.

Many different combinations of arguments are possible.  The simplest
form is

@example
plot3 (@var{x}, @var{y}, @var{z})
@end example

@noindent
in which the arguments are taken to be the vertices of the points to
be plotted in three dimensions.  If all arguments are vectors of the
same length, then a single continuous line is drawn.  If all arguments
are matrices, then each column of is treated as a separate line.  No attempt
is made to transpose the arguments to make the number of rows match.

If only two arguments are given, as

@example
plot3 (@var{x}, @var{cplx})
@end example

@noindent
the real and imaginary parts of the second argument are used
as the @var{y} and @var{z} coordinates, respectively.

If only one argument is given, as

@example
plot3 (@var{cplx})
@end example

@noindent
the real and imaginary parts of the argument are used as the @var{y}
and @var{z} values, and they are plotted versus their index.

Arguments may also be given in groups of three as

@example
plot3 (@var{x1}, @var{y1}, @var{z1}, @var{x2}, @var{y2}, @var{z2}, @dots{})
@end example

@noindent
in which each set of three arguments is treated as a separate line or
set of lines in three dimensions.

To plot multiple one- or two-argument groups, separate each group
with an empty format string, as

@example
plot3 (@var{x1}, @var{c1}, "", @var{c2}, "", @dots{})
@end example

Multiple property-value pairs may be specified which will affect the line
objects drawn by @code{plot3}.  If the @var{fmt} argument is supplied it
will format the line objects in the same manner as @code{plot}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

@example
@group
z = [0:0.05:5];
plot3 (cos (2*pi*z), sin (2*pi*z), z, ";helix;");
plot3 (z, exp (2i*pi*z), ";complex sinusoid;");
@end group
@end example
@xseealso{ezplot3, plot}
@end deftypefn
plotmatrix
@c plotmatrix scripts/plot/draw/plotmatrix.m
@deftypefn  {} {} plotmatrix (@var{x}, @var{y})
@deftypefnx {} {} plotmatrix (@var{x})
@deftypefnx {} {} plotmatrix (@dots{}, @var{style})
@deftypefnx {} {} plotmatrix (@var{hax}, @dots{})
@deftypefnx {} {[@var{h}, @var{ax}, @var{bigax}, @var{p}, @var{pax}] =} plotmatrix (@dots{})
Scatter plot of the columns of one matrix against another.

Given the arguments @var{x} and @var{y} that have a matching number of
rows, @code{plotmatrix} plots a set of axes corresponding to

@example
plot (@var{x}(:, i), @var{y}(:, j))
@end example

When called with a single argument @var{x} this is equivalent to

@example
plotmatrix (@var{x}, @var{x})
@end example

@noindent
except that the diagonal of the set of axes will be replaced with the
histogram @code{hist (@var{x}(:, i))}.

The marker to use can be changed with the @var{style} argument, that is a
string defining a marker in the same manner as the @code{plot} command.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} provides handles to the individual
graphics objects in the scatter plots, whereas @var{ax} returns the
handles to the scatter plot axes objects.

@var{bigax} is a hidden axes object that surrounds the other axes, such
that the commands @code{xlabel}, @code{title}, etc., will be associated
with this hidden axes.

Finally, @var{p} returns the graphics objects associated with the histogram
and @var{pax} the corresponding axes objects.

Example:

@example
plotmatrix (randn (100, 3), "g+")
@end example

@xseealso{scatter, plot}
@end deftypefn
plotyy
@c plotyy scripts/plot/draw/plotyy.m
@deftypefn  {} {} plotyy (@var{x1}, @var{y1}, @var{x2}, @var{y2})
@deftypefnx {} {} plotyy (@dots{}, @var{fun})
@deftypefnx {} {} plotyy (@dots{}, @var{fun1}, @var{fun2})
@deftypefnx {} {} plotyy (@var{hax}, @dots{})
@deftypefnx {} {[@var{ax}, @var{h1}, @var{h2}] =} plotyy (@dots{})
Plot two sets of data with independent y-axes and a common x-axis.

The arguments @var{x1} and @var{y1} define the arguments for the first plot
and @var{x1} and @var{y2} for the second.

By default the arguments are evaluated with
@code{feval (@@plot, @var{x}, @var{y})}.  However the type of plot can be
modified with the @var{fun} argument, in which case the plots are
generated by @code{feval (@var{fun}, @var{x}, @var{y})}.  @var{fun} can be
a function handle, an inline function, or a string of a function name.

The function to use for each of the plots can be independently defined
with @var{fun1} and @var{fun2}.

If the first argument @var{hax} is an axes handle, then it defines
the principal axes in which to plot the @var{x1} and @var{y1} data.

The return value @var{ax} is a vector with the axes handles of the two
y-axes.  @var{h1} and @var{h2} are handles to the objects generated by the
plot commands.

@example
@group
x = 0:0.1:2*pi;
y1 = sin (x);
y2 = exp (x - 1);
ax = plotyy (x, y1, x - 1, y2, @@plot, @@semilogy);
xlabel ("X");
ylabel (ax(1), "Axis 1");
ylabel (ax(2), "Axis 2");
@end group
@end example
@xseealso{plot}
@end deftypefn
polar
@c polar scripts/plot/draw/polar.m
@deftypefn  {} {} polar (@var{theta}, @var{rho})
@deftypefnx {} {} polar (@var{theta}, @var{rho}, @var{fmt})
@deftypefnx {} {} polar (@var{cplx})
@deftypefnx {} {} polar (@var{cplx}, @var{fmt})
@deftypefnx {} {} polar (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} polar (@dots{})
Create a 2-D plot from polar coordinates @var{theta} and @var{rho}.

The input @var{theta} is assumed to be radians and is converted to degrees
for plotting. If you have degrees then you must convert
(@pxref{XREFcart2pol,,cart2pol}) to radians before passing the data to this
function.

If a single complex input @var{cplx} is given then the real part is used
for @var{theta} and the imaginary part is used for @var{rho}.

The optional argument @var{fmt} specifies the line format in the same way
as @code{plot}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Implementation Note: The polar axis is drawn using line and text objects
encapsulated in an hggroup.  The hggroup properties are linked to the
original axes object such that altering an appearance property, for example
@code{fontname}, will update the polar axis.  Two new properties are
added to the original axes--@code{rtick}, @code{ttick}--which replace
@code{xtick}, @code{ytick}.  The first is a list of tick locations in the
radial (rho) direction; The second is a list of tick locations in the
angular (theta) direction specified in degrees, i.e., in the range 0--359.
@xseealso{rose, compass, plot, cart2pol}
@end deftypefn
quiver
@c quiver scripts/plot/draw/quiver.m
@deftypefn  {} {} quiver (@var{u}, @var{v})
@deftypefnx {} {} quiver (@var{x}, @var{y}, @var{u}, @var{v})
@deftypefnx {} {} quiver (@dots{}, @var{s})
@deftypefnx {} {} quiver (@dots{}, @var{style})
@deftypefnx {} {} quiver (@dots{}, "filled")
@deftypefnx {} {} quiver (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} quiver (@dots{})

Plot a 2-D vector field with arrows.

Plot the (@var{u}, @var{v}) components of a vector field at the grid points
defined by (@var{x}, @var{y}).  If the grid is uniform then @var{x} and
@var{y} can be specified as vectors and @code{meshgrid} is used to create
the 2-D grid.

If @var{x} and @var{y} are not given they are assumed to be
@code{(1:@var{m}, 1:@var{n})} where
@code{[@var{m}, @var{n}] = size (@var{u})}.

The optional input @var{s} is a scalar defining a scaling factor to use for
the arrows of the field relative to the mesh spacing.  A value of 1.0 will
result in the longest vector exactly filling one grid square.  A value of 0
disables all scaling.  The default value is 0.9.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.  If a marker is specified
then the markers are drawn at the origin of the vectors (which are the grid
points defined by @var{x} and @var{y}).  When a marker is specified, the
arrowhead is not drawn.  If the argument @qcode{"filled"} is given then the
markers are filled.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to a quiver object.
A quiver object regroups the components of the quiver plot (body, arrow,
and marker), and allows them to be changed together.

Example:

@example
@group
[x, y] = meshgrid (1:2:20);
h = quiver (x, y, sin (2*pi*x/10), sin (2*pi*y/10));
set (h, "maxheadsize", 0.33);
@end group
@end example

@xseealso{quiver3, compass, feather, plot}
@end deftypefn
quiver3
@c quiver3 scripts/plot/draw/quiver3.m
@deftypefn  {} {} quiver3 (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w})
@deftypefnx {} {} quiver3 (@var{z}, @var{u}, @var{v}, @var{w})
@deftypefnx {} {} quiver3 (@dots{}, @var{s})
@deftypefnx {} {} quiver3 (@dots{}, @var{style})
@deftypefnx {} {} quiver3 (@dots{}, "filled")
@deftypefnx {} {} quiver3 (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} quiver3 (@dots{})

Plot a 3-D vector field with arrows.

Plot the (@var{u}, @var{v}, @var{w}) components of a vector field at the
grid points defined by (@var{x}, @var{y}, @var{z}).  If the grid is uniform
then @var{x}, @var{y}, and @var{z} can be specified as vectors and
@code{meshgrid} is used to create the 3-D grid.

If @var{x} and @var{y} are not given they are assumed to be
@code{(1:@var{m}, 1:@var{n})} where
@code{[@var{m}, @var{n}] = size (@var{u})}.

The optional input @var{s} is a scalar defining a scaling factor to use for
the arrows of the field relative to the mesh spacing.  A value of 1.0 will
result in the longest vector exactly filling one grid cube.  A value of 0
disables all scaling.  The default value is 0.9.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.  If a marker is specified
then the markers are drawn at the origin of the vectors (which are the grid
points defined by @var{x}, @var{y}, @var{z}).  When a marker is specified,
the arrowhead is not drawn.  If the argument @qcode{"filled"} is given then
the markers are filled.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to a quiver object.
A quiver object regroups the components of the quiver plot (body, arrow,
and marker), and allows them to be changed together.

@example
@group
[x, y, z] = peaks (25);
surf (x, y, z);
hold on;
[u, v, w] = surfnorm (x, y, z / 10);
h = quiver3 (x, y, z, u, v, w);
set (h, "maxheadsize", 0.33);
@end group
@end example

@xseealso{quiver, compass, feather, plot}
@end deftypefn
rectangle
@c rectangle scripts/plot/draw/rectangle.m
@deftypefn  {} {} rectangle ()
@deftypefnx {} {} rectangle (@dots{}, "Position", @var{pos})
@deftypefnx {} {} rectangle (@dots{}, "Curvature", @var{curv})
@deftypefnx {} {} rectangle (@dots{}, "EdgeColor", @var{ec})
@deftypefnx {} {} rectangle (@dots{}, "FaceColor", @var{fc})
@deftypefnx {} {} rectangle (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} rectangle (@dots{})
Draw a rectangular patch defined by @var{pos} and @var{curv}.

The variable @code{@var{pos}(1:2)} defines the lower left-hand corner of
the patch and @code{@var{pos}(3:4)} defines its width and height.  By
default, the value of @var{pos} is @code{[0, 0, 1, 1]}.

The variable @var{curv} defines the curvature of the sides of the rectangle
and may be a scalar or two-element vector with values between 0 and 1.
A value of 0 represents no curvature of the side, whereas a value of 1
means that the side is entirely curved into the arc of a circle.
If @var{curv} is a two-element vector, then the first element is the
curvature along the x-axis of the patch and the second along y-axis.

If @var{curv} is a scalar, it represents the curvature of the shorter of the
two sides of the rectangle and the curvature of the other side is defined
by

@example
min (pos(1:2)) / max (pos(1:2)) * curv
@end example

Additional property/value pairs are passed to the underlying patch command.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
rectangle object.
@xseealso{patch, line, cylinder, ellipsoid, sphere}
@end deftypefn
reducepatch
@c reducepatch scripts/plot/draw/reducepatch.m
@deftypefn  {} {@var{reduced_fv} =} reducepatch (@var{fv})
@deftypefnx {} {@var{reduced_fv} =} reducepatch (@var{faces}, @var{vertices})
@deftypefnx {} {@var{reduced_fv} =} reducepatch (@var{patch_handle})
@deftypefnx {} {} reducepatch (@var{patch_handle})
@deftypefnx {} {@var{reduced_fv} =} reducepatch (@dots{}, @var{reduction_factor})
@deftypefnx {} {@var{reduced_fv} =} reducepatch (@dots{}, "fast")
@deftypefnx {} {@var{reduced_fv} =} reducepatch (@dots{}, "verbose")
@deftypefnx {} {[@var{reduced_faces}, @var{reduces_vertices}] =} reducepatch (@dots{})

Reduce the number of faces and vertices in a patch object while retaining
the overall shape of the patch.

The input patch can be represented by a structure @var{fv} with the
fields @code{faces} and @code{vertices}, by two matrices @var{faces} and
@var{vertices} (see, e.g., the result of @code{isosurface}), or by a
handle to a patch object @var{patch_handle} (@pxref{XREFpatch,,patch}).

The number of faces and vertices in the patch is reduced by iteratively
collapsing the shortest edge of the patch to its midpoint (as discussed,
e.g., here:
@url{https://libigl.github.io/libigl/tutorial/tutorial.html#meshdecimation}).

Currently, only patches consisting of triangles are supported.  The
resulting patch also consists only of triangles.

If @code{reducepatch} is called with a handle to a valid patch
@var{patch_handle}, and without any output arguments, then the given
patch is updated immediately.

If the @var{reduction_factor} is omitted, the resulting structure
@var{reduced_fv} includes approximately 50% of the faces of the original
patch.  If @var{reduction_factor} is a fraction between 0 (excluded) and 1
(excluded), a patch with approximately the corresponding fraction of faces
is determined.
If @var{reduction_factor} is an integer greater than or equal to 1, the
resulting patch has approximately @var{reduction_factor} faces.  Depending
on the geometry of the patch, the resulting number of faces can differ from
the given value of @var{reduction_factor}.  This is especially true when
many shared vertices are detected.

For the reduction, it is necessary that vertices of touching faces are
shared.  Shared vertices are detected automatically.  This detection can be
skipped by passing the optional string argument @qcode{"fast"}.

With the optional string arguments @qcode{"verbose"}, additional status
messages are printed to the command window.

Any string input arguments must be passed after all other arguments.

If called with one output argument, the reduced faces and vertices are
returned in a structure @var{reduced_fv} with the fields @code{faces} and
@code{vertices} (see the one output option of @code{isosurface}).

If called with two output arguments, the reduced faces and vertices are
returned in two separate matrices @var{reduced_faces} and
@var{reduced_vertices}.

@xseealso{isosurface, isonormals, reducevolume, patch}
@end deftypefn
reducevolume
@c reducevolume scripts/plot/draw/reducevolume.m
@deftypefn  {} {[@var{nx}, @var{ny}, @var{nz}, @var{nv}] =} reducevolume (@var{v}, @var{r})
@deftypefnx {} {[@var{nx}, @var{ny}, @var{nz}, @var{nv}] =} reducevolume (@var{x}, @var{y}, @var{z}, @var{v}, @var{r})
@deftypefnx {} {@var{nv} =} reducevolume (@dots{})

Reduce the volume of the dataset in @var{v} according to the values in
@var{r}.

@var{v} is a matrix that is non-singleton in the first 3 dimensions.

@var{r} can either be a vector of 3 elements representing the reduction
factors in the x-, y-, and z-directions or a scalar, in which case the same
reduction factor is used in all three dimensions.

@code{reducevolume} reduces the number of elements of @var{v} by taking
only every @var{r}-th element in the respective dimension.

Optionally, @var{x}, @var{y}, and @var{z} can be supplied to represent the
set of coordinates of @var{v}.  They can either be matrices of the same size
as @var{v} or vectors with sizes according to the dimensions of @var{v}, in
which case they are expanded to matrices (@pxref{XREFmeshgrid,,meshgrid}).

If @code{reducevolume} is called with two arguments then @var{x}, @var{y},
and @var{z} are assumed to match the respective indices of @var{v}.

The reduced matrix is returned in @var{nv}.

Optionally, the reduced set of coordinates are returned in @var{nx},
@var{ny}, and @var{nz}, respectively.

Examples:

@example
@group
@var{v} = reshape (1:6*8*4, [6 8 4]);
@var{nv} = reducevolume (@var{v}, [4 3 2]);
@end group
@end example

@example
@group
@var{v} = reshape (1:6*8*4, [6 8 4]);
@var{x} = 1:3:24;  @var{y} = -14:5:11;  @var{z} = linspace (16, 18, 4);
[@var{nx}, @var{ny}, @var{nz}, @var{nv}] = reducevolume (@var{x}, @var{y}, @var{z}, @var{v}, [4 3 2]);
@end group
@end example

@xseealso{isosurface, isonormals}
@end deftypefn
ribbon
@c ribbon scripts/plot/draw/ribbon.m
@deftypefn  {} {} ribbon (@var{y})
@deftypefnx {} {} ribbon (@var{x}, @var{y})
@deftypefnx {} {} ribbon (@var{x}, @var{y}, @var{width})
@deftypefnx {} {} ribbon (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} ribbon (@dots{})
Draw a ribbon plot for the columns of @var{y} vs. @var{x}.

If @var{x} is omitted, a vector containing the row numbers is assumed
(@code{1:rows (Y)}).  Alternatively, @var{x} can also be a vector with
same number of elements as rows of @var{y} in which case the same
@var{x} is used for each column of @var{y}.

The optional parameter @var{width} specifies the width of a single ribbon
(default is 0.75).

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the surface objects representing each ribbon.
@xseealso{surface, waterfall}
@end deftypefn
rose
@c rose scripts/plot/draw/rose.m
@deftypefn  {} {} rose (@var{th})
@deftypefnx {} {} rose (@var{th}, @var{nbins})
@deftypefnx {} {} rose (@var{th}, @var{bins})
@deftypefnx {} {} rose (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} rose (@dots{})
@deftypefnx {} {[@var{thout} @var{rout}] =} rose (@dots{})
Plot an angular histogram.

With one vector argument, @var{th}, plot the histogram with 20 angular bins.
If @var{th} is a matrix then each column of @var{th} produces a separate
histogram.

If @var{nbins} is given and is a scalar, then the histogram is produced with
@var{nbin} bins.  If @var{bins} is a vector, then the center of each bin is
defined by the values in @var{bins} and the number of bins is
given by the number of elements in @var{bins}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to the
line objects representing each histogram.

If two output arguments are requested then no plot is made and
the polar vectors necessary to plot the histogram are returned instead.

Example

@example
@group
[th, r] = rose ([2*randn(1e5,1), pi + 2*randn(1e5,1)]);
polar (th, r);
@end group
@end example

Programming Note: When specifying bin centers with the @var{bins} input,
the edges for bins 2 to N-1 are spaced so that @code{@var{bins}(i)} is
centered between the edges.  The final edge is drawn halfway between bin N
and bin 1.  This guarantees that all input @var{th} will be placed into one
of the bins, but also means that for some combinations bin 1 and bin N may
not be centered on the user's given values.
@xseealso{hist, polar}
@end deftypefn
scatter
@c scatter scripts/plot/draw/scatter.m
@deftypefn  {} {} scatter (@var{x}, @var{y})
@deftypefnx {} {} scatter (@var{x}, @var{y}, @var{s})
@deftypefnx {} {} scatter (@var{x}, @var{y}, @var{s}, @var{c})
@deftypefnx {} {} scatter (@dots{}, @var{style})
@deftypefnx {} {} scatter (@dots{}, "filled")
@deftypefnx {} {} scatter (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} scatter (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} scatter (@dots{})
Draw a 2-D scatter plot.

A marker is plotted at each point defined by the coordinates in the vectors
@var{x} and @var{y}.

The size of the markers is determined by @var{s}, which can be a scalar
or a vector of the same length as @var{x} and @var{y}.  If @var{s}
is not given, or is an empty matrix, then a default value of 36 square
points is used (The marker size itself is @code{sqrt (s)}).

The color of the markers is determined by @var{c}, which can be a string
defining a fixed color; a 3-element vector giving the red, green, and blue
components of the color; a vector of the same length as @var{x} that gives
a scaled index into the current colormap; or an @nospell{Nx3} matrix
defining the RGB color of each marker individually.

The marker to use can be changed with the @var{style} argument; it is a
string defining a marker in the same manner as the @code{plot} command.
If no marker is specified it defaults to @qcode{"o"} or circles.
If the argument @qcode{"filled"} is given then the markers are filled.

Additional property/value pairs are passed directly to the underlying
patch object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
scatter object.

Example:

@example
@group
x = randn (100, 1);
y = randn (100, 1);
scatter (x, y, [], sqrt (x.^2 + y.^2));
@end group
@end example

@xseealso{scatter3, patch, plot}
@end deftypefn
scatter3
@c scatter3 scripts/plot/draw/scatter3.m
@deftypefn  {} {} scatter3 (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s})
@deftypefnx {} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}, @var{c})
@deftypefnx {} {} scatter3 (@dots{}, @var{style})
@deftypefnx {} {} scatter3 (@dots{}, "filled")
@deftypefnx {} {} scatter3 (@dots{}, @var{prop}, @var{val})
@deftypefnx {} {} scatter3 (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} scatter3 (@dots{})
Draw a 3-D scatter plot.

A marker is plotted at each point defined by the coordinates in the vectors
@var{x}, @var{y}, and @var{z}.

The size of the markers is determined by @var{s}, which can be a scalar
or a vector of the same length as @var{x}, @var{y}, and @var{z}.  If @var{s}
is not given, or is an empty matrix, then a default value of 8 points is
used.

The color of the markers is determined by @var{c}, which can be a string
defining a fixed color; a 3-element vector giving the red, green, and blue
components of the color; a vector of the same length as @var{x} that gives
a scaled index into the current colormap; or an @nospell{Nx3} matrix
defining the RGB color of each marker individually.

The marker to use can be changed with the @var{style} argument, that is a
string defining a marker in the same manner as the @code{plot} command.
If no marker is specified it defaults to @qcode{"o"} or circles.
If the argument @qcode{"filled"} is given then the markers are filled.

Additional property/value pairs are passed directly to the underlying
patch object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the hggroup
object representing the points.

@example
@group
[x, y, z] = peaks (20);
scatter3 (x(:), y(:), z(:), [], z(:));
@end group
@end example

@xseealso{scatter, patch, plot}
@end deftypefn
semilogx
@c semilogx scripts/plot/draw/semilogx.m
@deftypefn  {} {} semilogx (@var{y})
@deftypefnx {} {} semilogx (@var{x}, @var{y})
@deftypefnx {} {} semilogx (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} semilogx (@var{x}, @var{y}, @var{fmt})
@deftypefnx {} {} semilogx (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} semilogx (@dots{})
Produce a 2-D plot using a logarithmic scale for the x-axis.

See the documentation of @code{plot} for a description of the
arguments that @code{semilogx} will accept.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.
@xseealso{plot, semilogy, loglog}
@end deftypefn
semilogxerr
@c semilogxerr scripts/plot/draw/semilogxerr.m
@deftypefn  {} {} semilogxerr (@var{y}, @var{ey})
@deftypefnx {} {} semilogxerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {} {} semilogxerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {} {} semilogxerr (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} semilogxerr (@dots{})
Produce 2-D plots using a logarithmic scale for the x-axis and errorbars
at each data point.

Many different combinations of arguments are possible.  The most common
form is

@example
semilogxerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a semi-logarithmic plot of @var{y} versus @var{x}
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}.  @xref{XREFerrorbar,,errorbar}, for available
formats and additional information.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

@xseealso{errorbar, semilogyerr, loglogerr}
@end deftypefn
semilogy
@c semilogy scripts/plot/draw/semilogy.m
@deftypefn  {} {} semilogy (@var{y})
@deftypefnx {} {} semilogy (@var{x}, @var{y})
@deftypefnx {} {} semilogy (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} semilogy (@var{x}, @var{y}, @var{fmt})
@deftypefnx {} {} semilogy (@var{h}, @dots{})
@deftypefnx {} {@var{h} =} semilogy (@dots{})
Produce a 2-D plot using a logarithmic scale for the y-axis.

See the documentation of @code{plot} for a description of the
arguments that @code{semilogy} will accept.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.
@xseealso{plot, semilogx, loglog}
@end deftypefn
semilogyerr
@c semilogyerr scripts/plot/draw/semilogyerr.m
@deftypefn  {} {} semilogyerr (@var{y}, @var{ey})
@deftypefnx {} {} semilogyerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {} {} semilogyerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {} {} semilogyerr (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} semilogyerr (@dots{})
Produce 2-D plots using a logarithmic scale for the y-axis and errorbars
at each data point.

Many different combinations of arguments are possible.  The most common
form is

@example
semilogyerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a semi-logarithmic plot of @var{y} versus @var{x}
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}.  @xref{XREFerrorbar,,errorbar}, for available
formats and additional information.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

@xseealso{errorbar, semilogxerr, loglogerr}
@end deftypefn
shrinkfaces
@c shrinkfaces scripts/plot/draw/shrinkfaces.m
@deftypefn  {} {} shrinkfaces (@var{p}, @var{sf})
@deftypefnx {} {@var{nfv} =} shrinkfaces (@var{p}, @var{sf})
@deftypefnx {} {@var{nfv} =} shrinkfaces (@var{fv}, @var{sf})
@deftypefnx {} {@var{nfv} =} shrinkfaces (@var{f}, @var{v}, @var{sf})
@deftypefnx {} {[@var{nf}, @var{nv}] =} shrinkfaces (@dots{})

Reduce the size of faces in a patch by the shrink factor @var{sf}.

The patch object can be specified by a graphics handle (@var{p}), a patch
structure (@var{fv}) with the fields @qcode{"faces"} and @qcode{"vertices"},
or as two separate matrices (@var{f}, @var{v}) of faces and vertices.

The shrink factor @var{sf} is a positive number specifying the percentage
of the original area the new face will occupy.  If no factor is given the
default is 0.3 (a reduction to 30% of the original size).  A factor greater
than 1.0 will result in the expansion of faces.

Given a patch handle as the first input argument and no output parameters,
perform the shrinking of the patch faces in place and redraw the patch.

If called with one output argument, return a structure with fields
@qcode{"faces"}, @qcode{"vertices"}, and @qcode{"facevertexcdata"}
containing the data after shrinking.  This structure can be used directly
as an input argument to the @code{patch} function.

@strong{Caution:}: Performing the shrink operation on faces which are not
convex can lead to undesirable results.

Example: a triangulated 3/4 circle and the corresponding shrunken version.

@example
@group
[phi r] = meshgrid (linspace (0, 1.5*pi, 16), linspace (1, 2, 4));
tri = delaunay (phi(:), r(:));
v = [r(:).*sin(phi(:)) r(:).*cos(phi(:))];
clf ()
p = patch ("Faces", tri, "Vertices", v, "FaceColor", "none");
fv = shrinkfaces (p);
patch (fv)
axis equal
grid on
@end group
@end example

@xseealso{patch}
@end deftypefn
slice
@c slice scripts/plot/draw/slice.m
@deftypefn  {} {} slice (@var{x}, @var{y}, @var{z}, @var{v}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} slice (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {} {} slice (@var{v}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {} {} slice (@var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {} {} slice (@dots{}, @var{method})
@deftypefnx {} {} slice (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} slice (@dots{})
Plot slices of 3-D data/scalar fields.

Each element of the 3-dimensional array @var{v} represents a scalar value at
a location given by the parameters @var{x}, @var{y}, and @var{z}.  The
parameters @var{x}, @var{x}, and @var{z} are either 3-dimensional arrays of
the same size as the array @var{v} in the @qcode{"meshgrid"} format or
vectors.  The parameters @var{xi}, etc.@: respect a similar format to
@var{x}, etc., and they represent the points at which the array @var{vi}
is interpolated using interp3.  The vectors @var{sx}, @var{sy}, and
@var{sz} contain points of orthogonal slices of the respective axes.

If @var{x}, @var{y}, @var{z} are omitted, they are assumed to be
@code{x = 1:size (@var{v}, 2)}, @code{y = 1:size (@var{v}, 1)} and
@code{z = 1:size (@var{v}, 3)}.

@var{method} is one of:

@table @asis
@item @qcode{"nearest"}
Return the nearest neighbor.

@item @qcode{"linear"}
Linear interpolation from nearest neighbors.

@item @qcode{"cubic"}
Cubic interpolation from four nearest neighbors (not implemented yet).

@item @qcode{"spline"}
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

The default method is @qcode{"linear"}.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Examples:

@example
@group
[x, y, z] = meshgrid (linspace (-8, 8, 32));
v = sin (sqrt (x.^2 + y.^2 + z.^2)) ./ (sqrt (x.^2 + y.^2 + z.^2));
slice (x, y, z, v, [], 0, []);

[xi, yi] = meshgrid (linspace (-7, 7));
zi = xi + yi;
slice (x, y, z, v, xi, yi, zi);
@end group
@end example
@xseealso{interp3, surface, pcolor}
@end deftypefn
smooth3
@c smooth3 scripts/plot/draw/smooth3.m
@deftypefn  {} {@var{smoothed_data} =} smooth3 (@var{data})
@deftypefnx {} {@var{smoothed_data} =} smooth3 (@var{data}, @var{method})
@deftypefnx {} {@var{smoothed_data} =} smooth3 (@var{data}, @var{method}, @var{sz})
@deftypefnx {} {@var{smoothed_data} =} smooth3 (@var{data}, @var{method}, @var{sz}, @var{std_dev})
Smooth values of 3-dimensional matrix @var{data}.

This function can be used, for example, to reduce the impact of noise in
@var{data} before calculating isosurfaces.

@var{data} must be a non-singleton 3-dimensional matrix.  The smoothed data
from this matrix is returned in @var{smoothed_data} which is of the same
size as @var{data}.

The option input @var{method} determines which convolution kernel is used
for the smoothing process.  Possible choices:

@table @asis
@item @qcode{"box"}, @qcode{"b"} (default)
to use a convolution kernel with sharp edges.

@item @qcode{"gaussian"}, @qcode{"g"}
to use a convolution kernel that is represented by a non-correlated
trivariate normal distribution function.
@end table

@var{sz} is either a vector of 3 elements representing the size of the
convolution kernel in x-, y- and z-direction or a scalar, in which case
the same size is used in all three dimensions.  The default value is 3.

When @var{method} is @qcode{"gaussian"}, @var{std_dev} defines the standard
deviation of the trivariate normal distribution function.  @var{std_dev} is
either a vector of 3 elements representing the standard deviation of the
Gaussian convolution kernel in x-, y- and z-directions or a scalar, in which
case the same value is used in all three dimensions.  The default value is
0.65.

@xseealso{isosurface, isonormals, patch}
@end deftypefn
sombrero
@c sombrero scripts/plot/draw/sombrero.m
@deftypefn  {} {} sombrero ()
@deftypefnx {} {} sombrero (@var{n})
@deftypefnx {} {@var{z} =} sombrero (@dots{})
@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} sombrero (@dots{})
Plot the familiar 3-D sombrero function.

The function plotted is
@tex
$$z = { \rm{sin} (\sqrt {(x^2 + y^2)}) \over \sqrt {(x^2 + y^2)} }$$
@end tex
@ifnottex

@example
z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2))
@end example

@end ifnottex
Called without a return argument, @code{sombrero} plots the surface of the
above function over the meshgrid [-8,8] using @code{surf}.

If @var{n} is a scalar the plot is made with @var{n} grid lines.
The default value for @var{n} is 41.

When called with output arguments, return the data for the function
evaluated over the meshgrid.  This can subsequently be plotted with
@code{surf (@var{x}, @var{y}, @var{z})}.

@xseealso{peaks, meshgrid, mesh, surf}
@end deftypefn
sphere
@c sphere scripts/plot/draw/sphere.m
@deftypefn  {} {} sphere ()
@deftypefnx {} {} sphere (@var{n})
@deftypefnx {} {} sphere (@var{hax}, @dots{})
@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} sphere (@dots{})
Plot a 3-D unit sphere.

The optional input @var{n} determines the number of faces around the
circumference of the sphere.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

If outputs are requested @code{sphere} returns three matrices in
@code{meshgrid} format such that @code{surf (@var{x}, @var{y}, @var{z})}
generates a unit sphere.

Example:

@example
@group
[x, y, z] = sphere (40);
surf (3*x, 3*y, 3*z);
axis equal;
title ("sphere of radius 3");
@end group
@end example
@xseealso{cylinder, ellipsoid, rectangle}
@end deftypefn
stairs
@c stairs scripts/plot/draw/stairs.m
@deftypefn  {} {} stairs (@var{y})
@deftypefnx {} {} stairs (@var{x}, @var{y})
@deftypefnx {} {} stairs (@dots{}, @var{style})
@deftypefnx {} {} stairs (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} stairs (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} stairs (@dots{})
@deftypefnx {} {[@var{xstep}, @var{ystep}] =} stairs (@dots{})
Produce a stairstep plot.

The arguments @var{x} and @var{y} may be vectors or matrices.
If only one argument is given, it is taken as a vector of Y values
and the X coordinates are taken to be the indices of the elements
(@code{@var{x} = 1:numel (@var{y})}).

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.

Multiple property/value pairs may be specified, but they must appear in
pairs.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

If one output argument is requested, return a graphics handle to the
created plot.  If two output arguments are specified, the data are generated
but not plotted.  For example,

@example
stairs (x, y);
@end example

@noindent
and

@example
@group
[xs, ys] = stairs (x, y);
plot (xs, ys);
@end group
@end example

@noindent
are equivalent.
@xseealso{bar, hist, plot, stem}
@end deftypefn
stem
@c stem scripts/plot/draw/stem.m
@deftypefn  {} {} stem (@var{y})
@deftypefnx {} {} stem (@var{x}, @var{y})
@deftypefnx {} {} stem (@dots{}, @var{linespec})
@deftypefnx {} {} stem (@dots{}, "filled")
@deftypefnx {} {} stem (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} stem (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} stem (@dots{})
Plot a 2-D stem graph.

If only one argument is given, it is taken as the y-values and the
x-coordinates are taken from the indices of the elements.

If @var{y} is a matrix, then each column of the matrix is plotted as
a separate stem graph.  In this case @var{x} can either be a vector,
the same length as the number of rows in @var{y}, or it can be a
matrix of the same size as @var{y}.

The default color is @qcode{"b"} (blue), the default line style is
@qcode{"-"}, and the default marker is @qcode{"o"}.  The line style can
be altered by the @var{linespec} argument in the same manner as the
@code{plot} command.  If the @qcode{"filled"} argument is present the
markers at the top of the stems will be filled in.  For example,

@example
@group
x = 1:10;
y = 2*x;
stem (x, y, "r");
@end group
@end example

@noindent
plots 10 stems with heights from 2 to 20 in red;

Optional property/value pairs may be specified to control the appearance
of the plot.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a handle to a @nospell{"stem series"}
hggroup.  The single hggroup handle has all of the graphical elements
comprising the plot as its children; This allows the properties of
multiple graphics objects to be changed by modifying just a single
property of the @nospell{"stem series"} hggroup.

For example,

@example
@group
x = [0:10]';
y = [sin(x), cos(x)]
h = stem (x, y);
set (h(2), "color", "g");
set (h(1), "basevalue", -1)
@end group
@end example

@noindent
changes the color of the second @nospell{"stem series"} and moves the base
line of the first.

Stem Series Properties

@table @asis
@item linestyle
The linestyle of the stem.  (Default: @qcode{"-"})

@item linewidth
The width of the stem.  (Default: 0.5)

@item color
The color of the stem, and if not separately specified, the marker.
(Default: @qcode{"b"} [blue])

@item marker
The marker symbol to use at the top of each stem.  (Default: @qcode{"o"})

@item markeredgecolor
The edge color of the marker.  (Default: @qcode{"color"} property)

@item markerfacecolor
The color to use for @nospell{"filling"} the marker.
(Default: @qcode{"none"} [unfilled])

@item markersize
The size of the marker.  (Default: 6)

@item baseline
The handle of the line object which implements the baseline.  Use @code{set}
with the returned handle to change graphic properties of the baseline.

@item basevalue
The y-value where the baseline is drawn.  (Default: 0)
@end table
@xseealso{stem3, bar, hist, plot, stairs}
@end deftypefn
stem3
@c stem3 scripts/plot/draw/stem3.m
@deftypefn  {} {} stem3 (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} stem3 (@dots{}, @var{linespec})
@deftypefnx {} {} stem3 (@dots{}, "filled")
@deftypefnx {} {} stem3 (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} stem3 (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} stem3 (@dots{})
Plot a 3-D stem graph.

Stems are drawn from the height @var{z} to the location in the x-y plane
determined by @var{x} and @var{y}.  The default color is @qcode{"b"} (blue),
the default line style is @qcode{"-"}, and the default marker is
@qcode{"o"}.

The line style can be altered by the @var{linespec} argument in the same
manner as the @code{plot} command.  If the @qcode{"filled"} argument is
present the markers at the top of the stems will be filled in.

Optional property/value pairs may be specified to control the appearance
of the plot.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a handle to the @nospell{"stem series"}
hggroup containing the line and marker objects used for the plot.
@xref{XREFstem,,stem}, for a description of the @nospell{"stem series"}
object.

Example:

@example
@group
theta = 0:0.2:6;
stem3 (cos (theta), sin (theta), theta);
@end group
@end example

@noindent
plots 31 stems with heights from 0 to 6 lying on a circle.

Implementation Note: Color definitions with RGB-triples are not valid.
@xseealso{stem, bar, hist, plot}
@end deftypefn
stemleaf
@c stemleaf scripts/plot/draw/stemleaf.m
@deftypefn  {} {} stemleaf (@var{x}, @var{caption})
@deftypefnx {} {} stemleaf (@var{x}, @var{caption}, @var{stem_sz})
@deftypefnx {} {@var{plotstr} =} stemleaf (@dots{})
Compute and display a stem and leaf plot of the vector @var{x}.

The input @var{x} should be a vector of integers.  Any non-integer values
will be converted to integer by @code{@var{x} = fix (@var{x})}.  By default
each element of @var{x} will be plotted with the last digit of the element
as a leaf value and the remaining digits as the stem.  For example, 123
will be plotted with the stem @samp{12} and the leaf @samp{3}.  The second
argument, @var{caption}, should be a character array which provides a
description of the data.  It is included as a heading for the output.

The optional input @var{stem_sz} sets the width of each stem.
The stem width is determined by @code{10^(@var{stem_sz} + 1)}.
The default stem width is 10.

The output of @code{stemleaf} is composed of two parts: a
"Fenced Letter Display," followed by the stem-and-leaf plot itself.
The Fenced Letter Display is described in @cite{Exploratory Data Analysis}.
Briefly, the entries are as shown:

@example
@group

        Fenced Letter Display
#% nx|___________________     nx = numel (x)
M% mi|       md         |     mi median index, md median
H% hi|hl              hu| hs  hi lower hinge index, hl,hu hinges,
1    |x(1)         x(nx)|     hs h_spreadx(1), x(nx) first
           _______            and last data value.
     ______|step |_______     step 1.5*h_spread
    f|ifl            ifh|     inner fence, lower and higher
     |nfl            nfh|     no.\ of data points within fences
    F|ofl            ofh|     outer fence, lower and higher
     |nFl            nFh|     no.\ of data points outside outer
                              fences
@end group
@end example

The stem-and-leaf plot shows on each line the stem value followed by the
string made up of the leaf digits.  If the @var{stem_sz} is not 1 the
successive leaf values are separated by ",".

With no return argument, the plot is immediately displayed.  If an output
argument is provided, the plot is returned as an array of strings.

The leaf digits are not sorted.  If sorted leaf values are desired, use
@code{@var{xs} = sort (@var{x})} before calling @code{stemleaf (@var{xs})}.

The stem and leaf plot and associated displays are described in:
Chapter 3, @cite{Exploratory Data Analysis} by @nospell{J. W. Tukey},
Addison-Wesley, 1977.
@xseealso{hist, printd}
@end deftypefn
surf
@c surf scripts/plot/draw/surf.m
@deftypefn  {} {} surf (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} surf (@var{z})
@deftypefnx {} {} surf (@dots{}, @var{c})
@deftypefnx {} {} surf (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} surf (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} surf (@dots{})
Plot a 3-D surface mesh.

The surface mesh is plotted using shaded rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the surface is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the surface can be specified independently of
@var{z} by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Note: The exact appearance of the surface can be controlled with the
@code{shading} command or by using @code{set} to control surface object
properties.
@xseealso{ezsurf, surfc, surfl, surfnorm, trisurf, contour, mesh, surface, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
surface
@c surface scripts/plot/draw/surface.m
@deftypefn  {} {} surface (@var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {} {} surface (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} surface (@var{z}, @var{c})
@deftypefnx {} {} surface (@var{z})
@deftypefnx {} {} surface (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} surface (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} surface (@dots{})
Create a surface graphic object given matrices @var{x} and @var{y} from
@code{meshgrid} and a matrix of values @var{z} corresponding to the
@var{x} and @var{y} coordinates of the surface.

If @var{x} and @var{y} are vectors, then a typical vertex is
(@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns of @var{z} correspond
to different @var{x} values and rows of @var{z} correspond to different
@var{y} values.  If only a single input @var{z} is given then @var{x} is
taken to be @code{1:columns (@var{z})} and @var{y} is
@code{1:rows (@var{z})}.

Any property/value input pairs are assigned to the surface object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Programming Note: The full list of properties is documented at
@ref{Surface Properties,,Surface Properties}.
@xseealso{surf, mesh, patch, line}
@end deftypefn
surfc
@c surfc scripts/plot/draw/surfc.m
@deftypefn  {} {} surfc (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} surfc (@var{z})
@deftypefnx {} {} surfc (@dots{}, @var{c})
@deftypefnx {} {} surfc (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} surfc (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} surfc (@dots{})
Plot a 3-D surface mesh with underlying contour lines.

The surface mesh is plotted using shaded rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the surface is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the surface can be specified independently of
@var{z} by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Note: The exact appearance of the surface can be controlled with the
@code{shading} command or by using @code{set} to control surface object
properties.
@xseealso{ezsurfc, surf, surfl, surfnorm, trisurf, contour, mesh, surface, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
surfl
@c surfl scripts/plot/draw/surfl.m
@deftypefn  {} {} surfl (@var{z})
@deftypefnx {} {} surfl (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} surfl (@dots{}, @var{lsrc})
@deftypefnx {} {} surfl (@var{x}, @var{y}, @var{z}, @var{lsrc}, @var{P})
@deftypefnx {} {} surfl (@dots{}, "cdata")
@deftypefnx {} {} surfl (@dots{}, "light")
@deftypefnx {} {} surfl (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} surfl (@dots{})
Plot a 3-D surface using shading based on various lighting models.

The surface mesh is plotted using shaded rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The default lighting mode @qcode{"cdata"}, changes the cdata property of the
surface object to give the impression of a lighted surface.

The alternate mode @qcode{"light"} creates a light object to illuminate the
surface.

The light source location may be specified using @var{lsrc} which can be
a 2-element vector [azimuth, elevation] in degrees, or a 3-element vector
[lx, ly, lz].  The default value is rotated 45 degrees counterclockwise to
the current view.

The material properties of the surface can specified using a 4-element
vector @var{P} = [@var{AM} @var{D} @var{SP} @var{exp}] which defaults to
@var{p} = [0.55 0.6 0.4 10].

@table @asis
@item @qcode{"AM"} strength of ambient light

@item @qcode{"D"} strength of diffuse reflection

@item @qcode{"SP"} strength of specular reflection

@item @qcode{"EXP"} specular exponent
@end table

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Example:

@example
@group
colormap (bone (64));
surfl (peaks);
shading interp;
@end group
@end example
@xseealso{diffuse, specular, surf, shading, colormap, caxis}
@end deftypefn
surfnorm
@c surfnorm scripts/plot/draw/surfnorm.m
@deftypefn  {} {} surfnorm (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} surfnorm (@var{z})
@deftypefnx {} {} surfnorm (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} surfnorm (@var{hax}, @dots{})
@deftypefnx {} {[@var{nx}, @var{ny}, @var{nz}] =} surfnorm (@dots{})
Find the vectors normal to a meshgridded surface.

If @var{x} and @var{y} are vectors, then a typical vertex is
(@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns of @var{z} correspond
to different @var{x} values and rows of @var{z} correspond to different
@var{y} values.  If only a single input @var{z} is given then @var{x} is
taken to be @code{1:columns (@var{z})} and @var{y} is
@code{1:rows (@var{z})}.

If no return arguments are requested, a surface plot with the normal
vectors to the surface is plotted.

Any property/value input pairs are assigned to the surface object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

If output arguments are requested then the components of the normal
vectors are returned in @var{nx}, @var{ny}, and @var{nz} and no plot is
made.  The normal vectors are unnormalized (magnitude != 1).  To normalize,
use

@example
@group
len = sqrt (nx.^2 + ny.^2 + nz.^2);
nx ./= len;  ny ./= len;  nz ./= len;
@end group
@end example

An example of the use of @code{surfnorm} is

@example
surfnorm (peaks (25));
@end example

Algorithm: The normal vectors are calculated by taking the cross product
of the diagonals of each of the quadrilateral faces in the meshgrid to find
the normal vectors at the center of each face.  Next, for each meshgrid
point the four nearest normal vectors are averaged to obtain the final
normal to the surface at the meshgrid point.

For surface objects, the @qcode{"VertexNormals"} property contains
equivalent information, except possibly near the boundary of the surface
where different interpolation schemes may yield slightly different values.

@xseealso{isonormals, quiver3, surf, meshgrid}
@end deftypefn
tetramesh
@c tetramesh scripts/plot/draw/tetramesh.m
@deftypefn  {} {} tetramesh (@var{T}, @var{X})
@deftypefnx {} {} tetramesh (@var{T}, @var{X}, @var{C})
@deftypefnx {} {} tetramesh (@dots{}, @var{property}, @var{val}, @dots{})
@deftypefnx {} {@var{h} =} tetramesh (@dots{})
Display the tetrahedrons defined in the m-by-4 matrix @var{T} as 3-D
patches.

@var{T} is typically the output of a Delaunay triangulation of a 3-D set
of points.  Every row of @var{T} contains four indices into the n-by-3
matrix @var{X} of the vertices of a tetrahedron.  Every row in @var{X}
represents one point in 3-D space.

The vector @var{C} specifies the color of each tetrahedron as an index
into the current colormap.  The default value is 1:m where m is the number
of tetrahedrons; the indices are scaled to map to the full range of the
colormap.  If there are more tetrahedrons than colors in the colormap then
the values in @var{C} are cyclically repeated.

Calling @code{tetramesh (@dots{}, "property", "value", @dots{})} passes all
property/value pairs directly to the patch function as additional arguments.

The optional return value @var{h} is a vector of patch handles where each
handle represents one tetrahedron in the order given by @var{T}.
A typical use case for @var{h} is to turn the respective patch
@qcode{"visible"} property @qcode{"on"} or @qcode{"off"}.

Type @code{demo tetramesh} to see examples on using @code{tetramesh}.
@xseealso{trimesh, delaunay, delaunayn, patch}
@end deftypefn
trimesh
@c trimesh scripts/plot/draw/trimesh.m
@deftypefn  {} {} trimesh (@var{tri}, @var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {} {} trimesh (@var{tri}, @var{x}, @var{y}, @var{z})
@deftypefnx {} {} trimesh (@var{tri}, @var{x}, @var{y})
@deftypefnx {} {} trimesh (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@var{h} =} trimesh (@dots{})
Plot a 3-D triangular wireframe mesh.

In contrast to @code{mesh}, which plots a mesh using rectangles,
@code{trimesh} plots the mesh using triangles.

@var{tri} is typically the output of a Delaunay triangulation over the
grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
and contains three indices into [@var{x}, @var{y}] which are the
vertices of the triangles in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If no @var{z} input is given then
the triangles are plotted as a 2-D figure.

The color of the trimesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the mesh can be specified independently of @var{z}
by supplying @var{c}, which is a vector for colormap data, or a matrix with
three columns for RGB data.  The number of colors specified in @var{c} must
either equal the number of vertices in @var{z} or the number of triangles
in @var{tri}.

Any property/value pairs are passed directly to the underlying patch object.

The optional return value @var{h} is a graphics handle to the created patch
object.
@xseealso{mesh, tetramesh, triplot, trisurf, delaunay, patch, hidden}
@end deftypefn
triplot
@c triplot scripts/plot/draw/triplot.m
@deftypefn  {} {} triplot (@var{tri}, @var{x}, @var{y})
@deftypefnx {} {} triplot (@var{tri}, @var{x}, @var{y}, @var{linespec})
@deftypefnx {} {@var{h} =} triplot (@dots{})
Plot a 2-D triangular mesh.

@var{tri} is typically the output of a Delaunay triangulation over the
grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
and contains three indices into [@var{x}, @var{y}] which are the
vertices of the triangles in the x-y plane.

The linestyle to use for the plot can be defined with the argument
@var{linespec} of the same format as the @code{plot} command.

The optional return value @var{h} is a graphics handle to the created
patch object.
@xseealso{plot, trimesh, trisurf, delaunay}
@end deftypefn
trisurf
@c trisurf scripts/plot/draw/trisurf.m
@deftypefn  {} {} trisurf (@var{tri}, @var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {} {} trisurf (@var{tri}, @var{x}, @var{y}, @var{z})
@deftypefnx {} {} trisurf (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@var{h} =} trisurf (@dots{})
Plot a 3-D triangular surface.

In contrast to @code{surf}, which plots a surface mesh using rectangles,
@code{trisurf} plots the mesh using triangles.

@var{tri} is typically the output of a Delaunay triangulation over the
grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
and contains three indices into [@var{x}, @var{y}] which are the vertices of
the triangles in the x-y plane.  @var{z} determines the height above the
plane of each vertex.

The color of the trisurf is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or change
the colormap to control the appearance.

Optionally, the color of the mesh can be specified independently of @var{z}
by supplying @var{c}, which is a vector for colormap data, or a matrix with
three columns for RGB data.  The number of colors specified in @var{c} must
either equal the number of vertices in @var{z} or the number of triangles
in @var{tri}.  When specifying the color at each vertex the triangle will
be colored according to the color of the first vertex only (see patch
documentation and the @qcode{"FaceColor"} property when set to
@qcode{"flat"}).

Any property/value pairs are passed directly to the underlying patch object.

The optional return value @var{h} is a graphics handle to the created patch
object.
@xseealso{surf, triplot, trimesh, delaunay, patch, shading}
@end deftypefn
waterfall
@c waterfall scripts/plot/draw/waterfall.m
@deftypefn  {} {} waterfall (@var{x}, @var{y}, @var{z})
@deftypefnx {} {} waterfall (@var{z})
@deftypefnx {} {} waterfall (@dots{}, @var{c})
@deftypefnx {} {} waterfall (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} waterfall (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} waterfall (@dots{})
Plot a 3-D waterfall plot.

A waterfall plot is similar to a @code{meshz} plot except only
mesh lines for the rows of @var{z} (x-values) are shown.

The wireframe mesh is plotted using rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@xseealso{meshz, mesh, meshc, contour, surf, surface, ribbon, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
__actual_axis_position__
@c __actual_axis_position__ scripts/plot/util/__actual_axis_position__.m
@deftypefn  {} {} __actual_axis_position__ (@var{h})
@deftypefnx {} {} __actual_axis_position__ (@var{axis_struct})
Undocumented internal function.
@end deftypefn
__default_plot_options__
@c __default_plot_options__ scripts/plot/util/__default_plot_options__.m
@deftypefn {} {@var{options} =} __default_plot_options__ ()
Undocumented internal function.
@end deftypefn
__gnuplot_drawnow__
@c __gnuplot_drawnow__ scripts/plot/util/__gnuplot_drawnow__.m
@deftypefn {} {} __gnuplot_drawnow__ (@var{h}, @var{term}, @var{file}, @var{debug_file})
Undocumented internal function.
@end deftypefn
__next_line_color__
@c __next_line_color__ scripts/plot/util/__next_line_color__.m
@deftypefn {} {@var{rgb} =} __next_line_color__ (@var{reset})
Undocumented internal function.
@end deftypefn
__next_line_style__
@c __next_line_style__ scripts/plot/util/__next_line_style__.m
@deftypefn {} {@var{style} =} __next_line_style__ (@var{reset})
Undocumented internal function.
@end deftypefn
__opengl_info__
@c __opengl_info__ scripts/plot/util/__opengl_info__.m
@deftypefn  {} {} __opengl_info__
@deftypefnx {} {@var{retval} =} __opengl_info__ ()

Get OpenGL driver information.

If no output values are requested, display information about the
OpenGL subsystem.  If an output is requested, return the information
in a structure.

Fields in the structure are:

@table @asis
@item version
OpenGL Driver version string

@item vendor
OpenGL Driver vendor string

@item renderer
OpenGL renderer string

@item extensions
List of enabled extensions for the OpenGL driver.
@end table

Example Code:

@example
glinfo = __opengl_info__ ();
@end example

@end deftypefn
__plt_get_axis_arg__
@c __plt_get_axis_arg__ scripts/plot/util/__plt_get_axis_arg__.m
@deftypefn {} {[@var{h}, @var{varargin}, @var{narg}] =} __plt_get_axis_arg__ (@var{caller}, @var{varargin})
Undocumented internal function.
@end deftypefn
__pltopt__
@c __pltopt__ scripts/plot/util/__pltopt__.m
@deftypefn {} {} __pltopt__ (@var{caller}, @var{opt}, @var{err_on_invalid})

Decode plot option strings.

@var{opt} can currently be some combination of the following:

@table @code
@item "-"
For solid linestyle (default).

@item "--"
For dashed line style.

@item "-."
For linespoints plot style.

@item ":"
For dots plot style.

@item "r"
Red line color.

@item "g"
Green line color.

@item "b"
Blue line color.

@item "c"
Cyan line color.

@item "m"
Magenta line color.

@item "y"
Yellow line color.

@item "k"
Black line color.

@item "w"
White line color.

@item ";title;"
Here @code{"title"} is the label for the key.

@item  "+"
@itemx "o"
@itemx "*"
@itemx "."
@itemx "x"
@itemx "s"
@itemx "d"
@itemx "^"
@itemx "v"
@itemx ">"
@itemx "<"
@itemx "p"
@itemx "h"
Used in combination with the points or linespoints styles, set the point
style.
@end table

The legend may be fixed to include the name of the variable
plotted in some future version of Octave.
@end deftypefn
allchild
@c allchild scripts/plot/util/allchild.m
@deftypefn {} {@var{h} =} allchild (@var{handles})
Find all children, including hidden children, of a graphics object.

This function is similar to @code{get (h, "children")}, but also returns
hidden objects (HandleVisibility = @qcode{"off"}).

If @var{handles} is a scalar, @var{h} will be a vector.  Otherwise,
@var{h} will be a cell matrix of the same size as @var{handles} and each
cell will contain a vector of handles.
@xseealso{findall, findobj, get, set}
@end deftypefn
ancestor
@c ancestor scripts/plot/util/ancestor.m
@deftypefn  {} {@var{parent} =} ancestor (@var{h}, @var{type})
@deftypefnx {} {@var{parent} =} ancestor (@var{h}, @var{type}, "toplevel")
Return the first ancestor of handle object @var{h} whose type matches
@var{type}, where @var{type} is a character string.

If @var{type} is a cell array of strings, return the first parent whose
type matches any of the given type strings.

If the handle object @var{h} itself is of type @var{type}, return @var{h}.

If @qcode{"toplevel"} is given as a third argument, return the highest
parent in the object hierarchy that matches the condition, instead
of the first (nearest) one.
@xseealso{findobj, findall, allchild}
@end deftypefn
axes
@c axes scripts/plot/util/axes.m
@deftypefn  {} {} axes ()
@deftypefnx {} {} axes (@var{property}, @var{value}, @dots{})
@deftypefnx {} {} axes (@var{hpar}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} axes (@var{hax})
@deftypefnx {} {@var{h} =} axes (@dots{})
Create a Cartesian axes object and return a handle to it, or set the current
axes to @var{hax}.

Called without any arguments, or with @var{property}/@var{value} pairs,
construct a new axes.  The optional argument @var{hpar} is a graphics handle
specifying the parent for the new axes and may be a figure, uipanel, or
uitab.

Called with a single axes handle argument @var{hax}, the function makes
@var{hax} the current axes (as returned by @code{gca}).  It also makes
the figure which contains @var{hax} the current figure (as returned by
@code{gcf}).  Finally, it restacks the parent object's @code{children}
property so that the axes @var{hax} appears before all other axes handles
in the list.  This causes @var{hax} to be displayed on top of any other axes
objects (Z-order stacking).  In addition it restacks any legend or colorbar
objects associated with @var{hax} so that they are also visible.

Programming Note: The full list of properties is documented at
@ref{Axes Properties,,Axes Properties}.
@xseealso{gca, set, get}
@end deftypefn
cla
@c cla scripts/plot/util/cla.m
@deftypefn  {} {} cla
@deftypefnx {} {} cla reset
@deftypefnx {} {} cla (@var{hax})
@deftypefnx {} {} cla (@var{hax}, "reset")
Clear the current or specified (@var{hax}) axes object.

@code{cla} operates by deleting child graphic objects with visible
handles (@code{HandleVisibility} = @qcode{"on"}).  This typically clears the
axes of any visual objects, but leaves in place axes limits, tick marks and
labels, camera view, etc.  In addition, the automatic coloring and styling
of lines is reset by changing the axes properties @code{ColorOrderIndex},
@code{LinestyleOrderIndex} to 1.

If the optional argument @qcode{"reset"} is specified, delete all child
objects, including those with hidden handles, and reset all axes properties
to their defaults.  However, the following properties are not reset:
@code{Position}, @code{Units}.

If the first argument @var{hax} is an axes handle, then operate on
this axes rather than the current axes returned by @code{gca}.
@xseealso{clf, delete, reset}
@end deftypefn
clf
@c clf scripts/plot/util/clf.m
@deftypefn  {} {} clf
@deftypefnx {} {} clf reset
@deftypefnx {} {} clf (@var{hfig})
@deftypefnx {} {} clf (@var{hfig}, "reset")
@deftypefnx {} {@var{h} =} clf (@dots{})
Clear the current figure window.

@code{clf} operates by deleting child graphics objects with visible
handles (HandleVisibility = @qcode{"on"}).

If the optional argument @qcode{"reset"} is specified, delete all child
objects including those with hidden handles and reset all figure
properties to their defaults.  However, the following properties are not
reset: Position, Units, PaperPosition, PaperUnits.

If the first argument @var{hfig} is a figure handle, then operate on
this figure rather than the current figure returned by @code{gcf}.

The optional return value @var{h} is the graphics handle of the figure
window that was cleared.
@xseealso{cla, close, delete, reset}
@end deftypefn
close
@c close scripts/plot/util/close.m
@deftypefn  {} {} close
@deftypefnx {} {} close (@var{h})
@deftypefnx {} {} close @var{figname}
@deftypefnx {} {} close all
@deftypefnx {} {} close all hidden
@deftypefnx {} {} close all force
Close figure window(s).

When called with no arguments, close the current figure.  This is equivalent
to @code{close (gcf)}.  If the input @var{h} is a graphic handle, or vector
of graphics handles, then close each figure in @var{h}.  The figure to
close may also be specified by name @var{figname} which is matched against
the @qcode{"Name"} property of all figures.

If the argument @qcode{"all"} is given then all figures with visible handles
(HandleVisibility = @qcode{"on"}) are closed.

If the additional argument @qcode{"hidden"} is given then all figures,
including hidden ones, are closed.

If the additional argument @qcode{"force"} is given then figures are closed
even when @qcode{"closerequestfcn"} has been altered to prevent closing the
window.

Implementation Note: @code{close} operates by making the handle @var{h} the
current figure, and then calling the function specified by the
@qcode{"closerequestfcn"} property of the figure.  By default, the function
@code{closereq} is used.  It is possible that the function invoked will
delay or abort removing the figure.  To remove a figure without executing
any callback functions use @code{delete}.  When writing a callback function
to close a window do not use @code{close} to avoid recursion.

@xseealso{closereq, delete}
@end deftypefn
closereq
@c closereq scripts/plot/util/closereq.m
@deftypefn {} {} closereq ()
Close the current figure and delete all graphics objects associated with it.

By default, the @qcode{"closerequestfcn"} property of a new plot figure
points to this function.
@xseealso{close, delete}
@end deftypefn
colstyle
@c colstyle scripts/plot/util/colstyle.m
@deftypefn {} {[@var{style}, @var{color}, @var{marker}, @var{msg}] =} colstyle (@var{style})
Parse the line specification @var{style} and return the line style, color,
and markers given.

In the case of an error, the string @var{msg} will return the text of the
error.
@end deftypefn
copyobj
@c copyobj scripts/plot/util/copyobj.m
@deftypefn  {} {@var{hnew} =} copyobj (@var{horig})
@deftypefnx {} {@var{hnew} =} copyobj (@var{horig}, @var{hparent})
Construct a copy of the graphic objects associated with the handles
@var{horig} and return new handles @var{hnew} to the new objects.

If a parent handle @var{hparent} (root, figure, axes, or hggroup) is
specified, the copied object will be created as a child of @var{hparent}.

If @var{horig} is a vector of handles, and @var{hparent} is a scalar,
then each handle in the vector @var{hnew} has its @qcode{"Parent"} property
set to @var{hparent}.  Conversely, if @var{horig} is a scalar and
@var{hparent} a vector, then each parent object will receive a copy of
@var{horig}.  If @var{horig} and @var{hparent} are both vectors with the
same number of elements then @code{@var{hnew}(i)} will have parent
@code{@var{hparent}(i)}.
@xseealso{struct2hdl, hdl2struct, findobj}
@end deftypefn
figure
@c figure scripts/plot/util/figure.m
@deftypefn  {} {} figure
@deftypefnx {} {} figure @var{n}
@deftypefnx {} {} figure (@var{n})
@deftypefnx {} {} figure (@dots{}, "@var{property}", @var{value}, @dots{})
@deftypefnx {} {@var{h} =} figure (@dots{})
Create a new figure window for plotting.

If no arguments are specified, a new figure with the next available number
is created.

If called with an integer @var{n}, and no such numbered figure exists, then
a new figure with the specified number is created.  If the figure already
exists then it is made visible and becomes the current figure for plotting.

Multiple property-value pairs may be specified for the figure object, but
they must appear in pairs.

The optional return value @var{h} is a graphics handle to the created figure
object.

Programming Note: The full list of properties is documented at
@ref{Figure Properties,,Figure Properties}.
@xseealso{axes, gcf, shg, clf, close}
@end deftypefn
findall
@c findall scripts/plot/util/findall.m
@deftypefn  {} {@var{h} =} findall ()
@deftypefnx {} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, @dots{})
@deftypefnx {} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @var{prop_name}, @var{prop_value})
@deftypefnx {} {@var{h} =} findall ("-property", @var{prop_name})
@deftypefnx {} {@var{h} =} findall ("-regexp", @var{prop_name}, @var{pattern})
@deftypefnx {} {@var{h} =} findall (@var{hlist}, @dots{})
@deftypefnx {} {@var{h} =} findall (@var{hlist}, "flat", @dots{})
@deftypefnx {} {@var{h} =} findall (@var{hlist}, "-depth", @var{d}, @dots{})
Find graphics object, including hidden ones, with specified properties.

The return value @var{h} is a list of handles to the found graphic objects.

@code{findall} performs the same search as @code{findobj}, but it
includes hidden objects (HandleVisibility = @qcode{"off"}).  For full
documentation, @pxref{XREFfindobj,,findobj}.
@xseealso{findobj, allchild, get, set}
@end deftypefn
findfigs
@c findfigs scripts/plot/util/findfigs.m
@deftypefn {} {} findfigs ()
Find all visible figures that are currently off the screen and move them
onto the screen.
@xseealso{allchild, figure, get, set}
@end deftypefn
findobj
@c findobj scripts/plot/util/findobj.m
@deftypefn  {} {@var{h} =} findobj ()
@deftypefnx {} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, @dots{})
@deftypefnx {} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @var{prop_name}, @var{prop_value})
@deftypefnx {} {@var{h} =} findobj ("-property", @var{prop_name})
@deftypefnx {} {@var{h} =} findobj ("-regexp", @var{prop_name}, @var{pattern})
@deftypefnx {} {@var{h} =} findobj (@var{hlist}, @dots{})
@deftypefnx {} {@var{h} =} findobj (@var{hlist}, "flat", @dots{})
@deftypefnx {} {@var{h} =} findobj (@var{hlist}, "-depth", @var{d}, @dots{})
Find graphics objects with specified properties.

When called without arguments, return all graphic objects beginning with the
root object (0) and including all of its descendants.

The simplest form for narrowing the results is

@example
findobj (@var{prop_name}, @var{prop_value})
@end example

@noindent
which returns the handles of all objects which have a property named
@var{prop_name} that has the value @var{prop_value}.  If multiple
property/value pairs are specified then only objects meeting all of the
conditions (equivalent to @code{-and}) are returned.

The search can be limited to a particular set of objects and their
descendants, by passing a handle or set of handles @var{hlist} as the first
argument.

The depth of the object hierarchy to search can be limited with the
@qcode{"-depth"} argument.  An example of searching through only three
generations of children is:

@example
findobj (@var{hlist}, "-depth", 3, @var{prop_name}, @var{prop_value})
@end example

Specifying a depth @var{d} of 0 limits the search to the set of objects
passed in @var{hlist}.  A depth of 0 is also equivalent to the
@qcode{"flat"} argument.  The default depth value is @code{Inf} which
includes all descendants.

A specified logical operator may be used between @var{prop_name},
@var{prop_value} pairs.  The supported logical operators are:
@qcode{"-and"}, @qcode{"-or"}, @qcode{"-xor"}, @qcode{"-not"}.  Example code
to locate all figure and axes objects is

@example
findobj ("type", "figure", "-or", "type", "axes")
@end example

Objects may also be matched by comparing a regular expression to the
property values, where property values that match
@code{regexp (@var{prop_value}, @var{pattern})} are returned.

Finally, objects which have a property name can be found with the
@qcode{"-property"} option.  For example, code to locate objects with a
@qcode{"meshstyle"} property is

@example
findobj ("-property", "meshstyle")
@end example

Implementation Note: The search only includes objects with visible
handles (@w{HandleVisibility} = @qcode{"on"}).  @xref{XREFfindall,,findall},
to search for all objects including hidden ones.
@xseealso{findall, allchild, get, set}
@end deftypefn
gca
@c gca scripts/plot/util/gca.m
@deftypefn {} {@var{h} =} gca ()
Return a handle to the current axes object.

The current axes is the default target for graphics output.  In the case
of a figure with multiple axes, @code{gca} returns the last created axes
or the last axes that was clicked on with the mouse.

If no current axes object exists, create one and return its handle.  The
handle may then be used to examine or set properties of the axes.  For
example,

@example
@group
ax = gca ();
set (ax, "position", [0.5, 0.5, 0.5, 0.5]);
@end group
@end example

@noindent
creates an empty axes object and then changes its location and size in the
figure window.

Note: To find the current axes without creating a new axes object if it
does not exist, query the @qcode{"CurrentAxes"} property of a figure.

@example
get (gcf, "currentaxes");
@end example
@xseealso{gcf, gco, gcbf, gcbo, get, set}
@end deftypefn
gcbf
@c gcbf scripts/plot/util/gcbf.m
@deftypefn {} {@var{fig} =} gcbf ()
Return a handle to the figure containing the object whose callback is
currently executing.

If no callback is executing, this function returns the empty matrix.  The
handle returned by this function is the same as the second output argument
of @code{gcbo}.

@xseealso{gcbo, gcf, gco, gca, get, set}
@end deftypefn
gcbo
@c gcbo scripts/plot/util/gcbo.m
@deftypefn  {} {@var{h} =} gcbo ()
@deftypefnx {} {[@var{h}, @var{fig}] =} gcbo ()
Return a handle to the object whose callback is currently executing.

If no callback is executing, this function returns the empty matrix.  This
handle is obtained from the root object property @qcode{"CallbackObject"}.

When called with a second output argument, return the handle of the figure
containing the object whose callback is currently executing.  If no callback
is executing the second output is also set to the empty matrix.

@xseealso{gcbf, gco, gca, gcf, get, set}
@end deftypefn
gcf
@c gcf scripts/plot/util/gcf.m
@deftypefn {} {@var{h} =} gcf ()
Return a handle to the current figure.

The current figure is the default target for graphics output.  If multiple
figures exist, @code{gcf} returns the last created figure or the last figure
that was clicked on with the mouse.

If a current figure does not exist, create one and return its handle.  The
handle may then be used to examine or set properties of the figure.  For
example,

@example
@group
fplot (@@sin, [-10, 10]);
fig = gcf ();
set (fig, "numbertitle", "off", "name", "sin plot")
@end group
@end example

@noindent
plots a sine wave, finds the handle of the current figure, and then
renames the figure window to describe the contents.

Note: To find the current figure without creating a new one if it does not
exist, query the @qcode{"CurrentFigure"} property of the root graphics
object.

@example
get (groot, "currentfigure");
@end example

@xseealso{gca, gco, gcbf, gcbo, get, set}
@end deftypefn
gco
@c gco scripts/plot/util/gco.m
@deftypefn  {} {@var{h} =} gco ()
@deftypefnx {} {@var{h} =} gco (@var{fig})
Return a handle to the current object of the current figure, or a handle
to the current object of the figure with handle @var{fig}.

The current object of a figure is the object that was last clicked on.  It
is stored in the @qcode{"CurrentObject"} property of the target figure.

If the last mouse click did not occur on any child object of the figure,
then the current object is the figure itself.

If no mouse click occurred in the target figure, this function returns an
empty matrix.

Programming Note: The value returned by this function is not necessarily the
same as the one returned by @code{gcbo} during callback execution.  An
executing callback can be interrupted by another callback and the current
object may be changed.

@xseealso{gcbo, gca, gcf, gcbf, get, set}
@end deftypefn
ginput
@c ginput scripts/plot/util/ginput.m
@deftypefn  {} {[@var{x}, @var{y}, @var{buttons}] =} ginput (@var{n})
@deftypefnx {} {[@var{x}, @var{y}, @var{buttons}] =} ginput ()
Return the position and type of mouse button clicks and/or key strokes
in the current figure window.

If @var{n} is defined, then capture @var{n} events before returning.
When @var{n} is not defined @code{ginput} will loop until the return key
@key{RET} is pressed.

The return values @var{x}, @var{y} are the coordinates where the mouse
was clicked in the units of the current axes.  The return value @var{button}
is 1, 2, or 3 for the left, middle, or right button.  If a key is pressed
the ASCII value is returned in @var{button}.

Implementation Note: @code{ginput} is intenteded for 2-D plots.  For 3-D
plots see the @var{currentpoint} property of the current axes which can be
transformed with knowledge of the current @code{view} into data units.
@xseealso{gtext, waitforbuttonpress}
@end deftypefn
graphics_toolkit
@c graphics_toolkit scripts/plot/util/graphics_toolkit.m
@deftypefn  {} {@var{name} =} graphics_toolkit ()
@deftypefnx {} {@var{name} =} graphics_toolkit (@var{hlist})
@deftypefnx {} {} graphics_toolkit (@var{name})
@deftypefnx {} {} graphics_toolkit (@var{hlist}, @var{name})
Query or set the default graphics toolkit which is assigned to new figures.

With no inputs, return the current default graphics toolkit.  If the input
is a list of figure graphic handles, @var{hlist}, then return the name
of the graphics toolkit in use for each figure.

When called with a single input @var{name} set the default graphics toolkit
to @var{name}.  If the toolkit is not already loaded, it is initialized by
calling the function @code{__init_@var{name}__}.  If the first input
is a list of figure handles, @var{hlist}, then the graphics toolkit is set
to @var{name} for these figures only.

@xseealso{available_graphics_toolkits}
@end deftypefn
groot
@c groot scripts/plot/util/groot.m
@deftypefn {} {@var{h} =} groot ()
Return a handle to the root graphics object.

The root graphics object is the ultimate parent of all graphics objects.

In addition, the root object contains information about the graphics
system as a whole such as the @code{ScreenSize}.  Use @w{@code{get (groot)}}
to find out what information is available.

Defaults for the graphic system as a whole are specified by setting
properties of the root graphics object that begin with @qcode{"Default"}.
For example, to set the default font for all text objects to FreeSans use

@example
set (groot, "DefaultTextFontName", "FreeSans")
@end example

Default properties can be deleted by using @code{set} with the special
property value of @qcode{"remove"}.  To undo the default font assignment
above use

@example
set (groot, "DefaultTextFontName", "remove")
@end example

Programming Note: The root graphics object is identified by the special
handle value of 0.  At some point this unique value may change, but code can
be made resistant to future changes by using @code{groot} which is
guaranteed to always return the root graphics object.
@xseealso{gcf, gca, get, set}
@end deftypefn
hdl2struct
@c hdl2struct scripts/plot/util/hdl2struct.m
@deftypefn {} {@var{s} =} hdl2struct (@var{h})
Return a structure, @var{s}, whose fields describe the properties
of the object, and its children, associated with the handle, @var{h}.

The fields of the structure @var{s} are @qcode{"type"}, @qcode{"handle"},
@qcode{"properties"}, @qcode{"children"}, and @qcode{"special"}.
@xseealso{struct2hdl, hgsave, findobj}
@end deftypefn
hggroup
@c hggroup scripts/plot/util/hggroup.m
@deftypefn  {} {} hggroup ()
@deftypefnx {} {} hggroup (@var{hax})
@deftypefnx {} {} hggroup (@dots{}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{h} =} hggroup (@dots{})
Create handle graphics group object with axes parent @var{hax}.

If no parent is specified, the group is created in the current axes.

Multiple property/value pairs may be specified for the hggroup, but they
must appear in pairs.

The optional return value @var{h} is a graphics handle to the created
hggroup object.

Programming Note: An hggroup is a way to group base graphics objects such
as line objects or patch objects into a single unit which can react
appropriately.  For example, the individual lines of a contour plot are
collected into a single hggroup so that they can be made visible/invisible
with a single command, @code{set (hg_handle, "visible", "off")}.

@xseealso{addproperty, addlistener}
@end deftypefn
hgload
@c hgload scripts/plot/util/hgload.m
@deftypefn  {} {@var{h} =} hgload (@var{filename})
@deftypefnx {} {[@var{h}, @var{old_prop}] =} hgload (@var{filename}, @var{prop_struct})
Load the graphics objects in @var{filename} into a vector of graphics
handles @var{h}.

If @var{filename} has no extension, Octave will try to find the file with
and without the default extension @file{.ofig}.

If provided, the elements of structure @var{prop_struct} will be used to
override the properties of top-level objects stored in @var{filename}, and
the saved values from @var{filename} will be stored in @var{old_prop}.
@var{old_prop} is a cell array matching the size of @var{h}; each cell
contains a structure of the existing property names and values before being
overridden.

@xseealso{openfig, hgsave, struct2hdl}
@end deftypefn
hgsave
@c hgsave scripts/plot/util/hgsave.m
@deftypefn  {} {} hgsave (@var{filename})
@deftypefnx {} {} hgsave (@var{h}, @var{filename})
@deftypefnx {} {} hgsave (@var{h}, @var{filename}, @var{fmt})
Save the graphics handle(s) @var{h} to the file @var{filename} in the format
@var{fmt}.

If unspecified, @var{h} is the current figure as returned by @code{gcf}.

When @var{filename} does not have an extension the default filename
extension @file{.ofig} will be appended.

If present, @var{fmt} must be one of the following:

@itemize @bullet
@item @option{-binary}, @option{-float-binary}

@item @option{-hdf5}, @option{-float-hdf5}

@item @option{-V7}, @option{-v7}, @option{-7}, @option{-mat7-binary}

@item @option{-V6}, @option{-v6}, @option{-6}, @option{-mat6-binary}

@item @option{-text}

@item @option{-zip}, @option{-z}
@end itemize

The default format is @option{-binary} to minimize storage.

Programming Note: When producing graphics for final publication use
@code{print} or @code{saveas}.  When it is important to be able to continue
to edit a figure as an Octave object, use @code{hgsave}/@code{hgload}.
@xseealso{hgload, hdl2struct, savefig, saveas, print}
@end deftypefn
hgtransform
@c hgtransform scripts/plot/util/hgtransform.m
@deftypefn  {} {@var{h} =} hgtransform ()
@deftypefnx {} {@var{h} =} hgtransform (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{h} =} hgtransform (@var{hax}, @dots{})

Create a graphics transform object.

FIXME: Need to write documentation.
FIXME: Add 'makehgtform' to seealso list when it is implemented.
@xseealso{hggroup}
@end deftypefn
hold
@c hold scripts/plot/util/hold.m
@deftypefn  {} {} hold
@deftypefnx {} {} hold on
@deftypefnx {} {} hold off
@deftypefnx {} {} hold (@var{hax}, @dots{})
Toggle or set the @qcode{"hold"} state of the plotting engine which
determines whether new graphic objects are added to the plot or replace
the existing objects.

@table @code
@item hold on
Retain plot data and settings so that subsequent plot commands are displayed
on a single graph.  Line color and line style are advanced for each new plot
added.

@item hold all (deprecated)
Equivalent to @code{hold on}.

@item hold off
Restore default graphics settings which clear the graph and reset axes
properties before each new plot command.  (default).

@item hold
Toggle the current hold state.
@end table

When given the additional argument @var{hax}, the hold state is modified
for this axes rather than the current axes returned by @code{gca}.

To query the current hold state use the @code{ishold} function.
@xseealso{ishold, cla, clf, newplot}
@end deftypefn
isaxes
@c isaxes scripts/plot/util/isaxes.m
@deftypefn {} {} isaxes (@var{h})
Return true if @var{h} is an axes graphics handle and false otherwise.

If @var{h} is a matrix then return a logical array which is true where the
elements of @var{h} are axes graphics handles and false where they are not.
@xseealso{isfigure, ishghandle, isgraphics}
@end deftypefn
isfigure
@c isfigure scripts/plot/util/isfigure.m
@deftypefn {} {} isfigure (@var{h})
Return true if @var{h} is a figure graphics handle and false otherwise.

If @var{h} is a matrix then return a logical array which is true where the
elements of @var{h} are figure graphics handles and false where they are
not.
@xseealso{isaxes, ishghandle, isgraphics}
@end deftypefn
isgraphics
@c isgraphics scripts/plot/util/isgraphics.m
@deftypefn  {} {} isgraphics (@var{h})
@deftypefnx {} {} isgraphics (@var{h}, @var{type})
Return true if @var{h} is a graphics handle (of type @var{type}) and false
otherwise.

When no @var{type} is specified the function is equivalent to
@code{ishghandle}.
@xseealso{ishghandle, ishandle, isaxes, isfigure}
@end deftypefn
ishandle
@c ishandle scripts/plot/util/ishandle.m
@deftypefn {} {} ishandle (@var{h})
Return true if @var{h} is a handle to a graphics or Java object 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 handles to graphics
or Java objects and false where they are not.

Programming Note: It is often more useful to test for a specific object
type.  To determine if a handle belongs to a graphics object use
@code{ishghandle} or @code{isgraphics}.  To determine if a handle belongs
to a Java object use @code{isjava}.
@xseealso{ishghandle, isgraphics, isjava}
@end deftypefn
ishold
@c ishold scripts/plot/util/ishold.m
@deftypefn  {} {} ishold
@deftypefnx {} {} ishold (@var{hax})
@deftypefnx {} {} ishold (@var{hfig})
Return true if the next plot will be added to the current plot, or
false if the plot device will be cleared before drawing the next plot.

If the first argument is an axes handle @var{hax} or figure handle
@var{hfig} then operate on this plot rather than the current one.
@xseealso{hold, newplot}
@end deftypefn
isprop
@c isprop scripts/plot/util/isprop.m
@deftypefn {} {@var{res} =} isprop (@var{obj}, "@var{prop}")
Return true if @var{prop} is a property of the object @var{obj}.

@var{obj} may also be an array of objects in which case @var{res} will be a
logical array indicating whether each handle has the property @var{prop}.

For plotting, @var{obj} is a handle to a graphics object.  Otherwise,
@var{obj} should be an instance of a class.
@xseealso{get, set, ismethod, isobject}
@end deftypefn
linkaxes
@c linkaxes scripts/plot/util/linkaxes.m
@deftypefn  {} {} linkaxes (@var{hax})
@deftypefnx {} {} linkaxes (@var{hax}, @var{optstr})
Link the axis limits of 2-D plots such that a change in one is propagated
to the others.

The axes handles to be linked are passed as the first argument @var{hax}.

The optional second argument is a string which defines which axis limits
will be linked.  The possible values for @var{optstr} are:

@table @asis
@item @qcode{"x"}
Link x-axes

@item @qcode{"y"}
Link y-axes

@item @qcode{"xy"} (default)
Link both axes

@item @qcode{"off"}
Turn off linking
@end table

If unspecified the default is to link both X and Y axes.

When linking, the limits from the first axes in @var{hax} are applied to the
other axes in the list.  Subsequent changes to any one of the axes will be
propagated to the others.

@xseealso{linkprop, addproperty}
@end deftypefn
linkprop
@c linkprop scripts/plot/util/linkprop.m
@deftypefn  {} {@var{hlink} =} linkprop (@var{h}, "@var{prop}")
@deftypefnx {} {@var{hlink} =} linkprop (@var{h}, @{"@var{prop1}", "@var{prop2}", @dots{}@})
Link graphic object properties, such that a change in one is propagated to
the others.

The input @var{h} is a vector of graphic handles to link.

@var{prop} may be a string when linking a single property, or a cell array
of strings for multiple properties.  During the linking process all
properties in @var{prop} will initially be set to the values that exist on
the first object in the list @var{h}.

The function returns @var{hlink} which is a special object describing the
link.  As long as the reference @var{hlink} exists, the link between graphic
objects will be active.  This means that @var{hlink} must be preserved in
a workspace variable, a global variable, or otherwise stored using a
function such as @code{setappdata} or @code{guidata}.  To unlink properties,
execute @code{clear @var{hlink}}.

An example of the use of @code{linkprop} is

@example
@group
x = 0:0.1:10;
subplot (1,2,1);
h1 = plot (x, sin (x));
subplot (1,2,2);
h2 = plot (x, cos (x));
hlink = linkprop ([h1, h2], @{"color","linestyle"@});
set (h1, "color", "green");
set (h2, "linestyle", "--");
@end group
@end example

@xseealso{linkaxes, addlistener}
@end deftypefn
meshgrid
@c meshgrid scripts/plot/util/meshgrid.m
@deftypefn  {} {[@var{xx}, @var{yy}] =} meshgrid (@var{x}, @var{y})
@deftypefnx {} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x}, @var{y}, @var{z})
@deftypefnx {} {[@var{xx}, @var{yy}] =} meshgrid (@var{x})
@deftypefnx {} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x})
Given vectors of @var{x} and @var{y} coordinates, return matrices @var{xx}
and @var{yy} corresponding to a full 2-D grid.

The rows of @var{xx} are copies of @var{x}, and the columns of @var{yy} are
copies of @var{y}.  If @var{y} is omitted, then it is assumed to be the same
as @var{x}.

If the optional @var{z} input is given, or @var{zz} is requested, then the
output will be a full 3-D grid.  If @var{z} is omitted and @var{zz} is
requested, it is assumed to be the same as @var{y}.

@code{meshgrid} is most frequently used to produce input for a 2-D or 3-D
function that will be plotted.  The following example creates a surface
plot of the ``sombrero'' function.

@example
@group
f = @@(x,y) sin (sqrt (x.^2 + y.^2)) ./ sqrt (x.^2 + y.^2);
range = linspace (-8, 8, 41);
[@var{X}, @var{Y}] = meshgrid (range, range);
Z = f (X, Y);
surf (X, Y, Z);
@end group
@end example

Programming Note: @code{meshgrid} is restricted to 2-D or 3-D grid
generation.  The @code{ndgrid} function will generate 1-D through N-D
grids.  However, the functions are not completely equivalent.  If @var{x}
is a vector of length M and @var{y} is a vector of length N, then
@code{meshgrid} will produce an output grid which is NxM@.  @code{ndgrid}
will produce an output which is @nospell{MxN} (transpose) for the same
input.  Some core functions expect @code{meshgrid} input and others expect
@code{ndgrid} input.  Check the documentation for the function in question
to determine the proper input format.
@xseealso{ndgrid, mesh, contour, surf}
@end deftypefn
ndgrid
@c ndgrid scripts/plot/util/ndgrid.m
@deftypefn  {} {[@var{y1}, @var{y2}, @dots{}, @var{y}n] =} ndgrid (@var{x1}, @var{x2}, @dots{}, @var{x}n)
@deftypefnx {} {[@var{y1}, @var{y2}, @dots{}, @var{y}n] =} ndgrid (@var{x})
Given n vectors @var{x1}, @dots{}, @var{x}n, @code{ndgrid} returns n
arrays of dimension n.

The elements of the i-th output argument contains the elements of the
vector @var{x}i repeated over all dimensions different from the i-th
dimension.  Calling ndgrid with only one input argument @var{x} is
equivalent to calling ndgrid with all n input arguments equal to @var{x}:

[@var{y1}, @var{y2}, @dots{}, @var{y}n] = ndgrid (@var{x}, @dots{}, @var{x})

Programming Note: @code{ndgrid} is very similar to the function
@code{meshgrid} except that the first two dimensions are transposed in
comparison to @code{meshgrid}.  Some core functions expect @code{meshgrid}
input and others expect @code{ndgrid} input.  Check the documentation for
the function in question to determine the proper input format.
@xseealso{meshgrid}
@end deftypefn
newplot
@c newplot scripts/plot/util/newplot.m
@deftypefn  {} {} newplot ()
@deftypefnx {} {} newplot (@var{hfig})
@deftypefnx {} {} newplot (@var{hax})
@deftypefnx {} {@var{hax} =} newplot (@dots{})
Prepare graphics engine to produce a new plot.

This function is called at the beginning of all high-level plotting
functions.  It is not normally required in user programs.  @code{newplot}
queries the @qcode{"NextPlot"} field of the current figure and axes to
determine what to do.

@multitable @columnfractions .25 .75
@headitem Figure NextPlot @tab Action
@item @qcode{"new"} @tab Create a new figure and make it the current figure.

@item @qcode{"add"} (default) @tab Add new graphic objects to the current
figure.

@item @qcode{"replacechildren"} @tab Delete child objects whose
HandleVisibility is set to @qcode{"on"}.  Set NextPlot property to
@qcode{"add"}.  This typically clears a figure, but leaves in place hidden
objects such as menubars.  This is equivalent to @code{clf}.

@item @qcode{"replace"} @tab Delete all child objects of the figure and
reset all figure properties to their defaults.  However, the following
four properties are not reset: Position, Units, PaperPosition, PaperUnits.
This is equivalent to @code{clf reset}.
@end multitable

@multitable @columnfractions .25 .75
@headitem Axes NextPlot @tab Action
@item @qcode{"add"} @tab Add new graphic objects to the current axes.  This
is equivalent to @code{hold on}.

@item @qcode{"replacechildren"} @tab Delete child objects whose
HandleVisibility is set to @qcode{"on"}, but leave axes properties
unmodified.  This typically clears a plot, but preserves special settings
such as log scaling for axes.  This is equivalent to @code{cla}.

@item @qcode{"replace"} (default) @tab Delete all child objects of the
axes and reset all axes properties to their defaults.  However, the
following properties are not reset: Position, Units.  This is equivalent
to @code{cla reset}.
@end multitable

If the optional input @var{hfig} or @var{hax} is given then prepare the
specified figure or axes rather than the current figure and axes.

The optional return value @var{hax} is a graphics handle to the created
axes object (not figure).

@strong{Caution:} Calling @code{newplot} may change the current figure and
current axes.
@end deftypefn
openfig
@c openfig scripts/plot/util/openfig.m
@deftypefn  {} {} openfig
@deftypefnx {} {} openfig (@var{filename})
@deftypefnx {} {} openfig (@dots{}, @var{copies})
@deftypefnx {} {} openfig (@dots{}, @var{visibility})
@deftypefnx {} {@var{h} =} openfig (@dots{})
Read saved figure window(s) from @var{filename} and return graphics
handle(s) @var{h}.

By default, @var{filename} is @qcode{"Untitled.fig"}.  If a full path is not
specified, the file opened will be the first one encountered in the load
path.  If @var{filename} is not found and does not have an extension, a
search will take place for the first file in the load path with extension
@qcode{".fig"} or @qcode{".ofig"}, in that order.

@var{copies} is an optional input indicating whether a new figure should
be created (@qcode{"new"}) or whether an existing figure may be reused
(@qcode{"reuse"}).  An existing figure may be reused if the
@qcode{"FileName"} property matches the specified input @var{filename}.
When a figure is reused it becomes the active figure and is shown on top
of other figures.  If the figure was offscreen, it is re-positioned to be
onscreen.  The default value for @var{copies} is @qcode{"new"}.

@var{visibility} is an optional input indicating whether to show the figure
(@qcode{"visible"}) or not (@qcode{"invisible"}).  When @var{visibility} is
specified as an input to @code{openfig} it overrides the visibility setting
stored in @var{filename}.

@xseealso{open, hgload, savefig, struct2hdl}
@end deftypefn
pan
@c pan scripts/plot/util/pan.m
@deftypefn  {} {} pan
@deftypefnx {} {} pan on
@deftypefnx {} {} pan off
@deftypefnx {} {} pan xon
@deftypefnx {} {} pan yon
@deftypefnx {} {} pan (@var{hfig}, @var{option})
Control the interactive panning mode of a figure in the GUI.

Given the option @qcode{"on"} or @qcode{"off"}, set the interactive
pan mode on or off.

With no arguments, toggle the current pan mode on or off.

Given the option @qcode{"xon"} or @qcode{"yon"}, enable pan mode
for the x or y axis only.

If the first argument @var{hfig} is a figure, then operate on the given
figure rather than the current figure as returned by @code{gcf}.

@xseealso{rotate3d, zoom}
@end deftypefn
print
@c print scripts/plot/util/print.m
@deftypefn  {} {} print ()
@deftypefnx {} {} print (@var{options})
@deftypefnx {} {} print (@var{filename}, @var{options})
@deftypefnx {} {} print (@var{hfig}, @dots{})
@deftypefnx {} {@var{rgb} =} print (@qcode{"-RGBImage"}, @dots{})
Format a figure for printing and either save it to a file, send it to a
printer, or return an RGB image.

@var{filename} defines the name of the output file.  If the filename has
no suffix then one is inferred from the specified device and appended to the
filename.  When neither a filename nor the @qcode{"-RGBImage"} option is
present, the output is sent to the printer.  The various options and
filename arguments may be given in any order, except for the figure handle
argument @var{hfig} which must be first if it is present.

Example: Print to a file using PDF and JPEG formats.

@example
@group
figure (1);
clf ();
surf (peaks);
print figure1.pdf    # The extension specifies the format
print -djpg figure1  # Will produce "figure1.jpg" file
@end group
@end example

If the first argument is a handle @var{hfig} to a figure object then it
specifies the figure to print.  By default, the current figure returned
by @code{gcf} is printed.

For outputs to paged formats, for example, PostScript and PDF, the page size
is specified by the figure's @code{papersize} property together with the
@code{paperunits} property.  The location and size of the plot on the page
are specified by the figure's @code{paperposition} property.  The
orientation of the page is specified by the figure's @code{paperorientation}
property.

For non-page formats---for example, image formats like JPEG---the width and
height of the output are specified by the figure's @code{paperposition(3:4)}
property values.

The @code{print} command supports many @var{options}:

@table @code
@item -f@var{h}
  Specify the handle, @var{h}, of the figure to be printed.

Example: Print figure 1.

@example
@group
figure (1);
clf ();
surf (peaks);
figure (2);
print -f1 figure1.pdf
## Equivalent functional form:
print (1, "figure1.pdf")
@end group
@end example

@item -P@var{printer}
  Set the @var{printer} name to which the plot is sent if no @var{filename}
is specified.

Example: Print to printer named PS_printer using PostScript format.

@example
@group
clf ();
surf (peaks);
print -dpswrite -PPS_printer
@end group
@end example

@item -RGBImage
  Return an M-by-N-by-3 RGB image of the figure.  The size of the image
depends on the formatting options.  This is similar to taking a screen
capture of the plot, but formatting options may be changed such as the
resolution or monochrome/color.

Example: Get the pixels of a figure image.

@example
@group
clf ();
surf (peaks);
@var{rgb} = print ("-RGBImage");
@end group
@end example

@item  -opengl
@itemx -painters
  Specifies whether the opengl (pixel-based) or painters (vector-based)
renderer is used.  This is equivalent to changing the figure's
@qcode{"Renderer"} property.  When the figure @code{RendererMode} property
is @qcode{"auto"} Octave will use the @qcode{"opengl"} renderer for raster
formats (e.g., JPEG) and @qcode{"painters"} for vector formats (e.g., PDF)@.
Those options are only supported for the "qt" graphics tookit.

@item -svgconvert
  For OpenGL-based graphic toolkits, this enables a different backend
toolchain with enhanced characteristics.  The toolchain adds support for
printing arbitrary characters and fonts in PDF outputs; it avoids some
anti-aliasing artifacts in the rendering of patch and surface objects
(particularly for 2-D scenes); and it supports transparency of line, patch,
and surface objects.

This option only affects PDF outputs, unless it is combined with
@option{-painters} option, in which case raster outputs are also affected.

Caution: @option{-svgconvert} may lead to inaccurate rendering of image
objects.

@item  -portrait
@itemx -landscape
  Specify the orientation of the plot for printed output.
For non-printed output the aspect ratio of the output corresponds to the
plot area defined by the @qcode{"paperposition"} property in the
orientation specified.  This option is equivalent to changing the figure's
@qcode{"paperorientation"} property.

@item  -fillpage
@itemx -bestfit
  When using a page-based format (PDF, PostScript, printer) ignore the
@qcode{"paperposition"} property and have the plot occupy the entire page.
The option @option{-fillpage} will stretch the plot to occupy the page with
0.25 inch margins all around.  The option @option{-bestfit} will expand the
plot to take up as much room as possible on the page @strong{without}
distorting the original aspect ratio of the plot.

@item  -color
@itemx -mono
  Color or monochrome output.

@item  -solid
@itemx -dashed
  Force all lines to be solid or dashed, respectively.

@item -noui
  Don't print uicontrol objects such as pushbuttons which may overlay the
plot.  This is the default behavior and it is not possible to include
uicontrol objects in the output without using an external screen capture
tool.

@item -r@var{NUM}
  Resolution of bitmaps in dots per inch (DPI).  For both metafiles and SVG
the default is the screen resolution; for other formats the default is 150
DPI@.  To specify screen resolution, use @qcode{"-r0"}.

Example: high resolution raster output.

@example
@group
clf ();
surf (peaks (), "facelighting", "gouraud");
light ();
print ("-r600", "lit_peaks.png");
@end group
@end example

@item -S@var{xsize},@var{ysize}
  Plot size in pixels for raster formats including PNG, JPEG, PNG, and
(unusually (SVG))@.  For all vector formats, including PDF, PS, and EPS, the
plot size is specified in points.  This option is equivalent to changing the
width and height of the output by setting the figure property
@code{paperposition(3:4)}.  When using the command form of the print
function you must quote the @var{xsize},@var{ysize} option to prevent the
Octave interpreter from recognizing the embedded comma (',').  For example,
by writing @w{"-S640,480"}.

@item  -loose
@itemx -tight
  Force a tight or loose bounding box for EPS files.  The default is loose.

@item -@var{preview}
  Add a preview to EPS files.  Supported formats are:

@table @code
@item -interchange
    Provide an interchange preview.

@item -metafile
    Provide a metafile preview.

@item -pict
    Provide a pict preview.

@item -tiff
    Provide a TIFF preview.
@end table

@item -append
  Append PostScript or PDF output to an existing file of the same type.

@item  -F@var{fontname}
@itemx -F@var{fontname}:@var{size}
@itemx -F:@var{size}
  Use @var{fontname} and/or @var{fontsize} for all text.
@var{fontname} is ignored for some devices: dxf, fig, hpgl, etc.

@item -d@var{device}
  The available output format is specified by the option @var{device}, and
is one of the following (devices marked with a "*" are only available with
the Gnuplot toolkit):

Vector Formats

@table @code
@item  pdf
@itemx pdfcrop
    Portable Document Format.  The @code{pdfcrop} device removes the default
surrounding page.

The OpenGL-based graphics toolkits have limited support for text.
Limitations include using only ASCII characters (e.g., no Greek letters)
and support for just three base PostScript fonts: Helvetica (the default),
Times, or Courier.  Any other font will be replaced by Helvetica.

For an enhanced output with complete text support and basic transparency,
use the @option{-svgconvert} option.

@item  ps
@itemx ps2
@itemx psc
@itemx psc2
    PostScript (level 1 and 2, mono and color).  The OpenGL-based graphics
toolkits always generate PostScript level 3.0 and have limited support for
text.

@item  eps
@itemx eps2
@itemx epsc
@itemx epsc2
    Encapsulated PostScript (level 1 and 2, mono and color).  The
OpenGL-based toolkits always generate PostScript level 3.0 and have
limited support for text.

@item  pslatex
@itemx epslatex
@itemx pdflatex
@itemx pslatexstandalone
@itemx epslatexstandalone
@itemx pdflatexstandalone
    Generate a @LaTeX{} file @file{@var{filename}.tex} for the text portions
of a plot and a file @file{@var{filename}.(ps|eps|pdf)} for the remaining
graphics.  The graphics file suffix .ps|eps|pdf is determined by the
specified device type.  The @LaTeX{} file produced by the @samp{standalone}
option can be processed directly by @LaTeX{}.  The file generated without
the @samp{standalone} option is intended to be included from another
@LaTeX{} document.  In either case, the @LaTeX{} file contains an
@code{\includegraphics} command so that the generated graphics file is
automatically included when the @LaTeX{} file is processed.  The text that
is written to the @LaTeX{} file contains the strings @strong{exactly} as
they were specified in the plot.  If any special characters of the @TeX{}
mode interpreter were used, the file must be edited before @LaTeX{}
processing.  Specifically, the special characters must be enclosed with
dollar signs @w{(@code{$ @dots{} $})}, and other characters that are
recognized by @LaTeX{} may also need editing (e.g., braces).  The
@samp{pdflatex} device, and any of the @samp{standalone} formats, are not
available with the Gnuplot toolkit.

@item  epscairo*
@itemx pdfcairo*
@itemx epscairolatex*
@itemx pdfcairolatex*
@itemx epscairolatexstandalone*
@itemx pdfcairolatexstandalone*
    Generate output with Cairo renderer.  The devices @samp{epscairo} and
@samp{pdfcairo} are synonymous with the @samp{epsc} device.  The @LaTeX{}
variants generate a @LaTeX{} file, @file{@var{filename}.tex}, for the text
portions of a plot, and an image file, @file{@var{filename}.(eps|pdf)}, for
the graph portion of the plot.  The @samp{standalone} variants behave as
described for @samp{epslatexstandalone} above.

@item svg
    Scalable Vector Graphics

@item canvas*
    Javascript-based drawing on an HTML5 canvas viewable in a web browser.

@item  cdr*
@itemx @nospell{corel*}
    CorelDraw

@item cgm*
    Computer Graphics Metafile, Version 1, ANSI X3.122-1986

@item dxf
    AutoCAD

@item  emf
@itemx meta
    Microsoft Enhanced Metafile

@item fig
    XFig.  For the Gnuplot graphics toolkit, the additional options
@option{-textspecial} or @option{-textnormal} can be used to control
whether the special flag should be set for the text in the figure.
(default is @option{-textnormal})

@item hpgl
    HP plotter language

@item  ill
@itemx @nospell{aifm}
    Adobe Illustrator (obsolete for Gnuplot versions > 4.2)

@item  latex*
@itemx eepic*
@LaTeX{} picture environment and extended picture environment.

@item mf*
    Metafont

@item  tikz
@itemx tikzstandalone*
    Generate a @LaTeX{} file using PGF/TikZ format.  The OpenGL-based
toolkits create a PGF file while Gnuplot creates a TikZ file.  The
@samp{tikzstandalone} device produces a @LaTeX{} document which includes the
TikZ file.

@end table

Raster Formats

@table @code
@item png
    Portable Network Graphics

@item  jpg
@itemx jpeg
    JPEG image

@item  tif
@itemx tiff
@itemx tiffn
    TIFF image with LZW compression (@nospell{tif}, tiff) or uncompressed
(@nospell{tiffn}).

@item gif
    GIF image

@item pbm
    PBMplus

@item dumb*
    ASCII art

@end table

  If the device is omitted, it is inferred from the file extension,
or if there is no filename then it is sent to the printer as PostScript.

@item -d@var{ghostscript_device}
  Additional devices are supported by Ghostscript.
Some examples are:

@table @code
@item ljet2p
    HP LaserJet @nospell{IIP}

@item pcx24b
    24-bit color PCX file format

@item ppm
    Portable Pixel Map file format
@end table

  For a complete list of available formats and devices type
@code{system ("gs -h")}.

  When Ghostscript output is sent to a printer the size is determined by
the figure's @qcode{"papersize"} property.  When the output is sent to a
file the size is determined by the plot box defined by the figure's
@qcode{"paperposition"} property.

@item -G@var{ghostscript_command}
  Specify the command for calling Ghostscript.  For Unix the default is
@qcode{"gs"} and for Windows it is @qcode{"gswin32c"}.

@item  -TextAlphaBits=@var{n}
@itemx -GraphicsAlphaBits=@var{n}
  Octave is able to produce output for various printers, bitmaps, and
vector formats by using Ghostscript.  For bitmap and printer output
anti-aliasing is applied using Ghostscript's TextAlphaBits and
GraphicsAlphaBits options.  The default number of bits are 4 and 1
respectively.  Allowed values for @var{N} are 1, 2, or 4.
@end table

@xseealso{saveas, hgsave, getframe, orient, figure}
@end deftypefn
printd
@c printd scripts/plot/util/printd.m
@deftypefn  {} {} printd (@var{obj}, @var{filename})
@deftypefnx {} {@var{out_file} =} printd (@dots{})

Convert any object acceptable to @code{disp} into the format selected by
the suffix of @var{filename}.

If the return argument @var{out_file} is given, the name of the created
file is returned.

This function is intended to facilitate manipulation of the output of
functions such as @code{stemleaf}.
@xseealso{stemleaf}
@end deftypefn
refresh
@c refresh scripts/plot/util/refresh.m
@deftypefn  {} {} refresh ()
@deftypefnx {} {} refresh (@var{h})
Refresh a figure, forcing it to be redrawn.

When called without an argument the current figure is redrawn.  Otherwise,
the figure with graphic handle @var{h} is redrawn.
@xseealso{drawnow}
@end deftypefn
refreshdata
@c refreshdata scripts/plot/util/refreshdata.m
@deftypefn  {} {} refreshdata ()
@deftypefnx {} {} refreshdata (@var{h})
@deftypefnx {} {} refreshdata (@var{h}, @var{workspace})
Evaluate any @samp{datasource} properties of the current figure and update
the plot if the corresponding data has changed.

If the first argument @var{h} is a list of graphic handles, then operate
on these objects rather than the current figure returned by @code{gcf}.

The optional second argument @var{workspace} can take the following values:

@table @asis
@item @qcode{"base"}
Evaluate the datasource properties in the base workspace.  (default).

@item @qcode{"caller"}
Evaluate the datasource properties in the workspace of the function
that called @code{refreshdata}.
@end table

An example of the use of @code{refreshdata} is:

@example
@group
x = 0:0.1:10;
y = sin (x);
plot (x, y, "ydatasource", "y");
for i = 1 : 100
  pause (0.1);
  y = sin (x + 0.1*i);
  refreshdata ();
endfor
@end group
@end example
@end deftypefn
rotate
@c rotate scripts/plot/util/rotate.m
@deftypefn  {} {} rotate (@var{h}, @var{direction}, @var{alpha})
@deftypefnx {} {} rotate (@dots{}, @var{origin})
Rotate the plot object @var{h} through @var{alpha} degrees around the line
with direction @var{direction} and origin @var{origin}.

The default value of @var{origin} is the center of the axes object that is
the parent of @var{h}.

If @var{h} is a vector of handles, they must all have the same parent axes
object.

Graphics objects that may be rotated are lines, surfaces, patches, and
images.
@end deftypefn
rotate3d
@c rotate3d scripts/plot/util/rotate3d.m
@deftypefn  {} {} rotate3d
@deftypefnx {} {} rotate3d on
@deftypefnx {} {} rotate3d off
@deftypefnx {} {} rotate3d (@var{hfig}, @var{option})
Control the interactive 3-D rotation mode of a figure in the GUI.

Given the option @qcode{"on"} or @qcode{"off"}, set the interactive
rotate mode on or off.

With no arguments, toggle the current rotate mode on or off.

If the first argument @var{hfig} is a figure, then operate on the given
figure rather than the current figure as returned by @code{gcf}.

@xseealso{pan, zoom}
@end deftypefn
saveas
@c saveas scripts/plot/util/saveas.m
@deftypefn  {} {} saveas (@var{h}, @var{filename})
@deftypefnx {} {} saveas (@var{h}, @var{filename}, @var{fmt})
Save graphic object @var{h} to the file @var{filename} in graphic format
@var{fmt}.

All device formats accepted by @code{print} may be used.  Common formats
are:

@table @code
@item ps
    PostScript

@item eps
    Encapsulated PostScript

@item pdf
    Portable Document Format

@item jpg
    JPEG Image

@item png
    Portable Network Graphics image

@item emf
    Enhanced MetaFile

@item tif
    TIFF Image, compressed

@end table

If @var{fmt} is omitted it is extracted from the extension of
@var{filename}.  The default format when there is no extension is
@qcode{"pdf"}.

@example
@group
clf ();
surf (peaks);
saveas (1, "figure1.png");
@end group
@end example

@xseealso{print, hgsave, orient}
@end deftypefn
savefig
@c savefig scripts/plot/util/savefig.m
@deftypefn  {} {} savefig ()
@deftypefnx {} {} savefig (@var{h})
@deftypefnx {} {} savefig (@var{filename})
@deftypefnx {} {} savefig (@var{h}, @var{filename})
@deftypefnx {} {} savefig (@var{h}, @var{filename}, @qcode{"compact"})
Save figure windows specified by graphics handle(s) @var{h} to file
@var{filename}.

If unspecified, @var{h} is the current figure returned by @code{gcf}.

If unspecified, @var{filename} is set to @file{"Untitled.fig"}.  If
@var{filename} does not have an extension then the default extension
@file{".fig"} will be added.

If the optional third input @qcode{"compact"} is present then the data
will be compressed to save more space.

@xseealso{hgsave, hdl2struct, openfig}
@end deftypefn
shg
@c shg scripts/plot/util/shg.m
@deftypefn {} {} shg
Show the graph window.

This function makes the current figure visible, and places it on top of
of all other plot windows.

Programming Note: @code{shg} is equivalent to @code{figure (gcf)} assuming
that a current figure exists.
@xseealso{figure, drawnow, gcf}
@end deftypefn
struct2hdl
@c struct2hdl scripts/plot/util/struct2hdl.m
@deftypefn  {} {@var{h} =} struct2hdl (@var{s})
@deftypefnx {} {@var{h} =} struct2hdl (@var{s}, @var{p})
@deftypefnx {} {@var{h} =} struct2hdl (@var{s}, @var{p}, @var{hilev})
Construct a graphics handle object @var{h} from the structure @var{s}.

The structure must contain the fields @qcode{"handle"}, @qcode{"type"},
@qcode{"children"}, @qcode{"properties"}, and @qcode{"special"}.

If the handle of an existing figure or axes is specified, @var{p}, the new
object will be created as a child of that object.  If no parent handle is
provided then a new figure and the necessary children will be constructed
using the default values from the root object.

A third boolean argument @var{hilev} can be passed to specify whether the
function should preserve listeners/callbacks, e.g., for legends or
hggroups.  The default is false.
@xseealso{hdl2struct, hgload, findobj}
@end deftypefn
subplot
@c subplot scripts/plot/util/subplot.m
@deftypefn  {} {} subplot (@var{rows}, @var{cols}, @var{index})
@deftypefnx {} {} subplot (@var{rows}, @var{cols}, @var{index}, @var{hax})
@deftypefnx {} {} subplot (@var{rcn})
@deftypefnx {} {} subplot (@var{hax})
@deftypefnx {} {} subplot (@dots{}, "align")
@deftypefnx {} {} subplot (@dots{}, "replace")
@deftypefnx {} {} subplot (@dots{}, "position", @var{pos})
@deftypefnx {} {} subplot (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@var{hax} =} subplot (@dots{})
Set up a plot grid with @var{rows} by @var{cols} subwindows and set the
current axes for plotting (@code{gca}) to the location given by @var{index}.

If an axes handle @var{hax} is provided after the (@var{rows}, @var{cols},
@var{index}) arguments, the corresponding axes is turned into a
subplot.

If only one numeric argument is supplied, then it must be a three digit
value specifying the number of rows in digit 1, the number of columns in
digit 2, and the plot index in digit 3.

The plot index runs row-wise; First, all columns in a row are numbered
and then the next row is filled.

For example, a plot with 2x3 grid will have plot indices running as follows:
@tex
\vskip 10pt
\hfil\vbox{\offinterlineskip\hrule
\halign{\vrule#&&\qquad\hfil#\hfil\qquad\vrule\cr
height13pt&1&2&3\cr height12pt&&&\cr\noalign{\hrule}
height13pt&4&5&6\cr height12pt&&&\cr\noalign{\hrule}}}
\hfil
\vskip 10pt
@end tex
@ifnottex

@example
@group
+-----+-----+-----+
|  1  |  2  |  3  |
+-----+-----+-----+
|  4  |  5  |  6  |
+-----+-----+-----+
@end group
@end example

@end ifnottex

@var{index} may also be a vector.  In this case, the new axes will enclose
the grid locations specified.  The first demo illustrates this:

@example
demo ("subplot", 1)
@end example

The index of the subplot to make active may also be specified by its axes
handle, @var{hax}, returned from a previous @code{subplot} command.

If the option @qcode{"align"} is given then the plot boxes of the subwindows
will align, but this may leave no room for axes tick marks or labels.

If the option @qcode{"replace"} is given then the subplot axes will be
reset, rather than just switching the current axes for plotting to the
requested subplot.

The @qcode{"position"} property can be used to exactly position the subplot
axes within the current figure.  The option @var{pos} is a 4-element vector
[x, y, width, height] that determines the location and size of the axes.
The values in @var{pos} are normalized in the range [0,1].

Any property/value pairs are passed directly to the underlying axes object.

If the output @var{hax} is requested, subplot returns the axes handle for
the subplot.  This is useful for modifying the properties of a subplot
using @code{set}.
@xseealso{axes, plot, gca, set}
@end deftypefn
zoom
@c zoom scripts/plot/util/zoom.m
@deftypefn  {} {} zoom
@deftypefnx {} {} zoom (@var{factor})
@deftypefnx {} {} zoom on
@deftypefnx {} {} zoom off
@deftypefnx {} {} zoom xon
@deftypefnx {} {} zoom yon
@deftypefnx {} {} zoom out
@deftypefnx {} {} zoom reset
@deftypefnx {} {} zoom (@var{hfig}, @var{option})
Zoom the current axes object or control the interactive zoom mode of a
figure in the GUI.

Given a numeric argument greater than zero, zoom by the given factor.  If
the zoom factor is greater than one, zoom in on the plot.  If the factor
is less than one, zoom out.  If the zoom factor is a two- or three-element
vector, then the elements specify the zoom factors for the x, y, and z
axes respectively.

Given the option @qcode{"on"} or @qcode{"off"}, set the interactive zoom
mode on or off.

With no arguments, toggle the current zoom mode on or off.

Given the option @qcode{"xon"} or @qcode{"yon"}, enable zoom mode for the
x or y-axis only.

Given the option @qcode{"out"}, zoom to the initial zoom setting.

Given the option @qcode{"reset"}, store the current zoom setting so that
@code{zoom out} will return to this zoom level.

If the first argument @var{hfig} is a figure, then operate on the given
figure rather than the current figure as returned by @code{gcf}.

@xseealso{pan, rotate3d}
@end deftypefn
compan
@c compan scripts/polynomial/compan.m
@deftypefn {} {} compan (@var{c})
Compute the companion matrix corresponding to polynomial coefficient vector
@var{c}.

The companion matrix is
@tex
$$
A = \left[\matrix{
 -c_2/c_1 & -c_3/c_1 & \cdots & -c_N/c_1 & -c_{N+1}/c_1\cr
     1    &     0    & \cdots &     0    &         0   \cr
     0    &     1    & \cdots &     0    &         0   \cr
  \vdots  &   \vdots & \ddots &  \vdots  &      \vdots \cr
     0    &     0    & \cdots &     1    &         0}\right].
$$
@end tex
@ifnottex
@c Set example in small font to prevent overfull line

@smallexample
@group
     _                                                        _
    |  -c(2)/c(1)   -c(3)/c(1)  @dots{}  -c(N)/c(1)  -c(N+1)/c(1)  |
    |       1            0      @dots{}       0             0      |
    |       0            1      @dots{}       0             0      |
A = |       .            .      .         .             .      |
    |       .            .       .        .             .      |
    |       .            .        .       .             .      |
    |_      0            0      @dots{}       1             0     _|
@end group
@end smallexample

@end ifnottex
The eigenvalues of the companion matrix are equal to the roots of the
polynomial.
@xseealso{roots, poly, eig}
@end deftypefn
conv
@c conv scripts/polynomial/conv.m
@deftypefn  {} {} conv (@var{a}, @var{b})
@deftypefnx {} {} conv (@var{a}, @var{b}, @var{shape})
Convolve two vectors @var{a} and @var{b}.

When @var{a} and @var{b} are the coefficient vectors of two polynomials, the
convolution represents the coefficient vector of the product polynomial.

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)
The result is a vector with length equal to
@code{length (@var{a}) + length (@var{b}) - 1}.

@item @var{shape} = @qcode{"same"}
Return the central part of the convolution with the same size as @var{a}.

@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 (@var{a}) - size (@var{b}) + 1, 0)}.
@end table

@xseealso{deconv, conv2, convn, fftconv}
@end deftypefn
deconv
@c deconv scripts/polynomial/deconv.m
@deftypefn  {} {@var{b} =} deconv (@var{y}, @var{a})
@deftypefnx {} {[@var{b}, @var{r}] =} deconv (@var{y}, @var{a})
Deconvolve two vectors (polynomial division).

@code{[@var{b}, @var{r}] = deconv (@var{y}, @var{a})} solves for @var{b} and
@var{r} such that @code{@var{y} = conv (@var{a}, @var{b}) + @var{r}}.

If @var{y} and @var{a} are polynomial coefficient vectors, @var{b} will
contain the coefficients of the polynomial quotient and @var{r} will be
a remainder polynomial of lowest order.
@xseealso{conv, residue}
@end deftypefn
mkpp
@c mkpp scripts/polynomial/mkpp.m
@deftypefn  {} {@var{pp} =} mkpp (@var{breaks}, @var{coefs})
@deftypefnx {} {@var{pp} =} mkpp (@var{breaks}, @var{coefs}, @var{d})

Construct a piecewise polynomial (pp) structure from sample points
@var{breaks} and coefficients @var{coefs}.

@var{breaks} must be a vector of strictly increasing values.  The number of
intervals is given by @code{@var{ni} = length (@var{breaks}) - 1}.

When @var{m} is the polynomial order @var{coefs} must be of size:
@w{@var{ni}-by-(@var{m} + 1)}.

The i-th row of @var{coefs}, @code{@var{coefs}(@var{i},:)}, contains the
coefficients for the polynomial over the @var{i}-th interval, ordered from
highest (@var{m}) to lowest (@var{0}) degree.

@var{coefs} may also be a multi-dimensional array, specifying a
vector-valued or array-valued polynomial.  In that case the polynomial
order @var{m} is defined by the length of the last dimension of @var{coefs}.
The size of first dimension(s) are given by the scalar or vector @var{d}.
If @var{d} is not given it is set to @code{1}.  In this case
@code{@var{p}(@var{r}, @var{i}, :)} contains the coefficients for the
@var{r}-th polynomial defined on interval @var{i}.  In any case @var{coefs}
is reshaped to a 2-D matrix of size @code{[@var{ni}*prod(@var{d}) @var{m}]}.

Programming Note: @code{ppval} evaluates polynomials at
@code{@var{xi} - @var{breaks}(i)}, i.e., it subtracts the lower endpoint of
the current interval from @var{xi}.  This must be taken into account when
creating piecewise polynomials objects with @code{mkpp}.
@xseealso{unmkpp, ppval, spline, pchip, ppder, ppint, ppjumps}
@end deftypefn
mpoles
@c mpoles scripts/polynomial/mpoles.m
@deftypefn  {} {[@var{multp}, @var{idxp}] =} mpoles (@var{p})
@deftypefnx {} {[@var{multp}, @var{idxp}] =} mpoles (@var{p}, @var{tol})
@deftypefnx {} {[@var{multp}, @var{idxp}] =} mpoles (@var{p}, @var{tol}, @var{reorder})
Identify unique poles in @var{p} and their associated multiplicity.

The output is ordered from largest pole to smallest pole.

If the relative difference of two poles is less than @var{tol} then they are
considered to be multiples.  The default value for @var{tol} is 0.001.

If the optional parameter @var{reorder} is zero, poles are not sorted.

The output @var{multp} is a vector specifying the multiplicity of the poles.
@code{@var{multp}(n)} refers to the multiplicity of the Nth pole
@code{@var{p}(@var{idxp}(n))}.

For example:

@example
@group
p = [2 3 1 1 2];
[m, n] = mpoles (p)
   @result{} m = [1; 1; 2; 1; 2]
   @result{} n = [2; 5; 1; 4; 3]
   @result{} p(n) = [3, 2, 2, 1, 1]
@end group
@end example

@xseealso{residue, poly, roots, conv, deconv}
@end deftypefn
padecoef
@c padecoef scripts/polynomial/padecoef.m
@deftypefn  {} {[@var{num}, @var{den}] =} padecoef (@var{T})
@deftypefnx {} {[@var{num}, @var{den}] =} padecoef (@var{T}, @var{N})
Compute the @var{N}th-order Pad@'e approximant of the continuous-time
delay @var{T} in transfer function form.

@tex
The Pad\'e approximant of $e^{-sT}$ is defined by the following equation
$$ e^{-sT} \approx {P_n(s) \over Q_n(s)} $$
where both $P_n(s)$ and $Q_n(s)$ are $N^{th}$-order rational functions
defined by the following expressions
$$ P_n(s)=\sum_{k=0}^N {(2N - k)!N!\over (2N)!k!(N - k)!}(-sT)^k $$
$$ Q_n(s) = P_n(-s) $$
@end tex
@ifnottex
The Pad@'e approximant of @nospell{@code{exp (-sT)}} is defined by the
following equation

@example
@group
             Pn(s)
exp (-sT) ~ -------
             Qn(s)
@end group
@end example

Where both @nospell{Pn(s) and Qn(s)} are @var{N}th-order rational functions
defined by the following expressions

@example
@group
         N    (2N - k)!N!        k
Pn(s) = SUM --------------- (-sT)
        k=0 (2N)!k!(N - k)!

Qn(s) = Pn(-s)
@end group
@end example

@end ifnottex

The inputs @var{T} and @var{N} must be non-negative numeric scalars.  If
@var{N} is unspecified it defaults to 1.

The output row vectors @var{num} and @var{den} contain the numerator and
denominator coefficients in descending powers of s.  Both are
@var{N}th-order polynomials.

For example:

@smallexample
@group
t = 0.1;
n = 4;
[num, den] = padecoef (t, n)
@result{} num =

      1.0000e-04  -2.0000e-02   1.8000e+00  -8.4000e+01   1.6800e+03

@result{} den =

      1.0000e-04   2.0000e-02   1.8000e+00   8.4000e+01   1.6800e+03
@end group
@end smallexample
@end deftypefn
pchip
@c pchip scripts/polynomial/pchip.m
@deftypefn  {} {@var{pp} =} pchip (@var{x}, @var{y})
@deftypefnx {} {@var{yi} =} pchip (@var{x}, @var{y}, @var{xi})
Return the Piecewise Cubic Hermite Interpolating Polynomial (pchip) of
points @var{x} and @var{y}.

If called with two arguments, return the piecewise polynomial @var{pp}
that may be used with @code{ppval} to evaluate the polynomial at specific
points.

When called with a third input argument, @code{pchip} evaluates the pchip
polynomial at the points @var{xi}.  The third calling form is equivalent to
@code{ppval (pchip (@var{x}, @var{y}), @var{xi})}.

The variable @var{x} must be a strictly monotonic vector (either increasing
or decreasing) of length @var{n}.

@var{y} can be either a vector or array.  If @var{y} is a vector then it
must be the same length @var{n} as @var{x}.  If @var{y} is an array then
the size of @var{y} must have the form
@tex
$$[s_1, s_2, \cdots, s_k, n]$$
@end tex
@ifnottex
@code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n}]}
@end ifnottex
The array is reshaped internally to a matrix where the leading dimension is
given by
@tex
$$s_1 s_2 \cdots s_k$$
@end tex
@ifnottex
@code{@var{s1} * @var{s2} * @dots{} * @var{sk}}
@end ifnottex
and each row of this matrix is then treated separately.  Note that this is
exactly opposite to @code{interp1} but is done for @sc{matlab}
compatibility.

@xseealso{spline, ppval, mkpp, unmkpp}
@end deftypefn
poly
@c poly scripts/polynomial/poly.m
@deftypefn  {} {} poly (@var{A})
@deftypefnx {} {} poly (@var{x})
If @var{A} is a square @math{N}-by-@math{N} matrix, @code{poly (@var{A})}
is the row vector of the coefficients of @code{det (z * eye (N) - A)},
the characteristic polynomial of @var{A}.

For example, the following code finds the eigenvalues of @var{A} which are
the roots of @code{poly (@var{A})}.

@example
@group
roots (poly (eye (3)))
    @result{} 1.00001 + 0.00001i
       1.00001 - 0.00001i
       0.99999 + 0.00000i
@end group
@end example

In fact, all three eigenvalues are exactly 1 which emphasizes that for
numerical performance the @code{eig} function should be used to compute
eigenvalues.

If @var{x} is a vector, @code{poly (@var{x})} is a vector of the
coefficients of the polynomial whose roots are the elements of @var{x}.
That is, if @var{c} is a polynomial, then the elements of
@code{@var{d} = roots (poly (@var{c}))} are contained in @var{c}.  The
vectors @var{c} and @var{d} are not identical, however, due to sorting and
numerical errors.
@xseealso{roots, eig}
@end deftypefn
polyaffine
@c polyaffine scripts/polynomial/polyaffine.m
@deftypefn {} {} polyaffine (@var{f}, @var{mu})
Return the coefficients of the polynomial vector @var{f} after an affine
transformation.

If @var{f} is the vector representing the polynomial f(x), then
@code{@var{g} = polyaffine (@var{f}, @var{mu})} is the vector representing:

@example
g(x) = f( (x - @var{mu}(1)) / @var{mu}(2) )
@end example

@xseealso{polyval, polyfit}
@end deftypefn
polyder
@c polyder scripts/polynomial/polyder.m
@deftypefn  {} {} polyder (@var{p})
@deftypefnx {} {[@var{k}] =} polyder (@var{a}, @var{b})
@deftypefnx {} {[@var{q}, @var{d}] =} polyder (@var{b}, @var{a})
Return the coefficients of the derivative of the polynomial whose
coefficients are given by the vector @var{p}.

If a pair of polynomials is given, return the derivative of the product
@math{@var{a}*@var{b}}.

If two inputs and two outputs are given, return the derivative of the
polynomial quotient @math{@var{b}/@var{a}}.  The quotient numerator is
in @var{q} and the denominator in @var{d}.
@xseealso{polyint, polyval, polyreduce}
@end deftypefn
polyeig
@c polyeig scripts/polynomial/polyeig.m
@deftypefn  {} {@var{z} =} polyeig (@var{C0}, @var{C1}, @dots{}, @var{Cl})
@deftypefnx {} {[@var{v}, @var{z}] =} polyeig (@var{C0}, @var{C1}, @dots{}, @var{Cl})

Solve the polynomial eigenvalue problem of degree @var{l}.

Given an @var{n}x@var{n} matrix polynomial

@code{@var{C}(@var{s}) = @var{C0} + @var{C1} @var{s} + @dots{} + @var{Cl}
@var{s}^@var{l}}

@code{polyeig} solves the eigenvalue problem

@code{(@var{C0} + @var{C1} @var{z} + @dots{} + @var{Cl} @var{z}^@var{l})
@var{v} = 0}.

Note that the eigenvalues @var{z} are the zeros of the matrix polynomial.
@var{z} is a row vector with @code{@var{n}*@var{l}} elements.  @var{v} is a
matrix (@var{n} x @var{n}*@var{l}) with columns that correspond to the
eigenvectors.

@xseealso{eig, eigs, compan}
@end deftypefn
polyfit
@c polyfit scripts/polynomial/polyfit.m
@deftypefn  {} {@var{p} =} polyfit (@var{x}, @var{y}, @var{n})
@deftypefnx {} {[@var{p}, @var{s}] =} polyfit (@var{x}, @var{y}, @var{n})
@deftypefnx {} {[@var{p}, @var{s}, @var{mu}] =} polyfit (@var{x}, @var{y}, @var{n})
Return the coefficients of a polynomial @var{p}(@var{x}) of degree
@var{n} that minimizes the least-squares-error of the fit to the points
@code{[@var{x}, @var{y}]}.

If @var{n} is a logical vector, it is used as a mask to selectively force
the corresponding polynomial coefficients to be used or ignored.

The polynomial coefficients are returned in a row vector.

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

@table @samp
@item R
Triangular factor R from the QR@tie{}decomposition.

@item X
The @nospell{Vandermonde} matrix used to compute the polynomial
coefficients.

@item C
The unscaled covariance matrix, formally equal to the inverse of
@var{x'}*@var{x}, but computed in a way minimizing roundoff error
propagation.

@item df
The degrees of freedom.

@item normr
The norm of the residuals.

@item yf
The values of the polynomial for each value of @var{x}.
@end table

The second output may be used by @code{polyval} to calculate the
statistical error limits of the predicted values.  In particular, the
standard deviation of @var{p} coefficients is given by

@code{sqrt (diag (s.C)/s.df)*s.normr}.

When the third output, @var{mu}, is present the coefficients, @var{p}, are
associated with a polynomial in

@code{@var{xhat} = (@var{x} - @var{mu}(1)) / @var{mu}(2)} @*
where @var{mu}(1) = mean (@var{x}), and @var{mu}(2) = std (@var{x}).

This linear transformation of @var{x} improves the numerical stability of
the fit.
@xseealso{polyval, polyaffine, roots, vander, zscore}
@end deftypefn
polygcd
@c polygcd scripts/polynomial/polygcd.m
@deftypefn  {} {@var{q} =} polygcd (@var{b}, @var{a})
@deftypefnx {} {@var{q} =} polygcd (@var{b}, @var{a}, @var{tol})

Find the greatest common divisor of two polynomials.

This is equivalent to the polynomial found by multiplying together all the
common roots.  Together with deconv, you can reduce a ratio of two
polynomials.

The tolerance @var{tol} defaults to @code{sqrt (eps)}.

@strong{Caution:} This is a numerically unstable algorithm and should not
be used on large polynomials.

Example code:

@example
@group
polygcd (poly (1:8), poly (3:12)) - poly (3:8)
@result{} [ 0, 0, 0, 0, 0, 0, 0 ]
deconv (poly (1:8), polygcd (poly (1:8), poly (3:12))) - poly (1:2)
@result{} [ 0, 0, 0 ]
@end group
@end example
@xseealso{poly, roots, conv, deconv, residue}
@end deftypefn
polyint
@c polyint scripts/polynomial/polyint.m
@deftypefn  {} {} polyint (@var{p})
@deftypefnx {} {} polyint (@var{p}, @var{k})
Return the coefficients of the integral of the polynomial whose
coefficients are represented by the vector @var{p}.

The variable @var{k} is the constant of integration, which by default is
set to zero.
@xseealso{polyder, polyval}
@end deftypefn
polyout
@c polyout scripts/polynomial/polyout.m
@deftypefn  {} {} polyout (@var{c})
@deftypefnx {} {} polyout (@var{c}, @var{x})
@deftypefnx {} {@var{str} =} polyout (@dots{})
Display a formatted version of the polynomial @var{c}.

The formatted polynomial
@tex
$$ c(x) = c_1 x^n + \ldots + c_n x + c_{n+1} $$
@end tex
@ifnottex

@example
c(x) = c(1) * x^n + @dots{} + c(n) x + c(n+1)
@end example

@end ifnottex
is returned as a string or written to the screen if @code{nargout} is zero.

The second argument @var{x} specifies the variable name to use for each term
and defaults to the string @qcode{"s"}.
@xseealso{polyreduce}
@end deftypefn
polyreduce
@c polyreduce scripts/polynomial/polyreduce.m
@deftypefn {} {} polyreduce (@var{c})
Reduce a polynomial coefficient vector to a minimum number of terms by
stripping off any leading zeros.
@xseealso{polyout}
@end deftypefn
polyval
@c polyval scripts/polynomial/polyval.m
@deftypefn  {} {@var{y} =} polyval (@var{p}, @var{x})
@deftypefnx {} {@var{y} =} polyval (@var{p}, @var{x}, [], @var{mu})
@deftypefnx {} {[@var{y}, @var{dy}] =} polyval (@var{p}, @var{x}, @var{s})
@deftypefnx {} {[@var{y}, @var{dy}] =} polyval (@var{p}, @var{x}, @var{s}, @var{mu})

Evaluate the polynomial @var{p} at the specified values of @var{x}.

If @var{x} is a vector or matrix, the polynomial is evaluated for each of
the elements of @var{x}.

When @var{mu} is present, evaluate the polynomial for
(@var{x}-@var{mu}(1))/@var{mu}(2).

In addition to evaluating the polynomial, the second output represents the
prediction interval, @var{y} +/- @var{dy}, which contains at least 50% of
the future predictions.  To calculate the prediction interval, the
structured variable @var{s}, originating from @code{polyfit}, must be
supplied.

@xseealso{polyvalm, polyaffine, polyfit, roots, poly}
@end deftypefn
polyvalm
@c polyvalm scripts/polynomial/polyvalm.m
@deftypefn {} {} polyvalm (@var{c}, @var{x})
Evaluate a polynomial in the matrix sense.

@code{polyvalm (@var{c}, @var{x})} will evaluate the polynomial in the
matrix sense, i.e., matrix multiplication is used instead of element by
element multiplication as used in @code{polyval}.

The argument @var{x} must be a square matrix.
@xseealso{polyval, roots, poly}
@end deftypefn
ppder
@c ppder scripts/polynomial/ppder.m
@deftypefn  {} {ppd =} ppder (pp)
@deftypefnx {} {ppd =} ppder (pp, m)
Compute the piecewise @var{m}-th derivative of a piecewise polynomial
struct @var{pp}.

If @var{m} is omitted the first derivative is calculated.
@xseealso{mkpp, ppval, ppint}
@end deftypefn
ppint
@c ppint scripts/polynomial/ppint.m
@deftypefn  {} {@var{ppi} =} ppint (@var{pp})
@deftypefnx {} {@var{ppi} =} ppint (@var{pp}, @var{c})
Compute the integral of the piecewise polynomial struct @var{pp}.

@var{c}, if given, is the constant of integration.
@xseealso{mkpp, ppval, ppder}
@end deftypefn
ppjumps
@c ppjumps scripts/polynomial/ppjumps.m
@deftypefn {} {@var{jumps} =} ppjumps (@var{pp})
Evaluate the boundary jumps of a piecewise polynomial.

If there are @math{n} intervals, and the dimensionality of @var{pp} is
@math{d}, the resulting array has dimensions @code{[d, n-1]}.
@xseealso{mkpp}
@end deftypefn
ppval
@c ppval scripts/polynomial/ppval.m
@deftypefn {} {@var{yi} =} ppval (@var{pp}, @var{xi})
Evaluate the piecewise polynomial structure @var{pp} at the points @var{xi}.

If @var{pp} describes a scalar polynomial function, the result is an array
of the same shape as @var{xi}.  Otherwise, the size of the result is
@code{[pp.dim, length(@var{xi})]} if @var{xi} is a vector, or
@code{[pp.dim, size(@var{xi})]} if it is a multi-dimensional array.
@xseealso{mkpp, unmkpp, spline, pchip}
@end deftypefn
residue
@c residue scripts/polynomial/residue.m
@deftypefn  {} {[@var{r}, @var{p}, @var{k}, @var{e}] =} residue (@var{b}, @var{a})
@deftypefnx {} {[@var{b}, @var{a}] =} residue (@var{r}, @var{p}, @var{k})
@deftypefnx {} {[@var{b}, @var{a}] =} residue (@var{r}, @var{p}, @var{k}, @var{e})
The first calling form computes the partial fraction expansion for the
quotient of the polynomials, @var{b} and @var{a}.

The quotient is defined as
@tex
$$
{B(s)\over A(s)} = \sum_{m=1}^M {r_m\over (s-p_m)^e_m}
  + \sum_{i=1}^N k_i s^{N-i}.
$$
@end tex
@ifnottex

@example
@group
B(s)    M       r(m)        N
---- = SUM ------------- + SUM k(i)*s^(N-i)
A(s)   m=1 (s-p(m))^e(m)   i=1
@end group
@end example

@end ifnottex
@noindent
where @math{M} is the number of poles (the length of the @var{r}, @var{p},
and @var{e}), the @var{k} vector is a polynomial of order @math{N-1}
representing the direct contribution, and the @var{e} vector specifies the
multiplicity of the m-th residue's pole.

For example,

@example
@group
b = [1, 1, 1];
a = [1, -5, 8, -4];
[r, p, k, e] = residue (b, a)
   @result{} r = [-2; 7; 3]
   @result{} p = [2; 2; 1]
   @result{} k = [](0x0)
   @result{} e = [1; 2; 1]
@end group
@end example

@noindent
which represents the following partial fraction expansion
@tex
$$
{s^2+s+1\over s^3-5s^2+8s-4} = {-2\over s-2} + {7\over (s-2)^2} + {3\over s-1}
$$
@end tex
@ifnottex

@example
@group
        s^2 + s + 1       -2        7        3
   ------------------- = ----- + ------- + -----
   s^3 - 5s^2 + 8s - 4   (s-2)   (s-2)^2   (s-1)
@end group
@end example

@end ifnottex

The second calling form performs the inverse operation and computes the
reconstituted quotient of polynomials, @var{b}(s)/@var{a}(s), from the
partial fraction expansion; represented by the residues, poles, and a direct
polynomial specified by @var{r}, @var{p} and @var{k}, and the pole
multiplicity @var{e}.

If the multiplicity, @var{e}, is not explicitly specified the multiplicity
is determined by the function @code{mpoles}.

For example:

@example
@group
r = [-2; 7; 3];
p = [2; 2; 1];
k = [1, 0];
[b, a] = residue (r, p, k)
   @result{} b = [1, -5, 9, -3, 1]
   @result{} a = [1, -5, 8, -4]

where mpoles is used to determine e = [1; 2; 1]
@end group
@end example

Alternatively the multiplicity may be defined explicitly, for example,

@example
@group
r = [7; 3; -2];
p = [2; 1; 2];
k = [1, 0];
e = [2; 1; 1];
[b, a] = residue (r, p, k, e)
   @result{} b = [1, -5, 9, -3, 1]
   @result{} a = [1, -5, 8, -4]
@end group
@end example

@noindent
which represents the following partial fraction expansion
@tex
$$
{-2\over s-2} + {7\over (s-2)^2} + {3\over s-1} + s = {s^4-5s^3+9s^2-3s+1\over s^3-5s^2+8s-4}
$$
@end tex
@ifnottex

@example
@group
 -2        7        3         s^4 - 5s^3 + 9s^2 - 3s + 1
----- + ------- + ----- + s = --------------------------
(s-2)   (s-2)^2   (s-1)          s^3 - 5s^2 + 8s - 4
@end group
@end example

@end ifnottex
@xseealso{mpoles, poly, roots, conv, deconv}
@end deftypefn
roots
@c roots scripts/polynomial/roots.m
@deftypefn {} {} roots (@var{c})

Compute the roots of the polynomial @var{c}.

For a vector @var{c} with @math{N} components, return the roots of the
polynomial
@tex
$$
c_1 x^{N-1} + \cdots + c_{N-1} x + c_N.
$$
@end tex
@ifnottex

@example
c(1) * x^(N-1) + @dots{} + c(N-1) * x + c(N)
@end example

@end ifnottex

As an example, the following code finds the roots of the quadratic
polynomial
@tex
$$ p(x) = x^2 - 5. $$
@end tex
@ifnottex

@example
p(x) = x^2 - 5.
@end example

@end ifnottex

@example
@group
c = [1, 0, -5];
roots (c)
@result{}  2.2361
@result{} -2.2361
@end group
@end example

Note that the true result is
@tex
$\pm \sqrt{5}$
@end tex
@ifnottex
@math{+/- sqrt(5)}
@end ifnottex
which is roughly
@tex
$\pm 2.2361$.
@end tex
@ifnottex
@math{+/- 2.2361}.
@end ifnottex
@xseealso{poly, compan, fzero}
@end deftypefn
spline
@c spline scripts/polynomial/spline.m
@deftypefn  {} {@var{pp} =} spline (@var{x}, @var{y})
@deftypefnx {} {@var{yi} =} spline (@var{x}, @var{y}, @var{xi})
Return the cubic spline interpolant of points @var{x} and @var{y}.

When called with two arguments, return the piecewise polynomial @var{pp}
that may be used with @code{ppval} to evaluate the polynomial at specific
points.

When called with a third input argument, @code{spline} evaluates the spline
at the points @var{xi}.  The third calling form
@code{spline (@var{x}, @var{y}, @var{xi})} is equivalent to
@code{ppval (spline (@var{x}, @var{y}), @var{xi})}.

The variable @var{x} must be a vector of length @var{n}.

@var{y} can be either a vector or array.  If @var{y} is a vector it must
have a length of either @var{n} or @code{@var{n} + 2}.  If the length of
@var{y} is @var{n}, then the @qcode{"not-a-knot"} end condition is used.
If the length of @var{y} is @code{@var{n} + 2}, then the first and last
values of the vector @var{y} are the values of the first derivative of the
cubic spline at the endpoints.

If @var{y} is an array, then the size of @var{y} must have the form
@tex
$$[s_1, s_2, \cdots, s_k, n]$$
@end tex
@ifnottex
@code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n}]}
@end ifnottex
or
@tex
$$[s_1, s_2, \cdots, s_k, n + 2].$$
@end tex
@ifnottex
@code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n} + 2]}.
@end ifnottex
The array is reshaped internally to a matrix where the leading
dimension is given by
@tex
$$s_1 s_2 \cdots s_k$$
@end tex
@ifnottex
@code{@var{s1} * @var{s2} * @dots{} * @var{sk}}
@end ifnottex
and each row of this matrix is then treated separately.  Note that this is
exactly the opposite of @code{interp1} but is done for @sc{matlab}
compatibility.

@xseealso{pchip, ppval, mkpp, unmkpp}
@end deftypefn
splinefit
@c splinefit scripts/polynomial/splinefit.m
@deftypefn  {} {@var{pp} =} splinefit (@var{x}, @var{y}, @var{breaks})
@deftypefnx {} {@var{pp} =} splinefit (@var{x}, @var{y}, @var{p})
@deftypefnx {} {@var{pp} =} splinefit (@dots{}, "periodic", @var{periodic})
@deftypefnx {} {@var{pp} =} splinefit (@dots{}, "robust", @var{robust})
@deftypefnx {} {@var{pp} =} splinefit (@dots{}, "beta", @var{beta})
@deftypefnx {} {@var{pp} =} splinefit (@dots{}, "order", @var{order})
@deftypefnx {} {@var{pp} =} splinefit (@dots{}, "constraints", @var{constraints})

Fit a piecewise cubic spline with breaks (knots) @var{breaks} to the
noisy data, @var{x} and @var{y}.

@var{x} is a vector, and @var{y} is a vector or N-D array.  If @var{y} is an
N-D array, then @var{x}(j) is matched to @var{y}(:,@dots{},:,j).

@var{p} is a positive integer defining the number of intervals along
@var{x}, and @var{p}+1 is the number of breaks.  The number of points in
each interval differ by no more than 1.

The optional property @var{periodic} is a logical value which specifies
whether a periodic boundary condition is applied to the spline.  The
length of the period is @code{max (@var{breaks}) - min (@var{breaks})}.
The default value is @code{false}.

The optional property @var{robust} is a logical value which specifies
if robust fitting is to be applied to reduce the influence of outlying
data points.  Three iterations of weighted least squares are performed.
Weights are computed from previous residuals.  The sensitivity of outlier
identification is controlled by the property @var{beta}.  The value of
@var{beta} is restricted to the range, 0 < @var{beta} < 1.  The default
value is @var{beta} = 1/2.  Values close to 0 give all data equal
weighting.  Increasing values of @var{beta} reduce the influence of
outlying data.  Values close to unity may cause instability or rank
deficiency.

The fitted spline is returned as a piecewise polynomial, @var{pp}, and
may be evaluated using @code{ppval}.

The splines are constructed of polynomials with degree @var{order}.
The default is a cubic, @var{order}=3.  A spline with P pieces has
P+@var{order} degrees of freedom.  With periodic boundary conditions
the degrees of freedom are reduced to P.

The optional property, @var{constraints}, is a structure specifying linear
constraints on the fit.  The structure has three fields, @qcode{"xc"},
@qcode{"yc"}, and @qcode{"cc"}.

@table @asis
@item @qcode{"xc"}
Vector of the x-locations of the constraints.

@item @qcode{"yc"}
Constraining values at the locations @var{xc}.
The default is an array of zeros.

@item @qcode{"cc"}
Coefficients (matrix).  The default is an array of ones.  The number of
rows is limited to the order of the piecewise polynomials, @var{order}.
@end table

Constraints are linear combinations of derivatives of order 0 to
@var{order}-1 according to

@example
@group
@tex
$cc(1,j) \cdot y(xc(j)) + cc(2,j) \cdot y\prime(xc(j)) + ... = yc(:,\dots,:,j)$.
@end tex
@ifnottex
cc(1,j) * y(xc(j)) + cc(2,j) * y'(xc(j)) + ... = yc(:,...,:,j).
@end ifnottex
@end group
@end example

@xseealso{interp1, unmkpp, ppval, spline, pchip, ppder, ppint, ppjumps}
@end deftypefn
unmkpp
@c unmkpp scripts/polynomial/unmkpp.m
@deftypefn {} {[@var{x}, @var{p}, @var{n}, @var{k}, @var{d}] =} unmkpp (@var{pp})

Extract the components of a piecewise polynomial structure @var{pp}.

This function is the inverse of @code{mkpp}: it extracts the inputs to
@code{mkpp} needed to create the piecewise polynomial structure @var{PP}.
The code below makes this relation explicit:

@example
@group
[breaks, coefs, numinter, order, dim] = unmkpp (pp);
pp2  = mkpp (breaks, coefs, dim);
@end group
@end example

The piecewise polynomial structure @code{pp2} obtained in this way, is
identical to the original @code{pp}.  The same can be obtained by directly
accessing the fields of the structure @code{pp}.

The components are:

@table @asis
@item @var{x}
Sample points or breaks.

@item @var{p}
Polynomial coefficients for points in sample interval.
@code{@var{p}(@var{i}, :)} contains the coefficients for the polynomial
over interval @var{i} ordered from highest to lowest degree.
If @code{@var{d} > 1}, then @var{p} is a matrix of size
@code{[@var{n}*prod(@var{d}) @var{m}]}, where the
@code{@var{i} + (1:@var{d})} rows are the coefficients of all the @var{d}
polynomials in the interval @var{i}.

@item @var{n}
Number of polynomial pieces or intervals,
@code{@var{n} = length (@var{x}) - 1}.

@item @var{k}
Order of the polynomial plus 1.

@item @var{d}
Number of polynomials defined for each interval.
@end table

@xseealso{mkpp, ppval, spline, pchip}
@end deftypefn
addpref
@c addpref scripts/prefs/addpref.m
@deftypefn  {} {} addpref ("@var{group}", "@var{pref}", @var{val})
@deftypefnx {} {} addpref ("@var{group}", @{"@var{pref1}", "@var{pref2}", @dots{}@}, @{@var{val1}, @var{val2}, @dots{}@})
Add the preference @var{pref} and associated value @var{val} to the named
preference group @var{group}.

The named preference group must be a string.

The preference @var{pref} may be a string or a cell array of strings.  An
error will be issued if the preference already exists.

The corresponding value @var{val} may be any Octave value, .e.g., double,
struct, cell array, object, etc.  Or, if @var{pref} is a cell array of
strings then @var{val} must be a cell array of values with the same size as
@var{pref}.
@xseealso{setpref, getpref, ispref, rmpref}
@end deftypefn
getpref
@c getpref scripts/prefs/getpref.m
@deftypefn  {} {@var{val} =} getpref ("@var{group}", "@var{pref}")
@deftypefnx {} {@var{val} =} getpref ("@var{group}", "@var{pref}", @var{default})
@deftypefnx {} {@{@var{val1}, @var{val2}, @dots{}@} =} getpref ("@var{group}", @{"@var{pref1}", "@var{pref2"}, @dots{}@})
@deftypefnx {} {@var{prefstruct} =} getpref ("@var{group}")
@deftypefnx {} {@var{prefstruct} =} getpref ()
Return the preference value corresponding to the named preference @var{pref}
in the preference group @var{group}.

The named preference group must be a string.

If @var{pref} does not exist in @var{group} and @var{default} is specified,
create the preference with value @var{default} and return @var{default}.

The preference @var{pref} may be a string or cell array of strings.  If it
is a cell array of strings then a cell array of preferences is returned.

The corresponding default value @var{default} may be any Octave value,
.e.g., double, struct, cell array, object, etc.  Or, if @var{pref} is a cell
array of strings then @var{default} must be a cell array of values with the
same size as @var{pref}.

If neither @var{pref} nor @var{default} are specified, return a structure
of preferences for the preference group @var{group}.

If no arguments are specified, return a structure containing all groups of
preferences and their values.
@xseealso{addpref, setpref, ispref, rmpref}
@end deftypefn
ispref
@c ispref scripts/prefs/ispref.m
@deftypefn  {} {} ispref ("@var{group}", "@var{pref}")
@deftypefnx {} {} ispref ("@var{group}", @{"@var{pref1}", "@var{pref2"}, @dots{}@})
@deftypefnx {} {} ispref ("@var{group}")
Return true if the named preference @var{pref} exists in the preference
group @var{group}.

The named preference group must be a string.

The preference @var{pref} may be a string or a cell array of strings.

If @var{pref} is not specified, return true if the preference group
@var{group} exists.
@xseealso{getpref, addpref, setpref, rmpref}
@end deftypefn
prefdir
@c prefdir scripts/prefs/prefdir.m
@deftypefn  {} {} prefdir
@deftypefnx {} {} prefdir (1)
@deftypefnx {} {@var{dir} =} prefdir
Return the directory that holds the preferences for Octave.

Examples:

Display the preferences directory

@example
prefdir
@end example

Change to the preferences folder

@example
cd (prefdir)
@end example

If called with an argument, the preferences directory is created if it
doesn't already exist.
@xseealso{getpref, setpref, addpref, rmpref, ispref}
@end deftypefn
preferences
@c preferences scripts/prefs/preferences.m
@deftypefn {} {} preferences
Display the GUI preferences dialog window for Octave.
@end deftypefn
rmpref
@c rmpref scripts/prefs/rmpref.m
@deftypefn  {} {} rmpref ("@var{group}", "@var{pref}")
@deftypefnx {} {} rmpref ("@var{group}", @{"@var{pref1}", "@var{pref2}", @dots{}@})
@deftypefnx {} {} rmpref ("@var{group}")
Remove the named preference @var{pref} from the preference group
@var{group}.

The named preference group must be a string.

The preference @var{pref} may be a string or cell array of strings.

If @var{pref} is not specified, remove the preference group @var{group}.

It is an error to remove a nonexistent preference or group.
@xseealso{addpref, ispref, setpref, getpref}
@end deftypefn
setpref
@c setpref scripts/prefs/setpref.m
@deftypefn  {} {} setpref ("@var{group}", "@var{pref}", @var{val})
@deftypefnx {} {} setpref ("@var{group}", @{"@var{pref1}", "@var{pref2}", @dots{}@}, @{@var{val1}, @var{val2}, @dots{}@})
Set the preference @var{pref} to the given @var{val} in the named preference
group @var{group}.

The named preference group must be a string.

The preference @var{pref} may be a string or a cell array of strings.

The corresponding value @var{val} may be any Octave value, .e.g., double,
struct, cell array, object, etc.  Or, if @var{pref} is a cell array of
strings then @var{val} must be a cell array of values with the same size as
@var{pref}.

If the named preference or group does not exist, it is added.
@xseealso{addpref, getpref, ispref, rmpref}
@end deftypefn
profexplore
@c profexplore scripts/profiler/profexplore.m
@deftypefn  {} {} profexplore ()
@deftypefnx {} {} profexplore (@var{data})
Interactively explore hierarchical profiler output.

Assuming @var{data} is the structure with profile data returned by
@code{profile (@qcode{"info"})}, this command opens an interactive prompt
that can be used to explore the call-tree.  Type @kbd{help} to get a list
of possible commands.  If @var{data} is omitted, @code{profile ("info")}
is called and used in its place.
@xseealso{profile, profshow}
@end deftypefn
profexport
@c profexport scripts/profiler/profexport.m
@deftypefn  {} {} profexport (@var{dir})
@deftypefnx {} {} profexport (@var{dir}, @var{data})
@deftypefnx {} {} profexport (@var{dir}, @var{name})
@deftypefnx {} {} profexport (@var{dir}, @var{name}, @var{data})

Export profiler data as HTML.

Export the profiling data in @var{data} into a series of HTML files in
the folder @var{dir}.  The initial file will be
@file{@var{data}/index.html}.

If @var{name} is specified, it must be a string that contains a ``name''
for the profile being exported.  This name is included in the HTML.

The input @var{data} is the structure returned by @code{profile ("info")}.
If unspecified, @code{profexport} will use the current profile dataset.

@xseealso{profshow, profexplore, profile}
@end deftypefn
profile
@c profile scripts/profiler/profile.m
@deftypefn  {} {} profile on
@deftypefnx {} {} profile off
@deftypefnx {} {} profile resume
@deftypefnx {} {} profile clear
@deftypefnx {} {@var{S} =} profile ("status")
@deftypefnx {} {@var{T} =} profile ("info")
Control the built-in profiler.

@table @code
@item profile on
Start the profiler, clearing all previously collected data if there is any.

@item profile off
Stop profiling.  The collected data can later be retrieved and examined
with @code{T = profile ("info")}.

@item profile clear
Clear all collected profiler data.

@item profile resume
Restart profiling without clearing the old data.  All newly collected
statistics are added to the existing ones.

@item @var{S} = profile ("status")
Return a structure with information about the current status of the
profiler.  At the moment, the only field is @code{ProfilerStatus} which is
either @qcode{"on"} or @qcode{"off"}.

@item @var{T} = profile ("info")
Return the collected profiling statistics in the structure @var{T}.  The
flat profile is returned in the field @code{FunctionTable} which is an
array of structures, each entry corresponding to a function which was called
and for which profiling statistics are present.  In addition, the field
@code{Hierarchical} contains the hierarchical call tree.  Each node has an
index into the @code{FunctionTable} identifying the function it corresponds
to as well as data fields for number of calls and time spent at this level
in the call tree.
@xseealso{profshow, profexplore}
@end table
@end deftypefn
profshow
@c profshow scripts/profiler/profshow.m
@deftypefn  {} {} profshow (@var{data})
@deftypefnx {} {} profshow (@var{data}, @var{n})
@deftypefnx {} {} profshow ()
@deftypefnx {} {} profshow (@var{n})
Display flat per-function profiler results.

Print out profiler data (execution time, number of calls) for the most
critical @var{n} functions.  The results are sorted in descending order by
the total time spent in each function.  If @var{n} is unspecified it
defaults to 20.

The input @var{data} is the structure returned by @code{profile ("info")}.
If unspecified, @code{profshow} will use the current profile dataset.

The attribute column displays @samp{R} for recursive functions, and is blank
for all other function types.
@xseealso{profexplore, profile}
@end deftypefn
intersect
@c intersect scripts/set/intersect.m
@deftypefn  {} {@var{c} =} intersect (@var{a}, @var{b})
@deftypefnx {} {@var{c} =} intersect (@var{a}, @var{b}, "rows")
@deftypefnx {} {[@var{c}, @var{ia}, @var{ib}] =} intersect (@dots{})

Return the unique elements common to both @var{a} and @var{b} sorted in
ascending order.

If @var{a} and @var{b} are both row vectors then return a row vector;
Otherwise, return a column vector.  The inputs may also be cell arrays of
strings.

If the optional input @qcode{"rows"} is given then return the common rows of
@var{a} and @var{b}.  The inputs must be 2-D matrices to use this option.

If requested, return index vectors @var{ia} and @var{ib} such that
@code{@var{c} = @var{a}(@var{ia})} and @code{@var{c} = @var{b}(@var{ib})}.

@xseealso{unique, union, setdiff, setxor, ismember}
@end deftypefn
ismember
@c ismember scripts/set/ismember.m
@deftypefn  {} {@var{tf} =} ismember (@var{a}, @var{s})
@deftypefnx {} {@var{tf} =} ismember (@var{a}, @var{s}, "rows")
@deftypefnx {} {[@var{tf}, @var{s_idx}] =} ismember (@dots{})

Return a logical matrix @var{tf} with the same shape as @var{a} which is
true (1) if the element in @var{a} is found in @var{s} and false (0) if it
is not.

If a second output argument is requested then the index into @var{s} of each
matching element is also returned.

@example
@group
a = [3, 10, 1];
s = [0:9];
[tf, s_idx] = ismember (a, s)
     @result{} tf = [1, 0, 1]
     @result{} s_idx = [4, 0, 2]
@end group
@end example

The inputs @var{a} and @var{s} may also be cell arrays.

@example
@group
a = @{"abc"@};
s = @{"abc", "def"@};
[tf, s_idx] = ismember (a, s)
     @result{} tf = 1
     @result{} s_idx = 1
@end group
@end example

If the optional third argument @qcode{"rows"} is given then compare rows
in @var{a} with rows in @var{s}.  The inputs must be 2-D matrices with the
same number of columns to use this option.

@example
@group
a = [1:3; 5:7; 4:6];
s = [0:2; 1:3; 2:4; 3:5; 4:6];
[tf, s_idx] = ismember (a, s, "rows")
     @result{} tf = logical ([1; 0; 1])
     @result{} s_idx = [2; 0; 5];
@end group
@end example

@xseealso{lookup, unique, union, intersect, setdiff, setxor}
@end deftypefn
powerset
@c powerset scripts/set/powerset.m
@deftypefn  {} {} powerset (@var{a})
@deftypefnx {} {} powerset (@var{a}, "rows")
Compute the powerset (all subsets) of the set @var{a}.

The set @var{a} must be a numerical matrix or a cell array of strings.  The
output will always be a cell array of either vectors or strings.

With the optional argument @qcode{"rows"}, each row of the set @var{a} is
considered one element of the set.  The input must be a 2-D numeric matrix
to use this argument.

@xseealso{unique, union, intersect, setdiff, setxor, ismember}
@end deftypefn
setdiff
@c setdiff scripts/set/setdiff.m
@deftypefn  {} {@var{c} =} setdiff (@var{a}, @var{b})
@deftypefnx {} {@var{c} =} setdiff (@var{a}, @var{b}, "rows")
@deftypefnx {} {[@var{c}, @var{ia}] =} setdiff (@dots{})
Return the unique elements in @var{a} that are not in @var{b} sorted in
ascending order.

If @var{a} is a row vector return a row vector; Otherwise, return a
column vector.  The inputs may also be cell arrays of strings.

If the optional input @qcode{"rows"} is given then return the rows in
@var{a} that are not in @var{b}.  The inputs must be 2-D matrices to use
this option.

If requested, return the index vector @var{ia} such that
@code{@var{c} = @var{a}(@var{ia})}.
@xseealso{unique, union, intersect, setxor, ismember}
@end deftypefn
setxor
@c setxor scripts/set/setxor.m
@deftypefn  {} {@var{c} =} setxor (@var{a}, @var{b})
@deftypefnx {} {@var{c} =} setxor (@var{a}, @var{b}, "rows")
@deftypefnx {} {[@var{c}, @var{ia}, @var{ib}] =} setxor (@dots{})

Return the unique elements exclusive to sets @var{a} or @var{b} sorted in
ascending order.

If @var{a} and @var{b} are both row vectors then return a row vector;
Otherwise, return a column vector.  The inputs may also be cell arrays of
strings.

If the optional input @qcode{"rows"} is given then return the rows exclusive
to sets @var{a} and @var{b}.  The inputs must be 2-D matrices to use this
option.

If requested, return index vectors @var{ia} and @var{ib} such that
@code{@var{a}(@var{ia})} and @code{@var{b}(@var{ib})} are disjoint sets
whose union is @var{c}.

@xseealso{unique, union, intersect, setdiff, ismember}
@end deftypefn
union
@c union scripts/set/union.m
@deftypefn  {} {@var{c} =} union (@var{a}, @var{b})
@deftypefnx {} {@var{c} =} union (@var{a}, @var{b}, "rows")
@deftypefnx {} {[@var{c}, @var{ia}, @var{ib}] =} union (@dots{})

Return the unique elements that are in either @var{a} or @var{b} sorted in
ascending order.

If @var{a} and @var{b} are both row vectors then return a row vector;
Otherwise, return a column vector.  The inputs may also be cell arrays of
strings.

If the optional input @qcode{"rows"} is given then return rows that are in
either @var{a} or @var{b}.  The inputs must be 2-D matrices to use this
option.

The optional outputs @var{ia} and @var{ib} are index vectors such that
@code{@var{a}(@var{ia})} and @code{@var{b}(@var{ib})} are disjoint sets
whose union is @var{c}.

@xseealso{unique, intersect, setdiff, setxor, ismember}
@end deftypefn
unique
@c unique scripts/set/unique.m
@deftypefn  {} {} unique (@var{x})
@deftypefnx {} {} unique (@var{x}, "rows")
@deftypefnx {} {[@var{y}, @var{i}, @var{j}] =} unique (@dots{})
@deftypefnx {} {[@var{y}, @var{i}, @var{j}] =} unique (@dots{}, "first")
@deftypefnx {} {[@var{y}, @var{i}, @var{j}] =} unique (@dots{}, "last")
Return the unique elements of @var{x} sorted in ascending order.

If the input @var{x} is a column vector then return a column vector;
Otherwise, return a row vector.  @var{x} may also be a cell array of
strings.

If the optional argument @qcode{"rows"} is given then return the unique
rows of @var{x} sorted in ascending order.  The input must be a 2-D matrix
to use this option.

If requested, return index vectors @var{i} and @var{j} such that
@code{@var{y} = @var{x}(@var{i})} and @code{@var{x} = @var{y}(@var{j})}.

Additionally, if @var{i} is a requested output then one of
@qcode{"first"} or @qcode{"last"} may be given as an input.  If
@qcode{"last"} is specified, return the highest possible indices in
@var{i}, otherwise, if @qcode{"first"} is specified, return the lowest.
The default is @qcode{"last"}.
@xseealso{union, intersect, setdiff, setxor, ismember}
@end deftypefn
__parse_movargs__
@c __parse_movargs__ scripts/signal/__parse_movargs__.m
@deftypefn {} {@var{args} =} __parse_movargs__ (@var{varargin})

Parse arguments for movXXX functions before passing to @code{movfun}.

@xseealso{movfun}
@end deftypefn
arch_fit
@c arch_fit scripts/signal/arch_fit.m
@deftypefn {} {[@var{a}, @var{b}] =} arch_fit (@var{y}, @var{x}, @var{p}, @var{iter}, @var{gamma}, @var{a0}, @var{b0})
Fit an ARCH regression model to the time series @var{y} using the scoring
algorithm in @nospell{Engle's} original ARCH paper.

The model is

@example
@group
y(t) = b(1) * x(t,1) + @dots{} + b(k) * x(t,k) + e(t),
h(t) = a(1) + a(2) * e(t-1)^2 + @dots{} + a(p+1) * e(t-p)^2
@end group
@end example

@noindent
in which @math{e(t)} is @math{N(0, h(t))}, given a time-series vector
@var{y} up to time @math{t-1} and a matrix of (ordinary) regressors @var{x}
up to @math{t}.  The order of the regression of the residual variance is
specified by @var{p}.

If invoked as @code{arch_fit (@var{y}, @var{k}, @var{p})} with a positive
integer @var{k}, fit an ARCH(@var{k}, @var{p}) process, i.e., do the above
with the @math{t}-th row of @var{x} given by

@example
[1, y(t-1), @dots{}, y(t-k)]
@end example

Optionally, one can specify the number of iterations @var{iter}, the
updating factor @var{gamma}, and initial values @math{a0} and @math{b0}
for the scoring algorithm.
@end deftypefn
arch_rnd
@c arch_rnd scripts/signal/arch_rnd.m
@deftypefn {} {} arch_rnd (@var{a}, @var{b}, @var{t})
Simulate an ARCH sequence of length @var{t} with AR coefficients @var{b} and
CH coefficients @var{a}.

The result @math{y(t)} follows the model
@c Set example in small font to prevent overfull line

@smallexample
y(t) = b(1) + b(2) * y(t-1) + @dots{} + b(lb) * y(t-lb+1) + e(t),
@end smallexample

@noindent
where @math{e(t)}, given @var{y} up to time @math{t-1}, is
@math{N(0, h(t))}, with
@c Set example in small font to prevent overfull line

@smallexample
h(t) = a(1) + a(2) * e(t-1)^2 + @dots{} + a(la) * e(t-la+1)^2
@end smallexample
@end deftypefn
arch_test
@c arch_test scripts/signal/arch_test.m
@deftypefn {} {[@var{pval}, @var{lm}] =} arch_test (@var{y}, @var{x}, @var{p})
For a linear regression model

@example
y = x * b + e
@end example

@noindent
perform a Lagrange Multiplier (LM) test of the null hypothesis of no
conditional heteroscedascity against the alternative of CH(@var{p}).

I.e., the model is

@example
y(t) = b(1) * x(t,1) + @dots{} + b(k) * x(t,k) + e(t),
@end example

@noindent
given @var{y} up to @math{t-1} and @var{x} up to @math{t},
@math{e}(t) is @math{N(0, h(t))} with

@example
h(t) = v + a(1) * e(t-1)^2 + @dots{} + a(p) * e(t-p)^2,
@end example

@noindent
and the null is @math{a(1)} == @dots{} == @math{a(p)} == 0.

If the second argument is a scalar integer, @math{k}, perform the same
test in a linear autoregression model of order @math{k}, i.e., with

@example
[1, y(t-1), @dots{}, y(t-@var{k})]
@end example

@noindent
as the @math{t}-th row of @var{x}.

Under the null, LM approximately has a chisquare distribution with
@var{p} degrees of freedom and @var{pval} is the @math{p}-value (1
minus the CDF of this distribution at LM) of the test.

If no output argument is given, the @math{p}-value is displayed.
@end deftypefn
arma_rnd
@c arma_rnd scripts/signal/arma_rnd.m
@deftypefn {} {} arma_rnd (@var{a}, @var{b}, @var{v}, @var{t}, @var{n})
Return a simulation of the ARMA model.

The ARMA model is defined by

@example
@group
x(n) = a(1) * x(n-1) + @dots{} + a(k) * x(n-k)
     + e(n) + b(1) * e(n-1) + @dots{} + b(l) * e(n-l)
@end group
@end example

@noindent
in which @var{k} is the length of vector @var{a}, @var{l} is the length of
vector @var{b} and @var{e} is Gaussian white noise with variance @var{v}.
The function returns a vector of length @var{t}.

The optional parameter @var{n} gives the number of dummy @var{x}(@var{i})
used for initialization, i.e., a sequence of length @var{t}+@var{n} is
generated and @var{x}(@var{n}+1:@var{t}+@var{n}) is returned.  If @var{n}
is omitted, @var{n} = 100 is used.
@end deftypefn
autoreg_matrix
@c autoreg_matrix scripts/signal/autoreg_matrix.m
@deftypefn {} {} autoreg_matrix (@var{y}, @var{k})
Given a time series (vector) @var{y}, return a matrix with ones in the first
column and the first @var{k} lagged values of @var{y} in the other columns.

In other words, for @var{t} > @var{k},
@code{[1, @var{y}(@var{t}-1), @dots{}, @var{y}(@var{t}-@var{k})]} is the
t-th row of the result.

The resulting matrix may be used as a regressor matrix in autoregressions.
@end deftypefn
bartlett
@c bartlett scripts/signal/bartlett.m
@deftypefn {} {} bartlett (@var{m})
Return the filter coefficients of a Bartlett (triangular) window of length
@var{m}.

For a definition of the Bartlett window see, e.g.,
@nospell{A.V. Oppenheim & R. W. Schafer},
@cite{Discrete-Time Signal Processing}.
@end deftypefn
blackman
@c blackman scripts/signal/blackman.m
@deftypefn  {} {} blackman (@var{m})
@deftypefnx {} {} blackman (@var{m}, "periodic")
@deftypefnx {} {} blackman (@var{m}, "symmetric")
Return the filter coefficients of a @nospell{Blackman} window of length
@var{m}.

If the optional argument @qcode{"periodic"} is given, the periodic form
of the window is returned.  This is equivalent to the window of length
@var{m}+1 with the last coefficient removed.  The optional argument
@qcode{"symmetric"} is equivalent to not specifying a second argument.

For a definition of the @nospell{Blackman} window, see, e.g.,
@nospell{A.V. Oppenheim & R. W. Schafer},
@cite{Discrete-Time Signal Processing}.
@end deftypefn
detrend
@c detrend scripts/signal/detrend.m
@deftypefn {} {} detrend (@var{x}, @var{p})
If @var{x} is a vector, @code{detrend (@var{x}, @var{p})} removes the
best fit of a polynomial of order @var{p} from the data @var{x}.

If @var{x} is a matrix, @code{detrend (@var{x}, @var{p})} does the same
for each column in @var{x}.

The second argument @var{p} is optional.  If it is not specified, a value of
1 is assumed.  This corresponds to removing a linear trend.

The order of the polynomial can also be given as a string, in which case
@var{p} must be either @qcode{"constant"} (corresponds to @code{@var{p}=0})
or @qcode{"linear"} (corresponds to @code{@var{p}=1}).
@xseealso{polyfit}
@end deftypefn
diffpara
@c diffpara scripts/signal/diffpara.m
@deftypefn {} {[@var{d}, @var{dd}] =} diffpara (@var{x}, @var{a}, @var{b})
Return the estimator @var{d} for the differencing parameter of an
integrated time series.

The frequencies from @math{[2*pi*a/t, 2*pi*b/T]} are used for the
estimation.  If @var{b} is omitted, the interval
@math{[2*pi/T, 2*pi*a/T]} is used.  If both @var{b} and @var{a} are omitted
then @math{a = 0.5 * sqrt (T)} and @math{b = 1.5 * sqrt (T)} is used, where
@math{T} is the sample size.  If @var{x} is a matrix, the differencing
parameter of each column is estimated.

The estimators for all frequencies in the intervals described above is
returned in @var{dd}.

The value of @var{d} is simply the mean of @var{dd}.

Reference: @nospell{P.J. Brockwell & R.A. Davis}. @cite{Time Series:
Theory and Methods}. @nospell{Springer} 1987.
@end deftypefn
durbinlevinson
@c durbinlevinson scripts/signal/durbinlevinson.m
@deftypefn {} {} durbinlevinson (@var{c}, @var{oldphi}, @var{oldv})
Perform one step of the @nospell{Durbin-Levinson} algorithm.

The vector @var{c} specifies the autocovariances
@code{[gamma_0, @dots{}, gamma_t]} from lag 0 to @var{t}, @var{oldphi}
specifies the coefficients based on @var{c}(@var{t}-1) and @var{oldv}
specifies the corresponding error.

If @var{oldphi} and @var{oldv} are omitted, all steps from 1 to @var{t} of
the algorithm are performed.
@end deftypefn
fftconv
@c fftconv scripts/signal/fftconv.m
@deftypefn  {} {} fftconv (@var{x}, @var{y})
@deftypefnx {} {} fftconv (@var{x}, @var{y}, @var{n})
Convolve two vectors using the FFT for computation.

@code{c = fftconv (@var{x}, @var{y})} returns a vector of length equal to
@code{length (@var{x}) + length (@var{y}) - 1}.  If @var{x} and @var{y}
are the coefficient vectors of two polynomials, the returned value is the
coefficient vector of the product polynomial.

The computation uses the FFT by calling the function @code{fftfilt}.  If
the optional argument @var{n} is specified, an N-point FFT is used.
@xseealso{deconv, conv, conv2}
@end deftypefn
fftfilt
@c fftfilt scripts/signal/fftfilt.m
@deftypefn  {} {} fftfilt (@var{b}, @var{x})
@deftypefnx {} {} fftfilt (@var{b}, @var{x}, @var{n})
Filter @var{x} with the FIR filter @var{b} using the FFT.

If @var{x} is a matrix, filter each column of the matrix.

Given the optional third argument, @var{n}, @code{fftfilt} uses the
overlap-add method to filter @var{x} with @var{b} using an N-point FFT@.
The FFT size must be an even power of 2 and must be greater than or equal to
the length of @var{b}.  If the specified @var{n} does not meet these
criteria, it is automatically adjusted to the nearest value that does.

@xseealso{filter, filter2}
@end deftypefn
fftshift
@c fftshift scripts/signal/fftshift.m
@deftypefn  {} {} fftshift (@var{x})
@deftypefnx {} {} fftshift (@var{x}, @var{dim})
Perform a shift of the vector @var{x}, for use with the @code{fft} and
@code{ifft} functions, in order to move the frequency 0 to the center of
the vector or matrix.

If @var{x} is a vector of @math{N} elements corresponding to @math{N} time
samples spaced by @nospell{@math{dt}}, then
@code{fftshift (fft (@var{x}))} corresponds to frequencies

@example
f = [ -(ceil((N-1)/2):-1:1), 0, (1:floor((N-1)/2)) ] * df
@end example

@noindent
where @nospell{@math{df = 1 / (N * dt)}}.

If @var{x} is a matrix, the same holds for rows and columns.  If @var{x}
is an array, then the same holds along each dimension.

The optional @var{dim} argument can be used to limit the dimension along
which the permutation occurs.
@xseealso{ifftshift}
@end deftypefn
filter2
@c filter2 scripts/signal/filter2.m
@deftypefn  {} {@var{y} =} filter2 (@var{b}, @var{x})
@deftypefnx {} {@var{y} =} filter2 (@var{b}, @var{x}, @var{shape})
Apply the 2-D FIR filter @var{b} to @var{x}.

If the argument @var{shape} is specified, return an array of the desired
shape.  Possible values are:

@table @asis
@item @qcode{"full"}
pad @var{x} with zeros on all sides before filtering.

@item @qcode{"same"}
unpadded @var{x} (default)

@item @qcode{"valid"}
trim @var{x} after filtering so edge effects are no included.
@end table

Note this is just a variation on convolution, with the parameters reversed
and @var{b} rotated 180 degrees.
@xseealso{conv2}
@end deftypefn
fractdiff
@c fractdiff scripts/signal/fractdiff.m
@deftypefn {} {} fractdiff (@var{x}, @var{d})
Compute the fractional differences @math{(1-L)^d x} where @math{L}
denotes the lag-operator and @math{d} is greater than -1.
@end deftypefn
freqz
@c freqz scripts/signal/freqz.m
@deftypefn  {} {[@var{h}, @var{w}] =} freqz (@var{b}, @var{a}, @var{n}, "whole")
@deftypefnx {} {[@var{h}, @var{w}] =} freqz (@var{b})
@deftypefnx {} {[@var{h}, @var{w}] =} freqz (@var{b}, @var{a})
@deftypefnx {} {[@var{h}, @var{w}] =} freqz (@var{b}, @var{a}, @var{n})
@deftypefnx {} {@var{h} =} freqz (@var{b}, @var{a}, @var{w})
@deftypefnx {} {[@var{h}, @var{w}] =} freqz (@dots{}, @var{Fs})
@deftypefnx {} {} freqz (@dots{})

Return the complex frequency response @var{h} of the rational IIR filter
whose numerator and denominator coefficients are @var{b} and @var{a},
respectively.

The response is evaluated at @var{n} angular frequencies between 0 and
@ifnottex
2*pi.
@end ifnottex
@tex
$2\pi$.
@end tex

@noindent
The output value @var{w} is a vector of the frequencies.

If @var{a} is omitted, the denominator is assumed to be 1 (this
corresponds to a simple FIR filter).

If @var{n} is omitted, a value of 512 is assumed.  For fastest computation,
@var{n} should factor into a small number of small primes.

If the fourth argument, @qcode{"whole"}, is omitted the response is
evaluated at frequencies between 0 and
@ifnottex
pi.
@end ifnottex
@tex
$\pi$.
@end tex

@code{freqz (@var{b}, @var{a}, @var{w})}

Evaluate the response at the specific frequencies in the vector @var{w}.
The values for @var{w} are measured in radians.

@code{[@dots{}] = freqz (@dots{}, @var{Fs})}

Return frequencies in Hz instead of radians assuming a sampling rate
@var{Fs}.  If you are evaluating the response at specific frequencies
@var{w}, those frequencies should be requested in Hz rather than radians.

@code{freqz (@dots{})}

Plot the magnitude and phase response of @var{h} rather than returning them.

@xseealso{freqz_plot}
@end deftypefn
freqz_plot
@c freqz_plot scripts/signal/freqz_plot.m
@deftypefn  {} {} freqz_plot (@var{w}, @var{h})
@deftypefnx {} {} freqz_plot (@var{w}, @var{h}, @var{freq_norm})
Plot the magnitude and phase response of @var{h}.

If the optional @var{freq_norm} argument is true, the frequency vector
@var{w} is in units of normalized radians.  If @var{freq_norm} is false, or
not given, then @var{w} is measured in Hertz.
@xseealso{freqz}
@end deftypefn
hamming
@c hamming scripts/signal/hamming.m
@deftypefn  {} {} hamming (@var{m})
@deftypefnx {} {} hamming (@var{m}, "periodic")
@deftypefnx {} {} hamming (@var{m}, "symmetric")
Return the filter coefficients of a Hamming window of length @var{m}.

If the optional argument @qcode{"periodic"} is given, the periodic form
of the window is returned.  This is equivalent to the window of length
@var{m}+1 with the last coefficient removed.  The optional argument
@qcode{"symmetric"} is equivalent to not specifying a second argument.

For a definition of the Hamming window see, e.g.,
@nospell{A.V. Oppenheim & R. W. Schafer},
@cite{Discrete-Time Signal Processing}.
@end deftypefn
hanning
@c hanning scripts/signal/hanning.m
@deftypefn  {} {} hanning (@var{m})
@deftypefnx {} {} hanning (@var{m}, "periodic")
@deftypefnx {} {} hanning (@var{m}, "symmetric")
Return the filter coefficients of a Hanning window of length @var{m}.

If the optional argument @qcode{"periodic"} is given, the periodic form
of the window is returned.  This is equivalent to the window of length
@var{m}+1 with the last coefficient removed.  The optional argument
@qcode{"symmetric"} is equivalent to not specifying a second argument.

For a definition of the Hanning window see, e.g.,
@nospell{A.V. Oppenheim & R. W. Schafer},
@cite{Discrete-Time Signal Processing}.
@end deftypefn
hurst
@c hurst scripts/signal/hurst.m
@deftypefn {} {} hurst (@var{x})
Estimate the Hurst parameter of sample @var{x} via the rescaled range
statistic.

If @var{x} is a matrix, the parameter is estimated for every column.
@end deftypefn
ifftshift
@c ifftshift scripts/signal/ifftshift.m
@deftypefn  {} {} ifftshift (@var{x})
@deftypefnx {} {} ifftshift (@var{x}, @var{dim})
Undo the action of the @code{fftshift} function.

For even length @var{x}, @code{fftshift} is its own inverse, but odd lengths
differ slightly.
@xseealso{fftshift}
@end deftypefn
movfun
@c movfun scripts/signal/movfun.m
@deftypefn  {} {@var{y} =} movfun (@var{fcn}, @var{x}, @var{wlen})
@deftypefnx {} {@var{y} =} movfun (@var{fcn}, @var{x}, @var{[@var{nb}, @var{na}}])
@deftypefnx {} {@var{y} =} movfun (@dots{}, "@var{property}", @var{value})

Apply function @var{fcn} to a moving window of length @var{wlen} on data
@var{x}.

If @var{wlen} is a scalar, the function @var{fcn} is applied to a moving
window of length @var{wlen}.  When @var{wlen} is an odd number the window is
symmetric and includes @w{@code{(@var{wlen} - 1) / 2}} elements on either
side of the central element.  For example, when calculating the output at
index 5 with a window length of 3, @code{movfun} uses data elements
@w{@code{[4, 5, 6]}}.  If @var{wlen} is an even number, the window is
asymmetric and has @w{@code{@var{wlen}/2}} elements to the left of the
central element and @w{@code{@var{wlen}/2 - 1}} elements to the right of the
central element.  For example, when calculating the output at index 5 with a
window length of 4, @code{movfun} uses data elements
@w{@code{[3, 4, 5, 6]}}.

If @var{wlen} is an array with two elements @w{@code{[@var{nb}, @var{na}]}},
the function is applied to a moving window @code{-@var{nb}:@var{na}}.  This
window includes @var{nb} number of elements @emph{before} the current
element and @var{na} number of elements @emph{after} the current element.
The current element is always included.  For example, given
@w{@code{@var{wlen} = [3, 0]}}, the data used to calculate index 5 is
@w{@code{[2, 3, 4, 5]}}.

During calculations the data input @var{x} is reshaped into a 2-dimensional
@var{wlen}-by-@var{N} matrix and @var{fcn} is called on this new matrix.
Therefore, @var{fcn} must accept an array input argument and apply the
computation along dimension 1, i.e., down the columns of the array.

When applied to an array (possibly multi-dimensional) with @var{n} columns,
@var{fcn} may return a result in either of two formats: @w{Format 1)}
an array of size 1-by-@var{n}-by-@var{dim3}-by-@dots{}-by-@var{dimN}.  This
is the typical output format from Octave core functions.  Type
@code{demo ("movfun", 5)} for an example of this use case.
@w{Format 2)} a row vector of length
@code{@var{n} * @var{numel_higher_dims}} where @var{numel_higher_dims} is
@w{@code{prod (size (@var{x})(3:end))}}.  The output of @var{fcn} for the
i-th input column must be found in the output at indices
@w{@code{i:@var{n}:(@var{n}*@var{numel_higher_dims})}}.
This format is useful when concatenating functions into arrays, or when
using @code{nthargout}.  Type @code{demo ("movfun", 6)} for an example of
this case.

The calculation can be controlled by specifying @var{property}/@var{value}
pairs.  Valid properties are

@table @asis

@item @qcode{"dim"}
Operate along the dimension specified, rather than the default of the first
non-singleton dimension.

@item @qcode{"Endpoints"}

This property controls how results are calculated at the boundaries
(@w{endpoints}) of the window.  Possible values are:

@table @asis
@item @qcode{"shrink"}  (default)
The window is truncated at the beginning and end of the array to exclude
elements for which there is no source data.  For example, with a window of
length 3, @code{@var{y}(1) = @var{fcn} (@var{x}(1:2))}, and
@code{@var{y}(end) = @var{fcn} (@var{x}(end-1:end))}.

@item @qcode{"discard"}
Any @var{y} values that use a window extending beyond the original
data array are deleted.  For example, with a 10-element data vector and a
window of length 3, the output will contain only 8 elements.  The first
element would require calculating the function over indices
@w{@code{[0, 1, 2]}} and is therefore discarded.  The last element would
require calculating the function over indices @w{@code{[9, 10, 11]}} and is
therefore discarded.

@item @qcode{"fill"}
Any window elements outside the data array are replaced by @code{NaN}.  For
example, with a window of length 3,
@code{@var{y}(1) = @var{fcn} ([NaN, @var{x}(1:2)])}, and
@code{@var{y}(end) = @var{fcn} ([@var{x}(end-1:end), NaN])}.
This option usually results in @var{y} having @code{NaN} values at the
boundaries, although it is influenced by how @var{fcn} handles @code{NaN},
and also by the property @qcode{"nancond"}.

@item @var{user_value}
Any window elements outside the data array are replaced by the specified
value @var{user_value} which must be a numeric scalar.  For example, with a
window of length 3,
@code{@var{y}(1) = @var{fcn} ([@var{user_value}, @var{x}(1:2)])}, and
@code{@var{y}(end) = @var{fcn} ([@var{x}(end-1:end), @var{user_value}])}.
A common choice for @var{user_value} is 0.

@item @qcode{"same"}
Any window elements outside the data array are replaced by the value of
@var{x} at the boundary.  For example, with a window of length 3,
@code{@var{y}(1) = @var{fcn} ([@var{x}(1), @var{x}(1:2)])}, and
@code{@var{y}(end) = @var{fcn} ([@var{x}(end-1:end), @var{x}(end)])}.

@item @qcode{"periodic"}
The window is wrapped so that any missing data elements are taken from
the other side of the data.  For example, with a window of length 3,
@code{@var{y}(1) = @var{fcn} ([@var{x}(end), @var{x}(1:2)])}, and
@code{@var{y}(end) = @var{fcn} ([@var{x}(end-1:end), @var{x}(1)])}.

@end table

Note that for some of these choices, the window size at the boundaries is
not the same as for the central part, and @var{fcn} must work in these
cases.

@item @qcode{"nancond"}
Controls whether @code{NaN} and @code{NA} values should be included (value:
@qcode{"includenan"}), or excluded (value: @qcode{"omitnan"}), from the data
passed to @var{fcn}.  The default is @qcode{"includenan"}.  Caution:
The @qcode{"omitnan"} option is not yet implemented.

@item @qcode{"outdim"}
A row vector that selects which dimensions of the calculation will appear
in the output @var{y}.  This is only useful when @var{fcn} returns an
N-dimensional array in @w{Format 1}.  The default is to return all output
dimensions.

@end table

Programming Note: The property @qcode{"outdim"} can be used to save memory
when the output of @var{fcn} has many dimensions, or when a wrapper to the
base function that selects the desired outputs is too costly.  When memory
is not an issue, the easiest way to select output dimensions is to first
calculate the complete result with @code{movfun} and then filter that result
with indexing.  If code complexity is not an issue then a wrapper can be
created using anonymous functions.  For example, if @code{basefcn}
is a function returning a @var{K}-dimensional row output, and only
dimension @var{D} is desired, then the following wrapper could be used.

@example
@group
@var{fcn} = @@(x) basefcn (x)(:,size(x,2) * (@var{D}-1) + (1:size(x,2)));
@var{y} = movfun (@@fcn, @dots{});
@end group
@end example

@xseealso{movslice, prepad, postpad, permute, reshape}
@end deftypefn
movslice
@c movslice scripts/signal/movslice.m
@deftypefn  {} {@var{slcidx} =} movslice (@var{N}, @var{wlen})
@deftypefnx {} {[@var{slcidx}, @var{C}, @var{Cpre}, @var{Cpost}, @var{win}] =} movslice (@dots{})
Generate indices to slice a vector of length @var{N} in to windows
of length @var{wlen}.

FIXME: Document inputs N, wlen

FIXME: Document outputs slcidx, C, Cpre, Cpost, win.
@xseealso{movfun}
@end deftypefn
periodogram
@c periodogram scripts/signal/periodogram.m
@deftypefn  {} {[@var{Pxx}, @var{w}] =} periodogram (@var{x})
@deftypefnx {} {[@var{Pxx}, @var{w}] =} periodogram (@var{x}, @var{win})
@deftypefnx {} {[@var{Pxx}, @var{w}] =} periodogram (@var{x}, @var{win}, @var{nfft})
@deftypefnx {} {[@var{Pxx}, @var{f}] =} periodogram (@var{x}, @var{win}, @var{nfft}, @var{Fs})
@deftypefnx {} {[@var{Pxx}, @var{f}] =} periodogram (@dots{}, "@var{range}")
@deftypefnx {} {} periodogram (@dots{})
Return the periodogram (Power Spectral Density) of @var{x}.

The possible inputs are:

@table @var
@item x

data vector.  If @var{x} is real-valued a one-sided spectrum is estimated.
If @var{x} is complex-valued, or @qcode{"@var{range}"} specifies
@qcode{"@nospell{twosided}"}, the full spectrum is estimated.

@item win
window weight data.  If window is empty or unspecified a default rectangular
window is used.  Otherwise, the window is applied to the signal
(@code{@var{x} .* @var{win}}) before computing the periodogram.  The window
data must be a vector of the same length as @var{x}.

@item nfft
number of frequency bins.  The default is 256 or the next higher power of
2 greater than the length of @var{x}
(@code{max (256, 2.^nextpow2 (length (x)))}).  If @var{nfft} is greater
than the length of the input then @var{x} will be zero-padded to the length
of @var{nfft}.

@item Fs
sampling rate.  The default is 1.

@item range
range of spectrum.  @qcode{"@nospell{onesided}"} computes spectrum from
[0:nfft/2+1].  @qcode{"@nospell{twosided}"} computes spectrum from
[0:nfft-1].
@end table

The optional second output @var{w} are the normalized angular frequencies.
For a one-sided calculation @var{w} is in the range [0, pi] if @var{nfft}
is even and [0, pi) if @var{nfft} is odd.  Similarly, for a two-sided
calculation @var{w} is in the range [0, 2*pi] or [0, 2*pi) depending on
@var{nfft}.

If a sampling frequency is specified, @var{Fs}, then the output frequencies
@var{f} will be in the range [0, @var{Fs}/2] or [0, @var{Fs}/2) for
one-sided calculations.  For two-sided calculations the range will be
[0, @var{Fs}).

When called with no outputs the periodogram is immediately plotted in the
current figure window.
@xseealso{fft}
@end deftypefn
sinc
@c sinc scripts/signal/sinc.m
@deftypefn {} {} sinc (@var{x})
Compute the sinc function.

Return
@tex
$ \sin (\pi x)/(\pi x)$.
@end tex
@ifnottex
sin (pi*x) / (pi*x).
@end ifnottex
@end deftypefn
sinetone
@c sinetone scripts/signal/sinetone.m
@deftypefn {} {} sinetone (@var{freq}, @var{rate}, @var{sec}, @var{ampl})
Return a sinetone of frequency @var{freq} with a length of @var{sec}
seconds at sampling rate @var{rate} and with amplitude @var{ampl}.

The arguments @var{freq} and @var{ampl} may be vectors of common size.

The defaults are @var{rate} = 8000, @var{sec} = 1, and @var{ampl} = 64.
@xseealso{sinewave}
@end deftypefn
sinewave
@c sinewave scripts/signal/sinewave.m
@deftypefn {} {} sinewave (@var{m}, @var{n}, @var{d})
Return an @var{m}-element vector with @var{i}-th element given by
@code{sin (2 * pi * (@var{i}+@var{d}-1) / @var{n})}.

The default value for @var{d} is 0 and the default value for @var{n} is
@var{m}.
@xseealso{sinetone}
@end deftypefn
spectral_adf
@c spectral_adf scripts/signal/spectral_adf.m
@deftypefn  {} {} spectral_adf (@var{c})
@deftypefnx {} {} spectral_adf (@var{c}, @var{win})
@deftypefnx {} {} spectral_adf (@var{c}, @var{win}, @var{b})
Return the spectral density estimator given a vector of autocovariances
@var{c}, window name @var{win}, and bandwidth, @var{b}.

The window name, e.g., @qcode{"triangle"} or @qcode{"rectangle"} is
used to search for a function called @code{@var{win}_lw}.

If @var{win} is omitted, the triangle window is used.

If @var{b} is omitted, @code{1 / sqrt (length (@var{x}))} is used.
@xseealso{spectral_xdf}
@end deftypefn
spectral_xdf
@c spectral_xdf scripts/signal/spectral_xdf.m
@deftypefn  {} {} spectral_xdf (@var{x})
@deftypefnx {} {} spectral_xdf (@var{x}, @var{win})
@deftypefnx {} {} spectral_xdf (@var{x}, @var{win}, @var{b})
Return the spectral density estimator given a data vector @var{x}, window
name @var{win}, and bandwidth, @var{b}.

The window name, e.g., @qcode{"triangle"} or @qcode{"rectangle"} is used to
search for a function called @code{@var{win}_sw}.

If @var{win} is omitted, the triangle window is used.

If @var{b} is omitted, @code{1 / sqrt (length (@var{x}))} is used.
@xseealso{spectral_adf}
@end deftypefn
spencer
@c spencer scripts/signal/spencer.m
@deftypefn {} {} spencer (@var{x})
Return @nospell{Spencer's} 15 point moving average of each column of
@var{x}.
@end deftypefn
stft
@c stft scripts/signal/stft.m
@deftypefn  {} {@var{y} =} stft (@var{x})
@deftypefnx {} {@var{y} =} stft (@var{x}, @var{win_size})
@deftypefnx {} {@var{y} =} stft (@var{x}, @var{win_size}, @var{inc})
@deftypefnx {} {@var{y} =} stft (@var{x}, @var{win_size}, @var{inc}, @var{num_coef})
@deftypefnx {} {@var{y} =} stft (@var{x}, @var{win_size}, @var{inc}, @var{num_coef}, @var{win_type})
@deftypefnx {} {[@var{y}, @var{c}] =} stft (@dots{})
Compute the short-time Fourier transform of the vector @var{x} with
@var{num_coef} coefficients by applying a window of @var{win_size} data
points and an increment of @var{inc} points.

Before computing the Fourier transform, one of the following windows
is applied:

@table @asis
@item @qcode{"hanning"}
win_type = 1

@item @qcode{"hamming"}
win_type = 2

@item @qcode{"rectangle"}
win_type = 3
@end table

The window names can be passed as strings or by the @var{win_type} number.

The following defaults are used for unspecified arguments:
@var{win_size} = 80, @var{inc} = 24, @var{num_coef} = 64, and
@var{win_type} = 1.

@code{@var{y} = stft (@var{x}, @dots{})} returns the absolute values of the
Fourier coefficients according to the @var{num_coef} positive frequencies.

@code{[@var{y}, @var{c}] = stft (@var{x}, @dots{})} returns the entire
STFT-matrix @var{y} and a 3-element vector @var{c} containing the window
size, increment, and window type, which is needed by the @code{synthesis}
function.
@xseealso{synthesis}
@end deftypefn
synthesis
@c synthesis scripts/signal/synthesis.m
@deftypefn {} {@var{x} =} synthesis (@var{y}, @var{c})
Compute a signal from its short-time Fourier transform @var{y} and a
3-element vector @var{c} specifying window size, increment, and window type.

The values @var{y} and @var{c} can be derived by

@example
[@var{y}, @var{c}] = stft (@var{x} , @dots{})
@end example
@xseealso{stft}
@end deftypefn
unwrap
@c unwrap scripts/signal/unwrap.m
@deftypefn  {} {@var{b} =} unwrap (@var{x})
@deftypefnx {} {@var{b} =} unwrap (@var{x}, @var{tol})
@deftypefnx {} {@var{b} =} unwrap (@var{x}, @var{tol}, @var{dim})

Unwrap radian phases by adding or subtracting multiples of 2*pi as
appropriate to remove jumps greater than @var{tol}.

@var{tol} defaults to pi.

Unwrap will work along the dimension @var{dim}.  If @var{dim}
is unspecified it defaults to the first non-singleton dimension.
@end deftypefn
yulewalker
@c yulewalker scripts/signal/yulewalker.m
@deftypefn {} {[@var{a}, @var{v}] =} yulewalker (@var{c})
Fit an AR (p)-model with Yule-Walker estimates given a vector @var{c} of
autocovariances @code{[gamma_0, @dots{}, gamma_p]}.

Returns the AR coefficients, @var{a}, and the variance of white noise,
@var{v}.
@end deftypefn
bicg
@c bicg scripts/sparse/bicg.m
@deftypefn  {} {@var{x} =} bicg (@var{A}, @var{b})
@deftypefnx {} {@var{x} =} bicg (@var{A}, @var{b}, @var{tol})
@deftypefnx {} {@var{x} =} bicg (@var{A}, @var{b}, @var{tol}, @var{maxit})
@deftypefnx {} {@var{x} =} bicg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M})
@deftypefnx {} {@var{x} =} bicg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M1}, @var{M2})
@deftypefnx {} {@var{x} =} bicg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M}, [], @var{x0})
@deftypefnx {} {@var{x} =} bicg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0})
@deftypefnx {} {@var{x} =} bicg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M}, [], @var{x0}, @dots{})
@deftypefnx {} {@var{x} =} bicg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0}, @dots{})
@deftypefnx {} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} bicg (@var{A}, @var{b}, @dots{})
Solve the linear system of equations @w{@code{@var{A} * @var{x} = @var{b}}}
by means of the Bi-Conjugate Gradient iterative method.

The input arguments are:

@itemize

@item @var{A} is the matrix of the linear system and it must be square.
@var{A} can be passed as a matrix, function handle, or inline function
@code{Afun} such that @w{@code{Afun (x, "notransp") = A * x}} and
@w{@code{Afun (x, "transp") = A' * x}}.  Additional parameters to
@code{Afun} may be passed after @var{x0}.

@item @var{b} is the right-hand side vector.  It must be a column vector
with the same number of rows as @var{A}.

@item
@var{tol} is the required relative tolerance for the residual error,
@w{@code{@var{b} - @var{A} * @var{x}}}.  The iteration stops if
@w{@code{norm (@var{b} - @var{A} * @var{x})} @leq{}
@w{@code{@var{tol} * norm (@var{b})}}}.
If @var{tol} is omitted or empty, then a tolerance of 1e-6 is used.

@item
@var{maxit} is the maximum allowed number of iterations; if @var{maxit}
is omitted or empty then a value of 20 is used.

@item
@var{M1}, @var{M2} are the preconditioners.  The preconditioner @var{M} is
given as @code{@var{M} = @var{M1} * @var{M2}}.  Both @var{M1} and @var{M2}
can be passed as a matrix or as a function handle or inline function
@code{g} such that @w{@code{g (@var{x}, "notransp") = @var{M1} \ @var{x}}}
or @w{@code{g (@var{x}, "notransp") = @var{M2} \ @var{x}}} and
@w{@code{g (@var{x}, "transp") = @var{M1}' \ @var{x}}} or
@w{@code{g (@var{x}, "transp") = @var{M2}' \ @var{x}}}.
If @var{M1} is omitted or empty, then preconditioning is not applied.
The preconditioned system is theoretically equivalent to applying the
@code{bicg} method to the linear system
@code{inv (@var{M1}) * A * inv (@var{M2}) * @var{y} = inv
(@var{M1}) * @var{b}} and
@code{inv (@var{M2'}) * A' * inv (@var{M1'}) * @var{z} =
inv (@var{M2'}) * @var{b}} and then setting
@code{@var{x} = inv (@var{M2}) * @var{y}}.

@item
@var{x0} is the initial guess.  If @var{x0} is omitted or empty then the
function sets @var{x0} to a zero vector by default.
@end itemize

Any arguments which follow @var{x0} are treated as parameters, and passed in
an appropriate manner to any of the functions (@var{Afun} or @var{Mfun}) or
that have been given to @code{bicg}.

The output parameters are:

@itemize

@item
@var{x} is the computed approximation to the solution of
@w{@code{@var{A} * @var{x} = @var{b}}}.  If the algorithm did not converge,
then @var{x} is the iteration which has the minimum residual.

@item
@var{flag} indicates the exit status:

@itemize
@item 0: The algorithm converged to within the prescribed tolerance.

@item 1: The algorithm did not converge and it reached the maximum number of
iterations.

@item 2: The preconditioner matrix is singular.

@item 3: The algorithm stagnated, i.e., the absolute value of the
difference between the current iteration @var{x} and the previous is less
than @code{eps * norm (@var{x},2)}.

@item 4: The algorithm could not continue because intermediate values
became too small or too large for reliable computation.
@end itemize

@item
@var{relres} is the ratio of the final residual to its initial value,
measured in the Euclidean norm.

@item
@var{iter} is the iteration which @var{x} is computed.

@item
@var{resvec} is a vector containing the residual at each iteration.
The total number of iterations performed is given by
@code{length (@var{resvec}) - 1}.
@end itemize

Consider a trivial problem with a tridiagonal matrix

@example
@group
n = 20;
A = toeplitz (sparse ([1, 1], [1, 2], [2, 1] * n ^ 2, 1, n)) + ...
    toeplitz (sparse (1, 2, -1, 1, n) * n / 2, ...
              sparse (1, 2, 1, 1, n) * n / 2);
b = A * ones (n, 1);
restart = 5;
[M1, M2] = ilu (A);  # in this tridiag case, it corresponds to lu (A)
M = M1 * M2;
Afun = @@(x, string) strcmp (string, "notransp") * (A * x) + ...
                     strcmp (string, "transp") * (A' * x);
Mfun = @@(x, string) strcmp (string, "notransp") * (M \ x) + ...
                     strcmp (string, "transp") * (M' \ x);
M1fun = @@(x, string) strcmp (string, "notransp") * (M1 \ x) + ...
                     strcmp (string, "transp") * (M1' \ x);
M2fun = @@(x, string) strcmp (string, "notransp") * (M2 \ x) + ...
                     strcmp (string, "transp") * (M2' \ x);
@end group
@end example

@sc{Example 1:} simplest usage of @code{bicg}

@example
x = bicg (A, b)
@end example

@sc{Example 2:} @code{bicg} with a function that computes
@code{@var{A}*@var{x}} and @code{@var{A'}*@var{x}}

@example
x = bicg (Afun, b, [], n)
@end example

@sc{Example 3:} @code{bicg} with a preconditioner matrix @var{M}

@example
x = bicg (A, b, 1e-6, n, M)
@end example

@sc{Example 4:} @code{bicg} with a function as preconditioner

@example
x = bicg (Afun, b, 1e-6, n, Mfun)
@end example

@sc{Example 5:} @code{bicg} with preconditioner matrices @var{M1}
and @var{M2}

@example
x = bicg (A, b, 1e-6, n, M1, M2)
@end example

@sc{Example 6:} @code{bicg} with functions as preconditioners

@example
x = bicg (Afun, b, 1e-6, n, M1fun, M2fun)
@end example

@sc{Example 7:} @code{bicg} with as input a function requiring an argument

@example
@group
function y = Ap (A, x, string, z)
  ## compute A^z * x or (A^z)' * x
  y = x;
  if (strcmp (string, "notransp"))
    for i = 1:z
      y = A * y;
    endfor
  elseif (strcmp (string, "transp"))
    for i = 1:z
      y = A' * y;
    endfor
  endif
endfunction

Apfun = @@(x, string, p) Ap (A, x, string, p);
x = bicg (Apfun, b, [], [], [], [], [], 2);
@end group
@end example

References:

@enumerate

@item @nospell{Y. Saad}, @cite{Iterative Methods for Sparse Linear Systems},
Second edition, 2003, SIAM.

@end enumerate

@xseealso{bicgstab, cgs, gmres, pcg, qmr, tfqmr}
@end deftypefn
bicgstab
@c bicgstab scripts/sparse/bicgstab.m
@deftypefn  {} {@var{x} =} bicgstab (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0}, @dots{})
@deftypefnx {} {@var{x} =} bicgstab (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M}, [], @var{x0}, @dots{})
@deftypefnx {} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} bicgstab (@var{A}, @var{b}, @dots{})
Solve @code{A x = b} using the stabilized Bi-conjugate gradient iterative
method.

The input parameters are:

@itemize @minus

@item @var{A} is the matrix of the linear system and it must be square.
@var{A} can be passed as a matrix, function handle, or inline
function @code{Afun} such that @code{Afun(x) = A * x}.  Additional
parameters to @code{Afun} are passed after @var{x0}.

@item @var{b} is the right hand side vector.  It must be a column vector
with the same number of rows as @var{A}.

@item
@var{tol} is the required relative tolerance for the residual error,
@w{@code{@var{b} - @var{A} * @var{x}}}.  The iteration stops if
@w{@code{norm (@var{b} - @var{A} * @var{x})} @leq{}
@w{@code{@var{tol} * norm (@var{b})}}}.
If @var{tol} is omitted or empty, then a tolerance of 1e-6 is used.

@item @var{maxit} the maximum number of outer iterations, if not given or
set to [] the default value @code{min (20, numel (b))} is used.

@item @var{M1}, @var{M2} are the preconditioners.  The preconditioner
@var{M} is given as @code{@var{M} = @var{M1} * @var{M2}}.
Both @var{M1} and @var{M2} can be passed as a matrix or as a function
handle or inline function @code{g} such that
@code{g(@var{x}) = @var{M1} \ @var{x}} or
@code{g(@var{x}) = @var{M2} \ @var{x}}.
The technique used is the right preconditioning, i.e., it is
solved @code{@var{A} * inv (@var{M}) * @var{y} = @var{b}} and then
@code{@var{x} = inv (@var{M}) * @var{y}}.

@item @var{x0} the initial guess, if not given or set to [] the default
value @code{zeros (size (@var{b}))} is used.

@end itemize

The arguments which follow @var{x0} are treated as parameters, and passed in
a proper way to any of the functions (@var{A} or @var{M}) which are passed
to @code{bicstab}.

The output parameters are:

@itemize @minus

@item @var{x} is the approximation computed.  If the method doesn't
converge then it is the iterated with the minimum residual.

@item @var{flag} indicates the exit status:

@itemize @minus
@item 0: iteration converged to the within the chosen tolerance

@item 1: the maximum number of iterations was reached before convergence

@item 2: the preconditioner matrix is singular

@item 3: the algorithm reached stagnation

@item 4: the algorithm can't continue due to a division by zero
@end itemize

@item @var{relres} is the relative residual obtained with as
@code{(@var{A}*@var{x}-@var{b}) / @code{norm(@var{b})}}.

@item @var{iter} is the (possibly half) iteration which @var{x} is
computed.  If it is an half iteration then it is @code{@var{iter} + 0.5}

@item @var{resvec} is a vector containing the residual of each half and
total iteration (There are also the half iterations since @var{x} is
computed in two steps at each iteration).
Doing @code{(length(@var{resvec}) - 1) / 2} is possible to see the
total number of (total) iterations performed.

@end itemize

Let us consider a trivial problem with a tridiagonal matrix

@example
@group
n = 20;
A = toeplitz (sparse ([1, 1], [1, 2], [2, 1] * n ^ 2, 1, n))  + ...
    toeplitz (sparse (1, 2, -1, 1, n) * n / 2, ...
    sparse (1, 2, 1, 1, n) * n / 2);
b = A * ones (n, 1);
restart = 5;
[M1, M2] = ilu (A); # in this tridiag case, it corresponds to lu (A)
M = M1 * M2;
Afun = @@(x) A * x;
Mfun = @@(x) M \ x;
M1fun = @@(x) M1 \ x;
M2fun = @@(x) M2 \ x;
@end group
@end example

@sc{Example 1:} simplest usage of @code{bicgstab}

@example
x = bicgstab (A, b, [], n)
@end example

@sc{Example 2:} @code{bicgstab} with a function which computes
@code{@var{A} * @var{x}}

@example
x = bicgstab (Afun, b, [], n)
@end example

@sc{Example 3:} @code{bicgstab} with a preconditioner matrix @var{M}

@example
x = bicgstab (A, b, [], 1e-06, n, M)
@end example

@sc{Example 4:} @code{bicgstab} with a function as preconditioner

@example
x = bicgstab (Afun, b, 1e-6, n, Mfun)
@end example

@sc{Example 5:} @code{bicgstab} with preconditioner matrices @var{M1}
and @var{M2}

@example
x = bicgstab (A, b, [], 1e-6, n, M1, M2)
@end example

@sc{Example 6:} @code{bicgstab} with functions as preconditioners

@example
x = bicgstab (Afun, b, 1e-6, n, M1fun, M2fun)
@end example

@sc{Example 7:} @code{bicgstab} with as input a function requiring
an argument

@example
@group
function y = Ap (A, x, z) # compute A^z * x
   y = x;
   for i = 1:z
     y = A * y;
   endfor
 endfunction
Apfun = @@(x, string, p) Ap (A, x, string, p);
x = bicgstab (Apfun, b, [], [], [], [], [], 2);
@end group
@end example

@sc{Example 8:} explicit example to show that @code{bicgstab} uses a
right preconditioner

@example
@group
[M1, M2] = ilu (A + 0.1 * eye (n)); # factorization of A perturbed
M = M1 * M2;

## reference solution computed by bicgstab after one iteration
[x_ref, fl] = bicgstab (A, b, [], 1, M)

## right preconditioning
[y, fl] = bicgstab (A / M, b, [], 1)
x = M \ y # compare x and x_ref

@end group
@end example

References:

@enumerate

@item @nospell{Y. Saad}, @cite{Iterative Methods for Sparse Linear
Systems}, Second edition, 2003, SIAM

@end enumerate

@xseealso{bicg, cgs, gmres, pcg, qmr, tfqmr}

@end deftypefn
cgs
@c cgs scripts/sparse/cgs.m
@deftypefn  {} {@var{x} =} cgs (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0}, @dots{})
@deftypefnx {} {@var{x} =} cgs (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M}, [], @var{x0}, @dots{})
@deftypefnx {} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} cgs (@var{A}, @var{b}, @dots{})
Solve @code{A x = b}, where @var{A} is a square matrix, using the
Conjugate Gradients Squared method.

The input arguments are:

@itemize @minus

@item @var{A} is the matrix of the linear system and it must be square.
@var{A} can be passed as a matrix, function handle, or inline
function @code{Afun} such that @code{Afun(x) = A * x}.  Additional
parameters to @code{Afun} are passed after @var{x0}.

@item @var{b} is the right hand side vector.  It must be a column vector
with same number of rows of @var{A}.

@item @var{tol} is the relative tolerance, if not given or set to [] the
default value 1e-6 is used.

@item @var{maxit} the maximum number of outer iterations, if not given or
set to [] the default value @code{min (20, numel (b))} is used.

@item @var{M1}, @var{M2} are the preconditioners.  The preconditioner
matrix is given as @code{M = M1 * M2}.  Both @var{M1}
and @var{M2} can be passed as a matrix or as a function handle or inline
function @code{g} such that @code{g(x) = M1 \ x} or @code{g(x) = M2 \ x}.
If M1 is empty or not passed then no preconditioners are applied.
The technique used is the right preconditioning, i.e., it is solved
@code{@var{A}*inv(@var{M})*y = b} and then @code{@var{x} = inv(@var{M})*y}.

@item @var{x0} the initial guess, if not given or set to [] the default
value @code{zeros (size (b))} is used.
@end itemize

The arguments which follow @var{x0} are treated as parameters, and passed in
a proper way to any of the functions (@var{A} or @var{P}) which are passed
to @code{cgs}.

The output parameters are:

@itemize @minus

@item @var{x} is the approximation computed.  If the method doesn't
converge then it is the iterated with the minimum residual.

@item @var{flag} indicates the exit status:

@itemize @minus
@item 0: iteration converged to the within the chosen tolerance

@item 1: the maximum number of iterations was reached before convergence

@item 2: the preconditioner matrix is singular

@item 3: the algorithm reached stagnation

@item 4: the algorithm can't continue due to a division by zero
@end itemize

@item @var{relres} is the relative residual obtained with as
@code{(@var{A}*@var{x}-@var{b}) / @code{norm(@var{b})}}.

@item @var{iter} is the iteration which @var{x} is computed.

@item @var{resvec} is a vector containing the residual at each iteration.
Doing @code{length(@var{resvec}) - 1} is possible to see the total number
of iterations performed.
@end itemize

Let us consider a trivial problem with a tridiagonal matrix

@example
@group
n = 20;
A = toeplitz (sparse ([1, 1], [1, 2], [2, 1] * n ^ 2, 1, n))  + ...
    toeplitz (sparse (1, 2, -1, 1, n) * n / 2, ...
    sparse (1, 2, 1, 1, n) * n / 2);
b = A * ones (n, 1);
restart = 5;
[M1, M2] = ilu (A); # in this tridiag case it corresponds to chol (A)'
M = M1 * M2;
Afun = @@(x) A * x;
Mfun = @@(x) M \ x;
M1fun = @@(x) M1 \ x;
M2fun = @@(x) M2 \ x;
@end group
@end example

@sc{Example 1:} simplest usage of @code{cgs}

@example
x = cgs (A, b, [], n)
@end example

@sc{Example 2:} @code{cgs} with a function which computes
@code{@var{A} * @var{x}}

@example
x = cgs (Afun, b, [], n)
@end example

@sc{Example 3:} @code{cgs} with a preconditioner matrix @var{M}

@example
x = cgs (A, b, [], 1e-06, n, M)
@end example

@sc{Example 4:} @code{cgs} with a function as preconditioner

@example
x = cgs (Afun, b, 1e-6, n, Mfun)
@end example

@sc{Example 5:} @code{cgs} with preconditioner matrices @var{M1}
and @var{M2}

@example
x = cgs (A, b, [], 1e-6, n, M1, M2)
@end example

@sc{Example 6:} @code{cgs} with functions as preconditioners

@example
x = cgs (Afun, b, 1e-6, n, M1fun, M2fun)
@end example

@sc{Example 7:} @code{cgs} with as input a function requiring an argument

@example
@group
function y = Ap (A, x, z) # compute A^z * x
   y = x;
   for i = 1:z
     y = A * y;
   endfor
 endfunction
Apfun = @@(x, string, p) Ap (A, x, string, p);
x = cgs (Apfun, b, [], [], [], [], [], 2);
@end group
@end example

@sc{Example 8:} explicit example to show that @code{cgs} uses a
right preconditioner

@example
@group
[M1, M2] = ilu (A + 0.3 * eye (n)); # factorization of A perturbed
M = M1 * M2;

## reference solution computed by cgs after one iteration
[x_ref, fl] = cgs (A, b, [], 1, M)

## right preconditioning
[y, fl] = cgs (A / M, b, [], 1)
x = M \ y # compare x and x_ref

@end group
@end example

References:

@enumerate

@item @nospell{Y. Saad}, @cite{Iterative Methods for Sparse Linear Systems},
Second edition, 2003, SIAM

@end enumerate

@xseealso{pcg, bicgstab, bicg, gmres, qmr, tfqmr}
@end deftypefn
colperm
@c colperm scripts/sparse/colperm.m
@deftypefn {} {@var{p} =} colperm (@var{s})
Return the column permutations such that the columns of
@code{@var{s} (:, @var{p})} are ordered in terms of increasing number of
nonzero elements.

If @var{s} is symmetric, then @var{p} is chosen such that
@code{@var{s} (@var{p}, @var{p})} orders the rows and columns with
increasing number of nonzeros elements.
@end deftypefn
eigs
@c eigs scripts/sparse/eigs.m
@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{})
Calculate a limited number of eigenvalues and eigenvectors of @var{A},
based on a selection criteria.

The number of eigenvalues and eigenvectors to calculate is given by
@var{k} and defaults to 6.

By default, @code{eigs} solve the equation
@tex
$A \nu = \lambda \nu$,
@end tex
@ifinfo
@code{A * v = lambda * v},
@end ifinfo
where
@tex
$\lambda$ is a scalar representing one of the eigenvalues, and $\nu$
@end tex
@ifinfo
@code{lambda} is a scalar representing one of the eigenvalues, and @code{v}
@end ifinfo
is the corresponding eigenvector.  If given the positive definite matrix
@var{B} then @code{eigs} solves the general eigenvalue equation
@tex
$A \nu = \lambda B \nu$.
@end tex
@ifinfo
@code{A * v = lambda * B * v}.
@end ifinfo

The argument @var{sigma} determines which eigenvalues are returned.
@var{sigma} can be either a scalar or a string.  When @var{sigma} is a
scalar, the @var{k} eigenvalues closest to @var{sigma} are returned.  If
@var{sigma} is a string, it must have one of the following values.

@table @asis
@item @nospell{@qcode{"lm"}}
Largest Magnitude (default).

@item @nospell{@qcode{"sm"}}
Smallest Magnitude.

@item @qcode{"la"}
Largest Algebraic (valid only for real symmetric problems).

@item @nospell{@qcode{"sa"}}
Smallest Algebraic (valid only for real symmetric problems).

@item @qcode{"be"}
Both Ends, with one more from the high-end if @var{k} is odd (valid only for
real symmetric problems).

@item @nospell{@qcode{"lr"}}
Largest Real part (valid only for complex or unsymmetric problems).

@item @nospell{@qcode{"sr"}}
Smallest Real part (valid only for complex or unsymmetric problems).

@item @nospell{@qcode{"li"}}
Largest Imaginary part (valid only for complex or unsymmetric problems).

@item @nospell{@qcode{"si"}}
Smallest Imaginary part (valid only for complex or unsymmetric problems).
@end table

If @var{opts} is given, it is a structure defining possible options that
@code{eigs} should use.  The fields of the @var{opts} structure are:

@table @code
@item issym
If @var{af} is given, then flags whether the function @var{af} defines a
symmetric problem.  It is ignored if @var{A} is given.  The default is
false.

@item isreal
If @var{af} is given, then flags whether the function @var{af} defines a
real problem.  It is ignored if @var{A} is given.  The default is true.

@item tol
Defines the required convergence tolerance, calculated as
@code{tol * norm (A)}.  The default is @code{eps}.

@item maxit
The maximum number of iterations.  The default is 300.

@item p
The number of Lanzcos basis vectors to use.  More vectors will result in
faster convergence, but a greater use of memory.  The optimal value of
@code{p} is problem dependent and should be in the range @code{@var{k} + 1}
to @var{n}.  The default value is @code{2 * @var{k}}.

@item v0
The starting vector for the algorithm.  An initial vector close to the
final vector will speed up convergence.  The default is for @sc{arpack}
to randomly generate a starting vector.  If specified, @code{v0} must be
an @var{n}-by-1 vector where @code{@var{n} = rows (@var{A})}

@item disp
The level of diagnostic printout (0|1|2).  If @code{disp} is 0 then
diagnostics are disabled.  The default value is 0.

@item cholB
Flag if @code{chol (@var{B})} is passed rather than @var{B}.  The default is
false.

@item permB
The permutation vector of the Cholesky@tie{}factorization of @var{B} if
@code{cholB} is true.  It is obtained by @code{[R, ~, permB] =
chol (@var{B}, @qcode{"vector"})}.  The default is @code{1:@var{n}}.

@end table

It is also possible to represent @var{A} by a function denoted @var{af}.
@var{af} must be followed by a scalar argument @var{n} defining the length
of the vector argument accepted by @var{af}.  @var{af} can be a function
handle, an inline function, or a string.  When @var{af} is a string it
holds the name of the function to use.

@var{af} is a function of the form @code{y = af (x)} where the required
return value of @var{af} is determined by the value of @var{sigma}.  The
four possible forms are

@table @code
@item A * x
if @var{sigma} is not given or is a string other than "sm".

@item A \ x
if @var{sigma} is 0 or "sm".

@item (A - sigma * I) \ x
for the standard eigenvalue problem, where @code{I} is the identity matrix
of the same size as @var{A}.

@item (A - sigma * B) \ x
for the general eigenvalue problem.
@end table

The return arguments of @code{eigs} depend on the number of return arguments
requested.  With a single return argument, a vector @var{d} of length
@var{k} is returned containing the @var{k} eigenvalues that have been
found.  With two return arguments, @var{V} is a @var{n}-by-@var{k} matrix
whose columns are the @var{k} eigenvectors corresponding to the returned
eigenvalues.  The eigenvalues themselves are returned in @var{d} in the
form of a @var{n}-by-@var{k} matrix, where the elements on the diagonal
are the eigenvalues.

Given a third return argument @var{flag}, @code{eigs} returns the status
of the convergence.  If @var{flag} is 0 then all eigenvalues have converged.
Any other value indicates a failure to converge.

This function is based on the @sc{arpack} package, written by
@nospell{R. Lehoucq, K. Maschhoff, D. Sorensen, and C. Yang}.  For more
information see @url{http://www.caam.rice.edu/software/ARPACK/}.

@xseealso{eig, svds}
@end deftypefn
etreeplot
@c etreeplot scripts/sparse/etreeplot.m
@deftypefn  {} {} etreeplot (@var{A})
@deftypefnx {} {} etreeplot (@var{A}, @var{node_style}, @var{edge_style})
Plot the elimination tree of the matrix @var{A} or
@tcode{@var{A}+@var{A}'} if @var{A} in not symmetric.

The optional parameters @var{node_style} and @var{edge_style} define the
output style.
@xseealso{treeplot, gplot}
@end deftypefn
gmres
@c gmres scripts/sparse/gmres.m
@deftypefn  {} {@var{x} =} gmres (@var{A}, @var{b}, @var{restart}, @var{tol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0}, @dots{})
@deftypefnx {} {@var{x} =} gmres (@var{A}, @var{b}, @var{restart}, @var{tol}, @var{maxit}, @var{M}, [], @var{x0}, @dots{})
@deftypefnx {} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} gmres (@var{A}, @var{b}, @dots{})
Solve @code{A x = b} using the Preconditioned GMRES iterative method with
restart, a.k.a. PGMRES(restart).

The input arguments are:

@itemize @minus

@item @var{A} is the matrix of the linear system and it must be square.
@var{A} can be passed as a matrix, function handle, or inline
function @code{Afun} such that @code{Afun(x) = A * x}.  Additional
parameters to @code{Afun} are passed after @var{x0}.

@item @var{b} is the right hand side vector.  It must be a column vector
with the same numbers of rows as @var{A}.

@item @var{restart} is the number of iterations before that the
method restarts.  If it is [] or N = numel (b), then the restart
is not applied.

@item @var{tol} is the required relative tolerance for the
preconditioned residual error,
@code{inv (@var{M}) * (@var{b} - @var{a} * @var{x})}.  The iteration
stops if @code{norm (inv (@var{M}) * (@var{b} - @var{a} * @var{x}))
@leq{} @var{tol} * norm (inv (@var{M}) * @var{B})}.  If @var{tol} is
omitted or empty, then a tolerance of 1e-6 is used.

@item @var{maxit} is the maximum number of outer iterations, if not given or
set to [], then the default value @code{min (10, @var{N} / @var{restart})}
is used.
Note that, if @var{restart} is empty, then @var{maxit} is the maximum number
of iterations.  If @var{restart} and @var{maxit} are not empty, then
the maximum number of iterations is @code{@var{restart} * @var{maxit}}.
If both @var{restart} and @var{maxit} are empty, then the maximum
number of iterations is set to @code{min (10, @var{N})}.

@item @var{M1}, @var{M2} are the preconditioners.  The preconditioner
@var{M} is given as @code{M = M1 * M2}.  Both @var{M1} and @var{M2} can
be passed as a matrix, function handle, or inline function @code{g} such
that @code{g(x) = M1 \ x} or @code{g(x) = M2 \ x}.  If @var{M1} is [] or not
given, then the preconditioner is not applied.
The technique used is the left-preconditioning, i.e., it is solved
@code{inv(@var{M}) * @var{A} * @var{x} = inv(@var{M}) * @var{b}} instead of
@code{@var{A} * @var{x} = @var{b}}.

@item @var{x0} is the initial guess,
if not given or set to [], then the default value
@code{zeros (size (@var{b}))} is used.

@end itemize

The arguments which follow @var{x0} are treated as parameters, and passed in
a proper way to any of the functions (@var{A} or @var{M} or
@var{M1} or @var{M2}) which are passed to @code{gmres}.

The outputs are:

@itemize @minus

@item @var{x} the computed approximation.  If the method does not
converge, then it is the iterated with minimum residual.

@item @var{flag} indicates the exit status:

@table @asis
@item 0 : iteration converged to within the specified tolerance

@item 1 : maximum number of iterations exceeded

@item 2 : the preconditioner matrix is singular

@item 3 : algorithm reached stagnation (the relative difference between two
consecutive iterations is less than eps)
@end table

@item @var{relres} is the value of the relative preconditioned
residual of the approximation @var{x}.

@item @var{iter} is a vector containing the number of outer iterations and
inner iterations performed to compute @var{x}.  That is:

@itemize
@item @var{iter(1)}: number of outer iterations, i.e., how many
times the method restarted.  (if @var{restart} is empty or @var{N},
then it is 1, if not 1 @leq{} @var{iter(1)} @leq{} @var{maxit}).

@item @var{iter(2)}: the number of iterations performed before the
restart, i.e., the method restarts when
@code{@var{iter(2)} = @var{restart}}.  If @var{restart} is empty or
@var{N}, then 1 @leq{} @var{iter(2)} @leq{} @var{maxit}.
@end itemize

To be more clear, the approximation @var{x} is computed at the iteration
@code{(@var{iter(1)} - 1) * @var{restart} + @var{iter(2)}}.
Since the output @var{x} corresponds to the minimal preconditioned
residual solution, the total number of iterations that
the method performed is given by @code{length (resvec) - 1}.

@item @var{resvec} is a vector containing the preconditioned
relative residual at each iteration, including the 0-th iteration
@code{norm (@var{A} * @var{x0} - @var{b})}.
@end itemize

Let us consider a trivial problem with a tridiagonal matrix

@example
@group
n = 20;
A = toeplitz (sparse ([1, 1], [1, 2], [2, 1] * n ^ 2, 1, n))  + ...
    toeplitz (sparse (1, 2, -1, 1, n) * n / 2, ...
    sparse (1, 2, 1, 1, n) * n / 2);
b = A * ones (n, 1);
restart = 5;
[M1, M2] = ilu (A); # in this tridiag case, it corresponds to lu (A)
M = M1 * M2;
Afun = @@(x) A * x;
Mfun = @@(x) M \ x;
M1fun = @@(x) M1 \ x;
M2fun = @@(x) M2 \ x;
@end group
@end example

@sc{Example 1:} simplest usage of @code{gmres}

@example
x = gmres (A, b, [], [], n)
@end example

@sc{Example 2:} @code{gmres} with a function which computes
@code{@var{A} * @var{x}}

@example
x = gmres (Afun, b, [], [], n)
@end example

@sc{Example 3:} usage of @code{gmres} with the restart

@example
x = gmres (A, b, restart);
@end example

@sc{Example 4:} @code{gmres} with a preconditioner matrix @var{M}
with and without restart

@example
@group
x = gmres (A, b, [], 1e-06, n, M)
x = gmres (A, b, restart, 1e-06, n, M)
@end group
@end example

@sc{Example 5:} @code{gmres} with a function as preconditioner

@example
x = gmres (Afun, b, [], 1e-6, n, Mfun)
@end example

@sc{Example 6:} @code{gmres} with preconditioner matrices @var{M1}
and @var{M2}

@example
x = gmres (A, b, [], 1e-6, n, M1, M2)
@end example

@sc{Example 7:} @code{gmres} with functions as preconditioners

@example
x = gmres (Afun, b, 1e-6, n, M1fun, M2fun)
@end example

@sc{Example 8:} @code{gmres} with as input a function requiring an argument

@example
@group
  function y = Ap (A, x, p) # compute A^p * x
     y = x;
     for i = 1:p
       y = A * y;
     endfor
  endfunction
Apfun = @@(x, p) Ap (A, x, p);
x = gmres (Apfun, b, [], [], [], [], [], [], 2);
@end group
@end example

@sc{Example 9:} explicit example to show that @code{gmres} uses a
left preconditioner

@example
@group
[M1, M2] = ilu (A + 0.1 * eye (n)); # factorization of A perturbed
M = M1 * M2;

## reference solution computed by gmres after two iterations
[x_ref, fl] = gmres (A, b, [], [], 1, M)

## left preconditioning
[x, fl] = gmres (M \ A, M \ b, [], [], 1)
x # compare x and x_ref

@end group
@end example

References:

@enumerate

@item @nospell{Y. Saad}, @cite{Iterative Methods for Sparse Linear
Systems}, Second edition, 2003, SIAM

@end enumerate
@xseealso{bicg, bicgstab, cgs, pcg, pcr, qmr, tfqmr}
@end deftypefn
gplot
@c gplot scripts/sparse/gplot.m
@deftypefn  {} {} gplot (@var{A}, @var{xy})
@deftypefnx {} {} gplot (@var{A}, @var{xy}, @var{line_style})
@deftypefnx {} {[@var{x}, @var{y}] =} gplot (@var{A}, @var{xy})
Plot a graph defined by @var{A} and @var{xy} in the graph theory sense.

@var{A} is the adjacency matrix of the array to be plotted and @var{xy} is
an @var{n}-by-2 matrix containing the coordinates of the nodes of the graph.

The optional parameter @var{line_style} defines the output style for the
plot.  Called with no output arguments the graph is plotted directly.
Otherwise, return the coordinates of the plot in @var{x} and @var{y}.
@xseealso{treeplot, etreeplot, spy}
@end deftypefn
ichol
@c ichol scripts/sparse/ichol.m
@deftypefn  {} {@var{L} =} ichol (@var{A})
@deftypefnx {} {@var{L} =} ichol (@var{A}, @var{opts})

Compute the incomplete Cholesky factorization of the sparse square matrix
@var{A}.

By default, @code{ichol} uses only the lower triangle of @var{A} and
produces a lower triangular factor @var{L} such that @tcode{L*L'}
approximates @var{A}.

The factor given by this routine may be useful as a preconditioner for a
system of linear equations being solved by iterative methods such as
PCG (Preconditioned Conjugate Gradient).

The factorization may be modified by passing options in a structure
@var{opts}.  The option name is a field of the structure and the setting
is the value of field.  Names and specifiers are case sensitive.

@table @asis
@item type
Type of factorization.

@table @asis
@item @qcode{"nofill"} (default)
Incomplete Cholesky factorization with no fill-in (@nospell{IC(0)}).

@item @qcode{"ict"}
Incomplete Cholesky factorization with threshold dropping (@nospell{ICT}).
@end table

@item diagcomp
A non-negative scalar @var{alpha} for incomplete Cholesky factorization of
@code{@var{A} + @var{alpha} * diag (diag (@var{A}))} instead of @var{A}.
This can be useful when @var{A} is not positive definite.  The default value
is 0.

@item droptol
A non-negative scalar specifying the drop tolerance for factorization if
performing @nospell{ICT}@.  The default value is 0 which produces the
complete Cholesky factorization.

Non-diagonal entries of @var{L} are set to 0 unless

@code{abs (@var{L}(i,j)) >= droptol * norm (@var{A}(j:end, j), 1)}.

@item michol
Modified incomplete Cholesky factorization:

@table @asis
@item @qcode{"off"} (default)
Row and column sums are not necessarily preserved.

@item @qcode{"on"}
The diagonal of @var{L} is modified so that row (and column) sums are
preserved even when elements have been dropped during the factorization.
The relationship preserved is: @code{@var{A} * e = @var{L} * @var{L}' * e},
where e is a vector of ones.
@end table

@item shape

@table @asis
@item @qcode{"lower"} (default)
Use only the lower triangle of @var{A} and return a lower triangular factor
@var{L} such that @tcode{L*L'} approximates @var{A}.

@item @qcode{"upper"}
Use only the upper triangle of @var{A} and return an upper triangular factor
@var{U} such that @code{U'*U} approximates @var{A}.
@end table
@end table

EXAMPLES

The following problem demonstrates how to factorize a sample symmetric
positive definite matrix with the full Cholesky decomposition and with the
incomplete one.

@example
@group
A = [ 0.37, -0.05,  -0.05,  -0.07;
     -0.05,  0.116,  0.0,   -0.05;
     -0.05,  0.0,    0.116, -0.05;
     -0.07, -0.05,  -0.05,   0.202];
A = sparse (A);
nnz (tril (A))
ans =  9
L = chol (A, "lower");
nnz (L)
ans =  10
norm (A - L * L', "fro") / norm (A, "fro")
ans =  1.1993e-16
opts.type = "nofill";
L = ichol (A, opts);
nnz (L)
ans =  9
norm (A - L * L', "fro") / norm (A, "fro")
ans =  0.019736
@end group
@end example

Another example for decomposition is a finite difference matrix used to
solve a boundary value problem on the unit square.

@example
@group
nx = 400; ny = 200;
hx = 1 / (nx + 1); hy = 1 / (ny + 1);
Dxx = spdiags ([ones(nx, 1), -2*ones(nx, 1), ones(nx, 1)],
               [-1 0 1 ], nx, nx) / (hx ^ 2);
Dyy = spdiags ([ones(ny, 1), -2*ones(ny, 1), ones(ny, 1)],
               [-1 0 1 ], ny, ny) / (hy ^ 2);
A = -kron (Dxx, speye (ny)) - kron (speye (nx), Dyy);
nnz (tril (A))
ans =  239400
opts.type = "nofill";
L = ichol (A, opts);
nnz (tril (A))
ans =  239400
norm (A - L * L', "fro") / norm (A, "fro")
ans =  0.062327
@end group
@end example

References for implemented algorithms:

[1] @nospell{Y. Saad}. "Preconditioning Techniques." @cite{Iterative
Methods for Sparse Linear Systems}, @nospell{PWS} Publishing Company, 1996.

[2] @nospell{M. Jones, P. Plassmann}: @cite{An Improved Incomplete
Cholesky Factorization}, 1992.
@xseealso{chol, ilu, pcg}
@end deftypefn
ilu
@c ilu scripts/sparse/ilu.m
@deftypefn  {} {} ilu (@var{A})
@deftypefnx {} {} ilu (@var{A}, @var{opts})
@deftypefnx {} {[@var{L}, @var{U}] =} ilu (@dots{})
@deftypefnx {} {[@var{L}, @var{U}, @var{P}] =} ilu (@dots{})

Compute the incomplete LU factorization of the sparse square matrix @var{A}.

@code{ilu} returns a unit lower triangular matrix @var{L}, an upper
triangular matrix @var{U}, and optionally a permutation matrix @var{P}, such
that @code{@var{L}*@var{U}} approximates @code{@var{P}*@var{A}}.

The factors given by this routine may be useful as preconditioners for a
system of linear equations being solved by iterative methods such as BICG
(BiConjugate Gradients) or GMRES (Generalized Minimum Residual Method).

The factorization may be modified by passing options in a structure
@var{opts}.  The option name is a field of the structure and the setting
is the value of field.  Names and specifiers are case sensitive.

@table @code
@item type
Type of factorization.

@table @asis
@item @qcode{"nofill"} (default)
ILU factorization with no fill-in (ILU(0)).

Additional supported options: @code{milu}.

@item @qcode{"crout"}
Crout version of ILU factorization (@nospell{ILUC}).

Additional supported options: @code{milu}, @code{droptol}.

@item @qcode{"ilutp"}
ILU factorization with threshold and pivoting.

Additional supported options: @code{milu}, @code{droptol}, @code{udiag},
@code{thresh}.
@end table

@item droptol
A non-negative scalar specifying the drop tolerance for factorization.  The
default value is 0 which produces the complete LU factorization.

Non-diagonal entries of @var{U} are set to 0 unless

@code{abs (@var{U}(i,j)) >= droptol * norm (@var{A}(:,j))}.

Non-diagonal entries of @var{L} are set to 0 unless

@code{abs (@var{L}(i,j)) >= droptol * norm (@var{A}(:,j))/@var{U}(j,j)}.

@item milu
Modified incomplete LU factorization:

@table @asis
@item @qcode{"row"}
Row-sum modified incomplete LU factorization.
The factorization preserves row sums:
@code{@var{A} * e = @var{L} * @var{U} * e}, where e is a vector of ones.

@item @qcode{"col"}
Column-sum modified incomplete LU factorization.
The factorization preserves column sums:
@code{e' * @var{A} = e' * @var{L} * @var{U}}.

@item @qcode{"off"} (default)
Row and column sums are not necessarily preserved.
@end table

@item udiag
If true, any zeros on the diagonal of the upper triangular factor are
replaced by the local drop tolerance
@code{droptol * norm (@var{A}(:,j))/@var{U}(j,j)}.  The default is false.

@item thresh
Pivot threshold for factorization.  It can range between 0 (diagonal
pivoting) and 1 (default), where the maximum magnitude entry in the column
is chosen to be the pivot.
@end table

If @code{ilu} is called with just one output, the returned matrix is
@code{@var{L} + @var{U} - speye (size (@var{A}))}, where @var{L} is unit
lower triangular and @var{U} is upper triangular.

With two outputs, @code{ilu} returns a unit lower triangular matrix @var{L}
and an upper triangular matrix @var{U}.  For @var{opts}.type ==
@qcode{"ilutp"}, one of the factors is permuted based on the value of
@var{opts}.milu.  When @var{opts}.milu == @qcode{"row"}, @var{U} is a
column permuted upper triangular factor.  Otherwise, @var{L} is a
row-permuted unit lower triangular factor.

If there are three named outputs and @var{opts}.milu != @qcode{"row"},
@var{P} is returned such that @var{L} and @var{U} are incomplete factors
of @code{@var{P}*@var{A}}.  When @var{opts}.milu == @qcode{"row"}, @var{P}
is returned such that @var{L} and @var{U} are incomplete factors of
@code{@var{A}*@var{P}}.

EXAMPLES

@example
@group
A = gallery ("neumann", 1600) + speye (1600);
opts.type = "nofill";
nnz (A)
ans = 7840

nnz (lu (A))
ans = 126478

nnz (ilu (A, opts))
ans = 7840
@end group
@end example

This shows that @var{A} has 7,840 nonzeros, the complete LU factorization
has 126,478 nonzeros, and the incomplete LU factorization, with 0 level of
fill-in, has 7,840 nonzeros, the same amount as @var{A}.  Taken from:
@url{https://www.mathworks.com/help/matlab/ref/ilu.html}

@example
@group
A = gallery ("wathen", 10, 10);
b = sum (A, 2);
tol = 1e-8;
maxit = 50;
opts.type = "crout";
opts.droptol = 1e-4;
[L, U] = ilu (A, opts);
x = bicg (A, b, tol, maxit, L, U);
norm (A * x - b, inf)
@end group
@end example

This example uses ILU as preconditioner for a random FEM-Matrix, which has a
large condition number.  Without @var{L} and @var{U} BICG would not
converge.

@xseealso{lu, ichol, bicg, gmres}
@end deftypefn
nonzeros
@c nonzeros scripts/sparse/nonzeros.m
@deftypefn {} {@var{v} =} nonzeros (@var{A})
Return a column vector of the nonzero values of the matrix @var{A}.
@xseealso{find, nnz}
@end deftypefn
pcg
@c pcg scripts/sparse/pcg.m
@deftypefn  {} {@var{x} =} pcg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{m1}, @var{m2}, @var{x0}, @dots{})
@deftypefnx {} {@var{x} =} pcg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M}, [], @var{x0}, @dots{})
@deftypefnx {} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}, @var{eigest}] =} pcg (@var{A}, @var{b}, @dots{})

Solve the linear system of equations @w{@code{@var{A} * @var{x} = @var{b}}}
by means of the Preconditioned Conjugate Gradient iterative method.

The input arguments are:

@itemize
@item @var{A} is the matrix of the linear system and it must be square.
@var{A} can be passed as a matrix, function handle, or inline function
@code{Afun} such that @code{Afun(x) = A * x}.  Additional parameters to
@code{Afun} may be passed after @var{x0}.

@var{A} has to be Hermitian and Positive Definite (@nospell{HPD})@.  If
@code{pcg} detects @var{A} not to be positive definite, a warning is printed
and the @var{flag} output is set.

@item
@var{b} is the right-hand side vector.

@item
@var{tol} is the required relative tolerance for the residual error,
@w{@code{@var{b} - @var{A} * @var{x}}}.  The iteration stops if
@w{@code{norm (@var{b} - @var{A} * @var{x})} @leq{}
@w{@code{@var{tol} * norm (@var{b})}}}.
If @var{tol} is omitted or empty, then a tolerance of 1e-6 is used.

@item
@var{maxit} is the maximum allowed number of iterations; if @var{maxit}
is omitted or empty then a value of 20 is used.

@item
@var{m} is a @nospell{HPD} preconditioning matrix.  For any decomposition
@code{@var{m} = @var{p1} * @var{p2}} such that
@w{@code{inv (@var{p1}) * @var{A} * inv (@var{p2})}} is @nospell{HPD}, the
conjugate gradient method is formally applied to the linear system
@w{@code{inv (@var{p1}) * @var{A} * inv (@var{p2}) * @var{y} = inv
(@var{p1}) * @var{b}}},
with @code{@var{x} = inv (@var{p2}) * @var{y}} (split preconditioning).
In practice, at each iteration of the conjugate gradient method a
linear system with matrix @var{m} is solved with @code{mldivide}.
If a particular factorization
@code{@var{m} = @var{m1} * @var{m2}} is available (for instance, an
incomplete Cholesky factorization of @var{a}), the two matrices
@var{m1} and @var{m2} can be passed and the relative linear systems
are solved with the @code{mldivide} operator.
Note that a proper choice of the preconditioner may dramatically improve
the overall performance of the method.  Instead of matrices @var{m1} and
@var{m2}, the user may pass two functions which return the results of
applying the inverse of @var{m1} and @var{m2} to a vector.
If @var{m1} is omitted or empty @code{[]}, then no preconditioning
is applied.  If no factorization of @var{m} is available, @var{m2}
can be omitted or left [], and the input variable @var{m1} can be
used to pass the preconditioner @var{m}.

@item
@var{x0} is the initial guess.  If @var{x0} is omitted or empty then the
function sets @var{x0} to a zero vector by default.
@end itemize

The arguments which follow @var{x0} are treated as parameters, and passed in
an appropriate manner to any of the functions (@var{A} or @var{m1} or
@var{m2}) that have been given to @code{pcg}.
See the examples below for further details.

The output arguments are:

@itemize
@item
@var{x} is the computed approximation to the solution of
@w{@code{@var{A} * @var{x} = @var{b}}}.  If the algorithm did not converge,
then @var{x} is the iteration which has the minimum residual.

@item
@var{flag} reports on the convergence:

@itemize
@item 0: The algorithm converged to within the prescribed tolerance.

@item 1: The algorithm did not converge and it reached the maximum
number of iterations.

@item 2: The preconditioner matrix is singular.

@item 3: The algorithm stagnated, i.e., the absolute value of the
difference between the current iteration @var{x} and the previous is less
than @code{@var{eps} * norm (@var{x},2)}.

@item 4: The algorithm detects that the input (preconditioned) matrix is not
@nospell{HPD}.
@end itemize

@item
@var{relres} is the ratio of the final residual to its initial value,
measured in the Euclidean norm.

@item
@var{iter} indicates the iteration of @var{x} which it was
computed.  Since the output @var{x} corresponds to the minimal
residual solution, the total number of iterations that
the method performed is given by @code{length(resvec) - 1}.

@item
@var{resvec} describes the convergence history of the method.
@code{@var{resvec} (@var{i}, 1)} is the Euclidean norm of the residual, and
@code{@var{resvec} (@var{i}, 2)} is the preconditioned residual
norm, after the
(@var{i}-1)-th iteration, @code{@var{i} = 1, 2, @dots{}, @var{iter}+1}.
The preconditioned residual norm is defined as
@code{@var{r}' * (@var{m} \ @var{r})} where
@code{@var{r} = @var{b} - @var{A} * @var{x}}, see also the
description of @var{m}.  If @var{eigest} is not required, only
@code{@var{resvec} (:, 1)} is returned.

@item
@var{eigest} returns the estimate for the smallest @code{@var{eigest}(1)}
and largest @code{@var{eigest}(2)} eigenvalues of the preconditioned matrix
@w{@code{@var{P} = @var{m} \ @var{A}}}.  In particular, if no
preconditioning is used, the estimates for the extreme eigenvalues of
@var{A} are returned.  @code{@var{eigest}(1)} is an overestimate and
@code{@var{eigest}(2)} is an underestimate, so that
@code{@var{eigest}(2) / @var{eigest}(1)} is a lower bound for
@code{cond (@var{P}, 2)}, which nevertheless in the limit should
theoretically be equal to the actual value of the condition number.
@end itemize


Let us consider a trivial problem with a tridiagonal matrix

@example
@group
n = 10;
A = toeplitz (sparse ([1, 1], [1, 2], [2, 1], 1, n));
b = A * ones (n, 1);
M1 = ichol (A); # in this tridiagonal case it corresponds to chol (A)'
M2 = M1';
M = M1 * M2;
Afun = @@(x) A * x;
Mfun = @@(x) M \ x;
M1fun = @@(x) M1 \ x;
M2fun = @@(x) M2 \ x;
@end group
@end example

@sc{Example 1:} Simplest use of @code{pcg}

@example
x = pcg (A, b)
@end example

@sc{Example 2:} @code{pcg} with a function which computes
@code{@var{A} * @var{x}}

@example
x = pcg (Afun, b)
@end example

@sc{Example 3:} @code{pcg} with a preconditioner matrix @var{M}

@example
x = pcg (A, b, 1e-06, 100, M)
@end example

@sc{Example 4:} @code{pcg} with a function as preconditioner

@example
x = pcg (Afun, b, 1e-6, 100, Mfun)
@end example

@sc{Example 5:} @code{pcg} with preconditioner matrices @var{M1}
and @var{M2}

@example
x = pcg (A, b, 1e-6, 100, M1, M2)
@end example

@sc{Example 6:} @code{pcg} with functions as preconditioners

@example
x = pcg (Afun, b, 1e-6, 100, M1fun, M2fun)
@end example

@sc{Example 7:} @code{pcg} with as input a function requiring an argument

@example
@group
  function y = Ap (A, x, p) # compute A^p * x
     y = x;
     for i = 1:p
       y = A * y;
     endfor
  endfunction
Apfun = @@(x, p) Ap (A, x, p);
x = pcg (Apfun, b, [], [], [], [], [], 2);
@end group
@end example

@sc{Example 8:} explicit example to show that @code{pcg} uses a
split preconditioner

@example
@group
M1 = ichol (A + 0.1 * eye (n)); # factorization of A perturbed
M2 = M1';
M = M1 * M2;

## reference solution computed by pcg after two iterations
[x_ref, fl] = pcg (A, b, [], 2, M)

## split preconditioning
[y, fl] = pcg ((M1 \ A) / M2, M1 \ b, [], 2)
x = M2 \ y # compare x and x_ref

@end group
@end example

References:

@enumerate
@item
C.T. Kelley, @cite{Iterative Methods for Linear and Nonlinear Equations},
SIAM, 1995. (the base PCG algorithm)

@item
@nospell{Y. Saad}, @cite{Iterative Methods for Sparse Linear Systems},
@nospell{PWS} 1996. (condition number estimate from PCG)
Revised version of this book is available online at
@url{https://www-users.cs.umn.edu/~saad/books.html}
@end enumerate

@xseealso{sparse, pcr, gmres, bicg, bicgstab, cgs}
@end deftypefn
pcr
@c pcr scripts/sparse/pcr.m
@deftypefn  {} {@var{x} =} pcr (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{m}, @var{x0}, @dots{})
@deftypefnx {} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} pcr (@dots{})

Solve the linear system of equations @code{@var{A} * @var{x} = @var{b}} by
means of the Preconditioned Conjugate Residuals iterative method.

The input arguments are

@itemize
@item
@var{A} can be either a square (preferably sparse) matrix or a function
handle, inline function or string containing the name of a function which
computes @code{@var{A} * @var{x}}.  In principle @var{A} should be
symmetric and non-singular; if @code{pcr} finds @var{A} to be numerically
singular, you will get a warning message and the @var{flag} output
parameter will be set.

@item
@var{b} is the right hand side vector.

@item
@var{tol} is the required relative tolerance for the residual error,
@code{@var{b} - @var{A} * @var{x}}.  The iteration stops if
@code{norm (@var{b} - @var{A} * @var{x}) <=
@var{tol} * norm (@var{b} - @var{A} * @var{x0})}.
If @var{tol} is empty or is omitted, the function sets
@code{@var{tol} = 1e-6} by default.

@item
@var{maxit} is the maximum allowable number of iterations; if @code{[]} is
supplied for @var{maxit}, or @code{pcr} has less arguments, a default
value equal to 20 is used.

@item
@var{m} is the (left) preconditioning matrix, so that the iteration is
(theoretically) equivalent to solving by
@code{pcr} @code{@var{P} * @var{x} = @var{m} \ @var{b}}, with
@code{@var{P} = @var{m} \ @var{A}}.  Note that a proper choice of the
preconditioner may dramatically improve the overall performance of the
method.  Instead of matrix @var{m}, the user may pass a function which
returns the results of applying the inverse of @var{m} to a vector
(usually this is the preferred way of using the preconditioner).  If
@code{[]} is supplied for @var{m}, or @var{m} is omitted, no
preconditioning is applied.

@item
@var{x0} is the initial guess.  If @var{x0} is empty or omitted, the
function sets @var{x0} to a zero vector by default.
@end itemize

The arguments which follow @var{x0} are treated as parameters, and passed
in a proper way to any of the functions (@var{A} or @var{m}) which are
passed to @code{pcr}.  See the examples below for further details.

The output arguments are

@itemize
@item
@var{x} is the computed approximation to the solution of
@code{@var{A} * @var{x} = @var{b}}.

@item
@var{flag} reports on the convergence.  @code{@var{flag} = 0} means the
solution converged and the tolerance criterion given by @var{tol} is
satisfied.  @code{@var{flag} = 1} means that the @var{maxit} limit for the
iteration count was reached.  @code{@var{flag} = 3} reports a @code{pcr}
breakdown, see [1] for details.

@item
@var{relres} is the ratio of the final residual to its initial value,
measured in the Euclidean norm.

@item
@var{iter} is the actual number of iterations performed.

@item
@var{resvec} describes the convergence history of the method, so that
@code{@var{resvec} (i)} contains the Euclidean norms of the residual after
the (@var{i}-1)-th iteration, @code{@var{i} = 1,2, @dots{}, @var{iter}+1}.
@end itemize

Let us consider a trivial problem with a diagonal matrix (we exploit the
sparsity of A)

@example
@group
n = 10;
A = sparse (diag (1:n));
b = rand (N, 1);
@end group
@end example

@sc{Example 1:} Simplest use of @code{pcr}

@example
x = pcr (A, b)
@end example

@sc{Example 2:} @code{pcr} with a function which computes
@code{@var{A} * @var{x}}.

@example
@group
function y = apply_a (x)
  y = [1:10]' .* x;
endfunction

x = pcr ("apply_a", b)
@end group
@end example

@sc{Example 3:}  Preconditioned iteration, with full diagnostics.  The
preconditioner (quite strange, because even the original matrix
@var{A} is trivial) is defined as a function

@example
@group
function y = apply_m (x)
  k = floor (length (x) - 2);
  y = x;
  y(1:k) = x(1:k) ./ [1:k]';
endfunction

[x, flag, relres, iter, resvec] = ...
                   pcr (A, b, [], [], "apply_m")
semilogy ([1:iter+1], resvec);
@end group
@end example

@sc{Example 4:} Finally, a preconditioner which depends on a
parameter @var{k}.

@example
@group
function y = apply_m (x, varargin)
  k = varargin@{1@};
  y = x;
  y(1:k) = x(1:k) ./ [1:k]';
endfunction

[x, flag, relres, iter, resvec] = ...
                   pcr (A, b, [], [], "apply_m"', [], 3)
@end group
@end example

References:

[1] @nospell{W. Hackbusch}, @cite{Iterative Solution of Large Sparse
Systems of Equations}, section 9.5.4; @nospell{Springer}, 1994

@xseealso{sparse, pcg}
@end deftypefn
qmr
@c qmr scripts/sparse/qmr.m
@deftypefn  {} {@var{x} =} qmr (@var{A}, @var{b}, @var{rtol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0})
@deftypefnx {} {@var{x} =} qmr (@var{A}, @var{b}, @var{rtol}, @var{maxit}, @var{P})
@deftypefnx {} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} qmr (@var{A}, @var{b}, @dots{})
Solve @code{A x = b} using the Quasi-Minimal Residual iterative method
(without look-ahead).

@itemize @minus
@item @var{rtol} is the relative tolerance, if not given or set to [] the
default value 1e-6 is used.

@item @var{maxit} the maximum number of outer iterations, if not given or
set to [] the default value @code{min (20, numel (b))} is used.

@item @var{x0} the initial guess, if not given or set to [] the default
value @code{zeros (size (b))} is used.
@end itemize

@var{A} can be passed as a matrix or as a function handle or inline
function @code{f} such that @code{f(x, "notransp") = A*x} and
@code{f(x, "transp") = A'*x}.

The preconditioner @var{P} is given as @code{P = M1 * M2}.  Both @var{M1}
and @var{M2} can be passed as a matrix or as a function handle or inline
function @code{g} such that @code{g(x, "notransp") = M1 \ x} or
@code{g(x, "notransp") = M2 \ x} and @code{g(x, "transp") = M1' \ x} or
@code{g(x, "transp") = M2' \ x}.

If called with more than one output parameter

@itemize @minus
@item @var{flag} indicates the exit status:

@itemize @minus
@item 0: iteration converged to the within the chosen tolerance

@item 1: the maximum number of iterations was reached before convergence

@item 3: the algorithm reached stagnation
@end itemize

(the value 2 is unused but skipped for compatibility).

@item @var{relres} is the final value of the relative residual.

@item @var{iter} is the number of iterations performed.

@item @var{resvec} is a vector containing the residual norms at each
      iteration.
@end itemize

References:

@enumerate
@item
@nospell{R. Freund and N. Nachtigal}, @cite{QMR: a quasi-minimal residual
method for non-Hermitian linear systems}, @nospell{Numerische Mathematik},
1991, 60, pp. 315--339.

@item
@nospell{ R. Barrett, M. Berry, T. Chan, J. Demmel, J. Donato, J. Dongarra},
@nospell{ V. Eijkhour, R. Pozo, C. Romine, and H. van der Vorst},
@cite{Templates for the solution of linear systems: Building blocks
for iterative methods}, SIAM, 2nd ed., 1994.
@end enumerate

@xseealso{bicg, bicgstab, cgs, gmres, pcg}
@end deftypefn
spaugment
@c spaugment scripts/sparse/spaugment.m
@deftypefn {} {@var{s} =} spaugment (@var{A}, @var{c})
Create the augmented matrix of @var{A}.

This is given by

@example
@group
[@var{c} * eye(@var{m}, @var{m}), @var{A};
            @var{A}', zeros(@var{n}, @var{n})]
@end group
@end example

@noindent
This is related to the least squares solution of
@code{@var{A} \ @var{b}}, by

@example
@group
@var{s} * [ @var{r} / @var{c}; x] = [ @var{b}, zeros(@var{n}, columns(@var{b})) ]
@end group
@end example

@noindent
where @var{r} is the residual error

@example
@var{r} = @var{b} - @var{A} * @var{x}
@end example

As the matrix @var{s} is symmetric indefinite it can be factorized with
@code{lu}, and the minimum norm solution can therefore be found without the
need for a @code{qr} factorization.  As the residual error will be
@code{zeros (@var{m}, @var{m})} for underdetermined problems, and example
can be

@example
@group
m = 11; n = 10; mn = max (m, n);
A = spdiags ([ones(mn,1), 10*ones(mn,1), -ones(mn,1)],
             [-1, 0, 1], m, n);
x0 = A \ ones (m,1);
s = spaugment (A);
[L, U, P, Q] = lu (s);
x1 = Q * (U \ (L \ (P  * [ones(m,1); zeros(n,1)])));
x1 = x1(end - n + 1 : end);
@end group
@end example

To find the solution of an overdetermined problem needs an estimate of the
residual error @var{r} and so it is more complex to formulate a minimum norm
solution using the @code{spaugment} function.

In general the left division operator is more stable and faster than using
the @code{spaugment} function.
@xseealso{mldivide}
@end deftypefn
spconvert
@c spconvert scripts/sparse/spconvert.m
@deftypefn {} {@var{x} =} spconvert (@var{m})
Convert a simple sparse matrix format easily generated by other programs
into Octave's internal sparse format.

The input @var{m} is either a 3 or 4 column real matrix, containing the
row, column, real, and imaginary parts of the elements of the sparse
matrix.  An element with a zero real and imaginary part can be used to
force a particular matrix size.
@xseealso{sparse}
@end deftypefn
spdiags
@c spdiags scripts/sparse/spdiags.m
@deftypefn  {} {@var{B} =} spdiags (@var{A})
@deftypefnx {} {[@var{B}, @var{d}] =} spdiags (@var{A})
@deftypefnx {} {@var{B} =} spdiags (@var{A}, @var{d})
@deftypefnx {} {@var{A} =} spdiags (@var{v}, @var{d}, @var{A})
@deftypefnx {} {@var{A} =} spdiags (@var{v}, @var{d}, @var{m}, @var{n})
A generalization of the function @code{diag}.

Called with a single input argument, the nonzero diagonals @var{d} of
@var{A} are extracted.

With two arguments the diagonals to extract are given by the vector @var{d}.

The other two forms of @code{spdiags} modify the input matrix by replacing
the diagonals.  They use the columns of @var{v} to replace the diagonals
represented by the vector @var{d}.  If the sparse matrix @var{A} is
defined then the diagonals of this matrix are replaced.  Otherwise a
matrix of @var{m} by @var{n} is created with the diagonals given by the
columns of @var{v}.

Negative values of @var{d} represent diagonals below the main diagonal, and
positive values of @var{d} diagonals above the main diagonal.

For example:

@example
@group
spdiags (reshape (1:12, 4, 3), [-1 0 1], 5, 4)
   @result{} 5 10  0  0
      1  6 11  0
      0  2  7 12
      0  0  3  8
      0  0  0  4
@end group
@end example

@xseealso{diag}
@end deftypefn
speye
@c speye scripts/sparse/speye.m
@deftypefn  {} {@var{s} =} speye (@var{m}, @var{n})
@deftypefnx {} {@var{s} =} speye (@var{m})
@deftypefnx {} {@var{s} =} speye (@var{sz})
Return a sparse identity matrix of size @var{m}x@var{n}.

The implementation is significantly more efficient than
@code{sparse (eye (@var{m}))} as the full matrix is not constructed.

Called with a single argument a square matrix of size
@var{m}-by-@var{m} is created.  If called with a single vector argument
@var{sz}, this argument is taken to be the size of the matrix to create.
@xseealso{sparse, spdiags, eye}
@end deftypefn
spfun
@c spfun scripts/sparse/spfun.m
@deftypefn {} {@var{y} =} spfun (@var{f}, @var{S})
Compute @code{f(@var{S})} for the nonzero values of @var{S}.

This results in a sparse matrix with the same structure as @var{S}.  The
function @var{f} can be passed as a string, a function handle, or an
inline function.
@xseealso{arrayfun, cellfun, structfun}
@end deftypefn
spones
@c spones scripts/sparse/spones.m
@deftypefn {} {@var{r} =} spones (@var{S})
Replace the nonzero entries of @var{S} with ones.

This creates a sparse matrix with the same structure as @var{S}.
@xseealso{sparse, sprand, sprandn, sprandsym, spfun, spy}
@end deftypefn
sprand
@c sprand scripts/sparse/sprand.m
@deftypefn  {} {} sprand (@var{m}, @var{n}, @var{d})
@deftypefnx {} {} sprand (@var{m}, @var{n}, @var{d}, @var{rc})
@deftypefnx {} {} sprand (@var{s})
Generate a sparse matrix with uniformly distributed random values.

The size of the matrix is @var{m}x@var{n} with a density of values @var{d}.
@var{d} must be between 0 and 1.  Values will be uniformly distributed on
the interval (0, 1).

If called with a single matrix argument, a sparse matrix is generated with
random values wherever the matrix @var{s} is nonzero.

If called with a scalar fourth argument @var{rc}, a random sparse matrix
with reciprocal condition number @var{rc} is generated.  If @var{rc} is
a vector, then it specifies the first singular values of the generated
matrix (@code{length (@var{rc}) <= min (@var{m}, @var{n})}).

@xseealso{sprandn, sprandsym, rand}
@end deftypefn
sprandn
@c sprandn scripts/sparse/sprandn.m
@deftypefn  {} {} sprandn (@var{m}, @var{n}, @var{d})
@deftypefnx {} {} sprandn (@var{m}, @var{n}, @var{d}, @var{rc})
@deftypefnx {} {} sprandn (@var{s})
Generate a sparse matrix with normally distributed random values.

The size of the matrix is @var{m}x@var{n} with a density of values @var{d}.
@var{d} must be between 0 and 1.  Values will be normally distributed with a
mean of 0 and a variance of 1.

If called with a single matrix argument, a sparse matrix is generated with
random values wherever the matrix @var{s} is nonzero.

If called with a scalar fourth argument @var{rc}, a random sparse matrix
with reciprocal condition number @var{rc} is generated.  If @var{rc} is
a vector, then it specifies the first singular values of the generated
matrix (@code{length (@var{rc}) <= min (@var{m}, @var{n})}).

@xseealso{sprand, sprandsym, randn}
@end deftypefn
sprandsym
@c sprandsym scripts/sparse/sprandsym.m
@deftypefn  {} {} sprandsym (@var{n}, @var{d})
@deftypefnx {} {} sprandsym (@var{s})
Generate a symmetric random sparse matrix.

The size of the matrix will be @var{n}x@var{n}, with a density of values
given by @var{d}.  @var{d} must be between 0 and 1 inclusive.  Values will
be normally distributed with a mean of zero and a variance of 1.

If called with a single matrix argument, a random sparse matrix is generated
wherever the matrix @var{s} is nonzero in its lower triangular part.
@xseealso{sprand, sprandn, spones, sparse}
@end deftypefn
spstats
@c spstats scripts/sparse/spstats.m
@deftypefn  {} {[@var{count}, @var{mean}, @var{var}] =} spstats (@var{S})
@deftypefnx {} {[@var{count}, @var{mean}, @var{var}] =} spstats (@var{S}, @var{j})
Return the stats for the nonzero elements of the sparse matrix @var{S}.

@var{count} is the number of nonzeros in each column, @var{mean} is the mean
of the nonzeros in each column, and @var{var} is the variance of the
nonzeros in each column.

Called with two input arguments, if @var{S} is the data and @var{j} is the
bin number for the data, compute the stats for each bin.  In this case,
bins can contain data values of zero, whereas with
@code{spstats (@var{S})} the zeros may disappear.
@end deftypefn
spy
@c spy scripts/sparse/spy.m
@deftypefn  {} {} spy (@var{x})
@deftypefnx {} {} spy (@dots{}, @var{markersize})
@deftypefnx {} {} spy (@dots{}, @var{line_spec})
Plot the sparsity pattern of the sparse matrix @var{x}.

If the argument @var{markersize} is given as a scalar value, it is used to
determine the point size in the plot.

If the string @var{line_spec} is given it is passed to @code{plot} and
determines the appearance of the plot.
@xseealso{plot, gplot}
@end deftypefn
svds
@c svds scripts/sparse/svds.m
@deftypefn  {} {@var{s} =} svds (@var{A})
@deftypefnx {} {@var{s} =} svds (@var{A}, @var{k})
@deftypefnx {} {@var{s} =} svds (@var{A}, @var{k}, @var{sigma})
@deftypefnx {} {@var{s} =} svds (@var{A}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {} {[@var{u}, @var{s}, @var{v}] =} svds (@dots{})
@deftypefnx {} {[@var{u}, @var{s}, @var{v}, @var{flag}] =} svds (@dots{})

Find a few singular values of the matrix @var{A}.

The singular values are calculated using

@example
@group
[@var{m}, @var{n}] = size (@var{A});
@var{s} = eigs ([sparse(@var{m}, @var{m}), @var{A};
                     @var{A}', sparse(@var{n}, @var{n})])
@end group
@end example

The eigenvalues returned by @code{eigs} correspond to the singular values
of @var{A}.  The number of singular values to calculate is given by @var{k}
and defaults to 6.

The argument @var{sigma} specifies which singular values to find.  When
@var{sigma} is the string @qcode{'L'}, the default, the largest singular
values of @var{A} are found.  Otherwise, @var{sigma} must be a real scalar
and the singular values closest to @var{sigma} are found.  As a corollary,
@code{@var{sigma} = 0} finds the smallest singular values.  Note that for
relatively small values of @var{sigma}, there is a chance that the
requested number of singular values will not be found.  In that case
@var{sigma} should be increased.

@var{opts} is a structure defining options that @code{svds} will pass
to @code{eigs}.  The possible fields of this structure are documented in
@code{eigs}.  By default, @code{svds} sets the following three fields:

@table @code
@item tol
The required convergence tolerance for the singular values.  The default
value is 1e-10.  @code{eigs} is passed @code{@var{tol} / sqrt(2)}.

@item maxit
The maximum number of iterations.  The default is 300.

@item disp
The level of diagnostic printout (0|1|2).  If @code{disp} is 0 then
diagnostics are disabled.  The default value is 0.
@end table

If more than one output is requested then @code{svds} will return an
approximation of the singular value decomposition of @var{A}

@example
@var{A}_approx = @var{u}*@var{s}*@var{v}'
@end example

@noindent
where @var{A}_approx is a matrix of size @var{A} but only rank @var{k}.

@var{flag} returns 0 if the algorithm has successfully converged, and 1
otherwise.  The test for convergence is

@example
@group
norm (@var{A}*@var{v} - @var{u}*@var{s}, 1) <= @var{tol} * norm (@var{A}, 1)
@end group
@end example

@code{svds} is best for finding only a few singular values from a large
sparse matrix.  Otherwise, @code{svd (full (@var{A}))} will likely be more
efficient.
@xseealso{svd, eigs}
@end deftypefn
tfqmr
@c tfqmr scripts/sparse/tfqmr.m
@deftypefn  {} {@var{x} =} tfqmr (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0}, @dots{})
@deftypefnx {} {@var{x} =} tfqmr (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M}, [], @var{x0}, @dots{})
@deftypefnx {} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} tfqmr (@var{A}, @var{b}, @dots{})
Solve @code{A x = b} using the Transpose-Tree qmr method, based on the cgs.

The input parameters are:

@itemize @minus

@item @var{A} is the matrix of the linear system and it must be square.
@var{A} can be passed as a matrix, function handle, or inline
function @code{Afun} such that @code{Afun(x) = A * x}.  Additional
parameters to @code{Afun} are passed after @var{x0}.

@item @var{b} is the right hand side vector.  It must be a column vector
with the same number of rows as @var{A}.

@item @var{tol} is the relative tolerance, if not given or set to [] the
default value 1e-6 is used.

@item @var{maxit} the maximum number of outer iterations, if not given or
set to [] the default value @code{min (20, numel (b))} is used.  To be
compatible, since the method as different behaviors in the iteration
number is odd or even, is considered as iteration in @code{tfqmr} the
entire odd-even cycle.  That is, to make an entire iteration, the algorithm
performs two sub-iterations: the odd one and the even one.

@item @var{M1}, @var{M2} are the preconditioners.  The preconditioner
@var{M} is given as @code{M = M1 * M2}.
Both @var{M1} and @var{M2} can be passed as a matrix or as a function
handle or inline function @code{g} such that @code{g(x) = M1 \ x} or
@code{g(x) = M2 \ x}.
The technique used is the right-preconditioning, i.e., it is solved
@code{A*inv(M)*y = b} and then @code{x = inv(M)*y}, instead of
@code{A x = b}.

@item @var{x0} the initial guess, if not given or set to [] the default
value @code{zeros (size (b))} is used.

@end itemize

The arguments which follow @var{x0} are treated as parameters, and passed in
a proper way to any of the functions (@var{A} or @var{M}) which are passed
to @code{tfqmr}.

The output parameters are:

@itemize @minus

@item @var{x} is the approximation computed.  If the method doesn't
converge then it is the iterated with the minimum residual.

@item @var{flag} indicates the exit status:

@itemize @minus
@item 0: iteration converged to the within the chosen tolerance

@item 1: the maximum number of iterations was reached before convergence

@item 2: the preconditioner matrix is singular

@item 3: the algorithm reached stagnation

@item 4: the algorithm can't continue due to a division by zero
@end itemize

@item @var{relres} is the relative residual obtained as
@code{(@var{A}*@var{x}-@var{b}) / @code{norm (@var{b})}}.

@item @var{iter} is the iteration which @var{x} is
computed.

@item @var{resvec} is a vector containing the residual at each iteration
(including @code{norm (b - A x0)}).
Doing @code{length (@var{resvec}) - 1} is possible to see the
total number of iterations performed.

@end itemize

Let us consider a trivial problem with a tridiagonal matrix

@example
@group
n = 20;
A = toeplitz (sparse ([1, 1], [1, 2], [2, 1] * n ^ 2, 1, n))  + ...
    toeplitz (sparse (1, 2, -1, 1, n) * n / 2, ...
    sparse (1, 2, 1, 1, n) * n / 2);
b = A * ones (n, 1);
restart = 5;
[M1, M2] = ilu (A); # in this tridiag case it corresponds to chol (A)'
M = M1 * M2;
Afun = @@(x) A * x;
Mfun = @@(x) M \ x;
M1fun = @@(x) M1 \ x;
M2fun = @@(x) M2 \ x;
@end group
@end example

@sc{Example 1:} simplest usage of @code{tfqmr}

@example
x = tfqmr (A, b, [], n)
@end example

@sc{Example 2:} @code{tfqmr} with a function which computes
@code{@var{A} * @var{x}}

@example
x = tfqmr (Afun, b, [], n)
@end example

@sc{Example 3:} @code{tfqmr} with a preconditioner matrix @var{M}

@example
x = tfqmr (A, b, [], 1e-06, n, M)
@end example

@sc{Example 4:} @code{tfqmr} with a function as preconditioner

@example
x = tfqmr (Afun, b, 1e-6, n, Mfun)
@end example

@sc{Example 5:} @code{tfqmr} with preconditioner matrices @var{M1}
and @var{M2}

@example
x = tfqmr (A, b, [], 1e-6, n, M1, M2)
@end example

@sc{Example 6:} @code{tfmqr} with functions as preconditioners

@example
x = tfqmr (Afun, b, 1e-6, n, M1fun, M2fun)
@end example

@sc{Example 7:} @code{tfqmr} with as input a function requiring an argument

@example
@group
function y = Ap (A, x, z) # compute A^z * x
   y = x;
   for i = 1:z
     y = A * y;
   endfor
 endfunction
Apfun = @@(x, string, p) Ap (A, x, string, p);
x = tfqmr (Apfun, b, [], [], [], [], [], 2);
@end group
@end example

@sc{Example 8:} explicit example to show that @code{tfqmr} uses a
right preconditioner

@example
@group
[M1, M2] = ilu (A + 0.3 * eye (n)); # factorization of A perturbed
M = M1 * M2;

## reference solution computed by tfqmr after one iteration
[x_ref, fl] = tfqmr (A, b, [], 1, M)

## right preconditioning
[y, fl] = tfqmr (A / M, b, [], 1)
x = M \ y # compare x and x_ref

@end group
@end example

References:

@enumerate

@item @nospell{Y. Saad}, @cite{Iterative Methods for Sparse Linear Systems},
Second edition, 2003, SIAM

@end enumerate

@xseealso{bicg, bicgstab, cgs, gmres, pcg, qmr, pcr}

@end deftypefn
treelayout
@c treelayout scripts/sparse/treelayout.m
@deftypefn  {} {} treelayout (@var{tree})
@deftypefnx {} {} treelayout (@var{tree}, @var{permutation})
treelayout lays out a tree or a forest.

The first argument @var{tree} is a vector of predecessors.

The parameter @var{permutation} is an optional postorder permutation.

The complexity of the algorithm is O(n) in terms of time and memory
requirements.
@xseealso{etreeplot, gplot, treeplot}
@end deftypefn
treeplot
@c treeplot scripts/sparse/treeplot.m
@deftypefn  {} {} treeplot (@var{tree})
@deftypefnx {} {} treeplot (@var{tree}, @var{node_style}, @var{edge_style})
Produce a graph of tree or forest.

The first argument is vector of predecessors.

The optional parameters @var{node_style} and @var{edge_style} define the
output plot style.

The complexity of the algorithm is O(n) in terms of is time and memory
requirements.
@xseealso{etreeplot, gplot}
@end deftypefn
beta
@c beta scripts/specfun/beta.m
@deftypefn {} {} beta (@var{a}, @var{b})
Compute the Beta function for real inputs @var{a} and @var{b}.

The Beta function definition is
@tex
$$
 B (a, b) = {\Gamma (a) \Gamma (b) \over \Gamma (a + b)}.
$$
@end tex
@ifnottex

@example
beta (a, b) = gamma (a) * gamma (b) / gamma (a + b).
@end example

@end ifnottex

The Beta function can grow quite large and it is often more useful to work
with the logarithm of the output rather than the function directly.
@xref{XREFbetaln,,betaln}, for computing the logarithm of the Beta function
in an efficient manner.
@xseealso{betaln, betainc, betaincinv}
@end deftypefn
betainc
@c betainc scripts/specfun/betainc.m
@deftypefn  {} {} betainc (@var{x}, @var{a}, @var{b})
@deftypefnx {} {} betainc (@var{x}, @var{a}, @var{b}, @var{tail})
Compute the incomplete beta function.

This is defined as
@tex
$$
I_x (a, b) = {1 \over {B(a,b)}} \displaystyle{\int_0^x t^{a-1} (1-t)^{b-1} dt}
$$
@end tex
@ifnottex

@example
@group
               x
              /
             |
I_x (a, b) = | t^(a-1) (1-t)^(b-1) dt
             |
             /
            0
@end group
@end example

@end ifnottex

with real @var{x} in the range [0,1].  The inputs @var{a} and @var{b} must
be real and strictly positive (> 0).  If one of the inputs is not a scalar
then the other inputs must be scalar or of compatible dimensions.

By default, @var{tail} is @qcode{"lower"} and the incomplete beta function
integrated from 0 to @var{x} is computed.  If @var{tail} is @qcode{"upper"}
then the complementary function integrated from @var{x} to 1 is calculated.
The two choices are related by

betainc (@var{x}, @var{a}, @var{b}, @qcode{"upper"}) =
1 - betainc (@var{x}, @var{a}, @var{b}, @qcode{"lower"}).

@code{betainc} uses a more sophisticated algorithm than subtraction to
get numerically accurate results when the @qcode{"lower"} value is small.

Reference: @nospell{A. Cuyt, V. Brevik Petersen, B. Verdonk, H. Waadeland,
W.B. Jones}, @cite{Handbook of Continued Fractions for Special Functions},
ch.@: 18.

@xseealso{beta, betaincinv, betaln}
@end deftypefn
betaincinv
@c betaincinv scripts/specfun/betaincinv.m
@deftypefn  {} {} betaincinv (@var{y}, @var{a}, @var{b})
@deftypefnx {} {} betaincinv (@var{y}, @var{a}, @var{b}, "lower")
@deftypefnx {} {} betaincinv (@var{y}, @var{a}, @var{b}, "upper")
Compute the inverse of the normalized incomplete beta function.

The normalized incomplete beta function is defined as
@tex
$$
 I_x (a, b) = {1 \over {B(a,b)}} \displaystyle{\int_0^x t^{a-1} (1-t)^{b-1} dt}
$$
@end tex
@ifnottex

@example
@group
               x
              /
             |
I_x (a, b) = | t^(a-1) (1-t)^(b-1) dt
             |
             /
            0
@end group
@end example

@end ifnottex

If two inputs are scalar, then @code{betaincinv (@var{y}, @var{a}, @var{b})}
is returned for each of the other inputs.

If two or more inputs are not scalar, the sizes of them must agree, and
@code{betaincinv} is applied element-by-element.

The variable @var{y} must be in the interval [0,1], while @var{a} and
@var{b} must be real and strictly positive.

By default, @var{tail} is @qcode{"lower"} and the inverse of the incomplete
beta function integrated from 0 to @var{x} is computed.  If @var{tail} is
@qcode{"upper"} then the complementary function integrated from @var{x} to 1
is inverted.

The function is computed by standard Newton's method, by solving
@tex
$$
 y - I_x (a, b) = 0
$$
@end tex
@ifnottex

@example
@var{y} - betainc (@var{x}, @var{a}, @var{b}) = 0
@end example

@end ifnottex

@xseealso{betainc, beta, betaln}
@end deftypefn
betaln
@c betaln scripts/specfun/betaln.m
@deftypefn {} {} betaln (@var{a}, @var{b})
Compute the natural logarithm of the Beta function for real inputs @var{a}
and @var{b}.

@code{betaln} is defined as
@tex
$$
 {\rm betaln} (a, b) = \ln (B (a,b)) \equiv \ln ({\Gamma (a) \Gamma (b) \over \Gamma (a + b)}).
$$
@end tex
@ifnottex

@example
betaln (a, b) = log (beta (a, b))
@end example

@end ifnottex
and is calculated in a way to reduce the occurrence of underflow.

The Beta function can grow quite large and it is often more useful to work
with the logarithm of the output rather than the function directly.
@xseealso{beta, betainc, betaincinv, gammaln}
@end deftypefn
cosint
@c cosint scripts/specfun/cosint.m
@deftypefn {} {} cosint (@var{x})
Compute the cosine integral function:
@tex
$$
{\rm Ci} (x) = - \int_x^\infty {{\cos (t)} \over t} dt
$$
@end tex
@ifnottex

@example
@group
            +oo
           /
Ci (x) = - | (cos (t)) / t dt
           /
          x
@end group
@end example

@end ifnottex
An equivalent definition is
@tex
$$
{\rm Ci} (x) = \gamma + \log (x) + \int_0^x {{\cos (t) - 1} \over t} dt
$$
@end tex
@ifnottex

@example
@group
                             x
                            /
                            |  cos (t) - 1
Ci (x) = gamma + log (x) +  | -------------  dt
                            |        t
                            /
                           0
@end group
@end example

@end ifnottex
Reference:

@nospell{M. Abramowitz and I.A. Stegun},
@cite{Handbook of Mathematical Functions}
1964.

@xseealso{sinint, expint, cos}

@end deftypefn
ellipke
@c ellipke scripts/specfun/ellipke.m
@deftypefn  {} {@var{k} =} ellipke (@var{m})
@deftypefnx {} {@var{k} =} ellipke (@var{m}, @var{tol})
@deftypefnx {} {[@var{k}, @var{e}] =} ellipke (@dots{})
Compute complete elliptic integrals of the first K(@var{m}) and second
E(@var{m}) kind.

@var{m} must be a scalar or real array with -Inf @leq{} @var{m} @leq{} 1.

The optional input @var{tol} controls the stopping tolerance of the
algorithm and defaults to @code{eps (class (@var{m}))}.  The tolerance can
be increased to compute a faster, less accurate approximation.

When called with one output only elliptic integrals of the first kind are
returned.

Mathematical Note:

Elliptic integrals of the first kind are defined as

@tex
$$
{\rm K} (m) = \int_0^1 {dt \over \sqrt{(1 - t^2) (1 - m t^2)}}
$$
@end tex
@ifnottex

@example
@group
         1
        /               dt
K (m) = | ------------------------------
        / sqrt ((1 - t^2)*(1 - m*t^2))
       0
@end group
@end example

@end ifnottex

Elliptic integrals of the second kind are defined as

@tex
$$
{\rm E} (m) = \int_0^1 {\sqrt{1 - m t^2} \over \sqrt{1 - t^2}} dt
$$
@end tex
@ifnottex

@example
@group
         1
        /  sqrt (1 - m*t^2)
E (m) = |  ------------------ dt
        /  sqrt (1 - t^2)
       0
@end group
@end example

@end ifnottex

Reference: Milton @nospell{Abramowitz} and Irene A. @nospell{Stegun},
@cite{Handbook of Mathematical Functions}, Chapter 17, Dover, 1965.
@xseealso{ellipj}
@end deftypefn
expint
@c expint scripts/specfun/expint.m
@deftypefn {} {} expint (@var{x})
Compute the exponential integral.

The exponential integral is defined as:

@tex
$$
{\rm E_1} (x) = \int_x^\infty {e^{-t} \over t} dt
$$
@end tex
@ifnottex

@example
@group
           +oo
          /
          | exp (-t)
E_1 (x) = | -------- dt
          |    t
          /
         x
@end group
@end example

@end ifnottex

Note: For compatibility, this function uses the @sc{matlab} definition
of the exponential integral.  Most other sources refer to this particular
value as @math{E_1 (x)}, and the exponential integral as
@tex
$$
{\rm Ei} (x) = - \int_{-x}^\infty {e^{-t} \over t} dt.
$$
@end tex
@ifnottex

@example
@group
            +oo
           /
           | exp (-t)
Ei (x) = - | -------- dt
           |    t
           /
         -x
@end group
@end example

@end ifnottex
The two definitions are related, for positive real values of @var{x}, by
@tex
$
E_1 (-x) = -{\rm Ei} (x) - i\pi.
$
@end tex
@ifnottex
@w{@code{E_1 (-x) = -Ei (x) - i*pi}}.
@end ifnottex

References:

@nospell{M. Abramowitz and I.A. Stegun},
@cite{Handbook of Mathematical Functions}, 1964.

@nospell{N. Bleistein and R.A. Handelsman},
@cite{Asymptotic expansions of integrals}, 1986.

@xseealso{cosint, sinint, exp}
@end deftypefn
factor
@c factor scripts/specfun/factor.m
@deftypefn  {} {@var{pf} =} factor (@var{q})
@deftypefnx {} {[@var{pf}, @var{n}] =} factor (@var{q})
Return the prime factorization of @var{q}.

The prime factorization is defined as @code{prod (@var{pf}) == @var{q}}
where every element of @var{pf} is a prime number.  If @code{@var{q} == 1},
return 1.  The output @var{pf} is of the same numeric class as the input.

With two output arguments, return the unique prime factors @var{pf} and
their multiplicities.  That is,
@code{prod (@var{pf} .^ @var{n}) == @var{q}}.

Implementation Note: The input @var{q} must be less than @code{flintmax}
(9.0072e+15) in order to factor correctly.
@xseealso{gcd, lcm, isprime, primes}
@end deftypefn
factorial
@c factorial scripts/specfun/factorial.m
@deftypefn {} {} factorial (@var{n})
Return the factorial of @var{n} where @var{n} is a real non-negative
integer.

If @var{n} is a scalar, this is equivalent to @code{prod (1:@var{n})}.  For
vector or matrix arguments, return the factorial of each element in the
array.

For non-integers see the generalized factorial function @code{gamma}.
Note that the factorial function grows large quite quickly, and even
with double precision values overflow will occur if @var{n} > 171.  For
such cases consider @code{gammaln}.
@xseealso{prod, gamma, gammaln}
@end deftypefn
gammainc
@c gammainc scripts/specfun/gammainc.m
@deftypefn  {} {} gammainc (@var{x}, @var{a})
@deftypefnx {} {} gammainc (@var{x}, @var{a}, @var{tail})
Compute the normalized incomplete gamma function.

This is defined as
@tex
$$
 \gamma (x, a) = {1 \over {\Gamma (a)}}\displaystyle{\int_0^x t^{a-1} e^{-t} dt}
$$
@end tex
@ifnottex

@example
@group
                                x
                       1       /
gammainc (x, a) = ---------    | exp (-t) t^(a-1) dt
                  gamma (a)    /
                            t=0
@end group
@end example

@end ifnottex
with the limiting value of 1 as @var{x} approaches infinity.
The standard notation is @math{P(a,x)}, e.g., @nospell{Abramowitz} and
@nospell{Stegun} (6.5.1).

If @var{a} is scalar, then @code{gammainc (@var{x}, @var{a})} is returned
for each element of @var{x} and vice versa.

If neither @var{x} nor @var{a} is scalar then the sizes of @var{x} and
@var{a} must agree, and @code{gammainc} is applied element-by-element.
The elements of @var{a} must be non-negative.

By default, @var{tail} is @qcode{"lower"} and the incomplete gamma function
integrated from 0 to @var{x} is computed.  If @var{tail} is @qcode{"upper"}
then the complementary function integrated from @var{x} to infinity is
calculated.

If @var{tail} is @qcode{"scaledlower"}, then the lower incomplete gamma
function is multiplied by
@tex
$\Gamma(a+1)\exp(x)x^{-a}$.
@end tex
@ifnottex
@math{gamma(a+1)*exp(x)/(x^a)}.
@end ifnottex
If @var{tail} is @qcode{"scaledupper"}, then the upper incomplete gamma
function is multiplied by the same quantity.

References:

@nospell{M. Abramowitz and I.A. Stegun},
@cite{Handbook of mathematical functions},
@nospell{Dover publications, Inc.}, 1972.

@nospell{W. Gautschi},
@cite{A computational procedure for incomplete gamma functions},
@nospell{ACM Trans. Math Software}, pp. 466--481, Vol 5, No. 4, 2012.

@nospell{W. H. Press, S. A. Teukolsky, W. T. Vetterling, and B. P. Flannery},
@cite{Numerical Recipes in Fortran 77}, ch.@: 6.2, Vol 1, 1992.

@xseealso{gamma, gammaincinv, gammaln}
@end deftypefn
gammaincinv
@c gammaincinv scripts/specfun/gammaincinv.m
@deftypefn  {} {} gammaincinv (@var{y}, @var{a})
@deftypefnx {} {} gammaincinv (@var{y}, @var{a}, @var{tail})
Compute the inverse of the normalized incomplete gamma function.

The normalized incomplete gamma function is defined as
@tex
$$
 \gamma (x, a) = {1 \over {\Gamma (a)}}\displaystyle{\int_0^x t^{a-1} e^{-t} dt}
$$
@end tex
@ifnottex

@example
@group
                                x
                       1       /
gammainc (x, a) = ---------    | exp (-t) t^(a-1) dt
                  gamma (a)    /
                            t=0
@end group
@end example

@end ifnottex

and @code{gammaincinv (gammainc (@var{x}, @var{a}), @var{a}) = @var{x}}
for each non-negative value of @var{x}.  If @var{a} is scalar then
@code{gammaincinv (@var{y}, @var{a})} is returned for each element of
@var{y} and vice versa.

If neither @var{y} nor @var{a} is scalar then the sizes of @var{y} and
@var{a} must agree, and @code{gammaincinv} is applied element-by-element.
The variable @var{y} must be in the interval @math{[0,1]} while @var{a} must
be real and positive.

By default, @var{tail} is @qcode{"lower"} and the inverse of the incomplete
gamma function integrated from 0 to @var{x} is computed.  If @var{tail} is
@qcode{"upper"}, then the complementary function integrated from @var{x} to
infinity is inverted.

The function is computed with Newton's method by solving
@tex
$$
 y - \gamma (x, a) = 0
$$
@end tex
@ifnottex

@example
@var{y} - gammainc (@var{x}, @var{a}) = 0
@end example

@end ifnottex

Reference: @nospell{A. Gil, J. Segura, and N. M. Temme}, @cite{Efficient and
accurate algorithms for the computation and inversion of the incomplete
gamma function ratios}, @nospell{SIAM J. Sci. Computing}, pp. A2965--A2981,
Vol 34, 2012.

@xseealso{gammainc, gamma, gammaln}
@end deftypefn
isprime
@c isprime scripts/specfun/isprime.m
@deftypefn {} {} isprime (@var{x})
Return a logical array which is true where the elements of @var{x} are prime
numbers and false where they are not.

A prime number is conventionally defined as a positive integer greater than
1 (e.g., 2, 3, @dots{}) which is divisible only by itself and 1.  Octave
extends this definition to include both negative integers and complex
values.  A negative integer is prime if its positive counterpart is prime.
This is equivalent to @code{isprime (abs (x))}.

If @code{class (@var{x})} is complex, then primality is tested in the domain
of Gaussian integers (@url{https://en.wikipedia.org/wiki/Gaussian_integer}).
Some non-complex integers are prime in the ordinary sense, but not in the
domain of Gaussian integers.  For example, @math{5 = (1+2i)*(1-2i)} shows
that 5 is not prime because it has a factor other than itself and 1.
Exercise caution when testing complex and real values together in the same
matrix.

Examples:

@example
@group
isprime (1:6)
  @result{}  0  1  1  0  1  0
@end group
@end example

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

Programming Note: @code{isprime} is appropriate if the maximum value in
@var{x} is not too large (< 1e15).  For larger values special purpose
factorization code should be used.

Compatibility Note: @var{matlab} does not extend the definition of prime
numbers and will produce an error if given negative or complex inputs.
@xseealso{primes, factor, gcd, lcm}
@end deftypefn
lcm
@c lcm scripts/specfun/lcm.m
@deftypefn  {} {} lcm (@var{x}, @var{y})
@deftypefnx {} {} lcm (@var{x}, @var{y}, @dots{})
Compute the least common multiple of @var{x} and @var{y}, or of the list of
all arguments.

All elements must be numeric and of the same size or scalar.
@xseealso{factor, gcd, isprime}
@end deftypefn
legendre
@c legendre scripts/specfun/legendre.m
@deftypefn  {} {@var{l} =} legendre (@var{n}, @var{x})
@deftypefnx {} {@var{l} =} legendre (@var{n}, @var{x}, @var{normalization})
Compute the associated Legendre function of degree @var{n} and order
@var{m} = 0 @dots{} @var{n}.

The value @var{n} must be a real non-negative integer.

@var{x} is a vector with real-valued elements in the range [-1, 1].

The optional argument @var{normalization} may be one of @qcode{"unnorm"},
@qcode{"sch"}, or @qcode{"norm"}.  The default if no normalization is given
is @qcode{"unnorm"}.

When the optional argument @var{normalization} is @qcode{"unnorm"}, compute
the associated Legendre function of degree @var{n} and order @var{m} and
return all values for @var{m} = 0 @dots{} @var{n}.  The return value has one
dimension more than @var{x}.

The associated Legendre function of degree @var{n} and order @var{m}:

@tex
$$
P^m_n(x) = (-1)^m (1-x^2)^{m/2}{d^m\over {dx^m}}P_n (x)
$$
@end tex
@ifnottex

@example
@group
 m         m      2  m/2   d^m
P(x) = (-1) * (1-x  )    * ----  P(x)
 n                         dx^m   n
@end group
@end example

@end ifnottex

@noindent
with Legendre polynomial of degree @var{n}:

@tex
$$
P(x) = {1\over{2^n n!}}\biggl({d^n\over{dx^n}}(x^2 - 1)^n\biggr)
$$
@end tex
@ifnottex

@example
@group
          1    d^n   2    n
P(x) = ------ [----(x - 1) ]
 n     2^n n!  dx^n
@end group
@end example

@end ifnottex

@noindent
@code{legendre (3, [-1.0, -0.9, -0.8])} returns the matrix:

@example
@group
 x  |   -1.0   |   -0.9   |   -0.8
------------------------------------
m=0 | -1.00000 | -0.47250 | -0.08000
m=1 |  0.00000 | -1.99420 | -1.98000
m=2 |  0.00000 | -2.56500 | -4.32000
m=3 |  0.00000 | -1.24229 | -3.24000
@end group
@end example

When the optional argument @var{normalization} is @qcode{"sch"}, compute
the Schmidt semi-normalized associated Legendre function.  The Schmidt
semi-normalized associated Legendre function is related to the unnormalized
Legendre functions by the following:

For Legendre functions of degree @var{n} and order 0:

@tex
$$
SP^0_n (x) = P^0_n (x)
$$
@end tex
@ifnottex

@example
@group
  0      0
SP(x) = P(x)
  n      n
@end group
@end example

@end ifnottex

For Legendre functions of degree n and order m:

@tex
$$
SP^m_n (x) = P^m_n (x)(-1)^m\biggl({2(n-m)!\over{(n+m)!}}\biggl)^{0.5}
$$
@end tex
@ifnottex

@example
@group
  m      m         m    2(n-m)! 0.5
SP(x) = P(x) * (-1)  * [-------]
  n      n              (n+m)!
@end group
@end example

@end ifnottex

When the optional argument @var{normalization} is @qcode{"norm"}, compute
the fully normalized associated Legendre function.  The fully normalized
associated Legendre function is related to the unnormalized associated
Legendre functions by the following:

For Legendre functions of degree @var{n} and order @var{m}

@tex
$$
NP^m_n (x) = P^m_n (x)(-1)^m\biggl({(n+0.5)(n-m)!\over{(n+m)!}}\biggl)^{0.5}
$$
@end tex
@ifnottex

@example
@group
  m      m         m    (n+0.5)(n-m)! 0.5
NP(x) = P(x) * (-1)  * [-------------]
  n      n                  (n+m)!
@end group
@end example

@end ifnottex
@end deftypefn
nchoosek
@c nchoosek scripts/specfun/nchoosek.m
@deftypefn  {} {@var{c} =} nchoosek (@var{n}, @var{k})
@deftypefnx {} {@var{c} =} nchoosek (@var{set}, @var{k})

Compute the binomial coefficient of @var{n} or list all possible
combinations of a @var{set} of items.

If @var{n} is a scalar then calculate the binomial coefficient
of @var{n} and @var{k} which is defined as
@tex
$$
 {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
               = {n! \over k! (n-k)!}
$$
@end tex
@ifnottex

@example
@group
 /   \
 | n |    n (n-1) (n-2) @dots{} (n-k+1)       n!
 |   |  = ------------------------- =  ---------
 | k |               k!                k! (n-k)!
 \   /
@end group
@end example

@end ifnottex
@noindent
This is the number of combinations of @var{n} items taken in groups of
size @var{k}.

If the first argument is a vector, @var{set}, then generate all
combinations of the elements of @var{set}, taken @var{k} at a time, with
one row per combination.  The result @var{c} has @var{k} columns and
@w{@code{nchoosek (length (@var{set}), @var{k})}} rows.

For example:

How many ways can three items be grouped into pairs?

@example
@group
nchoosek (3, 2)
   @result{} 3
@end group
@end example

What are the possible pairs?

@example
@group
nchoosek (1:3, 2)
   @result{}  1   2
       1   3
       2   3
@end group
@end example

Programming Note: When calculating the binomial coefficient @code{nchoosek}
works only for non-negative, integer arguments.  Use @code{bincoeff} for
non-integer and negative scalar arguments, or for computing many binomial
coefficients at once with vector inputs for @var{n} or @var{k}.

@xseealso{bincoeff, perms}
@end deftypefn
nthroot
@c nthroot scripts/specfun/nthroot.m
@deftypefn {} {} nthroot (@var{x}, @var{n})

Compute the real (non-complex) @var{n}-th root of @var{x}.

@var{x} must have all real entries and @var{n} must be a scalar.
If @var{n} is an even integer and @var{x} has negative entries then
@code{nthroot} aborts and issues an error.

Example:

@example
@group
nthroot (-1, 3)
@result{} -1
(-1) ^ (1 / 3)
@result{} 0.50000 - 0.86603i
@end group
@end example
@xseealso{realsqrt, sqrt, cbrt}
@end deftypefn
perms
@c perms scripts/specfun/perms.m
@deftypefn {} {} perms (@var{v})
Generate all permutations of vector @var{v} with one row per permutation.

Results are returned in inverse lexicographic order.  The result has size
@code{factorial (@var{n}) * @var{n}}, where @var{n} is the length of
@var{v}.  Any repetitions are included in the output.  To generate just the
unique permutations use @code{unique (perms (@var{v}), "rows")(end:-1:1,:)}.

Example

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

Programming Note: The maximum length of @var{v} should be less than or
equal to 10 to limit memory consumption.
@xseealso{permute, randperm, nchoosek}
@end deftypefn
pow2
@c pow2 scripts/specfun/pow2.m
@deftypefn  {} {} pow2 (@var{x})
@deftypefnx {} {} pow2 (@var{f}, @var{e})
With one input argument, compute
@tex
$2^x$
@end tex
@ifnottex
2 .^ x
@end ifnottex
for each element of @var{x}.

With two input arguments, return
@tex
$f \cdot 2^e$.
@end tex
@ifnottex
f .* (2 .^ e).
@end ifnottex
@xseealso{log2, nextpow2, power}
@end deftypefn
primes
@c primes scripts/specfun/primes.m
@deftypefn {} {@var{p} =} primes (@var{n})
Return all primes up to @var{n}.

The output data class (double, single, uint32, etc.@:) is the same as the
input class of @var{n}.  The algorithm used is the Sieve of Eratosthenes.

Note: If you need a specific number of primes you can use the fact that the
distance from one prime to the next is, on average, proportional to the
logarithm of the prime.  Integrating, one finds that there are about
@math{k} primes less than
@tex
$k \log (5 k)$.
@end tex
@ifnottex
k*log (5*k).
@end ifnottex

See also @code{list_primes} if you need a specific number @var{n} of primes.
@xseealso{list_primes, isprime}
@end deftypefn
reallog
@c reallog scripts/specfun/reallog.m
@deftypefn {} {} reallog (@var{x})
Return the real-valued natural logarithm of each element of @var{x}.

If any element results in a complex return value @code{reallog} aborts and
issues an error.
@xseealso{log, realpow, realsqrt}
@end deftypefn
realpow
@c realpow scripts/specfun/realpow.m
@deftypefn {} {} realpow (@var{x}, @var{y})
Compute the real-valued, element-by-element power operator.

This is equivalent to @w{@code{@var{x} .^ @var{y}}}, except that
@code{realpow} reports an error if any return value is complex.
@xseealso{power, reallog, realsqrt}
@end deftypefn
realsqrt
@c realsqrt scripts/specfun/realsqrt.m
@deftypefn {} {} realsqrt (@var{x})
Return the real-valued square root of each element of @var{x}.

If any element results in a complex return value @code{realsqrt} aborts and
issues an error.
@xseealso{sqrt, realpow, reallog}
@end deftypefn
sinint
@c sinint scripts/specfun/sinint.m
@deftypefn {} {} sinint (@var{x})
Compute the sine integral function:
@tex
$$
{\rm Si} (x) = \int_0^x {\sin (t) \over t} dt
$$
@end tex
@ifnottex

@example
@group
           x
          /
Si (x) =  | sin (t) / t dt
          /
         0
@end group
@end example

@end ifnottex

Reference:
@nospell{M. Abramowitz and I.A. Stegun},
@cite{Handbook of Mathematical Functions}, 1964.

@xseealso{cosint, expint, sin}
@end deftypefn
gallery
@c gallery scripts/special-matrix/gallery.m
@deftypefn  {} {} gallery (@var{name})
@deftypefnx {} {} gallery (@var{name}, @var{args})
Create interesting matrices for testing.

@end deftypefn

@deftypefn  {} {@var{c} =} gallery ("cauchy", @var{x})
@deftypefnx {} {@var{c} =} gallery ("cauchy", @var{x}, @var{y})
Create a Cauchy matrix.

@end deftypefn

@deftypefn  {} {@var{c} =} gallery ("chebspec", @var{n})
@deftypefnx {} {@var{c} =} gallery ("chebspec", @var{n}, @var{k})
Create a Chebyshev spectral differentiation matrix.

@end deftypefn

@deftypefn  {} {@var{c} =} gallery ("chebvand", @var{p})
@deftypefnx {} {@var{c} =} gallery ("chebvand", @var{m}, @var{p})
Create a @nospell{Vandermonde}-like matrix for the Chebyshev polynomials.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("chow", @var{n})
@deftypefnx {} {@var{a} =} gallery ("chow", @var{n}, @var{alpha})
@deftypefnx {} {@var{a} =} gallery ("chow", @var{n}, @var{alpha}, @var{delta})
Create a Chow matrix -- a singular Toeplitz lower Hessenberg matrix.

@end deftypefn

@deftypefn {} {@var{c} =} gallery ("circul", @var{v})
Create a circulant matrix.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("clement", @var{n})
@deftypefnx {} {@var{a} =} gallery ("clement", @var{n}, @var{k})
Create a tridiagonal matrix with zero diagonal entries.

@end deftypefn

@deftypefn  {} {@var{c} =} gallery ("compar", @var{a})
@deftypefnx {} {@var{c} =} gallery ("compar", @var{a}, @var{k})
Create a comparison matrix.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("condex", @var{n})
@deftypefnx {} {@var{a} =} gallery ("condex", @var{n}, @var{k})
@deftypefnx {} {@var{a} =} gallery ("condex", @var{n}, @var{k}, @var{theta})
Create a `counterexample' matrix to a condition estimator.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("cycol", [@var{m} @var{n}])
@deftypefnx {} {@var{a} =} gallery ("cycol", @var{n})
@deftypefnx {} {@var{a} =} gallery (@dots{}, @var{k})
Create a matrix whose columns repeat cyclically.

@end deftypefn

@deftypefn  {} {[@var{c}, @var{d}, @var{e}] =} gallery ("dorr", @var{n})
@deftypefnx {} {[@var{c}, @var{d}, @var{e}] =} gallery ("dorr", @var{n}, @var{theta})
@deftypefnx {} {@var{a} =} gallery ("dorr", @dots{})
Create a diagonally dominant, ill-conditioned, tridiagonal matrix.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("dramadah", @var{n})
@deftypefnx {} {@var{a} =} gallery ("dramadah", @var{n}, @var{k})
Create a (0, 1) matrix whose inverse has large integer entries.

@end deftypefn

@deftypefn {} {@var{a} =} gallery ("fiedler", @var{c})
Create a symmetric @nospell{Fiedler} matrix.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("forsythe", @var{n})
@deftypefnx {} {@var{a} =} gallery ("forsythe", @var{n}, @var{alpha})
@deftypefnx {} {@var{a} =} gallery ("forsythe", @var{n}, @var{alpha}, @var{lambda})
Create a @nospell{Forsythe} matrix (a perturbed Jordan block).

@end deftypefn

@deftypefn  {} {@var{f} =} gallery ("frank", @var{n})
@deftypefnx {} {@var{f} =} gallery ("frank", @var{n}, @var{k})
Create a Frank matrix (ill-conditioned eigenvalues).

@end deftypefn

@deftypefn {} {@var{c} =} gallery ("gcdmat", @var{n})
Create a greatest common divisor matrix.

@var{c} is an @var{n}-by-@var{n} matrix whose values correspond to the
greatest common divisor of its coordinate values, i.e., @var{c}(i,j)
correspond @code{gcd (i, j)}.
@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("gearmat", @var{n})
@deftypefnx {} {@var{a} =} gallery ("gearmat", @var{n}, @var{i})
@deftypefnx {} {@var{a} =} gallery ("gearmat", @var{n}, @var{i}, @var{j})
Create a Gear matrix.

@end deftypefn

@deftypefn  {} {@var{g} =} gallery ("grcar", @var{n})
@deftypefnx {} {@var{g} =} gallery ("grcar", @var{n}, @var{k})
Create a Toeplitz matrix with sensitive eigenvalues.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("hanowa", @var{n})
@deftypefnx {} {@var{a} =} gallery ("hanowa", @var{n}, @var{d})
Create a matrix whose eigenvalues lie on a vertical line in the complex
plane.

@end deftypefn

@deftypefn  {} {@var{v} =} gallery ("house", @var{x})
@deftypefnx {} {[@var{v}, @var{beta}] =} gallery ("house", @var{x})
Create a householder matrix.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("integerdata", @var{imax}, [@var{M} @var{N} @dots{}], @var{j})
@deftypefnx {} {@var{a} =} gallery ("integerdata", @var{imax}, @var{M}, @var{N}, @dots{}, @var{j})
@deftypefnx {} {@var{a} =} gallery ("integerdata", [@var{imin}, @var{imax}], [@var{M} @var{N} @dots{}], @var{j})
@deftypefnx {} {@var{a} =} gallery ("integerdata", [@var{imin}, @var{imax}], @var{M}, @var{N}, @dots{}, @var{j})
@deftypefnx {} {@var{a} =} gallery ("integerdata", @dots{}, "@var{class}")
Create a matrix with random integers in the range [1, @var{imax}].
If @var{imin} is given then the integers are in the range
[@var{imin}, @var{imax}].

The second input is a matrix of dimensions describing the size of the
output.  The dimensions can also be input as comma-separated arguments.

The input @var{j} is an integer index in the range [0, 2^32-1].  The values
of the output matrix are always exactly the same (reproducibility) for a
given size input and @var{j} index.

The final optional argument determines the class of the resulting matrix.
Possible values for @var{class}: @qcode{"uint8"}, @qcode{"uint16"},
@qcode{"uint32"}, @qcode{"int8"}, @qcode{"int16"}, int32", @qcode{"single"},
@qcode{"double"}.  The default is @qcode{"double"}.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("invhess", @var{x})
@deftypefnx {} {@var{a} =} gallery ("invhess", @var{x}, @var{y})
Create the inverse of an upper Hessenberg matrix.

@end deftypefn

@deftypefn {} {@var{a} =} gallery ("invol", @var{n})
Create an involutory matrix.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("ipjfact", @var{n})
@deftypefnx {} {@var{a} =} gallery ("ipjfact", @var{n}, @var{k})
Create a Hankel matrix with factorial elements.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("jordbloc", @var{n})
@deftypefnx {} {@var{a} =} gallery ("jordbloc", @var{n}, @var{lambda})
Create a Jordan block.

@end deftypefn

@deftypefn  {} {@var{u} =} gallery ("kahan", @var{n})
@deftypefnx {} {@var{u} =} gallery ("kahan", @var{n}, @var{theta})
@deftypefnx {} {@var{u} =} gallery ("kahan", @var{n}, @var{theta}, @var{pert})
Create a @nospell{Kahan} matrix (upper trapezoidal).

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("kms", @var{n})
@deftypefnx {} {@var{a} =} gallery ("kms", @var{n}, @var{rho})
Create a @nospell{Kac-Murdock-Szego} Toeplitz matrix.

@end deftypefn

@deftypefn  {} {@var{b} =} gallery ("krylov", @var{a})
@deftypefnx {} {@var{b} =} gallery ("krylov", @var{a}, @var{x})
@deftypefnx {} {@var{b} =} gallery ("krylov", @var{a}, @var{x}, @var{j})
Create a Krylov matrix.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("lauchli", @var{n})
@deftypefnx {} {@var{a} =} gallery ("lauchli", @var{n}, @var{mu})
Create a @nospell{Lauchli} matrix (rectangular).

@end deftypefn

@deftypefn {} {@var{a} =} gallery ("lehmer", @var{n})
Create a @nospell{Lehmer} matrix (symmetric positive definite).

@end deftypefn

@deftypefn {} {@var{t} =} gallery ("lesp", @var{n})
Create a tridiagonal matrix with real, sensitive eigenvalues.

@end deftypefn

@deftypefn {} {@var{a} =} gallery ("lotkin", @var{n})
Create a @nospell{Lotkin} matrix.

@end deftypefn

@deftypefn {} {@var{a} =} gallery ("minij", @var{n})
Create a symmetric positive definite matrix MIN(i,j).

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("moler", @var{n})
@deftypefnx {} {@var{a} =} gallery ("moler", @var{n}, @var{alpha})
Create a @nospell{Moler} matrix (symmetric positive definite).

@end deftypefn

@deftypefn {} {[@var{a}, @var{t}] =} gallery ("neumann", @var{n})
Create a singular matrix from the discrete @nospell{Neumann} problem
(sparse).

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("normaldata", [@var{M} @var{N} @dots{}], @var{j})
@deftypefnx {} {@var{a} =} gallery ("normaldata", @var{M}, @var{N}, @dots{}, @var{j})
@deftypefnx {} {@var{a} =} gallery ("normaldata", @dots{}, "@var{class}")
Create a matrix with random samples from the standard normal distribution
(mean = 0, std = 1).

The first input is a matrix of dimensions describing the size of the output.
The dimensions can also be input as comma-separated arguments.

The input @var{j} is an integer index in the range [0, 2^32-1].  The values
of the output matrix are always exactly the same (reproducibility) for a
given size input and @var{j} index.

The final optional argument determines the class of the resulting matrix.
Possible values for @var{class}: @qcode{"single"}, @qcode{"double"}.
The default is @qcode{"double"}.

@end deftypefn

@deftypefn  {} {@var{q} =} gallery ("orthog", @var{n})
@deftypefnx {} {@var{q} =} gallery ("orthog", @var{n}, @var{k})
Create orthogonal and nearly orthogonal matrices.

@end deftypefn

@deftypefn {} {@var{a} =} gallery ("parter", @var{n})
Create a @nospell{Parter} matrix (a Toeplitz matrix with singular values
near pi).

@end deftypefn

@deftypefn  {} {@var{p} =} gallery ("pei", @var{n})
@deftypefnx {} {@var{p} =} gallery ("pei", @var{n}, @var{alpha})
Create a Pei matrix.

@end deftypefn

@deftypefn {} {@var{a} =} gallery ("poisson", @var{n})
Create a block tridiagonal matrix from Poisson's equation (sparse).

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("prolate", @var{n})
@deftypefnx {} {@var{a} =} gallery ("prolate", @var{n}, @var{w})
Create a prolate matrix (symmetric, ill-conditioned Toeplitz matrix).

@end deftypefn

@deftypefn {} {@var{h} =} gallery ("randhess", @var{x})
Create a random, orthogonal upper Hessenberg matrix.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("rando", @var{n})
@deftypefnx {} {@var{a} =} gallery ("rando", @var{n}, @var{k})
Create a random matrix with elements -1, 0 or 1.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("randsvd", @var{n})
@deftypefnx {} {@var{a} =} gallery ("randsvd", @var{n}, @var{kappa})
@deftypefnx {} {@var{a} =} gallery ("randsvd", @var{n}, @var{kappa}, @var{mode})
@deftypefnx {} {@var{a} =} gallery ("randsvd", @var{n}, @var{kappa}, @var{mode}, @var{kl})
@deftypefnx {} {@var{a} =} gallery ("randsvd", @var{n}, @var{kappa}, @var{mode}, @var{kl}, @var{ku})
Create a random matrix with pre-assigned singular values.

@end deftypefn

@deftypefn {} {@var{a} =} gallery ("redheff", @var{n})
Create a zero and ones matrix of @nospell{Redheffer} associated with the
Riemann hypothesis.

@end deftypefn

@deftypefn {} {@var{a} =} gallery ("riemann", @var{n})
Create a matrix associated with the Riemann hypothesis.

@end deftypefn

@deftypefn {} {@var{a} =} gallery ("ris", @var{n})
Create a symmetric Hankel matrix.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("smoke", @var{n})
@deftypefnx {} {@var{a} =} gallery ("smoke", @var{n}, @var{k})
Create a complex matrix, with a `smoke ring' pseudospectrum.

@end deftypefn

@deftypefn  {} {@var{t} =} gallery ("toeppd", @var{n})
@deftypefnx {} {@var{t} =} gallery ("toeppd", @var{n}, @var{m})
@deftypefnx {} {@var{t} =} gallery ("toeppd", @var{n}, @var{m}, @var{w})
@deftypefnx {} {@var{t} =} gallery ("toeppd", @var{n}, @var{m}, @var{w}, @var{theta})
Create a symmetric positive definite Toeplitz matrix.

@end deftypefn

@deftypefn  {} {@var{p} =} gallery ("toeppen", @var{n})
@deftypefnx {} {@var{p} =} gallery ("toeppen", @var{n}, @var{a})
@deftypefnx {} {@var{p} =} gallery ("toeppen", @var{n}, @var{a}, @var{b})
@deftypefnx {} {@var{p} =} gallery ("toeppen", @var{n}, @var{a}, @var{b}, @var{c})
@deftypefnx {} {@var{p} =} gallery ("toeppen", @var{n}, @var{a}, @var{b}, @var{c}, @var{d})
@deftypefnx {} {@var{p} =} gallery ("toeppen", @var{n}, @var{a}, @var{b}, @var{c}, @var{d}, @var{e})
Create a pentadiagonal Toeplitz matrix (sparse).

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("tridiag", @var{x}, @var{y}, @var{z})
@deftypefnx {} {@var{a} =} gallery ("tridiag", @var{n})
@deftypefnx {} {@var{a} =} gallery ("tridiag", @var{n}, @var{c}, @var{d}, @var{e})
Create a tridiagonal matrix (sparse).

@end deftypefn

@deftypefn  {} {@var{t} =} gallery ("triw", @var{n})
@deftypefnx {} {@var{t} =} gallery ("triw", @var{n}, @var{alpha})
@deftypefnx {} {@var{t} =} gallery ("triw", @var{n}, @var{alpha}, @var{k})
Create an upper triangular matrix discussed by
@nospell{Kahan, Golub, and Wilkinson}.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("uniformdata", [@var{M} @var{N} @dots{}], @var{j})
@deftypefnx {} {@var{a} =} gallery ("uniformdata", @var{M}, @var{N}, @dots{}, @var{j})
@deftypefnx {} {@var{a} =} gallery ("uniformdata", @dots{}, "@var{class}")
Create a matrix with random samples from the standard uniform distribution
(range [0,1]).

The first input is a matrix of dimensions describing the size of the output.
The dimensions can also be input as comma-separated arguments.

The input @var{j} is an integer index in the range [0, 2^32-1].  The values
of the output matrix are always exactly the same (reproducibility) for a
given size input and @var{j} index.

The final optional argument determines the class of the resulting matrix.
Possible values for @var{class}: @qcode{"single"}, @qcode{"double"}.
The default is @qcode{"double"}.

@end deftypefn

@deftypefn  {} {@var{a} =} gallery ("wathen", @var{nx}, @var{ny})
@deftypefnx {} {@var{a} =} gallery ("wathen", @var{nx}, @var{ny}, @var{k})
Create the @nospell{Wathen} matrix.

@end deftypefn

@deftypefn {} {[@var{a}, @var{b}] =} gallery ("wilk", @var{n})
Create various specific matrices devised/discussed by Wilkinson.

@end deftypefn
hadamard
@c hadamard scripts/special-matrix/hadamard.m
@deftypefn {} {} hadamard (@var{n})
Construct a Hadamard matrix (@nospell{Hn}) of size @var{n}-by-@var{n}.

The size @var{n} must be of the form @math{2^k * p} in which p is one of
1, 12, 20 or 28.  The returned matrix is normalized, meaning
@w{@code{Hn(:,1) == 1}} and @w{@code{Hn(1,:) == 1}}.

Some of the properties of Hadamard matrices are:

@itemize @bullet
@item
@code{kron (Hm, Hn)} is a Hadamard matrix of size @var{m}-by-@var{n}.

@item
@code{Hn * Hn' = @var{n} * eye (@var{n})}.

@item
The rows of @nospell{Hn} are orthogonal.

@item
@code{det (@var{A}) <= abs (det (Hn))} for all @var{A} with
@w{@code{abs (@var{A}(i, j)) <= 1}}.

@item
Multiplying any row or column by -1 and the matrix will remain a Hadamard
matrix.
@end itemize
@xseealso{compan, hankel, toeplitz}
@end deftypefn
hankel
@c hankel scripts/special-matrix/hankel.m
@deftypefn  {} {} hankel (@var{c})
@deftypefnx {} {} hankel (@var{c}, @var{r})
Return the Hankel matrix constructed from the first column @var{c}, and
(optionally) the last row @var{r}.

If the last element of @var{c} is not the same as the first element of
@var{r}, the last element of @var{c} is used.  If the second argument is
omitted, it is assumed to be a vector of zeros with the same size as
@var{c}.

A Hankel matrix formed from an m-vector @var{c}, and an n-vector @var{r},
has the elements
@tex
$$
H(i, j) = \cases{c_{i+j-1},&$i+j-1\le m$;\cr r_{i+j-m},&otherwise.\cr}
$$
@end tex
@ifnottex

@example
@group
H(i,j) = c(i+j-1),  i+j-1 <= m;
H(i,j) = r(i+j-m),  otherwise
@end group
@end example

@end ifnottex
@xseealso{hadamard, toeplitz}
@end deftypefn
hilb
@c hilb scripts/special-matrix/hilb.m
@deftypefn {} {} hilb (@var{n})
Return the Hilbert matrix of order @var{n}.

The @math{i,j} element of a Hilbert matrix is defined as
@tex
$$
H(i, j) = {1 \over (i + j - 1)}
$$
@end tex
@ifnottex

@example
H(i, j) = 1 / (i + j - 1)
@end example

@end ifnottex

Hilbert matrices are close to being singular which make them difficult to
invert with numerical routines.  Comparing the condition number of a random
matrix 5x5 matrix with that of a Hilbert matrix of order 5 reveals just how
difficult the problem is.

@example
@group
cond (rand (5))
   @result{} 14.392
cond (hilb (5))
   @result{} 4.7661e+05
@end group
@end example

@xseealso{invhilb}
@end deftypefn
invhilb
@c invhilb scripts/special-matrix/invhilb.m
@deftypefn {} {} invhilb (@var{n})
Return the inverse of the Hilbert matrix of order @var{n}.

This can be computed exactly using
@tex
$$\eqalign{
  A_{ij} &= -1^{i+j} (i+j-1)
             \left( \matrix{n+i-1 \cr n-j } \right)
             \left( \matrix{n+j-1 \cr n-i } \right)
             \left( \matrix{i+j-2 \cr i-2 } \right)^2 \cr
         &= { p(i)p(j) \over (i+j-1) }
}$$
where
$$
  p(k) = -1^k \left( \matrix{ k+n-1 \cr k-1 } \right)
              \left( \matrix{ n \cr k } \right)
$$
@end tex
@ifnottex

@example
@group

           (i+j)         /n+i-1\  /n+j-1\   /i+j-2\ 2
A(i,j) = -1      (i+j-1)(       )(       ) (       )
                         \ n-j /  \ n-i /   \ i-2 /

       = p(i) p(j) / (i+j-1)

@end group
@end example

@noindent
where

@example
@group
         k  /k+n-1\   /n\
p(k) = -1  (       ) (   )
            \ k-1 /   \k/
@end group
@end example

@end ifnottex
The validity of this formula can easily be checked by expanding the binomial
coefficients in both formulas as factorials.  It can be derived more
directly via the theory of Cauchy matrices.  See @nospell{J. W. Demmel},
@cite{Applied Numerical Linear Algebra}, p. 92.

Compare this with the numerical calculation of @code{inv (hilb (n))},
which suffers from the ill-conditioning of the Hilbert matrix, and the
finite precision of your computer's floating point arithmetic.
@xseealso{hilb}
@end deftypefn
magic
@c magic scripts/special-matrix/magic.m
@deftypefn {} {} magic (@var{n})

Create an @var{n}-by-@var{n} magic square.

A magic square is an arrangement of the integers @code{1:n^2} such that the
row sums, column sums, and diagonal sums are all equal to the same value.

Note: @var{n} must be a scalar greater than or equal to 3.  If you supply
@var{n} less than 3, magic returns either a nonmagic square, or else the
degenerate magic squares 1 and [].
@end deftypefn
pascal
@c pascal scripts/special-matrix/pascal.m
@deftypefn  {} {} pascal (@var{n})
@deftypefnx {} {} pascal (@var{n}, @var{t})
Return the Pascal matrix of order @var{n} if @code{@var{t} = 0}.

The default value of @var{t} is 0.

When @code{@var{t} = 1}, return the pseudo-lower triangular
Cholesky@tie{}factor of the Pascal matrix (The sign of some columns may be
negative).  This matrix is its own inverse, that is
@code{pascal (@var{n}, 1) ^ 2 == eye (@var{n})}.

If @code{@var{t} = -1}, return the true Cholesky@tie{}factor with strictly
positive values on the diagonal.

If @code{@var{t} = 2}, return a transposed and permuted version of
@code{pascal (@var{n}, 1)}, which is the cube root of the identity matrix.
That is, @code{pascal (@var{n}, 2) ^ 3 == eye (@var{n})}.

@xseealso{chol}
@end deftypefn
rosser
@c rosser scripts/special-matrix/rosser.m
@deftypefn {} {} rosser ()
Return the @nospell{Rosser} matrix.

This is a difficult test case used to evaluate eigenvalue algorithms.
@xseealso{wilkinson, eig}
@end deftypefn
toeplitz
@c toeplitz scripts/special-matrix/toeplitz.m
@deftypefn  {} {} toeplitz (@var{c})
@deftypefnx {} {} toeplitz (@var{c}, @var{r})
Return the Toeplitz matrix constructed from the first column @var{c},
and optionally the first row @var{r}.

If the second argument is omitted, the first row is taken to be the
same as the first column.  If the first element of @var{r} is not the same
as the first element of @var{c}, the first element of @var{c} is used.

A Toeplitz, or diagonal-constant, matrix has the same value along each
diagonal.  Although it need not be square, it often is.  An @nospell{MxN}
Toeplitz matrix has the form:
@tex
$$
\left[\matrix{c_1    & r_2     & r_3      & \cdots & r_n\cr
              c_2    & c_1     & r_2      & \cdots & r_{n-1}\cr
              c_3    & c_2     & c_1      & \cdots & r_{n-2}\cr
              \vdots & \vdots  & \vdots   & \ddots & \vdots\cr
              c_m    & c_{m-1} & c_{m-2} & \ldots & c{m-n+1}}\right]
$$
@end tex
@ifnottex

@example
@group
c(1)  r(2)   r(3)  @dots{}  r(n)
c(2)  c(1)   r(2)  @dots{} r(n-1)
c(3)  c(2)   c(1)  @dots{} r(n-2)
 .     .      .   .      .
 .     .      .     .    .
 .     .      .       .  .
c(m) c(m-1) c(m-2) @dots{} c(m-n+1)
@end group
@end example

@end ifnottex
@xseealso{hankel}
@end deftypefn
vander
@c vander scripts/special-matrix/vander.m
@deftypefn  {} {} vander (@var{c})
@deftypefnx {} {} vander (@var{c}, @var{n})
Return the @nospell{Vandermonde} matrix whose next to last column is
@var{c}.

If @var{n} is specified, it determines the number of columns; otherwise,
@var{n} is taken to be equal to the length of @var{c}.

A @nospell{Vandermonde} matrix has the form:
@tex
$$
\left[\matrix{c_1^{n-1}  & \cdots & c_1^2  & c_1    & 1      \cr
              c_2^{n-1}  & \cdots & c_2^2  & c_2    & 1      \cr
              \vdots     & \ddots & \vdots & \vdots & \vdots \cr
              c_n^{n-1}  & \cdots & c_n^2  & c_n    & 1      }\right]
$$
@end tex
@ifnottex

@example
@group
c(1)^(n-1) @dots{} c(1)^2  c(1)  1
c(2)^(n-1) @dots{} c(2)^2  c(2)  1
    .     .      .      .    .
    .       .    .      .    .
    .         .  .      .    .
c(n)^(n-1) @dots{} c(n)^2  c(n)  1
@end group
@end example

@end ifnottex
@xseealso{polyfit}
@end deftypefn
wilkinson
@c wilkinson scripts/special-matrix/wilkinson.m
@deftypefn {} {} wilkinson (@var{n})
Return the Wilkinson matrix of order @var{n}.

Wilkinson matrices are symmetric and tridiagonal with pairs of nearly, but
not exactly, equal eigenvalues.  They are useful in testing the behavior and
performance of eigenvalue solvers.

@xseealso{rosser, eig}
@end deftypefn
__finish__
@c __finish__ scripts/startup/__finish__.m
@deftypefn {} {} __finish__
Check for the existence of the function/script, @file{finish}, in the
path or current working directory and execute it.

This function is intended to be executed upon a clean exit from Octave.
This is accomplished in the system script @file{startup/octaverc} by use of
the built-in function @code{atexit}.
@xseealso{atexit}
@end deftypefn
bounds
@c bounds scripts/statistics/bounds.m
@deftypefn  {} {[@var{s}, @var{l}] =} bounds (@var{x})
@deftypefnx {} {[@var{s}, @var{l}] =} bounds (@var{x}, @var{dim})
@deftypefnx {} {[@var{s}, @var{l}] =} bounds (@dots{}, "nanflag")
Return the smallest and largest values of the input data @var{x}.

If @var{x} is a vector, the bounds are calculated over the elements of
@var{x}.  If @var{x} is a matrix, the bounds are calculated for each column.
For a multi-dimensional array, the bounds are calculated over the first
non-singleton dimension.

If the optional argument @var{dim} is given, operate along this dimension.

The optional argument @qcode{"nanflag"} defaults to @qcode{"omitnan"} which
does not include NaN values in the result.  If the argument
@qcode{"includenan"} is given, and there is a NaN present, then the result
for both smallest (@var{s}) and largest (@var{l}) elements will be NaN.

The bounds are a quickly computed measure of the dispersion of a data set,
but are less accurate than @code{iqr} if there are outlying data points.
@xseealso{range, iqr, mad, std}
@end deftypefn
center
@c center scripts/statistics/center.m
@deftypefn  {} {} center (@var{x})
@deftypefnx {} {} center (@var{x}, @var{dim})
Center data by subtracting its mean.

If @var{x} is a vector, subtract its mean.

If @var{x} is a matrix, do the above for each column.

If the optional argument @var{dim} is given, operate along this dimension.

Programming Note: @code{center} has obvious application for normalizing
statistical data.  It is also useful for improving the precision of general
numerical calculations.  Whenever there is a large value that is common
to a batch of data, the mean can be subtracted off, the calculation
performed, and then the mean added back to obtain the final answer.
@xseealso{zscore}
@end deftypefn
corr
@c corr scripts/statistics/corr.m
@deftypefn  {} {} corr (@var{x})
@deftypefnx {} {} corr (@var{x}, @var{y})
Compute matrix of correlation coefficients.

If each row of @var{x} and @var{y} is an observation and each column is
a variable, then the @w{(@var{i}, @var{j})-th} entry of
@code{corr (@var{x}, @var{y})} is the correlation between the
@var{i}-th variable in @var{x} and the @var{j}-th variable in @var{y}.
@tex
$$
{\rm corr}(x,y) = {{\rm cov}(x,y) \over {\rm std}(x) \, {\rm std}(y)}
$$
@end tex
@ifnottex

@example
corr (@var{x},@var{y}) = cov (@var{x},@var{y}) / (std (@var{x}) * std (@var{y}))
@end example

@end ifnottex
If called with one argument, compute @code{corr (@var{x}, @var{x})},
the correlation between the columns of @var{x}.
@xseealso{cov}
@end deftypefn
corrcoef
@c corrcoef scripts/statistics/corrcoef.m
@deftypefn  {} {@var{r} =} corrcoef (@var{x})
@deftypefnx {} {@var{r} =} corrcoef (@var{x}, @var{y})
@deftypefnx {} {@var{r} =} corrcoef (@dots{}, @var{param}, @var{value}, @dots{})
@deftypefnx {} {[@var{r}, @var{p}] =} corrcoef (@dots{})
@deftypefnx {} {[@var{r}, @var{p}, @var{lci}, @var{hci}] =} corrcoef (@dots{})
Compute a matrix of correlation coefficients.

@var{x} is an array where each column contains a variable and each row is
an observation.

If a second input @var{y} (of the same size as @var{x}) is given then
calculate the correlation coefficients between @var{x} and @var{y}.

@var{param}, @var{value} are optional pairs of parameters and values which
modify the calculation.  Valid options are:

@table @asis
@item @qcode{"alpha"}
Confidence level used for the bounds of the confidence interval, @var{lci}
and @var{hci}.  Default is 0.05, i.e., 95% confidence interval.

@item @qcode{"rows"}
Determine processing of NaN values.  Acceptable values are @qcode{"all"},
@qcode{"complete"}, and @qcode{"pairwise"}.  Default is @qcode{"all"}.
With @qcode{"complete"}, only the rows without NaN values are considered.
With @qcode{"pairwise"}, the selection of NaN-free rows is made for each
pair of variables.
@end table

Output @var{r} is a matrix of Pearson's product moment correlation
coefficients for each pair of variables.

Output @var{p} is a matrix of pair-wise p-values testing for the null
hypothesis of a correlation coefficient of zero.

Outputs @var{lci} and @var{hci} are matrices containing, respectively, the
lower and higher bounds of the 95% confidence interval of each correlation
coefficient.
@xseealso{corr, cov}
@end deftypefn
cov
@c cov scripts/statistics/cov.m
@deftypefn  {} {} cov (@var{x})
@deftypefnx {} {} cov (@var{x}, @var{opt})
@deftypefnx {} {} cov (@var{x}, @var{y})
@deftypefnx {} {} cov (@var{x}, @var{y}, @var{opt})
Compute the covariance matrix.

If each row of @var{x} and @var{y} is an observation, and each column is
a variable, then the @w{(@var{i}, @var{j})-th} entry of
@code{cov (@var{x}, @var{y})} is the covariance between the @var{i}-th
variable in @var{x} and the @var{j}-th variable in @var{y}.
@tex
$$
\sigma_{ij} = {1 \over N-1} \sum_{i=1}^N (x_i - \bar{x})(y_i - \bar{y})
$$
where $\bar{x}$ and $\bar{y}$ are the mean values of @var{x} and @var{y}.
@end tex
@ifnottex

@example
cov (@var{x}) = 1/(N-1) * SUM_i (@var{x}(i) - mean(@var{x})) * (@var{y}(i) - mean(@var{y}))
@end example

@noindent
where @math{N} is the length of the @var{x} and @var{y} vectors.

@end ifnottex

If called with one argument, compute @code{cov (@var{x}, @var{x})}, the
covariance between the columns of @var{x}.

The argument @var{opt} determines the type of normalization to use.
Valid values are

@table @asis
@item 0:
  normalize with @math{N-1}, provides the best unbiased estimator of the
covariance [default]

@item 1:
  normalize with @math{N}, this provides the second moment around the mean
@end table

Compatibility Note:: Octave always treats rows of @var{x} and @var{y}
as multivariate random variables.
For two inputs, however, @sc{matlab} treats @var{x} and @var{y} as two
univariate distributions regardless of their shapes, and will calculate
@code{cov ([@var{x}(:), @var{y}(:)])} whenever the number of elements in
@var{x} and @var{y} are equal.  This will result in a 2x2 matrix.
Code relying on @sc{matlab}'s definition will need to be changed when
running in Octave.
@xseealso{corr}
@end deftypefn
discrete_cdf
@c discrete_cdf scripts/statistics/discrete_cdf.m
@deftypefn {} {} discrete_cdf (@var{x}, @var{v}, @var{p})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of a univariate discrete distribution which assumes the
values in @var{v} with probabilities @var{p}.
@end deftypefn
discrete_inv
@c discrete_inv scripts/statistics/discrete_inv.m
@deftypefn {} {} discrete_inv (@var{x}, @var{v}, @var{p})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the univariate distribution which assumes the values in
@var{v} with probabilities @var{p}.
@end deftypefn
discrete_pdf
@c discrete_pdf scripts/statistics/discrete_pdf.m
@deftypefn {} {} discrete_pdf (@var{x}, @var{v}, @var{p})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of a univariate discrete distribution which assumes the values
in @var{v} with probabilities @var{p}.
@end deftypefn
discrete_rnd
@c discrete_rnd scripts/statistics/discrete_rnd.m
@deftypefn  {} {} discrete_rnd (@var{v}, @var{p})
@deftypefnx {} {} discrete_rnd (@var{v}, @var{p}, @var{r})
@deftypefnx {} {} discrete_rnd (@var{v}, @var{p}, @var{r}, @var{c}, @dots{})
@deftypefnx {} {} discrete_rnd (@var{v}, @var{p}, [@var{sz}])
Return a matrix of random samples from the univariate distribution which
assumes the values in @var{v} with probabilities @var{p}.

When called with a single size 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 size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{v} and @var{p}.
@end deftypefn
empirical_cdf
@c empirical_cdf scripts/statistics/empirical_cdf.m
@deftypefn {} {} empirical_cdf (@var{x}, @var{data})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the empirical distribution obtained from
the univariate sample @var{data}.
@end deftypefn
empirical_inv
@c empirical_inv scripts/statistics/empirical_inv.m
@deftypefn {} {} empirical_inv (@var{x}, @var{data})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the empirical distribution obtained from the
univariate sample @var{data}.
@end deftypefn
empirical_pdf
@c empirical_pdf scripts/statistics/empirical_pdf.m
@deftypefn {} {} empirical_pdf (@var{x}, @var{data})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the empirical distribution obtained from the
univariate sample @var{data}.
@end deftypefn
empirical_rnd
@c empirical_rnd scripts/statistics/empirical_rnd.m
@deftypefn  {} {} empirical_rnd (@var{data})
@deftypefnx {} {} empirical_rnd (@var{data}, @var{r})
@deftypefnx {} {} empirical_rnd (@var{data}, @var{r}, @var{c}, @dots{})
@deftypefnx {} {} empirical_rnd (@var{data}, [@var{sz}])
Return a matrix of random samples from the empirical distribution obtained
from the univariate sample @var{data}.

When called with a single size 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 size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is a random ordering
of the sample @var{data}.
@end deftypefn
histc
@c histc scripts/statistics/histc.m
@deftypefn  {} {@var{n} =} histc (@var{x}, @var{edges})
@deftypefnx {} {@var{n} =} histc (@var{x}, @var{edges}, @var{dim})
@deftypefnx {} {[@var{n}, @var{idx}] =} histc (@dots{})
Compute histogram counts.

When @var{x} is a vector, the function counts the number of elements of
@var{x} that fall in the histogram bins defined by @var{edges}.  This
must be a vector of monotonically increasing values that define the edges
of the histogram bins.
@tex
$n(k)$
@end tex
@ifnottex
@code{@var{n}(k)}
@end ifnottex
contains the number of elements in @var{x} for which
@tex
$@var{edges}(k) <= @var{x} < @var{edges}(k+1)$.
@end tex
@ifnottex
@code{@var{edges}(k) <= @var{x} < @var{edges}(k+1)}.
@end ifnottex
The final element of @var{n} contains the number of elements of @var{x}
exactly equal to the last element of @var{edges}.

When @var{x} is an @math{N}-dimensional array, the computation is carried
out along dimension @var{dim}.  If not specified @var{dim} defaults to the
first non-singleton dimension.

When a second output argument is requested an index matrix is also returned.
The @var{idx} matrix has the same size as @var{x}.  Each element of
@var{idx} contains the index of the histogram bin in which the
corresponding element of @var{x} was counted.
@xseealso{hist}
@end deftypefn
iqr
@c iqr scripts/statistics/iqr.m
@deftypefn  {} {} iqr (@var{x})
@deftypefnx {} {} iqr (@var{x}, @var{dim})
Return the interquartile range, i.e., the difference between the upper
and lower quartile of the input data.

If @var{x} is a matrix, do the above for first non-singleton dimension of
@var{x}.

If the optional argument @var{dim} is given, operate along this dimension.

As a measure of dispersion, the interquartile range is less affected by
outliers than either @code{range} or @code{std}.
@xseealso{bounds, mad, range, std}
@end deftypefn
kendall
@c kendall scripts/statistics/kendall.m
@deftypefn  {} {} kendall (@var{x})
@deftypefnx {} {} kendall (@var{x}, @var{y})
@cindex Kendall's Tau
Compute Kendall's
@tex
$\tau$.
@end tex
@ifnottex
@var{tau}.
@end ifnottex

For two data vectors @var{x}, @var{y} of common length @math{N}, Kendall's
@tex
$\tau$
@end tex
@ifnottex
@var{tau}
@end ifnottex
is the correlation of the signs of all rank differences of
@var{x} and @var{y}; i.e., if both @var{x} and @var{y} have distinct
entries, then

@tex
$$ \tau = {1 \over N(N-1)} \sum_{i,j} {\rm sign}(q_i-q_j) \, {\rm sign}(r_i-r_j) $$
@end tex
@ifnottex

@example
@group
         1
@var{tau} = -------   SUM sign (@var{q}(i) - @var{q}(j)) * sign (@var{r}(i) - @var{r}(j))
      N (N-1)   i,j
@end group
@end example

@end ifnottex
@noindent
in which the
@tex
$q_i$ and $r_i$
@end tex
@ifnottex
@var{q}(i) and @var{r}(i)
@end ifnottex
are the ranks of @var{x} and @var{y}, respectively.

If @var{x} and @var{y} are drawn from independent distributions,
Kendall's
@tex
$\tau$
@end tex
@ifnottex
@var{tau}
@end ifnottex
is asymptotically normal with mean 0 and variance
@tex
${2 (2N+5) \over 9N(N-1)}$.
@end tex
@ifnottex
@code{(2 * (2N+5)) / (9 * N * (N-1))}.
@end ifnottex

@code{kendall (@var{x})} is equivalent to @code{kendall (@var{x},
@var{x})}.
@xseealso{ranks, spearman}
@end deftypefn
kurtosis
@c kurtosis scripts/statistics/kurtosis.m
@deftypefn  {} {} kurtosis (@var{x})
@deftypefnx {} {} kurtosis (@var{x}, @var{flag})
@deftypefnx {} {} kurtosis (@var{x}, @var{flag}, @var{dim})
Compute the sample kurtosis of the elements of @var{x}.

The sample kurtosis is defined as
@tex
$$
\kappa_1 = {{{1\over N}\,
         \sum_{i=1}^N (x_i - \bar{x})^4} \over \sigma^4},
$$
where $N$ is the length of @var{x}, $\bar{x}$ its mean, and $\sigma$
its (uncorrected) standard deviation.
@end tex
@ifnottex

@example
@group
     mean ((@var{x} - mean (@var{x})).^4)
k1 = ------------------------
            std (@var{x}).^4
@end group
@end example

@end ifnottex

@noindent
The optional argument @var{flag} controls which normalization is used.
If @var{flag} is equal to 1 (default value, used when @var{flag} is omitted
or empty), return the sample kurtosis as defined above.  If @var{flag} is
equal to 0, return the @w{"bias-corrected"} kurtosis coefficient instead:
@tex
$$
\kappa_0 = 3 + {\scriptstyle N - 1 \over \scriptstyle (N - 2)(N - 3)} \,
    \left( (N + 1)\, \kappa_1 - 3 (N - 1) \right)
$$
@end tex
@ifnottex

@example
@group
              N - 1
k0 = 3 + -------------- * ((N + 1) * k1 - 3 * (N - 1))
         (N - 2)(N - 3)
@end group
@end example

@noindent
where @math{N} is the length of the @var{x} vector.

@end ifnottex
The bias-corrected kurtosis coefficient is obtained by replacing the sample
second and fourth central moments by their unbiased versions.  It is an
unbiased estimate of the population kurtosis for normal populations.

If @var{x} is a matrix, or more generally a multi-dimensional array, return
the kurtosis along the first non-singleton dimension.  If the optional
@var{dim} argument is given, operate along this dimension.

@xseealso{var, skewness, moment}
@end deftypefn
mad
@c mad scripts/statistics/mad.m
@deftypefn  {} {} mad (@var{x})
@deftypefnx {} {} mad (@var{x}, @var{opt})
@deftypefnx {} {} mad (@var{x}, @var{opt}, @var{dim})
Compute the mean or median absolute deviation of the elements of @var{x}.

The mean absolute deviation is defined as

@example
@var{mad} = mean (abs (@var{x} - mean (@var{x})))
@end example

The median absolute deviation is defined as

@example
@var{mad} = median (abs (@var{x} - median (@var{x})))
@end example

If @var{x} is a matrix, compute @code{mad} for each column and return
results in a row vector.  For a multi-dimensional array, the calculation is
done over the first non-singleton dimension.

The optional argument @var{opt} determines whether mean or median absolute
deviation is calculated.  The default is 0 which corresponds to mean
absolute deviation; A value of 1 corresponds to median absolute deviation.

If the optional argument @var{dim} is given, operate along this dimension.

As a measure of dispersion, @code{mad} is less affected by outliers than
@code{std}.
@xseealso{bounds, range, iqr, std, mean, median}
@end deftypefn
mean
@c mean scripts/statistics/mean.m
@deftypefn  {} {} mean (@var{x})
@deftypefnx {} {} mean (@var{x}, @var{dim})
@deftypefnx {} {} mean (@var{x}, @var{opt})
@deftypefnx {} {} mean (@var{x}, @var{dim}, @var{opt})
@deftypefnx {} {} mean (@dots{}, @var{outtype})
Compute the mean of the elements of the vector @var{x}.

The mean is defined as

@tex
$$ {\rm mean}(x) = \bar{x} = {1\over N} \sum_{i=1}^N x_i $$
where $N$ is the number of elements of @var{x}.

@end tex
@ifnottex

@example
mean (@var{x}) = SUM_i @var{x}(i) / N
@end example

@noindent
where @math{N} is the length of the @var{x} vector.

@end ifnottex
If @var{x} is a matrix, compute the mean for each column and return them
in a row vector.

If the optional argument @var{dim} is given, operate along this dimension.

The optional argument @var{opt} selects the type of mean to compute.
The following options are recognized:

@table @asis
@item @qcode{"a"}
Compute the (ordinary) arithmetic mean.  [default]

@item @qcode{"g"}
Compute the geometric mean.

@item @qcode{"h"}
Compute the harmonic mean.
@end table

The optional argument @var{outtype} selects the data type of the
output value.  The following options are recognized:

@table @asis
@item @qcode{"default"}
Output will be of class double unless @var{x} is of class single,
in which case the output will also be single.

@item @qcode{"double"}
Output will be of class double.

@item @qcode{"native"}
Output will be the same class as @var{x} unless @var{x} is of class
logical in which case it returns of class double.

@end table

Both @var{dim} and @var{opt} are optional.  If both are supplied, either
may appear first.
@xseealso{median, mode}
@end deftypefn
meansq
@c meansq scripts/statistics/meansq.m
@deftypefn  {} {} meansq (@var{x})
@deftypefnx {} {} meansq (@var{x}, @var{dim})
Compute the mean square of the elements of the vector @var{x}.

The mean square is defined as
@tex
$$
{\rm meansq} (x) = {\sum_{i=1}^N {x_i}^2 \over N}
$$
where $N$ is the number of elements of @var{x}.

@end tex
@ifnottex

@example
@group
meansq (@var{x}) = 1/N SUM_i @var{x}(i)^2
@end group
@end example

@noindent
where @math{N} is the length of the @var{x} vector.

@end ifnottex
If @var{x} is a matrix, return a row vector containing the mean square
of each column.

If the optional argument @var{dim} is given, operate along this dimension.
@xseealso{var, std, moment}
@end deftypefn
median
@c median scripts/statistics/median.m
@deftypefn  {} {} median (@var{x})
@deftypefnx {} {} median (@var{x}, @var{dim})
Compute the median value of the elements of the vector @var{x}.

When the elements of @var{x} are sorted, say
@code{@var{s} = sort (@var{x})}, the median is defined as
@tex
$$
{\rm median} (x) =
  \cases{s(\lceil N/2\rceil), & $N$ odd;\cr
          (s(N/2)+s(N/2+1))/2, & $N$ even.}
$$
where $N$ is the number of elements of @var{x}.

@end tex
@ifnottex

@example
@group
             |  @var{s}(ceil(N/2))           N odd
median (@var{x}) = |
             | (@var{s}(N/2) + @var{s}(N/2+1))/2   N even
@end group
@end example

@end ifnottex
If @var{x} is of a discrete type such as integer or logical, then
the case of even @math{N} rounds up (or toward @code{true}).

If @var{x} is a matrix, compute the median value for each column and
return them in a row vector.

If the optional @var{dim} argument is given, operate along this dimension.
@xseealso{mean, mode}
@end deftypefn
mode
@c mode scripts/statistics/mode.m
@deftypefn  {} {} mode (@var{x})
@deftypefnx {} {} mode (@var{x}, @var{dim})
@deftypefnx {} {[@var{m}, @var{f}, @var{c}] =} mode (@dots{})
Compute the most frequently occurring value in a dataset (mode).

@code{mode} determines the frequency of values along the first non-singleton
dimension and returns the value with the highest frequency.  If two, or
more, values have the same frequency @code{mode} returns the smallest.

If the optional argument @var{dim} is given, operate along this dimension.

The return variable @var{f} is the number of occurrences of the mode in
the dataset.

The cell array @var{c} contains all of the elements with the maximum
frequency.
@xseealso{mean, median}
@end deftypefn
moment
@c moment scripts/statistics/moment.m
@deftypefn  {} {} moment (@var{x}, @var{p})
@deftypefnx {} {} moment (@var{x}, @var{p}, @var{type})
@deftypefnx {} {} moment (@var{x}, @var{p}, @var{dim})
@deftypefnx {} {} moment (@var{x}, @var{p}, @var{type}, @var{dim})
@deftypefnx {} {} moment (@var{x}, @var{p}, @var{dim}, @var{type})
Compute the @var{p}-th central moment of the vector @var{x}.

The @var{p}-th central moment of @var{x} is defined as:

@tex
$$
{\sum_{i=1}^N (x_i - \bar{x})^p \over N}
$$
where $\bar{x}$ is the mean value of @var{x} and $N$ is the number of elements of @var{x}.


@end tex
@ifnottex

@example
@group
1/N SUM_i (@var{x}(i) - mean(@var{x}))^@var{p}
@end group
@end example

@noindent
where @math{N} is the length of the @var{x} vector.

@end ifnottex

If @var{x} is a matrix, return the row vector containing the @var{p}-th
central moment of each column.

If the optional argument @var{dim} is given, operate along this dimension.

The optional string @var{type} specifies the type of moment to be computed.
Valid options are:

@table @asis
@item @qcode{"c"}
  Central Moment (default).

@item  @qcode{"a"}
@itemx @qcode{"ac"}
  Absolute Central Moment.  The moment about the mean ignoring sign
defined as
@tex
$$
{\sum_{i=1}^N {\left| x_i - \bar{x} \right|}^p \over N}
$$
@end tex
@ifnottex

@example
@group
1/N SUM_i (abs (@var{x}(i) - mean(@var{x})))^@var{p}
@end group
@end example

@end ifnottex

@item @qcode{"r"}
  Raw Moment.  The moment about zero defined as

@tex
$$
{\rm moment} (x) = { \sum_{i=1}^N {x_i}^p \over N }
$$
@end tex
@ifnottex

@example
@group
moment (@var{x}) = 1/N SUM_i @var{x}(i)^@var{p}
@end group
@end example

@end ifnottex

@item @nospell{@qcode{"ar"}}
  Absolute Raw Moment.  The moment about zero ignoring sign defined as
@tex
$$
{\sum_{i=1}^N {\left| x_i \right|}^p \over N}
$$
@end tex
@ifnottex

@example
@group
1/N SUM_i ( abs (@var{x}(i)) )^@var{p}
@end group
@end example

@end ifnottex
@end table

If both @var{type} and @var{dim} are given they may appear in any order.
@xseealso{var, skewness, kurtosis}
@end deftypefn
movmad
@c movmad scripts/statistics/movmad.m
@deftypefn  {} {@var{y} =} movmad (@var{x}, @var{wlen})
@deftypefnx {} {@var{y} =} movmad (@var{x}, [@var{na}, @var{nb}])
@deftypefnx {} {@var{y} =} movmad (@dots{}, @var{dim})
@deftypefnx {} {@var{y} =} movmad (@dots{}, "@var{nancond}")
@deftypefnx {} {@var{y} =} movmad (@dots{}, @var{property}, @var{value})
Calculate the moving mean absolute deviation over a sliding window of length
@var{wlen} on data @var{x}.

If @var{wlen} is a scalar, the function @code{mad} is applied to a
moving window of length @var{wlen}.  When @var{wlen} is an odd number the
window is symmetric and includes @w{@code{(@var{wlen} - 1) / 2}} elements on
either side of the central element.  For example, when calculating the
output at index 5 with a window length of 3, @code{movmad} uses data
elements @w{@code{[4, 5, 6]}}.  If @var{wlen} is an even number, the window
is asymmetric and has @w{@code{@var{wlen}/2}} elements to the left of the
central element and @w{@code{@var{wlen}/2 - 1}} elements to the right of the
central element.  For example, when calculating the output at index 5 with a
window length of 4, @code{movmad} uses data elements
@w{@code{[3, 4, 5, 6]}}.

If @var{wlen} is an array with two elements @w{@code{[@var{nb}, @var{na}]}},
the function is applied to a moving window @code{-@var{nb}:@var{na}}.  This
window includes @var{nb} number of elements @emph{before} the current
element and @var{na} number of elements @emph{after} the current element.
The current element is always included.  For example, given
@w{@code{@var{wlen} = [3, 0]}}, the data used to calculate index 5 is
@w{@code{[2, 3, 4, 5]}}.

If the optional argument @var{dim} is given, operate along this dimension.

The optional string argument @qcode{"@var{nancond}"} controls whether
@code{NaN} and @code{NA} values should be included (@qcode{"includenan"}),
or excluded (@qcode{"omitnan"}), from the data passed to @code{mad}.  The
default is @qcode{"includenan"}.  Caution: the @qcode{"omitnan"} option is
not yet implemented.

The calculation can be controlled by specifying @var{property}/@var{value}
pairs.  Valid properties are

@table @asis

@item @qcode{"Endpoints"}

This property controls how results are calculated at the boundaries
(@w{endpoints}) of the window.  Possible values are:

@table @asis
@item @qcode{"shrink"}  (default)
The window is truncated at the beginning and end of the array to exclude
elements for which there is no source data.  For example, with a window of
length 3, @code{@var{y}(1) = mad (@var{x}(1:2))}, and
@code{@var{y}(end) = mad (@var{x}(end-1:end))}.

@item @qcode{"discard"}
Any @var{y} values that use a window extending beyond the original
data array are deleted.  For example, with a 10-element data vector and a
window of length 3, the output will contain only 8 elements.  The first
element would require calculating the function over indices
@w{@code{[0, 1, 2]}} and is therefore discarded.  The last element would
require calculating the function over indices @w{@code{[9, 10, 11]}} and is
therefore discarded.

@item @qcode{"fill"}
Any window elements outside the data array are replaced by @code{NaN}.  For
example, with a window of length 3,
@code{@var{y}(1) = mad ([NaN, @var{x}(1:2)])}, and
@code{@var{y}(end) = mad ([@var{x}(end-1:end), NaN])}.
This option usually results in @var{y} having @code{NaN} values at the
boundaries, although it is influenced by how @code{mad} handles @code{NaN},
and also by the property @qcode{"nancond"}.

@item @var{user_value}
Any window elements outside the data array are replaced by the specified
value @var{user_value} which must be a numeric scalar.  For example, with a
window of length 3,
@code{@var{y}(1) = mad ([@var{user_value}, @var{x}(1:2)])}, and
@code{@var{y}(end) = mad ([@var{x}(end-1:end), @var{user_value}])}.
A common choice for @var{user_value} is 0.

@item @qcode{"same"}
Any window elements outside the data array are replaced by the value of
@var{x} at the boundary.  For example, with a window of length 3,
@code{@var{y}(1) = mad ([@var{x}(1), @var{x}(1:2)])}, and
@code{@var{y}(end) = mad ([@var{x}(end-1:end), @var{x}(end)])}.

@item @qcode{"periodic"}
The window is wrapped so that any missing data elements are taken from
the other side of the data.  For example, with a window of length 3,
@code{@var{y}(1) = mad ([@var{x}(end), @var{x}(1:2)])}, and
@code{@var{y}(end) = mad ([@var{x}(end-1:end), @var{x}(1)])}.

@end table

@item @qcode{"SamplePoints"}
Caution: This option is not yet implemented.

@end table

Programming Note: This function is a wrapper which calls @code{movfun}.
For additional options and documentation, @xref{XREFmovfun,,movfun}.

@xseealso{movfun, movslice, movmax, movmean, movmedian, movmin, movprod, movstd, movsum, movvar}
@end deftypefn
movmax
@c movmax scripts/statistics/movmax.m
@deftypefn  {} {@var{y} =} movmax (@var{x}, @var{wlen})
@deftypefnx {} {@var{y} =} movmax (@var{x}, [@var{na}, @var{nb}])
@deftypefnx {} {@var{y} =} movmax (@dots{}, @var{dim})
@deftypefnx {} {@var{y} =} movmax (@dots{}, "@var{nancond}")
@deftypefnx {} {@var{y} =} movmax (@dots{}, @var{property}, @var{value})
Calculate the moving maximum over a sliding window of length @var{wlen} on
data @var{x}.

If @var{wlen} is a scalar, the function @code{max} is applied to a
moving window of length @var{wlen}.  When @var{wlen} is an odd number the
window is symmetric and includes @w{@code{(@var{wlen} - 1) / 2}} elements on
either side of the central element.  For example, when calculating the
output at index 5 with a window length of 3, @code{movmax} uses data
elements @w{@code{[4, 5, 6]}}.  If @var{wlen} is an even number, the window
is asymmetric and has @w{@code{@var{wlen}/2}} elements to the left of the
central element and @w{@code{@var{wlen}/2 - 1}} elements to the right of the
central element.  For example, when calculating the output at index 5 with a
window length of 4, @code{movmax} uses data elements
@w{@code{[3, 4, 5, 6]}}.

If @var{wlen} is an array with two elements @w{@code{[@var{nb}, @var{na}]}},
the function is applied to a moving window @code{-@var{nb}:@var{na}}.  This
window includes @var{nb} number of elements @emph{before} the current
element and @var{na} number of elements @emph{after} the current element.
The current element is always included.  For example, given
@w{@code{@var{wlen} = [3, 0]}}, the data used to calculate index 5 is
@w{@code{[2, 3, 4, 5]}}.

If the optional argument @var{dim} is given, operate along this dimension.

The optional string argument @qcode{"@var{nancond}"} controls whether
@code{NaN} and @code{NA} values should be included (@qcode{"includenan"}),
or excluded (@qcode{"omitnan"}), from the data passed to @code{max}.  The
default is @qcode{"includenan"}.  Caution: the @qcode{"omitnan"} option is
not yet implemented.

The calculation can be controlled by specifying @var{property}/@var{value}
pairs.  Valid properties are

@table @asis

@item @qcode{"Endpoints"}

This property controls how results are calculated at the boundaries
(@w{endpoints}) of the window.  Possible values are:

@table @asis
@item @qcode{"shrink"}  (default)
The window is truncated at the beginning and end of the array to exclude
elements for which there is no source data.  For example, with a window of
length 3, @code{@var{y}(1) = max (@var{x}(1:2))}, and
@code{@var{y}(end) = max (@var{x}(end-1:end))}.

@item @qcode{"discard"}
Any @var{y} values that use a window extending beyond the original
data array are deleted.  For example, with a 10-element data vector and a
window of length 3, the output will contain only 8 elements.  The first
element would require calculating the function over indices
@w{@code{[0, 1, 2]}} and is therefore discarded.  The last element would
require calculating the function over indices @w{@code{[9, 10, 11]}} and is
therefore discarded.

@item @qcode{"fill"}
Any window elements outside the data array are replaced by @code{NaN}.  For
example, with a window of length 3,
@code{@var{y}(1) = max ([NaN, @var{x}(1:2)])}, and
@code{@var{y}(end) = max ([@var{x}(end-1:end), NaN])}.
This option usually results in @var{y} having @code{NaN} values at the
boundaries, although it is influenced by how @code{max} handles @code{NaN},
and also by the property @qcode{"nancond"}.

@item @var{user_value}
Any window elements outside the data array are replaced by the specified
value @var{user_value} which must be a numeric scalar.  For example, with a
window of length 3,
@code{@var{y}(1) = max ([@var{user_value}, @var{x}(1:2)])}, and
@code{@var{y}(end) = max ([@var{x}(end-1:end), @var{user_value}])}.
A common choice for @var{user_value} is 0.

@item @qcode{"same"}
Any window elements outside the data array are replaced by the value of
@var{x} at the boundary.  For example, with a window of length 3,
@code{@var{y}(1) = max ([@var{x}(1), @var{x}(1:2)])}, and
@code{@var{y}(end) = max ([@var{x}(end-1:end), @var{x}(end)])}.

@item @qcode{"periodic"}
The window is wrapped so that any missing data elements are taken from
the other side of the data.  For example, with a window of length 3,
@code{@var{y}(1) = max ([@var{x}(end), @var{x}(1:2)])}, and
@code{@var{y}(end) = max ([@var{x}(end-1:end), @var{x}(1)])}.

@end table

@item @qcode{"SamplePoints"}
Caution: This option is not yet implemented.

@end table

Programming Note: This function is a wrapper which calls @code{movfun}.
For additional options and documentation, @xref{XREFmovfun,,movfun}.

@xseealso{movfun, movslice, movmad, movmean, movmedian, movmin, movprod, movstd, movsum, movvar}
@end deftypefn
movmean
@c movmean scripts/statistics/movmean.m
@deftypefn  {} {@var{y} =} movmean (@var{x}, @var{wlen})
@deftypefnx {} {@var{y} =} movmean (@var{x}, [@var{na}, @var{nb}])
@deftypefnx {} {@var{y} =} movmean (@dots{}, @var{dim})
@deftypefnx {} {@var{y} =} movmean (@dots{}, "@var{nancond}")
@deftypefnx {} {@var{y} =} movmean (@dots{}, @var{property}, @var{value})
Calculate the moving average over a sliding window of length @var{wlen} on
data @var{x}.

If @var{wlen} is a scalar, the function @code{mean} is applied to a
moving window of length @var{wlen}.  When @var{wlen} is an odd number the
window is symmetric and includes @w{@code{(@var{wlen} - 1) / 2}} elements on
either side of the central element.  For example, when calculating the
output at index 5 with a window length of 3, @code{movmean} uses data
elements @w{@code{[4, 5, 6]}}.  If @var{wlen} is an even number, the window
is asymmetric and has @w{@code{@var{wlen}/2}} elements to the left of the
central element and @w{@code{@var{wlen}/2 - 1}} elements to the right of the
central element.  For example, when calculating the output at index 5 with a
window length of 4, @code{movmean} uses data elements
@w{@code{[3, 4, 5, 6]}}.

If @var{wlen} is an array with two elements @w{@code{[@var{nb}, @var{na}]}},
the function is applied to a moving window @code{-@var{nb}:@var{na}}.  This
window includes @var{nb} number of elements @emph{before} the current
element and @var{na} number of elements @emph{after} the current element.
The current element is always included.  For example, given
@w{@code{@var{wlen} = [3, 0]}}, the data used to calculate index 5 is
@w{@code{[2, 3, 4, 5]}}.

If the optional argument @var{dim} is given, operate along this dimension.

The optional string argument @qcode{"@var{nancond}"} controls whether
@code{NaN} and @code{NA} values should be included (@qcode{"includenan"}),
or excluded (@qcode{"omitnan"}), from the data passed to @code{mean}.  The
default is @qcode{"includenan"}.  Caution: the @qcode{"omitnan"} option is
not yet implemented.

The calculation can be controlled by specifying @var{property}/@var{value}
pairs.  Valid properties are

@table @asis

@item @qcode{"Endpoints"}

This property controls how results are calculated at the boundaries
(@w{endpoints}) of the window.  Possible values are:

@table @asis
@item @qcode{"shrink"}  (default)
The window is truncated at the beginning and end of the array to exclude
elements for which there is no source data.  For example, with a window of
length 3, @code{@var{y}(1) = mean (@var{x}(1:2))}, and
@code{@var{y}(end) = mean (@var{x}(end-1:end))}.

@item @qcode{"discard"}
Any @var{y} values that use a window extending beyond the original
data array are deleted.  For example, with a 10-element data vector and a
window of length 3, the output will contain only 8 elements.  The first
element would require calculating the function over indices
@w{@code{[0, 1, 2]}} and is therefore discarded.  The last element would
require calculating the function over indices @w{@code{[9, 10, 11]}} and is
therefore discarded.

@item @qcode{"fill"}
Any window elements outside the data array are replaced by @code{NaN}.  For
example, with a window of length 3,
@code{@var{y}(1) = mean ([NaN, @var{x}(1:2)])}, and
@code{@var{y}(end) = mean ([@var{x}(end-1:end), NaN])}.
This option usually results in @var{y} having @code{NaN} values at the
boundaries, although it is influenced by how @code{mean} handles @code{NaN},
and also by the property @qcode{"nancond"}.

@item @var{user_value}
Any window elements outside the data array are replaced by the specified
value @var{user_value} which must be a numeric scalar.  For example, with a
window of length 3,
@code{@var{y}(1) = mean ([@var{user_value}, @var{x}(1:2)])}, and
@code{@var{y}(end) = mean ([@var{x}(end-1:end), @var{user_value}])}.
A common choice for @var{user_value} is 0.

@item @qcode{"same"}
Any window elements outside the data array are replaced by the value of
@var{x} at the boundary.  For example, with a window of length 3,
@code{@var{y}(1) = mean ([@var{x}(1), @var{x}(1:2)])}, and
@code{@var{y}(end) = mean ([@var{x}(end-1:end), @var{x}(end)])}.

@item @qcode{"periodic"}
The window is wrapped so that any missing data elements are taken from
the other side of the data.  For example, with a window of length 3,
@code{@var{y}(1) = mean ([@var{x}(end), @var{x}(1:2)])}, and
@code{@var{y}(end) = mean ([@var{x}(end-1:end), @var{x}(1)])}.

@end table

@item @qcode{"SamplePoints"}
Caution: This option is not yet implemented.

@end table

Programming Note: This function is a wrapper which calls @code{movfun}.
For additional options and documentation, @xref{XREFmovfun,,movfun}.

@xseealso{movfun, movslice, movmad, movmax, movmedian, movmin, movprod, movstd, movsum, movvar}
@end deftypefn
movmedian
@c movmedian scripts/statistics/movmedian.m
@deftypefn  {} {@var{y} =} movmedian (@var{x}, @var{wlen})
@deftypefnx {} {@var{y} =} movmedian (@var{x}, [@var{na}, @var{nb}])
@deftypefnx {} {@var{y} =} movmedian (@dots{}, @var{dim})
@deftypefnx {} {@var{y} =} movmedian (@dots{}, "@var{nancond}")
@deftypefnx {} {@var{y} =} movmedian (@dots{}, @var{property}, @var{value})
Calculate the moving median over a sliding window of length @var{wlen} on
data @var{x}.

If @var{wlen} is a scalar, the function @code{movmedian} is applied to a
moving window of length @var{wlen}.  When @var{wlen} is an odd number the
window is symmetric and includes @w{@code{(@var{wlen} - 1) / 2}} elements on
either side of the central element.  For example, when calculating the
output at index 5 with a window length of 3, @code{movmedian} uses data
elements @w{@code{[4, 5, 6]}}.  If @var{wlen} is an even number, the window
is asymmetric and has @w{@code{@var{wlen}/2}} elements to the left of the
central element and @w{@code{@var{wlen}/2 - 1}} elements to the right of the
central element.  For example, when calculating the output at index 5 with a
window length of 4, @code{movmedian} uses data elements
@w{@code{[3, 4, 5, 6]}}.

If @var{wlen} is an array with two elements @w{@code{[@var{nb}, @var{na}]}},
the function is applied to a moving window @code{-@var{nb}:@var{na}}.  This
window includes @var{nb} number of elements @emph{before} the current
element and @var{na} number of elements @emph{after} the current element.
The current element is always included.  For example, given
@w{@code{@var{wlen} = [3, 0]}}, the data used to calculate index 5 is
@w{@code{[2, 3, 4, 5]}}.

If the optional argument @var{dim} is given, operate along this dimension.

The optional string argument @qcode{"@var{nancond}"} controls whether
@code{NaN} and @code{NA} values should be included (@qcode{"includenan"}),
or excluded (@qcode{"omitnan"}), from the data passed to @code{movmedian}.  The
default is @qcode{"includenan"}.  Caution: the @qcode{"omitnan"} option is
not yet implemented.

The calculation can be controlled by specifying @var{property}/@var{value}
pairs.  Valid properties are

@table @asis

@item @qcode{"Endpoints"}

This property controls how results are calculated at the boundaries
(@w{endpoints}) of the window.  Possible values are:

@table @asis
@item @qcode{"shrink"}  (default)
The window is truncated at the beginning and end of the array to exclude
elements for which there is no source data.  For example, with a window of
length 3, @code{@var{y}(1) = movmedian (@var{x}(1:2))}, and
@code{@var{y}(end) = movmedian (@var{x}(end-1:end))}.

@item @qcode{"discard"}
Any @var{y} values that use a window extending beyond the original
data array are deleted.  For example, with a 10-element data vector and a
window of length 3, the output will contain only 8 elements.  The first
element would require calculating the function over indices
@w{@code{[0, 1, 2]}} and is therefore discarded.  The last element would
require calculating the function over indices @w{@code{[9, 10, 11]}} and is
therefore discarded.

@item @qcode{"fill"}
Any window elements outside the data array are replaced by @code{NaN}.  For
example, with a window of length 3,
@code{@var{y}(1) = movmedian ([NaN, @var{x}(1:2)])}, and
@code{@var{y}(end) = movmedian ([@var{x}(end-1:end), NaN])}.
This option usually results in @var{y} having @code{NaN} values at the
boundaries, although it is influenced by how @code{movmedian} handles @code{NaN},
and also by the property @qcode{"nancond"}.

@item @var{user_value}
Any window elements outside the data array are replaced by the specified
value @var{user_value} which must be a numeric scalar.  For example, with a
window of length 3,
@code{@var{y}(1) = movmedian ([@var{user_value}, @var{x}(1:2)])}, and
@code{@var{y}(end) = movmedian ([@var{x}(end-1:end), @var{user_value}])}.
A common choice for @var{user_value} is 0.

@item @qcode{"same"}
Any window elements outside the data array are replaced by the value of
@var{x} at the boundary.  For example, with a window of length 3,
@code{@var{y}(1) = movmedian ([@var{x}(1), @var{x}(1:2)])}, and
@code{@var{y}(end) = movmedian ([@var{x}(end-1:end), @var{x}(end)])}.

@item @qcode{"periodic"}
The window is wrapped so that any missing data elements are taken from
the other side of the data.  For example, with a window of length 3,
@code{@var{y}(1) = movmedian ([@var{x}(end), @var{x}(1:2)])}, and
@code{@var{y}(end) = movmedian ([@var{x}(end-1:end), @var{x}(1)])}.

@end table

@item @qcode{"SamplePoints"}
Caution: This option is not yet implemented.

@end table

Programming Note: This function is a wrapper which calls @code{movfun}.
For additional options and documentation, @xref{XREFmovfun,,movfun}.

@xseealso{movfun, movslice, movmad, movmax, movmean, movmin, movprod, movstd, movsum, movvar}
@end deftypefn
movmin
@c movmin scripts/statistics/movmin.m
@deftypefn  {} {@var{y} =} movmin (@var{x}, @var{wlen})
@deftypefnx {} {@var{y} =} movmin (@var{x}, [@var{na}, @var{nb}])
@deftypefnx {} {@var{y} =} movmin (@dots{}, @var{dim})
@deftypefnx {} {@var{y} =} movmin (@dots{}, "@var{nancond}")
@deftypefnx {} {@var{y} =} movmin (@dots{}, @var{property}, @var{value})
Calculate the moving minimum over a sliding window of length @var{wlen} on
data @var{x}.

If @var{wlen} is a scalar, the function @code{min} is applied to a
moving window of length @var{wlen}.  When @var{wlen} is an odd number the
window is symmetric and includes @w{@code{(@var{wlen} - 1) / 2}} elements on
either side of the central element.  For example, when calculating the
output at index 5 with a window length of 3, @code{movmin} uses data
elements @w{@code{[4, 5, 6]}}.  If @var{wlen} is an even number, the window
is asymmetric and has @w{@code{@var{wlen}/2}} elements to the left of the
central element and @w{@code{@var{wlen}/2 - 1}} elements to the right of the
central element.  For example, when calculating the output at index 5 with a
window length of 4, @code{movmin} uses data elements
@w{@code{[3, 4, 5, 6]}}.

If @var{wlen} is an array with two elements @w{@code{[@var{nb}, @var{na}]}},
the function is applied to a moving window @code{-@var{nb}:@var{na}}.  This
window includes @var{nb} number of elements @emph{before} the current
element and @var{na} number of elements @emph{after} the current element.
The current element is always included.  For example, given
@w{@code{@var{wlen} = [3, 0]}}, the data used to calculate index 5 is
@w{@code{[2, 3, 4, 5]}}.

If the optional argument @var{dim} is given, operate along this dimension.

The optional string argument @qcode{"@var{nancond}"} controls whether
@code{NaN} and @code{NA} values should be included (@qcode{"includenan"}),
or excluded (@qcode{"omitnan"}), from the data passed to @code{min}.  The
default is @qcode{"includenan"}.  Caution: the @qcode{"omitnan"} option is
not yet implemented.

The calculation can be controlled by specifying @var{property}/@var{value}
pairs.  Valid properties are

@table @asis

@item @qcode{"Endpoints"}

This property controls how results are calculated at the boundaries
(@w{endpoints}) of the window.  Possible values are:

@table @asis
@item @qcode{"shrink"}  (default)
The window is truncated at the beginning and end of the array to exclude
elements for which there is no source data.  For example, with a window of
length 3, @code{@var{y}(1) = min (@var{x}(1:2))}, and
@code{@var{y}(end) = min (@var{x}(end-1:end))}.

@item @qcode{"discard"}
Any @var{y} values that use a window extending beyond the original
data array are deleted.  For example, with a 10-element data vector and a
window of length 3, the output will contain only 8 elements.  The first
element would require calculating the function over indices
@w{@code{[0, 1, 2]}} and is therefore discarded.  The last element would
require calculating the function over indices @w{@code{[9, 10, 11]}} and is
therefore discarded.

@item @qcode{"fill"}
Any window elements outside the data array are replaced by @code{NaN}.  For
example, with a window of length 3,
@code{@var{y}(1) = min ([NaN, @var{x}(1:2)])}, and
@code{@var{y}(end) = min ([@var{x}(end-1:end), NaN])}.
This option usually results in @var{y} having @code{NaN} values at the
boundaries, although it is influenced by how @code{min} handles @code{NaN},
and also by the property @qcode{"nancond"}.

@item @var{user_value}
Any window elements outside the data array are replaced by the specified
value @var{user_value} which must be a numeric scalar.  For example, with a
window of length 3,
@code{@var{y}(1) = min ([@var{user_value}, @var{x}(1:2)])}, and
@code{@var{y}(end) = min ([@var{x}(end-1:end), @var{user_value}])}.
A common choice for @var{user_value} is 0.

@item @qcode{"same"}
Any window elements outside the data array are replaced by the value of
@var{x} at the boundary.  For example, with a window of length 3,
@code{@var{y}(1) = min ([@var{x}(1), @var{x}(1:2)])}, and
@code{@var{y}(end) = min ([@var{x}(end-1:end), @var{x}(end)])}.

@item @qcode{"periodic"}
The window is wrapped so that any missing data elements are taken from
the other side of the data.  For example, with a window of length 3,
@code{@var{y}(1) = min ([@var{x}(end), @var{x}(1:2)])}, and
@code{@var{y}(end) = min ([@var{x}(end-1:end), @var{x}(1)])}.

@end table

@item @qcode{"SamplePoints"}
Caution: This option is not yet implemented.

@end table

Programming Note: This function is a wrapper which calls @code{movfun}.
For additional options and documentation, @xref{XREFmovfun,,movfun}.

@xseealso{movfun, movslice, movmad, movmax, movmean, movmedian, movprod, movstd, movsum, movvar}
@end deftypefn
movprod
@c movprod scripts/statistics/movprod.m
@deftypefn  {} {@var{y} =} movprod (@var{x}, @var{wlen})
@deftypefnx {} {@var{y} =} movprod (@var{x}, [@var{na}, @var{nb}])
@deftypefnx {} {@var{y} =} movprod (@dots{}, @var{dim})
@deftypefnx {} {@var{y} =} movprod (@dots{}, "@var{nancond}")
@deftypefnx {} {@var{y} =} movprod (@dots{}, @var{property}, @var{value})
Calculate the moving product over a sliding window of length @var{wlen} on
data @var{x}.

If @var{wlen} is a scalar, the function @code{movprod} is applied to a
moving window of length @var{wlen}.  When @var{wlen} is an odd number the
window is symmetric and includes @w{@code{(@var{wlen} - 1) / 2}} elements on
either side of the central element.  For example, when calculating the
output at index 5 with a window length of 3, @code{movprod} uses data
elements @w{@code{[4, 5, 6]}}.  If @var{wlen} is an even number, the window
is asymmetric and has @w{@code{@var{wlen}/2}} elements to the left of the
central element and @w{@code{@var{wlen}/2 - 1}} elements to the right of the
central element.  For example, when calculating the output at index 5 with a
window length of 4, @code{movprod} uses data elements
@w{@code{[3, 4, 5, 6]}}.

If @var{wlen} is an array with two elements @w{@code{[@var{nb}, @var{na}]}},
the function is applied to a moving window @code{-@var{nb}:@var{na}}.  This
window includes @var{nb} number of elements @emph{before} the current
element and @var{na} number of elements @emph{after} the current element.
The current element is always included.  For example, given
@w{@code{@var{wlen} = [3, 0]}}, the data used to calculate index 5 is
@w{@code{[2, 3, 4, 5]}}.

If the optional argument @var{dim} is given, operate along this dimension.

The optional string argument @qcode{"@var{nancond}"} controls whether
@code{NaN} and @code{NA} values should be included (@qcode{"includenan"}),
or excluded (@qcode{"omitnan"}), from the data passed to @code{movprod}.  The
default is @qcode{"includenan"}.  Caution: the @qcode{"omitnan"} option is
not yet implemented.

The calculation can be controlled by specifying @var{property}/@var{value}
pairs.  Valid properties are

@table @asis

@item @qcode{"Endpoints"}

This property controls how results are calculated at the boundaries
(@w{endpoints}) of the window.  Possible values are:

@table @asis
@item @qcode{"shrink"}  (default)
The window is truncated at the beginning and end of the array to exclude
elements for which there is no source data.  For example, with a window of
length 3, @code{@var{y}(1) = movprod (@var{x}(1:2))}, and
@code{@var{y}(end) = movprod (@var{x}(end-1:end))}.

@item @qcode{"discard"}
Any @var{y} values that use a window extending beyond the original
data array are deleted.  For example, with a 10-element data vector and a
window of length 3, the output will contain only 8 elements.  The first
element would require calculating the function over indices
@w{@code{[0, 1, 2]}} and is therefore discarded.  The last element would
require calculating the function over indices @w{@code{[9, 10, 11]}} and is
therefore discarded.

@item @qcode{"fill"}
Any window elements outside the data array are replaced by @code{NaN}.  For
example, with a window of length 3,
@code{@var{y}(1) = movprod ([NaN, @var{x}(1:2)])}, and
@code{@var{y}(end) = movprod ([@var{x}(end-1:end), NaN])}.
This option usually results in @var{y} having @code{NaN} values at the
boundaries, although it is influenced by how @code{movprod} handles @code{NaN},
and also by the property @qcode{"nancond"}.

@item @var{user_value}
Any window elements outside the data array are replaced by the specified
value @var{user_value} which must be a numeric scalar.  For example, with a
window of length 3,
@code{@var{y}(1) = movprod ([@var{user_value}, @var{x}(1:2)])}, and
@code{@var{y}(end) = movprod ([@var{x}(end-1:end), @var{user_value}])}.
A common choice for @var{user_value} is 0.

@item @qcode{"same"}
Any window elements outside the data array are replaced by the value of
@var{x} at the boundary.  For example, with a window of length 3,
@code{@var{y}(1) = movprod ([@var{x}(1), @var{x}(1:2)])}, and
@code{@var{y}(end) = movprod ([@var{x}(end-1:end), @var{x}(end)])}.

@item @qcode{"periodic"}
The window is wrapped so that any missing data elements are taken from
the other side of the data.  For example, with a window of length 3,
@code{@var{y}(1) = movprod ([@var{x}(end), @var{x}(1:2)])}, and
@code{@var{y}(end) = movprod ([@var{x}(end-1:end), @var{x}(1)])}.

@end table

@item @qcode{"SamplePoints"}
Caution: This option is not yet implemented.

@end table

Programming Note: This function is a wrapper which calls @code{movfun}.
For additional options and documentation, @xref{XREFmovfun,,movfun}.

@xseealso{movfun, movslice, movmad, movmax, movmean, movmedian, movmin, movstd, movsum, movvar}
@end deftypefn
movstd
@c movstd scripts/statistics/movstd.m
@deftypefn  {} {@var{y} =} movstd (@var{x}, @var{wlen})
@deftypefnx {} {@var{y} =} movstd (@var{x}, [@var{na}, @var{nb}])
@deftypefnx {} {@var{y} =} movstd (@dots{}, @var{dim})
@deftypefnx {} {@var{y} =} movstd (@dots{}, "@var{nancond}")
@deftypefnx {} {@var{y} =} movstd (@dots{}, @var{property}, @var{value})
Calculate the moving standard deviation over a sliding window of length
@var{wlen} on data @var{x}.

If @var{wlen} is a scalar, the function @code{movstd} is applied to a
moving window of length @var{wlen}.  When @var{wlen} is an odd number the
window is symmetric and includes @w{@code{(@var{wlen} - 1) / 2}} elements on
either side of the central element.  For example, when calculating the
output at index 5 with a window length of 3, @code{movstd} uses data
elements @w{@code{[4, 5, 6]}}.  If @var{wlen} is an even number, the window
is asymmetric and has @w{@code{@var{wlen}/2}} elements to the left of the
central element and @w{@code{@var{wlen}/2 - 1}} elements to the right of the
central element.  For example, when calculating the output at index 5 with a
window length of 4, @code{movstd} uses data elements
@w{@code{[3, 4, 5, 6]}}.

If @var{wlen} is an array with two elements @w{@code{[@var{nb}, @var{na}]}},
the function is applied to a moving window @code{-@var{nb}:@var{na}}.  This
window includes @var{nb} number of elements @emph{before} the current
element and @var{na} number of elements @emph{after} the current element.
The current element is always included.  For example, given
@w{@code{@var{wlen} = [3, 0]}}, the data used to calculate index 5 is
@w{@code{[2, 3, 4, 5]}}.

If the optional argument @var{dim} is given, operate along this dimension.

The optional string argument @qcode{"@var{nancond}"} controls whether
@code{NaN} and @code{NA} values should be included (@qcode{"includenan"}),
or excluded (@qcode{"omitnan"}), from the data passed to @code{movstd}.  The
default is @qcode{"includenan"}.  Caution: the @qcode{"omitnan"} option is
not yet implemented.

The calculation can be controlled by specifying @var{property}/@var{value}
pairs.  Valid properties are

@table @asis

@item @qcode{"Endpoints"}

This property controls how results are calculated at the boundaries
(@w{endpoints}) of the window.  Possible values are:

@table @asis
@item @qcode{"shrink"}  (default)
The window is truncated at the beginning and end of the array to exclude
elements for which there is no source data.  For example, with a window of
length 3, @code{@var{y}(1) = movstd (@var{x}(1:2))}, and
@code{@var{y}(end) = movstd (@var{x}(end-1:end))}.

@item @qcode{"discard"}
Any @var{y} values that use a window extending beyond the original
data array are deleted.  For example, with a 10-element data vector and a
window of length 3, the output will contain only 8 elements.  The first
element would require calculating the function over indices
@w{@code{[0, 1, 2]}} and is therefore discarded.  The last element would
require calculating the function over indices @w{@code{[9, 10, 11]}} and is
therefore discarded.

@item @qcode{"fill"}
Any window elements outside the data array are replaced by @code{NaN}.  For
example, with a window of length 3,
@code{@var{y}(1) = movstd ([NaN, @var{x}(1:2)])}, and
@code{@var{y}(end) = movstd ([@var{x}(end-1:end), NaN])}.
This option usually results in @var{y} having @code{NaN} values at the
boundaries, although it is influenced by how @code{movstd} handles @code{NaN},
and also by the property @qcode{"nancond"}.

@item @var{user_value}
Any window elements outside the data array are replaced by the specified
value @var{user_value} which must be a numeric scalar.  For example, with a
window of length 3,
@code{@var{y}(1) = movstd ([@var{user_value}, @var{x}(1:2)])}, and
@code{@var{y}(end) = movstd ([@var{x}(end-1:end), @var{user_value}])}.
A common choice for @var{user_value} is 0.

@item @qcode{"same"}
Any window elements outside the data array are replaced by the value of
@var{x} at the boundary.  For example, with a window of length 3,
@code{@var{y}(1) = movstd ([@var{x}(1), @var{x}(1:2)])}, and
@code{@var{y}(end) = movstd ([@var{x}(end-1:end), @var{x}(end)])}.

@item @qcode{"periodic"}
The window is wrapped so that any missing data elements are taken from
the other side of the data.  For example, with a window of length 3,
@code{@var{y}(1) = movstd ([@var{x}(end), @var{x}(1:2)])}, and
@code{@var{y}(end) = movstd ([@var{x}(end-1:end), @var{x}(1)])}.

@end table

@item @qcode{"SamplePoints"}
Caution: This option is not yet implemented.

@end table

Programming Note: This function is a wrapper which calls @code{movfun}.
For additional options and documentation, @xref{XREFmovfun,,movfun}.

@xseealso{movfun, movslice, movmad, movmax, movmean, movmedian, movmin, movprod, movsum, movvar}
@end deftypefn
movsum
@c movsum scripts/statistics/movsum.m
@deftypefn  {} {@var{y} =} movsum (@var{x}, @var{wlen})
@deftypefnx {} {@var{y} =} movsum (@var{x}, [@var{na}, @var{nb}])
@deftypefnx {} {@var{y} =} movsum (@dots{}, @var{dim})
@deftypefnx {} {@var{y} =} movsum (@dots{}, "@var{nancond}")
@deftypefnx {} {@var{y} =} movsum (@dots{}, @var{property}, @var{value})
Calculate the moving sum over a sliding window of length @var{wlen} on
data @var{x}.

If @var{wlen} is a scalar, the function @code{movsum} is applied to a
moving window of length @var{wlen}.  When @var{wlen} is an odd number the
window is symmetric and includes @w{@code{(@var{wlen} - 1) / 2}} elements on
either side of the central element.  For example, when calculating the
output at index 5 with a window length of 3, @code{movsum} uses data
elements @w{@code{[4, 5, 6]}}.  If @var{wlen} is an even number, the window
is asymmetric and has @w{@code{@var{wlen}/2}} elements to the left of the
central element and @w{@code{@var{wlen}/2 - 1}} elements to the right of the
central element.  For example, when calculating the output at index 5 with a
window length of 4, @code{movsum} uses data elements
@w{@code{[3, 4, 5, 6]}}.

If @var{wlen} is an array with two elements @w{@code{[@var{nb}, @var{na}]}},
the function is applied to a moving window @code{-@var{nb}:@var{na}}.  This
window includes @var{nb} number of elements @emph{before} the current
element and @var{na} number of elements @emph{after} the current element.
The current element is always included.  For example, given
@w{@code{@var{wlen} = [3, 0]}}, the data used to calculate index 5 is
@w{@code{[2, 3, 4, 5]}}.

If the optional argument @var{dim} is given, operate along this dimension.

The optional string argument @qcode{"@var{nancond}"} controls whether
@code{NaN} and @code{NA} values should be included (@qcode{"includenan"}),
or excluded (@qcode{"omitnan"}), from the data passed to @code{movsum}.  The
default is @qcode{"includenan"}.  Caution: the @qcode{"omitnan"} option is
not yet implemented.

The calculation can be controlled by specifying @var{property}/@var{value}
pairs.  Valid properties are

@table @asis

@item @qcode{"Endpoints"}

This property controls how results are calculated at the boundaries
(@w{endpoints}) of the window.  Possible values are:

@table @asis
@item @qcode{"shrink"}  (default)
The window is truncated at the beginning and end of the array to exclude
elements for which there is no source data.  For example, with a window of
length 3, @code{@var{y}(1) = movsum (@var{x}(1:2))}, and
@code{@var{y}(end) = movsum (@var{x}(end-1:end))}.

@item @qcode{"discard"}
Any @var{y} values that use a window extending beyond the original
data array are deleted.  For example, with a 10-element data vector and a
window of length 3, the output will contain only 8 elements.  The first
element would require calculating the function over indices
@w{@code{[0, 1, 2]}} and is therefore discarded.  The last element would
require calculating the function over indices @w{@code{[9, 10, 11]}} and is
therefore discarded.

@item @qcode{"fill"}
Any window elements outside the data array are replaced by @code{NaN}.  For
example, with a window of length 3,
@code{@var{y}(1) = movsum ([NaN, @var{x}(1:2)])}, and
@code{@var{y}(end) = movsum ([@var{x}(end-1:end), NaN])}.
This option usually results in @var{y} having @code{NaN} values at the
boundaries, although it is influenced by how @code{movsum} handles @code{NaN},
and also by the property @qcode{"nancond"}.

@item @var{user_value}
Any window elements outside the data array are replaced by the specified
value @var{user_value} which must be a numeric scalar.  For example, with a
window of length 3,
@code{@var{y}(1) = movsum ([@var{user_value}, @var{x}(1:2)])}, and
@code{@var{y}(end) = movsum ([@var{x}(end-1:end), @var{user_value}])}.
A common choice for @var{user_value} is 0.

@item @qcode{"same"}
Any window elements outside the data array are replaced by the value of
@var{x} at the boundary.  For example, with a window of length 3,
@code{@var{y}(1) = movsum ([@var{x}(1), @var{x}(1:2)])}, and
@code{@var{y}(end) = movsum ([@var{x}(end-1:end), @var{x}(end)])}.

@item @qcode{"periodic"}
The window is wrapped so that any missing data elements are taken from
the other side of the data.  For example, with a window of length 3,
@code{@var{y}(1) = movsum ([@var{x}(end), @var{x}(1:2)])}, and
@code{@var{y}(end) = movsum ([@var{x}(end-1:end), @var{x}(1)])}.

@end table

@item @qcode{"SamplePoints"}
Caution: This option is not yet implemented.

@end table

Programming Note: This function is a wrapper which calls @code{movfun}.
For additional options and documentation, @xref{XREFmovfun,,movfun}.

@xseealso{movfun, movslice, movmad, movmax, movmean, movmedian, movmin, movprod, movstd, movvar}
@end deftypefn
movvar
@c movvar scripts/statistics/movvar.m
@deftypefn  {} {@var{y} =} movvar (@var{x}, @var{wlen})
@deftypefnx {} {@var{y} =} movvar (@var{x}, [@var{na}, @var{nb}])
@deftypefnx {} {@var{y} =} movvar (@dots{}, @var{dim})
@deftypefnx {} {@var{y} =} movvar (@dots{}, "@var{nancond}")
@deftypefnx {} {@var{y} =} movvar (@dots{}, @var{property}, @var{value})
Calculate the moving variance over a sliding window of length @var{wlen} on
data @var{x}.

If @var{wlen} is a scalar, the function @code{var} is applied to a
moving window of length @var{wlen}.  When @var{wlen} is an odd number the
window is symmetric and includes @w{@code{(@var{wlen} - 1) / 2}} elements on
either side of the central element.  For example, when calculating the
output at index 5 with a window length of 3, @code{movvar} uses data
elements @w{@code{[4, 5, 6]}}.  If @var{wlen} is an even number, the window
is asymmetric and has @w{@code{@var{wlen}/2}} elements to the left of the
central element and @w{@code{@var{wlen}/2 - 1}} elements to the right of the
central element.  For example, when calculating the output at index 5 with a
window length of 4, @code{movvar} uses data elements
@w{@code{[3, 4, 5, 6]}}.

If @var{wlen} is an array with two elements @w{@code{[@var{nb}, @var{na}]}},
the function is applied to a moving window @code{-@var{nb}:@var{na}}.  This
window includes @var{nb} number of elements @emph{before} the current
element and @var{na} number of elements @emph{after} the current element.
The current element is always included.  For example, given
@w{@code{@var{wlen} = [3, 0]}}, the data used to calculate index 5 is
@w{@code{[2, 3, 4, 5]}}.

If the optional argument @var{dim} is given, operate along this dimension.

The optional string argument @qcode{"@var{nancond}"} controls whether
@code{NaN} and @code{NA} values should be included (@qcode{"includenan"}),
or excluded (@qcode{"omitnan"}), from the data passed to @code{var}.  The
default is @qcode{"includenan"}.  Caution: the @qcode{"omitnan"} option is
not yet implemented.

The calculation can be controlled by specifying @var{property}/@var{value}
pairs.  Valid properties are

@table @asis

@item @qcode{"Endpoints"}

This property controls how results are calculated at the boundaries
(@w{endpoints}) of the window.  Possible values are:

@table @asis
@item @qcode{"shrink"}  (default)
The window is truncated at the beginning and end of the array to exclude
elements for which there is no source data.  For example, with a window of
length 3, @code{@var{y}(1) = var (@var{x}(1:2))}, and
@code{@var{y}(end) = var (@var{x}(end-1:end))}.

@item @qcode{"discard"}
Any @var{y} values that use a window extending beyond the original
data array are deleted.  For example, with a 10-element data vector and a
window of length 3, the output will contain only 8 elements.  The first
element would require calculating the function over indices
@w{@code{[0, 1, 2]}} and is therefore discarded.  The last element would
require calculating the function over indices @w{@code{[9, 10, 11]}} and is
therefore discarded.

@item @qcode{"fill"}
Any window elements outside the data array are replaced by @code{NaN}.  For
example, with a window of length 3,
@code{@var{y}(1) = var ([NaN, @var{x}(1:2)])}, and
@code{@var{y}(end) = var ([@var{x}(end-1:end), NaN])}.
This option usually results in @var{y} having @code{NaN} values at the
boundaries, although it is influenced by how @code{var} handles @code{NaN},
and also by the property @qcode{"nancond"}.

@item @var{user_value}
Any window elements outside the data array are replaced by the specified
value @var{user_value} which must be a numeric scalar.  For example, with a
window of length 3,
@code{@var{y}(1) = var ([@var{user_value}, @var{x}(1:2)])}, and
@code{@var{y}(end) = var ([@var{x}(end-1:end), @var{user_value}])}.
A common choice for @var{user_value} is 0.

@item @qcode{"same"}
Any window elements outside the data array are replaced by the value of
@var{x} at the boundary.  For example, with a window of length 3,
@code{@var{y}(1) = var ([@var{x}(1), @var{x}(1:2)])}, and
@code{@var{y}(end) = var ([@var{x}(end-1:end), @var{x}(end)])}.

@item @qcode{"periodic"}
The window is wrapped so that any missing data elements are taken from
the other side of the data.  For example, with a window of length 3,
@code{@var{y}(1) = var ([@var{x}(end), @var{x}(1:2)])}, and
@code{@var{y}(end) = var ([@var{x}(end-1:end), @var{x}(1)])}.

@end table

@item @qcode{"SamplePoints"}
Caution: This option is not yet implemented.

@end table

Programming Note: This function is a wrapper which calls @code{movfun}.
For additional options and documentation, @xref{XREFmovfun,,movfun}.

@xseealso{movfun, movslice, movmad, movmax, movmean, movmedian, movmin, movprod, movstd, movsum}
@end deftypefn
prctile
@c prctile scripts/statistics/prctile.m
@deftypefn  {} {@var{q} =} prctile (@var{x})
@deftypefnx {} {@var{q} =} prctile (@var{x}, @var{p})
@deftypefnx {} {@var{q} =} prctile (@var{x}, @var{p}, @var{dim})
For a sample @var{x}, compute the quantiles, @var{q}, corresponding
to the cumulative probability values, @var{p}, in percent.

If @var{x} is a matrix, compute the percentiles for each column and return
them in a matrix, such that the i-th row of @var{q} contains the
@var{p}(i)th percentiles of each column of @var{x}.

If @var{p} is unspecified, return the quantiles for @code{[0 25 50 75 100]}.

The optional argument @var{dim} determines the dimension along which the
percentiles are calculated.  If @var{dim} is omitted it defaults to the
first non-singleton dimension.

Programming Note: All non-numeric values (NaNs) of @var{x} are ignored.
@xseealso{quantile}
@end deftypefn
quantile
@c quantile scripts/statistics/quantile.m
@deftypefn  {} {@var{q} =} quantile (@var{x})
@deftypefnx {} {@var{q} =} quantile (@var{x}, @var{p})
@deftypefnx {} {@var{q} =} quantile (@var{x}, @var{p}, @var{dim})
@deftypefnx {} {@var{q} =} quantile (@var{x}, @var{p}, @var{dim}, @var{method})
For a sample, @var{x}, calculate the quantiles, @var{q}, corresponding to
the cumulative probability values in @var{p}.  All non-numeric values (NaNs)
of @var{x} are ignored.

If @var{x} is a matrix, compute the quantiles for each column and
return them in a matrix, such that the i-th row of @var{q} contains
the @var{p}(i)th quantiles of each column of @var{x}.

If @var{p} is unspecified, return the quantiles for
@code{[0.00 0.25 0.50 0.75 1.00]}.
The optional argument @var{dim} determines the dimension along which
the quantiles are calculated.  If @var{dim} is omitted it defaults to
the first non-singleton dimension.

The methods available to calculate sample quantiles are the nine methods
used by R (@url{https://www.r-project.org/}).  The default value is
@w{@var{method} = 5}.

Discontinuous sample quantile methods 1, 2, and 3

@enumerate 1
@item Method 1: Inverse of empirical distribution function.

@item Method 2: Similar to method 1 but with averaging at discontinuities.

@item Method 3: SAS definition: nearest even order statistic.
@end enumerate

Continuous sample quantile methods 4 through 9, where
@tex
$p(k)$
@end tex
@ifnottex
@var{p}(k)
@end ifnottex
is the linear
interpolation function respecting each method's representative cdf.

@enumerate 4
@item Method 4:
@tex
$p(k) = k / N$.
@end tex
@ifnottex
@var{p}(k) = k / N.
@end ifnottex
That is, linear interpolation of the empirical cdf, where @math{N} is the
length of @var{P}.

@item Method 5:
@tex
$p(k) = (k - 0.5) / N$.
@end tex
@ifnottex
@var{p}(k) = (k - 0.5) / N.
@end ifnottex
That is, a piecewise linear function where the knots are the values midway
through the steps of the empirical cdf.

@item Method 6:
@tex
$p(k) = k / (N + 1)$.
@end tex
@ifnottex
@var{p}(k) = k / (N + 1).
@end ifnottex

@item Method 7:
@tex
$p(k) = (k - 1) / (N - 1)$.
@end tex
@ifnottex
@var{p}(k) = (k - 1) / (N - 1).
@end ifnottex

@item Method 8:
@tex
$p(k) = (k - 1/3) / (N + 1/3)$.
@end tex
@ifnottex
@var{p}(k) = (k - 1/3) / (N + 1/3).
@end ifnottex
The resulting quantile estimates are approximately median-unbiased
regardless of the distribution of @var{x}.

@item Method 9:
@tex
$p(k) = (k - 3/8) / (N + 1/4)$.
@end tex
@ifnottex
@var{p}(k) = (k - 3/8) / (N + 1/4).
@end ifnottex
The resulting quantile estimates are approximately unbiased for the
expected order statistics if @var{x} is normally distributed.
@end enumerate

@nospell{Hyndman and Fan} (1996) recommend method 8.  Maxima, S, and R
(versions prior to 2.0.0) use 7 as their default.  Minitab and SPSS
use method 6.  @sc{matlab} uses method 5.

References:

@itemize @bullet
@item @nospell{Becker, R. A., Chambers, J. M. and Wilks, A. R.} (1988)
The New S Language.  @nospell{Wadsworth & Brooks/Cole}.

@item @nospell{Hyndman, R. J. and Fan, Y.} (1996) Sample quantiles in
statistical packages, American Statistician, 50, 361--365.

@item R: A Language and Environment for Statistical Computing;
@url{https://cran.r-project.org/doc/manuals/fullrefman.pdf}.
@end itemize

Examples:
@c Set example in small font to prevent overfull line

@smallexample
@group
x = randi (1000, [10, 1]);  # Create empirical data in range 1-1000
q = quantile (x, [0, 1]);   # Return minimum, maximum of distribution
q = quantile (x, [0.25 0.5 0.75]); # Return quartiles of distribution
@end group
@end smallexample
@xseealso{prctile}
@end deftypefn
range
@c range scripts/statistics/range.m
@deftypefn  {} {} range (@var{x})
@deftypefnx {} {} range (@var{x}, @var{dim})
Return the range, i.e., the difference between the maximum and the minimum
of the input data.

If @var{x} is a vector, the range is calculated over the elements of
@var{x}.  If @var{x} is a matrix, the range is calculated over each column
of @var{x}.

If the optional argument @var{dim} is given, operate along this dimension.

The range is a quickly computed measure of the dispersion of a data set, but
is less accurate than @code{iqr} if there are outlying data points.
@xseealso{bounds, iqr, mad, std}
@end deftypefn
ranks
@c ranks scripts/statistics/ranks.m
@deftypefn  {} {} ranks (@var{x})
@deftypefnx {} {} ranks (@var{x}, @var{dim})
@deftypefnx {} {} ranks (@var{x}, @var{dim}, @var{rtype})
Return the ranks (in the sense of order statistics) of @var{x} along the
first non-singleton dimension adjusted for ties.

If the optional @var{dim} argument is given, operate along this dimension.

The optional parameter @var{rtype} determines how ties are handled.  All
examples below assume an input of @code{[ 1, 2, 2, 4 ]}.

@table @asis
@item 0 or @qcode{"fractional"} (default) for fractional ranking (1, 2.5,
2.5, 4);

@item 1 or @qcode{"competition"} for competition ranking (1, 2, 2, 4);

@item 2 or @qcode{"modified"} for modified competition ranking (1, 3, 3, 4);

@item 3 or @qcode{"ordinal"} for ordinal ranking (1, 2, 3, 4);

@item 4 or @qcode{"dense"} for dense ranking (1, 2, 2, 3).
@end table

@xseealso{spearman, kendall}
@end deftypefn
run_count
@c run_count scripts/statistics/run_count.m
@deftypefn  {} {} run_count (@var{x}, @var{n})
@deftypefnx {} {} run_count (@var{x}, @var{n}, @var{dim})
Count the upward runs along the first non-singleton dimension of @var{x}
of length 1, 2, @dots{}, @var{n}-1 and greater than or equal to @var{n}.

If the optional argument @var{dim} is given then operate along this
dimension.
@xseealso{runlength}
@end deftypefn
runlength
@c runlength scripts/statistics/runlength.m
@deftypefn  {} {count =} runlength (@var{x})
@deftypefnx {} {[count, value] =} runlength (@var{x})
Find the lengths of all sequences of common values.

@var{count} is a vector with the lengths of each repeated value.

The optional output @var{value} contains the value that was repeated in
the sequence.

@example
@group
runlength ([2, 2, 0, 4, 4, 4, 0, 1, 1, 1, 1])
@result{}   2   1   3   1   4
@end group
@end example
@xseealso{run_count}
@end deftypefn
skewness
@c skewness scripts/statistics/skewness.m
@deftypefn  {} {} skewness (@var{x})
@deftypefnx {} {} skewness (@var{x}, @var{flag})
@deftypefnx {} {} skewness (@var{x}, @var{flag}, @var{dim})
Compute the sample skewness of the elements of @var{x}.

The sample skewness is defined as
@tex
$$
{\rm skewness} (@var{x}) = {{{1\over N}\,
         \sum_{i=1}^N (x_i - \bar{x})^3} \over \sigma^3},
$$
where $N$ is the length of @var{x}, $\bar{x}$ its mean and $\sigma$
its (uncorrected) standard deviation.
@end tex
@ifnottex

@example
@group
               mean ((@var{x} - mean (@var{x})).^3)
skewness (@var{X}) = ------------------------.
                      std (@var{x}).^3
@end group
@end example

@end ifnottex

@noindent
The optional argument @var{flag} controls which normalization is used.
If @var{flag} is equal to 1 (default value, used when @var{flag} is omitted
or empty), return the sample skewness as defined above.  If @var{flag} is
equal to 0, return the adjusted skewness coefficient instead:
@tex
$$
{\rm skewness} (@var{x}) = {\sqrt{N (N - 1)} \over N - 2} \times \,
  {{{1 \over N} \sum_{i=1}^N (x_i - \bar{x})^3} \over \sigma^3}
$$
@end tex
@ifnottex

@example
@group
                  sqrt (N*(N-1))   mean ((@var{x} - mean (@var{x})).^3)
skewness (@var{X}, 0) = -------------- * ------------------------.
                      (N - 2)             std (@var{x}).^3
@end group
@end example

@noindent
where @math{N} is the length of the @var{x} vector.

@end ifnottex
The adjusted skewness coefficient is obtained by replacing the sample second
and third central moments by their bias-corrected versions.

If @var{x} is a matrix, or more generally a multi-dimensional array, return
the skewness along the first non-singleton dimension.  If the optional
@var{dim} argument is given, operate along this dimension.

@xseealso{var, kurtosis, moment}
@end deftypefn
spearman
@c spearman scripts/statistics/spearman.m
@deftypefn  {} {} spearman (@var{x})
@deftypefnx {} {} spearman (@var{x}, @var{y})
@cindex Spearman's Rho
Compute Spearman's rank correlation coefficient
@tex
$\rho$.
@end tex
@ifnottex
@var{rho}.
@end ifnottex

For two data vectors @var{x} and @var{y}, Spearman's
@tex
$\rho$
@end tex
@ifnottex
@var{rho}
@end ifnottex
is the correlation coefficient of the ranks of @var{x} and @var{y}.

If @var{x} and @var{y} are drawn from independent distributions,
@tex
$\rho$
@end tex
@ifnottex
@var{rho}
@end ifnottex
has zero mean and variance
@tex
$1 / (N - 1)$,
@end tex
@ifnottex
@code{1 / (N - 1)},
@end ifnottex
where @math{N} is the length of the @var{x} and @var{y} vectors, and is
asymptotically normally distributed.

@code{spearman (@var{x})} is equivalent to
@code{spearman (@var{x}, @var{x})}.
@xseealso{ranks, kendall}
@end deftypefn
statistics
@c statistics scripts/statistics/statistics.m
@deftypefn  {} {} statistics (@var{x})
@deftypefnx {} {} statistics (@var{x}, @var{dim})
Return a vector with the minimum, first quartile, median, third quartile,
maximum, mean, standard deviation, skewness, and kurtosis of the elements of
the vector @var{x}.

If @var{x} is a matrix, calculate statistics over the first non-singleton
dimension.

If the optional argument @var{dim} is given, operate along this dimension.
@xseealso{min, max, median, mean, std, skewness, kurtosis}
@end deftypefn
std
@c std scripts/statistics/std.m
@deftypefn  {} {} std (@var{x})
@deftypefnx {} {} std (@var{x}, @var{opt})
@deftypefnx {} {} std (@var{x}, @var{opt}, @var{dim})
Compute the standard deviation of the elements of the vector @var{x}.

The standard deviation is defined as
@tex
$$
{\rm std} (x) = \sigma = \sqrt{{\sum_{i=1}^N (x_i - \bar{x})^2 \over N - 1}}
$$
where $\bar{x}$ is the mean value of @var{x} and $N$ is the number of elements of @var{x}.
@end tex
@ifnottex

@example
@group
std (@var{x}) = sqrt ( 1/(N-1) SUM_i (@var{x}(i) - mean(@var{x}))^2 )
@end group
@end example

@noindent
where @math{N} is the number of elements of the @var{x} vector.
@end ifnottex

If @var{x} is a matrix, compute the standard deviation for each column and
return them in a row vector.

The argument @var{opt} determines the type of normalization to use.
Valid values are

@table @asis
@item 0:
  normalize with @math{N-1}, provides the square root of the best unbiased
estimator of the variance [default]

@item 1:
  normalize with @math{N}, this provides the square root of the second
moment around the mean
@end table

If the optional argument @var{dim} is given, operate along this dimension.
@xseealso{var, bounds, mad, range, iqr, mean, median}
@end deftypefn
var
@c var scripts/statistics/var.m
@deftypefn  {} {} var (@var{x})
@deftypefnx {} {} var (@var{x}, @var{opt})
@deftypefnx {} {} var (@var{x}, @var{opt}, @var{dim})
Compute the variance of the elements of the vector @var{x}.

The variance is defined as
@tex
$$
{\rm var} (x) = \sigma^2 = {\sum_{i=1}^N (x_i - \bar{x})^2 \over N - 1}
$$
where $\bar{x}$ is the mean value of @var{x} and $N$ is the number of
elements of @var{x}.

@end tex
@ifnottex

@example
@group
var (@var{x}) = 1/(N-1) SUM_i (@var{x}(i) - mean(@var{x}))^2
@end group
@end example

@noindent
where @math{N} is the length of the @var{x} vector.

@end ifnottex
If @var{x} is a matrix, compute the variance for each column and return
them in a row vector.

The argument @var{opt} determines the type of normalization to use.
Valid values are

@table @asis
@item 0:
  normalize with @math{N-1}, provides the best unbiased estimator of the
variance [default]

@item 1:
  normalizes with @math{N}, this provides the second moment around the mean
@end table

If @math{N} is equal to 1 the value of @var{opt} is ignored and
normalization by @math{N} is used.

If the optional argument @var{dim} is given, operate along this dimension.
@xseealso{cov, std, skewness, kurtosis, moment}
@end deftypefn
zscore
@c zscore scripts/statistics/zscore.m
@deftypefn  {} {@var{z} =} zscore (@var{x})
@deftypefnx {} {@var{z} =} zscore (@var{x}, @var{opt})
@deftypefnx {} {@var{z} =} zscore (@var{x}, @var{opt}, @var{dim})
@deftypefnx {} {[@var{z}, @var{mu}, @var{sigma}] =} zscore (@dots{})
Compute the Z score of @var{x}.

If @var{x} is a vector, subtract its mean and divide by its standard
deviation.  If the standard deviation is zero, divide by 1 instead.

The optional parameter @var{opt} determines the normalization to use when
computing the standard deviation and has the same definition as the
corresponding parameter for @code{std}.

If @var{x} is a matrix, calculate along the first non-singleton dimension.
If the third optional argument @var{dim} is given, operate along this
dimension.

The optional outputs @var{mu} and @var{sigma} contain the mean and standard
deviation.

@xseealso{mean, std, center}
@end deftypefn
base2dec
@c base2dec scripts/strings/base2dec.m
@deftypefn {} {} base2dec (@var{s}, @var{base})
Convert @var{s} from a string of digits in base @var{base} to a decimal
integer (base 10).

@example
@group
base2dec ("11120", 3)
   @result{} 123
@end group
@end example

If @var{s} is a string matrix, return a column vector with one value per
row of @var{s}.  If a row contains invalid symbols then the corresponding
value will be NaN@.

If @var{s} is a cell array of strings, return a column vector with one
value per cell element in @var{s}.

If @var{base} is a string, the characters of @var{base} are used as the
symbols for the digits of @var{s}.  Space (' ') may not be used as a symbol.

@example
@group
base2dec ("yyyzx", "xyz")
   @result{} 123
@end group
@end example
@xseealso{dec2base, bin2dec, hex2dec}
@end deftypefn
bin2dec
@c bin2dec scripts/strings/bin2dec.m
@deftypefn {} {} bin2dec (@var{s})
Return the decimal number corresponding to the binary number represented
by the string @var{s}.

For example:

@example
@group
bin2dec ("1110")
     @result{} 14
@end group
@end example

Spaces are ignored during conversion and may be used to make the binary
number more readable.

@example
@group
bin2dec ("1000 0001")
     @result{} 129
@end group
@end example

If @var{s} is a string matrix, return a column vector with one converted
number per row of @var{s}; Invalid rows evaluate to NaN@.

If @var{s} is a cell array of strings, return a column vector with one
converted number per cell element in @var{s}.
@xseealso{dec2bin, base2dec, hex2dec}
@end deftypefn
blanks
@c blanks scripts/strings/blanks.m
@deftypefn {} {} blanks (@var{n})
Return a string of @var{n} blanks.

For example:

@example
@group
blanks (10);
whos ans
     @result{}
      Attr Name        Size                     Bytes  Class
      ==== ====        ====                     =====  =====
           ans         1x10                        10  char
@end group
@end example
@xseealso{repmat}
@end deftypefn
cstrcat
@c cstrcat scripts/strings/cstrcat.m
@deftypefn {} {} cstrcat (@var{s1}, @var{s2}, @dots{})
Return a string containing all the arguments concatenated horizontally
with trailing white space preserved.

For example:

@example
@group
cstrcat ("ab   ", "cd")
      @result{} "ab   cd"
@end group
@end example

@example
@group
s = [ "ab"; "cde" ];
cstrcat (s, s, s)
      @result{} "ab ab ab "
         "cdecdecde"
@end group
@end example
@xseealso{strcat, char, strvcat}
@end deftypefn
deblank
@c deblank scripts/strings/deblank.m
@deftypefn {} {} deblank (@var{s})
Remove trailing whitespace and nulls from @var{s}.

If @var{s} is a matrix, @var{deblank} trims each row to the length of
longest string.  If @var{s} is a cell array of strings, operate
recursively on each string element.

Examples:

@example
@group
deblank ("    abc  ")
     @result{}  "    abc"

deblank ([" abc   "; "   def   "])
     @result{}  [" abc  " ; "   def"]
@end group
@end example
@xseealso{strtrim}
@end deftypefn
dec2base
@c dec2base scripts/strings/dec2base.m
@deftypefn  {} {} dec2base (@var{d}, @var{base})
@deftypefnx {} {} dec2base (@var{d}, @var{base}, @var{len})
Return a string of symbols in base @var{base} corresponding to the
non-negative integer @var{d}.

@example
@group
dec2base (123, 3)
   @result{} "11120"
@end group
@end example

If @var{d} is a matrix or cell array, return a string matrix with one row
per element in @var{d}, padded with leading zeros to the width of the
largest value.

If @var{base} is a string then the characters of @var{base} are used as
the symbols for the digits of @var{d}.  Space (' ') may not be used as a
symbol.

@example
@group
dec2base (123, "aei")
   @result{} "eeeia"
@end group
@end example

The optional third argument, @var{len}, specifies the minimum number of
digits in the result.
@xseealso{base2dec, dec2bin, dec2hex}
@end deftypefn
dec2bin
@c dec2bin scripts/strings/dec2bin.m
@deftypefn {} {} dec2bin (@var{d}, @var{len})
Return a binary number corresponding to the non-negative integer @var{d},
as a string of ones and zeros.

For example:

@example
@group
dec2bin (14)
     @result{} "1110"
@end group
@end example

If @var{d} is a matrix or cell array, return a string matrix with one row
per element in @var{d}, padded with leading zeros to the width of the
largest value.

The optional second argument, @var{len}, specifies the minimum number of
digits in the result.
@xseealso{bin2dec, dec2base, dec2hex}
@end deftypefn
dec2hex
@c dec2hex scripts/strings/dec2hex.m
@deftypefn {} {} dec2hex (@var{d}, @var{len})
Return the hexadecimal string corresponding to the non-negative integer
@var{d}.

For example:

@example
@group
dec2hex (2748)
     @result{} "ABC"
@end group
@end example

If @var{d} is a matrix or cell array, return a string matrix with one row
per element in @var{d}, padded with leading zeros to the width of the
largest value.

The optional second argument, @var{len}, specifies the minimum number of
digits in the result.
@xseealso{hex2dec, dec2base, dec2bin}
@end deftypefn
erase
@c erase scripts/strings/erase.m
@deftypefn {} {@var{newstr} =} erase (@var{str}, @var{ptn})
Delete all occurrences of @var{ptn} within @var{str}.

@var{str} and @var{ptn} can be ordinary strings, cell array of strings, or
character arrays.

Examples

@example
@group
## string, single pattern
erase ("Hello World!", " World")
    @result{} "Hello!"

## cellstr, single pattern
erase (@{"Hello", "World!"@}, "World")
    @result{} @{"Hello", "!"@}

## string, multiple patterns
erase ("The Octave interpreter is fabulous", ...
       @{"interpreter ", "The "@})
    @result{} "Octave is fabulous"

## cellstr, multiple patterns
erase (@{"The ", "Octave interpreter ", "is fabulous"@}, ...
       @{"interpreter ", "The "@})
    @result{} @{"", "Octave ", "is fabulous"@}
@end group
@end example

Programming Note: @code{erase} deletes the first instance of a pattern in a
string when there are overlapping occurrences.  For example:

@example
@group
erase ("abababa", "aba")
    @result{} "b"
@end group
@end example

See @code{strrep} for processing overlaps.

@xseealso{strrep, regexprep}
@end deftypefn
hex2dec
@c hex2dec scripts/strings/hex2dec.m
@deftypefn {} {} hex2dec (@var{s})
Return the integer corresponding to the hexadecimal number represented by
the string @var{s}.

For example:

@example
@group
hex2dec ("12B")
      @result{} 299
hex2dec ("12b")
      @result{} 299
@end group
@end example

If @var{s} is a string matrix, return a column vector with one converted
number per row of @var{s}; Invalid rows evaluate to NaN@.

If @var{s} is a cell array of strings, return a column vector with one
converted number per cell element in @var{s}.

@xseealso{dec2hex, base2dec, bin2dec}
@end deftypefn
index
@c index scripts/strings/index.m
@deftypefn  {} {} index (@var{s}, @var{t})
@deftypefnx {} {} index (@var{s}, @var{t}, @var{direction})
Return the position of the first occurrence of the string @var{t} in the
string @var{s}, or 0 if no occurrence is found.

@var{s} may also be a string array or cell array of strings.

For example:

@example
@group
index ("Teststring", "t")
    @result{} 4
@end group
@end example

If @var{direction} is @qcode{"first"}, return the first element found.
If @var{direction} is @qcode{"last"}, return the last element found.

@xseealso{find, rindex}
@end deftypefn
isletter
@c isletter scripts/strings/isletter.m
@deftypefn {} {} isletter (@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 an alias for the @code{isalpha} function.
@xseealso{isalpha, isdigit, ispunct, isspace, iscntrl, isalnum}
@end deftypefn
isstring
@c isstring scripts/strings/isstring.m
@deftypefn {} {} isstring (@var{s})
Return true if @var{s} is a string array.

A string array is a data type that stores strings (row vectors of
characters) at each element in the array.  It is distinct from character
arrays which are N-dimensional arrays where each element is a single 1x1
character.  It is also distinct from cell arrays of strings which store
strings at each element, but use cell indexing @samp{@{@}} to access
elements rather than string arrays which use ordinary array indexing
@samp{()}.

Programming Note: Octave does not yet implement string arrays so this
function will always return false.
@xseealso{ischar, iscellstr, isfloat, isinteger, islogical, isnumeric, isa}
@end deftypefn
isstrprop
@c isstrprop scripts/strings/isstrprop.m
@deftypefn {} {} isstrprop (@var{str}, @var{prop})
Test character string properties.

For example:

@example
@group
isstrprop ("abc123", "alpha")
@result{} [1, 1, 1, 0, 0, 0]
@end group
@end example

If @var{str} is a cell array, @code{isstrpop} is applied recursively to
each element of the cell array.

Numeric arrays are converted to character strings.

The second argument @var{prop} must be one of

@table @asis
@item @qcode{"alpha"}
True for characters that are alphabetic (letters).

@item  @nospell{@qcode{"alnum"}}
@itemx @nospell{@qcode{"alphanum"}}
True for characters that are alphabetic or digits.

@item @qcode{"lower"}
True for lowercase letters.

@item @qcode{"upper"}
True for uppercase letters.

@item @qcode{"digit"}
True for decimal digits (0-9).

@item @nospell{@qcode{"xdigit"}}
True for hexadecimal digits (@nospell{a-fA-F0-9}).

@item  @qcode{"space"}
@itemx @nospell{@qcode{"wspace"}}
True for whitespace characters (space, formfeed, newline, carriage return,
tab, vertical tab).

@item @nospell{@qcode{"punct"}}
True for punctuation characters (printing characters except space or
letter or digit).

@item @nospell{@qcode{"cntrl"}}
True for control characters.

@item  @qcode{"graph"}
@itemx @qcode{"graphic"}
True for printing characters except space.

@item @qcode{"print"}
True for printing characters including space.

@item @qcode{"ascii"}
True for characters that are in the range of ASCII encoding.

@end table

@xseealso{isalpha, isalnum, islower, isupper, isdigit, isxdigit,
isspace, ispunct, iscntrl, isgraph, isprint, isascii}
@end deftypefn
mat2str
@c mat2str scripts/strings/mat2str.m
@deftypefn  {} {@var{s} =} mat2str (@var{x}, @var{n})
@deftypefnx {} {@var{s} =} mat2str (@var{x}, @var{n}, "class")
Format real, complex, and logical matrices as strings.

The returned string may be used to reconstruct the original matrix by using
the @code{eval} function.

The precision of the values is given by @var{n}.  If @var{n} is a scalar
then both real and imaginary parts of the matrix are printed to the same
precision.  Otherwise @code{@var{n}(1)} defines the precision of the real
part and @code{@var{n}(2)} defines the precision of the imaginary part.
The default for @var{n} is 15.

If the argument @qcode{"class"} is given then the class of @var{x} is
included in the string in such a way that @code{eval} will result in the
construction of a matrix of the same class.

@example
@group
mat2str ([ -1/3 + i/7; 1/3 - i/7 ], [4 2])
     @result{} "[-0.3333+0.14i;0.3333-0.14i]"

mat2str ([ -1/3 +i/7; 1/3 -i/7 ], [4 2])
     @result{} "[-0.3333+0i 0+0.14i;0.3333+0i -0-0.14i]"

mat2str (int16 ([1 -1]), "class")
     @result{} "int16([1 -1])"

mat2str (logical (eye (2)))
     @result{} "[true false;false true]"

isequal (x, eval (mat2str (x)))
     @result{} 1
@end group
@end example

@xseealso{sprintf, num2str, int2str}
@end deftypefn
native2unicode
@c native2unicode scripts/strings/native2unicode.m
@deftypefn  {} {@var{utf8_str} =} native2unicode (@var{native_bytes}, @var{codepage})
@deftypefnx {} {@var{utf8_str} =} native2unicode (@var{native_bytes})
Convert byte stream @var{native_bytes} to UTF-8 using @var{codepage}.

The numbers in the vector @var{native_bytes} are rounded and clipped to
integers between 0 and 255.  This byte stream is then mapped into the
code page given by the string @var{codepage} and returned in the string
@var{utf8_str}.  Octave uses UTF-8 as its internal encoding.  The string
@var{codepage} must be an identifier of a valid code page.  Examples for
valid code pages are @qcode{"ISO-8859-1"}, @qcode{"Shift-JIS"}, or
@qcode{"UTF-16"}.  For a list of supported code pages, see
@url{https://www.gnu.org/software/libiconv}.  If @var{codepage} is omitted
or empty, the system default codepage is used.

If @var{native_bytes} is a string vector, it is returned as is.

@xseealso{unicode2native}
@end deftypefn
ostrsplit
@c ostrsplit scripts/strings/ostrsplit.m
@deftypefn  {} {[@var{cstr}] =} ostrsplit (@var{s}, @var{sep})
@deftypefnx {} {[@var{cstr}] =} ostrsplit (@var{s}, @var{sep}, @var{strip_empty})
Split the string @var{s} using one or more separators @var{sep} and return
a cell array of strings.

Consecutive separators and separators at boundaries result in empty
strings, unless @var{strip_empty} is true.  The default value of
@var{strip_empty} is false.

2-D character arrays are split at separators and at the original column
boundaries.

Example:

@example
@group
ostrsplit ("a,b,c", ",")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

ostrsplit (["a,b" ; "cde"], ",")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = cde
          @}
@end group
@end example
@xseealso{strsplit, strtok}
@end deftypefn
regexptranslate
@c regexptranslate scripts/strings/regexptranslate.m
@deftypefn {} {} regexptranslate (@var{op}, @var{s})
Translate a string for use in a regular expression.

This may include either wildcard replacement or special character escaping.

The behavior is controlled by @var{op} which can take the following
values

@table @asis
@item @qcode{"wildcard"}
The wildcard characters @code{.}, @code{*}, and @code{?} are replaced with
wildcards that are appropriate for a regular expression.  For example:

@example
@group
regexptranslate ("wildcard", "*.m")
     @result{} '.*\.m'
@end group
@end example

@item @qcode{"escape"}
The characters @code{$.?[]}, that have special meaning for regular
expressions are escaped so that they are treated literally.  For example:

@example
@group
regexptranslate ("escape", "12.5")
     @result{} '12\.5'
@end group
@end example

@end table
@xseealso{regexp, regexpi, regexprep}
@end deftypefn
rindex
@c rindex scripts/strings/rindex.m
@deftypefn {} {} rindex (@var{s}, @var{t})
Return the position of the last occurrence of the character string
@var{t} in the character string @var{s}, or 0 if no occurrence is
found.

@var{s} may also be a string array or cell array of strings.

For example:

@example
@group
rindex ("Teststring", "t")
     @result{} 6
@end group
@end example

The @code{rindex} function is equivalent to @code{index} with
@var{direction} set to @qcode{"last"}.

@xseealso{find, index}
@end deftypefn
str2num
@c str2num scripts/strings/str2num.m
@deftypefn  {} {@var{x} =} str2num (@var{s})
@deftypefnx {} {[@var{x}, @var{state}] =} str2num (@var{s})
Convert the string (or character array) @var{s} to a number (or an array).

Examples:

@example
@group
str2num ("3.141596")
      @result{} 3.141596

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

The optional second output, @var{state}, is logically true when the
conversion is successful.  If the conversion fails the numeric output,
@var{x}, is empty and @var{state} is false.

@strong{Caution:} As @code{str2num} uses the @code{eval} function to do the
conversion, @code{str2num} will execute any code contained in the string
@var{s}.  Use @code{str2double} for a safer and faster conversion.

For cell array of strings use @code{str2double}.
@xseealso{str2double, eval}
@end deftypefn
strcat
@c strcat scripts/strings/strcat.m
@deftypefn {} {} strcat (@var{s1}, @var{s2}, @dots{})
Return a string containing all the arguments concatenated
horizontally.

If the arguments are cell strings, @code{strcat} returns a cell string
with the individual cells concatenated.  For numerical input, each element
is converted to the corresponding ASCII character.  Trailing white space
for any character string input is eliminated before the strings are
concatenated.  Note that cell string values do @strong{not} have
whitespace trimmed.

For example:

@example
@group
strcat ("|", " leading space is preserved", "|")
    @result{} | leading space is preserved|
@end group
@end example

@example
@group
strcat ("|", "trailing space is eliminated ", "|")
    @result{} |trailing space is eliminated|
@end group
@end example

@example
@group
strcat ("homogeneous space |", "  ", "| is also eliminated")
    @result{} homogeneous space || is also eliminated
@end group
@end example

@example
@group
s = [ "ab"; "cde" ];
strcat (s, s, s)
    @result{}
        "ababab   "
        "cdecdecde"
@end group
@end example

@example
@group
s = @{ "ab"; "cd " @};
strcat (s, s, s)
    @result{}
        @{
          [1,1] = ababab
          [2,1] = cd cd cd
        @}
@end group
@end example

@xseealso{cstrcat, char, strvcat}
@end deftypefn
strchr
@c strchr scripts/strings/strchr.m
@deftypefn  {} {@var{idx} =} strchr (@var{str}, @var{chars})
@deftypefnx {} {@var{idx} =} strchr (@var{str}, @var{chars}, @var{n})
@deftypefnx {} {@var{idx} =} strchr (@var{str}, @var{chars}, @var{n}, @var{direction})
@deftypefnx {} {[@var{i}, @var{j}] =} strchr (@dots{})
Search for the string @var{str} for occurrences of characters from
the set @var{chars}.

The return value(s), as well as the @var{n} and @var{direction} arguments
behave identically as in @code{find}.

This will be faster than using regexp in most cases.

@xseealso{find}
@end deftypefn
strjoin
@c strjoin scripts/strings/strjoin.m
@deftypefn  {} {@var{str} =} strjoin (@var{cstr})
@deftypefnx {} {@var{str} =} strjoin (@var{cstr}, @var{delimiter})
Join the elements of the cell string array, @var{cstr}, into a single
string.

If no @var{delimiter} is specified, the elements of @var{cstr} are
separated by a space.

If @var{delimiter} is specified as a string, the cell string array is
joined using the string.  Escape sequences are supported.

If @var{delimiter} is a cell string array whose length is one less than
@var{cstr}, then the elements of @var{cstr} are joined by interleaving the
cell string elements of @var{delimiter}.  Escape sequences are not
supported.

@example
@group
strjoin (@{'Octave','Scilab','Lush','Yorick'@}, '*')
      @result{} 'Octave*Scilab*Lush*Yorick'
@end group
@end example
@xseealso{strsplit}
@end deftypefn
strjust
@c strjust scripts/strings/strjust.m
@deftypefn  {} {} strjust (@var{s})
@deftypefnx {} {} strjust (@var{s}, @var{pos})
Return the text, @var{s}, justified according to @var{pos}, which may
be @qcode{"left"}, @qcode{"center"}, or @qcode{"right"}.

If @var{pos} is omitted it defaults to @qcode{"right"}.

Null characters are replaced by spaces.  All other character data are
treated as non-white space.

Example:

@example
@group
strjust (["a"; "ab"; "abc"; "abcd"])
     @result{}
        "   a"
        "  ab"
        " abc"
        "abcd"
@end group
@end example
@xseealso{deblank, strrep, strtrim, untabify}
@end deftypefn
strsplit
@c strsplit scripts/strings/strsplit.m
@deftypefn  {} {[@var{cstr}] =} strsplit (@var{str})
@deftypefnx {} {[@var{cstr}] =} strsplit (@var{str}, @var{del})
@deftypefnx {} {[@var{cstr}] =} strsplit (@dots{}, @var{name}, @var{value})
@deftypefnx {} {[@var{cstr}, @var{matches}] =} strsplit (@dots{})
Split the string @var{str} using the delimiters specified by @var{del} and
return a cell string array of substrings.

If a delimiter is not specified the string is split at whitespace
@code{@{" ", "\f", "\n", "\r", "\t", "\v"@}}.  Otherwise, the delimiter,
@var{del} must be a string or cell array of strings.  By default,
consecutive delimiters in the input string @var{s} are collapsed into one
resulting in a single split.

Supported @var{name}/@var{value} pair arguments are:

@itemize
@item @var{collapsedelimiters} which may take the value of @code{true}
(default) or @code{false}.

@item @var{delimitertype} which may take the value of @qcode{"simple"}
(default) or @nospell{@qcode{"regularexpression"}}.  A simple delimiter
matches the text exactly as written.  Otherwise, the syntax for regular
expressions outlined in @code{regexp} is used.
@end itemize

The optional second output, @var{matches}, returns the delimiters which were
matched in the original string.

Examples with simple delimiters:

@example
strsplit ("a b c")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

strsplit ("a,b,c", ",")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

strsplit ("a foo b,bar c", @{" ", ",", "foo", "bar"@})
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

strsplit ("a,,b, c", @{",", " "@}, "collapsedelimiters", false)
      @result{}
          @{
            [1,1] = a
            [1,2] =
            [1,3] = b
            [1,4] =
            [1,5] = c
          @}

@end example

Examples with @nospell{regularexpression} delimiters:

@smallexample
strsplit ("a foo b,bar c", ',|\s|foo|bar', ...
          "delimitertype", "regularexpression")
@result{}
@{
            [1,1] = a
            [1,2] = b
            [1,3] = c
@}

strsplit ("a,,b, c", '[, ]', "collapsedelimiters", false, ...
          "delimitertype", "regularexpression")
@result{}
@{
            [1,1] = a
            [1,2] =
            [1,3] = b
            [1,4] =
            [1,5] = c
@}

strsplit ("a,\t,b, c", @{',', '\s'@}, "delimitertype", "regularexpression")
@result{}
@{
            [1,1] = a
            [1,2] = b
            [1,3] = c
@}

strsplit ("a,\t,b, c", @{',', ' ', '\t'@}, "collapsedelimiters", false)
@result{}
@{
            [1,1] = a
            [1,2] =
            [1,3] =
            [1,4] = b
            [1,5] =
            [1,6] = c
@}
@end smallexample

@xseealso{ostrsplit, strjoin, strtok, regexp}
@end deftypefn
strtok
@c strtok scripts/strings/strtok.m
@deftypefn  {} {[@var{tok}, @var{rem}] =} strtok (@var{str})
@deftypefnx {} {[@var{tok}, @var{rem}] =} strtok (@var{str}, @var{delim})

Find all characters in the string @var{str} up to, but not including, the
first character which is in the string @var{delim}.

@var{str} may also be a cell array of strings in which case the function
executes on every individual string and returns a cell array of tokens and
remainders.

Leading delimiters are ignored.  If @var{delim} is not specified,
whitespace is assumed.

If @var{rem} is requested, it contains the remainder of the string, starting
at the first delimiter.

Examples:

@example
@group
strtok ("this is the life")
     @result{} "this"

[tok, rem] = strtok ("14*27+31", "+-*/")
     @result{}
        tok = 14
        rem = *27+31
@end group
@end example
@xseealso{index, strsplit, strchr, isspace}
@end deftypefn
strtrim
@c strtrim scripts/strings/strtrim.m
@deftypefn {} {} strtrim (@var{s})
Remove leading and trailing whitespace from @var{s}.

If @var{s} is a matrix, @var{strtrim} trims each row to the length of
longest string.  If @var{s} is a cell array of strings, operate recursively
on each string element.

For example:

@example
@group
strtrim ("    abc  ")
     @result{}  "abc"

strtrim ([" abc   "; "   def   "])
     @result{}  ["abc  "  ; "  def"]
@end group
@end example
@xseealso{deblank}
@end deftypefn
strtrunc
@c strtrunc scripts/strings/strtrunc.m
@deftypefn {} {} strtrunc (@var{s}, @var{n})
Truncate the character string @var{s} to length @var{n}.

If @var{s} is a character matrix, then the number of columns is adjusted.

If @var{s} is a cell array of strings, then the operation is performed
on each cell element and the new cell array is returned.
@end deftypefn
substr
@c substr scripts/strings/substr.m
@deftypefn  {} {} substr (@var{s}, @var{offset})
@deftypefnx {} {} substr (@var{s}, @var{offset}, @var{len})
Return the substring of @var{s} which starts at character number
@var{offset} and is @var{len} characters long.

Position numbering for offsets begins with 1.  If @var{offset} is negative,
extraction starts that far from the end of the string.

If @var{len} is omitted, the substring extends to the end of @var{s}.  A
negative value for @var{len} extracts to within @var{len} characters of
the end of the string

Examples:

@example
@group
substr ("This is a test string", 6, 9)
     @result{} "is a test"
substr ("This is a test string", -11)
     @result{} "test string"
substr ("This is a test string", -11, -7)
     @result{} "test"
@end group
@end example

This function is patterned after the equivalent function in Perl.
@end deftypefn
unicode2native
@c unicode2native scripts/strings/unicode2native.m
@deftypefn  {} {@var{native_bytes} =} unicode2native (@var{utf8_str}, @var{codepage})
@deftypefnx {} {@var{native_bytes} =} unicode2native (@var{utf8_str})
Convert UTF-8 string @var{utf8_str} to byte stream using @var{codepage}.

The character vector @var{utf8_str} is converted to a byte stream
@var{native_bytes} using the code page given by @var{codepage}.  The
string @var{codepage} must be an identifier of a valid code page.
Examples for valid code pages are @qcode{"ISO-8859-1"},
@qcode{"Shift-JIS"}, or @qcode{"UTF-16"}.  For a list of supported code
pages, see @url{https://www.gnu.org/software/libiconv}.  If @var{codepage}
is omitted or empty, the system default codepage is used.

If any of the characters cannot be mapped into the codepage @var{codepage},
they are replaced with the appropriate substitution sequence for that
codepage.

@xseealso{native2unicode}
@end deftypefn
untabify
@c untabify scripts/strings/untabify.m
@deftypefn  {} {} untabify (@var{t})
@deftypefnx {} {} untabify (@var{t}, @var{tw})
@deftypefnx {} {} untabify (@var{t}, @var{tw}, @var{deblank})
Replace TAB characters in @var{t} with spaces.

The input, @var{t}, may be either a 2-D character array, or a cell array of
character strings.  The output is the same class as the input.

The tab width is specified by @var{tw}, and defaults to eight.

If the optional argument @var{deblank} is true, then the spaces will be
removed from the end of the character data.

The following example reads a file and writes an untabified version of the
same file with trailing spaces stripped.

@example
@group
fid = fopen ("tabbed_script.m");
text = char (fread (fid, "uchar")');
fclose (fid);
fid = fopen ("untabified_script.m", "w");
text = untabify (strsplit (text, "\n"), 8, true);
fprintf (fid, "%s\n", text@{:@});
fclose (fid);
@end group
@end example

@xseealso{strjust, strsplit, deblank}
@end deftypefn
validatestring
@c validatestring scripts/strings/validatestring.m
@deftypefn  {} {@var{validstr} =} validatestring (@var{str}, @var{strarray})
@deftypefnx {} {@var{validstr} =} validatestring (@var{str}, @var{strarray}, @var{funcname})
@deftypefnx {} {@var{validstr} =} validatestring (@var{str}, @var{strarray}, @var{funcname}, @var{varname})
@deftypefnx {} {@var{validstr} =} validatestring (@dots{}, @var{position})
Verify that @var{str} is an element, or substring of an element, in
@var{strarray}.

When @var{str} is a character string to be tested, and @var{strarray} is a
cellstr of valid values, then @var{validstr} will be the validated form
of @var{str} where validation is defined as @var{str} being a member
or substring of @var{validstr}.  This is useful for both verifying
and expanding short options, such as @qcode{"r"}, to their longer forms,
such as @qcode{"red"}.  If @var{str} is a substring of @var{validstr}, and
there are multiple matches, the shortest match will be returned if all
matches are substrings of each other.  Otherwise, an error will be raised
because the expansion of @var{str} is ambiguous.  All comparisons are case
insensitive.

The additional inputs @var{funcname}, @var{varname}, and @var{position}
are optional and will make any generated validation error message more
specific.

Examples:
@c Set example in small font to prevent overfull line

@smallexample
@group
validatestring ("r", @{"red", "green", "blue"@})
@result{} "red"

validatestring ("b", @{"red", "green", "blue", "black"@})
@result{} error: validatestring: multiple unique matches were found for 'b':
   blue, black
@end group
@end smallexample

@xseealso{strcmp, strcmpi, validateattributes, inputParser}
@end deftypefn
__have_feature__
@c __have_feature__ scripts/testfun/__have_feature__.m
@deftypefn {} {} __have_feature__ (feature)
Undocumented internal function.
@end deftypefn
__printf_assert__
@c __printf_assert__ scripts/testfun/__printf_assert__.m
@deftypefn {} {} __printf_assert__ (@dots{})
Undocumented internal function.
@end deftypefn
__prog_output_assert__
@c __prog_output_assert__ scripts/testfun/__prog_output_assert__.m
@deftypefn {} {} __prog_output_assert__ (@var{str})
Undocumented internal function.
@end deftypefn
__run_test_suite__
@c __run_test_suite__ scripts/testfun/__run_test_suite__.m
@deftypefn  {} {} __run_test_suite__ (@var{fcndirs}, @var{fixedtestdirs})
@deftypefnx {} {} __run_test_suite__ (@var{fcndirs}, @var{fixedtestdirs}, @var{topsrcdir}, @var{topbuilddir})
Undocumented internal function.
@end deftypefn
assert
@c assert scripts/testfun/assert.m
@deftypefn  {} {} assert (@var{cond})
@deftypefnx {} {} assert (@var{cond}, @var{errmsg})
@deftypefnx {} {} assert (@var{cond}, @var{errmsg}, @dots{})
@deftypefnx {} {} assert (@var{cond}, @var{msg_id}, @var{errmsg}, @dots{})
@deftypefnx {} {} assert (@var{observed}, @var{expected})
@deftypefnx {} {} assert (@var{observed}, @var{expected}, @var{tol})

Produce an error if the specified condition is not met.

@code{assert} can be called in three different ways.

@table @code
@item  assert (@var{cond})
@itemx assert (@var{cond}, @var{errmsg})
@itemx assert (@var{cond}, @var{errmsg}, @dots{})
@itemx assert (@var{cond}, @var{msg_id}, @var{errmsg}, @dots{})
Called with a single argument @var{cond}, @code{assert} produces an error if
@var{cond} is false (numeric zero).

Any additional arguments are passed to the @code{error} function for
processing.

@item assert (@var{observed}, @var{expected})
Produce an error if observed is not the same as expected.

Note that @var{observed} and @var{expected} can be scalars, vectors,
matrices, strings, cell arrays, or structures.

@item assert (@var{observed}, @var{expected}, @var{tol})
Produce an error if observed is not the same as expected but equality
comparison for numeric data uses a tolerance @var{tol}.

If @var{tol} is positive then it is an absolute tolerance which will produce
an error if @code{abs (@var{observed} - @var{expected}) > abs (@var{tol})}.

If @var{tol} is negative then it is a relative tolerance which will produce
an error if @code{abs (@var{observed} - @var{expected}) >
abs (@var{tol} * @var{expected})}.

If @var{expected} is zero @var{tol} will always be interpreted as an
absolute tolerance.

If @var{tol} is not scalar its dimensions must agree with those of
@var{observed} and @var{expected} and tests are performed on an
element-by-element basis.
@end table
@xseealso{fail, test, error, isequal}
@end deftypefn
demo
@c demo scripts/testfun/demo.m
@deftypefn  {} {} demo @var{name}
@deftypefnx {} {} demo @var{name} @var{n}
@deftypefnx {} {} demo ("@var{name}")
@deftypefnx {} {} demo ("@var{name}", @var{n})

Run example code block @var{n} associated with the function @var{name}.

If @var{n} is not specified, all examples are run.

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

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

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

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

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

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

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

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

@xseealso{rundemos, example, test}
@end deftypefn
example
@c example scripts/testfun/example.m
@deftypefn  {} {} example @var{name}
@deftypefnx {} {} example @var{name} @var{n}
@deftypefnx {} {} example ("@var{name}")
@deftypefnx {} {} example ("@var{name}", @var{n})
@deftypefnx {} {[@var{s}, @var{idx}] =} example (@dots{})

Display the code for example @var{n} associated with the function
@var{name}, but do not run it.

If @var{n} is not specified, all examples are displayed.

When called with output arguments, the examples are returned in the form of
a string @var{s}, with @var{idx} indicating the ending position of the
various examples.

See @code{demo} for a complete explanation.
@xseealso{demo, test}
@end deftypefn
fail
@c fail scripts/testfun/fail.m
@deftypefn  {} {} fail (@var{code})
@deftypefnx {} {} fail (@var{code}, @var{pattern})
@deftypefnx {} {} fail (@var{code}, "warning")
@deftypefnx {} {} fail (@var{code}, "warning", @var{pattern})

Return true if @var{code} fails with an error message matching
@var{pattern}, otherwise produce an error.

@var{code} must be in the form of a string that is passed to the Octave
interpreter via the @code{evalin} function, i.e., a (quoted) string constant
or a string variable.

Note that if @var{code} runs successfully, rather than failing, the error
printed is:

@example
          expected error <.> but got none
@end example

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

@example
@group
          expected <@var{pattern}>
          but got <text of actual error>
@end group
@end example

The angle brackets are not part of the output.

When called with the @qcode{"warning"} option @code{fail} will produce an
error if executing the code produces no warning.
@xseealso{assert, error}
@end deftypefn
rundemos
@c rundemos scripts/testfun/rundemos.m
@deftypefn  {} {} rundemos ()
@deftypefnx {} {} rundemos (@var{directory})
Execute built-in demos for all m-files in the specified @var{directory}.

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

If no directory is specified, operate on all directories in Octave's search
path for functions.
@xseealso{demo, runtests, path}
@end deftypefn
runtests
@c runtests scripts/testfun/runtests.m
@deftypefn  {} {} runtests ()
@deftypefnx {} {} runtests (@var{directory})
Execute built-in tests for all m-files in the specified @var{directory}.

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

If no directory is specified, operate on all directories in Octave's search
path for functions.
@xseealso{rundemos, test, path}
@end deftypefn
speed
@c speed scripts/testfun/speed.m
@deftypefn  {} {} speed (@var{f}, @var{init}, @var{max_n}, @var{f2}, @var{tol})
@deftypefnx {} {[@var{order}, @var{n}, @var{T_f}, @var{T_f2}] =} speed (@dots{})

Determine the execution time of an expression (@var{f}) for various input
values (@var{n}).

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

@table @code
@item @var{f}
The code expression to evaluate.

@item @var{max_n}
The maximum test length to run.  The default value is 100.  Alternatively,
use @code{[min_n, max_n]} or specify the @var{n} exactly with
@code{[n1, n2, @dots{}, nk]}.

@item @var{init}
Initialization expression for function argument values.  Use @var{k} for
the test number and @var{n} for the size of the test.  This should compute
values for all variables used by @var{f}.  Note that @var{init} will be
evaluated first for @math{k = 0}, so things which are constant throughout
the test series can be computed once.  The default value is
@code{@var{x} = randn (@var{n}, 1)}.

@item @var{f2}
An alternative expression to evaluate, so that the speed of two
expressions can be directly compared.  The default is @code{[]}.

@item @var{tol}
Tolerance used to compare the results of expression @var{f} and expression
@var{f2}.  If @var{tol} is positive, the tolerance is an absolute one.
If @var{tol} is negative, the tolerance is a relative one.  The default is
@code{eps}.  If @var{tol} is @code{Inf}, then no comparison will be made.

@item @var{order}
The time complexity of the expression @math{O(a*n^p)}.  This is a
structure with fields @code{a} and @code{p}.

@item @var{n}
The values @var{n} for which the expression was calculated @strong{AND}
the execution time was greater than zero.

@item @var{T_f}
The nonzero execution times recorded for the expression @var{f} in seconds.

@item @var{T_f2}
The nonzero execution times recorded for the expression @var{f2} in seconds.
If required, the mean time ratio is simply @code{mean (T_f ./ T_f2)}.

@end table

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

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

@noindent
But it is if you preallocate the cell array @code{y}:

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

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

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

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

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

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

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

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

Type @kbd{example ("speed")} to see some real examples or
@kbd{demo ("speed")} to run them.

@end deftypefn
test
@c test scripts/testfun/test.m
@deftypefn  {} {} test @var{name}
@deftypefnx {} {} test @var{name} quiet|normal|verbose
@deftypefnx {} {} test ("@var{name}", "quiet|normal|verbose", @var{fid})
@deftypefnx {} {} test ("@var{name}", "quiet|normal|verbose", @var{fname})
@deftypefnx {} {@var{success} =} test (@dots{})
@deftypefnx {} {[@var{n}, @var{nmax}, @var{nxfail}, @var{nbug}, @var{nskip}, @var{nrtskip}, @var{nregression}] =} test (@dots{})
@deftypefnx {} {[@var{code}, @var{idx}] =} test ("@var{name}", "grabdemo")
@deftypefnx {} {} test ([], "explain", @var{fid})
@deftypefnx {} {} test ([], "explain", @var{fname})

Perform built-in self-tests from the first file in the loadpath matching
@var{name}.

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

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

Batch mode is enabled by either 1) specifying a logfile using the third
argument @var{fname} or @var{fid}, or 2) requesting an output argument
such as @var{success}, @var{n}, etc.

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

@table @asis
@item @qcode{"quiet"}
Print a summary message when all tests pass, or print an error with the
results of the first bad test when a failure occurs.  Don't run tests which
require user interaction.

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

@item @qcode{"verbose"}
Display tests before execution.  Print all warning messages.  In interactive
mode, run all tests including those which require user interaction.
@end table

The optional third input argument specifies a logfile where results of the
tests should be written.  The logfile may be a character string
(@var{fname}) or an open file descriptor ID (@var{fid}).  To enable batch
processing, but still print the results to the screen, use @code{stdout} for
@var{fid}.

When called with just a single output argument @var{success}, @code{test}
returns true if all of the tests were successful.  If called with more
than one output argument then the number of successful tests (@var{n}),
the total number of tests in the file (@var{nmax}), the number of xtest
failures (@var{nxfail}), the number of tests failed due known bugs
(@var{nbug}), the number of tests skipped due to missing features
(@var{nskip}), the number of tests skipped due to run-time
conditions (@var{nrtskip}), and the number of regressions
(@var{nregression}) are returned.

Example

@example
@group
test sind
@result{}
PASSES 5 out of 5 tests

[n, nmax] = test ("sind")
@result{}
n =  5
nmax =  5
@end group
@end example

Additional Calling Syntaxes

If the second argument is the string @qcode{"grabdemo"}, the contents of
any built-in demo blocks are extracted but not executed.  The text for all
code blocks is concatenated and returned as @var{code} with @var{idx} being
a vector of positions of the ends of each demo block.  For an easier way to
extract demo blocks from files, @xref{XREFexample,,example}.

If the second argument is @qcode{"explain"} then @var{name} is ignored and
an explanation of the line markers used in @code{test} output reports is
written to the file specified by @var{fname} or @var{fid}.

@xseealso{assert, fail, demo, example, error}
@end deftypefn
addtodate
@c addtodate scripts/time/addtodate.m
@deftypefn {} {@var{d} =} addtodate (@var{d}, @var{q}, @var{f})
Add @var{q} amount of time (with units @var{f}) to the serial datenum,
@var{d}.

@var{f} must be one of @qcode{"year"}, @qcode{"month"}, @qcode{"day"},
@qcode{"hour"}, @qcode{"minute"}, @qcode{"second"}, or
@qcode{"millisecond"}.
@xseealso{datenum, datevec, etime}
@end deftypefn
asctime
@c asctime scripts/time/asctime.m
@deftypefn {} {} asctime (@var{tm_struct})
Convert a time structure to a string using the following
format: @qcode{"ddd mmm mm HH:MM:SS yyyy@xbackslashchar{}n"}.

For example:

@example
@group
asctime (localtime (time ()))
     @result{} "Mon Feb 17 01:15:06 1997@xbackslashchar{}n"
@end group
@end example

This is equivalent to @code{ctime (time ())}.
@xseealso{ctime, localtime, time}
@end deftypefn
calendar
@c calendar scripts/time/calendar.m
@deftypefn  {} {@var{c} =} calendar ()
@deftypefnx {} {@var{c} =} calendar (@var{d})
@deftypefnx {} {@var{c} =} calendar (@var{y}, @var{m})
@deftypefnx {} {} calendar (@dots{})
Return the current monthly calendar in a 6x7 matrix.

If @var{d} is specified, return the calendar for the month containing the
date @var{d}, which must be a serial date number or a date string.

If @var{y} and @var{m} are specified, return the calendar for year @var{y}
and month @var{m}.

If no output arguments are specified, print the calendar on the screen
instead of returning a matrix.
@xseealso{datenum, datestr}
@end deftypefn
clock
@c clock scripts/time/clock.m
@deftypefn {} {} clock ()
Return the current local date and time as a date vector.

The date vector contains the following fields: current year, month (1-12),
day (1-31), hour (0-23), minute (0-59), and second (0-61).  The seconds
field has a fractional part after the decimal point for extended accuracy.

For example:

@example
@group
fix (clock ())
  @result{}   1993      8     20      4     56      1
@end group
@end example

@code{clock} is more accurate on systems that have the @code{gettimeofday}
function.
@xseealso{now, date, datevec}
@end deftypefn
ctime
@c ctime scripts/time/ctime.m
@deftypefn {} {} ctime (@var{t})
Convert a value returned from @code{time} (or any other non-negative
integer), to the local time and return a string of the same form as
@code{asctime}.

The function @code{ctime (time)} is equivalent to
@code{asctime (localtime (time))}.  For example:

@example
@group
ctime (time ())
   @result{} "Mon Feb 17 01:15:06 1997@xbackslashchar{}n"
@end group
@end example
@xseealso{asctime, time, localtime}
@end deftypefn
date
@c date scripts/time/date.m
@deftypefn {} {} date ()
Return the current date as a character string in the form DD-MMM-YYYY@.

For example:

@example
@group
date ()
  @result{} 20-Aug-1993
@end group
@end example
@xseealso{now, clock, datestr, localtime}
@end deftypefn
datenum
@c datenum scripts/time/datenum.m
@deftypefn  {} {@var{days} =} datenum (@var{datevec})
@deftypefnx {} {@var{days} =} datenum (@var{year}, @var{month}, @var{day})
@deftypefnx {} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour})
@deftypefnx {} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute})
@deftypefnx {} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute}, @var{second})
@deftypefnx {} {@var{days} =} datenum ("datestr")
@deftypefnx {} {@var{days} =} datenum ("datestr", @var{f})
@deftypefnx {} {@var{days} =} datenum ("datestr", @var{p})
@deftypefnx {} {[@var{days}, @var{secs}] =} datenum (@dots{})
Return the date/time input as a serial day number, with Jan 1, 0000
defined as day 1.

The integer part, @code{floor (@var{days})} counts the number of
complete days in the date input.

The fractional part, @code{rem (@var{days}, 1)} corresponds to the time
on the given day.

The input may be a date vector (see @code{datevec}),
datestr (see @code{datestr}), or directly specified as input.

When processing input datestrings, @var{f} is the format string used to
interpret date strings (see @code{datestr}).  If no format @var{f} is
specified, then a relatively slow search is performed through various
formats.  It is always preferable to specify the format string @var{f} if
it is known.  Formats which do not specify a particular time component
will have the value set to zero.  Formats which do not specify a date
will default to January 1st of the current year.

@var{p} is the year at the start of the century to which two-digit years
will be referenced.  If not specified, it defaults to the current year
minus 50.

The optional output @var{secs} holds the time on the specified day with
greater precision than @var{days}.

Notes:

@itemize
@item
Years can be negative and/or fractional.

@item
Months below 1 are considered to be January.

@item
Days of the month start at 1.

@item
Days beyond the end of the month go into subsequent months.

@item
Days before the beginning of the month go to the previous month.

@item
Days can be fractional.
@end itemize

@strong{Caution:} datenums represent a specific time for the Earth as a
a whole.  They do not take in to account time zones (shifts in time based
on location), nor seasonal changes due to Daylight Savings Time (shifts in
time based on local regulation).  Be aware that it is possible to create
datenums that, when interpreted by a function which accounts for time zone
and DST shifts such as @code{datestr}, are nonexistent or ambiguous.

@strong{Caution:} this function does not attempt to handle Julian calendars
so dates before October 15, 1582 are wrong by as much as eleven days.  Also,
be aware that only Roman Catholic countries adopted the calendar in 1582.
It took until 1924 for it to be adopted everywhere.  See the Wikipedia entry
on the Gregorian calendar for more details.

@strong{Warning:} leap seconds are ignored.  A table of leap seconds is
available on the Wikipedia entry for leap seconds.

@xseealso{datestr, datevec, now, clock, date}
@end deftypefn
datestr
@c datestr scripts/time/datestr.m
@deftypefn  {} {@var{str} =} datestr (@var{date})
@deftypefnx {} {@var{str} =} datestr (@var{date}, @var{f})
@deftypefnx {} {@var{str} =} datestr (@var{date}, @var{f}, @var{p})
Format the given date/time according to the format @var{f} and return
the result in @var{str}.

@var{date} is a serial date number (see @code{datenum}), a date vector (see
@code{datevec}), or a string or cell array of strings.  In the latter case,
it is passed to @code{datevec} to guess the input date format.

@var{f} can be an integer which corresponds to one of the codes in the table
below, or a date format string.

@var{p} is the year at the start of the century in which two-digit years are
to be interpreted in.  If not specified, it defaults to the current year
minus 50.

For example, the date 730736.65149 (2000-09-07 15:38:09.0934) would be
formatted as follows:

@multitable @columnfractions 0.1 0.45 0.35
@headitem Code @tab Format @tab Example
@item 0 @tab dd-mmm-yyyy HH:MM:SS    @tab 07-Sep-2000 15:38:09
@item 1 @tab dd-mmm-yyyy             @tab 07-Sep-2000
@item 2 @tab mm/dd/yy                @tab 09/07/00
@item 3 @tab mmm                     @tab Sep
@item 4 @tab m                       @tab S
@item 5 @tab mm                      @tab 09
@item 6 @tab mm/dd                   @tab 09/07
@item 7 @tab dd                      @tab 07
@item 8 @tab ddd                     @tab Thu
@item 9 @tab d                       @tab T
@item 10 @tab yyyy                   @tab 2000
@item 11 @tab yy                     @tab 00
@item 12 @tab mmmyy                  @tab Sep00
@item 13 @tab HH:MM:SS               @tab 15:38:09
@item 14 @tab HH:MM:SS PM            @tab  3:38:09 PM
@item 15 @tab HH:MM                  @tab 15:38
@item 16 @tab HH:MM PM               @tab  3:38 PM
@item 17 @tab QQ-YY                  @tab Q3-00
@item 18 @tab QQ                     @tab Q3
@item 19 @tab dd/mm                  @tab 07/09
@item 20 @tab dd/mm/yy               @tab 07/09/00
@item 21 @tab mmm.dd,yyyy HH:MM:SS   @tab Sep.07,2000 15:38:08
@item 22 @tab mmm.dd,yyyy            @tab Sep.07,2000
@item 23 @tab mm/dd/yyyy             @tab 09/07/2000
@item 24 @tab dd/mm/yyyy             @tab 07/09/2000
@item 25 @tab yy/mm/dd               @tab 00/09/07
@item 26 @tab yyyy/mm/dd             @tab 2000/09/07
@item 27 @tab QQ-YYYY                @tab Q3-2000
@item 28 @tab mmmyyyy                @tab Sep2000
@item 29 @tab yyyy-mm-dd             @tab 2000-09-07
@item 30 @tab yyyymmddTHHMMSS        @tab 20000907T153808
@item 31 @tab yyyy-mm-dd HH:MM:SS    @tab 2000-09-07 15:38:08
@end multitable

If @var{f} is a format string, the following symbols are recognized:

@multitable @columnfractions 0.1 0.7 0.2
@headitem Symbol @tab Meaning @tab Example
@item yyyy @tab Full year                                    @tab 2005
@item yy   @tab Two-digit year                               @tab 05
@item mmmm @tab Full month name                              @tab December
@item mmm  @tab Abbreviated month name                       @tab Dec
@item mm   @tab Numeric month number (padded with zeros)     @tab 01, 08, 12
@item m    @tab First letter of month name (capitalized)     @tab D
@item dddd @tab Full weekday name                            @tab Sunday
@item ddd  @tab Abbreviated weekday name                     @tab Sun
@item dd   @tab Numeric day of month (padded with zeros)     @tab 11
@item d    @tab First letter of weekday name (capitalized)   @tab S
@item HH   @tab Hour of day, padded with zeros,              @tab 09:00
@item      @tab or padded with spaces if PM is set           @tab  9:00 AM
@item MM   @tab Minute of hour (padded with zeros)           @tab 10:05
@item SS   @tab Second of minute (padded with zeros)         @tab 10:05:03
@item FFF  @tab Milliseconds of second (padded with zeros)   @tab 10:05:03.012
@item AM   @tab Use 12-hour time format                      @tab 11:30 AM
@item PM   @tab Use 12-hour time format                      @tab 11:30 PM
@end multitable

If @var{f} is not specified or is @code{-1}, then use 0, 1 or 16, depending
on whether the date portion or the time portion of @var{date} is empty.

If @var{p} is nor specified, it defaults to the current year minus 50.

If a matrix or cell array of dates is given, a column vector of date strings
is returned.

@xseealso{datenum, datevec, date, now, clock}
@end deftypefn
datevec
@c datevec scripts/time/datevec.m
@deftypefn  {} {@var{v} =} datevec (@var{date})
@deftypefnx {} {@var{v} =} datevec (@var{date}, @var{f})
@deftypefnx {} {@var{v} =} datevec (@var{date}, @var{p})
@deftypefnx {} {@var{v} =} datevec (@var{date}, @var{f}, @var{p})
@deftypefnx {} {[@var{y}, @var{m}, @var{d}, @var{h}, @var{mi}, @var{s}] =} datevec (@dots{})
Convert a serial date number (see @code{datenum}) or date string (see
@code{datestr}) into a date vector.

A date vector is a row vector with six members, representing the year,
month, day, hour, minute, and seconds respectively.

@var{f} is the format string used to interpret date strings
(see @code{datestr}).  If @var{date} is a string, but no format is
specified, then a relatively slow search is performed through various
formats.  It is always preferable to specify the format string @var{f} if it
is known.  Formats which do not specify a particular time component will
have the value set to zero.  Formats which do not specify a date will
default to January 1st of the current year.

@var{p} is the year at the start of the century to which two-digit years
will be referenced.  If not specified, it defaults to the current year minus
50.
@xseealso{datenum, datestr, clock, now, date}
@end deftypefn
eomday
@c eomday scripts/time/eomday.m
@deftypefn {} {@var{e} =} eomday (@var{y}, @var{m})
Return the last day of the month @var{m} for the year @var{y}.
@xseealso{weekday, datenum, datevec, is_leap_year, calendar}
@end deftypefn
etime
@c etime scripts/time/etime.m
@deftypefn {} {} etime (@var{t2}, @var{t1})
Return the difference in seconds between two time values returned from
@code{clock} (@math{@var{t2} - @var{t1}}).

For example:

@example
@group
t0 = clock ();
# many computations later@dots{}
elapsed_time = etime (clock (), t0);
@end group
@end example

@noindent
will set the variable @code{elapsed_time} to the number of seconds since the
variable @code{t0} was set.
@xseealso{tic, toc, clock, cputime, addtodate}
@end deftypefn
is_leap_year
@c is_leap_year scripts/time/is_leap_year.m
@deftypefn  {} {} is_leap_year ()
@deftypefnx {} {} is_leap_year (@var{year})
Return true if @var{year} is a leap year and false otherwise.

If no year is specified, @code{is_leap_year} uses the current year.

For example:

@example
@group
is_leap_year (2000)
   @result{} 1
@end group
@end example
@xseealso{weekday, eomday, calendar}
@end deftypefn
now
@c now scripts/time/now.m
@deftypefn {} {t =} now ()
Return the current local date/time as a serial day number
(see @code{datenum}).

The integral part, @code{floor (now)} corresponds to the number of days
between today and Jan 1, 0000.

The fractional part, @code{rem (now, 1)} corresponds to the current time.
@xseealso{clock, date, datenum}
@end deftypefn
weekday
@c weekday scripts/time/weekday.m
@deftypefn  {} {[@var{n}, @var{s}] =} weekday (@var{d})
@deftypefnx {} {[@var{n}, @var{s}] =} weekday (@var{d}, @var{format})
Return the day of the week as a number in @var{n} and as a string in
@var{s}.

The days of the week are numbered 1--7 with the first day being Sunday.

@var{d} is a serial date number or a date string.

If the string @var{format} is not present or is equal to @qcode{"short"}
then @var{s} will contain the abbreviated name of the weekday.  If
@var{format} is @qcode{"long"} then @var{s} will contain the full name.

Table of return values based on @var{format}:

@multitable @columnfractions .06 .13 .16
@headitem @var{n} @tab @qcode{"short"} @tab @qcode{"long"}
@item 1 @tab Sun @tab Sunday
@item 2 @tab Mon @tab Monday
@item 3 @tab Tue @tab Tuesday
@item 4 @tab Wed @tab Wednesday
@item 5 @tab Thu @tab Thursday
@item 6 @tab Fri @tab Friday
@item 7 @tab Sat @tab Saturday
@end multitable

@xseealso{eomday, is_leap_year, calendar, datenum, datevec}
@end deftypefn
@@ftp/ascii
@c @ftp/ascii scripts/@ftp/ascii.m
@deftypefn {} {} ascii (@var{f})
Set the FTP connection @var{f} to use ASCII mode for transfers.

ASCII mode is only appropriate for text files as it will convert the
remote host's newline representation to the local host's newline
representation.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@@ftp/binary
@c @ftp/binary scripts/@ftp/binary.m
@deftypefn {} {} binary (@var{f})
Set the FTP connection @var{f} to use binary mode for transfers.

In binary mode there is no conversion of newlines from the remote
representation to the local representation.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@@ftp/cd
@c @ftp/cd scripts/@ftp/cd.m
@deftypefn  {} {} cd (@var{f})
@deftypefnx {} {} cd (@var{f}, @var{path})
Get or set the remote directory on the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.

If @var{path} is not specified, return the remote current working
directory.  Otherwise, set the remote directory to @var{path} and return
the new remote working directory.

If the directory does not exist, an error message is printed and the
working directory is not changed.
@end deftypefn
@@ftp/close
@c @ftp/close scripts/@ftp/close.m
@deftypefn {} {} close (@var{f})
Close the FTP connection represented by the FTP object @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@@ftp/delete
@c @ftp/delete scripts/@ftp/delete.m
@deftypefn {} {} delete (@var{f}, @var{file})
Delete the remote file @var{file} over the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@@ftp/dir
@c @ftp/dir scripts/@ftp/dir.m
@deftypefn {} {@var{lst} =} dir (@var{f})
List the current directory in verbose form for the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@@ftp/ftp
@c @ftp/ftp scripts/@ftp/ftp.m
@deftypefn  {} {@var{f} =} ftp (@var{host})
@deftypefnx {} {@var{f} =} ftp (@var{host}, @var{username}, @var{password})
Connect to the FTP server @var{host} with @var{username} and @var{password}.

If @var{username} and @var{password} are not specified, user
@qcode{"anonymous"} with no password is used.  The returned FTP object
@var{f} represents the established FTP connection.

The list of actions for an FTP object are shown below.  All functions
require an FTP object as the first argument.

@multitable @columnfractions 0.15 0.8
@headitem Method @tab Description
@item ascii @tab Set transfer type to ascii
@item binary @tab Set transfer type to binary
@item cd @tab Change remote working directory
@item close @tab Close FTP connection
@item delete @tab Delete remote file
@item dir @tab List remote directory contents
@item mget @tab Download remote files
@item mkdir @tab Create remote directory
@item mput @tab Upload local files
@item rename @tab Rename remote file or directory
@item rmdir @tab Remove remote directory
@end multitable

@end deftypefn
@@ftp/mget
@c @ftp/mget scripts/@ftp/mget.m
@deftypefn  {} {} mget (@var{f}, @var{file})
@deftypefnx {} {} mget (@var{f}, @var{dir})
@deftypefnx {} {} mget (@var{f}, @var{remote_name}, @var{target})
Download a remote file @var{file} or directory @var{dir} to the local
directory on the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.

The arguments @var{file} and @var{dir} can include wildcards and any
files or directories on the remote server that match will be downloaded.

If a third string argument @var{target} is given, then it must indicate
the path to the local destination directory.  @var{target} may be a
relative or absolute path.
@end deftypefn
@@ftp/mkdir
@c @ftp/mkdir scripts/@ftp/mkdir.m
@deftypefn {} {} mkdir (@var{f}, @var{path})
Create the remote directory @var{path}, over the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@@ftp/mput
@c @ftp/mput scripts/@ftp/mput.m
@deftypefn {} {} mput (@var{f}, @var{file})
Upload the local file @var{file} into the current remote directory on the
FTP connection @var{f}.

@var{f} is an FTP object returned by the ftp function.

The argument @var{file} is passed through the @code{glob} function and any
files that match the wildcards in @var{file} will be uploaded.
@end deftypefn
@@ftp/rename
@c @ftp/rename scripts/@ftp/rename.m
@deftypefn {} {} rename (@var{f}, @var{oldname}, @var{newname})
Rename or move the remote file or directory @var{oldname} to @var{newname},
over the FTP connection @var{f}.

@var{f} is an FTP object returned by the ftp function.
@end deftypefn
@@ftp/rmdir
@c @ftp/rmdir scripts/@ftp/rmdir.m
@deftypefn {} {} rmdir (@var{f}, @var{path})
Remove the remote directory @var{path}, over the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
gnuplot_binary
@c gnuplot_binary scripts/plot/util/gnuplot_binary.in.m
@deftypefn  {} {[@var{prog}, @var{args}] =} gnuplot_binary ()
@deftypefnx {} {[@var{old_prog}, @var{old_args}] =} gnuplot_binary (@var{new_prog})
@deftypefnx {} {[@var{old_prog}, @var{old_args}] =} gnuplot_binary (@var{new_prog}, @var{arg1}, @dots{})
Query or set the name of the program invoked by the plot command when the
graphics toolkit is set to @qcode{"gnuplot"}.

Additional arguments to pass to the external plotting program may also be
given.  The default value is @qcode{"gnuplot"} with no additional arguments.
@xref{Installation}.
@xseealso{graphics_toolkit}
@end deftypefn