]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ++++++++++++++++++++++++++++++++++ |
2 | |Boost| Pointer Container Library | |
3 | ++++++++++++++++++++++++++++++++++ | |
4 | ||
5 | .. |Boost| image:: boost.png | |
6 | ||
7 | Class ``ptr_multimap_adapter`` | |
8 | ------------------------------ | |
9 | ||
10 | This class is used to build custom pointer containers with | |
11 | an underlying multimap-like container. The interface of the class is an extension | |
12 | of 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&, std::auto_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 | ||
78 | Semantics | |
79 | --------- | |
80 | ||
81 | . _`typedefs`: | |
82 | ||
83 | Semantics: typedefs | |
84 | ^^^^^^^^^^^^^^^^^^^ | |
85 | ||
86 | The 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 | ||
94 | However, the structure of the type mimics ``std::pair`` s.t. one | |
95 | can use ``first`` and ``second`` members. The reference-types | |
96 | are not real references and the pointer-types are not real pointers. | |
97 | However, 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 | ||
108 | The difference compared to ``std::map<Key,T*>`` is that constness | |
109 | is propagated to the pointer (that is, to ``second``) in ``const_itertor``. | |
110 | ||
111 | .. _`modifiers`: | |
112 | ||
113 | Semantics: 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, std::auto_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 | ||
155 | Semantics: 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 |