File: func.texi

package info (click to toggle)
octave 10.3.0-1
links: PTS, VCS
area: main
in suites:
size: 145,388 kB
sloc: cpp: 335,976; ansic: 82,241; fortran: 20,963; objc: 9,402; sh: 8,756; yacc: 4,392; lex: 4,333; perl: 1,544; java: 1,366; awk: 1,259; makefile: 659; xml: 192
file content (4315 lines) | stat: -rw-r--r-- 127,116 bytes
parent folder | download | duplicates (2)
@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

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

@node Functions and Scripts
@chapter Functions and Scripts
@cindex defining functions
@cindex user-defined functions
@cindex functions, user-defined
@cindex script files

Complicated Octave programs can often be simplified by defining functions.
Functions can be defined directly on the command line during interactive
Octave sessions, or in external files, and can be called just like built-in
functions.

@menu
* Introduction to Function and Script Files::
* Defining Functions::
* Returning from a Function::
* Multiple Return Values::
* Variable-length Return Lists::
* Variable-length Argument Lists::
* Ignoring Arguments::
* Default Arguments::
* Validating Arguments::
* Function Files::
* Script Files::
* Function Handles and Anonymous Functions::
* Command Syntax and Function Syntax::
* Organization of Functions::
@end menu

@node Introduction to Function and Script Files
@section Introduction to Function and Script Files

There are seven different things covered in this section.
@enumerate
@item
Typing in a function at the command prompt.

@item
Storing a group of commands in a file --- called a script file.

@item
Storing a function in a file---called a function file.

@item
Subfunctions in function files.

@item
Multiple functions in one script file.

@item
Private functions.

@item
Nested functions.
@end enumerate

Both function files and script files end with an extension of .m, for
@sc{matlab} compatibility.  If you want more than one independent
functions in a file, it must be a script file (@pxref{Script Files}),
and to use these functions you must execute the script file before you
can use the functions that are in the script file.

@node Defining Functions
@section Defining Functions
@cindex @code{function} statement
@cindex @code{endfunction} statement

In its simplest form, the definition of a function named @var{name}
looks like this:

@example
@group
function @var{name}
  @var{body}
endfunction
@end group
@end example

@noindent
A valid function name is like a valid variable name: a sequence of
letters, digits and underscores, not starting with a digit.  Functions
share the same pool of names as variables.

The function @var{body} consists of Octave statements.  It is the
most important part of the definition, because it says what the function
should actually @emph{do}.

For example, here is a function that, when executed, will ring the bell
on your terminal (assuming that it is possible to do so):

@example
@group
function wakeup
  printf ("\a");
endfunction
@end group
@end example

The @code{printf} statement (@pxref{Input and Output}) simply tells
Octave to print the string @qcode{"@backslashchar{}a"}.  The special character
@samp{\a} stands for the alert character (ASCII 7).  @xref{Strings}.

Once this function is defined, you can ask Octave to evaluate it by
typing the name of the function.

Normally, you will want to pass some information to the functions you
define.  The syntax for passing parameters to a function in Octave is

@example
@group
function @var{name} (@var{arg-list})
  @var{body}
endfunction
@end group
@end example

@noindent
where @var{arg-list} is a comma-separated list of the function's
arguments.  When the function is called, the argument names are used to
hold the argument values given in the call.  The list of arguments may
be empty, in which case this form is equivalent to the one shown above.

To print a message along with ringing the bell, you might modify the
@code{wakeup} to look like this:

@example
@group
function wakeup (message)
  printf ("\a%s\n", message);
endfunction
@end group
@end example

Calling this function using a statement like this

@example
wakeup ("Rise and shine!");
@end example

@noindent
will cause Octave to ring your terminal's bell and print the message
@samp{Rise and shine!}, followed by a newline character (the @samp{\n}
in the first argument to the @code{printf} statement).

In most cases, you will also want to get some information back from the
functions you define.  Here is the syntax for writing a function that
returns a single value:

@example
@group
function @var{ret-var} = @var{name} (@var{arg-list})
  @var{body}
endfunction
@end group
@end example

@noindent
The symbol @var{ret-var} is the name of the variable that will hold the
value to be returned by the function.  This variable must be defined
before the end of the function body in order for the function to return
a value.

Variables used in the body of a function are local to the
function.  Variables named in @var{arg-list} and @var{ret-var} are also
local to the function.  @xref{Global Variables}, for information about
how to access global variables inside a function.

For example, here is a function that computes the average of the
elements of a vector:

@example
@group
function retval = avg (v)
  retval = sum (v) / length (v);
endfunction
@end group
@end example

If we had written @code{avg} like this instead,

@example
@group
function retval = avg (v)
  if (isvector (v))
    retval = sum (v) / length (v);
  endif
endfunction
@end group
@end example

@noindent
and then called the function with a matrix instead of a vector as the
argument, Octave would have printed an error message like this:

@example
@group
error: value on right hand side of assignment is undefined
@end group
@end example

@noindent
because the body of the @code{if} statement was never executed, and
@code{retval} was never defined.  To prevent obscure errors like this,
it is a good idea to always make sure that the return variables will
always have values, and to produce meaningful error messages when
problems are encountered.  For example, @code{avg} could have been
written like this:

@example
@group
function retval = avg (v)
  retval = 0;
  if (isvector (v))
    retval = sum (v) / length (v);
  else
    error ("avg: expecting vector argument");
  endif
endfunction
@end group
@end example

There is still one remaining problem with this function.  What if it is
called without an argument?  Without additional error checking, Octave
will probably print an error message that won't really help you track
down the source of the error.  To allow you to catch errors like this,
Octave provides each function with an automatic variable called
@code{nargin}.  Each time a function is called, @code{nargin} is
automatically initialized to the number of arguments that have actually
been passed to the function.  For example, we might rewrite the
@code{avg} function like this:

@example
@group
function retval = avg (v)
  retval = 0;
  if (nargin != 1)
    usage ("avg (vector)");
  endif
  if (isvector (v))
    retval = sum (v) / length (v);
  else
    error ("avg: expecting vector argument");
  endif
endfunction
@end group
@end example

Octave automatically reports an error for functions written in .m file code
if they are called with more arguments than expected.  Octave does not
automatically report an error if a function is called with too few arguments,
since functions in general may have default arguments, but any attempt to use
a variable that has not been given a value will result in an error.
Functions can check the arguments they are called with to avoid such problems
and to provide more context-specific error messages.

@c nargin libinterp/octave-value/ov-usr-fcn.cc
@anchor{XREFnargin}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{n} =} nargin ()
@deftypefnx {} {@var{n} =} 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{@ref{XREFnargout,,nargout}, @ref{XREFnarginchk,,narginchk}, @ref{XREFvarargin,,varargin}, @ref{XREFinputname,,inputname}}
@end deftypefn


@c inputname libinterp/parse-tree/pt-eval.cc
@anchor{XREFinputname}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{namestr} =} inputname (@var{n})
@deftypefnx {} {@var{namestr} =} 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.
Examples which will return @qcode{""} are numbers (@code{5.1}), expressions
(@code{@var{y}/2}), and cell or structure indexing (@code{@var{c}@{1@}} or
@code{@var{s}.@var{field}}).

@code{inputname} is only useful within a function.  When used at the command
line or within a script 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.  This is an
Octave extension that allows the programmer to view exactly how the function
was invoked even when the inputs are complex expressions.
@xseealso{@ref{XREFnargin,,nargin}, @ref{XREFnarginchk,,narginchk}}
@end deftypefn


@c silent_functions libinterp/parse-tree/pt-eval.cc
@anchor{XREFsilent_functions}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} silent_functions ()
@deftypefnx {} {@var{old_val} =} silent_functions (@var{new_val})
@deftypefnx {} {@var{old_val} =} 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


@node Returning from a Function
@section Returning from a Function

The body of a user-defined function can contain a @code{return} statement.
This statement returns control to the rest of the Octave program.  It
looks like this:

@example
return
@end example

Unlike the @code{return} statement in C, Octave's @code{return}
statement cannot be used to return a value from a function.  Instead,
you must assign values to the list of return variables that are part of
the @code{function} statement.  The @code{return} statement simply makes
it easier to exit a function from a deeply nested loop or conditional
statement.

Here is an example of a function that checks to see if any elements of a
vector are nonzero.

@example
@group
function retval = any_nonzero (v)
  retval = 0;
  for i = 1:length (v)
    if (v (i) != 0)
      retval = 1;
      return;
    endif
  endfor
  printf ("no nonzero elements found\n");
endfunction
@end group
@end example

Note that this function could not have been written using the
@code{break} statement to exit the loop once a nonzero value is found
without adding extra logic to avoid printing the message if the vector
does contain a nonzero element.

@deftypefn {} {} return
When Octave encounters the keyword @code{return} inside a function or
script, it returns control to the caller immediately.  At the top level,
the return statement is ignored.  A @code{return} statement is assumed
at the end of every function definition.
@end deftypefn

@node Multiple Return Values
@section Multiple Return Values

Unlike many other computer languages, Octave allows you to define
functions that return more than one value.  The syntax for defining
functions that return multiple values is

@example
@group
function [@var{ret-list}] = @var{name} (@var{arg-list})
  @var{body}
endfunction
@end group
@end example

@noindent
where @var{name}, @var{arg-list}, and @var{body} have the same meaning
as before, and @var{ret-list} is a comma-separated list of variable
names that will hold the values returned from the function.  The list of
return values must have at least one element.  If @var{ret-list} has
only one element, this form of the @code{function} statement is
equivalent to the form described in the previous section.

Here is an example of a function that returns two values, the maximum
element of a vector and the index of its first occurrence in the vector.

@example
@group
function [max, idx] = vmax (v)
  idx = 1;
  max = v (idx);
  for i = 2:length (v)
    if (v (i) > max)
      max = v (i);
      idx = i;
    endif
  endfor
endfunction
@end group
@end example

In this particular case, the two values could have been returned as
elements of a single array, but that is not always possible or
convenient.  The values to be returned may not have compatible
dimensions, and it is often desirable to give the individual return
values distinct names.

