* Bug 16450 fixed: [double, integer] & [double ; integer] implemented
[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 - 2020 - 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 &lt; decimal number &lt; complex
165                                 </listitem>
166                                 <listitem>decimal number &lt; polynomial &lt; rational
167                                     <warning>booleans and polynomials are not compatible.
168                                         <itemizedlist>
169                                             <listitem>
170                                                 <literal>[%t 2. %z]</literal> is accepted:
171                                                 <literal>[%t 2.]</literal> is first converted into
172                                                 <literal>[1. 2.]</literal>, and then
173                                                 <literal>[[1. 2.] %z]</literal> is accepted.
174                                             </listitem>
175                                             <listitem>
176                                                 <literal>[%z %t 2.]</literal> is rejected and yields
177                                                 an error. Indeed, <literal>[%z %t]</literal>
178                                                 can't be converted first.
179                                             </listitem>
180                                         </itemizedlist>
181                                     </warning>
182                                 </listitem>
183                                 <listitem>
184                                     Any encoded integer can be concatenated only with booleans,
185                                     decimal numbers, or other integers of the same inttype.
186                                     Thus, the expressions
187                                     <literal>[int8(2), uint8(7)]</literal>,
188                                     <literal>[int8(2), int16(7)]</literal>,
189                                     <literal>[int8(2), 7+0*%z]</literal>,
190                                     <literal>[int8(2), sparse(7)]</literal>, or
191                                     <literal>[int8(2), sparse(%t)]</literal>
192                                     will yield an error.
193                                 </listitem>
194                                 <listitem>
195                                     The result becomes complex-encoded as soon as a complex-encoded
196                                     component -- value, polynomial, or rational -- is met in the
197                                     list (even with a null imaginary part)
198                                     <para/>
199                                     Similarly, the result becomes sparse-encoded
200                                     as soon as a sparse-encoded component is met and processed.
201                                 </listitem>
202                                 <listitem>
203                                     It is possible to concatenate polynomials or/and rationals
204                                     having different variable names. Then, the first polynomial
205                                     or rational met in the list sets the variable name to the
206                                     concatenation result:
207                                     <literal>[%z, 1+%s, 1-%i*%s]
208                                         // => [z, 1+z, 1-iz]
209                                     </literal>.
210                                 </listitem>
211                                 <listitem>
212                                     Text components can be concatenated (in the set meaning,
213                                     with brackets) only with other text components or with the
214                                     empty matrix <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                     <para/>
237                     <refsect3>
238                         <title>Extensions</title>
239                         <para>
240                           <itemizedlist>
241                             <listitem>
242                               To concatenate simple lists, please use <link linkend="lstcat">lstcat</link>.
243                             </listitem>
244                             <listitem>
245                               To stack vectors or matrices over some dimension > 2 to build a
246                               N-dimensional array, please use <link linkend="cat">cat</link>.
247                             </listitem>
248                           </itemizedlist>
249                         </para>
250                     </refsect3>
251                 </listitem>
252                 <para/>
253             </varlistentry>
254             <varlistentry>
255                 <term>[] on left-hand side of a <literal>"="</literal> assignment</term>
256                 <listitem>
257                     <para>
258                     In this case, brackets are no longer concatenators.
259                     They are used as left and right delimiters of a series of
260                     variables used as recipients.
261                     </para>
262                     <para>
263                         <itemizedlist>
264                             <listitem>Recipients must be variables.
265                                 Literal expressions are not accepted.
266                             </listitem>
267                             <listitem>Variables shall be separated with commas.
268                             </listitem>
269                             <listitem>In a distributive assignment, there must
270                                 be at most as many LHS recipients
271                                 as output sources, not more. If there are less
272                                 recipients on the left than sources on the right,
273                                 non-collected data sources are ignored. Examples :
274                                 <simplelist>
275                                     <member><literal>[a,b]=(%pi,"Hi", %z)</literal>
276                                         is OK, but <literal>%z</literal> is ignored.
277                                     </member>
278                                     <member><literal>[a,b,c]=(%pi,"Hi")</literal>
279                                         yields an error because <literal>c</literal>
280                                         expects some foods.
281                                     </member>
282                                 </simplelist>
283                             </listitem>
284                             <listitem>
285                                 <literal>[a,b,a] = (%pi, %z, "Allo")</literal> performs assignments
286                                 from left to right, such that finally <literal>a = "Allo"</literal>.
287                             </listitem>
288                         </itemizedlist>
289                     </para>
290                 </listitem>
291             </varlistentry>
292         </variablelist>
293     </refsection>
294     <refsection role="examples">
295         <title>Examples</title>
296         <programlisting role="example"><![CDATA[
297 // Horizontal concatenations
298 a = [ %pi 4 -1 ]
299 b1 = grand(3,4,"uin",0,10)
300 b2 = grand(3,2,"uin",0,10)
301 b = [b1 b2]  // they must have the same number of rows
302
303 // Vertical concatenations
304 a = [-2 ; 10 ; 7]
305
306 b1 = grand(2,4,"uin",0,10)
307 b2 = grand(3,4,"uin",0,10)
308 b = [b1 ; b2] // they must have the same number of columns
309
310 // Mixed horizontal and vertical concatenations
311 a = [ 3 7 ; 6, 5 ]
312 b = [ 1:3 ; 7:3:13]
313 c = [ a b ; a b]
314
315 d = [ 3 5
316       1 4
317     ]
318 e = [ d d d
319       d d d
320     ]
321 // Concatenation of various types of data:
322 ['this is' ; 'a column' ; 'of texts']
323
324 s = poly(0,'s');[1/s,2/s]
325 [tf2ss(1/s),tf2ss(2/s)]
326
327 [%t %f %f %T %F]
328      ]]></programlisting>
329         <para>
330             Heterogeneous concatenations with automatical type conversions:
331         </para>
332         <programlisting role="example"><![CDATA[
333 [%T int8(-5)]
334 [%T %pi %f 2]
335 [%pi, 2+%i, %F]
336 [%pi int16(-1000.84) 1.23]
337 v = [%pi+0*%i, %F, %z, (1-%z)^2 ]; typeof(v), isreal(v)
338 v = [10 1/%z], typeof(v)
339
340 // Special case: int16 and uint8 together, due to initial
341 //   conversion to real propagating from left to right
342 [%pi int16(-1000.84) uint8(87)]
343      ]]></programlisting>
344         <para>
345             Incompatible heterogeneous concatenations => ERRORS:
346         </para>
347         <programlisting role="example"><![CDATA[
348 [%F %z]
349 [int8(%pi), uint8(%e)]
350 [int8(%pi), int16(%e)]
351 [int8(-70), sparse(18)]
352 [int8(-70), sparse([%T %F])]
353      ]]></programlisting>
354         <para>
355             Concatenation of cells arrays:
356         </para>
357         <programlisting role="example"><![CDATA[
358 c1 = {%pi %t};
359 c2 = {%z "abc"};
360 c = [[{%i} c1] ; [c2, {1/%z^2}]]  // comma mandatory, to not parse c2{1/%z^2}
361 ]]></programlisting>
362
363         <para>
364             <emphasis role="bold">Distributive assignments:</emphasis>
365         </para>
366         <programlisting role="example"><![CDATA[
367 // Output from a function. Most often, output results are serially optional:
368 M = rand(3,3);
369 [u, s] = schur(M) // we expect and use both results u and s
370 u = schur(M)      // we expect and store only the first result u
371
372 // Direct RHS list
373 [a, b, c] = (%pi, %t, "test")
374 [a, b] = (%e, %f, "Hello")
375 [a, b, a] = (%pi, %t, "test"); a
376
377 // Explicit RHS list
378 L = list(%z, %i, %t, %pi, "Text");
379 [a, b, c] = L(:)
380
381 // RHS structure
382 s(2,3).r = %pi; s(2,1).r = %i; s(2,2) = %e;
383 s(2,:).r
384 s.r([2 4 6])
385 [a, b, c] = s.r([2 4 6])
386
387 // Forbidden / Rejected LHS expressions (=> error)
388 [m, n, m+n] = myfun(a,b)   // Symbolic expressions like "m+n" are forbidden
389 [p, 4.5, q] = myfun(a,b)   // Literal LHS values or expressions like "4.5" are forbidden
390 [r, s+3 ] = myfun(a,b)   // Expressions mixing literals and symbols like "s+3" can't be LHS recipients
391 ]]></programlisting>
392         <screen><![CDATA[--> [a, b, c] = (%pi, %t, "test")
393  a  =
394    3.1415927
395
396  b  =
397   T
398
399  c  =
400  test
401
402 --> [a, b] = (%e, %f, "Hello")
403  a  =
404    2.7182818
405
406  b  =
407   F
408
409 --> [a, b, a] = (%pi, %t, "test"); a
410  a  =
411  test
412 ]]></screen>
413     </refsection>
414     <refsection role="see also">
415         <title>See also</title>
416         <simplelist type="inline">
417             <member>
418                 <link linkend="cat">cat</link>
419             </member>
420             <member>
421                 <link linkend="lstcat">lstcat</link>
422             </member>
423             <member>
424                 <link linkend="comma">comma</link>
425             </member>
426             <member>
427                 <link linkend="semicolon">semicolon</link>
428             </member>
429             <member>
430                 <link linkend="parentheses">parentheses</link>
431             </member>
432             <member>
433                 <link linkend="empty">empty</link>
434             </member>
435             <member>
436                 <link linkend="overloading">overloading</link>
437             </member>
438         </simplelist>
439     </refsection>
440     <refsection role="history">
441         <title>History</title>
442         <revhistory>
443             <revision>
444                 <revnumber>6.0</revnumber>
445                 <revdescription>
446                     Brackets <literal>[..]</literal> and braces
447                     <literal>{..}</literal> are no longer equivalent
448                 </revdescription>
449             </revision>
450             <revision>
451                 <revnumber>6.1.0</revnumber>
452                 <revdescription>
453                     <itemizedlist>
454                         <listitem>
455                             Booleans and encoded integers can now be concatenated together,
456                             as in [%t, int8(-5)].
457                         </listitem>
458                         <listitem>
459                             [a, b, ..] = (A, B,..) now performs assignments from left to right.
460                         </listitem>
461                     </itemizedlist>
462                 </revdescription>
463             </revision>
464             <revision>
465                 <revnumber>6.1.1</revnumber>
466                 <revdescription>
467                     Concatenations between encoded integers and decimal numbers
468                     are now supported.
469                 </revdescription>
470             </revision>
471         </revhistory>
472     </refsection>
473 </refentry>