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 #define BOOST_MULTI_INDEX_DISABLE_SERIALIZATION
59 #ifndef BOOST_BIMAP_DISABLE_SERIALIZATION
60 #include <boost/serialization/nvp.hpp>
61 #endif // BOOST_BIMAP_DISABLE_SERIALIZATION
64 #include <boost/bimap/detail/bimap_core.hpp>
65 #include <boost/bimap/detail/map_view_base.hpp>
66 #include <boost/bimap/detail/modifier_adaptor.hpp>
67 #include <boost/bimap/relation/support/data_extractor.hpp>
68 #include <boost/bimap/relation/support/member_with_tag.hpp>
70 #include <boost/bimap/support/map_type_by.hpp>
71 #include <boost/bimap/support/map_by.hpp>
72 #include <boost/bimap/support/iterator_type_by.hpp>
74 /// \brief The namespace where all the boost libraries lives.
78 /// \brief Boost.Bimap library namespace
80 All the entities in the library are defined in this namespace.
84 /// \brief The bimap class is the entry point to the library.
86 This class manages the instantiation of the desired bimap type.
87 As there are several types of bidirectional maps that can be
88 created using it. the main job of it is to find the desired
89 type. This is done using metaprogramming to obtain the relation
90 type that will be stored, the map_view type of each side and
91 the set_view type of the general relationship. The instantiation
92 is kept simple using an extended standard set theory, where a
93 bidirectional map type is defined by the set types it relates.
94 For example, a bidirectional map that has multimap semantics
95 viewed from both sides is defined by specifying that the two
96 keys sets are of \c multiset_of<Key> type.
97 This allows the bimap class to support seamingless N-N, 1-N,
98 ordered/unordered and even vector-list types of mapping.
99 The three last parameters are used to specify the set type of
100 the relation, an inplace hooked data class and the allocator
101 type. As a help to the bimap user, these parameters support
102 default types but use a special idiom that allow them to be
103 specified without interleaving the usual use_default keyword.
104 The possible bimap instantiation are enumerated here:
105 \c {Side}KeyType can be directly a type, this is default to
106 \c set_of<{Side}KeyType>, or can be a \c {SetType}_of<Type>
107 specification. Additionally this two parameters can be tagged
108 to specify others tags instead of the usual \c member_at::{Side}
116 LeftCollectionType, RightCollectionType
118 [ , SetTypeOfRelation ] // Default to left_based
119 [ , info_hook< Info > ] // Default to no info
120 [ , Allocator ] // Default to std::allocator<>
131 class KeyTypeA, class KeyTypeB,
132 class AP1 = ::boost::mpl::na,
133 class AP2 = ::boost::mpl::na,
134 class AP3 = ::boost::mpl::na
138 // Bimap Core, use mpl magic to find the desired bimap type
140 public ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>,
142 // You can use bimap as a collection of relations
144 public ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>
147 // Include extra typedefs (i.e. left_local_iterator for unordered_map)
149 public ::boost::bimaps::detail:: left_map_view_extra_typedefs<
150 BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::left_map_view_type<
151 ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>
154 public ::boost::bimaps::detail::right_map_view_extra_typedefs<
155 BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::right_map_view_type<
156 ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>
160 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::
161 bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3> base_;
163 BOOST_DEDUCED_TYPENAME base_::core_type core;
167 // metadata --------------------------------------------------------
170 // The rest is computed in the core, because it is quite difficult to
171 // expose a nice interface with so many metaprogramming stuff.
172 // Here it is the complete metadat list.
174 // Map by {side} metadata
176 typedef -unspecified- {side}_tag;
177 typedef -unspecified- {side}_data_type;
178 typedef -unspecified- {side}_value_type;
179 typedef -unspecified- {side}_key_type;
180 typedef -unspecified- {side}_iterator;
181 typedef -unspecified- {side}_const_iterator;
183 ------------------------------------------------------------------*/
185 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::
186 left_map_view_type<base_>::type left_map;
187 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::
188 right_map_view_type<base_>::type right_map;
190 typedef BOOST_DEDUCED_TYPENAME
191 left_map::reference left_reference;
192 typedef BOOST_DEDUCED_TYPENAME
193 left_map::const_reference left_const_reference;
195 typedef BOOST_DEDUCED_TYPENAME
196 right_map::reference right_reference;
197 typedef BOOST_DEDUCED_TYPENAME
198 right_map::const_reference right_const_reference;
200 typedef BOOST_DEDUCED_TYPENAME base_::relation::info_type info_type;
211 ::boost::multi_index::get<
212 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag
216 ::boost::multi_index::get<
217 BOOST_DEDUCED_TYPENAME base_::logic_left_tag
221 ::boost::multi_index::get<
222 BOOST_DEDUCED_TYPENAME base_::logic_right_tag
228 template< class InputIterator >
229 bimap(InputIterator first,InputIterator last) :
232 ::boost::multi_index::get<
233 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag
240 ::boost::multi_index::get<
241 BOOST_DEDUCED_TYPENAME base_::logic_left_tag
245 ::boost::multi_index::get<
246 BOOST_DEDUCED_TYPENAME base_::logic_right_tag
252 bimap(const bimap& x) :
255 ::boost::multi_index::get<
256 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag
263 ::boost::multi_index::get<
264 BOOST_DEDUCED_TYPENAME base_::logic_left_tag
268 ::boost::multi_index::get<
269 BOOST_DEDUCED_TYPENAME base_::logic_right_tag
275 bimap& operator=(const bimap& x)
281 // Projection of iterators
283 template< class IteratorType >
284 BOOST_DEDUCED_TYPENAME base_::left_iterator
285 project_left(IteratorType iter)
287 return core.template project<
288 BOOST_DEDUCED_TYPENAME base_::logic_left_tag>(iter.base());
291 template< class IteratorType >
292 BOOST_DEDUCED_TYPENAME base_::left_const_iterator
293 project_left(IteratorType iter) const
295 return core.template project<
296 BOOST_DEDUCED_TYPENAME base_::logic_left_tag>(iter.base());
299 template< class IteratorType >
300 BOOST_DEDUCED_TYPENAME base_::right_iterator
301 project_right(IteratorType iter)
303 return core.template project<
304 BOOST_DEDUCED_TYPENAME base_::logic_right_tag>(iter.base());
307 template< class IteratorType >
308 BOOST_DEDUCED_TYPENAME base_::right_const_iterator
309 project_right(IteratorType iter) const
311 return core.template project<
312 BOOST_DEDUCED_TYPENAME base_::logic_right_tag>(iter.base());
315 template< class IteratorType >
316 BOOST_DEDUCED_TYPENAME base_::relation_set::iterator
317 project_up(IteratorType iter)
319 return core.template project<
320 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag>(iter.base());
323 template< class IteratorType >
324 BOOST_DEDUCED_TYPENAME base_::relation_set::const_iterator
325 project_up(IteratorType iter) const
327 return core.template project<
328 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag>(iter.base());
333 template< class Tag, class IteratorType >
334 BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
335 iterator_type_by<Tag,bimap>::type
336 project(IteratorType iter
337 BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(Tag))
339 return core.template project<Tag>(iter.base());
342 template< class Tag, class IteratorType >
343 BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
344 const_iterator_type_by<Tag,bimap>::type
345 project(IteratorType iter
346 BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(Tag)) const
348 return core.template project<Tag>(iter.base());
351 template< class Tag >
353 public ::boost::bimaps::support::map_type_by<Tag,bimap>::type
355 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
356 map_type_by<Tag,bimap>::type type;
361 template< class Tag >
362 BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
363 map_type_by<Tag,bimap>::type &
364 by(BOOST_EXPLICIT_TEMPLATE_TYPE(Tag))
366 return ::boost::bimaps::support::map_by<Tag>(*this);
369 template< class Tag >
370 const BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
371 map_type_by<Tag,bimap>::type &
372 by(BOOST_EXPLICIT_TEMPLATE_TYPE(Tag)) const
374 return ::boost::bimaps::support::map_by<Tag>(*this);
378 #ifndef BOOST_BIMAP_DISABLE_SERIALIZATION
380 // Serialization support
384 friend class boost::serialization::access;
386 template<class Archive>
387 void serialize(Archive & ar, const unsigned int version)
389 ar & serialization::make_nvp("mi_core",core);
392 #endif // BOOST_BIMAP_DISABLE_SERIALIZATION
395 } // namespace bimaps
399 /** \namespace boost::bimaps::support
400 \brief Metafunctions to help working with bimaps.
403 /** \namespace boost::bimaps::views
407 /** \namespace boost::bimaps::views::detail
408 \brief Bimap views details.
413 // Include basic tools for user commodity
415 #include <boost/bimap/tags/tagged.hpp>
416 #include <boost/bimap/relation/member_at.hpp>
417 #include <boost/multi_index/detail/unbounded.hpp>
419 // Bring the most used namespaces directly to the user main namespace
423 using ::boost::bimaps::tags::tagged;
425 namespace member_at = ::boost::bimaps::relation::member_at;
427 using ::boost::multi_index::unbounded;
429 } // namespace bimaps
433 #endif // BOOST_BIMAP_BIMAP_HPP