Elementary_functions: members() improved
[scilab.git] / scilab / modules / elementary_functions / help / en_US / setoperations / members.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) 2013 - Samuel GOUGEON
5  * Copyright (C) 2009 - Université du Maine - Samuel GOUGEON
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <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="members" xml:lang="en">
15     <refnamediv>
16         <refname>members</refname>
17         <refpurpose>count (and locate) in an array each element or row or column of another array
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>
23             [nb [,loc]] = members(N, H)
24             [nb [,loc]] = members(N, H, "last")
25             [nb [,loc]] = members(N, H, "rows"|"cols")
26             [nb [,loc]] = members(N, H, "rows"|"cols", "last")
27             [nb [,loc]] = members(N, H, "rows"|"cols", "shuffle")
28             [nb [,loc]] = members(N, H, "rows"|"cols", "shuffle", "last")
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>N</term>
36                 <listitem>
37                     <para>
38                         Needles: matrix or hypermatrix of booleans, integer-encoded numbers, real or complex decimal numbers, polynomials or texts. In "rows" or "cols" mode, no hypermatrix is accepted. A given value (or row or column) may appear several times in <literal>N</literal>.
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>H</term>
44                 <listitem>
45                     <para>
46                         Haystack: matrix or hypermatrix of same data type as <literal>N</literal>. In "rows" or "cols" mode, no hypermatrix is accepted, and <literal>N</literal> and <literal>H</literal> must have respectively the same number of columns or rows.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>Options:</term>
52                 <listitem>
53                     <para>From one to three options may be specified in any order:
54                         <variablelist>
55                             <varlistentry>
56                                 <term>"last"</term>
57                                 <listitem>
58                                     <para>
59                                         when the location in <literal>H</literal> of needles from <literal>N</literal> is querried through <literal>loc</literal>, by default the position of the first respective occurrences in <literal>H</literal> are returned. If <literal>"last"</literal> is specified, the position of the last occurrences in <literal>H</literal> are returned instead.
60                                     </para>
61                                 </listitem>
62                             </varlistentry>
63                             <varlistentry>
64                                 <term>"rows", "cols"</term>
65                                 <listitem>
66                                     <para>
67                                         By default, each element <literal>N(i, j, ...)</literal> of <literal>N</literal> is considered as a needle to search in <literal>H</literal>. If <literal>"rows"</literal> is specified, each row of <literal>N</literal> is considered as a needle -- as a whole --, and is searched among rows of <literal>H</literal>. The same applies between columns of <literal>N</literal> and <literal>H</literal> if <literal>"cols"</literal> is used.
68                                     </para>
69                                 </listitem>
70                             </varlistentry>
71                             <varlistentry>
72                                 <term>"shuffle"</term>
73                                 <listitem>
74                                     <para>
75                                         In <literal>"rows"</literal> or <literal>"cols"</literal> mode, by default the order of components of a row/column is considered: for instance, <literal>[ 7 3 5 ]</literal> in <literal>N</literal> does not match <literal>[3 5 7]</literal> in <literal>H</literal>. When <literal>"shuffle"</literal> is specified, any permutation of --say--<literal>[3 5 7]</literal> will be considered as matching a <literal>[3 5 7]</literal> row of <literal>N</literal>. This option is ignored for polynomials.
76                                     </para>
77                                 </listitem>
78                             </varlistentry>
79                         </variablelist>
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>nb</term>
85                 <listitem>
86                     <para>
87                         In normal mode: <literal>nb(i, j, ...)</literal> returns (as reals) the number of occurrences in <literal>H</literal> of <literal>N(i, j, ...)</literal>. <literal>nb</literal> and <literal>N</literal> have the same format. If <literal>H</literal> is empty, a matrix of zeros is returned. If <literal>N</literal> is empty, the empty matrix <literal>[]</literal> is returned.
88                     </para>
89                     <para>
90                         In <literal>"rows"</literal> or <literal>"cols"</literal> mode: <literal>nb</literal> is a row of reals with as many components as <literal>N</literal> has rows/columns. <literal>nb(i)</literal> returns the number of occurrences in <literal>H(., :)</literal> of <literal>N(i, :)</literal> (or of <literal>N(:, i)</literal> in <literal>H(:, .)</literal> ).
91                     </para>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>loc</term>
96                 <listitem>
97                     <para>
98                         In normal mode: <literal>loc</literal> and <literal>N</literal> have the same format. <literal>loc(i, j, ...)</literal> returns the smallest linearized index in <literal>H</literal> where <literal>N(i, j, ...)</literal> occurs. If the <literal>"last"</literal> flag is used, the greatest linearized index is returned instead. If <literal>N(i, j, ...)</literal> in not found in <literal>H</literal>, <literal>loc(i, j, ...)</literal> is set to <literal>0</literal>.
99                     </para>
100                     <para>
101                         In <literal>"rows"</literal> or <literal>"cols"</literal> mode: <literal>loc</literal> is a row of reals with as many components as <literal>N</literal> has respectively rows or columns. <literal>loc(i)</literal> returns the index of the first line <literal>H(loc(i), :)</literal> matching <literal>N(i, :)</literal> (or the index of the first column <literal>H(:, loc(i))</literal> matching <literal>N(:, i)</literal>). If the <literal>"shuffle"</literal> flag is additionnaly specified, the order of components along the rows/columns is not considered.
102                     </para>
103                 </listitem>
104             </varlistentry>
105         </variablelist>
106     </refsection>
107     <refsection>
108         <title>Description</title>
109         <para>
110             <literal>nb = members(N, H [,"rows"|"cols"])</literal> returns the number of occurrences of each component or row or column of <literal>N</literal> found in <literal>H</literal>. If no match is found for an element, 0 is returned for it.
111             The index in <literal>H</literal> of the first (default) or <literal>"last"</literal> occurrence of <literal>N(i,j,...)</literal> can be querried through a second optional output <literal>loc</literal>.
112             If matching <literal>"rows"</literal> or <literal>"cols"</literal> are searched for, matches can ignore the order of their elements, by using the option <literal>"shuffle"</literal>.
113         </para>
114         <para>
115             <literal>%inf</literal> and <literal>-%inf</literal> values are supported in <literal>N</literal> as well as in <literal>H</literal>.
116             In normal mode, <literal>%nan</literal> are supported in <literal>N</literal> but not in <literal>H</literal>. In <literal>"rows"</literal> or <literal>"cols"</literal> modes, <literal>%nan</literal> are supported everywhere.
117         </para>
118         <para>
119             In normal element-wise mode, members(..) uses <link type="scilab" linkend="dsearch">dsearch(..)</link> to fastly proceed with booleans, integer-encoded numbers (any length 8-16-32 bits signed or not), and real numbers. For complex numbers, texts, and polynomials, a slower and more memory-consuming algorithm is used. For better performances with these types of data, for big <literal>N</literal> or/and <literal>H</literal>, the user may priorly increase the <link type="scilab" linkend="scilab.help/stacksize">stacksize(..)</link>. For long calculations, a progression bar is displayed.
120         </para>
121     </refsection>
122     <refsection>
123         <title>Examples</title>
124         <programlisting role="example"><![CDATA[
125 N = [1 8 4 5 2 1];
126 H = [9 7 4 2 1 4];
127
128 [nb, loc] = members(N, H, "last")
129 // Returns nb  = [1 0 2 0 1 1]: for instance, 4 appears twice in H.
130 // And     loc = [5 0 6 0 4 5]: the last occurrence of 4 is in sixth position in H
131
132 [nb, loc] = members(N, H)
133 // Returns loc = [5 0 3 0 4 5]: the 1st occurrence of 4 is in third position in H
134
135 // With hypermatrices. From previous N and H:
136 N = matrix(N, [3 1 2]);
137 H = matrix(H, [3 1 2]);
138 [nb, loc] = members(N, H, "last")
139
140 // With integers:
141 N = int8(grand(3, 2, "uin", -5, 5));
142 H = int8(grand(4, 4, "uin", -5, 5));
143 [nb, loc] = members(N, H)
144
145 // With polynomials (complex coefficients are accepted):
146 z = %z;
147 N = [z (1-z)^2 ; -4 %i*z ];
148 H = [2  %i*z -z  3-z  z  z^3 z];
149 [nb, loc] = members(N, H)
150
151 // With text:
152 N = [ "Hi" "Hu" "Allo"];
153 H = [ "Hello" "Bonjour" "Allo"
154       "Holà"  "Allo"  "Hallo"
155       "Hi"    "Hé"    "Salud" ];
156 [nb, loc] = members(N, H, "last")
157
158 // By rows:
159  H = [
160   3  3  0
161   4  1  0
162   2  0  3
163   0  1  4
164   3  4  3
165   0  4  1
166   3  1  0
167   ];
168  N = [
169   1  2  3
170   0  1  4
171   3  0  3
172   4  1  0
173   2  0  2
174   ];
175  N, H
176  [nb, loc] = members(N, H, "rows")
177  [nb, loc] = members(N, H, "rows","last")
178  [nb, loc] = members(N, H, "rows","shuffle") // [4 1 0], [0 1 4] and [0 4 1] are considered the same
179
180 // By columns: From N and H defined above:
181  N = N.', H = H.'
182  [nb, loc] = members(N, H, "cols", "shuffle")
183
184 ]]></programlisting>
185     </refsection>
186     <refsection role="see also">
187         <title>See Also</title>
188         <simplelist type="inline">
189             <member>
190                 <link type="scilab" linkend="scilab.help/dsearch">dsearch</link>
191             </member>
192             <member>
193                 <link type="scilab" linkend="scilab.help/intersect">intersect</link>
194             </member>
195             <member>
196                 <link type="scilab" linkend="scilab.help/find">find</link>
197             </member>
198             <member>
199                 <link type="scilab" linkend="scilab.help/vectorfind">vectorfind</link>
200             </member>
201         </simplelist>
202     </refsection>
203     <refsection>
204         <title>History</title>
205         <revhistory>
206             <revision>
207                 <revnumber>5.5.0</revnumber>
208                 <revremark>members() function introduced.</revremark>
209             </revision>
210         </revhistory>
211     </refsection>
212 </refentry>