It is possible to use the @code{nthargout} function to obtain only some
of the return values or several at once in a cell array.
@xref{Cell Array Objects}.

@c nthargout scripts/miscellaneous/nthargout.m
@anchor{XREFnthargout}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{arg} =} nthargout (@var{n}, @var{fcn}, @dots{})
@deftypefnx {} {@var{arg} =} nthargout (@var{n}, @var{ntot}, @var{fcn}, @dots{})
Return the @var{n}th output argument of the function specified by the
function handle or string @var{fcn}.

Any additional arguments are passed directly to @var{fcn}.  The total
number of arguments to call @var{fcn} 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 of @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 @code{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 collected in a single
cell array as the following code demonstrates:

@example
@var{USV} = nthargout ([1:3], @@svd, hilb (5));
@end example

Programming Note: Equivalent functionality to the @code{nthargout} function
is frequently possible by using the character @samp{~} in code to ignore
outputs.  This functionality is implemented by the Octave interpreter and
is even more efficient than using this function.

Equivalent Code:

@example
@group
idx = nthargout (2, @@max, rand (100, 1));
@equiv{}
[~, idx] = max (rand (100, 1));
@end group
@end example

@xseealso{@ref{XREFnargin,,nargin}, @ref{XREFnargout,,nargout}, @ref{XREFvarargin,,varargin}, @ref{XREFvarargout,,varargout}, @ref{XREFisargout,,isargout}}
@end deftypefn


In addition to setting @code{nargin} each time a function is called,
Octave also automatically initializes @code{nargout} to the number of
values that are expected to be returned.  This allows you to write
functions that behave differently depending on the number of values that
the user of the function has requested.  The implicit assignment to the
built-in variable @code{ans} does not figure in the count of output
arguments, so the value of @code{nargout} may be zero.

The @code{svd} and @code{hist} functions are examples of built-in
functions that behave differently depending on the value of
@code{nargout}.  For example, @code{hist} will draw a histogram when called
with no output variables, but if called with outputs it will return the
frequency counts and/or bin centers without creating a plot.

It is possible to write functions that only set some return values.  For
example, calling the function

@example
@group
function [x, y, z] = f ()
  x = 1;
  z = 2;
endfunction
@end group
@end example

@noindent
as

@example
[a, b, c] = f ()
@end example

@noindent
produces:

@example
@group
a = 1

b = [](0x0)

c = 2
@end group
@end example

@noindent
along with a warning.

@c nargout libinterp/octave-value/ov-usr-fcn.cc
@anchor{XREFnargout}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{n} =} nargout ()
@deftypefnx {} {@var{n} =} 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{@ref{XREFnargin,,nargin}, @ref{XREFvarargout,,varargout}, @ref{XREFisargout,,isargout}, @ref{XREFnthargout,,nthargout}}
@end deftypefn


@node Variable-length Return Lists
@section Variable-length Return Lists
@cindex variable-length return lists
@cindex @code{varargout}
@anchor{XREFvarargout}

It is possible to return a variable number of output arguments from a
function using a syntax that's similar to the one used with the
special @code{varargin} parameter name.  To let a function return a
variable number of output arguments the special output parameter name
@code{varargout} is used.  As with @code{varargin}, @code{varargout} is
a cell array that will contain the requested output arguments.

As an example the following function sets the first output argument to
1, the second to 2, and so on.

@example
@group
function varargout = one_to_n ()
  for i = 1:nargout
    varargout@{i@} = i;
  endfor
endfunction
@end group
@end example

@noindent
When called this function returns values like this

@example
@group
[a, b, c] = one_to_n ()
     @result{} a =  1
     @result{} b =  2
     @result{} c =  3
@end group
@end example

If @code{varargin} (@code{varargout}) does not appear as the last
element of the input (output) parameter list, then it is not special,
and is handled the same as any other parameter name.

@c deal scripts/general/deal.m
@anchor{XREFdeal}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFcell2struct,,cell2struct}, @ref{XREFstruct2cell,,struct2cell}, @ref{XREFrepmat,,repmat}}
@end deftypefn


@node Variable-length Argument Lists
@section Variable-length Argument Lists
@cindex variable-length argument lists
@cindex @code{varargin}
@anchor{XREFvarargin}

Sometimes the number of input arguments is not known when the function
is defined.  As an example think of a function that returns the smallest
of all its input arguments.  For example:

@example
@group
a = smallest (1, 2, 3);
b = smallest (1, 2, 3, 4);
@end group
@end example

@noindent
In this example both @code{a} and @code{b} would be 1.  One way to write
the @code{smallest} function is

@example
@group
function val = smallest (arg1, arg2, arg3, arg4, arg5)
  @var{body}
endfunction
@end group
@end example

@noindent
and then use the value of @code{nargin} to determine which of the input
arguments should be considered.  The problem with this approach is
that it can only handle a limited number of input arguments.

If the special parameter name @code{varargin} appears at the end of a
function parameter list it indicates that the function takes a variable
number of input arguments.  Using @code{varargin} the function
looks like this

@example
@group
function val = smallest (varargin)
  @var{body}
endfunction
@end group
@end example

@noindent
In the function body the input arguments can be accessed through the
variable @code{varargin}.  This variable is a cell array containing
all the input arguments.  @xref{Cell Arrays}, for details on working
with cell arrays.  The @code{smallest} function can now be defined
like this

@example
@group
function val = smallest (varargin)
  val = min ([varargin@{:@}]);
endfunction
@end group
@end example

@noindent
This implementation handles any number of input arguments, but it's also
a very simple solution to the problem.

A slightly more complex example of @code{varargin} is a function
@code{print_arguments} that prints all input arguments.  Such a function
can be defined like this

@example
@group
function print_arguments (varargin)
  for i = 1:length (varargin)
    printf ("Input argument %d: ", i);
    disp (varargin@{i@});
  endfor
endfunction
@end group
@end example

@noindent
This function produces output like this

@example
@group
print_arguments (1, "two", 3);
     @print{} Input argument 1:  1
     @print{} Input argument 2: two
     @print{} Input argument 3:  3
@end group
@end example

@c parseparams scripts/miscellaneous/parseparams.m
@anchor{XREFparseparams}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFvarargin,,varargin}, @ref{XREFinputParser,,inputParser}}
@end deftypefn


@node Ignoring Arguments
@section Ignoring Arguments

In the formal argument list, it is possible to use the dummy placeholder
@code{~} instead of a name.  This indicates that the corresponding argument
value should be ignored and not stored to any variable.

@example
@group
function val = pick2nd (~, arg2)
  val = arg2;
endfunction
@end group
@end example

The value of @code{nargin} is not affected by using this declaration.

Return arguments can also be ignored using the same syntax.  For example, the
sort function returns both the sorted values, and an index vector for the
original input which will result in a sorted output.  Ignoring the second
output is simple---don't request more than one output.  But ignoring the first,
and calculating just the second output, requires the use of the @code{~}
placeholder.

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

   1   2   3

i =

   3   1   2

[~, i] = sort (x)
@result{}
i =

   3   1   2
@end group
@end example

When using the @code{~} placeholder, commas---not whitespace---must be used
to separate output arguments.  Otherwise, the interpreter will view @code{~} as
the logical not operator.

@example
@group
[~ i] = sort (x)
parse error:

  invalid left hand side of assignment
@end group
@end example

Functions may take advantage of ignored outputs to reduce the number of
calculations performed.  To do so, use the @code{isargout} function to query
whether the output argument is wanted.  For example:

@example
@group
function [out1, out2] = long_function (x, y, z)
  if (isargout (1))
    ## Long calculation
    @dots{}
    out1 = result;
  endif
  @dots{}
endfunction
@end group
@end example

@c isargout libinterp/octave-value/ov-usr-fcn.cc
@anchor{XREFisargout}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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{@ref{XREFnargout,,nargout}, @ref{XREFvarargout,,varargout}, @ref{XREFnthargout,,nthargout}}
@end deftypefn


@node Default Arguments
@section Default Arguments
@cindex default arguments

Since Octave supports variable number of input arguments, it is very useful
to assign default values to some input arguments.  When an input argument
is declared in the argument list it is possible to assign a default
value to the argument like this

@example
@group
function @var{name} (@var{arg1} = @var{val1}, @dots{})
  @var{body}
endfunction
@end group
@end example

@noindent
If no value is assigned to @var{arg1} by the user, it will have the
value @var{val1}.

As an example, the following function implements a variant of the classic
``Hello, World'' program.

@example
@group
function hello (who = "World")
  printf ("Hello, %s!\n", who);
endfunction
@end group
@end example

@noindent
When called without an input argument the function prints the following

@example
@group
hello ();
     @print{} Hello, World!
@end group
@end example

@noindent
and when it's called with an input argument it prints the following

@example
@group
hello ("Beautiful World of Free Software");
     @print{} Hello, Beautiful World of Free Software!
@end group
@end example

Sometimes it is useful to explicitly tell Octave to use the default value
of an input argument.  This can be done writing a @samp{:} as the value
of the input argument when calling the function.

@example
@group
hello (:);
     @print{} Hello, World!
@end group
@end example

@node Validating Arguments
@section Validating Arguments
@cindex validating arguments

Octave is a weakly typed programming language.  Thus it is possible to
call a function with arguments, that probably cause errors or might have
undesirable side effects.  For example calling a string processing function
with a huge sparse matrix.

It is good practice at the head of a function to verify that it has been
called correctly.  Octave offers several functions for this purpose.

@menu
* Validating the number of Arguments::
* Validating the type of Arguments::
* Parsing Arguments::
@end menu

@node Validating the number of Arguments
@subsection Validating the number of Arguments

In Octave the following idiom is seen frequently at the beginning of a
function definition:

@example
@group
if (nargin < min_#_inputs || nargin > max_#_inputs)
  print_usage ();
endif
@end group
@end example

@noindent
which stops the function execution and prints a message about the correct
way to call the function whenever the number of inputs is wrong.

Similar error checking is provided by @code{narginchk} and
@code{nargoutchk}.

@c narginchk scripts/miscellaneous/narginchk.m
@anchor{XREFnarginchk}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFnargoutchk,,nargoutchk}, @ref{XREFerror,,error}, @ref{XREFnargout,,nargout}, @ref{XREFnargin,,nargin}}
@end deftypefn


