]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ++++++++++++++++++++++++++++++++++ |
2 | |Boost| Pointer Container Library | |
3 | ++++++++++++++++++++++++++++++++++ | |
4 | ||
5 | .. |Boost| image:: boost.png | |
6 | ||
7 | Class ``ptr_map_adapter`` | |
8 | ------------------------- | |
9 | ||
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``. | |
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, std::auto_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 | ||
83 | Semantics | |
84 | --------- | |
85 | ||
86 | .. _`typedefs`: | |
87 | ||
88 | Semantics: typedefs | |
89 | ^^^^^^^^^^^^^^^^^^^ | |
90 | ||
91 | The 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 | ||
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 :: | |
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 | ||
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``. | |
115 | ||
116 | .. _`modifiers`: | |
117 | ||
118 | Semantics: 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, std::auto_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 | ||
146 | Semantics: 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 | ||
162 | Semantics: 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 |