<!--
* 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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="find">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
+ xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
+ xml:lang="en" xml:id="find">
<refnamediv>
<refname>find</refname>
- <refpurpose>find indices of boolean vector or matrix true elements</refpurpose>
+ <refpurpose>gives the indices of %T or non-zero elements</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Syntax</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>may be a boolean vector, a boolean matrix, a boolean
- hypermatrix, a "standard" matrix or hypermatrix
+ <para>
+ Vector, matrix, or hypermatrix of booleans or of numbers.
+ All non-zero numbers are considered as %T.
+ Sparse matrices are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>nmax</term>
<listitem>
- <para>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.</para>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ii</term>
+ <listitem>
+ <para>
+ row vector of linearized indices of %T or non-zero elements, or empty matrix []
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>ii, i1, i2, .. </term>
+ <term>i1, i2, ..</term>
<listitem>
- <para>integer vectors of indices or empty matrices</para>
+ <para>
+ row vectors of directional indices, or empty matrix []
+ </para>
</listitem>
</varlistentry>
</variablelist>
</refsection>
<refsection>
<title>Examples</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[
-beers=["Desperados", "Leffe", "Kronenbourg", "Heineken"];
-find(beers=="Leffe") // OK
-find(beers=="1664") // KO
-find(beers=="Foster") // KO
-beers=[beers, "Foster"]
-find(beers=="Foster") // OK
+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
-A=rand(1,20);
-w=find(A<0.4)
-A(w)
-w=find(A>100)
+--> full(D)
+ ans =
+ F F T F T F
+ F F F F T F
+ T F F F F T
-B=rand(1,20);
-w=find(B<0.4,2) //at most 2 returned values
+-->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
-H=rand(4,3,5); //an hypermatrix
-[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>See also</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>
projects / scilab.git / blobdiff