@c nargoutchk scripts/miscellaneous/nargoutchk.m
@anchor{XREFnargoutchk}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFnarginchk,,narginchk}, @ref{XREFerror,,error}, @ref{XREFnargout,,nargout}, @ref{XREFnargin,,nargin}}
@end deftypefn


@node Validating the type of Arguments
@subsection Validating the type of Arguments

Besides the number of arguments, inputs can be checked for various
properties.  @code{validatestring} is used for string arguments and
@code{validateattributes} for numeric arguments.

@c validatestring scripts/strings/validatestring.m
@anchor{XREFvalidatestring}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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
cell array of strings 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{@ref{XREFstrcmp,,strcmp}, @ref{XREFstrcmpi,,strcmpi}, @ref{XREFvalidateattributes,,validateattributes}, @ref{XREFinputParser,,inputParser}}
@end deftypefn


@c validateattributes scripts/miscellaneous/validateattributes.m
@anchor{XREFvalidateattributes}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFisa,,isa}, @ref{XREFvalidatestring,,validatestring}, @ref{XREFinputParser,,inputParser}}
@end deftypefn


As alternatives to @code{validateattributes} there are several shorter
convenience functions to check for individual properties.

@c mustBeFinite scripts/miscellaneous/mustBeFinite.m
@anchor{XREFmustBeFinite}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeFinite (@var{x})

Require that input @var{x} is finite.

Raise an error if any element of the input @var{x} is not finite, as
determined by @code{isfinite (x)}.

@xseealso{@ref{XREFmustBeNonNan,,mustBeNonNan}, @ref{XREFisfinite,,isfinite}}
@end deftypefn


@c mustBeGreaterThan scripts/miscellaneous/mustBeGreaterThan.m
@anchor{XREFmustBeGreaterThan}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeGreaterThan (@var{x}, @var{c})

Require that input @var{x} is greater than @var{c}.

Raise an error if any element of the input @var{x} is not greater than
@var{c}, as determined by @code{@var{x} > @var{c}}.

@xseealso{@ref{XREFmustBeGreaterThanOrEqual,,mustBeGreaterThanOrEqual}, @ref{XREFmustBeLessThan,,mustBeLessThan}, @ref{XREFgt,,gt}}
@end deftypefn


@c mustBeGreaterThanOrEqual scripts/miscellaneous/mustBeGreaterThanOrEqual.m
@anchor{XREFmustBeGreaterThanOrEqual}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeGreaterThanOrEqual (@var{x}, @var{c})

Require that input @var{x} is greater than or equal to @var{c}.

Raise an error if any element of the input @var{x} is not greater than
or equal to @var{c}, as determined by @code{@var{x} >= @var{c}}.

@xseealso{@ref{XREFmustBeGreaterThan,,mustBeGreaterThan}, @ref{XREFmustBeLessThanOrEqual,,mustBeLessThanOrEqual}, @ref{XREFge,,ge}}
@end deftypefn


@c mustBeInteger scripts/miscellaneous/mustBeInteger.m
@anchor{XREFmustBeInteger}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeInteger (@var{x})

Require that input @var{x} is integer-valued (but not necessarily
integer-typed).

Raise an error if any element of the input @var{x} is not a finite,
real, integer-valued numeric value, as determined by various checks.

@xseealso{@ref{XREFmustBeNumeric,,mustBeNumeric}}
@end deftypefn


@c mustBeLessThan scripts/miscellaneous/mustBeLessThan.m
@anchor{XREFmustBeLessThan}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeLessThan (@var{x}, @var{c})

Require that input @var{x} is less than @var{c}.

Raise an error if any element of the input @var{x} is not less than
@var{c}, as determined by @code{@var{x} < @var{c}}.

@xseealso{@ref{XREFmustBeLessThanOrEqual,,mustBeLessThanOrEqual}, @ref{XREFmustBeGreaterThan,,mustBeGreaterThan}, @ref{XREFlt,,lt}}
@end deftypefn


@c mustBeLessThanOrEqual scripts/miscellaneous/mustBeLessThanOrEqual.m
@anchor{XREFmustBeLessThanOrEqual}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeLessThanOrEqual (@var{x}, @var{c})

Require that input is less than or equal to a given value.

Raise an error if any element of the input @var{x} is not less than
or equal to @var{c}, as determined by @code{@var{x} <= @var{c}}.

@xseealso{@ref{XREFmustBeLessThan,,mustBeLessThan}, @ref{XREFmustBeGreaterThanOrEqual,,mustBeGreaterThanOrEqual}, @ref{XREFle,,le}}
@end deftypefn


@c mustBeMember scripts/miscellaneous/mustBeMember.m
@anchor{XREFmustBeMember}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeMember (@var{x}, @var{valid})

Require that input @var{x} is a member of a set of given valid values.

Raise an error if any element of the input @var{x} is not a member
of the set @var{valid}, as determined by @code{ismember (@var{x})}.

Programming Note: char inputs may behave strangely because of the
interaction between chars and cellstrings when calling @code{ismember} on
them.  But it will probably "do what you mean" if you just use it naturally.
To guarantee operation, convert all char arrays to cellstrings with
@code{cellstr}.

@xseealso{@ref{XREFmustBeNonempty,,mustBeNonempty}, @ref{XREFismember,,ismember}}
@end deftypefn


@c mustBeNegative scripts/miscellaneous/mustBeNegative.m
@anchor{XREFmustBeNegative}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeNegative (@var{x})

Require that input @var{x} is negative.

Raise an error if any element of the input @var{x} is not negative, as
determined by @code{@var{x} < 0}.

@xseealso{@ref{XREFmustBeNonnegative,,mustBeNonnegative}}
@end deftypefn


@c mustBeNonempty scripts/miscellaneous/mustBeNonempty.m
@anchor{XREFmustBeNonempty}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeNonempty (@var{x})

Require that input @var{x} is nonempty.

Raise an error if the input @var{x} is empty, as determined by
@code{isempty (@var{x})}.

@xseealso{@ref{XREFmustBeMember,,mustBeMember}, @ref{XREFmustBeNonzero,,mustBeNonzero}, @ref{XREFisempty,,isempty}}
@end deftypefn


@c mustBeNonNan scripts/miscellaneous/mustBeNonNan.m
@anchor{XREFmustBeNonNan}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeNonNan (@var{x})

Require that input @var{x} is non-@code{NaN}.

Raise an error if any element of the input @var{x} is @code{NaN}, as
determined by @code{isnan (@var{x})}.

@xseealso{@ref{XREFmustBeFinite,,mustBeFinite}, @ref{XREFmustBeNonempty,,mustBeNonempty}, @ref{XREFisnan,,isnan}}
@end deftypefn


@c mustBeNonnegative scripts/miscellaneous/mustBeNonnegative.m
@anchor{XREFmustBeNonnegative}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeNonnegative (@var{x})

Require that input @var{x} is not negative.

Raise an error if any element of the input @var{x} is negative, as
determined by @code{@var{x} >= 0}.

@xseealso{@ref{XREFmustBeNonzero,,mustBeNonzero}, @ref{XREFmustBePositive,,mustBePositive}}
@end deftypefn


@c mustBeNonpositive scripts/miscellaneous/mustBeNonpositive.m
@anchor{XREFmustBeNonpositive}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeNonpositive (@var{x})

Require that input @var{x} is not positive.

Raise an error if any element of the input @var{x} is positive, as
determined by @code{@var{x} <= 0}.

@xseealso{@ref{XREFmustBeNegative,,mustBeNegative}, @ref{XREFmustBeNonzero,,mustBeNonzero}}
@end deftypefn


@c mustBeNonsparse scripts/miscellaneous/mustBeNonsparse.m
@anchor{XREFmustBeNonsparse}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeNonsparse (@var{x})

Require that input @var{x} is not sparse.

Raise an error if the input @var{x} is sparse, as determined by
@code{issparse (@var{x})}.

@xseealso{@ref{XREFissparse,,issparse}}
@end deftypefn


@c mustBeNonzero scripts/miscellaneous/mustBeNonzero.m
@anchor{XREFmustBeNonzero}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeNonzero (@var{x})

Require that input @var{x} is not zero.

Raise an error if any element of the input @var{x} is zero, as determined
by @code{@var{x} == 0}.

@xseealso{@ref{XREFmustBeNonnegative,,mustBeNonnegative}, @ref{XREFmustBePositive,,mustBePositive}}
@end deftypefn


@c mustBeNumeric scripts/miscellaneous/mustBeNumeric.m
@anchor{XREFmustBeNumeric}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeNumeric (@var{x})

Require that input @var{x} is numeric.

Raise an error if the input @var{x} is not numeric, as determined by
@code{isnumeric (@var{x})}.

@xseealso{@ref{XREFmustBeNumericOrLogical,,mustBeNumericOrLogical}, @ref{XREFisnumeric,,isnumeric}}
@end deftypefn


@c mustBeNumericOrLogical scripts/miscellaneous/mustBeNumericOrLogical.m
@anchor{XREFmustBeNumericOrLogical}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeNumericOrLogical (@var{x})

Require that input @var{x} is numeric or logical.

Raise an error if the input @var{x} is not numeric or logical, as
determined by @code{isnumeric (@var{x}) || islogical (@var{x})}.

@xseealso{@ref{XREFmustBeNumeric,,mustBeNumeric}, @ref{XREFisnumeric,,isnumeric}, @ref{XREFislogical,,islogical}}
@end deftypefn


@c mustBePositive scripts/miscellaneous/mustBePositive.m
@anchor{XREFmustBePositive}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBePositive (@var{x})

Require that input @var{x} is positive.

Raise an error if any element of the input @var{x} is not positive, as
determined by @code{@var{x} > 0}.

@xseealso{@ref{XREFmustBeNonnegative,,mustBeNonnegative}, @ref{XREFmustBeNonzero,,mustBeNonzero}}
@end deftypefn


