@c Copyright (C) 1992 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@c XXX FIXME XXX The functions should probably also be grouped by
@c functionality.

@node Built-in Functions, Invoking Octave, Built-in Variables, Top
@chapter Built-in Functions
@cindex Functions
@cindex built-in functions
@cindex functions, built-in

@ftable @code
@item abs

@example
abs (a)
@end example

@item acos

@example
acos (a)
@end example

@item acosh

@example
acosh (a)
@end example

@item all

@example
all (a)
@end example

@item angle

@example
angle (a)
@end example

@item any

@example
any (a)
@end example

@item arg

@example
arg (a)
@end example

@item asin

@example
asin (a)
@end example

@item asinh

@example
asinh (a)
@end example

@item atan

@example
atan (a)
@end example

@item atanh

@example
atanh (a)
@end example

@item bar

@example
           bar (x, y)
[xb, yb] = bar (x, y)
@end example

Given two vectors of x-y data, bar produces a bar graph.

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.

If two output arguments are specified, the data are generated but
not plotted.  For example,

@example
bar (x, y);
@end example
and

@example
[xb, yb] = bar (x, y);
plot (xb, yb);
@end example

@noindent
are equivalent.

@item casesen

@example
casesen
@end example

@item cd

@example
cd
@end example

@item ceil

@example
ceil (a)
@end example

@item clc

@example
clc ()
@end example

@item clear

@example
clear
@end example

@item clock

@example
clock (a)
@end example

@item closeplot

@example
closeplot ()
@end example

@item colloc

@example
[r, A, B, q] = colloc (n)
[r, A, B, q] = colloc (n, 'left')
[r, A, B, q] = colloc (n, 'left', 'right')
@end example

@item columns

@example
columns (a)
@end example

@item computer

@example
computer ()
@end example

@item cond

@example
cond (a)
@end example

@item conj

@example
conj (a)
@end example

@item contour

@example
contour (z)
contour (z, n)
contour (z, n, x, y)
@end example

@item cos

@example
cos (a)
@end example

@item cosh

@example
cosh (a)
@end example

@item cumprod

@example
cumprod (a)
@end example

@item cumsum

@example
cumsum (a)
@end example

@item dassl

@example
y = dassl ('function_name', x_0, xdot_0, t_out)
y = dassl ('function_name', x_0, xdot_0, t_out, t_crit)
@end example

Solve DAEs using Petzold's DASSL.

The first argument is the name of the function to call to
compute the vector of residuals.  It must have the form

@example
res = f (x, xdot, t)
@end example

@noindent
where x, xdot, and res are vectors, and t is a scalar.

@item date

@example
date ()
@end example

@item det

@example
det (a)
@end example

@item diag

@example
diag (a)
diag (a, k)
@end example

@item dir

@example
dir
@end example

@item disp

@example
disp (a)
@end example

@item document

@example
document
@end example

@item edit

@example
edit
@end example

@item eig

@example
            = eig (a)
[lambda, v] = eig (a)
@end example

@item error

@example
error (message)
@end example

@item eval

@example
eval (command)
@end example

@item exist

@example
exist (name)
@end example

@item exit

@example
exit ()
@end example

@item exp

@example
exp (a)
@end example

@item expm

@example
expm (a)
@end example

@item eye

@example
eye (n)
eye (a)
eye (n, m)
@end example

@item fclose
Close a file.

@item feval

@example
feval (name, ...)
@end example

@item fflush
Flush output to a file.

@item fft

@example
fft (a)
@end example

@item fgets
Read characters from a file.

@item find

@example
find (a)
@end example

@item finite

@example
finite (a)
@end example

@item fix

@example
fix (a)
@end example

@item fliplr

@example
fliplr (a)
@end example

@item flipud

@example
flipud (a)
@end example

@item floor

@example
floor (a)
@end example

@item flops

@example
flops ()
@end example

@item fopen
Open a file for reading or writing.

@item format

@example
format
@end example

@item fprintf

@example
fprintf ('file', 'format', ...)
@end example

@item freport
Print a report for all open files.

@item frewind
Set file position to the beginning of a file.

@item fscanf
Read from a file.

@item fseek
Set file position.

@item fsolve

@example
[x, info] = fsolve ('f', x0)
@end example

Solve nonlinear equations using Minpack.

Where the first argument is the name of the  function to call to
compute the vector of function values.  It must have the form

@example
y = f (x)
@end example

@noindent
where y and x are vectors.

@item fsqp

@example
fsqp ()
@end example

Sorry, this hasn't been implemented yet.

@item ftell
Tell file position.

@item getenv

@example
getenv (name)
@end example

@item grid

@example
grid ()
@end example

@item hadamard

@example
hadamard (k)
@end example

Return the Hadamard matrix of order n = 2^k.

@item hankel

@example
hankel (c)
hankel (c, r)
@end example

Return the Hankel matrix constructed given the first column
c, and (optionally) the last row r.

If the second argument is omitted, the last row is taken to be the
same as the first column.  If the last element of c is not the same
as the first element of r, the last element of c is used.

@item help

@example
help
@end example

@item hess

@example
     h = hess (a)
