<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2020 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
          xmlns:scilab="http://www.scilab.org" xml:id="find" xml:lang="pt">
    <refnamediv>
        <refname>find</refname>
        <refpurpose>
            fornece os índices de elementos %T ou diferentes de zero
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</title>
        <synopsis>
            ii = find(x)
            [i1,i2,..] = find(x)
            .. = find(x, nmax)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>
                        vetor, matriz ou hipermatriz de booleanos ou de números.
                        Todos os números diferentes de zero são considerados como %T.
                        Matrizes esparsas são aceitas.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>nmax</term>
                <listitem>
                    <para>um inteiro fornecendo o número máximo de índices a serem
                        retornados. o valor padrão é -1, que significa "todos". Esta opção
                        pode ser usada por eficiência, para evitar uma busca por todos os
                        índices.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ii</term>
                <listitem>
                    <para>
                        vetor de linha de índices linearizados de elementos %T ou diferentes
                        de zero, ou matriz vazia [].
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>i1, i2, ..</term>
                <listitem>
                    <para>
                        vetores de linha de índices direcionais, ou matriz vazia [].
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>
            Se <literal>x</literal> é uma matriz booleana,
        </para>
        <para>
            <literal>ii=find(x)</literal> retorna o vetor de índices
            <literal>i</literal> para os quais <literal>x(i)</literal> é "true"
            ("verdadeiro").Se nenhum elemento "true" for encontrado, retorna uma
            matriz vazia.
        </para>
        <para>
            <literal>[i1,i2,..]=find(x)</literal> retorna vetores de índices
            <literal>i1</literal> (para linhas) e <literal>i2</literal> (para
            colunas),... tais que <literal>x(i1(n),i2(n),..)</literal> ié "true"
            ("verdadeiro"). Se nenhum elemento "true" for encontrado, retorna matrizes
            vazias em <literal>i1</literal>, <literal>i2</literal>, ...
        </para>
        <para>
            Se <literal>x</literal> é uma matriz ou hipermatriz padrão
            <literal>find(x)</literal> é interpretado como
            <literal>find(x&lt;&gt;0)</literal>
        </para>
        <para>
            <literal>find([])</literal> retorna <literal>[]</literal>
        </para>
    </refsection>
    <refsection>
        <title>Exemplos</title>
        <para>
            With input booleans:
        </para>
        <programlisting role="example"><![CDATA[
A = [%F %T %T %F ; %T %F %F %T]
find(A)
find(A,2)
      ]]></programlisting>
    <screen><![CDATA[
--> 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.
]]></screen>
    <para>
        With input numbers:
    </para>
        <programlisting role="example"><![CDATA[
B = [0 -1 0 3 ; 0 -1 -0.4 0]
find(B)
[i, j] = find(B);
[i' j']
      ]]></programlisting>
    <screen><![CDATA[
--> 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.
]]></screen>
    <para>
        With an input hypermatrix of numbers:
    </para>
        <programlisting role="example"><![CDATA[
E = grand(2,5,2,"uin",1,6)
find(E < 4)
      ]]></programlisting>
    <screen><![CDATA[
--> 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.
]]></screen>
    <para>
         With an input numerical or boolean sparse matrix:
    </para>
        <programlisting role="example"><![CDATA[
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)
      ]]></programlisting>
    <screen><![CDATA[
--> 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.
]]></screen>
    <para>
        With the result of a boolean element-wise condition on texts
    </para>
        <programlisting role="example"><![CDATA[
beers = ["Desperados", "Leffe", "Kronenbourg", "Heineken"];
find(beers == "Leffe")
find(beers == "1664")
      ]]></programlisting>
    <screen><![CDATA[
--> find(beers == "Leffe")
 ans  =
   2.

--> find(beers == "1664")
 ans  =
    []
]]></screen>
    <para>
        Addressing selected elements:
    </para>
        <programlisting role="example"><![CDATA[
// 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
      ]]></programlisting>
    <screen><![CDATA[
--> // 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.
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>Ver Também</title>
        <simplelist type="inline">
            <member>
                <link linkend="vectorfind">vectorfind</link>
            </member>
            <member>
                <link linkend="grep">grep</link>
            </member>
            <member>
                <link linkend="findobj">findobj</link>
            </member>
            <member>
                <link linkend="boolean">boolean</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
