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