@c mustBeReal scripts/miscellaneous/mustBeReal.m
@anchor{XREFmustBeReal}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mustBeReal (@var{x})

Require that input @var{x} is real.

Raise an error if the input @var{x} is not real, as determined by
@code{isreal (@var{x})}.

@xseealso{@ref{XREFmustBeFinite,,mustBeFinite}, @ref{XREFmustBeNonNan,,mustBeNonNan}, @ref{XREFisreal,,isreal}}
@end deftypefn


@node Parsing Arguments
@subsection Parsing Arguments

If none of the preceding validation functions is sufficient there is also
the class @code{inputParser} which can perform extremely complex input
checking for functions.

@c inputParser scripts/miscellaneous/inputParser.m
@anchor{XREFinputParser}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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 results accessed with
the @code{Results} accessor.
@end deftypefn

@deftypefn {} {} inputParser.Parameters
Return the list of parameter names already defined.  (read-only)
@end deftypefn

@deftypefn {} {} inputParser.Results
Return a structure with argument names as fieldnames and corresponding
values.  (read-only)
@end deftypefn

@deftypefn {} {} inputParser.Unmatched
Return a structure similar to @code{Results}, but for unmatched
parameters.  (read-only)
See the @code{KeepUnmatched} property.
@end deftypefn

@deftypefn {} {} inputParser.UsingDefaults
Return cell array with the names of arguments that are using default
values.  (read-only)
@end deftypefn

@deftypefn {} {} inputParser.FunctionName = @var{name}
Set function name to be used in error messages; Defaults to empty string.
@end deftypefn

@deftypefn {} {} inputParser.CaseSensitive = @var{boolean}
Set whether matching of argument names should be case sensitive; Defaults
to false.
@end deftypefn

@deftypefn {} {} inputParser.KeepUnmatched = @var{boolean}
Set whether string arguments which do not match any Parameter are parsed
and stored in the @code{Unmatched} property; Defaults to false.  If false,
an error will be emitted at the first unrecognized argument and parsing
will stop.  Note that since @code{Switch} and @code{Parameter} arguments
can be mixed, it is not possible to know the type of the unmatched
argument.  Octave assumes that all unmatched arguments are of the
@code{Parameter} type and therefore must be followed by a value.
@end deftypefn

@deftypefn {} {} inputParser.PartialMatching = @var{boolean}
Set whether argument names for @code{Parameter} and @code{Switch} options
may be given in shortened form as long as the name uniquely identifies
an option; Defaults to true.  For example, the argument @qcode{'opt'} will
match a parameter @qcode{'opt_color'}, but will fail if there is also a
parameter @qcode{'opt_case'}.
@end deftypefn

@deftypefn {} {} inputParser.StructExpand = @var{boolean}
Set whether a structure passed to the function is expanded into
parameter/value pairs (parameter = fieldname); 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 anonymous function handle for validators
  valid_vec = @@(x) isvector (x) && all (x >= 0) && all (x <= 1);
  p.addOptional ("vec", [0 0], valid_vec);

  ## Create two arguments of type "Parameter"
  vld_type = @@(x) any (strcmp (x, @{"linear", "quadratic"@}));
  p.addParameter ("type", "linear", vld_type);
  vld_tol = @@(x) any (strcmp (x, @{"low", "medium", "high"@}));
  p.addParameter ("tolerance", "low", vld_tol);

  ## 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 in with or before the Parameter argument type (but it
## must still appear after any Optional arguments).
check ("mech", "~/dev", [0 1 0 0], "verbose", "tolerance", "high");

## following returns an error since an Optional argument, 'path',
## was given after the Parameter argument 'type'.
check ("mech", "type", "linear", "~/dev");
@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 following the first two types.

@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{@ref{XREFnargin,,nargin}, @ref{XREFvalidateattributes,,validateattributes}, @ref{XREFvalidatestring,,validatestring}, @ref{XREFvarargin,,varargin}}
@end deftypefn


@node Function Files
@section Function Files
@cindex function file

Except for simple one-shot programs, it is not practical to have to
define all the functions you need each time you need them.  Instead, you
will normally want to save them in a file so that you can easily edit
them, and save them for use at a later time.

Octave does not require you to load function definitions from files
before using them.  You simply need to put the function definitions in a
place where Octave can find them.

When Octave encounters an identifier that is undefined, it first looks
for variables or functions that are already compiled and currently
listed in its symbol table.  If it fails to find a definition there, it
searches a list of directories (the @dfn{path}) for files ending in
@file{.m} that have the same base name as the undefined
identifier.@footnote{The @samp{.m} suffix was chosen for compatibility
with @sc{matlab}.}  Once Octave finds a file with a name that matches,
the contents of the file are read.  If it defines a @emph{single}
function, it is compiled and executed.  @xref{Script Files}, for more
information about how you can define more than one function in a single
file.

When Octave defines a function from a function file, it saves the full
name of the file it read and the time stamp on the file.  If the time
stamp on the file changes, Octave may reload the file.  When Octave is
running interactively, time stamp checking normally happens at most once
each time Octave prints the prompt.  Searching for new function
definitions also occurs if the current working directory changes.

Checking the time stamp allows you to edit the definition of a function
while Octave is running, and automatically use the new function
definition without having to restart your Octave session.

To avoid degrading performance unnecessarily by checking the time stamps
on functions that are not likely to change, Octave assumes that function
files in the directory tree
@file{@var{octave-home}/share/octave/@var{version}/m}
will not change, so it doesn't have to check their time stamps every time the
functions defined in those files are used.  This is normally a very good
assumption and provides a significant improvement in performance for the
function files that are distributed with Octave.

If you know that your own function files will not change while you are
running Octave, you can improve performance by calling
@code{ignore_function_time_stamp ("all")}, so that Octave will
ignore the time stamps for all function files.  Passing
@qcode{"system"} to this function resets the default behavior.

@c FIXME: note about time stamps on files in NFS environments?

@c edit scripts/miscellaneous/edit.m
@anchor{XREFedit}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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 default text editor.  The default editor
for the Octave GUI is specified in the Editor tab of Preferences.  The
default editor for the CLI is specified by the @code{EDITOR} function.

@itemize @bullet
@item
If the function @var{name} is available in a file on your path, then it
will be opened in the editor.  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 command-line function, then an m-file will
be created to contain that function along with its current definition.

@item
If @code{@var{name}.cc} is specified, then it will search for
@file{@var{name}.cc} in the path and open it in the editor.  If the file is
not found, then a new @file{.cc} file will be created.  If @var{name}
happens to be an m-file or command-line 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.

@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 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,,@code{system}}).

@item editinplace
Determines whether files should be edited in place, without regard to
whether they are modifiable or not.  The default is @code{true}.
Set it to @code{false} to have read-only function files automatically
copied to @samp{home}, if it exists, when editing them.

@item home
This value indicates a directory that system m-files should be copied into
before opening them in the editor.  The intent is that this directory is
also in the path, so that the edited copy of a system function file shadows
the original.  This setting only has an effect when @samp{editinplace} is
set to @code{false}.  The default is the empty matrix (@code{[]}), which
means it is not used.  The default in previous versions of Octave was
@file{~/octave}.
@end table
@xseealso{@ref{XREFEDITOR,,EDITOR}, @ref{XREFpath,,path}}
@end deftypefn


@c mfilename libinterp/parse-tree/oct-parse.yy
@anchor{XREFmfilename}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFinputname,,inputname}, @ref{XREFdbstack,,dbstack}}
@end deftypefn


@c ignore_function_time_stamp libinterp/corefcn/fcn-info.cc
@anchor{XREFignore_function_time_stamp}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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}/share/@var{version}/m} 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


@menu
* Manipulating the Load Path::
* Subfunctions::
* Private Functions::
* Nested Functions::
* Overloading and Autoloading::
* Function Locking::
* Function Precedence::
@end menu

@node Manipulating the Load Path
@subsection Manipulating the Load Path

When a function is called, Octave searches a list of directories for
a file that contains the function declaration.  This list of directories
is known as the load path.  By default the load path contains
a list of directories distributed with Octave plus the current
working directory.  To see your current load path call the @code{path}
function without any input or output arguments.

It is possible to add or remove directories to or from the load path
using @code{addpath} and @code{rmpath}.  As an example, the following
code adds @samp{~/Octave} to the load path.

@example
addpath ("~/Octave")
@end example

@noindent
After this the directory @samp{~/Octave} will be searched for functions.

@c addpath libinterp/corefcn/load-path.cc
@anchor{XREFaddpath}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} addpath (@var{dir1}, @dots{})
@deftypefnx {} {} addpath (@var{dir1}, @dots{}, @var{option})
@deftypefnx {} {@var{oldpath} =} addpath (@dots{})
Add named directories to the function search path.

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

The newly added paths appear in the load path in the same order that they
appear in the arguments of @code{addpath}.  When extending the load path to
the front, the last path in the list of arguments is added first.  When
extending the load path to the end, the first path in the list of arguments
is added first.

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{@ref{XREFpath,,path}, @ref{XREFrmpath,,rmpath}, @ref{XREFgenpath,,genpath}, @ref{XREFpathdef,,pathdef}, @ref{XREFsavepath,,savepath}, @ref{XREFpathsep,,pathsep}}
@end deftypefn


@c genpath libinterp/corefcn/load-path.cc
@anchor{XREFgenpath}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{pathstr} =} genpath (@var{dir})
@deftypefnx {} {@var{pathstr} =} genpath (@var{dir}, @var{skipdir1}, @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{@ref{XREFpath,,path}, @ref{XREFaddpath,,addpath}}
@end deftypefn


@c rmpath libinterp/corefcn/load-path.cc
@anchor{XREFrmpath}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} rmpath (@var{dir1}, @dots{})
@deftypefnx {} {@var{oldpath} =} 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{@ref{XREFpath,,path}, @ref{XREFaddpath,,addpath}, @ref{XREFgenpath,,genpath}, @ref{XREFpathdef,,pathdef}, @ref{XREFsavepath,,savepath}, @ref{XREFpathsep,,pathsep}}
@end deftypefn


