<!--
* Scilab ( http://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.
* 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">
+<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>encontra índices de elementos verdadeiros em uma matriz ou
- vetor de booleanos
+ <refpurpose>
+ fornece os índices de elementos %T ou diferentes de zero
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Seqüência de Chamamento</title>
- <synopsis>[ii]=find(x [,nmax])
- [i1,i2,..]=find(x [,nmax])
+ <synopsis>
+ ii = find(x)
+ [i1,i2,..] = find(x)
+ .. = find(x, nmax)
</synopsis>
</refsynopsisdiv>
<refsection>
<varlistentry>
<term>x</term>
<listitem>
- <para>pode ser um vetor, matriz ou hipermatriz de booleanos, uma
- matriz ou hipermatriz "padrão".
+ <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>
</listitem>
</varlistentry>
<varlistentry>
- <term>ii, i1, i2, ..</term>
+ <term>ii</term>
<listitem>
- <para>vetores de índices inteiros ou matrizes vazias</para>
+ <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>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[
-A=rand(1,20);
-w=find(A<0.4)
-A(w)
-w=find(A>100)
+beers = ["Desperados", "Leffe", "Kronenbourg", "Heineken"];
+find(beers == "Leffe")
+find(beers == "1664")
+ ]]></programlisting>
+ <screen><![CDATA[
+--> find(beers == "Leffe")
+ ans =
+ 2.
-B=rand(1,20);
-w=find(B<0.4,2) //no máximo dois valores retornados
+--> 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
-H=rand(4,3,5); //uma hipermatriz
-[i,j,k]=find(H>0.9)
+// 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.
-H(i(1),j(1),k(1))
- ]]></programlisting>
+--> // 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="boolean">boolean</link>
+ <link linkend="vectorfind">vectorfind</link>
</member>
<member>
- <link linkend="extraction">extraction</link>
+ <link linkend="grep">grep</link>
</member>
<member>
- <link linkend="insertion">insertion</link>
+ <link linkend="findobj">findobj</link>
</member>
<member>
- <link linkend="vectorfind">vectorfind</link>
+ <link linkend="boolean">boolean</link>
</member>
</simplelist>
</refsection>