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
52 #include <boost/config.hpp>
53 #include <boost/bimap/detail/user_interface_config.hpp>
54 #include <boost/mpl/aux_/na.hpp>
56 #ifndef BOOST_BIMAP_DISABLE_SERIALIZATION
57 #include <boost/serialization/nvp.hpp>
58 #endif // BOOST_BIMAP_DISABLE_SERIALIZATION
61 #include <boost/bimap/detail/bimap_core.hpp>
62 #include <boost/bimap/detail/map_view_base.hpp>
63 #include <boost/bimap/detail/modifier_adaptor.hpp>
64 #include <boost/bimap/relation/support/data_extractor.hpp>
65 #include <boost/bimap/relation/support/member_with_tag.hpp>
67 #include <boost/bimap/support/map_type_by.hpp>
68 #include <boost/bimap/support/map_by.hpp>
69 #include <boost/bimap/support/iterator_type_by.hpp>
71 /// \brief The namespace where all the boost libraries lives.
75 /// \brief Boost.Bimap library namespace
77 All the entities in the library are defined in this namespace.
81 /// \brief The bimap class is the entry point to the library.
83 This class manages the instantiation of the desired bimap type.
84 As there are several types of bidirectional maps that can be
85 created using it. the main job of it is to find the desired
86 type. This is done using metaprogramming to obtain the relation
87 type that will be stored, the map_view type of each side and
88 the set_view type of the general relationship. The instantiation
89 is kept simple using an extended standard set theory, where a
90 bidirectional map type is defined by the set types it relates.
91 For example, a bidirectional map that has multimap semantics
92 viewed from both sides is defined by specifying that the two
93 keys sets are of \c multiset_of<Key> type.
94 This allows the bimap class to support seamingless N-N, 1-N,
95 ordered/unordered and even vector-list types of mapping.
96 The three last parameters are used to specify the set type of
97 the relation, an inplace hooked data class and the allocator
98 type. As a help to the bimap user, these parameters support
99 default types but use a special idiom that allow them to be
100 specified without interleaving the usual use_default keyword.
101 The possible bimap instantiation are enumerated here:
102 \c {Side}KeyType can be directly a type, this is default to
103 \c set_of<{Side}KeyType>, or can be a \c {SetType}_of<Type>
104 specification. Additionally this two parameters can be tagged
105 to specify others tags instead of the usual \c member_at::{Side}
113 LeftCollectionType, RightCollectionType
115 [ , SetTypeOfRelation ] // Default to left_based
116 [ , info_hook< Info > ] // Default to no info
117 [ , Allocator ] // Default to std::allocator<>
128 class KeyTypeA, class KeyTypeB,
129 class AP1 = ::boost::mpl::na,
130 class AP2 = ::boost::mpl::na,
131 class AP3 = ::boost::mpl::na
135 // Bimap Core, use mpl magic to find the desired bimap type
137 public ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>,
139 // You can use bimap as a collection of relations
141 public ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>
144 // Include extra typedefs (i.e. left_local_iterator for unordered_map)
146 public ::boost::bimaps::detail:: left_map_view_extra_typedefs<
147 BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::left_map_view_type<
148 ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>
151 public ::boost::bimaps::detail::right_map_view_extra_typedefs<
152 BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::right_map_view_type<
153 ::boost::bimaps::detail::bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3>
157 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::
158 bimap_core<KeyTypeA,KeyTypeB,AP1,AP2,AP3> base_;
160 BOOST_DEDUCED_TYPENAME base_::core_type core;
164 // metadata --------------------------------------------------------
167 // The rest is computed in the core, because it is quite difficult to
168 // expose a nice interface with so many metaprogramming stuff.
170 // Map by {side} metadata
172 typedef -unspecified- {side}_tag;
173 typedef -unspecified- {side}_data_type;
174 typedef -unspecified- {side}_value_type;
175 typedef -unspecified- {side}_key_type;
177 // There are other typedefs for definitions of different map views
179 ------------------------------------------------------------------*/
181 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::
182 left_map_view_type<base_>::type left_map;
183 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::detail::
184 right_map_view_type<base_>::type right_map;
186 typedef BOOST_DEDUCED_TYPENAME
187 left_map::iterator left_iterator;
188 typedef BOOST_DEDUCED_TYPENAME
189 left_map::const_iterator left_const_iterator;
191 typedef BOOST_DEDUCED_TYPENAME
192 right_map::iterator right_iterator;
193 typedef BOOST_DEDUCED_TYPENAME
194 right_map::const_iterator right_const_iterator;
196 typedef BOOST_DEDUCED_TYPENAME
197 left_map::reference left_reference;
198 typedef BOOST_DEDUCED_TYPENAME
199 left_map::const_reference left_const_reference;
201 typedef BOOST_DEDUCED_TYPENAME
202 right_map::reference right_reference;
203 typedef BOOST_DEDUCED_TYPENAME
204 right_map::const_reference right_const_reference;
206 typedef BOOST_DEDUCED_TYPENAME base_::relation::info_type info_type;
208 typedef BOOST_DEDUCED_TYPENAME base_::core_type::allocator_type allocator_type;
216 typedef BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag
217 logic_relation_set_tag;
218 typedef BOOST_DEDUCED_TYPENAME base_::logic_left_tag logic_left_tag;
219 typedef BOOST_DEDUCED_TYPENAME base_::logic_right_tag logic_right_tag;
220 typedef BOOST_DEDUCED_TYPENAME base_::core_type::ctor_args_list
223 bimap(const allocator_type& al = allocator_type()) :
226 ::boost::multi_index::get<
227 logic_relation_set_tag
234 ::boost::multi_index::get<
239 ::boost::multi_index::get<
246 template< class InputIterator >
247 bimap(InputIterator first,InputIterator last,
248 const allocator_type& al = allocator_type()) :
251 ::boost::multi_index::get<
252 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag>(core)
255 core(first,last,ctor_args_list(),al),
258 ::boost::multi_index::get<
259 BOOST_DEDUCED_TYPENAME base_::logic_left_tag>(core)
262 ::boost::multi_index::get<
263 BOOST_DEDUCED_TYPENAME base_::logic_right_tag>(core)
268 bimap(const bimap& x) :
271 ::boost::multi_index::get<
272 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag>(core)
278 ::boost::multi_index::get<
279 BOOST_DEDUCED_TYPENAME base_::logic_left_tag>(core)
282 ::boost::multi_index::get<
283 BOOST_DEDUCED_TYPENAME base_::logic_right_tag>(core)
288 bimap& operator=(const bimap& x)
294 // Projection of iterators
296 template< class IteratorType >
297 left_iterator project_left(IteratorType iter)
299 return core.template project<
300 BOOST_DEDUCED_TYPENAME base_::logic_left_tag>(iter.base());
303 template< class IteratorType >
304 left_const_iterator project_left(IteratorType iter) const
306 return core.template project<
307 BOOST_DEDUCED_TYPENAME base_::logic_left_tag>(iter.base());
310 template< class IteratorType >
311 right_iterator project_right(IteratorType iter)
313 return core.template project<
314 BOOST_DEDUCED_TYPENAME base_::logic_right_tag>(iter.base());
317 template< class IteratorType >
318 right_const_iterator project_right(IteratorType iter) const
320 return core.template project<
321 BOOST_DEDUCED_TYPENAME base_::logic_right_tag>(iter.base());
324 template< class IteratorType >
325 BOOST_DEDUCED_TYPENAME base_::relation_set::iterator
326 project_up(IteratorType iter)
328 return core.template project<
329 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag>(iter.base());
332 template< class IteratorType >
333 BOOST_DEDUCED_TYPENAME base_::relation_set::const_iterator
334 project_up(IteratorType iter) const
336 return core.template project<
337 BOOST_DEDUCED_TYPENAME base_::logic_relation_set_tag>(iter.base());
342 template< class Tag, class IteratorType >
343 BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
344 iterator_type_by<Tag,bimap>::type
345 project(IteratorType iter)
347 return core.template project<Tag>(iter.base());
350 template< class Tag, class IteratorType >
351 BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
352 const_iterator_type_by<Tag,bimap>::type
353 project(IteratorType iter) const
355 return core.template project<Tag>(iter.base());
358 template< class Tag >
360 public ::boost::bimaps::support::map_type_by<Tag,bimap>::type
362 typedef BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
363 map_type_by<Tag,bimap>::type type;
368 template< class Tag >
369 BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
370 map_type_by<Tag,bimap>::type &by()
372 return ::boost::bimaps::support::map_by<Tag>(*this);
375 template< class Tag >
376 const BOOST_DEDUCED_TYPENAME ::boost::bimaps::support::
377 map_type_by<Tag,bimap>::type &by() const
379 return ::boost::bimaps::support::map_by<Tag>(*this);
383 #ifndef BOOST_BIMAP_DISABLE_SERIALIZATION
385 // Serialization support
389 friend class boost::serialization::access;
391 template<class Archive>
392 void serialize(Archive & ar, const unsigned int)
394 ar & serialization::make_nvp("mi_core",core);
397 #endif // BOOST_BIMAP_DISABLE_SERIALIZATION
400 } // namespace bimaps
404 /** \namespace boost::bimaps::support
405 \brief Metafunctions to help working with bimaps.
408 /** \namespace boost::bimaps::views
412 /** \namespace boost::bimaps::views::detail
413 \brief Bimap views details.
418 // Include basic tools for user commodity
420 #include <boost/bimap/tags/tagged.hpp>
421 #include <boost/bimap/relation/member_at.hpp>
422 #include <boost/multi_index/detail/unbounded.hpp>
424 // Bring the most used namespaces directly to the user main namespace
428 using ::boost::bimaps::tags::tagged;
430 namespace member_at = ::boost::bimaps::relation::member_at;
432 using ::boost::multi_index::unbounded;
434 } // namespace bimaps
438 #endif // BOOST_BIMAP_BIMAP_HPP