@c savepath scripts/path/savepath.m
@anchor{XREFsavepath}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} savepath
@deftypefnx {} {} savepath @var{file}
@deftypefnx {} {@var{status} =} savepath (@dots{})
Save the unique portion of the current function search path to @var{file}.

The list of folders that are saved in @var{file} does @emph{not} include
the folders that are added for Octave's own functions, those that belong to
Octave packages (see @ref{XREFpkg,,pkg load}), and those added via command
line switches.

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{@ref{XREFpath,,path}, @ref{XREFaddpath,,addpath}, @ref{XREFrmpath,,rmpath}, @ref{XREFgenpath,,genpath}, @ref{XREFpathdef,,pathdef}}
@end deftypefn


@c path libinterp/corefcn/load-path.cc
@anchor{XREFpath}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFaddpath,,addpath}, @ref{XREFrmpath,,rmpath}, @ref{XREFgenpath,,genpath}, @ref{XREFpathdef,,pathdef}, @ref{XREFsavepath,,savepath}, @ref{XREFpathsep,,pathsep}}
@end deftypefn


@c pathdef scripts/path/pathdef.m
@anchor{XREFpathdef}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFpath,,path}, @ref{XREFaddpath,,addpath}, @ref{XREFrmpath,,rmpath}, @ref{XREFgenpath,,genpath}, @ref{XREFsavepath,,savepath}}
@end deftypefn


@c pathsep libinterp/corefcn/dirfns.cc
@anchor{XREFpathsep}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{val} =} pathsep ()
Query the character used to separate directories in a path.
@xseealso{@ref{XREFfilesep,,filesep}}
@end deftypefn


@c rehash libinterp/corefcn/load-path.cc
@anchor{XREFrehash}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} rehash ()
Reinitialize Octave's load path directory cache.
@end deftypefn


@c file_in_loadpath libinterp/corefcn/utils.cc
@anchor{XREFfile_in_loadpath}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFfile_in_path,,file_in_path}, @ref{XREFdir_in_loadpath,,dir_in_loadpath}, @ref{XREFpath,,path}}
@end deftypefn


@c restoredefaultpath libinterp/corefcn/load-path.cc
@anchor{XREFrestoredefaultpath}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{pathstr} =} restoredefaultpath ()
Restore Octave's path to its initial state at startup.

The re-initialized path is returned as an output.
@xseealso{@ref{XREFpath,,path}, @ref{XREFaddpath,,addpath}, @ref{XREFrmpath,,rmpath}, @ref{XREFgenpath,,genpath}, @ref{XREFpathdef,,pathdef}, @ref{XREFsavepath,,savepath}, @ref{XREFpathsep,,pathsep}}
@end deftypefn


@c command_line_path libinterp/corefcn/load-path.cc
@anchor{XREFcommand_line_path}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{pathstr} =} command_line_path ()
Return the path argument given to Octave at the command line when the
interpreter was started (@w{@env{--path @var{arg}}}).

@xseealso{@ref{XREFpath,,path}, @ref{XREFaddpath,,addpath}, @ref{XREFrmpath,,rmpath}, @ref{XREFgenpath,,genpath}, @ref{XREFpathdef,,pathdef}, @ref{XREFsavepath,,savepath}, @ref{XREFpathsep,,pathsep}}
@end deftypefn


@c dir_in_loadpath libinterp/corefcn/utils.cc
@anchor{XREFdir_in_loadpath}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFfile_in_path,,file_in_path}, @ref{XREFfile_in_loadpath,,file_in_loadpath}, @ref{XREFpath,,path}}
@end deftypefn


@c mfile_encoding libinterp/corefcn/input.cc
@anchor{XREFmfile_encoding}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{current_encoding} =} mfile_encoding ()
@deftypefnx {} {} mfile_encoding (@var{new_encoding})
@deftypefnx {} {@var{old_encoding} =} mfile_encoding (@var{new_encoding})
Query or set the encoding that is used for reading m-files.

The input and output are strings naming an encoding, e.g.,
@nospell{@qcode{"utf-8"}}.

This encoding is used by Octave's parser when reading m-files unless a
different encoding was set for a specific directory containing m-files using
the function @code{dir_encoding} or in a file @file{.oct-config} in that
directory.

The special value @qcode{"system"} selects the encoding that matches the system
locale.

If the m-file encoding is changed after the m-files have already been parsed,
the files have to be parsed again for that change to take effect.  That can be
triggered with the command @code{clear all}.

Additionally, this encoding is used to load and save files with the built-in
editor in Octave's GUI.

@xseealso{@ref{XREFdir_encoding,,dir_encoding}}
@end deftypefn


@c dir_encoding libinterp/corefcn/input.cc
@anchor{XREFdir_encoding}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{current_encoding} =} dir_encoding (@var{dir})
@deftypefnx {} {} dir_encoding (@var{dir}, @var{new_encoding})
@deftypefnx {} {} dir_encoding (@var{dir}, "delete")
@deftypefnx {} {@var{old_encoding} =} dir_encoding (@var{dir}, @var{new_encoding})
Query or set the @var{encoding} that is used for reading m-files in @var{dir}.

The per-directory encoding overrides the (globally set) m-file encoding,
@pxref{XREFmfile_encoding,,@code{mfile_encoding}}.

The string @var{DIR} must match how the directory would appear in the load
path.

The @var{new_encoding} input must be a valid encoding identifier or
@qcode{"delete"}.  In the latter case, any per-directory encoding is removed
and the (globally set) m-file encoding will be used for the given @var{dir}.

The currently or previously used encoding is returned only if an output
argument is requested.

The directory encoding is automatically read from the file @file{.oct-config}
when a new path is added to the load path (for example with @code{addpath}).
To set the encoding for all files in the same folder, that file must contain
a line starting with @qcode{"encoding="} followed by the encoding identifier.

For example to set the file encoding for all files in the same folder to
ISO 8859-1 (Latin-1), create a file @file{.oct-config} with the following
content:

@example
encoding=iso8859-1
@end example

If the file encoding is changed after the files have already been parsed, the
files have to be parsed again for that change to take effect.  That can be done
with the command @code{clear all}.

@xseealso{@ref{XREFaddpath,,addpath}, @ref{XREFpath,,path}, @ref{XREFmfile_encoding,,mfile_encoding}}
@end deftypefn


@node Subfunctions
@subsection Subfunctions

A function file may contain secondary functions called
@dfn{subfunctions}.  These secondary functions are only visible to the
other functions in the same function file.  For example, a file
@file{f.m} containing

@example
@group
function f ()
  printf ("in f, calling g\n");
  g ()
endfunction
function g ()
  printf ("in g, calling h\n");
  h ()
endfunction
function h ()
  printf ("in h\n")
endfunction
@end group
@end example

@noindent
defines a main function @code{f} and two subfunctions.  The
subfunctions @code{g} and @code{h} may only be called from the main
function @code{f} or from the other subfunctions, but not from outside
the file @file{f.m}.

@c localfunctions libinterp/corefcn/help.cc
@anchor{XREFlocalfunctions}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{subfcn_list} =} 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{@ref{XREFfunctions,,functions}}
@end deftypefn


@node Private Functions
@subsection Private Functions

In many cases one function needs to access one or more helper
functions.  If the helper function is limited to the scope of a single
function, then subfunctions as discussed above might be used.  However,
if a single helper function is used by more than one function, then
this is no longer possible.  In this case the helper functions might
be placed in a subdirectory, called "private", of the directory in which
the functions needing access to this helper function are found.

As a simple example, consider a function @code{func1}, that calls a helper
function @code{func2} to do much of the work.  For example:

@example
@group
function y = func1 (x)
  y = func2 (x);
endfunction
@end group
@end example

@noindent
Then if the path to @code{func1} is @code{<directory>/func1.m}, and if
@code{func2} is found in the directory @code{<directory>/private/func2.m},
then @code{func2} is only available for use of the functions, like
@code{func1}, that are found in @code{<directory>}.

@node Nested Functions
@subsection Nested Functions

Nested functions are similar to subfunctions in that only the main function is
visible outside the file.  However, they also allow for child functions to
access the local variables in their parent function.  This shared access mimics
using a global variable to share information --- but a global variable which is
not visible to the rest of Octave.  As a programming strategy, sharing data
this way can create code which is difficult to maintain.  It is recommended to
use subfunctions in place of nested functions when possible.

As a simple example, consider a parent function @code{foo}, that calls a nested
child function @code{bar}, with a shared variable @var{x}.

@example
@group
function y = foo ()
  x = 10;
  bar ();
  y = x;

  function bar ()
    x = 20;
  endfunction
endfunction

foo ()
 @result{} 20
@end group
@end example

@noindent
Notice that there is no special syntax for sharing @var{x}.  This can lead to
problems with accidental variable sharing between a parent function and its
child.  While normally variables are inherited, child function parameters and
return values are local to the child function.

Now consider the function @code{foobar} that uses variables @var{x} and
@var{y}.  @code{foobar} calls a nested function @code{foo} which takes
@var{x} as a parameter and returns @var{y}.  @code{foo} then calls @code{bat}
which does some computation.

@example
@group
function z = foobar ()
  x = 0;
  y = 0;
  z = foo (5);
  z += x + y;

  function y = foo (x)
    y = x + bat ();

    function z = bat ()
      z = x;
    endfunction
  endfunction
endfunction

foobar ()
    @result{} 10
@end group
@end example

@noindent
It is important to note that the @var{x} and @var{y} in @code{foobar} remain
zero, as in @code{foo} they are a return value and parameter respectively.  The
@var{x} in @code{bat} refers to the @var{x} in @code{foo}.

Variable inheritance leads to a problem for @code{eval} and scripts.  If a
new variable is created in a parent function, it is not clear what should
happen in nested child functions.  For example, consider a parent function
@code{foo} with a nested child function @code{bar}:

@example
@group
function y = foo (to_eval)
  bar ();
  eval (to_eval);

  function bar ()
    eval ("x = 100;");
    eval ("y = x;");
  endfunction
endfunction

foo ("x = 5;")
    @result{} error: can not add variable "x" to a static workspace

foo ("y = 10;")
    @result{} 10

foo ("")
    @result{} 100