[p, h] = hess (a)
@end example

@item hilb

@example
hilb (n)
@end example

Return the Hilbert matrix of order n.  The i, j element of a Hilbert
matrix is defined as

@example
H (i, j) = 1 / (i + j - 1);
@end example

@item history

@example
history
@end example

@item home

@example
home ()
@end example

@item ifft

@example
ifft (a)
@end example

@item imag

@example
imag (a)
@end example

@item input

@example
input (prompt)
input (prompt, 's')
@end example

@item int2str

@example
int2str (a)
@end example

@item inv
@itemx inverse

@example
inverse (a)
@end example

@item invhilb

@example
invhilb (n)
@end example

Return the inverse of a Hilbert matrix of order n.  This is slow but
exact.  Compare with inverse (hilb (n)).

@item is_matrix

@example
is_matrix (a)
@end example

@item is_scalar

@example
is_scalar (a)
@end example

@item is_vector

@example
is_vector (a)
@end example

@item isempty

@example
isempty (a)
@end example

@item isinf

@example
isinf (a)
@end example

@item isnan

@example
isnan (a)
@end example

@item isstr

@example
isstr (a)
@end example

@item keyboard

@example
keyboard ()
keyboard (prompt)
@end example

@item length

@example
length (a)
@end example

@item linspace

@example
linspace (base, limit)
linspace (base, limit, npoints)
@end example

@item load

@example
load
@end example

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.

Since it seems that both of these cases are likely to be the result of
some sort of error, they will generate warnings.

@item log

@example
log (a)
@end example

@item log10

@example
log10 (a)
@end example

@item loglog

@example
loglog (x, y)
@end example

Make a 2D plot of y versus x using log scales for both axes.

@item logm

@example
logm (a)
@end example

@item logspace

@example
logspace (base, limit)
logspace (base, limit, npoints)
@end example

@item ls

@example
ls
@end example

@item lsode

