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