* Bug 15431 fixed [doc]: empty [] better documented
[scilab.git] / scilab / modules / elementary_functions / help / en_US / elementarymatrices / empty.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) 2012 - 2016 - Scilab Enterprises
5  * Copyright (C) 2019 - Samuel GOUGEON
6  *
7  * This file is hereby licensed under the terms of the GNU GPL v2.0,
8  * pursuant to article 5.3.4 of the CeCILL v.2.1.
9  * This file was originally licensed under the terms of the CeCILL v2.1,
10  * and continues to be available under such terms.
11  * For more information, see the COPYING file which you should have received
12  * along with this program.
13  *
14  -->
15 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
17           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
18           xml:lang="en" xml:id="empty">
19     <refnamediv>
20         <refname>empty []</refname>
21         <refpurpose>empty matrix. Array ranges destructor.</refpurpose>
22     </refnamediv>
23     <refsection>
24         <title>Contents</title>
25         <simplelist type="inline">
26             <member>
27                 <link linkend="empty_general_properties">General [ ] properties</link>
28             </member>
29             <member>
30                 <link linkend="empty_operand_or_argument">[ ] as operand or input argument</link>
31             </member>
32             <member>
33                 <link linkend="empty_assigned_as_destructor">[ ] assigned as ranges destructor</link>
34             </member>
35             <member>
36                 <link linkend="empty_examples">Examples</link>
37             </member>
38             <member>
39                 <link linkend="empty_seealso">See also</link>
40             </member>
41             <member>
42                 <link linkend="empty_history">History</link>
43             </member>
44         </simplelist>
45     </refsection>
46     <refsection>
47         <title>Description</title>
48         <refsect3 id="empty_general_properties">
49             <title>General [ ] properties</title>
50             <para>
51             Empty brackets <literal>[]</literal> represent the empty matrix. Its general properties
52             are now described.
53             </para>
54             <orderedlist>
55                 <listitem>
56                     <para>
57                     It has only two dimensions. Any dimension > #2 is automatically squeezed:
58                     <screen><![CDATA[
59 --> e = ones(1,2,0,2); size(e)
60  ans  =
61    0.   0.
62
63 --> e == []
64  ans  =
65   T
66 ]]></screen>
67                     </para>
68                 </listitem>
69                 <listitem>
70                     <para>
71                     It is always of real decimal type. There is no empty matrix of integer types
72                     (int8, uint8, int16, uint16, int32, uint32, int64, uint64), nor of string type,
73                     etc:
74                     <screen><![CDATA[
75 --> type(uint8([]))  // not of type 8 (encoded integers)
76  ans  =
77    1.
78
79 --> a = [1 2 ; 3 4] + %i;
80 --> a(1,:) = []
81  a  =
82    3. + i     4. + i
83
84 --> a(1,:) = [], isreal(a)
85  a  =
86     []
87  ans  =
88   T
89
90 --> t = "abcd efg", type(t)
91  t  =
92  abcd efg
93
94  ans  =
95    10.
96
97 --> t(1) = [], type(t)
98  t  =
99     []
100
101  ans  =
102    1.
103 ]]></screen>
104                     </para>
105                 </listitem>
106                 <listitem>
107                     <para>
108                     However, it is distinct from the sparse empty matrix:
109                     <screen><![CDATA[
110 --> se = sparse([])
111  se  =
112 (  0,  0) zero sparse matrix
113
114 --> size(se)
115  ans  =
116    0.   0.
117
118 --> se == []
119  ans  =
120   F
121 ]]></screen>
122                     </para>
123                 </listitem>
124                 <listitem>
125                     <para>
126                     It is also distinct from all empty heterogeneous containers
127                     <literal>list()</literal>, <literal>struct()</literal> or
128                     <literal>cell()</literal> :
129                     <screen><![CDATA[
130 --> L = list()
131  L  =
132      ()
133 --> L == []
134  ans  =
135   F
136
137 --> s = struct()
138  s  =
139 0x0 struct array with no fields.
140 --> s == []
141  ans  =
142   F
143
144 --> c = cell()
145  c  =
146    {}
147 --> c == []
148  ans  =
149   F
150 ]]></screen>
151                     </para>
152                 </listitem>
153             </orderedlist>
154         </refsect3>
155         <refsect3 id="empty_operand_or_argument">
156             <title>[ ] as operand or input argument</title>
157             <orderedlist>
158                 <listitem>
159                     <para>
160                     As operand of usual predefined non-boolean operators, [] sets the result to [].
161                     <emphasis>All the following operations yield</emphasis> []:
162                     <table>
163                         <tr><td colspan="2"><emphasis role="bold">Unary operators</emphasis></td></tr>
164                         <tr><td colspan="2">[]', [].', -[],  ~[]</td></tr>
165                         <tr><td></td><td></td></tr>
166                         <tr><td colspan="2"><emphasis role="bold">Binary numerical operators</emphasis></td></tr>
167                         <tr><td>addition:</td>      <td> [] + [1 2], [1 2] + []</td></tr>
168                         <tr><td>subtraction:</td>   <td> [] - [1 2], [1 2] - []</td></tr>
169                         <tr><td>division:</td>      <td> []/[1 2], []./[1 2], [1 2]/[], [1 2]./[]</td></tr>
170                         <tr><td>left division:</td> <td> []\[1 2], [].\[1 2], [1 2]\[], [1 2].\[]</td></tr>
171                         <tr><td>multiplication:</td><td> []*[1 2], [].*[1 2], [1 2]*[], [1 2].*[]</td></tr>
172                         <tr><td>kronecker:</td>     <td> [].*.[1 2], [1 2].*.[]</td></tr>
173                         <tr><td>power:</td>         <td> []^[1 2], [].^[1 2], [1 2]^[], [1 2].^[]</td></tr>
174                         <tr><td></td><td></td></tr>
175                         <tr><td colspan="2"><emphasis role="bold">Inequality comparisons</emphasis></td></tr>
176                         <tr><td>greater:</td><td> []>[1 2], []>=[1 2], [1 2]>[], [1 2]>=[]</td></tr>
177                         <tr><td>less:</td><td> []&lt;[1 2], []&lt;=[1 2], [1 2]&lt;[], [1 2]&lt;=[]</td></tr>
178                     </table>
179                     </para>
180                 </listitem>
181                 <listitem>
182                     <para>
183                     As operand of boolean binary operators, [] <emphasis>is equivalent to %T</emphasis>:
184                     <table>
185                         <tr><td colspan="4"><emphasis role="bold">Binary numerical operators</emphasis></td></tr>
186                         <tr><td>or:</td> <td> [] | [%T %F], [%T %F] | []        </td><td>→</td><td>[%T %T]</td></tr>
187                         <tr><td>and:</td><td> [] &amp; [%T %F], [%T %F] &amp; []</td><td>→</td><td>[%T %F]</td></tr>
188                     </table>
189                     </para>
190                     But, noticeably:
191                     <itemizedlist>
192                         <listitem>
193                             <para>
194                                 <literal>or([])</literal> is %F.
195                             </para>
196                         </listitem>
197                         <listitem>
198                             <para>
199                                 As the condition of any <literal>if</literal> or <literal>while</literal>
200                                 statement, [] is %F:
201                                 <screen><![CDATA[
202 --> if []
203 -->     r = "[] is %T as any if condition";
204 --> else
205 -->     r = "[] is %F as any if condition";
206 --> end
207 --> r
208  r  =
209  [] is %F as any if condition
210 ]]></screen>
211                             </para>
212                         </listitem>
213                     </itemizedlist>
214                 </listitem>
215                 <listitem>
216                     <para>
217                     In concatenations, [] is simply ignored:
218                     <literal>[A,[]] == [[],A] == [A ; []] == [[] ; A] == A</literal>
219                     </para>
220                 </listitem>
221                 <listitem>
222                     <para>
223                     In text concatenations, +[] yields []:
224                     <literal>[]+["a" "bc"] == ["a" "bc"]+[] == []</literal>
225                     </para>
226                 </listitem>
227                 <listitem>
228                     <para>
229                         As special input matrix of linear algebra or common functions, the answer
230                         depends on the considered function. It is documented in the page dedicated
231                         to each function. Examples:
232                     </para>
233                     <para>
234                     <table>
235                     <tr>
236                     <td>
237                     <table>
238                         <tr><td><literal>det([])</literal></td>     <td><literal>1</literal></td></tr>
239                         <tr><td><literal>rank([])</literal></td>    <td><literal>0</literal></td></tr>
240                         <tr><td><literal>trace([])</literal></td>   <td><literal>0</literal></td></tr>
241                         <tr><td><literal>norm([])</literal></td>    <td><literal>0</literal></td></tr>
242                         <tr><td><literal>cond([])</literal></td>    <td><literal>0</literal></td></tr>
243                         <tr><td><literal>rcond([])</literal></td>   <td><literal>Inf</literal></td></tr>
244                     </table>
245                     </td>
246                     <td></td>
247                     <td>
248                     <table>
249                         <tr><td><literal>diag([])</literal></td>    <td><literal>[]</literal></td></tr>
250                         <tr><td><literal>tril([])</literal></td>    <td><literal>[]</literal></td></tr>
251                         <tr><td><literal>triu([])</literal></td>    <td><literal>[]</literal></td></tr>
252                         <tr><td><literal>min([])</literal></td>     <td><literal>[]</literal></td></tr>
253                         <tr><td><literal>max([])</literal></td>     <td><literal>[]</literal></td></tr>
254                         <tr><td><literal>sign([])</literal></td>    <td><literal>[]</literal></td></tr>
255                         <tr><td><literal>clean([])</literal></td>   <td><literal>[]</literal></td></tr>
256                         <tr><td><literal>svd([])</literal></td>     <td><literal>[]</literal></td></tr>
257                     </table>
258                     </td>
259                     <td></td>
260                     <td>
261                     <table>
262                         <tr><td><literal>sum([])</literal></td>     <td><literal>0</literal></td></tr>
263                         <tr><td><literal>prod([])</literal></td>    <td><literal>1</literal></td></tr>
264                         <tr><td><literal>mean([])</literal></td>    <td><literal>Nan</literal></td></tr>
265                         <tr><td><literal>median([])</literal></td>  <td><literal>Nan</literal></td></tr>
266                         <tr><td><literal>stdev([])</literal></td>   <td><literal>Nan</literal></td></tr>
267                         <tr><td><literal>mad([])</literal></td>     <td><literal>Nan</literal></td></tr>
268                         <tr><td><literal>variance([])</literal></td><td><literal>Nan</literal></td></tr>
269                     </table>
270                     </td>
271                     </tr>
272                     </table>
273                     </para>
274                 </listitem>
275                 <listitem>
276                     <para>
277                         As general input argument of functions, [] is often used to choose the default
278                         value of an input argument (to somewhat skip it, to avoid providing an actual
279                         explicit value). However, this is not a strict rule.
280                     </para>
281                 </listitem>
282                 <!--
283                 <listitem>
284                     <para>
285                         Empty linear systems (<literal> syslin</literal> lists) may have several
286                         rows or columns.
287                         w=ssrand(2,2,2);
288                         wr=[]*w;
289                         size(wr), w1=ss2tf(wr), size(w1)
290                     </para>
291                 </listitem>
292                 -->
293             </orderedlist>
294         </refsect3>
295         <refsect3 id="empty_assigned_as_destructor">
296             <title>Assigning [ ] to delete ranges in arrays</title>
297         </refsect3>
298         <para>
299             Considering an array of any number of dimensions and of any size, that can be a matrix
300             or hypermatrix of any datatype, an array of structures, or an array of cells, []
301             can be assigned to delete the addressed ranges (rows, columns, etc). These ones must
302             cover the full size of the array at least along one of its dimensions.
303         </para>
304         <para>Examples:</para>
305         <para>With a matrix of decimal numbers:</para>
306         <programlisting role="example"><![CDATA[
307 a = grand(3,5,"uin",0,9)
308      ]]></programlisting>
309         <screen><![CDATA[
310 --> a = grand(3,5,"uin",0,9)
311  a  =
312    2.   4.   8.   0.   9.
313    2.   1.   3.   6.   4.
314    4.   9.   5.   9.   7.
315
316 --> a(:,[3 5]) = []
317  a  =
318    2.   4.   0.
319    2.   1.   6.
320    4.   9.   9.
321
322 --> a(2,:) = []
323  a  =
324    2.   4.   0.
325    4.   9.   9.
326 ]]></screen>
327         <para>
328             With an hypermatrix of texts:
329         </para>
330         <programlisting role="example"><![CDATA[
331 cs = cumsum(grand(2,4,3,"uin",1,3));
332 t = matrix(strsplit(ascii(grand(1,cs($),"uin",ascii("a"),ascii("c"))),cs(1:$-1)),2,4,3)
333      ]]></programlisting>
334         <screen><![CDATA[
335 --> cs = cumsum(grand(2,4,3,"uin",1,3));
336 --> t = matrix(strsplit(ascii(grand(1,cs($),"uin",ascii("a"),ascii("c"))),cs(1:$-1)),2,4,3)
337  t  =
338 (:,:,1)
339 !ccc  b    b   b  !
340 !bbb  bcc  bc  c  !
341
342 (:,:,2)
343 !aa  aab  bc  a   !
344 !ab  a    cc  ba  !
345
346 (:,:,3)
347 !c   aba  c    abb  !
348 !bc  cc   acb  c    !
349
350 --> t(:,3,:) = []  // Deleting all 3rd columns
351  t  =
352 (:,:,1)
353 !ccc  b    b  !
354 !bbb  bcc  c  !
355
356 (:,:,2)
357 !aa  aab  a   !
358 !ab  a    ba  !
359
360 (:,:,3)
361 !c   aba  abb  !
362 !bc  cc   c    !
363
364 --> t(:,:,2) = []   // Deleting the 2nd page
365  t  =
366 (:,:,1)
367 !ccc  b    b  !
368 !bbb  bcc  c  !
369
370 (:,:,2)
371 !c   aba  abb  !
372 !bc  cc   c    !
373 ]]></screen>
374         <para>
375             With an array of cells:
376         </para>
377         <programlisting role="example"><![CDATA[
378 c = cat(3, {"start", -1.23, %f  ; (1-%s)^2, gda(), list(2,,%z)}, ..
379            {%t     , "abc", 5.2 ; int8(21), []   , %z})
380      ]]></programlisting>
381         <screen><![CDATA[
382 --> c = cat(3, {"start", -1.23, %f  ; (1-%s)^2, gda(), list(2,,%z)}, ..
383                {%t     , "abc", 5.2 ; int8(21), []   , %z})
384  c  =
385 (:,:,1)
386   [1x1 string    ]  [1x1 constant]  [1x1 boolean]
387   [1x1 polynomial]  [1x1 handle  ]  [    list   ]
388
389 (:,:,2)
390   [1x1 boolean]  [1x1 string  ]  [1x1 constant  ]
391   [1x1 int8   ]  [0x0 constant]  [1x1 polynomial]
392
393 --> c(:,2,:) = []                   // Deleting all 2nd columns
394  c  =
395 (:,:,1)
396   [1x1 string    ]  [1x1 boolean]
397   [1x1 polynomial]  [    list   ]
398
399 (:,:,2)
400   [1x1 boolean]  [1x1 constant  ]
401   [1x1 int8   ]  [1x1 polynomial]
402
403 --> c(1,:,:) = []                   // Deleting all 1st rows
404  c  =
405 (:,:,1)
406   [1x1 polynomial]  [ list]
407
408 (:,:,2)
409   [1x1 int8]  [1x1 polynomial]
410 ]]></screen>
411         <para>
412             With an array of structures:
413         </para>
414         <screen><![CDATA[
415 --> s(4,5).r = %pi;
416 --> s.b = %t
417  s  =
418 4x5 struct array with fields:
419    r
420    b
421
422 --> s([1 3],:) = []
423  s  =
424 2x5 struct array with fields:
425    r
426    b
427
428 --> s(:,2) = []
429  s  =
430 2x4 struct array with fields:
431    r
432    b
433 ]]></screen>
434     </refsection>
435     <refsection id="empty_examples">
436         <title>Other examples</title>
437         <programlisting role="example"><![CDATA[
438 type(string([]))
439 [type(int8([])) , type(int16([])) , type(int32([])) , type(int64([]))]
440 [type(uint8([])), type(uint16([])), type(uint32([])), type(uint64([]))]
441 [] * %F
442      ]]></programlisting>
443         <screen><![CDATA[
444 --> type(string([]))
445  ans  =
446    1.
447
448 --> [type(int8([])) , type(int16([])) , type(int32([])) , type(int64([]))]
449  ans  =
450    1.   1.   1.   1.
451
452 --> [type(uint8([])), type(uint16([])), type(uint32([])), type(uint64([]))]
453  ans  =
454    1.   1.   1.   1.
455
456 --> [] * %F
457  ans  =
458     []
459 ]]></screen>
460         <para/>
461         <programlisting role="example"><![CDATA[
462 A = [%s-1, %s^2]
463 A + []
464 A - []
465 A * []
466      ]]></programlisting>
467         <screen><![CDATA[
468 --> A = [%s-1, %s^2]
469  A  =
470            2
471   -1 +s   s
472
473 --> A + []
474  ans  =
475     []
476
477 --> A - []
478  ans  =
479     []
480
481 --> A * []
482  ans  =
483     []
484 ]]></screen>
485         <para/>
486         <programlisting role="example"><![CDATA[
487 string([]) == []
488 ["a" "bc"] + []
489 [] + ["a" "bc"]
490      ]]></programlisting>
491         <screen><![CDATA[
492 --> string([]) == []
493  ans  =
494   T
495
496 --> ["a" "bc"] + []
497  ans  =
498     []
499
500 --> [] + ["a" "bc"]
501  ans  =
502     []
503 ]]></screen>
504         <para/>
505         <programlisting role="example"><![CDATA[
506 A = rand(2,2);
507 A([],:)
508      ]]></programlisting>
509         <screen><![CDATA[
510 --> A = rand(2,2);
511 --> A([],:)
512  ans  =
513     []
514 ]]></screen>
515         <para/>
516         <programlisting role="example"><![CDATA[
517 [det([]) rank([]) trace([]) norm([]) cond([]) rcond([])]
518      ]]></programlisting>
519         <screen><![CDATA[
520 --> [det([]) rank([]) trace([]) norm([]) cond([]) rcond([])]
521  ans  =
522    1.   0.   0.   0.   0.   Inf
523 ]]></screen>
524         <para/>
525         <programlisting role="example"><![CDATA[
526 [sum([]) prod([]) mean([]) median([]) stdev([]) mad([])]
527      ]]></programlisting>
528         <screen><![CDATA[
529 --> [sum([]) prod([]) mean([]) median([]) stdev([]) mad([])]
530  ans  =
531    0.   1.   Nan   Nan   Nan   Nan
532 ]]></screen>
533     </refsection>
534     <refsection role="see also" id="empty_seealso">
535         <title>See also</title>
536         <simplelist type="inline">
537             <member>
538                 <link linkend="null">null</link>
539             </member>
540             <member>
541                 <link linkend="isempty">isempty</link>
542             </member>
543             <member>
544                 <link linkend="emptystr">emptystr</link>
545             </member>
546             <member>
547                 <link linkend="brackets">brackets</link>
548             </member>
549             <member>
550                 <link linkend="symbols">operators</link>
551             </member>
552             <member>
553                 <link linkend="matrices">matrices</link>
554             </member>
555             <member>
556                 <link linkend="oldEmptyBehaviour">oldEmptyBehaviour</link>
557             </member>
558             <member>
559                 <link linkend="insertion">insertion</link>
560             </member>
561         </simplelist>
562     </refsection>
563     <refsection id="empty_history">
564         <title>History</title>
565         <revhistory>
566             <revision>
567                 <revnumber>6.0.0</revnumber>
568                 <revremark>
569                     <itemizedlist>
570                       <listitem>
571                           <literal>A+[]</literal>, <literal>[]+A</literal> and <literal>A-[]</literal>
572                           now return <literal>[]</literal> instead of <literal>A</literal>.
573                           <literal>[]-A</literal> now returns <literal>[]</literal> instead of
574                           <literal>-A</literal>.
575                       </listitem>
576                       <listitem>
577                          <literal> A>[] </literal>, <literal> A>=[] </literal>,
578                          <literal> A&lt;[] </literal>, <literal> A&lt;=[] </literal>,
579                          <literal> []>A </literal>, <literal> []>=A </literal>,
580                          <literal> []&lt;A </literal>, and <literal> []&lt;=A </literal> now return
581                          <literal> [] </literal> instead of an error.
582                       </listitem>
583                     </itemizedlist>
584                 </revremark>
585             </revision>
586         </revhistory>
587     </refsection>
588 </refentry>