@end group
@end example

@noindent
The parent function @code{foo} is unable to create a new variable
@var{x}, but the child function @code{bar} was successful.  Furthermore, even
in an @code{eval} statement @var{y} in @code{bar} is the same @var{y} as in its
parent function @code{foo}.  The use of @code{eval} in conjunction with nested
functions is best avoided.

As with subfunctions, only the first nested function in a file may be called
from the outside.  Inside a function the rules are more complicated.  In
general a nested function may call:

@enumerate 0
@item
Globally visible functions

@item
Any function that the nested function's parent can call

@item
Sibling functions (functions that have the same parents)

@item
Direct children

@end enumerate

As a complex example consider a parent function @code{ex_top} with two
child functions, @code{ex_a} and @code{ex_b}.  In addition, @code{ex_a} has two
more child functions, @code{ex_aa} and @code{ex_ab}.  For example:

@example
function ex_top ()
  ## Can call: ex_top, ex_a, and ex_b
  ## Can NOT call: ex_aa and ex_ab

  function ex_a ()
    ## Can call everything

    function ex_aa ()
      ## Can call everything
    endfunction

    function ex_ab ()
      ## Can call everything
    endfunction
  endfunction

  function ex_b ()
    ## Can call: ex_top, ex_a, and ex_b
    ## Can NOT call: ex_aa and ex_ab
  endfunction
endfunction
@end example

@node Overloading and Autoloading
@subsection Overloading and Autoloading

Functions can be overloaded to work with different input arguments.  For
example, the operator '+' has been overloaded in Octave to work with single,
double, uint8, int32, and many other arguments.  The preferred way to overload
functions is through classes and object oriented programming
(@pxref{Function Overloading}).  Occasionally, however, one needs to undo
user overloading and call the default function associated with a specific
type.  The @code{builtin} function exists for this purpose.

@c builtin libinterp/parse-tree/oct-parse.yy
@anchor{XREFbuiltin}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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


A single dynamically linked file might define several
functions.  However, as Octave searches for functions based on the
functions filename, Octave needs a manner in which to find each of the
functions in the dynamically linked file.  On operating systems that
support symbolic links, it is possible to create a symbolic link to the
original file for each of the functions which it contains.

However, there is at least one well known operating system that doesn't
support symbolic links.  Making copies of the original file for each of
the functions is undesirable as it increases the
amount of disk space used by Octave.  Instead Octave supplies the
@code{autoload} function, that permits the user to define in which
file a certain function will be found.

@c autoload libinterp/parse-tree/oct-parse.yy
@anchor{XREFautoload}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFPKG_ADD,,PKG_ADD}}
@end deftypefn


@node Function Locking
@subsection Function Locking

It is sometime desirable to lock a function into memory with the @code{mlock}
function.  This is typically used for dynamically linked functions in
oct-files or mex-files that contain some initialization, and it is desirable
that calling @code{clear} does not remove this initialization.

As an example,

@example
@group
function my_function ()
  mlock ();
  @dots{}
endfunction
@end group
@end example

@noindent
prevents @code{my_function} from being removed from memory after it is called,
even if @code{clear} is called.  It is possible to determine if a function is
locked into memory with the @code{mislocked}, and to unlock a function with
@code{munlock}, which the following code illustrates.

@example
@group
my_function ();
mislocked ("my_function")
@result{} ans = 1
munlock ("my_function");
mislocked ("my_function")
@result{} ans = 0
@end group
@end example

A common use of @code{mlock} is to prevent persistent variables from being
removed from memory, as the following example shows:

@example
@group
function count_calls ()
  mlock ();
  persistent calls = 0;
  printf ("count_calls() has been called %d times\n", ++calls);
endfunction

count_calls ();
@print{} count_calls() has been called 1 times

clear count_calls
count_calls ();
@print{} count_calls() has been called 2 times
@end group
@end example

@code{mlock} might also be used to prevent changes to an m-file, such as in an
external editor, from having any effect in the current Octave session; A
similar effect can be had with the @code{ignore_function_time_stamp} function.

@c mlock libinterp/corefcn/variables.cc
@anchor{XREFmlock}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mlock ()
Lock the current function into memory so that it can't be removed with
@code{clear}.
@xseealso{@ref{XREFmunlock,,munlock}, @ref{XREFmislocked,,mislocked}, @ref{XREFpersistent,,persistent}, @ref{XREFclear,,clear}}
@end deftypefn


@c munlock libinterp/corefcn/variables.cc
@anchor{XREFmunlock}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFmlock,,mlock}, @ref{XREFmislocked,,mislocked}, @ref{XREFpersistent,,persistent}, @ref{XREFclear,,clear}}
@end deftypefn


@c mislocked libinterp/corefcn/variables.cc
@anchor{XREFmislocked}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tf} =} mislocked ()
@deftypefnx {} {@var{tf} =} 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{@ref{XREFmlock,,mlock}, @ref{XREFmunlock,,munlock}, @ref{XREFpersistent,,persistent}, @ref{XREFclear,,clear}}
@end deftypefn


@node Function Precedence
@subsection Function Precedence

Given the numerous different ways that Octave can define a function, it
is possible and even likely that multiple versions of a function, might be
defined within a particular scope.  The precedence of which function will be
used within a particular scope is given by

@enumerate 1
@item Subfunction
A subfunction with the required function name in the given scope.

@item Private function
A function defined within a private directory of the directory
which contains the current function.

@item Class constructor
A function that constructs a user class as defined in chapter
@ref{Object Oriented Programming}.

@item Class method
An overloaded function of a class as in chapter
@ref{Object Oriented Programming}.

@item Command-line Function
A function that has been defined on the command-line.

@item Autoload function
A function that is marked as autoloaded with @xref{XREFautoload,,autoload}.

@item A Function on the Path
A function that can be found on the users load-path.  There can also be
Oct-file, mex-file or m-file versions of this function and the precedence
between these versions are in that order.

@item Built-in function
A function that is a part of core Octave such as @code{numel}, @code{size},
etc.
@end enumerate

@node Script Files
@section Script Files

A script file is a file containing (almost) any sequence of Octave
commands.  It is read and evaluated just as if you had typed each
command at the Octave prompt, and provides a convenient way to perform a
sequence of commands that do not logically belong inside a function.

Unlike a function file, a script file must @emph{not} begin with the
keyword @code{function}.  If it does, Octave will assume that it is a
function file, and that it defines a single function that should be
evaluated as soon as it is defined.

A script file also differs from a function file in that the variables
named in a script file are not local variables, but are in the same
scope as the other variables that are visible on the command line.

Even though a script file may not begin with the @code{function}
keyword, it is possible to define more than one function in a single
script file and load (but not execute) all of them at once.  To do
this, the first token in the file (ignoring comments and other white
space) must be something other than @code{function}.  If you have no
other statements to evaluate, you can use a statement that has no
effect, like this:

@example
@group
# Prevent Octave from thinking that this
# is a function file:

1;

# Define function one:

function one ()
  @dots{}
@end group
@end example

To have Octave read and compile these functions into an internal form,
you need to make sure that the file is in Octave's load path
(accessible through the @code{path} function), then simply type the
base name of the file that contains the commands.  (Octave uses the
same rules to search for script files as it does to search for
function files.)

If the first token in a file (ignoring comments) is @code{function},
Octave will compile the function and try to execute it, printing a
message warning about any non-whitespace characters that appear after
the function definition.

Note that Octave does not try to look up the definition of any identifier
until it needs to evaluate it.  This means that Octave will compile the
following statements if they appear in a script file, or are typed at
the command line,

@example
@group
# not a function file:
1;
function foo ()
  do_something ();
endfunction
function do_something ()
  do_something_else ();
endfunction
@end group
@end example

@noindent
even though the function @code{do_something} is not defined before it is
referenced in the function @code{foo}.  This is not an error because
Octave does not need to resolve all symbols that are referenced by a
function until the function is actually evaluated.

Since Octave doesn't look for definitions until they are needed, the
following code will always print @samp{bar = 3} whether it is typed
directly on the command line, read from a script file, or is part of a
function body, even if there is a function or script file called
@file{bar.m} in Octave's path.

@example
@group
eval ("bar = 3");
bar
@end group
@end example

Code like this appearing within a function body could fool Octave if
definitions were resolved as the function was being compiled.  It would
be virtually impossible to make Octave clever enough to evaluate this
code in a consistent fashion.  The parser would have to be able to
perform the call to @code{eval} at compile time, and that would be
impossible unless all the references in the string to be evaluated could
also be resolved, and requiring that would be too restrictive (the
string might come from user input, or depend on things that are not
known until the function is evaluated).

Although Octave normally executes commands from script files that have
the name @file{@var{file}.m}, you can use the function @code{source} to
execute commands from any file.

@c source libinterp/parse-tree/oct-parse.yy
@anchor{XREFsource}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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{@ref{XREFrun,,run}}
@end deftypefn


@menu
* Publish Octave Script Files::
* Publishing Markup::
* Jupyter Notebooks::
@end menu

@node Publish Octave Script Files
@subsection Publish Octave Script Files

The function @code{publish} provides a dynamic possibility to document your
script file.  Unlike static documentation, @code{publish} runs the script
file, saves any figures and output while running the script, and presents them
alongside static documentation in a desired output format.  The static
documentation can make use of @ref{Publishing Markup} to enhance and
customize the output.

@c publish scripts/miscellaneous/publish.m
@anchor{XREFpublish}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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 Publishing Markup in section comments, which
is explained in detail in the GNU Octave manual.  Section comments are
comment blocks that start with a line with double comment character.

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

When called with one input argument, a HTML report is generated in a
subdirectory @file{html} relative to the current working directory.  Any
Octave commands in @file{pub_example.m} are evaluated in a separate context
and any figures created while executing the script file are 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{@ref{XREFgrabcode,,grabcode}}
@end deftypefn


The counterpart to @code{publish} is @code{grabcode}:

@c grabcode scripts/miscellaneous/grabcode.m
@anchor{XREFgrabcode}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} grabcode @var{filename}
@deftypefnx {} {} grabcode @var{url}
@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 to a
new filename 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{@ref{XREFpublish,,publish}}
@end deftypefn


