The <set>
header is one of the standard container template headers. It declares the set
and multiset
class templates and a few global functions that operate on set
and multiset
objects.
A set is a container that stores keys. Looking up keys, inserting keys, and deleting keys can all be performed in logarithmic or better time. Maps support bidirectional iterators (no random access). In other languages and libraries, sets are also called dictionaries and associative arrays.
See Chapter 11 for information about containers in general.
Set container with duplicate keys
template <typename Key, typename Compare = less<Key>, typename Alloc = allocator<Key> > class multiset { public: typedef Key key_type; typedef Key value_type; typedef Compare key_compare; typedef Compare value_compare; typedef Alloc allocator_type; typedef typename Alloc::reference reference; typedef typename Alloc::const_reference const_reference; typedef ... iterator; typedef ... const_iterator; typedef ... size_type; typedef ... difference_type; typedef typename Alloc::pointer pointer; typedef typename Alloc::const_pointer const_pointer; typedef std::reverse_iterator<iterator> reverse_iterator; typedef std::reverse_iterator<const_iterator> const_reverse_iterator; explicit multiset(const Compare& comp = Compare(), const Alloc& = Alloc()); template <class InputIterator> multiset(InputIterator first, InputIterator last, const Compare& comp = Compare(), const Alloc& = Alloc()); multiset(const multiset<Key,Compare,Alloc>& x); ~multiset(); multiset<Key,Compare,Alloc>& operator=(const multiset<Key,Compare,Alloc>& x); allocator_type get_allocator() const; // iterators: iterator begin(); const_iterator begin() const; iterator end(); const_iterator end() const; reverse_iterator rbegin(); const_reverse_iterator rbegin() const; reverse_iterator rend(); const_reverse_iterator rend() const; bool empty() const; size_type size() const; size_type max_size() const; iterator insert(const value_type& x); iterator insert(iterator position, const value_type& x); template <class InputIterator> void insert(InputIterator first, InputIterator last); void erase(iterator position); size_type erase(const key_type& x); void erase(iterator first, iterator last); void swap(multiset<Key,Compare,Alloc>&); void clear(); key_compare key_comp() const; value_compare value_comp() const; iterator find(const key_type& x) const; size_type count(const key_type& x) const; iterator lower_bound(const key_type& x) const; iterator upper_bound(const key_type& x) const; pair<iterator,iterator> equal_range(const key_type& x) const; };
The multiset
class template is a standard container that contains an ordered set of keys of type T
. The keys can be duplicated, that is, the multiset can contain more than one instance of a particular key.
A multiset's iterators are bidirectional. Note that keys are const
in the set. You must not change the key while it is stored in a set. More precisely, you must not change the key in a way that alters its relative order with the other keys in the set. If you need to modify a key, erase the key from the set, modify the key, and insert the new key, as shown in Example 13-37, later in this section.
Within a multiset, keys are ordered in ascending order, according to the Compare
template parameter (which can be a function pointer or functor that compares two objects of type Key
and returns true if the first argument should come before the second). Keys need not be unique. When searching for keys, they are compared using the function or functor specified by the Compare
template parameter. Two objects, a
and b
, are different (and therefore can both be present in a single set
object) if Compare(a,
b)
is true or Compare(b,
a)
is true. See set
, later in this section, for a set container that store unique keys.
Inserting into a multiset does not invalidate any iterators for that set. Erasing an element invalidates only iterators that refer to that element.
Insertion into a set and searching for an element in a set take logarithmic time. Erasing a single element, given an iterator, takes amortized constant time; erasing all elements in a range given by two iterators can be done in logarithmic time.
Following are the member functions of multiset
:
explicit
multiset
(const Compare& comp = Compare(),
const Alloc& = Alloc())
template
<class InputIterator>
multiset
(InputIterator first,
InputIterator
last,
const
Compare&
comp
=
Compare(),
const
Alloc&
=
Alloc())
first
, last
) into the new set.
multiset
(const multiset<Key,Compare,Alloc>& x)
x
to the new set.iterator
begin
()
const_iterator
begin
()
const
void
clear
()
size_type
count
(const key_type& x) const
x
.bool
empty
()
const
size()
==
0
.iterator
end
()
const_iterator
end
()
const
pair<iterator,iterator>
equal_range
(const key_type& x) const
pair
, e.g.,std::make_pair(lower_bound(x), upper_bound(x))
void
erase
(iterator position)
size_type
erase
(const key_type& x)
void
erase
(iterator first, iterator last)
position
in constant time (amortized over many calls). The second version erases the item equivalent to x
, if it is present, returning a count of the number of items erased. It runs in logarithmic time. The third version erases all elements in the range [first
, last
) in time proportional to log size()
+ (last
- first
).iterator
find
(const key_type& x) const
x
and returns an iterator that points to that key or end()
if not found. It runs in logarithmic time. If x
occurs more than once, the iterator might point to any of its occurrences in the multiset.allocator_type
get_allocator
()
const
pair<iterator,bool>
insert
(const value_type& x)
iterator
insert
(iterator
position,
const
value_type&
x)
template
<class InputIterator>
void
insert
(InputIterator
first,
InputIterator
last)
x
in logarithmic time.x
, using pos
as a position hint. If x
is inserted immediately after pos
, the performance is constant (amortized over many insertions); at any other position, the performance is logarithmic. Use this form when inserting many items that are already in the desired order.first
, last
), which must be pointing to a different multiset
object. If the items are already in the desired order, the performance is linear; otherwise it is N log (size()
+
N)
, where N is last
- first
.key_compare
key_comp
()
const
key_compare
type is the same as the Compare
template parameter.iterator
lower_bound
(const key_type& x) const
x
. That is, if x
is in the set, the iterator points to the position of its first occurrence; otherwise the iterator points to the first position where x
should be inserted. Performance is logarithmic.size_type
max_size
()
const
reverse_iterator
rbegin
()
const_reverse_iterator
rbegin
()
const
reverse_iterator
rend
()
const_reverse_iterator
rend
()
const
size_type
size
()
const
void
swap
(multiset<Key,Compare,Alloc>&)
x
.iterator
upper_bound
(const key_type& x) const
x
. Performance is logarithmic.value_compare
value_comp
()
const
value_compare
type is the same as the Compare
template parameter.multiset<Key,Compare,Alloc>&
operator=
(const multiset<Key,Compare,Alloc>& x)
x
.set class template, multimap in <map>
Compare sets for equality
template <typename Key, typename T, typename C, typename A> bool operator==(const set<Key,T,C,A>& x, const set<Key,T,C,A>& y); template <typename Key, typename T, typename C, typename A> bool operator==(const multiset<Key,T,C,A>& x, const multiset<Key,T,C,A>& y);
Returns true if x
and y
have the same size and their elements are equal, that is, x.size()
==
y.size()
&&
equals(x.begin(),
x.end(),
y.begin())
.
equals in <algorithm>
Compare sets for inequality
template <typename Key, typename T, typename C, typename A> bool operator!=(const set<Key,T,C,A>& x, const set<Key,T,C,A>& y); template <typename Key, typename T, typename C, typename A> bool operator!=(const multiset<Key,T,C,A>& x, const multiset<Key,T,C,A>& y);
Returns !
(x
==
y)
.
Compare sets for less than
template <typename Key, typename T, typename C, typename A> bool operator<(const set<Key,T,C,A>& x, const set<Key,T,C,A>& y); template <typename Key, typename T, typename C, typename A> bool operator<(const multiset<Key,T,C,A>& x, const multiset<Key,T,C,A>& y);
Determines whether x
is less than y
, using the same algorithm as lexicographic_compare(x.begin(),
x.end(),
y.begin(),
y.end())
.
lexicographic_compare in <algorithm>
Compare sets for less than or equal
template <typename Key, typename T, typename C, typename A> bool operator<=(const set<Key,T,C,A>& x, const set<Key,T,C,A>& y); template <typename Key, typename T, typename C, typename A> bool operator<=(const multiset<Key,T,C,A>& x, const multiset<Key,T,C,A>& y);
Returns !
(y
<
x)
.
Compare sets for greater than
template <typename Key, typename T, typename C, typename A> bool operator>(const set<Key,T,C,A>& x, const set<Key,T,C,A>& y); template <typename Key, typename T, typename C, typename A> bool operator>(const multiset<Key,T,C,A>& x, const multiset<Key,T,C,A>& y);
Returns (y
<
x)
.
Compare sets for greater than or equal
template <typename Key, typename T, typename C, typename A> bool operator>=(const set<Key,T,C,A>& x, const set<Key,T,C,A>& y); template <typename Key, typename T, typename C, typename A> bool operator>=(const multiset<Key,T,C,A>& x, const multiset<Key,T,C,A>& y);
Returns !
(x
<
y)
.
Set container with unique keys
template <typename Key, typename Compare = less<Key>, typename Alloc = allocator<Key> > class set { public: typedef Key key_type; typedef Key value_type; typedef Compare key_compare; typedef Compare value_compare; typedef Alloc allocator_type; typedef typename Alloc::reference reference; typedef typename Alloc::const_reference const_reference; typedef ... iterator; typedef ... const_iterator; typedef ... size_type; typedef ... difference_type; typedef typename Alloc::pointer pointer; typedef typename Alloc::const_pointer const_pointer; typedef std::reverse_iterator<iterator> reverse_iterator; typedef std::reverse_iterator<const_iterator> const_reverse_iterator; explicit set(const Compare& comp = Compare(), const Alloc& = Alloc()); template <class InputIterator> set(InputIterator first, InputIterator last, const Compare& comp = Compare(), const Alloc& = Alloc()); set(const set<Key,Compare,Alloc>& x); ~set(); set<Key,Compare,Alloc>& operator=(const set<Key,Compare,Alloc>& x); allocator_type get_allocator() const; iterator begin(); const_iterator begin() const; iterator end(); const_iterator end() const; reverse_iterator rbegin(); const_reverse_iterator rbegin() const; reverse_iterator rend(); const_reverse_iterator rend() const; bool empty() const; size_type size() const; size_type max_size() const; pair<iterator,bool> insert(const value_type& x); iterator insert(iterator position, const value_type& x); template <class InputIterator> void insert(InputIterator first, InputIterator last); void erase(iterator position); size_type erase(const key_type& x); void erase(iterator first, iterator last); void swap(set<Key,Compare,Alloc>&); void clear(); // observers: key_compare key_comp() const; value_compare value_comp() const; // set operations: iterator find(const key_type& x) const; size_type count(const key_type& x) const; iterator lower_bound(const key_type& x) const; iterator upper_bound(const key_type& x) const; pair<iterator,iterator> equal_range(const key_type& x) const; };
The set
class template is a standard container that contains an ordered set of unique keys of type T
.
A set's iterators are bidirectional. Note that keys are const
in the set. You must not change the key while it is stored in a set. More precisely, you must not change the key in a way that alters its relative order with the other keys in the set. If you need to modify a key, erase the key from the set, modify the key, and insert the new key, as shown in Example 13-37.
Example 13-37: One way to modify a key
template <typename T, typename C, typename A> void change_key(std::set<T, C, A>& s, const T& oldkey, const T& newkey) { using ::std::set; typedef set<T, C, A>::iterator set_iterator; set_iterator i = s.find(oldkey); if (i != s.end()) { m.erase(i); m.insert(newkey); } // Exercise for reader: What if newkey is already in m? }
Within a set, keys are ordered in ascending order, according to the Compare
template parameter (which can be a function pointer or functor that compares two objects of type Key
and returns true if the first argument should come before the second). Keys must be unique, but note that uniqueness is determined only by calling Compare
, not by using the ==
operator. That is, two objects, a
and b
, are different (and therefore can both be present in a single set
object) if Compare(a,
b)
is true or Compare(b,
a)
is true. See multiset
, earlier in this section, for a set container that can store non-unique keys.
Inserting into a set does not invalidate any iterators for that set. Erasing an element invalidates only iterators that refer to that element.
Insertion into a set and searching for an element in a set take logarithmic time. Erasing a single element, given an iterator, takes amortized constant time; erasing all elements in a range given by two iterators can be done in logarithmic time.
Following are the member functions of set
:
explicit
set
(const Compare& comp = Compare(),
const Alloc& = Alloc())
template
<class InputIterator>
set
(InputIterator first,
InputIterator
last,
const
Compare&
comp
=
Compare(),
const
Alloc&
=
Alloc())
first
, last
) into the new set.
set
(const set<Key,Compare,Alloc>& x)
x
to the new set.iterator
begin
()
const_iterator
begin
()
const
void
clear
()
size_type
count
(const key_type& x) const
x
. This value is always zero or one.bool
empty
()
const
size()
==
0
.iterator
end
()
const_iterator
end
()
const
pair<iterator,iterator>
equal_range
(const key_type& x) const
pair
, e.g.,std::make_pair(lower_bound(x), upper_bound(x))
void
erase
(iterator position)
size_type
erase
(const key_type& x)
void
erase
(iterator first, iterator last)
position
in constant time (amortized over many calls). The second version erases the item equivalent to x
, if it is present, returning a count of the number of items erased, that is, zero or one. It runs in logarithmic time. The third version erases all elements in the range [first
, last
) in time proportional to log size()
+ (last
- first
).iterator
find
(const key_type& x) const
x
and returns an iterator that points to that key or end()
if not found. It runs in logarithmic time.allocator_type
get_allocator
()
const
pair<iterator,bool>
insert
(const value_type& x)
iterator
insert
(iterator
position,
const
value_type&
x)
template
<class InputIterator>
void
insert
(InputIterator
first,
InputIterator
last)
x
in logarithmic time.x
, using pos
as a position hint. If x
is inserted immediately after pos
, the performance is constant (amortized over many insertions); at any other position, the performance is logarithmic. Use this form when inserting many items that are already in the desired order.first
, last
), which must be pointing to a different set
object. If the items are already in the desired order, the performance is linear; otherwise it is N log (size()
+
N)
, where N is last
- first
.key_compare
key_comp
()
const
key_compare
type is the same as the Compare
template parameter.iterator
lower_bound
(const key_type& x) const
x
. That is, if x
is in the set, the iterator points to its position; otherwise the iterator points to the first position where x
should be inserted. Performance is logarithmic.size_type
max_size
()
const
reverse_iterator
rbegin
()
const_reverse_iterator
rbegin
()
const
reverse_iterator
rend
()
const_reverse_iterator
rend
()
const
size_type
size
()
const
void
swap
(set<Key,Compare,Alloc>&)
x
.iterator
upper_bound
(const key_type& x) const
x
. Performance is logarithmic.value_compare
value_comp
()
const
value_compare
type is the same as the Compare
template parameter.set<Key,Compare,Alloc>&
operator=
(const set<Key,Compare,Alloc>& x)
x
.multiset class template, multimap in <map>
Swap the contents of two sets
template <typename Key, typename T, typename C, typename A> void swap(set<Key,T,C,A>& x, set<Key,T,C,A>& y); template <typename Key, typename T, typename C, typename A> void swap(multiset<Key,T,C,A>& x, multiset<Key,T,C,A>& y);
Calls x.swap(y)
.
swap in <algorithm>