* Bug #12705 fixed - Elementary_functions & m2sci: members() function
[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) 2009 - Université du Maine - Samuel Gougeon
5  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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="fr">
14     <refnamediv>
15         <refname>members</refname>
16         <refpurpose>returns vectors of indexes corresponding to the common values of two matrices
17         </refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>[nb [,loc]] = members(A, S [,last])</synopsis>
22     </refsynopsisdiv>
23     <refsection>
24         <title>Arguments</title>
25         <variablelist>
26             <varlistentry>
27                 <term>A</term>
28                 <listitem>
29                     <para>matrix or hypermatrix of booleans, integers, reals, complexes, polynomials or strings</para>
30                 </listitem>
31             </varlistentry>
32             <varlistentry>
33                 <term>S</term>
34                 <listitem>
35                     <para>
36                         matrix or hypermatrix of same datatype as <literal>A</literal>
37                     </para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>last</term>
42                 <listitem>
43                     <para>scalar boolean</para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>nb</term>
48                 <listitem>
49                     <para>
50                         matrix of reals, same size as <literal>A</literal>
51                     </para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>loc</term>
56                 <listitem>
57                     <para>
58                         matrix of reals, same size as <literal>A</literal>
59                     </para>
60                 </listitem>
61             </varlistentry>
62         </variablelist>
63     </refsection>
64     <refsection>
65         <title>Description</title>
66         <para>
67             <literal>nb = members(A, S)</literal> returns the number of occurrences of <literal>A</literal> in <literal>S</literal>.
68             After <literal>[nb, loc] = members(A, S, last)</literal>,
69             <literal>loc(i, j)</literal>contains the linear index in <literal>S</literal> of the first occurrence of <literal>A(i, j)</literal>.
70             If <literal>last==%t</literal>, the index of the last occurrence is returned instead.
71             <literal>loc(i, j)</literal> returns zero if <literal>A(i, j)</literal> is not found.
72             <literal>%inf</literal> and <literal>-%inf</literal> values are supported either in <literal>A</literal> as well as in <literal>S</literal>.
73             <literal>%nan</literal> are only supported in <literal>A</literal>.
74         </para>
75         <para>
76             When <literal>A</literal> is a vector of doubles or integers and <literal>S</literal> is a vector of doubles or integers in strictly increasing order,
77             <literal>dsearch(A, S, "d")</literal> is preferred over <literal>members(A, S)</literal>.
78         </para>
79     </refsection>
80     <refsection>
81         <title>Examples</title>
82         <programlisting role="example"><![CDATA[
83 A = [1 8 4 5 2 1];
84 S = [9 7 4 2 1 4];
85
86 [nb, loc] = members(A, S, %t)
87 // Returns nb  = [1 0 2 0 1 1] because, for instance, the third element of A (which is 4) appears twice in S.
88 // And     loc = [5 0 6 0 4 5] because the last occurrence in S of the third element of A (which is 4) is in sixth position
89
90 [nb, loc] = members(A, S, %f)
91 // Returns loc = [5 0 3 0 4 5] because the first occurrence in S of the third element of A (which is 4) is in third position
92
93 // With hypermatrices. From previous A and S:
94 A = matrix(A, [3 1 2]);
95 S = matrix(S, [3 1 2]);
96 [nb, loc] = members(A, S, %T)
97
98 // With integers:
99 A = int8(grand(3, 2, "uin", -5, 5));
100 S = int8(grand(4, 4, "uin", -5, 5));
101 [nb, loc] = members(A, S)
102
103 // With polynomials (complex coefficients are accepted):
104 z = %z;
105 A = [z (1-z)^2 ; -4 %i*z ];
106 S = [2  %i*z -z  3-z  z  z^3 z];
107 [nb, loc] = members(A, S)
108
109 // With text:
110 A = [ "Hi" "Hu" "Allo"];
111 S = [ "Hello" "Bonjour" "Allo"
112       "Holà"  "Allo"  "Hallo"
113       "Hi"    "Hé"    "Salud" ];
114 [nb, loc] = members(A, S, %t)
115 ]]></programlisting>
116     </refsection>
117     <refsection role="see also">
118         <title>See Also</title>
119         <simplelist type="inline">
120             <member>
121                 <link linkend="dsearch">dsearch</link>
122             </member>
123             <member>
124                 <link linkend="intersect">intersect</link>
125             </member>
126             <member>
127                 <link linkend="unique">unique</link>
128             </member>
129             <member>
130                 <link linkend="gsort">gsort</link>
131             </member>
132             <member>
133                 <link linkend="union">union</link>
134             </member>
135         </simplelist>
136     </refsection>
137     <refsection>
138         <title>History</title>
139         <revhistory>
140             <revision>
141                 <revnumber>5.5.0</revnumber>
142                 <revremark>Function members introduced.</revremark>
143             </revision>
144         </revhistory>
145     </refsection>
146 </refentry>