3 // Copyright (c) 2006-2007 Matias Capeletto
5 // Distributed under the Boost Software License, Version 1.0.
6 // (See accompanying file LICENSE_1_0.txt or copy at
7 // http://www.boost.org/LICENSE_1_0.txt)
10 /// \brief Includes the basic bimap container
14 \image html http://matias.capeletto.googlepages.com/boost.bimap.reference.logo.png
18 This is the complete reference of Boost.Bimap.
20 After getting a good understanding of the library from a user perspective
21 the next step will be:
23 - Understand the tagged idiom. (boost::bimaps::tags)
24 - Understand the internals of the relation class (boost::bimaps::relation)
25 - Read the container_adaptor toolbox docs (boost::bimaps::container_adaptor)
26 - Understand the internals of the bimap class. (boost::bimaps, boost::bimaps::views
27 and boost::bimaps::detail)
32 /** \defgroup mutant_group mutant idiom
33 \brief A safe wrapper around reinterpret_cast
36 /** \defgroup relation_group relation
40 /** \defgroup tags_group tagged idiom
41 \brief The tagged idiom
45 #ifndef BOOST_BIMAP_BIMAP_HPP
46 #define BOOST_BIMAP_BIMAP_HPP
48 #if defined(_MSC_VER) && (_MSC_VER>=1200)
52 #include <boost/config.hpp>
53 #include <boost/bimap/detail/user_interface_config.hpp>
54 #include <boost/mpl/aux_/na.hpp>
56 #define BOOST_BIMAP_DISABLE_SERIALIZATION
57 #ifndef BOOST_MULTI_INDEX_DISABLE_SERIALIZATION
58 #define BOOST_MULTI_INDEX_DISABLE_SERIALIZATION 1
61 #ifndef BOOST_BIMAP_DISABLE_SERIALIZATION
62 #include <boost/serialization/nvp.hpp>
63 #endif // BOOST_BIMAP_DISABLE_SERIALIZATION
66 #include <boost/bimap/detail/bimap_core.hpp>
67 #include <boost/bimap/detail/map_view_base.hpp>
68 #include <boost/bimap/detail/modifier_adaptor.hpp>
69 #include <boost/bimap/relation/support/data_extractor.hpp>
70 #include <boost/bimap/relation/support/member_with_tag.hpp>
72 #include <boost/bimap/support/map_type_by.hpp>
73 #include <boost/bimap/support/map_by.hpp>
74 #include <boost/bimap/support/iterator_type_by.hpp>
76 /// \brief The namespace where all the boost libraries lives.
80 /// \brief Boost.Bimap library namespace
82 All the entities in the library are defined in this namespace.
86 /// \brief The bimap class is the entry point to the library.
88 This class manages the instantiation of the desired bimap type.
89 As there are several types of bidirectional maps that can be
90 created using it. the main job of it is to find the desired
91 type. This is done using metaprogramming to obtain the relation
92 type that will be stored, the map_view type of each side and
93 the set_view type of the general relationship. The instantiation
94 is kept simple using an extended standard set theory, where a
95 bidirectional map type is defined by the set types it relates.
96 For example, a bidirectional map that has multimap semantics
97 viewed from both sides is defined by specifying that the two
98 keys sets are of \c multiset_of<Key> type.
99 This allows the bimap class to support seamingless N-N, 1-N,
100 ordered/unordered and even vector-list types of mapping.
101 The three last parameters are used to specify the set type of
102 the relation, an inplace hooked data class and the allocator
103 type. As a help to the bimap user, these parameters support
104 default types but use a special idiom that allow them to be
105 specified without interleaving the usual use_default keyword.
106 The possible bimap instantiation are enumerated here:
107 \c {Side}KeyType can be directly a type, this is default to
108 \c set_of<{Side}KeyType>, or can be a \c {SetType}_of<Type>
109 specification. Additionally this two parameters can be tagged
110 to specify others tags instead of the usual \c member_at::{Side}
118 LeftCollectionType, RightCollectionType
120 [ , SetTypeOfRelation ] // Default to left_based
121 [ , info_hook< Info > ] // Default to no info
122 [ , Allocator ] // Default to std::allocator<>
133 class KeyTypeA, class KeyTypeB,
134 class AP1 = ::boost::mpl::na,
135 class AP2 = ::boost::mpl::na,
136 class AP3 = ::boost::mpl::na
140 // Bimap Core, use mpl magic to find the desired bimap type
142 public ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>,
144 // You can use bimap as a collection of relations
146 public ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>
149 // Include extra typedefs (i.e. left_local_iterator for unordered_map)
151 public ::boost::bimaps::detail:: left_map_view_extra_typedefs<
152 BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::left_map_view_type<
153 ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>
156 public ::boost::bimaps::detail::right_map_view_extra_typedefs<
157 BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::right_map_view_type<
158 ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>
162 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::
163 bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3> base_;
165 BOOST_DEDUCED_TYPENAME base_::core_type core;
169 // metadata --------------------------------------------------------
172 // The rest is computed in the core, because it is quite difficult to
173 // expose a nice interface with so many metaprogramming stuff.
174 // Here it is the complete metadat list.
176 // Map by {side} metadata
178 typedef -unspecified- {side}_tag;
179 typedef -unspecified- {side}_data_type;
180 typedef -unspecified- {side}_value_type;
181 typedef -unspecified- {side}_key_type;
182 typedef -unspecified- {side}_iterator;
183 typedef -unspecified- {side}_const_iterator;
185 ------------------------------------------------------------------*/
187 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::
188 left_map_view_type<base_>::type left_map;
189 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::
190 right_map_view_type<base_>::type right_map;
192 typedef BOOST_DEDUCED_TYPENAME
193 left_map::reference left_reference;
194 typedef BOOST_DEDUCED_TYPENAME
195 left_map::const_reference left_const_reference;
197 typedef BOOST_DEDUCED_TYPENAME
198 right_map::reference right_reference;
199 typedef BOOST_DEDUCED_TYPENAME
200 right_map::const_reference right_const_reference;
202 typedef BOOST_DEDUCED_TYPENAME base_::relation::info_type info_type;
213 ::boost::multi_index::get<
214 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag
218 ::boost::multi_index::get<
219 BOOST_DEDUCED_TYPENAME base_::logic_left_tag
223 ::boost::multi_index::get<
224 BOOST_DEDUCED_TYPENAME base_::logic_right_tag
230 template< class InputIterator >
231 bimap(InputIterator first,InputIterator last) :
234 ::boost::multi_index::get<
235 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag
242 ::boost::multi_index::get<
243 BOOST_DEDUCED_TYPENAME base_::logic_left_tag
247 ::boost::multi_index::get<
248 BOOST_DEDUCED_TYPENAME base_::logic_right_tag
254 bimap(const bimap& x) :
257 ::boost::multi_index::get<
258 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag
265 ::boost::multi_index::get<
266 BOOST_DEDUCED_TYPENAME base_::logic_left_tag
270 ::boost::multi_index::get<
271 BOOST_DEDUCED_TYPENAME base_::logic_right_tag
277 bimap& operator=(const bimap& x)
283 // Projection of iterators
285 template< class IteratorType >
286 BOOST_DEDUCED_TYPENAME base_::left_iterator
287 project_left(IteratorType iter)
289 return core.template project<
290 BOOST_DEDUCED_TYPENAME base_::logic_left_tag>(iter.base());
293 template< class IteratorType >
294 BOOST_DEDUCED_TYPENAME base_::left_const_iterator
295 project_left(IteratorType iter) const
297 return core.template project<
298 BOOST_DEDUCED_TYPENAME base_::logic_left_tag>(iter.base());
301 template< class IteratorType >
302 BOOST_DEDUCED_TYPENAME base_::right_iterator
303 project_right(IteratorType iter)
305 return core.template project<
306 BOOST_DEDUCED_TYPENAME base_::logic_right_tag>(iter.base());
309 template< class IteratorType >
310 BOOST_DEDUCED_TYPENAME base_::right_const_iterator
311 project_right(IteratorType iter) const
313 return core.template project<
314 BOOST_DEDUCED_TYPENAME base_::logic_right_tag>(iter.base());
317 template< class IteratorType >
318 BOOST_DEDUCED_TYPENAME base_::relation_set::iterator
319 project_up(IteratorType iter)
321 return core.template project<
322 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag>(iter.base());
325 template< class IteratorType >
326 BOOST_DEDUCED_TYPENAME base_::relation_set::const_iterator
327 project_up(IteratorType iter) const
329 return core.template project<
330 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag>(iter.base());
335 template< class Tag, class IteratorType >
336 BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
337 iterator_type_by<Tag,bimap>::type
338 project(IteratorType iter
339 BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(Tag))
341 return core.template project<Tag>(iter.base());
344 template< class Tag, class IteratorType >
345 BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
346 const_iterator_type_by<Tag,bimap>::type
347 project(IteratorType iter
348 BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(Tag)) const
350 return core.template project<Tag>(iter.base());
353 template< class Tag >
355 public ::boost::bimaps::support::map_type_by<Tag,bimap>::type
357 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
358 map_type_by<Tag,bimap>::type type;
363 template< class Tag >
364 BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
365 map_type_by<Tag,bimap>::type &
366 by(BOOST_EXPLICIT_TEMPLATE_TYPE(Tag))
368 return ::boost::bimaps::support::map_by<Tag>(*this);
371 template< class Tag >
372 const BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
373 map_type_by<Tag,bimap>::type &
374 by(BOOST_EXPLICIT_TEMPLATE_TYPE(Tag)) const
376 return ::boost::bimaps::support::map_by<Tag>(*this);
380 #ifndef BOOST_BIMAP_DISABLE_SERIALIZATION
382 // Serialization support
386 friend class boost::serialization::access;
388 template<class Archive>
389 void serialize(Archive & ar, const unsigned int version)
391 ar & serialization::make_nvp("mi_core",core);
394 #endif // BOOST_BIMAP_DISABLE_SERIALIZATION
397 } // namespace bimaps
401 /** \namespace boost::bimaps::support
402 \brief Metafunctions to help working with bimaps.
405 /** \namespace boost::bimaps::views
409 /** \namespace boost::bimaps::views::detail
410 \brief Bimap views details.
415 // Include basic tools for user commodity
417 #include <boost/bimap/tags/tagged.hpp>
418 #include <boost/bimap/relation/member_at.hpp>
419 #include <boost/multi_index/detail/unbounded.hpp>
421 // Bring the most used namespaces directly to the user main namespace
425 using ::boost::bimaps::tags::tagged;
427 namespace member_at = ::boost::bimaps::relation::member_at;
429 using ::boost::multi_index::unbounded;
431 } // namespace bimaps
435 #endif // BOOST_BIMAP_BIMAP_HPP