<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 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: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="pt">
    <refnamediv>
        <refname>overloading</refname>
        <refpurpose>capacidades de overloading ("sobrecarga") de exibições,
            funções e operadores
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Descrição</title>
        <para>No Scilab, exibições, funções e operadores de variáveis podem ser
            definidos para novos objetos utilizando funções (codificadas no Scilab ou
            primitivas).
        </para>
        <variablelist>
            <varlistentry>
                <term>Exibição (Display)</term>
                <listitem>
                    <para>a exibição de objetos definidos por uma estrutura
                        <literal>tlist</literal> pode ser sobrecarregada (a exibição padrão
                        é semelhante a de <literal>list</literal>'s). A função de sobrecarga
                        não deve ter argumentos de saída e deve ter um único argumento de
                        entrada. Seu nome é formado como segue:
                        <literal>%&lt;tlist_type&gt;_p</literal> onde
                        <literal>%&lt;tlist_type&gt;</literal> significa a primeira entrada
                        do componente do tipo <literal>tlist</literal> truncado aos 9
                        primeiros caracteres.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Operadores (Operators)</term>
                <listitem>
                    <para>cada operador que não está definido para dados tipos de
                        operandos pode ser definido. A função de sobrecarga deve ter um
                        único argumento de saída e um ou dois de entrada de acordo com o
                        número de operandos. O nome da função é definido como segue:
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>para operadores binários:
            <literal>%&lt;tipo_do_primeiro_operando&gt;_&lt;código_do_
                operador&gt;_&lt;tipo_do_segundo_operando&gt;
            </literal>
        </para>
        <para>para operadores unários:
            <literal>%&lt;tipo_do_operando&gt;_&lt;código_do_operador&gt;</literal>
        </para>
        <para>Operadores de extração e inserção que são n-nários são descritos
            abaixo.
        </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;tipo_do_operando&gt;</literal>,
            <literal>&lt;tipo_do_primeiro_operando&gt;</literal>,
            <literal>&lt;tipo_do_segundo_operando&gt;</literal> são seqüências de
            caracteres associadas a cada tipo de dado como descrito na tabela
            seguinte:
        </para>
        <informaltable>
            <tr>
            <td>
            <informaltable border="1">
                <tr><td>tipo de dado</td>       <td>código "char"</td>          </tr>
                <tr><td>booleano</td>           <td><literal>b</literal></td>   </tr>
                <tr><td>esparso booleano</td>   <td><literal>spb</literal></td> </tr>
                <tr><td>inteiro</td>            <td><literal>i</literal></td>   </tr>
                <tr><td>número decimal</td>     <td><literal>s</literal></td>   </tr>
                <tr><td>matriz esparsa</td>     <td><literal>sp</literal></td>  </tr>
                <tr><td>matriz esparsa do Matlab</td><td><literal>msp</literal></td></tr>
                <tr><td>polinômio</td>          <td><literal>p</literal></td>   </tr>
                <tr><td>fração racional</td>    <td><literal>r</literal></td>   </tr>
                <tr><td>texto</td>              <td><literal>c</literal></td>   </tr>
                <tr><td>gráfico</td>            <td><literal>h</literal></td>   </tr>
            </informaltable>
            </td>
            <td> </td>
            <td>
            <informaltable border="1">
                <tr><td>tipo de dado</td>       <td>código "char"</td>          </tr>
                <tr><td><literal>function</literal></td><td><literal>function</literal></td></tr>
                <tr><td>hard-coded função</td>  <td><literal>fptr</literal></td></tr>
                <tr><td>biblioteca</td>         <td><literal>f</literal></td>   </tr>
                <tr><td>lista</td>              <td><literal>l</literal></td>   </tr>
                <tr><td>tlist</td>              <td><literal>tlist_type</literal></td></tr>
                <tr><td>mlist</td>              <td><literal>mlist_type</literal></td></tr>
                <tr><td>lista implícita</td>    <td><literal>ip</literal></td>  </tr>
                <tr><td>cell</td>               <td><literal>ce</literal></td> </tr>
                <tr><td>structure</td>          <td><literal>st</literal></td> </tr>
                <tr><td>linear dynamical system</td><td><literal>lss</literal></td> </tr>
                <tr><td>ponteiro</td>           <td><literal>ptr</literal></td> </tr>
                <tr><td>undefined|null object</td><td><literal>0</literal></td> </tr>
              </informaltable>
            </td>
            </tr>
        </informaltable>
        <para>
            <literal>&lt;código_do_operador&gt;</literal> é um único caractere
            associado a cada operador como descrito na tabela seguinte:
        </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>A função de sobrecarga para sintaxe de extração
            <literal>b=a(i1,...,in)</literal> tem a seguinte seqüência de chamamento:
            <literal>b=%&lt;tipo_de_a&gt;_e(i1,...,in,a)</literal>
        </para>
        <para>
            e a sintaxe<literal>[x1,..,xm]=a(i1,...,in)</literal> tem a seguinte
            seqüência de chamamento:
            <literal>[x1,..,xm]=%&lt;tipo_de_a&gt;_e(i1,...,in,a)</literal>
        </para>
        <para>A função de sobrecarga associada à sintaxe de inserção
            <literal>a(i1,...,in)=b</literal> tem a segunite seqüência de
            chamamento:<literal>
                a=%&lt;tipo_de_b&gt;_i_&lt;tipo_de_a&gt;(i1,...,in,b,a)
            </literal>
            .
        </para>
        <para>
            O código "char" <literal>6</literal> pode ser usado para alguns
            algoritmos de inserção complexos como <code>x.b(2) = 33</code> onde o
            campo <literal>b</literal> não está definido na estrutura
            <literal>x</literal>. A inserção é automaticamente decomposta em
            <literal>temp=x.b;</literal> <code>temp(2) = 33</code>;
            <code>x.b = temp</code>. O código "char" <literal>6</literal> é usado
            para o primeiro passo desse algoritmo. A função de sobrecarga de
            <literal>6</literal> é muito semelhante à função de
            <literal>e</literal>'s.
        </para>
        <variablelist>
            <varlistentry>
                <term>Funções (Functions)</term>
                <listitem>
                    <para>algumas funções primitivas básicas também podem ser
                        sobrecarregadas para novos tipo de dados. Quando tal função não é
                        definida para tipos de dados particulares, a função <literal>
                            %&lt;tipo_de_um_argumento&gt;_&lt;nome_da_função&gt;
                        </literal>
                        é
                        chamada. O usuário pode adicionar a esta função chamada a definição
                        associada aos tipos de dados de entrada.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Exemplos</title>
    </refsection>
    <refsection>
        <programlisting role="example">//EXIBIÇÃO
            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">//OPERADOR
            '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">//FUNÇÃO
            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>
        <title>Ver Também</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>Histórico</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>
