set_union


Category: algorithms 
Component type: function 
Prototype
Set_union is an overloaded name; there are actually two set_union
functions.
template <class InputIterator1, class InputIterator2, class OutputIterator>
OutputIterator set_union(InputIterator1 first1, InputIterator1 last1,
InputIterator2 first2, InputIterator2 last2,
OutputIterator result);
template <class InputIterator1, class InputIterator2, class OutputIterator,
class StrictWeakOrdering>
OutputIterator set_union(InputIterator1 first1, InputIterator1 last1,
InputIterator2 first2, InputIterator2 last2,
OutputIterator result,
StrictWeakOrdering comp);
Description
Set_union constructs a sorted range that is the union of the
sorted ranges [first1, last1) and [first2, last2).
The return value is the end of the output range.
In the simplest case, set_union performs the "union" operation from
set theory: the output range contains a copy of every element that is
contained in [first1, last1), [first2, last2), or both. The
general case is more complicated, because the input ranges may contain
duplicate elements. The generalization is that if a value appears m
times in [first1, last1) and n times in [first2, last2) (where
m or n may be zero), then it appears max(m,n) times in the
output range. [1] Set_union is stable, meaning both that the
relative order of elements within each input range is preserved, and
that if an element is present in both input ranges it is copied from
the first range rather than the second.
The two versions of set_union differ in how they define whether one
element is less than another. The first version compares
objects using operator<, and the second compares objects using
a function object comp.
Definition
Defined in the standard header algorithm, and in the nonstandard
backwardcompatibility header algo.h.
Requirements on types
For the first version:

InputIterator1 is a model of Input Iterator.

InputIterator2 is a model of Input Iterator.

OutputIterator is a model of Output Iterator.

InputIterator1 and InputIterator2 have the same value type.

InputIterator's value type is a model of LessThan Comparable.

The ordering on objects of InputIterator1's value type is a strict
weak ordering, as defined in the LessThan Comparable requirements.

InputIterator's value type is convertible to a type in
OutputIterator's set of value types.
For the second version:

InputIterator1 is a model of Input Iterator.

InputIterator2 is a model of Input Iterator.

OutputIterator is a model of Output Iterator.

StrictWeakOrdering is a model of Strict Weak Ordering.

InputIterator1 and InputIterator2 have the same value type.

InputIterator1's value type is convertible to StrictWeakOrdering's
argument type.

InputIterator's value type is convertible to a type in
OutputIterator's set of value types.
Preconditions
For the first version:

[first1, last1) is a valid range.

[first2, last2) is a valid range.

[first1, last1) is ordered in ascending order according to
operator<. That is, for every pair of iterators i and j
in [first1, last1) such that i precedes j,
*j < *i is false.

[first2, last2) is ordered in ascending order according to
operator<. That is, for every pair of iterators i and j
in [first2, last2) such that i precedes j,
*j < *i is false.

There is enough space to hold all of the elements being copied.
More formally, the requirement is that
[result, result + n) is a valid range, where n is the number
of elements in the union of the two input ranges.

[first1, last1) and [result, result + n) do not overlap.

[first2, last2) and [result, result + n) do not overlap.
For the second version:

[first1, last1) is a valid range.

[first2, last2) is a valid range.

[first1, last1) is ordered in ascending order according to
comp. That is, for every pair of iterators i and j
in [first1, last1) such that i precedes j,
comp(*j, *i) is false.

[first2, last2) is ordered in ascending order according to
comp. That is, for every pair of iterators i and j
in [first2, last2) such that i precedes j,
comp(*j, *i) is false.

There is enough space to hold all of the elements being copied.
More formally, the requirement is that
[result, result + n) is a valid range, where n is the number
of elements in the union of the two input ranges.

[first1, last1) and [result, result + n) do not overlap.

[first2, last2) and [result, result + n) do not overlap.
Complexity
Linear. Zero comparisons if either [first1, last1) or [first2, last2)
is empty, otherwise at most 2 * ((last1  first1) + (last2  first2))
 1 comparisons.
Example
inline bool lt_nocase(char c1, char c2) { return tolower(c1) < tolower(c2); }
int main()
{
int A1[] = {1, 3, 5, 7, 9, 11};
int A2[] = {1, 1, 2, 3, 5, 8, 13};
char A3[] = {'a', 'b', 'B', 'B', 'f', 'H'};
char A4[] = {'A', 'B', 'b', 'C', 'D', 'F', 'F', 'h', 'h'};
const int N1 = sizeof(A1) / sizeof(int);
const int N2 = sizeof(A2) / sizeof(int);
const int N3 = sizeof(A3);
const int N4 = sizeof(A4);
cout << "Union of A1 and A2: ";
set_union(A1, A1 + N1, A2, A2 + N2,
ostream_iterator<int>(cout, " "));
cout << endl
<< "Union of A3 and A4: ";
set_union(A3, A3 + N3, A4, A4 + N4,
ostream_iterator<char>(cout, " "),
lt_nocase);
cout << endl;
}
The output is
Union of A1 and A2: 1 1 2 3 5 7 8 9 11 13
Union of A3 and A4: a b B B C D f F H h
Notes
[1]
Even this is not a completely precise description, 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
x and y that are equivalent (that is, neither x < y nor y < x)
but not equal. See the LessThan Comparable requirements
for a more complete discussion. If the range [first1, last1) contains m
elements that are equivalent to each other and the range [first2,
last2) contains n elements from that equivalence class (where
either m or n may be zero), then the output range contains
max(m, n) elements from that equivalence class. Specifically, m
of these elements will be copied from [first1, last1) and max(nm,
0) of them will be copied from [first2, last2). Note that this
precision is only important if elements can be
equivalent but not equal. If you're using a total ordering
(if you're using strcmp, 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.
See also
includes, set_intersection, set_difference,
set_symmetric_difference, sort, merge
Copyright ©
1999 Silicon Graphics, Inc. All Rights Reserved.
TrademarkInformation
webmaster@www.sgi.com