<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA
 * Copyright (C) DIGITEO - 2012 - Allan CORNET
 *
 * 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:ns5="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
          xmlns:scilab="http://www.scilab.org" xml:id="overloading" xml:lang="en">
    <refnamediv>
        <refname>overloading</refname>
        <refpurpose>display, functions and operators overloading
            capabilities
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>In Scilab, variable display, functions and operators may be defined
            for new objects using functions (Scilab coded or primitives).
        </para>
        <variablelist>
            <varlistentry>
                <term>Display</term>
                <listitem>
                    <para>
                        The display of new objects defined by <literal>tlist</literal>
                        structure may be overloaded (the default display is similar to
                        <literal>list</literal>'s one). The overloading function must have
                        no output argument and a single input argument. It's name is formed as
                        follow <literal>%&lt;tlist_type&gt;_p</literal> where
                        <literal>%&lt;tlist_type&gt;</literal> stands for the first entry of
                        the <literal>tlist</literal> type component truncated to the first 9
                        characters.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Operators</term>
                <listitem>
                    <para>Each operator which is not defined for given operands type may
                        be defined. The overloading function must have a single output
                        argument and one or two inputs according to the number of operands.
                        The function name is formed as follow:
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>for binary operators:
            <literal>%&lt;first_operand_type&gt;_&lt;op_code&gt;_&lt;second_operand_type&gt;</literal>;
        </para>
        <para>for unary operators:
            <literal>%&lt;operand_type&gt;_&lt;op_code&gt;</literal>;
        </para>
        <para>extraction and insertion operators which are n-nary operators are
            described below.
        </para>
        <warning>Be careful, only the types registered by the
            <function>typename</function> function can be used in an overloading
            macros.
        </warning>
        <para>
            <literal>&lt;operand_type&gt;</literal>,
            <literal>&lt;first_operand_type&gt;</literal>,
            <literal>&lt;second_operand_type&gt;</literal> are sequence of characters
            associated with each data type as described in the following table:
        </para>
        <informaltable border="1">
            <tr>
                <td>data type</td>
                <td>char code</td>
                <td>typeof</td>
                <td>comments</td>
            </tr>
            <tr>
                <td>double matrix</td>
                <td>
                    <literal>s</literal>
                </td>
                <td>
                    <literal>constant</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>polynomial matrix</td>
                <td>
                    <literal>p</literal>
                </td>
                <td>
                    <literal>polynomial</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>boolean matrix</td>
                <td>
                    <literal>b</literal>
                </td>
                <td>
                    <literal>boolean</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>sparse matrix</td>
                <td>
                    <literal>sp</literal>
                </td>
                <td>
                    <literal>sparse</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>boolean sparse matrix</td>
                <td>
                    <literal>spb</literal>
                </td>
                <td>
                    <literal>boolean sparse</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>Matlab sparse matrix</td>
                <td>
                    <literal>msp</literal>
                </td>
                <td>
                    <literal>Matlab sparse</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>integer matrix</td>
                <td>
                    <literal>i</literal>
                </td>
                <td>
                    <literal>int8, int16, int32, int64, uint8, uint16, uint32, uint64</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>string matrix</td>
                <td>
                    <literal>c</literal>
                </td>
                <td>
                    <literal>string</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>handle</td>
                <td>
                    <literal>h</literal>
                </td>
                <td>
                    <literal>handle</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>hard-coded function</td>
                <td>
                    <literal>fptr</literal>
                </td>
                <td>
                    <literal>fptr</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>script function</td>
                <td>
                    <literal>function</literal>
                </td>
                <td>
                    <literal>function</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>library</td>
                <td>
                    <literal>f</literal>
                </td>
                <td>
                    <literal>library</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>list</td>
                <td>
                    <literal>l</literal>
                </td>
                <td>
                    <literal>list</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>tlist</td>
                <td>
                    <literal>tlist type</literal>
                </td>
                <td>
                    <literal>tlist type</literal>
                </td>
                <td>the first string in the first tlist entry</td>
            </tr>
            <tr>
                <td>mlist</td>
                <td>
                    <literal>mlist type</literal>
                </td>
                <td>
                    <literal>mlist type</literal>
                </td>
                <td>the first string in the first mlist entry</td>
            </tr>
            <tr>
                <td>hypermatrix</td>
                <td>
                    <literal>hm</literal>
                </td>
                <td>
                    <literal>hypermat</literal>
                </td>
                <td>Obsolete. Will be removed from Scilab 6.
                    The code of the hypermat contents must be targeted instead.
                </td>
            </tr>
            <tr>
                <td>pointer</td>
                <td>
                    <literal>ptr</literal>
                </td>
                <td>
                    <literal>pointer</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>cell</td>
                <td>
                    <literal>ce</literal>
                </td>
                <td>
                    <literal>ce</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>structure</td>
                <td>
                    <literal>st</literal>
                </td>
                <td>
                    <literal>st</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>rational</td>
                <td>
                    <literal>r</literal>
                </td>
                <td>
                    <literal>rational</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>linear state space</td>
                <td>
                    <literal>lss</literal>
                </td>
                <td>
                    <literal>state-space</literal>
                </td>
                <td/>
            </tr>
            <tr>
                <td>implicit list</td>
                <td>
                    <literal>ip</literal>
                </td>
                <td>
                    <literal>implicitlist</literal>
                </td>
                <td>1:1:$</td>
            </tr>
            <tr>
                <td>undefined|null object</td>
                <td>
                    <literal>0</literal>
                </td>
                <td>
                    <literal>listdelete, void</literal>
                </td>
                <td>see null(), list()</td>
            </tr>
        </informaltable>
        <para>
            <literal>&lt;op_code&gt;</literal> is a single character associated
            with each operator as described in the following table:
        </para>
        <informaltable border="1">
            <tr>
                <td>
                    <literal>op</literal>
                </td>
                <td>char code</td>
            </tr>
            <tr>
                <td>
                    <literal>'</literal>
                </td>
                <td>t</td>
            </tr>
            <tr>
                <td>
                    <literal>+</literal>
                </td>
                <td>a</td>
            </tr>
            <tr>
                <td>
                    <literal>-</literal>
                </td>
                <td>s</td>
            </tr>
            <tr>
                <td>
                    <literal>*</literal>
                </td>
                <td>m</td>
            </tr>
            <tr>
                <td>
                    <literal>/</literal>
                </td>
                <td>r</td>
            </tr>
            <tr>
                <td>
                    <literal>\</literal>
                </td>
                <td>l</td>
            </tr>
            <tr>
                <td>
                    <literal>^</literal>
                </td>
                <td>p</td>
            </tr>
            <tr>
                <td>
                    <literal>.*</literal>
                </td>
                <td>x</td>
            </tr>
            <tr>
                <td>
                    <literal>./</literal>
                </td>
                <td>d</td>
            </tr>
            <tr>
                <td>
                    <literal>.\</literal>
                </td>
                <td>q</td>
            </tr>
            <tr>
                <td>
                    <literal>.*.</literal>
                </td>
                <td>k</td>
            </tr>
            <tr>
                <td>
                    <literal>./.</literal>
                </td>
                <td>y</td>
            </tr>
            <tr>
                <td>
                    <literal>.\.</literal>
                </td>
                <td>z</td>
            </tr>
            <tr>
                <td>
                    <literal>:</literal>
                </td>
                <td>b</td>
            </tr>
            <tr>
                <td>
                    <literal>*.</literal>
                </td>
                <td>u</td>
            </tr>
            <tr>
                <td>
                    <literal>/.</literal>
                </td>
                <td>v</td>
            </tr>
            <tr>
                <td>
                    <literal>\.</literal>
                </td>
                <td>w</td>
            </tr>
            <tr>
                <td>
                    <literal>[a,b]</literal>
                </td>
                <td>c</td>
            </tr>
            <tr>
                <td>
                    <literal>[a;b]</literal>
                </td>
                <td>f</td>
            </tr>
            <tr>
                <td>
                    <literal>() extraction</literal>
                </td>
                <td>e</td>
            </tr>
            <tr>
                <td>
                    <literal>() insertion</literal>
                </td>
                <td>i</td>
            </tr>
            <tr>
                <td>
                    <literal>==</literal>
                </td>
                <td>o</td>
            </tr>
            <tr>
                <td>
                    <literal>&lt;&gt;</literal>
                </td>
                <td>n</td>
            </tr>
            <tr>
                <td>
                    <literal>|</literal>
                </td>
                <td>g</td>
            </tr>
            <tr>
                <td>
                    <literal>&amp;</literal>
                </td>
                <td>h</td>
            </tr>
            <tr>
                <td>
                    <literal>.^</literal>
                </td>
                <td>j</td>
            </tr>
            <tr>
                <td>
                    <literal>.'</literal>
                </td>
                <td>0</td>
            </tr>
            <tr>
                <td>
                    <literal>&lt;</literal>
                </td>
                <td>1</td>
            </tr>
            <tr>
                <td>
                    <literal>&gt;</literal>
                </td>
                <td>2</td>
            </tr>
            <tr>
                <td>
                    <literal>&lt;=</literal>
                </td>
                <td>3</td>
            </tr>
            <tr>
                <td>
                    <literal>&gt;=</literal>
                </td>
                <td>4</td>
            </tr>
            <tr>
                <td>
                    <literal>~</literal>
                </td>
                <td>5</td>
            </tr>
            <tr>
                <td>
                    <literal>iext</literal>
                </td>
                <td>6</td>
            </tr>
        </informaltable>
        <para>
            The overloading function for extraction syntax <literal>b= a(i1,
                ..., in)
            </literal>
            has the following syntax: <literal>b =
                %&lt;type_of_a&gt;_e(i1, ..., in, a)
            </literal>
        </para>
        <para>
            and the syntax <literal>[x1, .., xm] = a(i1, ..., in)</literal> has
            the following syntax: <literal>[x1, .., xm] =
                %&lt;type_of_a&gt;_e(i1, ..., in, a)
            </literal>
            .
        </para>
        <para>The overloading function associated to the insertion syntax
            <literal>a(i1, ..., in) = b</literal> has the following syntax:
            <literal>a = %&lt;type_of_b&gt;_i_&lt;type_of_a&gt;(i1, ..., in, b,
                a)
            </literal>
            .
        </para>
        <para>
            The <literal>6</literal> char code may be used for some complex
            insertion algorithm like <code>x.b(2) = 33</code> where
            <literal>b</literal> field is not defined in the structure
            <literal>x</literal>. The insertion is automatically decomposed into
            <code>temp = x.b</code>; <code>temp(2) = 33</code>;
            <code>x.b = temp</code>. The <literal>6</literal> char code is used
            for the first step of this algorithm. The <literal>6</literal> overloading
            function is very similar to the <literal>e</literal>'s one.
        </para>
        <variablelist>
            <varlistentry>
                <term>Functions :</term>
                <listitem>
                    <para>
                        Some basic primitive function may also be overloaded for new data type. When such function
                        is undefined for a particular data types the function
                        <literal>%&lt;type_of_an_argument&gt;_&lt;function_name&gt;</literal>
                        is called. User may add in this called function the definition
                        associated with the input data types.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Examples</title>
    </refsection>
    <refsection>
        <programlisting role="example">//DISPLAY
            var = tlist('tab', ['a', 'b'], ['x'; 'y'], rand(2, 2)) // the type of var is 'tab'

            typeof(var)

            function [] = %tab_p(l)
            disp([[' '; l(3)] [l(2); string(l(4))]])
            endfunction

            var // after overloading
        </programlisting>
    </refsection>
    <refsection>
        <programlisting role="example">//OPERATOR
            's' + 1 // it is impossible to add a number to a string

            function x = %c_a_s(a, b)
            x = a + string(b);
            endfunction

            's' + 1 // after overloading
        </programlisting>
    </refsection>
    <refsection>
        <programlisting role="example">//FUNCTION
            sin('2 * x') // the sin function does not work with a string

            function x = %c_sin(a)
            x = 'sin(' + a + ')'
            endfunction

            sin('2 * x') // after overloading
        </programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="tlist">tlist</link>
            </member>
            <member>
                <link linkend="disp">disp</link>
            </member>
            <member>
                <link linkend="symbols">symbols</link>
            </member>
            <member>
                <link linkend="typeof">typeof</link>
            </member>
            <member>
                <link linkend="type">type</link>
            </member>
            <member>
                <link linkend="typename">typename</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.0</revnumber>
                <revdescription>
                  <literal>function</literal> replaces <literal>mc</literal> as overloading code
                  for functions in Scilab language.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
