scilab/modules/elementary_functions/help/en_US/searchandsort/find.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   4  * Copyright (C) INRIA
   5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   6  * Copyright (C) 2020 - Samuel GOUGEON
   7  *
   8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
   9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  10  * This file was originally licensed under the terms of the CeCILL v2.1,
  11  * and continues to be available under such terms.
  12  * For more information, see the COPYING file which you should have received
  13  * along with this program.
  14  *
  15  -->
  16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
  18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
  19           xml:lang="en" xml:id="find">
  20     <refnamediv>
  21         <refname>find</refname>
  22         <refpurpose>gives the indices of %T or non-zero elements</refpurpose>
  23     </refnamediv>
  24     <refsynopsisdiv>
  25         <title>Syntax</title>
  26         <synopsis>
  27             ii = find(x)
  28             [i1,i2,..] = find(x)
  29             .. = find(x, nmax)
  30         </synopsis>
  31     </refsynopsisdiv>
  32     <refsection>
  33         <title>Arguments</title>
  34         <variablelist>
  35             <varlistentry>
  36                 <term>x</term>
  37                 <listitem>
  38                     <para>
  39                         Vector, matrix, or hypermatrix of booleans or of numbers.
  40                         All non-zero numbers are considered as %T.
  41                         Sparse matrices are accepted.
  42                     </para>
  43                 </listitem>
  44             </varlistentry>
  45             <varlistentry>
  46                 <term>nmax</term>
  47                 <listitem>
  48                     <para>
  49                         an integer giving the maximum number of indices to return.
  50                         The default value is -1 which stands for "all".
  51                         This option can be used for efficiency, to avoid searching all indices.
  52                     </para>
  53                 </listitem>
  54             </varlistentry>
  55             <varlistentry>
  56                 <term>ii</term>
  57                 <listitem>
  58                     <para>
  59                         row vector of linearized indices of %T or non-zero elements, or empty matrix []
  60                     </para>
  61                 </listitem>
  62             </varlistentry>
  63             <varlistentry>
  64                 <term>i1, i2, ..</term>
  65                 <listitem>
  66                     <para>
  67                         row vectors of directional indices, or empty matrix []
  68                     </para>
  69                 </listitem>
  70             </varlistentry>
  71         </variablelist>
  72     </refsection>
  73     <refsection>
  74         <title>Description</title>
  75         <para>
  76             If <literal>x</literal> is a boolean matrix,
  77         </para>
  78         <para>
  79             <literal>ii=find(x)</literal> returns the vector
  80             of indices <literal>i</literal> for which <literal>x(i)</literal> is "true". If no true element
  81             found find returns an empty matrix.
  82         </para>
  83         <para>
  84             <literal>[i1,i2,..]=find(x)</literal> returns vectors of indices <literal>i1</literal> (for rows) and <literal>i2</literal> (for columns),..
  85             such that <literal>x(i1(n),i2(n),..)</literal> is "true". If no true element
  86             found find returns  empty matrices in <literal>i1</literal>,
  87             <literal>i2</literal>, ...
  88         </para>
  89         <para>
  90             if <literal>x</literal> is a standard matrix or hypermatrix <literal>find(x)</literal> is interpreted as
  91             <literal>find(x&lt;&gt;0)</literal>
  92         </para>
  93         <para>
  94             <literal>find([])</literal> returns <literal>[]</literal>
  95         </para>
  96     </refsection>
  97     <refsection>
  98         <title>Examples</title>
  99         <para>
 100             With input booleans:
 101         </para>
 102         <programlisting role="example"><![CDATA[
 103 A = [%F %T %T %F ; %T %F %F %T]
 104 find(A)
 105 find(A,2)
 106       ]]></programlisting>
 107     <screen><![CDATA[
 108 --> A = [%F %T %T %F ; %T %F %F %T]
 109  A  =
 110   F T T F
 111   T F F T
 112
 113 --> find(A)
 114  ans  =
 115    2.   3.   5.   8.
 116
 117 --> find(A,2)
 118  ans  =
 119    2.   3.
 120 ]]></screen>
 121     <para>
 122         With input numbers:
 123     </para>
 124         <programlisting role="example"><![CDATA[
 125 B = [0 -1 0 3 ; 0 -1 -0.4 0]
 126 find(B)
 127 [i, j] = find(B);
 128 [i' j']
 129       ]]></programlisting>
 130     <screen><![CDATA[
 131 --> B = [0 -1 0 3 ; 0 -1 -0.4 0]
 132  B  =
 133    0.  -1.   0.    3.
 134    0.  -1.  -0.4   0.
 135
 136 --> find(B)
 137  ans  =
 138    3.   4.   6.   7.
 139
 140 --> [i, j] = find(B);
 141 --> [i' j']
 142  ans  =
 143    1.   2.
 144    2.   2.
 145    2.   3.
 146    1.   4.
 147 ]]></screen>
 148     <para>
 149         With an input hypermatrix of numbers:
 150     </para>
 151         <programlisting role="example"><![CDATA[
 152 E = grand(2,5,2,"uin",1,6)
 153 find(E < 4)
 154       ]]></programlisting>
 155     <screen><![CDATA[
 156 --> E = grand(2,5,2,"uin",1,6)
 157  E  =
 158 (:,:,1)
 159    1.   6.   5.   5.   4.
 160    6.   5.   3.   4.   4.
 161 (:,:,2)
 162    2.   4.   3.   6.   5.
 163    5.   6.   6.   6.   4.
 164
 165 --> find(E < 4)
 166  ans  =
 167    1.   6.   11.   15.
 168 ]]></screen>
 169     <para>
 170          With an input numerical or boolean sparse matrix:
 171     </para>
 172         <programlisting role="example"><![CDATA[
 173 C = [0  3  7  0  9  0
 174      0  4  0  0  5  0
 175      6  0  1  0  3  8
 176     ];
 177 C = sparse(C);
 178 find(C)
 179 find(C, 4)
 180
 181 // With input boolean sparse
 182 D = C > 4
 183 full(D)
 184 find(D)
 185       ]]></programlisting>
 186     <screen><![CDATA[
 187 --> C = sparse(C);
 188 --> find(C)
 189  ans  =
 190     3.    4.    5.    7.    9.    13.    14.    15.    18.
 191
 192 -->find(C, 4)
 193  ans  =
 194     3.    4.    5.    7.
 195
 196 --> // With input boolean sparse
 197 --> D = C > 4
 198  D  =
 199 (  3,  6) sparse boolean matrix
 200 (  1,  3)   T
 201 (  1,  5)   T
 202 (  2,  5)   T
 203 (  3,  1)   T
 204 (  3,  6)   T
 205
 206 --> full(D)
 207  ans  =
 208   F F T F T F
 209   F F F F T F
 210   T F F F F T
 211
 212 -->find(D)
 213  ans  =
 214     3.    7.    13.    14.    18.
 215 ]]></screen>
 216     <para>
 217         With the result of a boolean element-wise condition on texts:
 218     </para>
 219         <programlisting role="example"><![CDATA[
 220 beers = ["Desperados", "Leffe", "Kronenbourg", "Heineken"];
 221 find(beers == "Leffe")
 222 find(beers == "1664")
 223       ]]></programlisting>
 224     <screen><![CDATA[
 225 --> find(beers == "Leffe")
 226  ans  =
 227    2.
 228
 229 --> find(beers == "1664")
 230  ans  =
 231     []
 232 ]]></screen>
 233     <para>
 234         Addressing selected elements:
 235     </para>
 236         <programlisting role="example"><![CDATA[
 237 // a) Through their linearized indices:
 238 H = [ 0  -2  -8  4  -5  -1
 239      -2   2  -9  5   0   1
 240     ];
 241 L = H;
 242 L(find(L < 0)) = -10
 243
 244 // b) Directly through the array of their boolean status:
 245 L = H;
 246 L(L < 0) = -10
 247       ]]></programlisting>
 248     <screen><![CDATA[
 249 --> // a) Through their linearized indices:
 250 --> H = [ 0  -2  -8  4  -5  -1
 251   >      -2   2  -9  5   0   1
 252   >     ];
 253 --> L = H;
 254 --> L(find(L < 0)) = -10
 255  L  =
 256    0.   -10.  -10.   4.  -10.  -10.
 257   -10.   2.   -10.   5.   0.    1.
 258
 259 --> // b) Directly through the array of their boolean status:
 260 --> L = H;
 261 --> L(L < 0) = -10
 262  L  =
 263    0.   -10.  -10.   4.  -10.  -10.
 264   -10.   2.   -10.   5.   0.    1.
 265 ]]></screen>
 266     </refsection>
 267     <refsection role="see also">
 268         <title>See also</title>
 269         <simplelist type="inline">
 270             <member>
 271                 <link linkend="vectorfind">vectorfind</link>
 272             </member>
 273             <member>
 274                 <link linkend="grep">grep</link>
 275             </member>
 276             <member>
 277                 <link linkend="findobj">findobj</link>
 278             </member>
 279             <member>
 280                 <link linkend="boolean">boolean</link>
 281             </member>
 282         </simplelist>
 283     </refsection>
 284 </refentry>