brackets [,;] Concatenation. Recipients of an assignment. Results of a function

## Syntax

                Mh = [m11 m12 m13.. m1N] or [m11, m12, m13,.., m1N]
                Mv = [m11 ; m21 ; m31..; mN1]
                M  = [m11, m12,...; m21, m22,...;...]
                [r1, r2,...] = func(...)
                [r1, r2,.., rN] = (e1, e2, .., eN)
                [r1, r2,.., rk] = (e1, e2, .., ek,.., eN)
                [r1, r2,.., rN] = mylist(:)
                [r1, r2,.., rN] = S.field([i1 i2.. iN])

## Arguments

m11, m12,...

  Set of objects to be concatenated (and merged: the former individual containers are removed). The following subsets of types of objects can be mixed in-between, but are mutually exclusive:

  - Matrices of booleans, reals, complex numbers, polynomials, rationals: The data type of the concatenated result is set by the rules defined below (see the type conversions rules).
  - Matrices of encoded integers of any inttype.
    Encoded integers of different inttypes can't be concatenated together.
  - Arrays of cells.
  - Arrays of structures with same fields. Fields may be in different orders from an array to other ones.
  - Typed lists of type syslin.
M, Mh, Mv

  Matrices with the type of all `m##` (if they all have the same data type). cells arrays (if `mi` are so). structures arrays (if `mi` are so).

e1, e2,..

  Input objects (literals like `-1.23` or `"abcd"`, variables, or expressions like `a+%pi`, etc).

mylist

  a simple list

S.field

  Array of Structures with a field named `field`.

i1, i2,..

  Indices of components selected from `S`.

r1, r2,...

  Output variables

## Description

[] on right-hand side: concatenators

  [..] bundle their contents of simple and compatible types into a homogeneous vector, matrix or hypermatrix.

  An horizontal or a vertical concatenation is a binary iterated operator. It is performed step-by-step from left-to-right, and from top-to-bottom. Thus, `[1 3 5 7]` is performed as `[[[1 3] 5] 7]`.

  Inside brackets,

  - spaces (blanks or tabs) or commas are used as columns separators.
    Using commas instead of spaces is safer. For instance, `[2 1 +%i]` means `[2, 1, %i]`, while `[2 1 + %i]` means `[2, 1+%i]`
  - semi-colons or carriage-return are used as rows separators. Multiple rows do not need the continuation dots `..`

  ### Types conversions

  In some limits, brackets may be applied on a set of data having different but compatible types. In this case, some data are converted into the dominating type available in the set. The main conversion rules are the following:

  1. boolean < encoded integers < decimal number < complex
  2. decimal number < polynomial < rational
     booleans and polynomials are not compatible.
     - `[%t 2. %z]` is accepted: `[%t 2.]` is first converted into `[1. 2.]`, and then `[[1. 2.] %z]` is accepted.
     - `[%z %t 2.]` is rejected and yields an error. Indeed, `[%z %t]` can't be converted first.
  3. Any encoded integer can be concatenated only with booleans, decimal numbers, or other integers of the same inttype. Thus, the expressions `[int8(2), uint8(7)]`, `[int8(2), int16(7)]`, `[int8(2), 7+0*%z]`, `[int8(2), sparse(7)]`, or `[int8(2), sparse(%t)]` will yield an error.
  4. The result becomes complex-encoded as soon as a complex-encoded component -- value, polynomial, or rational -- is met in the list (even with a null imaginary part)

     Similarly, the result becomes sparse-encoded as soon as a sparse-encoded component is met and processed.
  5. Concatenated polynomials or/and rationals must have the same variable name.
  6. Text components can be concatenated (in the set meaning, with brackets) only with other text components or with the empty matrix `[]`.

  ### Overloading

  - [,]: horizontal concatenation: This operator is binary and automatically iterated from left to right. Its overloading code is `"c"`.
  - [;]: vertical concatenation: This operator is binary and automatically iterated from top to bottom. Its overloading code is `"f"`.

  ### Extensions

  - To concatenate simple lists, please use lstcat.
  - To stack vectors or matrices over some dimension > 2 to build a N-dimensional array, please use cat.

