1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
<HTML>
<!--
-- Copyright (c) 1996-1999
-- Silicon Graphics Computer Systems, Inc.
--
-- Permission to use, copy, modify, distribute and sell this software
-- and its documentation for any purpose is hereby granted without fee,
-- provided that the above copyright notice appears in all copies and
-- that both that copyright notice and this permission notice appear
-- in supporting documentation. Silicon Graphics makes no
-- representations about the suitability of this software for any
-- purpose. It is provided "as is" without express or implied warranty.
--
-- Copyright (c) 1994
-- Hewlett-Packard Company
--
-- Permission to use, copy, modify, distribute and sell this software
-- and its documentation for any purpose is hereby granted without fee,
-- provided that the above copyright notice appears in all copies and
-- that both that copyright notice and this permission notice appear
-- in supporting documentation. Hewlett-Packard Company makes no
-- representations about the suitability of this software for any
-- purpose. It is provided "as is" without express or implied warranty.
--
-->
<Head>
<Title>includes</Title>
<!-- Generated by htmldoc -->
</HEAD>
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
ALINK="#ff0000">
<IMG SRC="CorpID.gif"
ALT="SGI" HEIGHT="43" WIDTH="151">
<!--end header-->
<BR Clear>
<H1>includes</H1>
<Table CellPadding=0 CellSpacing=0 width=100%>
<TR>
<TD Align=left><Img src = "algorithms.gif" Alt="" WIDTH = "194" HEIGHT = "38" ></TD>
<TD Align=right><Img src = "function.gif" Alt="" WIDTH = "194" HEIGHT = "38" ></TD>
</TR>
<TR>
<TD Align=left VAlign=top><b>Category</b>: algorithms</TD>
<TD Align=right VAlign=top><b>Component type</b>: function</TD>
</TR>
</Table>
<h3>Prototype</h3>
<tt>Includes</tt> is an overloaded name; there are actually two <tt>includes</tt>
functions.
<pre>
template <class <A href="InputIterator.html">InputIterator</A>1, class <A href="InputIterator.html">InputIterator</A>2>
bool includes(InputIterator1 first1, InputIterator1 last1,
InputIterator2 first2, InputIterator2 last2);
template <class <A href="InputIterator.html">InputIterator</A>1, class <A href="InputIterator.html">InputIterator</A>2, class <A href="StrictWeakOrdering.html">StrictWeakOrdering</A>>
bool includes(InputIterator1 first1, InputIterator1 last1,
InputIterator2 first2, InputIterator2 last2,
StrictWeakOrdering comp);
</pre>
<h3>Description</h3>
<tt>Includes</tt> tests whether one sorted range includes another sorted
range. That is, it returns <tt>true</tt> if and only if, for every element in
<tt>[first2, last2)</tt>, an equivalent element <A href="#1">[1]</A> is also present in
<tt>[first1, last1)</tt> <A href="#2">[2]</A>.
Both <tt>[first1, last1)</tt> and <tt>[first2, last2)</tt> must be sorted in ascending order.
<P>
The two versions of <tt>includes</tt> differ in how they define whether one
element is less than another. The first version compares
objects using <tt>operator<</tt>, and the second compares objects using
the <A href="functors.html">function object</A> <tt>comp</tt>.
<h3>Definition</h3>
Defined in the standard header <A href="algorithm">algorithm</A>, and in the nonstandard
backward-compatibility header <A href="algo.h">algo.h</A>.
<h3>Requirements on types</h3>
For the first version:
<UL>
<LI>
<tt>InputIterator1</tt> is a model of <A href="InputIterator.html">Input Iterator</A>.
<LI>
<tt>InputIterator2</tt> is a model of <A href="InputIterator.html">Input Iterator</A>.
<LI>
<tt>InputIterator1</tt> and <tt>InputIterator2</tt> have the same value type.
<LI>
<tt>InputIterator</tt>'s value type is a model of <A href="LessThanComparable.html">LessThan Comparable</A>.
<LI>
The ordering on objects of <tt>InputIterator1</tt>'s value type is a <i>strict
weak ordering</i>, as defined in the <A href="LessThanComparable.html">LessThan Comparable</A> requirements.
</UL>
For the second version:
<UL>
<LI>
<tt>InputIterator1</tt> is a model of <A href="InputIterator.html">Input Iterator</A>.
<LI>
<tt>InputIterator2</tt> is a model of <A href="InputIterator.html">Input Iterator</A>.
<LI>
<tt>InputIterator1</tt> and <tt>InputIterator2</tt> have the same value type.
<LI>
<tt>StrictWeakOrdering</tt> is a model of <A href="StrictWeakOrdering.html">Strict Weak Ordering</A>.
<LI>
<tt>InputIterator1</tt>'s value type is convertible to <tt>StrictWeakOrdering</tt>'s
argument type.
</UL>
<h3>Preconditions</h3>
For the first version:
<UL>
<LI>
<tt>[first1, last1)</tt> is a valid range.
<LI>
<tt>[first2, last2)</tt> is a valid range.
<LI>
<tt>[first1, last1)</tt> is ordered in ascending order according to
<tt>operator<</tt>. That is, for every pair of iterators <tt>i</tt> and <tt>j</tt>
in <tt>[first1, last1)</tt> such that <tt>i</tt> precedes <tt>j</tt>,
<tt>*j < *i</tt> is <tt>false</tt>.
<LI>
<tt>[first2, last2)</tt> is ordered in ascending order according to
<tt>operator<</tt>. That is, for every pair of iterators <tt>i</tt> and <tt>j</tt>
in <tt>[first2, last2)</tt> such that <tt>i</tt> precedes <tt>j</tt>,
<tt>*j < *i</tt> is <tt>false</tt>.
</UL>
For the second version:
<UL>
<LI>
<tt>[first1, last1)</tt> is a valid range.
<LI>
<tt>[first2, last2)</tt> is a valid range.
<LI>
<tt>[first1, last1)</tt> is ordered in ascending order according to
<tt>comp</tt>. That is, for every pair of iterators <tt>i</tt> and <tt>j</tt>
in <tt>[first1, last1)</tt> such that <tt>i</tt> precedes <tt>j</tt>,
<tt>comp(*j, *i)</tt> is <tt>false</tt>.
<LI>
<tt>[first2, last2)</tt> is ordered in ascending order according to
<tt>comp</tt>. That is, for every pair of iterators <tt>i</tt> and <tt>j</tt>
in <tt>[first2, last2)</tt> such that <tt>i</tt> precedes <tt>j</tt>,
<tt>comp(*j, *i)</tt> is <tt>false</tt>.
</UL>
<h3>Complexity</h3>
Linear. Zero comparisons if either <tt>[first1, last1)</tt> or <tt>[first2, last2)</tt>
is an empty range, otherwise at most <tt>2 * ((last1 - first1) + (last2 -
first2)) - 1</tt> comparisons.
<h3>Example</h3>
<pre>
int A1[] = { 1, 2, 3, 4, 5, 6, 7 };
int A2[] = { 1, 4, 7 };
int A3[] = { 2, 7, 9 };
int A4[] = { 1, 1, 2, 3, 5, 8, 13, 21 };
int A5[] = { 1, 2, 13, 13 };
int A6[] = { 1, 1, 3, 21 };
const int N1 = sizeof(A1) / sizeof(int);
const int N2 = sizeof(A2) / sizeof(int);
const int N3 = sizeof(A3) / sizeof(int);
const int N4 = sizeof(A4) / sizeof(int);
const int N5 = sizeof(A5) / sizeof(int);
const int N6 = sizeof(A6) / sizeof(int);
cout << "A2 contained in A1: "
<< (includes(A1, A1 + N1, A2, A2 + N2) ? "true" : "false") << endl;
cout << "A3 contained in A1: "
<< (includes(A1, A1 + N2, A3, A3 + N3) ? "true" : "false") << endl;
cout << "A5 contained in A4: "
<< (includes(A4, A4 + N4, A5, A5 + N5) ? "true" : "false") << endl;
cout << "A6 contained in A4: "
<< (includes(A4, A4 + N4, A6, A6 + N6) ? "true" : "false") << endl;
</pre>
The output is:
<pre>
A2 contained in A1: true
A3 contained in A1: false
A5 contained in A4: false
A6 contained in A4: true
</pre>
<h3>Notes</h3>
<P><A name="1">[1]</A>
This reads "an equivalent element" rather than "the same element"
because
the ordering by which the input ranges are sorted
is permitted to be a strict weak ordering that is not a total ordering:
there might be values <tt>x</tt> and <tt>y</tt> that are
equivalent (that is, neither <tt>x < y</tt> nor <tt>y < x</tt> is true) but not
equal. See the <A href="LessThanComparable.html">LessThan Comparable</A> requirements for a fuller
discussion.)
If you're using a total ordering
(if you're using <tt>strcmp</tt>, for example, or if you're using
ordinary arithmetic comparison on integers), then you can ignore this
technical distinction: for a total ordering, equality and equivalence
are the same.
<P><A name="2">[2]</A>
Note that the range <tt>[first2, last2)</tt> may contain a consecutive range
of equivalent elements: there is no requirement that every element in
the range be unique. In this case, <tt>includes</tt> will return <tt>false</tt>
unless, for every element in <tt>[first2, last2)</tt>, a distinct equivalent
element is also present in <tt>[first1, last1)</tt>. That is, if a certain
value appears <tt>n</tt> times in <tt>[first2, last2)</tt> and <tt>m</tt> times in
<tt>[first1, last1)</tt>, then <tt>includes</tt> will return <tt>false</tt> if <tt>m < n</tt>.
<h3>See also</h3>
<tt><A href="set_union.html">set_union</A></tt>, <tt><A href="set_intersection.html">set_intersection</A></tt>, <tt><A href="set_difference.html">set_difference</A></tt>,
<tt><A href="set_symmetric_difference.html">set_symmetric_difference</A></tt>, <tt><A href="sort.html">sort</A></tt>
<!--start footer-->
<HR SIZE="6">
<A href="http://www.sgi.com/"><IMG SRC="surf.gif" HEIGHT="54" WIDTH="54"
ALT="[Silicon Surf]"></A>
<A HREF="index.html"><IMG SRC="stl_home.gif"
HEIGHT="54" WIDTH="54" ALT="[STL Home]"></A>
<BR>
<FONT SIZE="-2">
<A href="http://www.sgi.com/Misc/sgi_info.html" TARGET="_top">Copyright ©
1999 Silicon Graphics, Inc.</A> All Rights Reserved.</FONT>
<FONT SIZE="-3"><a href="http://www.sgi.com/Misc/external.list.html" TARGET="_top">TrademarkInformation</A>
</FONT>
<P>
</BODY>
</HTML>
|
