Scilab Function
Last update : 20/12/2004

extraction - matrix and list entry extraction

### Calling Sequence

  `x(i,j)`
  `x(i)`
  `[...]=l(i)`
  `[...]=l(k1)...(kn)(i) or [...]=l(list(k1,...,kn,i))`
  `l(k1)...(kn)(i,j) or l(list(k1,...,kn,list(i,j))`

### Parameters

- `x`: matrix of any possible types
- `l`: list variable
- `i,j`: indices
- `k1,...kn`: indices

### Description

  MATRIX CASE `i` and `j`, can be:
  -real scalars or vectors or matrices with positive elements.
  *

  `r=x(i,j)` builds the matrix `r` such as `r(l,k)=x(int(i(l)),int(j(k)))` for `l` from 1 to `size(i,'*')` and `k` from 1 to `size(j,'*')`. `i` (`j`) Maximum value must be less or equal to `size(x,1)` (`size(x,2)`).

  *

  `r=x(i)` with `x` a 1x1 matrix builds the matrix `r` such as `r(l,k)=x(int(i(l)),int(i(k)))` for `l` from 1 to `size(i,1)` and `k` from 1 to `size(i,2)`. Note that in this case index `i` is valid only if all its entries are equal to one.

  *`r=x(i)` with `x` a row vector builds the row vector `r` such as `r(l)=x(int(i(l)))` for `l` from 1 to `size(i,'*')``i` Maximum value must be less or equal to `size(x,'*')`.
  *

  `r=x(i)` with `x` a matrix with one or more columns builds the column vector `r` such as `r(l)` (`l` from 1 to `size(i,'*')`) contains the `int(i(l))` entry of the column vector formed by the concatenation of the `x`'s columns. `i` Maximum value must be less or equal to `size(x,'*')`.

  -the `:` symbol which stands for "all elements".
  *`r=x(i,:)` builds the matrix `r` such as `r(l,k)=x(int(i(l)),k))` for `l` from 1 to `size(i,'*')` and `k` from 1 to `size(x,2)`
  *`r=x(:,j)` builds the matrix `r` such as `r(l,k)=x(l,int(j(k)))` for `l` from 1 to `size(r,1)` and `k` from 1 to `size(j,'*')`.
  *`r=x(:)` builds the column vector `r` formed by the column concatenations of`x` columns. It is equivalent to `matrix(x,size(x,'*'),1)`.
  -vector of boolean. If an index (`i` or `j` )is a vector of booleans it is interpreted as `find(i)` or respectively `find(j)`
  -a polynomial. If an index (`i` or `j` )is a vector of polynomials or implicit polynomial vector it is interpreted as `horner(i,m)` or respectively `horner(j,n)` where `m` and `n` are associated `x` dimensions. Even if this feature works for all polynomials, it is recommended to use polynomials in `$` for readability.
  LIST OR TLIST CASE

  If they are present the `ki` give the path to a sub-list entry of `l` data structure. They allow a recursive extraction without intermediate copies. The `[...]=l(k1)...(kn)(i)` and `[...]=l(list(k1,...,kn,i))` instructions are interpreted as: `lk1 = l(k1)``.. = ..` `lkn = lkn-1(kn)``[...] = lkn(i)` And the `l(k1)...(kn)(i,j)` and `l(list(k1,...,kn,list(i,j))` instructions are interpreted as: `lk1 = l(k1)``.. = ..` `lkn = lkn-1(kn)``lkn(i,j)``i` and `j`, can be: When path points on more than one list component the instruction must have as many left hand side arguments as selected components. But if the extraction syntax is used within a function input calling sequence each returned list component is added to the function calling sequence.

  Note that, `l(list()` is the same as `l`.

  -real scalar or vector or matrix with positive elements. `[r1,...rn]=l(i)` extracts the `i(k)` elements from the list l and store them in `rk` variables for `k` from 1 to `size(i,'*')`
  -the `:` symbol which stands for "all elements".
  -a vector of booleans. If `i` is a vector of booleans it is interpreted as `find(i)`.
  -a polynomial. If `i` is a vector of polynomials or implicit polynomial vector it is interpreted as `horner(i,m)` where `m=size(l)`. Even if this feature works for all polynomials, it is recommended to use polynomials in `$` for readability.
  k1,..kn may be :
  -real positive scalar.
  -a polynomial,interpreted as `horner(ki,m)` where `m` is the corresponding sub-list size.
  - a character string associated with a sub-list entry name.

### Remarks

For soft coded matrix types such as rational functions and state space linear systems, `x(i)` syntax may not be used for vector element extraction due to confusion with list element extraction. `x(1,j)` or `x(i,1)` syntax must be used.

### Examples

    // MATRIX CASE
    a=[1 2 3;4 5 6]
    a(1,2)
    a([1 1],2)
    a(:,1)
    a(:,3:-1:1)
    a(1)
    a(6)
    a(:)
    a([%t %f %f %t])
    a([%t %f],[2 3])
    a(1:2,$-1)
    a($:-1:1,2)
    a($)
    //
    x='test'
    x([1 1;1 1;1 1])
    //
    b=[1/%s,(%s+1)/(%s-1)]
    b(1,1)
    b(1,$)
    b(2) // the numerator
    // LIST OR TLIST CASE
    l=list(1,'qwerw',%s)
    l(1)
    [a,b]=l([3 2])
    l($)
    x=tlist(l(2:3)) //form a tlist with the last 2 components of l
    //
    dts=list(1,tlist(['x';'a';'b'],10,[2 3]));
    dts(2)('a')
    dts(2)('b')(1,2)
    [a,b]=dts(2)(['a','b'])

### See Also

`find`, `horner`, `parents`,