@example
lsode ('function_name', x0, t_out
lsode ('function_name', x0, t_out, t_crit)
@end example

Solve ODEs using Hindmarsh's LSODE.

The first argument is the name of the function to call to
compute the vector of right hand sides.  It must have the form

@example
xdot = f (x, t)
@end example

@noindent
where xdot and x are vectors and t is a scalar.

@item lu

@example
[l, u, p] = lu (a)
@end example

@item max

@example
max (a)
@end example

@item mean

@example
mean (a)
@end example

@item median

@example
median (a)
@end example

@item menu

@example
menu (a)
@end example

@item mesh

@example
mesh (x, y, z)
@end example

@item meshdom

@example
[xx, yy] = meshdom (x, y)
@end example

Given vectors of x and y coordinates, return two matrices
corresponding to the x and y coordinates of the mesh.

See the file sombrero.m for an example of using mesh and meshdom.

@item min

@example
min (a)
@end example

@item norm

@example
norm (a)
@end example

@item npsol

@example
[x, obj, info, lambda] = npsol (x, 'phi')
[x, obj, info, lambda] = npsol (x, 'phi', lb, ub)
[x, obj, info, lambda] = npsol (x, 'phi', lb, ub, lb, A, ub)
[x, obj, info, lambda] = npsol (x, 'phi',         lb, A, ub)
[x, obj, info, lambda] = npsol (x, 'phi', lb, ub, lb, A, ub, lb, 'g', ub)
[x, obj, info, lambda] = npsol (x, 'phi',         lb, A, ub, lb, 'g', ub)
[x, obj, info, lambda] = npsol (x, 'phi',                    lb, 'g', ub)
[x, obj, info, lambda] = npsol (x, 'phi', lb, ub,            lb, 'g', ub)
@end example
Solve nonlinear programs using Gill and Murray's NPSOL.

The second argument is a string containing the name of the objective
function to call.  The objective function must be of the form

@example
y = phi (x)
@end example

@noindent
where x is a vector and y is a scalar.

@item num2str

@example
num2str (a)
@end example

@item ones

@example
ones (n)
ones (a)
ones (n, m)
@end example

@item pause

@example
pause (n)
@end example

@cindex plotting
@cindex graphics
@item plot

@example
plot (x, y)
@end example

This function produces two-dimensional plots.

If the first argument is a vector and the second is a matrix, the
the vector is plotted versus the columns (or rows) of the matrix.
(using whichever combination matches, with columns tried first.)

If the first argument is a matrix and the second is a vector, the
the columns (or rows) of the matrix are plotted versus the vector.
(using whichever combination matches, with columns tried first.)

If both arguments are vectors, the elements of y are plotted versus
the elements of x.

If both arguments are matrices, the columns of y are plotted versus
the columns of 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.

If both arguments are scalars, a single point is plotted.

If only one argument is given, it is taken as the set of y
coordinates and the x coordinates are taken to be the indices of the
elements, starting with 1.

@c XXX FIXME XXX -- add info about what to do to get plots on remote X
@c terminals.  People often forget how to properly set DISPLAY and run
@c xhost.

@c XXX FIXME XXX -- add info about getting paper copies of plots.

@item polar

@example
polar (theta, rho)
@end example

Make a 2D plot given polar the coordinates theta and rho.

@item printf

@example
printf ('format', ...)
@end example

@item prod

@example
prod (a)
@end example

@item purge_tmp_files

@example
purge_tmp_files ()
@end example

@item pwd

@example
pwd ()
@end example

@item qpsol

@example
[x, obj, info, lambda] = qpsol (x, H, c)
[x, obj, info, lambda] = qpsol (x, H, c, lb, ub)
[x, obj, info, lambda] = qpsol (x, H, c, lb, ub, lb, A, ub)
[x, obj, info, lambda] = qpsol (x, H, c,         lb, A, ub)
@end example
Solve quadratic programs using Gill and Murray's QPSOL.

@item qr

@example
[q, r] = qr (a)
@end example

@item quad

@example
[v, ier, nfun] = quad ('f', a, b)
[v, ier, nfun] = quad ('f', a, b, tol)
[v, ier, nfun] = quad ('f', a, b, tol, sing)
@end example

Integrate a nonlinear function of one variable using Quadpack.

Where the first argument is the name of the  function to call to
compute the value of the integrand.  It must have the form

@example
y = f (x)
@end example

@noindent
where y and x are scalars.

The second and third arguments are limits of integration.  Either or
both may be infinite.  The optional argument tol specifies the desired
accuracy of the result.  The optional argument sing is a vector of
at which the integrand is singular.

@item quit

@example
quit ()
@end example

@item rand

@example
rand (n)
rand (a)
rand (n, m)
@end example

@item rank

@example
rank (a)
@end example

@item real

@example
real (a)
@end example

@item rem

@example
rem (a, b)
@end example

@item replot

@example
replot ()
@end example

@item reshape

@example
reshape (a, n, m)
@end example

@item rot90

@example
rot90 (a, n)
@end example

@item round

@example
round (a)
@end example

@item rows

@example
rows (a)
@end example

@item save

@example
save
@end example

Saving global variables also saves the global status of the variable, so
that if it is restored at a later time using @samp{load}, it will be
restored as a global variable.

@item scanf
Read from the standard input.

@item sscanf
Read from a string.

@item schur

@example
usage: [u, s] = schur (a)
            s = schur (a)

 or, for ordered Schur:

       [u, s] = schur (a, "a, d, or u")
            s = schur (a, "a, d, or u")
 where:

   a = continuous time poles
   d = discrete time poles
   u = unordered schur (default)
@end example

@item semilogx

@example
semilogx (x, y)
@end example

Make a 2D plot of y versus x using a log scale for the x axis.

@item semilogy

@example
semilogy (x, y)
@end example

Make a 2D plot of y versus x using a log scale for the y axis.

@item set

@example
set
@end example

@item shell_cmd

@example
shell_cmd (a)
@end example

@item show

@example
show
@end example

@item sign

@example
sign (a)
@end example

@item sin

@example
sin (a)
@end example

@item sinh

@example
sinh (a)
@end example

@item size

@example
           size (a)
[nr, nc] = size (a)
@end example

@item sombrero

@example
sombrero (n)
@end example

@item sort

@example
sort (a)
@end example

@item sprintf

@example
sprintf ('format', ...)
@end example

@item sqrt

@example
sqrt (a)
@end example

@item sqrtm

@example
sqrtm (a)
@end example

@item stairs

@example
stairs (a)
           bar (x, y)
[xs, ys] = bar (x, y)
@end example

Given two vectors of x-y data, bar produces a `stairstep' plot.

If only one argument is given, it is taken as a vector of y-values
and the x coordiates are taken to be the indices of the elements.

If two output arguments are specified, the data are generated but
not plotted.  For example,

@example
bar (x, y);
@end example

@noindent
and

@example
[xs, ys] = stairs (x, y);
plot (xs, ys);
@end example

@noindent
are equivalent.

@item std

@example
std (a)
@end example

@item strcmp

@example
strcmp (s1, s2)
@end example

@item sum

@example
sum (a)
@end example

@item sumsq

@example
sumsq (a)
@end example

@item svd

@example
        s = svd (a)
[u, s, v] = svd (a)
@end example

@item tan

@example
tan (a)
@end example

@item tanh

@example
tanh (a)
@end example

@item texas_lotto

@example
texas_lotto ()
@end example

@item title

@example
title (string)
@end example

@item toeplitz

@example
toeplitz (c)
toeplitz (c, r)
@end example

Return the Toeplitz matrix constructed given the first column
c, and (optionally) the first row 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 c is not the same
as the first element of r, the first element of c is used.

@item trace

@example
trace (a)
@end example

@item tril

@example
tril (a)
tril (a, k)
@end example

@item triu

@example
triu (a)
triu (a, k)
@end example

@item vander

@example
vander (c)
@end example
Return the Vandermonde matrix whose next to last column is c.

@item warranty

@example
warranty ()
@end example

@item who

@example
who
@end example

@item xlabel

@example
xlabel (string)
@end example

@item ylabel

@example
ylabel (string)
@end example

@item zeros

@example
zeros (n)
zeros (a)
zeros (n, m)
@end example
@end ftable
