find gives the indices of %T or non-zero elements

## Syntax

                ii = find(x)
                [i1,i2,..] = find(x)
                .. = find(x, nmax)

## Arguments

x

  Vector, matrix, or hypermatrix of booleans or of numbers. All non-zero numbers are considered as %T. Sparse matrices are accepted.

nmax

  an integer giving the maximum number of indices to return. The default value is -1 which stands for "all". This option can be used for efficiency, to avoid searching all indices.

ii

  row vector of linearized indices of %T or non-zero elements, or empty matrix []

i1, i2, ..

  row vectors of directional indices, or empty matrix []

## Description

If `x` is a boolean matrix,

`ii=find(x)` returns the vector of indices `i` for which `x(i)` is "true". If no true element found find returns an empty matrix.

`[i1,i2,..]=find(x)` returns vectors of indices `i1` (for rows) and `i2` (for columns),.. such that `x(i1(n),i2(n),..)` is "true". If no true element found find returns empty matrices in `i1`, `i2`, ...

if `x` is a standard matrix or hypermatrix `find(x)` is interpreted as `find(x<>0)`

`find([])` returns `[]`

## Examples

With input booleans:

    A = [%F %T %T %F ; %T %F %F %T]
    find(A)
    find(A,2)

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

    --> find(A)
     ans  =
       2.   3.   5.   8.

    --> find(A,2)
     ans  =
       2.   3.

With input numbers:

    B = [0 -1 0 3 ; 0 -1 -0.4 0]
    find(B)
    [i, j] = find(B);
    [i' j']

    --> B = [0 -1 0 3 ; 0 -1 -0.4 0]
     B  =
       0.  -1.   0.    3.
       0.  -1.  -0.4   0.

    --> find(B)
     ans  =
       3.   4.   6.   7.

    --> [i, j] = find(B);
    --> [i' j']
     ans  =
       1.   2.
       2.   2.
       2.   3.
       1.   4.

With an input hypermatrix of numbers:

    E = grand(2,5,2,"uin",1,6)
    find(E < 4)

    --> E = grand(2,5,2,"uin",1,6)
     E  =
    (:,:,1)
       1.   6.   5.   5.   4.
       6.   5.   3.   4.   4.
    (:,:,2)
       2.   4.   3.   6.   5.
       5.   6.   6.   6.   4.

    --> find(E < 4)
     ans  =
       1.   6.   11.   15.

With an input numerical or boolean sparse matrix:

    C = [0  3  7  0  9  0
         0  4  0  0  5  0
         6  0  1  0  3  8
        ];
    C = sparse(C);
    find(C)
    find(C, 4)

    // With input boolean sparse
    D = C > 4
    full(D)
    find(D)

    --> C = sparse(C);
    --> find(C)
     ans  =
        3.    4.    5.    7.    9.    13.    14.    15.    18.

    -->find(C, 4)
     ans  =
        3.    4.    5.    7.

    --> // With input boolean sparse
    --> D = C > 4
     D  =
    (  3,  6) sparse boolean matrix
    (  1,  3)   T
    (  1,  5)   T
    (  2,  5)   T
    (  3,  1)   T
    (  3,  6)   T

    --> full(D)
     ans  =
      F F T F T F
      F F F F T F
      T F F F F T

    -->find(D)
     ans  =
        3.    7.    13.    14.    18.

With the result of a boolean element-wise condition on texts:

    beers = ["Desperados", "Leffe", "Kronenbourg", "Heineken"];
    find(beers == "Leffe")
    find(beers == "1664")

    --> find(beers == "Leffe")
     ans  =
       2.

    --> find(beers == "1664")
     ans  =
        []

Addressing selected elements:

    // a) Through their linearized indices:
    H = [ 0  -2  -8  4  -5  -1
         -2   2  -9  5   0   1
        ];
    L = H;
    L(find(L < 0)) = -10

    // b) Directly through the array of their boolean status:
    L = H;
    L(L < 0) = -10

    --> // a) Through their linearized indices:
    --> H = [ 0  -2  -8  4  -5  -1
      >      -2   2  -9  5   0   1
      >     ];
    --> L = H;
    --> L(find(L < 0)) = -10
     L  =
       0.   -10.  -10.   4.  -10.  -10.
      -10.   2.   -10.   5.   0.    1.

    --> // b) Directly through the array of their boolean status:
    --> L = H;
    --> L(L < 0) = -10
     L  =
       0.   -10.  -10.   4.  -10.  -10.
      -10.   2.   -10.   5.   0.    1.

## See also

- vectorfind
- grep
- findobj
- boolean