1 ++++++++++++++++++++++++++++++++++
2 |Boost| Pointer Container Library
3 ++++++++++++++++++++++++++++++++++
5 .. |Boost| image:: boost.png
7 Class ``ptr_map_adapter``
8 -------------------------
10 This class is used to build custom pointer containers with
11 an underlying map-like container. The interface of the class is an extension
12 of the interface from ``associative_ptr_container``.
16 - `reversible_ptr_container <reversible_ptr_container.html>`_
18 - `associative_ptr_container <associative_ptr_container.html>`_
20 - `ptr_set_adapter <ptr_set_adapter.html>`_
21 - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_
23 - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_
25 - `ptr_set <ptr_set.html>`_
26 - `ptr_multi_set <ptr_multiset.html>`_
27 - `ptr_map <ptr_map.html>`_
28 - `ptr_multimap <ptr_multimap.html>`_
32 - `home <ptr_container.html>`_
33 - `reference <reference.html>`_
46 class CloneAllocator = heap_clone_allocator
50 public: // `typedefs`_
51 typedef VoidPtrMap::key_type key_type;
52 typedef T* mapped_type;
53 typedef T& mapped_reference;
54 typedef const T& const_mapped_reference;
55 typedef ... value_type;
56 typedef ... reference;
57 typedef ... const_reference;
59 typedef ... const_pointer;
61 public: // `modifiers`_
62 std::pair<iterator,bool> insert( key_type& k, T* x );
64 std::pair<iterator,bool> insert( const key_type& k, std::auto_ptr<U> x );
67 T& operator[]( const key_type& key );
68 T& at( const key_type& key );
69 const T& at( const key_type& key ) const;
71 public: // `pointer container requirements`_
72 bool transfer( iterator object, ptr_map_adapter& from );
73 size_type transfer( iterator first, iterator last, ptr_map_adapter& from );
74 template< class Range >
75 size_type transfer( const Range& r, ptr_map_adapter& from );
76 size_type transfer( ptr_map_adapter& from );
78 }; // class 'ptr_map_adapter'
80 } // namespace 'boost'
91 The following types are implementation defined::
93 typedef ... value_type;
94 typedef ... reference;
95 typedef ... const_reference;
97 typedef ... const_pointer;
99 However, the structure of the type mimics ``std::pair`` s.t. one
100 can use ``first`` and ``second`` members. The reference-types
101 are not real references and the pointer-types are not real pointers.
102 However, one may still write ::
104 map_type::value_type a_value = *m.begin();
105 a_value.second->foo();
106 map_type::reference a_reference = *m.begin();
107 a_reference.second->foo();
108 map_type::const_reference a_creference = *const_begin(m);
109 map_type::pointer a_pointer = &*m.begin();
110 a_pointer->second->foo();
111 map_type::const_pointer a_cpointer = &*const_begin(m);
113 The difference compared to ``std::map<Key,T*>`` is that constness
114 is propagated to the pointer (that is, to ``second``) in ``const_itertor``.
121 - ``std::pair<iterator,bool> insert( key_type& k, value_type x );``
123 - Requirements: ``x != 0``
125 - Effects: Takes ownership of ``x`` and insert it iff there is no equivalent of it already. The bool part of the return value indicates insertion and the iterator points to the element with key ``x``.
127 - Throws: bad_pointer if ``x == 0``
129 - Exception safety: Strong guarantee
132 - ``template< class U > std::pair<iterator,bool> insert( const key_type& k, std::auto_ptr<U> x );``
134 - Equivalent to (but without the ``const_cast``): ``return insert( const_cast<key_type&>(k), x.release() );``
137 - ``std::pair<iterator,bool> insert( key_type& k, const_reference x );``
139 - Effects: ``return insert( allocate_clone( x ) );``
141 - Exception safety: Strong guarantee
149 - ``T& operator[]( const key_type& key );``
151 - Effects: returns the object with key ``key`` if it exists; otherwise a new object is allocated and inserted and its reference returned.
152 - Exception-safety: Strong guarantee
154 - ``T& at( const key_type& key );``
155 - ``const T& at( const key_type& jey ) const;``
157 - Requirement: the key exists
158 - Throws: ``bad_ptr_container_operation`` if the key does not exist
160 .. _`pointer container requirements`:
162 Semantics: pointer container requirements
163 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
165 - ``bool transfer( iterator object, ptr_map_adapter& from );``
167 - Requirements: ``not from.empty()``
169 - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``
170 iff no equivalent object exists.
172 - Returns: whether the object was transfered
174 - Exception safety: Strong guarantee
176 - ``size_type transfer( iterator first, iterator last, ptr__set_adapter& from );``
178 - Requirements: ``not from.empty()``
180 - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``.
181 An object is only transferred if no equivalent object exists.
183 - Returns: the number of transfered objects
185 - Exception safety: Basic guarantee
187 - ``template< class Range > void transfer( const Range& r, ptr_map_adapter& from );``
189 - Effects: ``return transfer( boost::begin(r), boost::end(r), from );``
191 - ``size_type transfer( ptr_set_adapter& from );``
193 - Effects: ``return transfer( from.begin(), from.end(), from );``.
199 :Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
201 __ http://www.boost.org/LICENSE_1_0.txt