[doc] find() page improved
[scilab.git] / scilab / modules / elementary_functions / help / pt_BR / searchandsort / find.xml
index 4670790..8672870 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * 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>