@node Publishing Markup
@subsection Publishing Markup

@menu
* Using Publishing Markup in Script Files::
* Text Formatting::
* Sections::
* Preformatted Code::
* Preformatted Text::
* Bulleted Lists::
* Numbered Lists::
* Including File Content::
* Including Graphics::
* Including URLs::
* Mathematical Equations::
* HTML Markup::
* LaTeX Markup::
@end menu

@node Using Publishing Markup in Script Files
@subsubsection Using Publishing Markup in Script Files

To use Publishing Markup, start by typing @samp{##} or @samp{%%} at the
beginning of a new line.  For @sc{matlab} compatibility @samp{%%%} is treated
the same way as @samp{%%}.

The lines following @samp{##} or @samp{%%} start with one of either
@samp{#} or @samp{%} followed by at least one space.  These lines are
interpreted as section.  A section ends at the first line not starting
with @samp{#} or @samp{%}, or when the end of the document is reached.

A section starting in the first line of the document, followed by another
start of a section that might be empty, is interpreted as a document
title and introduction text.

See the example below for clarity:

@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 ()

## Octave comment style supported as well
#
# * Bulleted list item 1
# * Bulleted list item 2
#
# # Numbered list item 1
# # Numbered list item 2
@end group
@end example

@node Text Formatting
@subsubsection Text Formatting

Basic text formatting is supported inside sections, see the example
given below:

@example
@group
##
# @b{*bold*}, @i{_italic_}, or |monospaced| Text
@end group
@end example

Additionally two trademark symbols are supported, just embrace the letters
@samp{TM} or @samp{R}.

@example
@group
##
# (TM) or (R)
@end group
@end example

@node Sections
@subsubsection Sections

A section is started by typing @samp{##} or @samp{%%} at the beginning of
a new line.  A section title can be provided by writing it, separated by a
space, in the first line after @samp{##} or @samp{%%}.  Without a section
title, the section is interpreted as a continuation of the previous section.
For @sc{matlab} compatibility @samp{%%%} is treated the same way as @samp{%%}.

@example
@group
some_code ();

## Section 1
#
## Section 2

some_code ();

##
# Still in section 2

some_code ();

%%% Section 3
%
%
@end group
@end example

@node Preformatted Code
@subsubsection Preformatted Code

To write preformatted code inside a section, indent the code by three
spaces after @samp{#} at the beginning of each line and leave the lines
above and below the code blank, except for @samp{#} at the beginning of
those lines.

@example
@group
##
# This is a syntax highlighted for-loop:
#
#   for i = 1:5
#     disp (i);
#   endfor
#
# And more usual text.
@end group
@end example

@node Preformatted Text
@subsubsection Preformatted Text

To write preformatted text inside a section, indent the code by two spaces
after @samp{#} at the beginning of each line and leave the lines above and
below the preformatted text blank, except for @samp{#} at the beginning of
those lines.

@example
@group
##
# This following text is preformatted:
#
#  "To be, or not to be: that is the question:
#  Whether 'tis nobler in the mind to suffer
#  The slings and arrows of outrageous fortune,
#  Or to take arms against a sea of troubles,
#  And by opposing end them?  To die: to sleep;"
#
#  --"Hamlet" by W. Shakespeare
@end group
@end example

@node Bulleted Lists
@subsubsection Bulleted Lists

To create a bulleted list, type

@example
@group
##
#
# * Bulleted list item 1
# * Bulleted list item 2
#
@end group
@end example

@noindent
to get output like

@itemize @bullet
@item Bulleted list item 1

@item Bulleted list item 2
@end itemize

Notice the blank lines, except for the @samp{#} or @samp{%} before and
after the bulleted list!

@node Numbered Lists
@subsubsection Numbered Lists

To create a numbered list, type

@example
@group
##
#
# # Numbered list item 1
# # Numbered list item 2
#
@end group
@end example

@noindent
to get output like

@enumerate
@item Numbered list item 1

@item Numbered list item 2
@end enumerate

Notice the blank lines, except for the @samp{#} or @samp{%} before and
after the numbered list!

@node Including File Content
@subsubsection Including File Content

To include the content of an external file, e.g., a file called
@samp{my_function.m} at the same location as the published Octave script,
use the following syntax to include it with Octave syntax highlighting.

Alternatively, you can write the full or relative path to the file.

@example
@group
##
#
# <include>my_function.m</include>
#
# <include>/full/path/to/my_function.m</include>
#
# <include>../relative/path/to/my_function.m</include>
#
@end group
@end example

@node Including Graphics
@subsubsection Including Graphics

To include external graphics, e.g., a graphic called @samp{my_graphic.png}
at the same location as the published Octave script, use the following syntax.

Alternatively, you can write the full path to the graphic.

@example
@group
##
#
# <<my_graphic.png>>
#
# <</full/path/to/my_graphic.png>>
#
# <<../relative/path/to/my_graphic.png>>
#
@end group
@end example

@node Including URLs
@subsubsection Including URLs

Basically, a URL is written between an opening @samp{<} and a closing @samp{>}
angle.

@example
@group
##
# <https://www.octave.org>
@end group
@end example

Text that is within these angles and separated by at least one space from the
URL is a displayed text for the link.

@example
@group
##
# <https://www.octave.org GNU Octave>
@end group
@end example

A link starting with @samp{<octave:} followed by the name of a GNU Octave
function, optionally with a displayed text, results in a link to the online
GNU Octave documentations function index.

@example
@group
##
# <octave:DISP The display function>
@end group
@end example

@node Mathematical Equations
@subsubsection Mathematical Equations

One can insert @LaTeX{} inline math, surrounded by single @samp{$} signs, or
displayed math, surrounded by double @samp{$$} signs, directly inside
sections.

@example
@group
##
# Some shorter inline equation $e^@{ix@} = \cos x + i\sin x$.
#
# Or more complicated formulas as displayed math:
# $$e^x = \lim_@{n\rightarrow\infty@}\left(1+\dfrac@{x@}@{n@}\right)^@{n@}.$$
@end group
@end example

@node HTML Markup
@subsubsection HTML Markup

If the published output is a HTML report, you can insert HTML markup,
that is only visible in this kind of output.

@example
@group
##
# <html>
# <table style="border:1px solid black;">
# <tr><td>1</td><td>2</td></tr>
# <tr><td>3</td><td>3</td></tr>
# </html>
@end group
@end example

@node LaTeX Markup
@subsubsection LaTeX Markup

If the published output is a @LaTeX{} or PDF report, you can insert @LaTeX{}
markup, that is only visible in this kind of output.

@example
@group
##
# <latex>
# Some output only visible in @nospell{LaTeX} or PDF reports.
# \begin@{equation@}
# e^x = \lim\limits_@{n\rightarrow\infty@}\left(1+\dfrac@{x@}@{n@}\right)^@{n@}
# \end@{equation@}
# </latex>
@end group
@end example

@node Jupyter Notebooks
@subsection Jupyter Notebooks
@cindex Jupyter Notebooks

Jupyter notebooks are one popular technique for displaying code, text, and
graphical output together in a comprehensive manner.  Octave can publish
results to a Jupyter notebook with the function @code{jupyter_notebook}.

@c jupyter_notebook scripts/miscellaneous/jupyter_notebook.m
@anchor{XREFjupyter_notebook}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{notebook} =} jupyter_notebook (@var{notebook_filename})
@deftypefnx {} {@var{notebook} =} jupyter_notebook (@var{notebook_filename}, @var{options})

Run and fill the Jupyter Notebook in file @var{notebook_filename} from
within GNU Octave.

Both text and graphical Octave outputs are supported.

This class has a public property @code{notebook} which is a structure
representing the JSON-decoded Jupyter Notebook.  This property is
intentionally public to enable advanced notebook manipulations.

Note: Jupyter Notebook versions (@code{nbformat}) lower than 4.0 are not
supported.

The optional second argument @var{options} is a struct with fields:

@itemize @bullet
@item
@code{tmpdir} to set the temporary working directory.
@end itemize

@code{%plot} magic is supported with the following settings:

@itemize @bullet
@item
"@code{%plot -f <format>}" or "@code{%plot --format <format>}": specifies
the image storage format.  Supported formats are:

@itemize @minus
@item
PNG (default)

@item SVG
(Note: If SVG images do not appear in the notebook, it is most likely
related to Jupyter Notebook security mechanisms and explicitly "trusting"
them will be necessary).

@item
JPG
@end itemize

@item
"@code{%plot -r <number>}" or "@code{%plot --resolution <number>}":
specifies the image resolution.

@item
"@code{%plot -w <number>}" or "@code{%plot --width <number>}":
specifies the image width.

@item
"@code{%plot -h <number>}" or "@code{%plot --height <number>}":
specifies the image height.
@end itemize

Examples:

@example
@group
## Run all cells and generate the filled notebook

## Instantiate an object from a notebook file
notebook = jupyter_notebook ("myNotebook.ipynb");
## Run the code and embed the results in the @code{notebook} property
notebook.run_all ();
## Generate a new notebook by overwriting the original notebook
notebook.generate_notebook ("myNotebook.ipynb");
@end group

@group
## Run just the second cell and generate the filled notebook

## Instantiate an object from a notebook file
notebook = jupyter_notebook ("myNotebook.ipynb");
## Run the code and embed the results in the @code{notebook} property
notebook.run (2)
## Generate a new notebook in a new file
notebook.generate_notebook ("myNewNotebook.ipynb");
@end group

@group
## Generate an Octave script from a notebook

## Instantiate an object from a notebook file
notebook = jupyter_notebook ("myNotebook.ipynb");
## Generate the Octave script
notebook.generate_octave_script ("jup_script.m");
@end group
@end example

@xseealso{@ref{XREFjsondecode,,jsondecode}, @ref{XREFjsonencode,,jsonencode}}
@end deftypefn


@node Function Handles and Anonymous Functions
@section Function Handles and Anonymous Functions
@cindex handle, function handles
@cindex anonymous functions

It can be very convenient store a function in a variable so that it
can be passed to a different function.  For example, a function that
performs numerical minimization needs access to the function that
should be minimized.

@menu
* Function Handles::
* Anonymous Functions::
@end menu

@node Function Handles
@subsection Function Handles

A function handle is a pointer to another function and is defined with
the syntax

@example
@@@var{function-name}
@end example

@noindent
For example,

@example
f = @@sin;
@end example

@noindent
creates a function handle called @code{f} that refers to the
function @code{sin}.

Function handles are used to call other functions indirectly, or to pass
a function as an argument to another function like @code{quad} or
@code{fsolve}.  For example:

@example
@group
f = @@sin;
quad (f, 0, pi)
    @result{} 2
@end group
@end example

You may use @code{feval} to call a function using function handle, or
simply write the name of the function handle followed by an argument
list.  If there are no arguments, you must use an empty argument list
@samp{()}.  For example:

@example
@group
f = @@sin;
feval (f, pi/4)
    @result{} 0.70711
f (pi/4)
    @result{} 0.70711
@end group
@end example

@c is_function_handle libinterp/octave-value/ov-fcn-handle.cc
@anchor{XREFis_function_handle}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} is_function_handle (@var{x})
Return true if @var{x} is a function handle.
@xseealso{@ref{XREFisa,,isa}, @ref{XREFtypeinfo,,typeinfo}, @ref{XREFclass,,class}, @ref{XREFfunctions,,functions}}
@end deftypefn


@c functions libinterp/octave-value/ov-fcn-handle.cc
@anchor{XREFfunctions}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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 nested
The function is nested.

@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{@ref{XREFfunc2str,,func2str}, @ref{XREFstr2func,,str2func}}
@end deftypefn


@c func2str libinterp/octave-value/ov-fcn-handle.cc
@anchor{XREFfunc2str}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{str} =} func2str (@var{fcn_handle})
Return a string containing the name of the function referenced by the function
handle @var{fcn_handle}.
@xseealso{@ref{XREFstr2func,,str2func}, @ref{XREFfunctions,,functions}}
@end deftypefn


@c str2func libinterp/octave-value/ov-fcn-handle.cc
@anchor{XREFstr2func}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{hfcn} =} str2func (@var{str})
Return a function handle constructed from the string @var{str}.

The input may be the name of a function such as @qcode{"sin"} or a string
defining a function such as @qcode{"@@(x) sin (x + pi)"}.

Programming Note: In most cases it will be better to use anonymous function
syntax and let the Octave parser create the function handle rather than use
@code{str2func}.  For example:

@example
@group
hfcn = @@sin ;
hfcn = @@(x) sin (x + pi) ;
@end group
@end example

@xseealso{@ref{XREFfunc2str,,func2str}, @ref{XREFfunctions,,functions}}
@end deftypefn


@c symvar scripts/miscellaneous/symvar.m
@anchor{XREFsymvar}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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


@node Anonymous Functions
@subsection Anonymous Functions

Anonymous functions are defined using the syntax

@example
@@(@var{argument-list}) @var{expression}
@end example

@noindent
Any variables that are not found in the argument list are inherited from
the enclosing scope.  Anonymous functions are useful for creating simple
unnamed functions from expressions or for wrapping calls to other
functions to adapt them for use by functions like @code{quad}.  For
example,

@example
@group
f = @@(x) x.^2;
quad (f, 0, 10)
    @result{} 333.33
@end group
@end example

@noindent
creates a simple unnamed function from the expression @code{x.^2} and
passes it to @code{quad},

@example
@group
quad (@@(x) sin (x), 0, pi)
    @result{} 2
@end group
@end example

@noindent
wraps another function, and

@example
@group
a = 1;
b = 2;
quad (@@(x) betainc (x, a, b), 0, 0.4)
    @result{} 0.13867
@end group
@end example

@noindent
adapts a function with several parameters to the form required by
@code{quad}.  In this example, the values of @var{a} and @var{b} that
are passed to @code{betainc} are inherited from the current
environment.

Note that for performance reasons it is better to use handles to existing
Octave functions, rather than to define anonymous functions which wrap an
existing function.  The integration of @code{sin (x)} is 5X faster if the code
is written as

@example
quad (@@sin, 0, pi)
@end example

@noindent
rather than using the anonymous function @code{@@(x) sin (x)}.  There are many
operators which have functional equivalents that may be better choices than an
anonymous function.  Instead of writing

@example
f = @@(x, y) x + y
@end example

@noindent
this should be coded as

@example
f = @@plus
@end example

@xref{Operator Overloading}, for a list of operators which also have a
functional form.

@node Command Syntax and Function Syntax
@section Command Syntax and Function Syntax
@cindex commands functions

In addition to the function syntax described above (i.e., calling a function
like @code{fun (arg1, arg2, @dots{})}), a function can be called using command
syntax (for example, calling a function like @code{fun arg1 arg2 @dots{}}).  In
that case, all arguments are passed to the function as strings.  For example,

@example
my_command hello world
@end example

@noindent
is equivalent to

@example
my_command ("hello", "world")
@end example

@noindent
The general form of a command call is

@example
cmdname arg1 arg2 @dots{}
@end example

@noindent
which translates directly to

@example
cmdname ("arg1", "arg2", @dots{})
@end example

If an argument including spaces should be passed to a function in command
syntax, (double-)quotes can be used.  For example,

@example
my_command "first argument" "second argument"
@end example

@noindent
is equivalent to

@example
my_command ("first argument", "second argument")
@end example

Any function can be used as a command if it accepts string input arguments.
For example:

@example
@group
upper lower_case_arg
   @result{} ans = LOWER_CASE_ARG
@end group
@end example

Since the arguments are passed as strings to the corresponding function, it is
not possible to pass input arguments that are stored in variables.  In that
case, a command must be called using the function syntax.  For example:

@example
@group
strvar = "hello world";
upper strvar
   @result{} ans = STRVAR
upper (strvar)
   @result{} ans = HELLO WORLD
@end group
@end example

Additionally, the return values of functions cannot be assigned to variables
using the command syntax.  Only the first return argument is assigned to the
built-in variable @code{ans}.  If the output argument of a command should be
assigned to a variable, or multiple output arguments of a function should be
returned, the function syntax must be used.

It should be noted that mixing command syntax and binary operators can
create apparent ambiguities with mathematical and logical expressions that
use function syntax.  For example, all three of the statements

@example
@group
arg1 - arg2
arg1 -arg2
arg1-arg2
@end group
@end example

@noindent
could be intended by a user to be subtraction operations between
@code{arg1} and @code{arg2}.  The first two, however, could also have been
meant as a command syntax call to function @code{arg1}, in the first case
with options @code{-} and @code{arg2}, and in the second case with option
@option{-arg2}.

Octave uses whitespace to interpret such expressions according to the
following rules:

@itemize @bullet
@item
Statements consisting of plain symbols without any operators that are
separated only by whitespace are always treated as command syntax:

@example
arg1 arg2 arg3 ... argn
@end example

@item
Statements without any whitespace are always treated as function syntax:

@example
@group
arg1+arg2
arg1&&arg2||arg3
arg1+=arg2*arg3
@end group
@end example

@item
If the first symbol is a constant (or special-valued named constant pi, i,
I, j, J, e, NaN, or Inf) followed by a binary operator, the statement is
treated as function syntax regardless of any whitespace or what follows the
second symbol:

@example
@group
7 -arg2
pi+ arg2
j * arg2 -arg3
@end group
@end example

@item
If the first symbol is a function or variable and there is no whitespace
separating the operator and the second symbol, the statement is treated
as command syntax:

@example
@group
arg1 -arg2
arg1 &&arg2 ||arg3
arg1 +=arg2*arg3
@end group
@end example

@item
Any other whitespace combination will result in the statement being treated
as function syntax.
@end itemize

Note 1: If a special-valued named constant has been redefined as a
variable, the interpreter will still process the statement with function
syntax.

Note 2: Attempting to use a variable as @code{arg1} in a command being
processed as command syntax will result in an error.


@node Organization of Functions
@section Organization of Functions Distributed with Octave

Many of Octave's standard functions are distributed as function files.
They are loosely organized by topic, in subdirectories of
@file{@var{octave-home}/share/octave/@var{version}/m}, to make it easier
to find them.

The following is a list of all the function file subdirectories, and the
types of functions you will find there.

@table @file
@item @@ftp
Class functions for the FTP object.

@item +containers
Package for the containers classes.

@item audio
Functions for playing and recording sounds.

@item deprecated
Out-of-date functions which will eventually be removed from Octave.

@item elfun
Elementary functions, principally trigonometric.

@item general
Miscellaneous matrix manipulations, like @code{flipud}, @code{rot90},
and @code{triu}, as well as other basic functions, like
@code{ismatrix}, @code{narginchk}, etc.

@item geometry
Functions related to Delaunay triangulation.

@item gui
Functions for GUI elements like dialog, message box, etc.

@item help
Functions for Octave's built-in help system.

@item image
Image processing tools.  These functions require the X Window System.

@item io
Input-output functions.

@item java
Functions related to the Java integration.

@item linear-algebra
Functions for linear algebra.

@item miscellaneous
Functions that don't really belong anywhere else.

@item ode
Functions to solve ordinary differential equations (ODEs).

@item optimization
Functions related to minimization, optimization, and root finding.

@item path
Functions to manage the directory path Octave uses to find functions.

@item pkg
Package manager for installing external packages of functions in Octave.

@item plot
Functions for displaying and printing two- and three-dimensional graphs.

@item polynomial
Functions for manipulating polynomials.

@item prefs
Functions implementing user-defined preferences.

@item set
Functions for creating and manipulating sets of unique values.

@item signal
Functions for signal processing applications.

@item sparse
Functions for handling sparse matrices.

@item specfun
Special functions such as @code{bessel} or @code{factor}.

@item special-matrix
Functions that create special matrix forms such as Hilbert or
@nospell{Vandermonde} matrices.

@item startup
Octave's system-wide startup file.

@item statistics
Statistical functions.

@item strings
Miscellaneous string-handling functions.

@item testfun
Functions for performing unit tests on other functions.

@item time
Functions related to time and date processing.
@end table