...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
namespace boost { namespace bimaps { template < class KeyType, class KeyCompare = std::less< KeyType > > struct set_of; template < class KeyCompare = std::less< _relation > > struct set_of_relation; } // namespace bimap } // namespace boost
namespace boost { namespace bimaps { template < class KeyType, class KeyCompare = std::less< KeyType > > struct multiset_of; template < class KeyCompare = std::less< _relation > > struct multiset_of_relation; } // namespace bimap } // namespace boost
These collection type specifiers allow for insertion of sets disallowing
or allowing duplicate elements, respectively. The syntaxes of set_of
and multiset_of
coincide, so they are described together.
A [multi]set_of set view is a std::[multi]set signature-compatible interface
to the underlying heap of elements contained in a bimap
.
There are two variants: set_of, which does not allow duplicate elements (with respect to its associated comparison predicate) and multiset_of, which does accept those duplicates. The interface of these two variants is largely the same, so they are documented together with their differences explicitly noted where they exist.
If you look the bimap from a side, you will use a map view, and if you look at it as a whole, you will be using a set view.
namespace boost { namespace bimaps { namespace views { template< -implementation defined parameter list- > class -implementation defined view name- { public: typedef -unspecified- key_type; typedef -unspecified- value_type; typedef -unspecified- key_compare; typedef -unspecified- value_compare; typedef -unspecified- allocator_type; typedef -unspecified- reference; typedef -unspecified- const_reference; typedef -unspecified- iterator; typedef -unspecified- const_iterator; typedef -unspecified- size_type; typedef -unspecified- difference_type; typedef -unspecified- pointer; typedef -unspecified- const_pointer; typedef -unspecified- reverse_iterator; typedef -unspecified- const_reverse_iterator; typedef -unspecified- info_type; this_type & operator=(const this_type & 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; // capacity bool empty() const; size_type size() const; size_type max_size() const; // modifiers std::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); iterator erase(iterator position); template< class CompatibleKey > size_type erase(const CompatibleKey & x); iterator erase(iterator first, iterator last); bool replace(iterator position, const value_type& x); // Only in map views // { template< class CompatibleKey > bool replace_key(iterator position, const CompatibleKey & x); template< class CompatibleData > bool replace_data(iterator position, const CompatibleData & x); template< class KeyModifier > bool modify_key(iterator position, KeyModifier mod); template< class DataModifier > bool modify_data(iterator position, DataModifier mod); // } void swap(this_type & x); void clear(); // observers key_compare key_comp() const; value_compare value_comp() const; // set operations template< class CompatibleKey > iterator find(const CompatibleKey & x); template< class CompatibleKey > const_iterator find(const CompatibleKey & x) const; template< class CompatibleKey > size_type count(const CompatibleKey & x) const; template< class CompatibleKey > iterator lower_bound(const CompatibleKey & x); template< class CompatibleKey > const_iterator lower_bound(const CompatibleKey & x) const; template< class CompatibleKey > iterator upper_bound(const CompatibleKey & x); template< class CompatibleKey > const_iterator upper_bound(const CompatibleKey & x) const; template< class CompatibleKey > std::pair<iterator,iterator> equal_range(const CompatibleKey & x); template< class CompatibleKey > std::pair<const_iterator,const_iterator> equal_range(const CompatibleKey & x) const; // Only in maps views // { template< class LowerBounder, class UpperBounder> std::pair<iterator,iterator> range( LowerBounder lower, UpperBounder upper); template< class LowerBounder, class UpperBounder> std::pair<const_iterator,const_iterator> range( LowerBounder lower, UpperBounder upper) const; typedef -unspecified- mapped_type; typedef -unspecified- data_type; // Equal to mapped_type // Only in for `set_of` collection type // { template< class CompatibleKey > const mapped_type & at(const CompatibleKey & k) const; // Only if the other collection type is mutable // { template< class CompatibleKey > mapped_type & operator[](const CompatibleKey & k); template< class CompatibleKey > mapped_type & at(const CompatibleKey & k); // } // Only if info_hook is used // { template< class CompatibleKey > info_type & info_at(const CompatibleKey & k); template< class CompatibleKey > const info_type & info_at(const CompatibleKey & k) const; // } // } // } }; // view comparison bool operator==(const this_type & v1, const this_type & v2 ); bool operator< (const this_type & v1, const this_type & v2 ); bool operator!=(const this_type & v1, const this_type & v2 ); bool operator> (const this_type & v1, const this_type & v2 ); bool operator>=(const this_type & v1, const this_type & v2 ); bool operator<=(const this_type & v1, const this_type & v2 ); } // namespace views } // namespace bimap } // namespace boost
In the case of a bimap< {multi}set_of<Left>, ... >
In the set view:
typedef signature-compatible with relation< Left, ... > key_type; typedef signature-compatible with relation< const Left, ... > value_type;
In the left map view:
typedef Left key_type; typedef ... mapped_type; typedef signature-compatible with std::pair< const Left, ... > value_type;
In the right map view:
typedef ... key_type; typedef Left mapped_type; typedef signature-compatible with std::pair< ... ,const Left > value_type;
Here and in the descriptions of operations of this view, we adopt the scheme outlined in the complexity signature section. The complexity signature of [multi]set_of view is:
c(n) = n * log(n)
,
i(n) = log(n)
,
h(n) = 1
(constant) if the hint element precedes
the point of insertion, h(n) = log(n)
otherwise,
d(n) = 1
(amortized constant),
r(n) = 1
(constant) if the element position does not change, r(n) = log(n)
otherwise,
m(n) = 1
(constant) if the element position does not change, m(n) = log(n)
otherwise.
Set views are instantiated internally to a bimap
.
Instantiations are dependent on the following types:
Value
from the set
specifier,
Allocator
from bimap
,
Compare
from the
set specifier.
Compare
is a Strict
Weak Ordering on elements of Value
.
Set views do not have public constructors or destructors. Assignment, on the other hand, is provided.
this_type & operator=(const this_type & x);
a
= b;
where a and b are the bimap
objects to which *this
and x belong, respectively.
*this
.
std::pair<iterator,bool> insert(const value_type & x);
x
into the bimap
to
which the set view belongs if
bimap
.
p
. p.second
is true
if and only if insertion took place. On successful insertion, p.first
points to the element inserted;
otherwise, p.first
points to an element that
caused the insertion to be banned. Note that more than one element
can be causing insertion not to be allowed.
iterator insert(iterator position, const value_type & x);
position
is a valid iterator of the view.
position
is used as a hint to improve the efficiency of the operation. Inserts
x
into the bimap
to which the view belongs
if
bimap
.
template< class InputIterator > void insert(InputIterator first, InputIterator last);
InputIterator
is a model of Input
Iterator over elements of type value_type
or a type convertible to value_type. first
and last
are not
iterators into any view of the bimap
to which this index belongs. last
is reachable from first
.
iterator
hint =
end()
;
while(
first !=
last )
hint =
insert(
hint,
*first++ );
[first,
last)
.
iterator erase(iterator position);
position
is a valid dereferenceable iterator if the set view.
position
.
end()
if no such element exists.
template< class CompatibleKey > size_type erase(const CompatibleKey & x);
CompatibleKey
is a compatible key of key_compare
.
x
.
iterator erase(iterator first, iterator last);
[first,last)
is a valid range of the view.
[first,last)
.
[first,last)
.
bool replace(iterator position, const value_type& x);
position
is a valid dereferenceable iterator of the set view.
x
to the element pointed to by
position
into the
bimap
to which the
set view belongs if, for the value x
*position
),
bimap
.
true
if the replacement took place, false
otherwise.
bimap
to which the set view belongs
remains in its original state.
template< class CompatibleKey > bool replace_key(iterator position, const CompatibleKey & x);
position
is a valid dereferenceable iterator of the set view. CompatibleKey
can be assigned to
key_type
.
x
to e.first
,
where e
is the element
pointed to by position
into the bimap
to
which the set view belongs if,
*position
),
bimap
.
true
if the replacement took place, false
otherwise.
bimap
to which the set view belongs
remains in its original state.
template< class CompatibleData > bool replace_data(iterator position, const CompatibleData & x);
position
is a valid dereferenceable iterator of the set view. CompatibleKey
can be assigned to
mapped_type
.
x
to e.second
,
where e
is the element
pointed to by position
into the bimap
to
which the set view belongs if,
*position
),
bimap
.
true
if the replacement took place, false
otherwise.
bimap
to which the set view belongs
remains in its original state.
template< class KeyModifier > bool modify_key(iterator position, KeyModifier mod);
KeyModifier
is a model of Unary
Function accepting arguments of type: key_type&
; position
is a valid dereferenceable iterator of the view.
mod(e.first)
where e is the element pointed to
by position and rearranges *position
into all the views of
the bimap
. If the
rearrangement fails, the element is erased. Rearrangement is successful
if
bimap
.
position
is preserved if the operation
succeeds.
true
if the operation succeeded, false
otherwise.
template< class DataModifier > bool modify_data(iterator position, DataModifier mod);
DataModifier
is a model of Unary
Function accepting arguments of type: mapped_type&
; position
is a valid dereferenceable iterator of the view.
mod(e.second)
where e is the element pointed to
by position and rearranges *position
into all the views of
the bimap
. If the
rearrangement fails, the element is erased. Rearrangement is successful
if
bimap
.
position
is preserved if the operation
succeeds.
true
if the operation succeeded, false
otherwise.
[multi]set_of
views provide the full lookup functionality required by Sorted
Associative Container and Unique
Associative Container, namely find
,
count
, lower_bound
, upper_bound
and equal_range
. Additionally,
these member functions are templatized to allow for non-standard arguments,
so extending the types of search operations allowed.
A type CompatibleKey
is said to be a compatible key of Compare
if (CompatibleKey,
Compare)
is a compatible extension of Compare
.
This implies that Compare
,
as well as being a strict weak ordering, accepts arguments of type CompatibleKey
, which usually means
it has several overloads of operator()
.
template< class CompatibleKey > iterator find(const CompatibleKey & x); template< class CompatibleKey > const_iterator find(const CompatibleKey & x) const;
CompatibleKey
is a compatible key of key_compare
.
x
,
or end()
if such an element does not exist.
template< class CompatibleKey > size_type count(const key_type & x) const;
CompatibleKey
is a compatible key of key_compare
.
x
.
template< class CompatibleKey > iterator lower_bound(const key_type & x); template< class CompatibleKey > const_iterator lower_bound(const key_type & x) const;
CompatibleKey
is a compatible key of key_compare
.
x
,
or end()
if such an element does not exist.
template< class CompatibleKey > iterator upper_bound(const key_type & x); template< class CompatibleKey > const_iterator upper_bound(const key_type & x) const;
CompatibleKey
is a compatible key of key_compare
.
x
,
or end()
if such an element does not exist.
template< class CompatibleKey > std::pair<iterator,iterator> equal_range(const key_type & x); template< class CompatibleKey > std::pair<const_iterator,const_iterator> equal_range(const key_type & x) const;
CompatibleKey
is a compatible key of key_compare
.
make_pair(lower_bound(x),upper_bound(x))
.
The member function range is not defined for sorted associative containers,
but [multi]set_of
map views provide it as a convenient utility. A range or interval is
defined by two conditions for the lower and upper bounds, which are modelled
after the following concepts.
Consider a Strict
Weak Ordering Compare
over values of type Key. A type LowerBounder
is said to be a lower bounder of Compare
if
LowerBounder
is a
Predicate
over Key
,
lower(k1)
and !comp(k2,k1)
then lower(k2)
,
for every lower
of type
LowerBounder
, comp
of type Compare
,
and k1
, k2
of type Key
.
Similarly, an upper bounder is a type UpperBounder
such that
UpperBounder
is a
Predicate
over Key
,
upper(k1)
and !comp(k1,k2)
then upper(k2)
,
for every upper
of type
UpperBounder
, comp
of type Compare
,
and k1
, k2
of type Key
.
template< class LowerBounder, class UpperBounder> std::pair<const_iterator,const_iterator> range( LowerBounder lower, UpperBounder upper) const;
LowerBounder
and UpperBounder
are a lower and upper bounder of key_compare
,
respectively.
end()
if this latter element does not
exist.
boost::bimap::unbounded
can be provided. This acts as a predicate which all values of type
key_type
satisfy.
template< class CompatibleKey > const mapped_type & at(const CompatibleKey & k) const;
CompatibleKey
is a compatible key of key_compare
.
mapped_type
reference that is associated
with k
, or throws
std::out_of_range
if such key does not
exist.
set_of
is used.
The symmetry of bimap imposes some constraints on operator[]
and the non constant version of at()
that are not found in std::maps
.
They are only provided if the other collection type is mutable (list_of
, vector_of
and unconstrained_set_of
).
template< class CompatibleKey > mapped_type & operator[](const CompatibleKey & k);
CompatibleKey
is a compatible key of key_compare
.
return
insert(value_type(k,mapped_type()))->second;
set_of
is used and the other collection
type is mutable.
template< class CompatibleKey > mapped_type & at(const CompatibleKey & k);
CompatibleKey
is a compatible key of key_compare
.
mapped_type
reference that is associated
with k
, or throws
std::out_of_range
if such key does not
exist.
set_of
is used and the other collection
type is mutable.
template< class CompatibleKey > info_type & info_at(const CompatibleKey & k); template< class CompatibleKey > const info_type & info_at(const CompatibleKey & k) const;
CompatibleKey
is a compatible key of key_compare
.
info_type
reference that is associated
with k
, or throws
std::out_of_range
if such key does not
exist.
set_of
and info_hook
are used
Views cannot be serialized on their own, but only as part of the bimap
into which they are embedded.
In describing the additional preconditions and guarantees associated
to [multi]set_of
views with respect to serialization of their embedding containers, we
use the concepts defined in the bimap
serialization section.
Operation: saving of a bimap
m to an output archive (XML archive)
ar.
Operation: loading of a bimap
m' from an input archive (XML
archive) ar.
value_comp()
must be serialization-compatible
with m.get<i>().value_comp()
,
where i is the position of the ordered view in the container.
[begin(),
end())
is a restored copy of the corresponding element in [m.get<i>().begin(), m.get<i>().end())
.
Operation: saving of an iterator or
const_iterator
it to
an output archive (XML archive) ar.
it
is a valid iterator of the view. The associated bimap
has been previously saved.
Operation: loading of an iterator
or const_iterator
it
' from an input archive
( XML archive) ar.
*it
' is the restored copy of *it
,
otherwise it
'
== end()
.
const_iterator
and
the restored it
'
an iterator, or viceversa.