d263467455a38f5f9abed10c81ba8a5561018d32
[scilab.git] / scilab / modules / elementary_functions / help / en_US / setoperations / intersect.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) 2008 - INRIA
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="intersect" xml:lang="en">
14     <refnamediv>
15         <refname>intersect</refname>
16         <refpurpose>returns the vector of common values of two
17             vectors
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>[v [,ka,kb]]=intersect(a,b)</synopsis>
23         <synopsis>[v [,ka,kb]]=intersect(a,b,orient)</synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>a</term>
30                 <listitem>
31                     <para>vector of numbers or strings</para>
32                 </listitem>
33             </varlistentry>
34             <varlistentry>
35                 <term>b</term>
36                 <listitem>
37                     <para>vector of numbers or strings</para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>orient</term>
42                 <listitem>
43                     <para>flag with possible values : 1 or "r", 2 or "c"</para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>v</term>
48                 <listitem>
49                     <para>row vector of numbers or strings</para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>ka</term>
54                 <listitem>
55                     <para>row vector of integers</para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>kb</term>
60                 <listitem>
61                     <para>row vector of integers</para>
62                 </listitem>
63             </varlistentry>
64         </variablelist>
65     </refsection>
66     <refsection>
67         <title>Description</title>
68         <para>
69             <literal>intersect(a,b)</literal> returns a sorted row vector of
70             common values of two vectors of <literal>a</literal> and
71             <literal>b</literal>.
72         </para>
73         <para>
74             <literal>[v,ka,kb]=intersect(a,b)</literal> also returns index
75             vectors <literal>ka</literal> and <literal>kb</literal> such that
76             <literal>v=a(ka)</literal> and <literal>v=b(kb)</literal>.
77         </para>
78         <para>
79             <literal>intersect(a,b,"r")</literal> or
80             <literal>intersect(a,b,1)</literal>returns the matrix formed by the
81             intersection of the unique rows of <literal>a</literal> and
82             <literal>b</literal> sorted in lexicographic ascending order. In this case
83             matrices <literal>a</literal> and <literal>b</literal> must have the same
84             number of columns.
85         </para>
86         <para>
87             <literal>[v,ka,kb]=intersect(a,b,"r")</literal> also returns index
88             vectors <literal>ka</literal> and <literal>kb</literal> such that
89             <literal>v=a(ka,:)</literal> and <literal>v=b(kb,:)</literal>.
90         </para>
91         <para>
92             <literal>intersect(a,b,"c")</literal> or
93             <literal>intersect(a,b,2)</literal>returns the matrix formed by the
94             intersection of the unique columns of <literal>a</literal> and
95             <literal>b</literal> sorted in lexicographic ascending order. In this case
96             matrices <literal>a</literal> and <literal>b</literal> must have the same
97             number of rows.
98         </para>
99         <para>
100             <literal>[v,ka,kb]=intersect(a,b,"c")</literal> also returns index
101             vectors <literal>ka</literal> and <literal>kb</literal> such that
102             <literal>v=a(:,ka)</literal> and <literal>v=b(:,kb)</literal>.
103         </para>
104     </refsection>
105     <refsection>
106         <title>Remark</title>
107         <para>NaN are considered as different from themselves so they are excluded
108             out of intersection in case of vector intersection.
109         </para>
110     </refsection>
111     <refsection>
112         <title>Examples</title>
113         <programlisting role="example"><![CDATA[ 
114 A=round(5*rand(10,1));
115 B=round(5*rand(7,1));
116
117 intersect(A,B)
118 [N,ka,kb]=intersect(A,B)
119
120 intersect('a'+string(A),'a'+string(B))
121
122 intersect(int16(A),int16(B))
123
124 //with matrices
125  A = [0,0,1,1 1;
126       0,1,1,1,1;
127       2,0,1,1,1;
128       0,2,2,2,2;
129       2,0,1,1,1;
130       0,0,1,1,%nan];
131 B = [1,0,1;
132      1,0,2;
133      1,2,3;
134      2,0,4;
135      1,2,5;
136      %nan,0,6];
137
138 [v,ka,kb] = intersect(A,B,'c')
139 A(:,ka)
140  ]]></programlisting>
141     </refsection>
142     <refsection role="see also">
143         <title>See Also</title>
144         <simplelist type="inline">
145             <member>
146                 <link linkend="unique">unique</link>
147             </member>
148             <member>
149                 <link linkend="gsort">gsort</link>
150             </member>
151             <member>
152                 <link linkend="union">union</link>
153             </member>
154         </simplelist>
155     </refsection>
156 </refentry>