brackets [,;]

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

_

Ignored output variable

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 — stacks vectors matrices or arrays into an hypermatrix or hyperarray
• lstcat — list concatenation
• comma — (,) comma; instruction, argument separator
• semicolon — (;) ending expression and row separator
• parentheses — ( ) left and right parenthesis
• empty — empty matrix. Array ranges destructor.
• overloading — display, functions and operators overloading capabilities

History