* Bug 14900 fixed: function overloading code mc => function
[scilab.git] / scilab / modules / functions / help / en_US / overloading.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA
5  * Copyright (C) DIGITEO - 2012 - Allan CORNET
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org" xml:id="overloading" xml:lang="en">
21     <refnamediv>
22         <refname>overloading</refname>
23         <refpurpose>display, functions and operators overloading
24             capabilities
25         </refpurpose>
26     </refnamediv>
27     <refsection>
28         <title>Description</title>
29         <para>In Scilab, variable display, functions and operators may be defined
30             for new objects using functions (Scilab coded or primitives).
31         </para>
32         <variablelist>
33             <varlistentry>
34                 <term>Display</term>
35                 <listitem>
36                     <para>
37                         The display of new objects defined by <literal>tlist</literal>
38                         structure may be overloaded (the default display is similar to
39                         <literal>list</literal>'s one). The overloading function must have
40                         no output argument and a single input argument. It's name is formed as
41                         follow <literal>%&lt;tlist_type&gt;_p</literal> where
42                         <literal>%&lt;tlist_type&gt;</literal> stands for the first entry of
43                         the <literal>tlist</literal> type component truncated to the first 9
44                         characters.
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>Operators</term>
50                 <listitem>
51                     <para>Each operator which is not defined for given operands type may
52                         be defined. The overloading function must have a single output
53                         argument and one or two inputs according to the number of operands.
54                         The function name is formed as follow:
55                     </para>
56                 </listitem>
57             </varlistentry>
58         </variablelist>
59         <para>for binary operators:
60             <literal>%&lt;first_operand_type&gt;_&lt;op_code&gt;_&lt;second_operand_type&gt;</literal>;
61         </para>
62         <para>for unary operators:
63             <literal>%&lt;operand_type&gt;_&lt;op_code&gt;</literal>;
64         </para>
65         <para>extraction and insertion operators which are n-nary operators are
66             described below.
67         </para>
68         <warning>Be careful, only the types registered by the
69             <function>typename</function> function can be used in an overloading
70             macros.
71         </warning>
72         <para>
73             <literal>&lt;operand_type&gt;</literal>,
74             <literal>&lt;first_operand_type&gt;</literal>,
75             <literal>&lt;second_operand_type&gt;</literal> are sequence of characters
76             associated with each data type as described in the following table:
77         </para>
78         <informaltable border="1">
79             <tr>
80                 <td>data type</td>
81                 <td>char code</td>
82                 <td>typeof</td>
83                 <td>comments</td>
84             </tr>
85             <tr>
86                 <td>double matrix</td>
87                 <td>
88                     <literal>s</literal>
89                 </td>
90                 <td>
91                     <literal>constant</literal>
92                 </td>
93                 <td/>
94             </tr>
95             <tr>
96                 <td>polynomial matrix</td>
97                 <td>
98                     <literal>p</literal>
99                 </td>
100                 <td>
101                     <literal>polynomial</literal>
102                 </td>
103                 <td/>
104             </tr>
105             <tr>
106                 <td>boolean matrix</td>
107                 <td>
108                     <literal>b</literal>
109                 </td>
110                 <td>
111                     <literal>boolean</literal>
112                 </td>
113                 <td/>
114             </tr>
115             <tr>
116                 <td>sparse matrix</td>
117                 <td>
118                     <literal>sp</literal>
119                 </td>
120                 <td>
121                     <literal>sparse</literal>
122                 </td>
123                 <td/>
124             </tr>
125             <tr>
126                 <td>boolean sparse matrix</td>
127                 <td>
128                     <literal>spb</literal>
129                 </td>
130                 <td>
131                     <literal>boolean sparse</literal>
132                 </td>
133                 <td/>
134             </tr>
135             <tr>
136                 <td>Matlab sparse matrix</td>
137                 <td>
138                     <literal>msp</literal>
139                 </td>
140                 <td>
141                     <literal>Matlab sparse</literal>
142                 </td>
143                 <td/>
144             </tr>
145             <tr>
146                 <td>integer matrix</td>
147                 <td>
148                     <literal>i</literal>
149                 </td>
150                 <td>
151                     <literal>int8, int16, int32, int64, uint8, uint16, uint32, uint64</literal>
152                 </td>
153                 <td/>
154             </tr>
155             <tr>
156                 <td>string matrix</td>
157                 <td>
158                     <literal>c</literal>
159                 </td>
160                 <td>
161                     <literal>string</literal>
162                 </td>
163                 <td/>
164             </tr>
165             <tr>
166                 <td>handle</td>
167                 <td>
168                     <literal>h</literal>
169                 </td>
170                 <td>
171                     <literal>handle</literal>
172                 </td>
173                 <td/>
174             </tr>
175             <tr>
176                 <td>hard-coded function</td>
177                 <td>
178                     <literal>fptr</literal>
179                 </td>
180                 <td>
181                     <literal>fptr</literal>
182                 </td>
183                 <td/>
184             </tr>
185             <tr>
186                 <td>script function</td>
187                 <td>
188                     <literal>function</literal>
189                 </td>
190                 <td>
191                     <literal>function</literal>
192                 </td>
193                 <td/>
194             </tr>
195             <tr>
196                 <td>library</td>
197                 <td>
198                     <literal>f</literal>
199                 </td>
200                 <td>
201                     <literal>library</literal>
202                 </td>
203                 <td/>
204             </tr>
205             <tr>
206                 <td>list</td>
207                 <td>
208                     <literal>l</literal>
209                 </td>
210                 <td>
211                     <literal>list</literal>
212                 </td>
213                 <td/>
214             </tr>
215             <tr>
216                 <td>tlist</td>
217                 <td>
218                     <literal>tlist type</literal>
219                 </td>
220                 <td>
221                     <literal>tlist type</literal>
222                 </td>
223                 <td>the first string in the first tlist entry</td>
224             </tr>
225             <tr>
226                 <td>mlist</td>
227                 <td>
228                     <literal>mlist type</literal>
229                 </td>
230                 <td>
231                     <literal>mlist type</literal>
232                 </td>
233                 <td>the first string in the first mlist entry</td>
234             </tr>
235             <tr>
236                 <td>hypermatrix</td>
237                 <td>
238                     <literal>hm</literal>
239                 </td>
240                 <td>
241                     <literal>hypermat</literal>
242                 </td>
243                 <td>Obsolete. Will be removed from Scilab 6.
244                     The code of the hypermat contents must be targeted instead.
245                 </td>
246             </tr>
247             <tr>
248                 <td>pointer</td>
249                 <td>
250                     <literal>ptr</literal>
251                 </td>
252                 <td>
253                     <literal>pointer</literal>
254                 </td>
255                 <td/>
256             </tr>
257             <tr>
258                 <td>cell</td>
259                 <td>
260                     <literal>ce</literal>
261                 </td>
262                 <td>
263                     <literal>ce</literal>
264                 </td>
265                 <td/>
266             </tr>
267             <tr>
268                 <td>structure</td>
269                 <td>
270                     <literal>st</literal>
271                 </td>
272                 <td>
273                     <literal>st</literal>
274                 </td>
275                 <td/>
276             </tr>
277             <tr>
278                 <td>rational</td>
279                 <td>
280                     <literal>r</literal>
281                 </td>
282                 <td>
283                     <literal>rational</literal>
284                 </td>
285                 <td/>
286             </tr>
287             <tr>
288                 <td>linear state space</td>
289                 <td>
290                     <literal>lss</literal>
291                 </td>
292                 <td>
293                     <literal>state-space</literal>
294                 </td>
295                 <td/>
296             </tr>
297             <tr>
298                 <td>implicit list</td>
299                 <td>
300                     <literal>ip</literal>
301                 </td>
302                 <td>
303                     <literal>implicitlist</literal>
304                 </td>
305                 <td>1:1:$</td>
306             </tr>
307             <tr>
308                 <td>undefined|null object</td>
309                 <td>
310                     <literal>0</literal>
311                 </td>
312                 <td>
313                     <literal>listdelete, void</literal>
314                 </td>
315                 <td>see null(), list()</td>
316             </tr>
317         </informaltable>
318         <para>
319             <literal>&lt;op_code&gt;</literal> is a single character associated
320             with each operator as described in the following table:
321         </para>
322         <informaltable border="1">
323             <tr>
324                 <td>
325                     <literal>op</literal>
326                 </td>
327                 <td>char code</td>
328             </tr>
329             <tr>
330                 <td>
331                     <literal>'</literal>
332                 </td>
333                 <td>t</td>
334             </tr>
335             <tr>
336                 <td>
337                     <literal>+</literal>
338                 </td>
339                 <td>a</td>
340             </tr>
341             <tr>
342                 <td>
343                     <literal>-</literal>
344                 </td>
345                 <td>s</td>
346             </tr>
347             <tr>
348                 <td>
349                     <literal>*</literal>
350                 </td>
351                 <td>m</td>
352             </tr>
353             <tr>
354                 <td>
355                     <literal>/</literal>
356                 </td>
357                 <td>r</td>
358             </tr>
359             <tr>
360                 <td>
361                     <literal>\</literal>
362                 </td>
363                 <td>l</td>
364             </tr>
365             <tr>
366                 <td>
367                     <literal>^</literal>
368                 </td>
369                 <td>p</td>
370             </tr>
371             <tr>
372                 <td>
373                     <literal>.*</literal>
374                 </td>
375                 <td>x</td>
376             </tr>
377             <tr>
378                 <td>
379                     <literal>./</literal>
380                 </td>
381                 <td>d</td>
382             </tr>
383             <tr>
384                 <td>
385                     <literal>.\</literal>
386                 </td>
387                 <td>q</td>
388             </tr>
389             <tr>
390                 <td>
391                     <literal>.*.</literal>
392                 </td>
393                 <td>k</td>
394             </tr>
395             <tr>
396                 <td>
397                     <literal>./.</literal>
398                 </td>
399                 <td>y</td>
400             </tr>
401             <tr>
402                 <td>
403                     <literal>.\.</literal>
404                 </td>
405                 <td>z</td>
406             </tr>
407             <tr>
408                 <td>
409                     <literal>:</literal>
410                 </td>
411                 <td>b</td>
412             </tr>
413             <tr>
414                 <td>
415                     <literal>*.</literal>
416                 </td>
417                 <td>u</td>
418             </tr>
419             <tr>
420                 <td>
421                     <literal>/.</literal>
422                 </td>
423                 <td>v</td>
424             </tr>
425             <tr>
426                 <td>
427                     <literal>\.</literal>
428                 </td>
429                 <td>w</td>
430             </tr>
431             <tr>
432                 <td>
433                     <literal>[a,b]</literal>
434                 </td>
435                 <td>c</td>
436             </tr>
437             <tr>
438                 <td>
439                     <literal>[a;b]</literal>
440                 </td>
441                 <td>f</td>
442             </tr>
443             <tr>
444                 <td>
445                     <literal>() extraction</literal>
446                 </td>
447                 <td>e</td>
448             </tr>
449             <tr>
450                 <td>
451                     <literal>() insertion</literal>
452                 </td>
453                 <td>i</td>
454             </tr>
455             <tr>
456                 <td>
457                     <literal>==</literal>
458                 </td>
459                 <td>o</td>
460             </tr>
461             <tr>
462                 <td>
463                     <literal>&lt;&gt;</literal>
464                 </td>
465                 <td>n</td>
466             </tr>
467             <tr>
468                 <td>
469                     <literal>|</literal>
470                 </td>
471                 <td>g</td>
472             </tr>
473             <tr>
474                 <td>
475                     <literal>&amp;</literal>
476                 </td>
477                 <td>h</td>
478             </tr>
479             <tr>
480                 <td>
481                     <literal>.^</literal>
482                 </td>
483                 <td>j</td>
484             </tr>
485             <tr>
486                 <td>
487                     <literal>.'</literal>
488                 </td>
489                 <td>0</td>
490             </tr>
491             <tr>
492                 <td>
493                     <literal>&lt;</literal>
494                 </td>
495                 <td>1</td>
496             </tr>
497             <tr>
498                 <td>
499                     <literal>&gt;</literal>
500                 </td>
501                 <td>2</td>
502             </tr>
503             <tr>
504                 <td>
505                     <literal>&lt;=</literal>
506                 </td>
507                 <td>3</td>
508             </tr>
509             <tr>
510                 <td>
511                     <literal>&gt;=</literal>
512                 </td>
513                 <td>4</td>
514             </tr>
515             <tr>
516                 <td>
517                     <literal>~</literal>
518                 </td>
519                 <td>5</td>
520             </tr>
521             <tr>
522                 <td>
523                     <literal>iext</literal>
524                 </td>
525                 <td>6</td>
526             </tr>
527         </informaltable>
528         <para>
529             The overloading function for extraction syntax <literal>b= a(i1,
530                 ..., in)
531             </literal>
532             has the following syntax: <literal>b =
533                 %&lt;type_of_a&gt;_e(i1, ..., in, a)
534             </literal>
535         </para>
536         <para>
537             and the syntax <literal>[x1, .., xm] = a(i1, ..., in)</literal> has
538             the following syntax: <literal>[x1, .., xm] =
539                 %&lt;type_of_a&gt;_e(i1, ..., in, a)
540             </literal>
541             .
542         </para>
543         <para>The overloading function associated to the insertion syntax
544             <literal>a(i1, ..., in) = b</literal> has the following syntax:
545             <literal>a = %&lt;type_of_b&gt;_i_&lt;type_of_a&gt;(i1, ..., in, b,
546                 a)
547             </literal>
548             .
549         </para>
550         <para>
551             The <literal>6</literal> char code may be used for some complex
552             insertion algorithm like <code>x.b(2) = 33</code> where
553             <literal>b</literal> field is not defined in the structure
554             <literal>x</literal>. The insertion is automatically decomposed into
555             <code>temp = x.b</code>; <code>temp(2) = 33</code>;
556             <code>x.b = temp</code>. The <literal>6</literal> char code is used
557             for the first step of this algorithm. The <literal>6</literal> overloading
558             function is very similar to the <literal>e</literal>'s one.
559         </para>
560         <variablelist>
561             <varlistentry>
562                 <term>Functions :</term>
563                 <listitem>
564                     <para>
565                         Some basic primitive function may also be overloaded for new data type. When such function
566                         is undefined for a particular data types the function
567                         <literal>%&lt;type_of_an_argument&gt;_&lt;function_name&gt;</literal>
568                         is called. User may add in this called function the definition
569                         associated with the input data types.
570                     </para>
571                 </listitem>
572             </varlistentry>
573         </variablelist>
574     </refsection>
575     <refsection>
576         <title>Examples</title>
577     </refsection>
578     <refsection>
579         <programlisting role="example">//DISPLAY
580             var = tlist('tab', ['a', 'b'], ['x'; 'y'], rand(2, 2)) // the type of var is 'tab'
581
582             typeof(var)
583
584             function [] = %tab_p(l)
585             disp([[' '; l(3)] [l(2); string(l(4))]])
586             endfunction
587
588             var // after overloading
589         </programlisting>
590     </refsection>
591     <refsection>
592         <programlisting role="example">//OPERATOR
593             's' + 1 // it is impossible to add a number to a string
594
595             function x = %c_a_s(a, b)
596             x = a + string(b);
597             endfunction
598
599             's' + 1 // after overloading
600         </programlisting>
601     </refsection>
602     <refsection>
603         <programlisting role="example">//FUNCTION
604             sin('2 * x') // the sin function does not work with a string
605
606             function x = %c_sin(a)
607             x = 'sin(' + a + ')'
608             endfunction
609
610             sin('2 * x') // after overloading
611         </programlisting>
612     </refsection>
613     <refsection role="see also">
614         <title>See also</title>
615         <simplelist type="inline">
616             <member>
617                 <link linkend="tlist">tlist</link>
618             </member>
619             <member>
620                 <link linkend="disp">disp</link>
621             </member>
622             <member>
623                 <link linkend="symbols">symbols</link>
624             </member>
625             <member>
626                 <link linkend="typeof">typeof</link>
627             </member>
628             <member>
629                 <link linkend="type">type</link>
630             </member>
631             <member>
632                 <link linkend="typename">typename</link>
633             </member>
634         </simplelist>
635     </refsection>
636     <refsection role="history">
637         <title>History</title>
638         <revhistory>
639             <revision>
640                 <revnumber>6.0</revnumber>
641                 <revdescription>
642                   <literal>function</literal> replaces <literal>mc</literal> as overloading code
643                   for functions in Scilab language.
644                 </revdescription>
645             </revision>
646         </revhistory>
647     </refsection>
648 </refentry>