intersect elements or rows or columns met in both input arrays, without duplicates

## Syntax

                M = intersect(a, b)
                M = intersect(a, b, orient)
                [M, ka] = intersect(..)
                [M, ka, kb] = intersect(..)

## Arguments

a, b
  vectors, matrices or hypermatrices of booleans, encoded integers, real or complex numbers, or text. `a` and `b` must have the same datatype. For text inputs, UTF characters are accepted. Sparse numeric or boolean matrices are accepted : Either `a` or `b` or both `a` and `b` may be sparse.

orient
  flag with possible values : 1 or "r", 2 or "c". Can't be used if `a` or/and `b` is an hypermatrix.

M

  matrix of the same datatype as `a` and `b`.

  - Without `orient`: `M` is a row vector.
  - With `orient="r"|1`: `M` is a matrix stacking the common rows of `a` and `b`.
  - With `orient="c"|2`: `M` is a matrix stacking the common columns of `a` and `b`.

  `M` is sparse as soon as either `a` or `b` is sparse and none is empty.

ka
  Dense row vector of indices in `a`.

kb
  Dense row vector of indices in `b`.

## Description

`intersect(a,b)` returns a row vector of unique values present in both `a` and `b` arrays. Values are sorted in increasing order

- for complex numbers : par increasing magnitudes, then by increasing phases
- for text : in alphabetical order.

Two NaN elements are always considered as different. So NaN or rows or columns having NaN will never be in the result `M`.

`[M, ka, kb] = intersect(a,b)` additionally returns the vectors `ka` and `kb` of indices in `a` and `b` of selected components firstly met, such that `M=a(ka)` and `M=b(kb)`.

### Common rows or columns

When the `orient` argument is provided, the comparison is performed between the rows of `a` and `b` -- each one being considered as a whole --, or between their columns.

`intersect(a,b,"r")` or `intersect(a,b,1)` will return the matrix of stacked unduplicated rows met in both `a` and `b`, sorted in lexicographic ascending order. If `a` and `b` don't have the same number of columns, [] is returned without comparing the values.

`[M,ka,kb] = intersect(a,b,"r")` additionally returns the vectors `ka` and `kb` of the minimal indices of common rows, respectively in `a` and `b`, such that `M=a(ka,:)` and `M=b(kb,:)`.

`intersect(a,b,"c")` or `intersect(a,b,2)` does the same for columns.

## Examples

    A = grand(3, 3, "uin", 0, 9)
    B = grand(2, 4, "uin", 0, 9)
    intersect(A, B)
    [N, ka, kb] = intersect(A,B);
    ka, kb

    --> A = grand(3, 3, "uin", 0, 9)
     A  =
       0.   6.   4.
       6.   6.   6.
       2.   7.   9.

    --> B = grand(2, 4, "uin", 0, 9)
     B  =
       1.   8.   0.   2.
       6.   2.   2.   1.

    --> intersect(A, B)
     ans  =
       0.   2.   6.

    --> [N, ka, kb] = intersect(A,B);
    --> ka, kb
     ka  =
       1.   3.   2.
     kb  =
       5.   4.   2.

In the above example, note that 6 is met four times in A, at indices [2 4 5 8]. Only the minimal index 2 is returned in ka. Same situation for 2 in B.

NaN values can never be in the result:

    %nan == %nan
    intersect([1 -2 %nan 3 6], [%nan 1:3])

    --> %nan == %nan
     ans  =
      F

    --> intersect([1 -2 %nan 3 6], [%nan 1:3])
     ans  =
       1.   3.

intersect() can also process some characters or some texts. Since Scilab is great with UTF characters, here is an example with some Arabic contents, getting characters present in both sentences:

    A = strsplit("هو برنامج علمي كبير ""Scilab""")'
    B = strsplit("فهو حر ومفتوح")'
    intersect(A,B)

    --> A = strsplit("هو برنامج علمي كبير ""Scilab""")'
     A  =
    !ه  و     ب  ر  ن  ا  م  ج     ع  ل  م  ي     ك  ب  ي  ر     "  S  c  i  l  a  b  "  !

    --> B = strsplit("فهو حر ومفتوح")'
     B  =
    !ف  ه  و     ح  ر     و  م  ف  ت  و  ح  !

    --> intersect(A,B)
     ans  =
    !   ر  م  ه  و  !

Column-wise or Row-wise processing of two matrices: Here we process 2 matrices of signed 1-byte integers, and get the common columns:

    A = int8(grand(3,5,"uin",0,1))
    B = int8(grand(3,9,"uin",0,1))
    [M,ka,kb] = intersect(A, B, "c");
    M, ka, kb

    --> A = int8(grand(3,5,"uin",0,1))
     A  =
      0  0  1  1  1
      0  0  1  1  0
      0  0  0  0  1

    --> B = int8(grand(3,9,"uin",0,1))
     B  =
      1  0  1  1  1  0  1  1  1
      1  0  0  1  1  1  0  0  0
      1  0  1  0  1  1  1  0  0

    --> [M,ka,kb] = intersect(A, B, "c");
    --> M, ka, kb
     M  =
      0  1  1
      0  0  1
      0  1  0

     ka  =
       1.   5.   3.

     kb  =
       2.   3.   4.

`intersect()` for booleans is mainly useful with the "r" or "c" option. Here is an example with a sparse boolean matrix:

    [F, T] = (%f, %t);
    A = [F F T F T F ; T F F T T T ; T T F T F F]
    B = [F T F T F F ; T F F F T F ; F T F F T F]
    [M,ka,kb] = intersect(A, sparse(B), "c");
    issparse(M), full(M), ka, kb

    --> A = [F F T F T F ; T F F T T T ; T T F T F F]
     A  =
      F F T F T F
      T F F T T T
      T T F T F F

    --> B = [F T F T F F ; T F F F T F ; F T F F T F]
     B  =
      F T F T F F
      T F F F T F
      F T F F T F

    --> [M,ka,kb] = intersect(A, sparse(B), "c");
    --> issparse(M), full(M), ka, kb
     ans  =
      T

     ans  =
      F F T
      T T F
      F T F

     ka  =
       6.   1.   3.

     kb  =
       1.   5.   4.

## See also

- members
- unique
- gsort
- union

## History

6.1.0 Complex numbers are now accepted.
6.1.1 Sparse matrices are now accepted (numbers or booleans).