[] on left-hand side of a `"="` assignment

  In this case, brackets are no longer concatenators. They are used as left and right delimiters of a series of variables used as recipients.

  - Recipients must be variables. Literal expressions are not accepted.
  - Variables shall be separated with commas.
  - In a distributive assignment, there must be at most as many LHS recipients as output sources, not more. If there are less recipients on the left than sources on the right, non-collected data sources are ignored. Examples :
    - `[a,b]=(%pi,"Hi", %z)` is OK, but `%z` is ignored.
    - `[a,b,c]=(%pi,"Hi")` yields an error because `c` expects some foods.
  - `[a,b,a] = (%pi, %z, "Allo")` performs assignments from left to right, such that finally `a = "Allo"`.

## Examples

    // Horizontal concatenations
    a = [ %pi 4 -1 ]
    b1 = grand(3,4,"uin",0,10)
    b2 = grand(3,2,"uin",0,10)
    b = [b1 b2]  // they must have the same number of rows

    // Vertical concatenations
    a = [-2 ; 10 ; 7]

    b1 = grand(2,4,"uin",0,10)
    b2 = grand(3,4,"uin",0,10)
    b = [b1 ; b2] // they must have the same number of columns

    // Mixed horizontal and vertical concatenations
    a = [ 3 7 ; 6, 5 ]
    b = [ 1:3 ; 7:3:13]
    c = [ a b ; a b]

    d = [ 3 5
          1 4
        ]
    e = [ d d d
          d d d
        ]
    // Concatenation of various types of data:
    ['this is' ; 'a column' ; 'of texts']

    s = poly(0,'s');[1/s,2/s]
    [tf2ss(1/s),tf2ss(2/s)]

    [%t %f %f %T %F]

Heterogeneous concatenations with automatical type conversions:

    [%T int8(-5)]
    [%T %pi %f 2]
    [%pi, 2+%i, %F]
    [%pi int16(-1000.84) 1.23]
    v = [%pi+0*%i, %F, %z, (1-%z)^2 ]; typeof(v), isreal(v)
    v = [10 1/%z], typeof(v)

    // Special case: int16 and uint8 together, due to initial
    //   conversion to real propagating from left to right
    [%pi int16(-1000.84) uint8(87)]

Incompatible heterogeneous concatenations => ERRORS:

    [%F %z]
    [%s %z]
    [int8(-70), sparse(18)]
    [int8(-70), sparse([%T %F])]

Concatenation of cells arrays:

    // Concatenation of cells arrays:
    c1 = {%pi %t};
    c2 = {%z "abc"};
    c = [[{%i} c1] ; [c2, {1/%z^2}]]  // comma mandatory, to not parse c2{1/%z^2}

Distributive assignments:

    // Output from a function. Most often, output results are serially optional:
    M = rand(3,3);
    [u, s] = schur(M) // we expect and use both results u and s
    u = schur(M)      // we expect and store only the first result u

    // Direct RHS list
    [a, b, c] = (%pi, %t, "test")
    [a, b] = (%e, %f, "Hello")
    [a, b, a] = (%pi, %t, "test"); a

    // Explicit RHS list
    L = list(%z, %i, %t, %pi, "Text");
    [a, b, c] = L(:)

    // RHS structure
    s(2,3).r = %pi; s(2,1).r = %i; s(2,2) = %e;
    s(2,:).r
    s.r([2 4 6])
    [a, b, c] = s.r([2 4 6])

    // Forbidden / Rejected LHS expressions (=> error)
    [m, n, m+n] = myfun(a,b)   // Symbolic expressions like "m+n" are forbidden
    [p, 4.5, q] = myfun(a,b)   // Literal LHS values or expressions like "4.5" are forbidden
    [r, s+3 ] = myfun(a,b)   // Expressions mixing literals and symbols like "s+3" can't be LHS recipients

    --> [a, b, c] = (%pi, %t, "test")
     a  =
       3.1415927

     b  =
      T

     c  =
     test

    --> [a, b] = (%e, %f, "Hello")
     a  =
       2.7182818

     b  =
      F

    --> [a, b, a] = (%pi, %t, "test"); a
     a  =
     test

## See also

- cat
- lstcat
- comma
- semicolon
- parentheses
- empty
- overloading

## History

6.0 Brackets `[..]` and braces `{..}` are no longer equivalent
6.1.0

- Booleans and encoded integers can now be concatenated together, as in [%t, int8(-5)].
- [a, b, ..] = (A, B,..) now performs assignments from left to right.

6.1.1

- Concatenations between encoded integers and decimal numbers are now supported.
- Concatenated polynomials or/and rationals must have the same variable name.