%i_isreal() %i_real() %i_imag() added
[scilab.git] / scilab / modules / core / help / en_US / types / type.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) 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:mml="http://www.w3.org/1998/Math/MathML"
19     xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
20     xml:lang="en" xml:id="type">
21     <refnamediv>
22         <refname>type</refname>
23         <refpurpose>returns the type of a Scilab object</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>i = type(x)</synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>x</term>
34                 <listitem>
35                     <para>a Scilab object: a variable or valid expression.</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>i</term>
40                 <listitem>
41                     <para>
42                         integer code identiying the type of <varname>x</varname>.
43                     </para>
44                 </listitem>
45             </varlistentry>
46         </variablelist>
47     </refsection>
48     <refsection>
49         <title>Description</title>
50         <para>
51             <code>type(x)</code>  returns an integer which is the type of <varname>x</varname>,
52             defined as following:
53         </para>
54         <variablelist>
55             <varlistentry>
56                 <term>1</term>
57                 <listitem>decimal or complex numbers
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>2</term>
62                 <listitem>
63                     <link linkend="poly">polynomials</link> with real or complex coefficients
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>4</term>
68                 <listitem>
69                     booleans
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>5</term>
74                 <listitem>
75                     a <link linkend="sparse">sparse matrix</link>.
76                 </listitem>
77             </varlistentry>
78             <varlistentry>
79                 <term>6</term>
80                 <listitem>
81                     a <link linkend="sparse">sparse boolean matrix</link>.
82                 </listitem>
83             </varlistentry>
84             <varlistentry>
85                 <term>7</term>
86                 <listitem>
87                     Matlab sparse matrix
88                 </listitem>
89             </varlistentry>
90             <varlistentry>
91                 <term>8</term>
92                 <listitem>
93                     <link linkend="int8">integers</link> stored on 1 (<literal>int8</literal>), 2 (<literal>int16</literal>), 4 (<literal>int32</literal>), or 8 (<literal>int64</literal>) bytes.
94                 </listitem>
95             </varlistentry>
96             <varlistentry>
97                 <term>9</term>
98                 <listitem>
99                     <link linkend="graphics_entities">graphic handles</link>.
100                 </listitem>
101             </varlistentry>
102             <varlistentry>
103                 <term>10</term>
104                 <listitem>
105                     <link linkend="strings">text objects</link>.
106                 </listitem>
107             </varlistentry>
108             <varlistentry>
109                 <term>13</term>
110                 <listitem>
111                     a compiled <link linkend="function">function</link> in Scilab code.
112                 </listitem>
113             </varlistentry>
114             <varlistentry>
115                 <term>14</term>
116                 <listitem>
117                     <link linkend="library">library</link> of compiled Scilab functions.
118                 </listitem>
119             </varlistentry>
120             <varlistentry>
121                 <term>15</term>
122                 <listitem>
123                     a simple <link linkend="list">list</link>.
124                 </listitem>
125             </varlistentry>
126             <varlistentry>
127                 <term>16</term>
128                 <listitem>
129                     a typed list (<link linkend="tlist">tlist</link>).
130                 </listitem>
131             </varlistentry>
132             <varlistentry>
133                 <term>17</term>
134                 <listitem>
135                     a matrix-oriented typed list (<link linkend="mlist">mlist</link>).
136                 </listitem>
137             </varlistentry>
138             <varlistentry>
139                 <term>128</term>
140                 <listitem>
141                     an identifier of a Xcos block, of a <link linkend="lufact">lufact</link>()'s result,
142                     etc.
143                 </listitem>
144             </varlistentry>
145             <varlistentry>
146                 <term>129</term>
147                 <listitem>
148                     a size implicit polynomial used for indexing.
149                 </listitem>
150             </varlistentry>
151             <varlistentry>
152                 <term>130</term>
153                 <listitem>
154                     a built-in Scilab function, aka <emphasis role="italic">gateway</emphasis> (C, C++ or Fortran code).
155                 </listitem>
156             </varlistentry>
157             <varlistentry>
158                 <term>0</term>
159                 <listitem>
160                     An undefined element of a list (with a typeof <literal>void</literal>, such as
161                     in the function call <literal>foo(a,,b)</literal>, or in
162                     <literal>list(%pi,,%i,,,%z)</literal>), or a null object of typeof
163                     <literal>listdelete</literal> returned by <literal>null()</literal>.
164                 </listitem>
165             </varlistentry>
166         </variablelist>
167         <refsect2>
168             <title>Remarks</title>
169             <para>
170                 Some data may be stored in custom containers defined as typed lists of type 16
171                 (tlist) or 17 (matrix-oriented typed mlist). This is also the case for embedded
172                 types like (<emphasis role="italic">rationals</emphasis>), structures
173                 (<emphasis role="italic">struct</emphasis>),
174                 <emphasis role="italic">state-space</emphasis>, interactive trees
175                 (<emphasis role="italic">uitree</emphasis>), etc, for which
176                 <literal>type(..)</literal> will return 16 or 17. One will use
177                 <link linkend="typeof">typeof</link> to get more information about their actual
178                 (sub)type.
179             </para>
180             <para>
181                 <emphasis role="bold">Type conversion in mixed operations</emphasis>:
182             </para>
183             <para>
184                 When a binary operator (like the multiplication) or an n-ary iterated one
185                 (like the concatenation) is applied between two operands of distinct but
186                 compatible types, usually the type of one of both is implicitly converted,
187                 and the other operand sets the type of the result to its own type.
188                 <para>
189                     Examples with the <link linkend="brackets">concatenation</link> :
190                     <literal>[%t, 3.124]</literal>, <literal>[int8(5), 3.124]</literal>, etc.
191                 </para>
192                 <para>
193                 For the concatenation, addition, substraction, multiplication, division,
194                 and the power operation, the hierarchy between operands types is as follows
195                 (read "A &lt; B": B imposes its type to A) :
196                 <simplelist>
197                     <member>
198                         boolean &lt; (decimal number, complex encoded number)
199                     </member>
200                     <member>
201                         <warning>
202                             (decimal number, complex-encoded number) &lt; encoded integer.
203                         </warning>
204                     </member>
205                     <member>
206                         polynomial (real | complex) &lt; rational (real | complex)
207                     </member>
208                 </simplelist>
209                 </para>
210             </para>
211         </refsect2>
212     </refsection>
213     <refsection>
214         <title>Examples</title>
215         <programlisting role="example"><![CDATA[
216 // (Select some lines, right-click and choose "Execute.." to run the selection)
217 L = list(%pi,,"abc");
218 type(L(2))                  // undefined component of a list
219
220 type(42)                    // decimal numbers
221 type(%nan)
222 type(%inf)
223
224 type(1+%i)                  // complex numbers
225
226 s = sparse([1,2;4,5;3,10],[1,2,3]);
227 type(s)                     // sparse-encoded decimal or complex numbers
228
229 type(%t)                    // booleans
230
231 type(s>2)                   // sparse-encoded booleans
232
233 g = int8([1 -120 127 312]); // encoded integers
234 type(g)
235 type(1.23 * int8(4))
236
237 type(1-%z+%z^2)             // polynomials
238
239 type(gdf())                 // graphic handles
240
241 type("foo")                 // texts
242
243 deff('[x] = mymacro(y,z)',['a=3*y+1'; 'x=a*z+y']);
244 type(mymacro)               // Scilab functions
245
246 type(disp)                  // Built-in functions
247
248 l = list(1,["a" "b"]);      // simple lists
249 type(l)
250
251 e = tlist(["listtype","field1","field2"], [], []);
252 type(e)                     // Typed list
253
254 h = mlist(['V','name','value'],['a','b';'c' 'd'],[1 2; 3 4]);
255 type(h)                     // Typed matrix-oriented list
256
257 clear s, s.r = %pi          // structures
258 type(s)
259
260 c = {%t %pi %i %z "abc" s}  // cells
261 type(c)
262
263 r = [%z/(1-%z) (1-%z)/%z^2]
264 type(r)                     // rational fractions
265 ]]></programlisting>
266     </refsection>
267     <refsection role="see also">
268         <title>See also</title>
269         <simplelist type="inline">
270             <member>
271                 <link linkend="typeof">typeof</link>
272             </member>
273             <member>
274                 <link linkend="inttype">inttype</link>
275             </member>
276             <member>
277                 <link linkend="isreal">isreal</link>
278             </member>
279             <member>
280                 <link linkend="brackets">brackets</link>
281             </member>
282             <member>
283                 <link linkend="overloading">overloading</link>
284             </member>
285             <member>
286                 <link linkend="poly">poly</link>
287             </member>
288             <member>
289                 <link linkend="rational">rational</link>
290             </member>
291             <member>
292                 <link linkend="tlist">tlist</link>
293             </member>
294             <member>
295                 <link linkend="mlist">mlist</link>
296             </member>
297             <member>
298                 <link linkend="null">null</link>
299             </member>
300         </simplelist>
301     </refsection>
302     <refsection role="history">
303         <title>History</title>
304         <revhistory>
305             <revision>
306                 <revnumber>6.0</revnumber>
307                 <revdescription>
308                   The type 11 is removed. It was used for uncompiled Scilab functions.
309                 </revdescription>
310             </revision>
311         </revhistory>
312     </refsection>
313 </refentry>