1++++++++++++++++++++++++++++++++++
2 |Boost| Pointer Container Library
3++++++++++++++++++++++++++++++++++
4
5.. |Boost| image:: boost.png
6
7Class ``ptr_map_adapter``
8-------------------------
9
10This class is used to build custom pointer containers with
11an underlying map-like container. The interface of the class is an extension
12of the interface from ``associative_ptr_container``.
13
14**Hierarchy:**
15
16- `reversible_ptr_container <reversible_ptr_container.html>`_
17
18  - `associative_ptr_container <associative_ptr_container.html>`_
19
20    - `ptr_set_adapter <ptr_set_adapter.html>`_
21    - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_
22    - ``ptr_map_adapter``
23    - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_
24
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>`_
29
30**Navigate:**
31
32- `home <ptr_container.html>`_
33- `reference <reference.html>`_
34
35**Synopsis:**
36
37.. parsed-literal::
38
39
40        namespace boost
41        {
42            template
43            <
44                class T,
45                class VoidPtrMap,
46                class CloneAllocator = heap_clone_allocator
47            >
48            class ptr_map_adapter
49            {
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;
58		typedef ...                  pointer;
59		typedef ...                  const_pointer;
60
61            public: // `modifiers`_
62                std::pair<iterator,bool>  insert( key_type& k, T* x );
63		template< class U >
64		std::pair<iterator,bool>  insert( const key_type& k, compatible-smart-ptr<U> x );
65
66            public; // `lookup`_
67                T&       operator[]( const key_type& key );
68                T&       at( const key_type& key );
69                const T& at( const key_type& key ) const;
70
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 );
77
78            }; //  class 'ptr_map_adapter'
79
80        } // namespace 'boost'
81
82
83Semantics
84---------
85
86.. _`typedefs`:
87
88Semantics: typedefs
89^^^^^^^^^^^^^^^^^^^
90
91The following types are implementation defined::
92
93	typedef ... value_type;
94	typedef ... reference;
95	typedef ... const_reference;
96	typedef ... pointer;
97	typedef ... const_pointer;
98
99However, the structure of the type mimics ``std::pair`` s.t. one
100can use ``first`` and ``second`` members. The reference-types
101are not real references and the pointer-types are not real pointers.
102However, one may still write ::
103
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);
112
113The difference compared to ``std::map<Key,T*>`` is that constness
114is propagated to the pointer (that is, to ``second``) in ``const_itertor``.
115
116.. _`modifiers`:
117
118Semantics: modifiers
119^^^^^^^^^^^^^^^^^^^^
120
121- ``std::pair<iterator,bool> insert( key_type& k, value_type x );``
122
123    - Requirements: ``x != 0``
124
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``.
126
127    - Throws: bad_pointer if ``x == 0``
128
129    - Exception safety: Strong guarantee
130
131
132- ``template< class U > std::pair<iterator,bool> insert( const key_type& k, compatible-smart-ptr<U> x );``
133
134   - Equivalent to (but without the ``const_cast``): ``return insert( const_cast<key_type&>(k), x.release() );``
135
136..
137        - ``std::pair<iterator,bool> insert( key_type& k, const_reference x );``
138
139        - Effects: ``return insert( allocate_clone( x ) );``
140
141        - Exception safety: Strong guarantee
142
143
144.. _`lookup`:
145
146Semantics: lookup
147^^^^^^^^^^^^^^^^^
148
149- ``T& operator[]( const key_type& key );``
150
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
153
154- ``T&       at( const key_type& key );``
155- ``const T& at( const key_type& jey ) const;``
156
157    - Requirement: the key exists
158    - Throws: ``bad_ptr_container_operation`` if the key does not exist
159
160.. _`pointer container requirements`:
161
162Semantics: pointer container requirements
163^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
164
165- ``bool transfer( iterator object, ptr_map_adapter& from );``
166
167   - Requirements: ``not from.empty()``
168
169   - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``
170     iff no equivalent object exists.
171
172   - Returns: whether the object was transfered
173
174   - Exception safety: Strong guarantee
175
176- ``size_type transfer( iterator first, iterator last, ptr__set_adapter& from );``
177
178   - Requirements: ``not from.empty()``
179
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.
182
183   - Returns: the number of transfered objects
184
185   - Exception safety: Basic guarantee
186
187- ``template< class Range > void transfer( const Range& r, ptr_map_adapter& from );``
188
189    - Effects: ``return transfer( boost::begin(r), boost::end(r), from );``
190
191- ``size_type transfer( ptr_set_adapter& from );``
192
193   - Effects: ``return transfer( from.begin(), from.end(), from );``.
194
195.. raw:: html
196
197        <hr>
198
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__).
200
201__ http://www.boost.org/LICENSE_1_0.txt
202
203
204