...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 HashFunctor = hash< KeyType >, class EqualKey = std::equal_to< KeyType > > struct unordered_set_of; template < class HashFunctor = hash< _relation >, class EqualKey = std::equal_to< _relation > > struct unordered_set_of_relation; } // namespace bimap } // namespace boost
namespace boost { namespace bimaps { template < class KeyType, class HashFunctor = hash< KeyType >, class EqualKey = std::equal_to< KeyType > > struct unordered_multiset_of; template < class HashFunctor = hash< _relation >, class EqualKey = std::equal_to< _relation > > struct unordered_multiset_of_relation; } // namespace bimap } // namespace boost
These collection types specifiers allow for set views without and with
allowance of duplicate elements, respectively. The syntax of set_of
and multiset_of
coincide, thus we describe them in a grouped manner.
An unordered_[multi]set_of set view is a tr1::unordered[multi]set signature
compatible interface to the underlying heap of elements contained in a
bimap
.
The interface and semantics of unordered_[multi]set_of
views are modeled according to the proposal for unordered associative containers
given in the C++
Standard Library Technical Report, also known as TR1. An unordered_[multi]set_of
view is particularized according
to a given Hash
function
object which returns hash values for the keys and a binary predicate Pred
acting as an equivalence relation
on values of Key.
There are two variants: unordered_set_of, which do not allow duplicate elements (with respect to its associated comparison predicate) and unordered_multiset_of, which accept those duplicates. The interface of these two variants is the same to a great extent, so they are documented together with their differences explicitly noted when they exist.
If you look the bimap by a side, you will use a map view and if you looked it as a whole you will be using a set view.
Except where noted, unordered_[multi]set_of
views (both unique and non-unique) are models of Unordered Associative
Container
. Validity of iterators and references to elements is
preserved in all cases. Occasionally, the exception safety guarantees provided
are actually stronger than required by the extension draft. We only provide
descriptions of those types and operations that are either not present
in the concepts modeled or do not exactly conform to the requirements for
unordered associative containers.
namespace boost { namespace bimap { namespace views { template< -implementation defined parameter list- > class -implementation defined view name- { public: // types typedef -unspecified- key_type; typedef -unspecified- value_type; typedef -unspecified- key_compare; typedef -unspecified- value_compare; typedef -unspecified- hasher; typedef -unspecified- key_equal; 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- local_iterator; typedef -unspecified- const_local_iterator; typedef -unspecified- info_type; // construct/destroy/copy: this_type & operator=(const this_type & x); allocator_type get_allocator() const; // size and capacity bool empty() const; size_type size() const; size_type max_size() const; // iterators iterator begin(); const_iterator begin() const; iterator end(); const_iterator end() 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 // { typedef -unspecified- mapped_type; typedef -unspecified- data_type; // Equal to mapped_type 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 clear(); // observers key_from_value key_extractor() const; hasher hash_function() const; key_equal key_eq() const; // lookup 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 > std::pair<iterator,iterator> equal_range(const CompatibleKey & x); template< class CompatibleKey > std::pair<const_iterator,const_iterator> equal_range(const CompatibleKey & x) const; // bucket interface size_type bucket_count() const; size_type max_bucket_count() const; size_type bucket_size(size_type n) const; size_type bucket(const key_type & k) const; local_iterator begin(size_type n); const_local_iterator begin(size_type n) const; local_iterator end(size_type n); const_local_iterator end(size_type n) const; // hash policy float load_factor() const; float max_load_factor() const; void max_load_factor(float z); void rehash(size_type n); // Only in maps views // { typedef -unspecified- mapped_type; // Only in for `unordered_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; // } // } }; } // namespace views } // namespace bimap } // namespace boost
In the case of a bimap< unordered_{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 unordered_[multi]set_of
views, we adopt the scheme outlined in the complexity
signature section. The complexity signature of unordered_[multi]set_of
view is:
c(n) = n * log(n)
,
i(n) = 1
(constant), worst case i(n) = n
,
h(n) = 1
(constant), worst case h(n) = n
,
d(n) = 1
(constant), worst case d(n) = n
,
r(n)
= 1
(constant),
r(n) =
1
(constant), worst case
r(n)
= n
,
m(n) = 1
(constant), worst case m(n) = n
.
unordered_[multi]set_of
views are instantiated internally
to bimap
specified by
means of the collection type specifiers and the bimap
itself. Instantiations are dependent on the following types:
Value
from bimap
,
Allocator
from bimap
,
Hash
from the collection
type specifier,
Pred
from the collection
type specifier.
Hash
is a Unary
Function taking a single argument of type key_type
and returning a value of type std::size_t
in the range [0, std::numeric_limits<std::size_t>::max())
. Pred is a Binary
Predicate inducing an equivalence relation on elements of key_type
. It is required that the
Hash
object return the
same value for keys equivalent under Pred
.
iterator const_iterator local_iterator const_local_iterator
These types are models of Forward Iterator.
As explained in the concepts section, views do not have public constructors
or destructors. Assignment, on the other hand, is provided. Upon construction,
max_load_factor()
is 1.0.
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 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
.
first
and last
are not iterators into any
views of the bimap
to which this view 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
of the view.
position
.
iterator
pointing to the element immediately following the one that was deleted,
or end()
if no such element exists.
template< class CompatibleKey > size_type erase(const CompatibleKey & x);
x
.
iterator erase(iterator first, iterator last);
[first,last)
is a valid range of the view.
[first,last)
.
last
.
[first,last)
.
bool replace(iterator position, const value_type & x);
position
is a valid dereferenceable iterator
of the view.
x
to the element pointed to by
position
into the
bimap
to which the
view belongs if, for the value x
*position
),
bimap
.
true
if the replacement took place, false
otherwise.
bimap
to which the 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.
unordered_[multi]set_of
views provide the full lookup
functionality required by unordered associative containers, namely find
, count
,
and equal_range
. Additionally,
these member functions are templatized to allow for non-standard arguments,
so extending the types of search operations allowed. The kind of arguments
permissible when invoking the lookup member functions is defined by the
following concept.
A type CompatibleKey
is said to be a compatible key of (Hash, Pred)
if (CompatibleKey,
Hash,
Pred)
is a compatible extension of (Hash, Pred)
.
This implies that Hash
and Pred
accept arguments
of type CompatibleKey
,
which usually means they have several overloads of their corresponding
operator()
member functions.
template< class CompatibleKey > iterator find(const CompatibleKey & x); template< class CompatibleKey > const_iterator find(const CompatibleKey & x) const;
x
,
or end()
if such an element does not exist.
template< class CompatibleKey > size_type count(const CompatibleKey & x) const;
x
.
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;
x
(and only those).
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.
unordered_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;
unordered_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.
unordered_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.
unordered_set_of
and info_hook
are used
void rehash(size_type n);
size()/bucket_count()
does not exceed the maximum load
factor, and bucket_count()>=n
.
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 unordered_[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
b to an output archive (XML archive)
ar.
Operation: loading of a bimap
b' from an input archive (XML
archive) ar.
key_eq()
must be serialization-compatible
with m.get<i>().key_eq()
,
where i is the position of the unordered_[multi]set_of
view in the container.
[begin(), end())
contains restored copies of every
element in [m.get<i>().begin(), m.get<i>().end())
, though not necessarily in the
same order.
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
was dereferenceable
then *it
'
is the restored copy of *it
, otherwise it
'
== end()
.
it
be a const_iterator
and the restored it
'
an iterator
, or viceversa.
Operation: saving of a local_iterator or const_local_iterator it to an output archive (XML archive) ar.
it
is a valid local iterator of the view. The associated bimap
has been previously saved.
Operation: loading of a local_iterator
or const_local_iterator
it
' from an input archive
(XML archive) ar.
it
was dereferenceable
then *it
'
is the restored copy of *it
; if it
was m.get<i>().end(n)
for some n, then it
'
== m
'.get<i>().end(n)
(where b
is the original bimap
,
b
' its restored copy
and i
is the ordinal
of the index.)
it
be a const_local_iterator
and the restored it
'
a local_iterator
,
or viceversa.