[doc] mv data_structures/types => core/types
[scilab.git] / scilab / modules / core / help / en_US / types / typeof.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) 2008 - INRIA
5  * Copyright (C) 2015 - 2017 - Samuel GOUGEON
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="typeof" xml:lang="en">
21     <refnamediv>
22         <refname>typeof</refname>
23         <refpurpose>explicit type or overloading code of an object</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             t  = typeof(object)
29             oc = typeof(object, "overload")
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection role="parameters">
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>object</term>
37                 <listitem>
38                     <para>a Scilab object</para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>t</term>
43                 <listitem>
44                     <para>
45                         a string (may have spaces): the name of the type of <varname>object</varname>
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>oc</term>
51                 <listitem>
52                     <para>a string (without spaces): the name of the overloading code for the
53                         <varname>object</varname>.
54                     </para>
55                 </listitem>
56             </varlistentry>
57         </variablelist>
58     </refsection>
59     <refsection role="description">
60         <title>Description</title>
61         <para>
62             <code>t = typeof(object)</code> returns one of the following strings:
63         </para>
64         <table>
65             <tr>
66                 <td>
67                     <emphasis role="bold">string</emphasis>
68                 </td>
69                 <td>
70                     <varname>object</varname> is a matrix or hypermatrix made of
71                     <link linkend="strings">characters</link> and texts.
72                 </td>
73             </tr>
74             <tr>
75                 <td>
76                     <emphasis role="bold">boolean</emphasis>
77                 </td>
78                 <td>
79                     <varname>object</varname> is a
80                     <link linkend="matrices">boolean matrix or hypermatrix</link>.
81                 </td>
82             </tr>
83             <tr>
84                 <td colspan="2">
85                     <emphasis role="bold">int8</emphasis> or
86                     <emphasis role="bold">int16</emphasis> or
87                     <emphasis role="bold">int32</emphasis> or
88                     <emphasis role="bold">int64</emphasis> or
89                     <emphasis role="bold">uint8</emphasis> or
90                     <emphasis role="bold">uint16</emphasis> or
91                     <emphasis role="bold">uint32</emphasis> or
92                     <emphasis role="bold">uint64</emphasis>
93                 </td>
94             </tr>
95             <tr>
96                 <td> </td>
97                 <td>
98                     <varname>object</varname> is a matrix or hypermatrix of [unsigned]
99                     integers stored
100                     on 8, 16, 32 or 64 bits. (see <link linkend="inttype">inttype</link>)
101                 </td>
102             </tr>
103             <tr>
104                 <td>
105                     <emphasis role="bold">constant</emphasis>
106                 </td>
107                 <td>
108                     <varname>object</varname> is matrix or hypermatrix of
109                     decimal or complex numbers.
110                 </td>
111             </tr>
112             <tr>
113                 <td>
114                     <emphasis role="bold">polynomial</emphasis>
115                 </td>
116                 <td>
117                     <varname>object</varname> is a matrix or hypermatrix of
118                     <link linkend="poly">polynomials</link>
119                     with decimal or complex coefficients.
120                 </td>
121             </tr>
122             <tr>
123                 <td>
124                     <emphasis role="bold">rational</emphasis>
125                 </td>
126                 <td>
127                     <varname>object</varname> is a matrix or hypermatrix of
128                     <link linkend="rational">rational</link>
129                     fractions (e.g. transfer matrix), with decimal or complex coefficients.
130                 </td>
131             </tr>
132             <tr>
133                 <td>
134                     <emphasis role="bold">handle</emphasis>
135                 </td>
136                 <td>
137                     <varname>object</varname> is a graphics
138                     <link linkend="graphics_entities">handle</link>.
139                     The subtype of graphics handles (Figure, Axes, Polyline,
140                     Compound, etc) is available in their <literal>.type</literal>
141                     property. See examples below.
142                 </td>
143             </tr>
144             <tr>
145                 <td>
146                     <emphasis role="bold">list</emphasis>
147                 </td>
148                 <td>
149                     <varname>object</varname> is a <link linkend="list">list</link>.
150                 </td>
151             </tr>
152             <tr>
153                 <td>
154                     <emphasis role="bold">st</emphasis>
155                 </td>
156                 <td>
157                     <varname>object</varname> is a
158                     <link linkend="struct">structure</link>
159                     or a nD-array of structures.
160                 </td>
161             </tr>
162             <tr>
163                 <td>
164                     <emphasis role="bold">ce</emphasis>
165                 </td>
166                 <td>
167                     <varname>object</varname> is a
168                     <link linkend="cell">cell</link> or a nD-array of cells.
169                 </td>
170             </tr>
171             <tr>
172                 <td>
173                     <emphasis role="bold">boolean sparse</emphasis>
174                 </td>
175                 <td>
176                     <varname>object</varname> is a
177                     <link linkend="sparse">boolean sparse matrix</link>.
178                     <warning>Sparse boolean hypermatrices are not supported.</warning>
179                 </td>
180             </tr>
181             <tr>
182                 <td>
183                     <emphasis role="bold">sparse</emphasis>
184                 </td>
185                 <td>
186                     <varname>object</varname> is a
187                     <link linkend="sparse">sparse matrix</link>
188                     of decimal or complex numbers.
189                     <warning>Sparse numerical hypermatrices are not supported.</warning>
190                 </td>
191             </tr>
192             <tr>
193                 <td style="white-space:nowrap">
194                     <emphasis role="bold">"Matlab sparse"</emphasis>
195                 </td>
196                 <td>
197                     <varname>object</varname> is a Matlab-like-encoded sparse
198                     matrix (see <link linkend="mtlb_sparse">mtlb_sparse()</link>).
199                 </td>
200             </tr>
201             <tr>
202                 <td>
203                     <emphasis role="bold">fptr</emphasis>
204                 </td>
205                 <td>
206                     <varname>object</varname> is a built-in Scilab function,
207                     called also <emphasis role="italic">gateway</emphasis>
208                     (C, C++ or Fortran code), a.k.a. a primitive.
209                 </td>
210             </tr>
211             <tr>
212                 <td>
213                     <emphasis role="bold">function</emphasis>
214                 </td>
215                 <td>
216                     <varname>object</varname> is a <link linkend="function">function</link>
217                     (Scilab code). See also <link linkend="deff">deff</link>.
218                 </td>
219             </tr>
220             <tr>
221                 <td>
222                     <emphasis role="bold">library</emphasis>
223                 </td>
224                 <td>
225                     <varname>object</varname> is a
226                     <link linkend="library">library</link>
227                     of functions in Scilab language.
228                 </td>
229             </tr>
230             <tr>
231                 <td>
232                     <emphasis role="bold">pointer</emphasis>
233                 </td>
234                 <td>
235                     <varname>object</varname> is a pointer. See a use case:
236                     <link linkend="lufact">lufact</link>.
237                 </td>
238             </tr>
239             <tr>
240                 <td>
241                     <emphasis role="bold">implicitlist</emphasis>
242                 </td>
243                 <td>
244                     <varname>object</varname> is an implicit list using a
245                     polynomial as formal index, for indexing.
246                     See  <link linkend="dollar">n:$</link>
247                     <link linkend="colon">: (colon)</link>
248                 </td>
249             </tr>
250             <tr>
251                 <td>
252                     <emphasis role="bold">listdelete</emphasis>
253                 </td>
254                 <td>
255                     is returned by
256                     <function>
257                         typeof(<literal>null()</literal>)
258                     </function>
259                     .
260                     See  <link linkend="null">null()</link>.
261                 </td>
262             </tr>
263             <tr>
264                 <td>
265                     <emphasis role="bold">void</emphasis>
266                 </td>
267                 <td>is the typeof undefined elements in lists.</td>
268             </tr>
269             <tr>
270                 <td colspan="2"></td>
271             </tr>
272             <tr>
273                 <td colspan="2">
274                     <emphasis role="bold italic">Typed T-Lists or M-Lists:</emphasis>
275                 </td>
276             </tr>
277             <tr>
278                 <td colspan="2">
279                     Note that if the <varname>object</varname> is a
280                     <link linkend="tlist">tlist</link>
281                     or a <link linkend="mlist">mlist</link>, <function>typeof</function>
282                     will return the corresponding customized type stored in as a
283                     string in the first list entry.
284                 </td>
285             </tr>
286             <tr>
287                 <td colspan="2"></td>
288             </tr>
289             <tr>
290                 <td colspan="2">
291                     <emphasis role="bold italic">Reserved T-List or M-List types
292                         predefined in Scilab:
293                     </emphasis>
294                 </td>
295             </tr>
296             <tr>
297                 <td>
298                     <emphasis role="bold">dir</emphasis>
299                 </td>
300                 <td>
301                     <varname>object</varname> is the result of a
302                     <link linkend="dir">dir()</link>
303                     instruction, with fields <literal>name</literal>, <literal>date</literal>,
304                     <literal>bytes</literal>, and <literal>isdir</literal>.
305                 </td>
306             </tr>
307             <tr>
308                 <td>
309                     <emphasis role="bold">state-space</emphasis>
310                 </td>
311                 <td>
312                     <varname>object</varname> is a state-space model
313                     (see <link linkend="syslin">syslin</link>).
314                 </td>
315             </tr>
316             <tr>
317                 <td>
318                     <emphasis role="bold">program</emphasis>
319                 </td>
320                 <td>
321                     <varname>object</varname> is a list describing the internal code of a function
322                     (see <link linkend="macr2tree">macr2tree</link>).
323                 </td>
324             </tr>
325             <tr>
326                 <td>
327                     <emphasis role="bold">cblock</emphasis>
328                 </td>
329                 <td>
330                     <varname>object</varname> is a block of columns of same
331                     heights but of different data types, as returned by
332                     <link linkend="mfscanf">mfscanf</link>.
333                 </td>
334             </tr>
335             <tr>
336                 <td>
337                     <emphasis role="bold">XMLDoc</emphasis>
338                 </td>
339                 <td>
340                     <varname>object</varname> is an XML Document created with
341                     <link linkend="xmlRead">xmlRead</link>,
342                     <link linkend="xmlReadStr">xmlReadStr</link>,
343                     <link linkend="htmlRead">htmlRead</link>, or
344                     <link linkend="htmlReadStr">htmlReadStr</link>.
345                     Additional XML typeof are defined.
346                 </td>
347             </tr>
348             <tr>
349                 <td>
350                     <emphasis role="bold">H5Object</emphasis>
351                 </td>
352                 <td>
353                     <varname>object</varname> is the id of an HDF5 file opened
354                     with <link linkend="h5open">h5open</link>.
355                     Additional HDF5 typeof are defined:
356                     See <link linkend="h5objects">HDF5 Objects</link>.
357                 </td>
358             </tr>
359             <tr>
360                 <td>
361                     <emphasis role="bold">uitree</emphasis>
362                 </td>
363                 <td>
364                     <varname>object</varname> is a tree, a branch or a leaf as created with  a
365                     uitree feature. See for instance <link linkend="uiCreateNode">uiCreateNode</link>.
366                 </td>
367             </tr>
368             <tr>
369                 <td colspan="2">
370                   <emphasis role="bold italic">Reserved T-list types used in Xcos</emphasis> :
371                 </td>
372             </tr>
373             <tr>
374                 <td>
375                   <link linkend="scicos_block"><emphasis role="bold">Block</emphasis></link>
376                 </td>
377                 <td><varname>object</varname> is a Xcos block.
378               </td>
379             </tr>
380             <tr>
381               <td>
382                 <link linkend="scicos_cpr"><emphasis role="bold">cpr</emphasis></link>
383               </td>
384               <td>
385                 <varname>object</varname> is a tlist containing the compilation results of a Xcos diagram.
386               </td>
387             </tr>
388             <tr>
389               <td>
390                 <link linkend="scicos_diagram"><emphasis role="bold">diagram</emphasis></link>
391               </td>
392               <td>
393                 <varname>object</varname> is a tlist defining a Xcos diagram: initial parameters,
394                 set of blocks, of links between blocks, and of Text labels belonging to the diagram.
395               </td>
396             </tr>
397             <tr>
398               <td>
399                 <link linkend="scicos_graphics"><emphasis role="bold">graphics</emphasis></link>
400               </td>
401               <td>
402                 <varname>object</varname> is a tlist assigned to the <literal>.graphics</literal>
403                 field of a block.
404               </td>
405             </tr>
406             <tr>
407               <td>
408                 <link linkend="scicos_link"><emphasis role="bold">Link</emphasis></link>
409               </td>
410               <td>
411                 <varname>object</varname> is a tlist defining and configuring a link between 2 blocks.
412               </td>
413             </tr>
414             <tr>
415               <td>
416                 <link linkend="scicos_model"><emphasis role="bold">model</emphasis></link>
417               </td>
418               <td>
419                 <varname>object</varname> is a tlist assigned to the <literal>.model</literal> field
420                 of a block.
421               </td>
422             </tr>
423             <tr>
424               <td>
425                 <link linkend="scicos_params"><emphasis role="bold">params</emphasis></link>
426               </td>
427               <td>
428                 <varname>object</varname> is a tlist containing some configuration parameters of a
429                 Xcos diagram.
430               </td>
431             </tr>
432             <tr>
433               <td>
434                 <emphasis role="bold">scsopt</emphasis>
435               </td>
436               <td>
437                 <varname>object</varname> is a tlist containing the graphical options of the Xcos
438                 diagram editor.
439               </td>
440             </tr>
441             <tr>
442               <td>
443                 <link linkend="scicos_sim"><emphasis role="bold">scs</emphasis></link>
444               </td>
445               <td>
446                 <varname>object</varname> is a tlist containing static results of the compilation of
447                 a Xcos diagram.
448               </td>
449             </tr>
450             <tr>
451               <td>
452                 <link linkend="scicos_state"><emphasis role="bold">xcs</emphasis></link>
453               </td>
454               <td>
455                 <varname>object</varname> is a tlist containing dynamical results during a Xcos
456                 simulation.
457               </td>
458             </tr>
459             <tr>
460               <td>
461                 <emphasis role="bold">Text</emphasis>
462               </td>
463               <td>
464                 <varname>object</varname> is a tlist defining a text label in a Xcos diagram.
465               </td>
466             </tr>
467         </table>
468     </refsection>
469     <refsection role="examples">
470         <title>Examples</title>
471         <programlisting role="no-scilab-exec"><![CDATA[
472 // Characters and texts
473 t = ["a" "Hello"   "à é è ï ô û ñ"
474      "1" "Bonjour" "указывает тип объекта"
475      ";" "Chao"    "オブジェクトの型"
476     ]
477 typeof(t)
478
479 // Booleans
480 typeof(%t)
481 typeof("abc"=="def")
482 hm = grand(2,2,2,"uin",0,9)<5
483 typeof(hm)
484
485 // Encoded integers
486 [ typeof(uint8(%pi))  typeof(int8(-%pi))
487   typeof(uint16(%pi)) typeof(int16(-%pi))
488   typeof(uint32(%pi)) typeof(int32(-%pi))
489   typeof(uint64(%pi)) typeof(int64(-%pi))
490 ]
491
492 // Decimal numbers
493 n = 1:0.3:2
494 typeof(n)
495 hm = grand(2,2,2,"uin",0,9)
496 typeof(hm)
497
498 // Decimal integers
499 n = 1:7
500 typeof(n)
501
502 // Complex numbers
503 n = [%i 1-%i %pi - 3*%i]
504 typeof(n)
505
506 // Special "constant"
507 typeof([])   // empty matrix
508
509 // Polynomials
510 n = [ %z (1-%z)^2]
511 typeof(n)
512 n = [ 3*%i + %z (1-%i*%z)^2]
513 typeof(n)
514
515 // Rational fractions
516 r = [%s/(1-%s) (1+%s)^2/(1-%s)]   // with real coefficients
517 typeof(r)
518 r = [%s/(%i-%s) (%i+%s)^2/(1-%s)] // with complex coefficients
519 typeof(r)
520
521 // Sparse matrices
522 // ---------------
523 w = sprand(100,100,0.001)
524 typeof(w)     // sparse
525 typeof(w==w)  // boolean sparse
526 //x = mtlb_sparse(sprand(10,10,0.1));
527 //typeof(x)
528
529 // Functions and libraries
530 // -----------------------
531 deff('y=f(x)','y=2*x');  // Function in Scilab language
532 f(%pi)
533 typeof(f)
534 typeof(cosd)  // written in Scilab
535
536 typeof(corelib) // Library of functions in Scilab language
537
538 typeof(sin)     // Built-in function (non-editable)
539 mysin = sin;
540 mysin(%pi/2)
541
542 // Graphical handles
543 // -----------------
544 clf
545 plot2d()
546 typeof(gcf())
547 // The subtype of the handle is in the "type" property:
548 gcf().type
549 gca().type
550 gce().type
551
552 close(gcf())
553
554 // Containers
555 // ----------
556 // Simple list
557 L = list(%pi, %t, %z, %s/(1-%s), "Bonjour", sin, cosd, list("list_in_list", 432));
558 typeof(L)
559
560 // Cells array
561 C = {%pi, %t, %z ; %s/(1-%s), "Bonjour", list("list_in_list", 432) }
562 typeof(C)
563
564 // (Array of) Structure
565 S.num = %pi;
566 S.b = %t;
567 S(2).t = "Bonjour"
568 typeof(S)
569
570 // Special generic indexing expressions
571 // ------------------------------------
572 typeof($)
573 typeof(:)    // "eye()" equivalent (all elements)
574 typeof(3:$)
575
576 // Typeof for deletion or undefined elements:
577 // -----------------------------------------
578 typeof([])      // empty matrix
579 typeof(null())
580 L = list(%pi, ,"hey!")
581 typeof(L(2))   // undefined element
582
583 // Customized typeof of T-Lists:
584 // ----------------------------
585 L = tlist(['myLongTypeOf','a','b'], 18, 'Scilab');
586 typeof(L)
587
588 // Reserved T-List typeof
589 // ----------------------
590 typeof(dir())        // Files directory
591 //
592 c = macr2tree(sind); // Internal code of a Scilab macro
593 typeof(c)
594 fieldnames(c)'
595 c.name
596 //
597 doc = xmlReadStr("<root><a att=""foo"">Hello</a></root>");
598 typeof(doc)
599 xmlDelete(doc)
600 //
601 x = 1;
602 save(TMPDIR + "/x.sod", "x"); // SOD files are HDF5 ones
603 a = h5open(TMPDIR + "/x.sod");
604 typeof(a)
605 h5close(a)
606  ]]></programlisting>
607     </refsection>
608     <refsection role="see also">
609         <title>See also</title>
610         <simplelist type="inline">
611             <member>
612                 <link linkend="type">type</link>
613             </member>
614             <member>
615                 <link linkend="inttype">inttype</link>
616             </member>
617             <member>
618                 <link linkend="overloading">overloading</link>
619             </member>
620             <member>
621                 <link linkend="isreal">isreal</link>
622             </member>
623             <member>
624                 <link linkend="strings">strings</link>
625             </member>
626             <member>
627                 <link linkend="poly">poly</link>
628             </member>
629             <member>
630                 <link linkend="rlist">rlist</link>
631             </member>
632             <member>
633                 <link linkend="null">null</link>
634             </member>
635             <member>
636                 <link linkend="sparse">sparse</link>
637             </member>
638             <member>
639                 <link linkend="issparse">issparse</link>
640             </member>
641             <member>
642                 <link linkend="mtlb_sparse">mtlb_sparse</link>
643             </member>
644             <member>
645                 <link linkend="syslin">syslin</link>
646             </member>
647             <member>
648                 <link linkend="dir">dir</link>
649             </member>
650             <member>
651                 <link linkend="XMLObjects">XML Objects</link>
652             </member>
653             <member>
654                 <link linkend="h5objects">HDF5 Objects</link>
655             </member>
656         </simplelist>
657     </refsection>
658     <refsection role="history">
659         <title>History</title>
660         <revhistory>
661             <revision>
662                 <revnumber>6.0</revnumber>
663                 <revdescription>
664                     <itemizedlist>
665                         <listitem>"overload" keyword added. </listitem>
666                         <listitem>typeof "uint64" and "int64" added. </listitem>
667                         <listitem>
668                             typeof "hypermat" removed. Hypermatrices of any homogeneous type are now
669                             natively supported.
670                         </listitem>
671                         <listitem>typeof "listdelete" added (as returned by null()).</listitem>
672                         <listitem>typeof() can now be used for any undefined element of a list.
673                           It then returns the new "void" typeof.
674                         </listitem>
675                         <listitem>
676                             The typeof of T-lists and M-lists were limited to 8 characters. They may
677                             be longer now.
678                         </listitem>
679                         <listitem>
680                             typeof "size implicit" renamed "implicitlist" (<literal>1:$</literal>)
681                         </listitem>
682                         <listitem>Help page reviewed.</listitem>
683                     </itemizedlist>
684                 </revdescription>
685             </revision>
686         </revhistory>
687     </refsection>
688 </refentry>