help brackets: page overhauled and rewritten
[scilab.git] / scilab / modules / core / help / en_US / 1_keywords / brackets.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) 2016 - Samuel GOUGEON
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="brackets">
17     <refnamediv>
18         <refname>brackets [,;]</refname>
19         <refpurpose>Concatenation. Recipients of an assignment. Results of a function</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>
24             Mh = [m11 m12 m13.. m1N] or [m11, m12, m13,.., m1N]
25             Mv = [m11 ; m21 ; m31..; mN1]
26             M  = [m11, m12,...; m21, m22,...;...]
27             [r1, r2,...] = func(...)
28             [r1, r2,.., rN] = (e1, e2, .., eN)
29             [r1, r2,.., rk] = (e1, e2, .., ek,.., eN)
30             [r1, r2,.., rN] = mylist(:)
31             [r1, r2,.., rN] = S.field([i1 i2.. iN])
32         </synopsis>
33     </refsynopsisdiv>
34     <refsection role="parameters">
35         <title>Arguments</title>
36         <variablelist>
37             <varlistentry>
38                 <term>m11, m12,...  </term>
39                 <listitem>
40                     <para>
41                     Set of objects to be
42                     concatenated (and merged: the former individual containers
43                     are removed).
44                     The following subsets of types of objects can be mixed
45                     in-between, but are mutually exclusive:
46                     <itemizedlist>
47                         <listitem>Matrices of booleans, reals, complex numbers,
48                             polynomials, rationals: The data type of the
49                             concatenated result is set by the rules defined below
50                             (see the <link linkend="brackets_Types_conversions">
51                             <emphasis role="italic">type conversions</emphasis>
52                             </link> rules).
53                         </listitem>
54                         <listitem>Matrices of encoded integers of any
55                             <link linkend="inttype">inttype</link>.
56                             <warning>
57                                 Encoded integers of different inttypes can't
58                                 be concatenated together.
59                             </warning>
60                         </listitem>
61                         <listitem>Arrays of structures with same fields.
62                             Fields may be in different orders from an array
63                             to other ones.
64                         </listitem>
65                         <listitem>
66                             Typed lists of type <link linkend="syslin">syslin</link>.
67                         </listitem>
68                     </itemizedlist>
69                     </para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>M, Mh, Mv</term>
74                 <listitem>
75                     <para>
76                         Matrices with the type of all <varname>m##</varname>
77                         (if they all have the same data type)
78                     </para>
79                 </listitem>
80             </varlistentry>
81             <varlistentry>
82                 <term>e1, e2,..  </term>
83                 <listitem>
84                     <para>Input objects (literals like <literal>-1.23</literal>
85                     or <literal>"abcd"</literal>, variables, or expressions
86                     like <literal>a+%pi</literal>, etc).
87                     </para>
88                 </listitem>
89             </varlistentry>
90             <varlistentry>
91                 <term>mylist</term>
92                 <listitem>
93                     <para>a simple list</para>
94                 </listitem>
95             </varlistentry>
96             <varlistentry>
97                 <term>S.field</term>
98                 <listitem>
99                     <para>
100                         Array of Structures with a field named <literal>field</literal>.
101                     </para>
102                 </listitem>
103             </varlistentry>
104             <varlistentry>
105                 <term>i1, i2,..  </term>
106                 <listitem>
107                     <para>
108                         Indices of components selected from <varname>S</varname>.
109                     </para>
110                 </listitem>
111             </varlistentry>
112             <varlistentry>
113                 <term>r1, r2,...  </term>
114                 <listitem>
115                     <para>Output variables</para>
116                 </listitem>
117             </varlistentry>
118         </variablelist>
119     </refsection>
120     <refsection role="description">
121         <title>Description</title>
122         <variablelist>
123             <varlistentry>
124                 <term>[] on right-hand side: concatenators</term>
125                 <listitem>
126                     <para>[..] bundle their contents of simple and compatible
127                         types into a homogeneous vector, matrix or hypermatrix.
128                     </para>
129                     <note>An horizontal or a vertical concatenation is a
130                         binary iterated operator. It is performed step-by-step
131                         from left-to-right, and from top-to-bottom. Thus,
132                         <literal>[1 3 5 7]</literal> is performed as
133                         <literal>[[[1 3] 5] 7]</literal>.
134                     </note>
135                     <para>Inside brackets,
136                         <itemizedlist>
137                             <listitem>spaces (blanks or tabs) or commas are
138                                 used as columns separators.
139                                 <note>Using commas instead of spaces is safer.
140                                     For instance, <literal>[2 1 +%i]</literal>
141                                     means <literal>[2, 1, %i]</literal>, while
142                                     <literal>[2 1 + %i]</literal> means
143                                     <literal>[2, 1+%i]</literal>
144                                 </note>
145                             </listitem>
146                             <listitem>semi-colons or carriage-return are used
147                                 as rows separators. Multiple rows do not need
148                                 the continuation dots <literal>..</literal>
149                             </listitem>
150                         </itemizedlist>
151                     </para>
152                     <refsect3 id="brackets_Types_conversions">
153                         <title>Types conversions</title>
154                         <para>
155                             In some limits, brackets may be applied on a set of
156                             data having different but compatible types. In this
157                             case, some data are converted into the dominating type
158                             available in the set. The main conversion rules are the
159                             following:
160                             <orderedlist>
161                                 <listitem>boolean &lt; decimal number &lt; complex
162                                 </listitem>
163                                 <listitem>decimal number &lt; polynomial &lt; rational
164                                     <warning>booleans and polynomials are not compatible.
165                                         <itemizedlist>
166                                             <listitem>
167                                                 <literal>[%t 2. %z]</literal> is accepted:
168                                                 <literal>[%t 2.]</literal> is first
169                                                 converted into
170                                                 <literal>[1. 2.]</literal>, and then
171                                                 <literal>[[1. 2.] %z]</literal> is accepted.
172                                             </listitem>
173                                             <listitem>
174                                                 <literal>[%z %t 2.]</literal> is
175                                                 rejected and yields an error.
176                                                 Indeed, <literal>[%z %t]</literal>
177                                                 can't be converted first.
178                                             </listitem>
179                                         </itemizedlist>
180                                     </warning>
181                                 </listitem>
182                                 <listitem>
183                                     The result becomes complex-encoded as soon as
184                                     a complex-encoded component -- value, polynomial,
185                                     or rational -- is met in the list
186                                     (even with a null imaginary part)
187                                     <para>Similarly, the result becomes sparse-encoded
188                                     as soon as a sparse-encoded component is met
189                                     and processed.
190                                     </para>
191                                 </listitem>
192                                 <listitem>
193                                     It is possible to concatenate polynomials or/and
194                                     rationals having different variable names. Then,
195                                     the first polynomial or rational met in the list
196                                     sets the variable name to the concatenation result:
197                                     <literal>[%z, 1+%s, 1-%i*%s]
198                                         // => [z, 1+z, 1-iz]
199                                     </literal>.
200                                 </listitem>
201                                 <listitem>
202                                     Any encoded integer can be concatenated
203                                     only with integers of the same inttype.
204                                     Thus, the expressions
205                                     <literal>[%t int8(2)]</literal>,
206                                     <literal>[int8(2) uint8(7)]</literal>,
207                                     <literal>[int8(2) int16(7)]</literal>,
208                                     <literal>[int8(2) 1.]</literal> will all yield
209                                     an error.
210                                 </listitem>
211                                 <listitem>Text components can be concatenated
212                                     (in the set meaning, with brackets) only with other
213                                     text components or with the empty matrix.
214                                     <literal>[]</literal>.
215                                 </listitem>
216                             </orderedlist>
217                         </para>
218                     </refsect3>
219                     <refsect3 id="brackets_overloading">
220                         <title>Overloading</title>
221                         <para>
222                             <itemizedlist>
223                                 <listitem>[,]: horizontal concatenation:
224                                     This operator is binary and automatically
225                                     iterated from left to right. Its overloading
226                                     code is <literal>"c"</literal>.
227                                 </listitem>
228                                 <listitem>[;]: vertical concatenation:
229                                     This operator is binary and automatically
230                                     iterated from top to bottom. Its overloading
231                                     code is <literal>"f"</literal>.
232                                 </listitem>
233                             </itemizedlist>
234                         </para>
235                     </refsect3>
236                 </listitem>
237             </varlistentry>
238             <varlistentry>
239                 <term>[] on left-hand side of a <literal>"="</literal> assignment</term>
240                 <listitem>
241                     <para>
242                     In this case, brackets are no longer concatenators.
243                     They are used as left and right delimiters of a series of
244                     variables used as recipients.
245                     </para>
246                     <para>
247                         <itemizedlist>
248                             <listitem>Recipients must be variables.
249                                 Litteral expressions are not accepted.
250                             </listitem>
251                             <listitem>Variables shall be separated with comas.
252                             </listitem>
253                             <listitem>In a distributive assignment, there must
254                                 be at most as many LHS recipients
255                                 as output sources, not more. If there are less
256                                 recipients on the left than sources on the right,
257                                 non-collected data sources are ignored. Examples :
258                                 <simplelist>
259                                     <member><literal>[a,b]=(%pi,"Hi", %z)</literal>
260                                         is OK, but <literal>%z</literal> is ignored.
261                                     </member>
262                                     <member><literal>[a,b,c]=(%pi,"Hi")</literal>
263                                         yields an error because <literal>c</literal>
264                                         expects some foods.
265                                     </member>
266                                 </simplelist>
267                             </listitem>
268                             <listitem>The same variable may be used several times
269                                 in the list. Then, multiple assignments overwrite
270                                 the previous ones, from left to right.
271                                 Example :
272                                 <literal>[a,b,a]=(%pi,%z,"Allo")</literal>
273                                 is equivalent to <literal>a="Allo", b=%z</literal>.
274                             </listitem>
275                         </itemizedlist>
276                     </para>
277                 </listitem>
278             </varlistentry>
279         </variablelist>
280     </refsection>
281     <refsection role="examples">
282         <title>Examples</title>
283         <programlisting role="example"><![CDATA[
284 // Horizontal concatenations
285 a = [ %pi 4 -1 ]
286 b1 = grand(3,4,"uin",0,10)
287 b2 = grand(3,2,"uin",0,10)
288 b = [b1 b2]  // they must have the same number of rows
289
290 // Vertical concatenations
291 a = [-2 ; 10 ; 7]
292
293 b1 = grand(2,4,"uin",0,10)
294 b2 = grand(3,4,"uin",0,10)
295 b = [b1 ; b2] // they must have the same number of columns
296
297 // Mixed horizontal and vertical concatenations
298 a = [ 3 7 ; 6, 5 ]
299 b = [ 1:3 ; 7:3:13]
300 c = [ a b ; a b]
301
302 d = [ 3 5
303       1 4
304     ]
305 e = [ d d d
306       d d d
307     ]
308 // Concatenation of various types of data:
309 ['this is' ; 'a column' ; 'of texts']
310
311 s = poly(0,'s');[1/s,2/s]
312 [tf2ss(1/s),tf2ss(2/s)]
313
314 [%t %f %f %T %F]
315
316 // Heterogeneous concatenations with automatical types conversions
317 [%T %pi %f 2]
318 [%pi, 2+%i, %F]
319 v = [%pi+0*%i, %F, %z, (1-%z)^2 ]; typeof(v), isreal(v)
320 v = [10 1/%z], typeof(v)
321
322 // Incompatible heterogeneous concatenations => ERRORS
323 [%F %z]
324 [%F int8(5)]
325 [int8(%pi) uint8(%e)]
326 [int8(%pi) int16(%e)]
327  ]]></programlisting>
328
329         <para>
330             <emphasis role="bold">Distributive assignments:</emphasis>
331         </para>
332         <programlisting role="example"><![CDATA[
333 // Output from a function. Most often, output results are serially optional:
334 M = rand(3,3);
335 [u, s] = schur(M) // we expect and use both results u and s
336 u = schur(M)      // we expect and store only the first result u
337
338 // Direct RHS list
339 [a, b, c] = (%pi, %t, "test")
340 [a, b] = (%e, %f, "Hello")
341 [a, b, a] = (%pi, %t, "test");
342
343 // Explicit RHS list
344 L = list(%z, %i, %t, %pi, "Text");
345 [a, b, c] = L(:)
346
347 // RHS structure
348 s(2,3).r = %pi; s(2,1).r = %i; s(2,2) = %e;
349 s(2,:).r
350 s.r([2 4 6])
351 [a, b, c] = s.r([2 4 6])
352
353 // Forbidden / Rejected LHS expressions (=> error)
354 [m, n, m+n] = myfun(a,b)   // Symbolic expressions like "m+n" are forbidden
355 [p, 4.5, q] = myfun(a,b)   // Literal LHS values or expressions like "4.5" are forbidden
356 [r, s+3 ] = myfun(a,b)   // Expressions mixing literals and symbols like "s+3" can't be LHS recipients
357 ]]></programlisting>
358         <screen><![CDATA[--> [a, b, c] = (%pi, %t, "test")
359  c  =
360  test
361
362  b  =
363   T
364
365  a  =
366    3.1415927
367
368 --> [a, b] = (%e, %f, "Hello")
369  b  =
370   F
371
372  a  =
373    2.7182818
374
375 --> [a, b, a] = (%pi, %t, "test"); a
376  a  =
377    3.1415927
378 ]]></screen>
379     </refsection>
380     <refsection role="see also">
381         <title>See also</title>
382         <simplelist type="inline">
383             <member>
384                 <link linkend="empty">empty</link>
385             </member>
386             <member>
387                 <link linkend="parentheses">parentheses</link>
388             </member>
389             <member>
390                 <link linkend="lstcat">lstcat</link>
391             </member>
392             <member>
393                 <link linkend="comma">comma</link>
394             </member>
395             <member>
396                 <link linkend="semicolon">semicolon</link>
397             </member>
398             <member>
399                 <link linkend="overloading">overloading</link>
400             </member>
401         </simplelist>
402     </refsection>
403     <refsection role="history">
404         <title>History</title>
405         <revhistory>
406             <revision>
407                 <revnumber>6.0</revnumber>
408                 <revdescription>
409                     Brackets <literal>[..]</literal> and braces
410                     <literal>{..}</literal> are no longer equivalent
411                 </revdescription>
412             </revision>
413         </revhistory>
414     </refsection>
415 </refentry>