• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1++++++++++++++++++++++++++++++++++
2 |Boost| Pointer Container Library
3++++++++++++++++++++++++++++++++++
4
5.. |Boost| image:: boost.png
6
7Class ``ptr_multimap_adapter``
8------------------------------
9
10This class is used to build custom pointer containers with
11an underlying multimap-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 <ptr_map_adapter.html>`_
23    - ``ptr_multi_map_adapter``
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                T,
45                class VoidPtrMultiMap,
46                class CloneAllocator = heap_clone_allocator
47            >
48            class ptr_multimap_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                iterator  insert( key_type& k, T* x );
63		template< class U >
64		iterator  insert( const key_type&, compatible-smart-ptr<U> x );
65
66            public: // `pointer container requirements`_
67                void      transfer( iterator object, ptr_multimap_adapter& from );
68                size_type transfer( iterator first, iterator last, ptr_multimap_adapter& from );
69                template< class Range >
70                size_type transfer( const Range& r, ptr_multimap_adapter& from );
71                void      transfer( ptr_multimap_adapter& from );
72
73            }; //  class 'ptr_multimap_adapter'
74
75        } // namespace 'boost'
76
77
78Semantics
79---------
80
81. _`typedefs`:
82
83Semantics: typedefs
84^^^^^^^^^^^^^^^^^^^
85
86The following types are implementation defined::
87
88	typedef ... value_type;
89	typedef ... reference;
90	typedef ... const_reference;
91	typedef ... pointer;
92	typedef ... const_pointer;
93
94However, the structure of the type mimics ``std::pair`` s.t. one
95can use ``first`` and ``second`` members. The reference-types
96are not real references and the pointer-types are not real pointers.
97However, one may still write ::
98
99    map_type::value_type       a_value      = *m.begin();
100    a_value.second->foo();
101    map_type::reference        a_reference  = *m.begin();
102    a_reference.second->foo();
103    map_type::const_reference  a_creference = *const_begin(m);
104    map_type::pointer          a_pointer    = &*m.begin();
105    a_pointer->second->foo();
106    map_type::const_pointer    a_cpointer   = &*const_begin(m);
107
108The difference compared to ``std::map<Key,T*>`` is that constness
109is propagated to the pointer (that is, to ``second``) in ``const_itertor``.
110
111.. _`modifiers`:
112
113Semantics: modifiers
114^^^^^^^^^^^^^^^^^^^^
115
116- ``iterator insert( key_type& k, T* x );``
117
118    - Requirements: ``x != 0``
119
120    - Effects: Takes ownership of ``x`` and returns an iterator pointing to it.
121
122    - Throws: bad_pointer if ``x == 0``
123
124    - Exception safety: Strong guarantee
125
126- ``template< class U > iterator insert( const key_type& k, compatible-smart-ptr<U> x );``
127
128   - Equivalent to (but without the ``const_cast``): ``return insert( const_cast<key_type&>(k), x.release() );``
129
130..
131        - ``iterator insert( key_type& k, const_reference x );``
132
133        - Effects: ``return insert( allocate_clone( x ) );``
134
135        - Exception safety: Strong guarantee
136
137
138.. _`lookup`:
139
140..
141        Semantics: lookup
142        ^^^^^^^^^^^^^^^^^
143
144        - ``reference        operator[]( const Key& key );``
145        - ``const_reference  operator[]( const Key& key ) const;``
146
147            - Requirements: the key exists
148
149            - Effects: returns the object with key ``key``
150
151            - Throws: ``bad_ptr_container_operation`` if the key does not exist
152
153.. _`pointer container requirements`:
154
155Semantics: pointer container requirements
156^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
157
158- ``void transfer( iterator object, ptr_multimap_adapter& from );``
159
160   - Requirements: ``not from.empty()``
161
162   - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``.
163
164   - Postconditions: ``size()`` is one more, ``from.size()`` is one less.
165
166   - Exception safety: Strong guarantee
167
168- ``void transfer( iterator first, iterator last, ptr_multimap_adapter& from );``
169
170   - Requirements: ``not from.empty()``
171
172   - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``.
173
174   - Postconditions: Let ``N == std::distance(first,last);`` then ``size()`` is ``N`` more, ``from.size()`` is ``N`` less.
175
176   - Exception safety: Basic guarantee
177
178- ``template< class Range > void transfer( const Range& r, ptr_multimap_adapter& from );``
179
180    - Effects: ``transfer( boost::begin(r), boost::end(r), from );``
181
182- ``void transfer( ptr_multimap_adapter& from );``
183
184   - Effects: ``transfer( from.begin(), from.end(), from );``.
185
186   - Postconditions: ``from.empty();``
187
188   - Exception safety: Basic guarantee
189
190.. raw:: html
191
192        <hr>
193
194:Copyright:     Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
195
196__ http://www.boost.org/LICENSE_1_0.txt
197
198
199