← Back to branch summary

~ubuntu-branches/ubuntu/raring/scilab/raring-proposed

« back to all changes in this revision

Viewing changes to modules/functions/help/en_US/overloading.xml

  • Committer: Package Import Robot
  • Author(s): Sylvestre Ledru
  • Date: 2012-08-30 14:42:38 UTC
  • mfrom: (1.4.7)
  • Revision ID: package-import@ubuntu.com-20120830144238-c1y2og7dbm7m9nig
Tags: 5.4.0-beta-3-1~exp1
* New upstream release
* Update the scirenderer dep
* Get ride of libjhdf5-java dependency

Show diffs side-by-side

added added

removed removed

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