<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) ????-2008 - INRIA
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="functions">
    <refnamediv>
        <refname>functions</refname>
        <refpurpose>Scilab procedures and Scilab objects</refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>
            Functions are Scilab procedures ("macro", "function" and "procedure"
            have the save meaning).
        </para>
    </refsection>
    <refsection>
        <title>Function definition</title>
        <para>
            Usually, they are defined in files with an editor and loaded into
            Scilab using the  <link linkend="exec">exec</link> function or through a library (see
            <link linkend="lib">lib</link> or <link linkend="genlib">genlib</link>). But they can also be
            defined on-line (see  <link linkend="deff">deff</link> or <link linkend="function">function</link>.
            A function is defined by two components:
        </para>
        <itemizedlist>
            <listitem>
                <para>a "syntax definition" part  as follows:</para>
                <programlisting role='no-scilab-exec'>
                    <![CDATA[
function [y1,...,yn]=foo(x1,...,xm)
function [y1,...,yn,varargout]=foo(x1,...,xm,varargin)
 ]]>
                </programlisting>
            </listitem>
            <listitem>
                <para>a sequence of Scilab instructions.</para>
            </listitem>
        </itemizedlist>
        <para>
            The "syntax definition" line gives the "full" calling syntax of
            this function. The <literal>yi</literal> are output variables
            calculated as functions of input variables <literal>xi</literal>
            and variables existing in Scilab when the function is
            executed.
        </para>
    </refsection>
    <refsection>
        <title>Calling function</title>
        <itemizedlist>
            <listitem>
                <para>
                    Usually function calling syntax is
                    <literal>[y1,...,yn]=foo(x1,...,xm)</literal>. Shorter input or
                    output argument list than definition ones may be used. In such
                    cases, only the first variables from the left are used or set.
                </para>
                <para>
                    The <literal>nargin</literal> and <literal>nargout</literal> variables can be used to obtain the actual number of input and output arguments.
                </para>
                <para>
                    <literal>_</literal> can be used to ignore output argument(s).
                </para>
                <para>
                    <code>[_, b, _, d] = regexp(...");</code> in this case, only the 2nd and 4th parameters will be assign to output variables
                </para>
            </listitem>
            <listitem>
                <para>
                    It is possible to define function with indeterminate
                    number of input or output maximum number of arguments. This
                    can be done using the <link linkend="varargin">varargin</link>
                    and <link linkend="varargout">varargout</link>
                    keywords. See the given links for details.
                </para>
            </listitem>
            <listitem>
                <para>
                    It is also possible to use "named argument" to specify input
                    arguments: suppose function <function>fun1</function> defined as
                    <code>function y1 = fun1(x1, x2, x3)</code> then it can be
                    called with a syntax like
                    <code>y = fun1(x1=33, x3=[1 2 3])</code>
                    within <function>fun1</function> <varname>x2</varname> will be
                    undefined.
                </para>
                <para>
                    It can also be called with a syntax like
                    <code>y = fun1(x1=33, y='foo')</code>. In such a case the
                    <varname>y</varname> variable will be available in the context
                    of the function <function>fun1</function>.
                    <note>
                        Note that the maximum number of argument must be
                        less or equal to the number of formal input
                        argument used in the function syntax part.
                    </note>
                </para>
                <para>
                    It is possible to check for defined variables with
                    the <link linkend="exists">exists</link> function.
                </para>
            </listitem>
            <listitem>
                <para>
                    When a function has no left hand side argument and
                    is called only with character string arguments, the
                    calling syntax may be simplified:
                </para>
                <programlisting role='no-scilab-exec'>
                    <![CDATA[
fun('a','toto','a string')
 ]]>
                </programlisting>
                <para>is equivalent to: </para>
                <programlisting role='no-scilab-exec'>
                    <![CDATA[
fun a toto 'a string'
 ]]>
                </programlisting>
            </listitem>
        </itemizedlist>
    </refsection>
    <refsection>
        <title>Miscellaneous</title>
        <para>
            Functions are Scilab objects (with type numbers 13 or 11). And they can be manipulated (built, saved, loaded, passed as
            arguments,...) as other variable types.
        </para>
        <para>
            Collections of functions can be collected in libraries.  Functions
            which begin with <literal>%</literal> sign
            (e.g. <literal>%foo</literal>) are often used to overload (see <link linkend="overloading">overloading</link>) operations or functions for new data type.
        </para>
        <para>
            Note that a function name must respect some syntax rules (see <link linkend="names">names</link>).
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example">
            <![CDATA[
//inline definition (see function)
function [x,y]=myfct(a,b)
  x=a+b
  y=a-b
endfunction

[x,y]=myfct(3,2)

//inline definition (see deff)
deff('[x,y]=myfct(a,b)',['x=a+b';
                         'y=a-b'])
// definition in an ascii file (see exec)
exec SCI/modules/elementary_functions/macros/asinh.sci;
 ]]>
        </programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="function">function</link>
            </member>
            <member>
                <link linkend="deff">deff</link>
            </member>
            <member>
                <link linkend="exec">exec</link>
            </member>
            <member>
                <link linkend="lib">lib</link>
            </member>
            <member>
                <link linkend="getd">getd</link>
            </member>
            <member>
                <link linkend="genlib">genlib</link>
            </member>
            <member>
                <link linkend="exists">exists</link>
            </member>
            <member>
                <link linkend="varargin">varargin</link>
            </member>
            <member>
                <link linkend="varargout">varargout</link>
            </member>
            <member>
                <link linkend="names">names</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
