]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ++++++++++++++++++++++++++++++++++ |
2 | |Boost| Pointer Container Library | |
3 | ++++++++++++++++++++++++++++++++++ | |
4 | ||
5 | .. |Boost| image:: boost.png | |
6 | ||
7 | ========= | |
8 | Reference | |
9 | ========= | |
10 | ||
11 | The documentation is divided into an explanation for | |
12 | each container. When containers have the same interface, that common interface is explained only once, | |
13 | but links are always provided to more relevant information. | |
14 | Please make sure you understand | |
15 | the `Clonable <reference.html#the-Clonable-concept>`_ concept and | |
16 | the `Clone Allocator <reference.html#the-clone-allocator-concept>`_ concept. | |
17 | ||
18 | - `Conventions <conventions.html>`_ | |
19 | - `The Clonable concept`_ | |
20 | - `The Clone Allocator concept`_ | |
21 | ||
22 | - `Class hierarchy`_: | |
23 | ||
24 | - `reversible_ptr_container <reversible_ptr_container.html>`_ | |
25 | ||
26 | - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ | |
27 | ||
28 | - `ptr_vector <ptr_vector.html>`_ | |
29 | - `ptr_list <ptr_list.html>`_ | |
30 | - `ptr_deque <ptr_deque.html>`_ | |
31 | - `ptr_array <ptr_array.html>`_ | |
32 | ||
33 | - `associative_ptr_container <associative_ptr_container.html>`_ | |
34 | ||
35 | - `ptr_set_adapter <ptr_set_adapter.html>`_ | |
36 | - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ | |
37 | - `ptr_map_adapter <ptr_map_adapter.html>`_ | |
38 | - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ | |
39 | ||
40 | - `ptr_set <ptr_set.html>`_ | |
41 | - `ptr_multi_set <ptr_multiset.html>`_ | |
42 | - `ptr_map <ptr_map.html>`_ | |
43 | - `ptr_multimap <ptr_multimap.html>`_ | |
44 | ||
45 | - `Serialization`_ | |
46 | - `Indirected functions <indirect_fun.html>`_ | |
47 | - `Insert iterators <ptr_inserter.html>`_ | |
48 | - `Class nullable`_ | |
49 | - `Exception classes`_ | |
50 | - `Disabling the use of exceptions`_ | |
51 | ||
52 | ||
53 | .. | |
54 | - Class `reversible_ptr_container <reversible_ptr_container.html>`_ | |
55 | - Class `associative_ptr_container <associative_ptr_container.html>`_ | |
56 | - `Pointer container adapters`_ | |
57 | ||
58 | - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ | |
59 | - `ptr_set_adapter <ptr_set_adapter.html>`_ | |
60 | - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ | |
61 | - `ptr_map_adapter <ptr_map_adapter.html>`_ | |
62 | - `ptr_multimap_adapter <ptr_multimap_adapter.html>`_ | |
63 | - `Sequence containers`_ | |
64 | ||
65 | - `ptr_vector <ptr_vector.html>`_ | |
66 | - `ptr_deque <ptr_deque.html>`_ | |
67 | - `ptr_list <ptr_list.html>`_ | |
68 | - `ptr_array <ptr_array.html>`_ | |
69 | - `Associative containers`_ | |
70 | ||
71 | - `ptr_set <ptr_set.html>`_ | |
72 | - `ptr_multiset <ptr_multiset.html>`_ | |
73 | - `ptr_map <ptr_map.html>`_ | |
74 | - `ptr_multimap <ptr_multimap.html>`_ | |
75 | ||
76 | ||
77 | ||
78 | The Clonable concept | |
79 | ++++++++++++++++++++ | |
80 | ||
81 | **Refinement of** | |
82 | ||
83 | - Heap Allocable | |
84 | - Heap Deallocable | |
85 | ||
86 | The Clonable concept is introduced to formalize the requirements for | |
87 | copying heap-allocated objects. A type ``T`` might be Clonable even though it | |
88 | is not Assignable or Copy Constructible. Notice that many operations on | |
89 | the containers do not even require the stored type to be Clonable. | |
90 | ||
91 | **Notation** | |
92 | ||
93 | ======================= ============================================ =================== ===================== | |
94 | **Type** **Object** (``const`` or non-``const``) **Pointer** **Describes** | |
95 | ``T`` ``a`` ``ptr`` A Clonable type | |
96 | ======================= ============================================ =================== ===================== | |
97 | ||
98 | **Valid expressions** | |
99 | ||
100 | ===================================== =========================== ======================================================================================== =================================== | |
101 | **Expression** **Type** **Semantics** **Postcondition** | |
102 | ``new_clone(a);`` ``T*`` Allocate a new object that can be considered equivalent to the ``a`` object ``typeid(*new_clone(a)) == typeid(a)`` | |
103 | ``delete_clone(ptr);`` ``void`` Deallocate an object previously allocated with ``allocate_clone()``. Must not throw | |
104 | ===================================== =========================== ======================================================================================== =================================== | |
105 | ||
106 | ||
107 | Default implementation | |
108 | ---------------------- | |
109 | ||
110 | In the ``<boost/ptr_container/clone_allocator.hpp>`` header a default implementation | |
111 | of the two functions is given: | |
112 | ||
113 | .. parsed-literal:: | |
114 | ||
115 | namespace boost | |
116 | { | |
117 | template< class T > | |
118 | inline T* new_clone( const T& t ) | |
119 | { | |
120 | return new T( t ); | |
121 | } | |
122 | ||
123 | template< class T > | |
124 | void delete_clone( const T* t ) | |
125 | { | |
126 | checked_delete( t ); | |
127 | } | |
128 | } | |
129 | ||
130 | ||
131 | Notice that this implementation makes normal Copy Constructible classes automatically | |
132 | Clonable unless ``operator new()`` or ``operator delete()`` are hidden. | |
133 | ||
134 | The two functions represent a layer of indirection which is necessary to support | |
135 | classes that are not Copy Constructible by default. Notice that the implementation | |
136 | relies on argument-dependent lookup (ADL) to find the right version of | |
137 | ``new_clone()`` and ``delete_clone()``. This means that one does not need to overload or specialize | |
138 | the function in the boost namespace, but it can be placed together with | |
139 | the rest of the interface of the class. If you are implementing a class | |
140 | inline in headers, remember to forward declare the functions. | |
141 | ||
142 | **Warning: We are considering the removal of default implementation above. Therefore always make sure that you overload the functions for your types and do not rely on the defaults in any way.** | |
143 | ||
144 | The Clone Allocator concept | |
145 | +++++++++++++++++++++++++++ | |
146 | ||
147 | The Clone Allocator concept is introduced to formalize the way | |
148 | pointer containers control memory of | |
149 | the stored objects (and not the pointers to the stored objects). | |
150 | The clone allocator allows | |
151 | users to apply custom allocators/deallocators for the cloned objects. | |
152 | ||
153 | More information can be found below: | |
154 | ||
155 | .. contents:: :depth: 1 | |
156 | :local: | |
157 | ||
158 | ||
159 | Clone Allocator requirements | |
160 | ---------------------------- | |
161 | ||
162 | **Notation** | |
163 | ||
164 | ===================== ============================================= ================================================== | |
165 | **Type** **Object** (``const`` or non-``const``) **Describes** | |
166 | ``T`` ``a`` A type | |
167 | ``T*`` ``ptr`` A pointer to ``T`` | |
168 | ===================== ============================================= ================================================== | |
169 | ||
170 | **Valid expressions** | |
171 | ||
172 | ============================================== ============= ============================================================================= ============================================================= | |
173 | **Expression** **Type** **Semantics** **Postcondition** | |
174 | ``CloneAllocator::allocate_clone(a);`` ``T*`` Allocate a new object that can be considered equivalent to the | |
175 | ``a`` object ``typeid(*CloneAllocator::allocate_clone(a)) == typeid(a)`` | |
176 | ``CloneAllocator::deallocate_clone(ptr);`` ``void`` Deallocate an object previously allocated with | |
177 | ``CloneAllocator::allocate_clone()`` or a compatible allocator. | |
178 | Must not throw. | |
179 | ============================================== ============= ============================================================================= ============================================================= | |
180 | ||
181 | ||
182 | ||
183 | The library comes with two predefined clone allocators. | |
184 | ||
185 | Class ``heap_clone_allocator`` | |
186 | ------------------------------ | |
187 | ||
188 | This is the default clone allocator used by all pointer containers. For most | |
189 | purposes you will never have to change this default. | |
190 | ||
191 | **Definition** | |
192 | ||
193 | .. parsed-literal:: | |
194 | ||
195 | namespace boost | |
196 | { | |
197 | struct heap_clone_allocator | |
198 | { | |
199 | template< class U > | |
200 | static U* allocate_clone( const U& r ) | |
201 | { | |
202 | return new_clone( r ); | |
203 | } | |
204 | ||
205 | template< class U > | |
206 | static void deallocate_clone( const U* r ) | |
207 | { | |
208 | delete_clone( r ); | |
209 | } | |
210 | }; | |
211 | } | |
212 | ||
213 | Notice that the above definition allows you to support custom allocation | |
214 | schemes by relying on ``new_clone()`` and ``delete_clone()``. | |
215 | ||
216 | Class ``view_clone_allocator`` | |
217 | ------------------------------ | |
218 | ||
219 | This class provides a way to remove ownership properties of the | |
220 | pointer containers. As its name implies, this means that you can | |
221 | instead use the pointer containers as a view into an existing | |
222 | container. | |
223 | ||
224 | **Definition** | |
225 | ||
226 | .. parsed-literal:: | |
227 | ||
228 | namespace boost | |
229 | { | |
230 | struct view_clone_allocator | |
231 | { | |
232 | template< class U > | |
233 | static U* allocate_clone( const U& r ) | |
234 | { | |
235 | return const_cast<U*>(&r); | |
236 | } | |
237 | ||
238 | template< class U > | |
239 | static void deallocate_clone( const U* ) | |
240 | { | |
241 | // empty | |
242 | } | |
243 | }; | |
244 | } | |
245 | ||
246 | .. **See also** | |
247 | ||
248 | - `Changing the clone allocator <examples.html#changing-the-clone-allocator>`_ | |
249 | ||
250 | Class hierarchy | |
251 | +++++++++++++++ | |
252 | ||
253 | The library consists of the following types of classes: | |
254 | ||
255 | 1. Pointer container adapters | |
256 | ||
257 | .. | |
258 | ||
259 | 2. Pointer containers | |
260 | ||
261 | The pointer container adapters are used when you | |
262 | want to make a pointer container starting from | |
263 | your own "normal" container. For example, you | |
264 | might have a map class that extends ``std::map`` | |
265 | in some way; the adapter class then allows you | |
266 | to use your map class as a basis for a new | |
267 | pointer container. | |
268 | ||
269 | The library provides an adapter for each type | |
270 | of standard container highlighted as links below: | |
271 | ||
272 | - ``reversible_ptr_container`` | |
273 | ||
274 | - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ | |
275 | ||
276 | - ``ptr_vector`` | |
277 | - ``ptr_list`` | |
278 | - ``ptr_deque`` | |
279 | - ``ptr_array`` | |
280 | ||
281 | - ``associative_ptr_container`` | |
282 | ||
283 | - `ptr_set_adapter <ptr_set_adapter.html>`_ | |
284 | - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ | |
285 | - `ptr_map_adapter <ptr_map_adapter.html>`_ | |
286 | - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ | |
287 | ||
288 | - ``ptr_set`` | |
289 | - ``ptr_multi_set`` | |
290 | - ``ptr_map`` | |
291 | - ``ptr_multimap`` | |
292 | ||
293 | ||
294 | The pointer containers of this library are all built using | |
295 | the adapters. There is a pointer container | |
296 | for each type of "normal" standard container highlighted as links below. | |
297 | ||
298 | - ``reversible_ptr_container`` | |
299 | ||
300 | - ``ptr_sequence_adapter`` | |
301 | ||
302 | - `ptr_vector <ptr_vector.html>`_ | |
303 | - `ptr_list <ptr_list.html>`_ | |
304 | - `ptr_deque <ptr_deque.html>`_ | |
305 | - `ptr_array <ptr_array.html>`_ | |
306 | ||
307 | - ``associative_ptr_container`` | |
308 | ||
309 | - ``ptr_set_adapter`` | |
310 | - ``ptr_multiset_adapter`` | |
311 | - ``ptr_map_adapter`` | |
312 | - ``ptr_multi_map_adapter`` | |
313 | ||
314 | - `ptr_set <ptr_set.html>`_ | |
315 | - `ptr_multi_set <ptr_multiset.html>`_ | |
316 | - `ptr_map <ptr_map.html>`_ | |
317 | - `ptr_multimap <ptr_multimap.html>`_ | |
318 | ||
319 | Serialization | |
320 | +++++++++++++ | |
321 | ||
322 | As of version 1.34.0 of Boost, the library supports | |
323 | serialization via `Boost.Serialization`__. | |
324 | ||
325 | .. __: ../../serialization/index.html | |
326 | ||
327 | Of course, for serialization to work it is required | |
328 | that the stored type itself is serializable. For maps, both | |
329 | the key type and the mapped type must be serializable. | |
330 | ||
331 | When dealing with serialization (and serialization of polymophic objects in particular), | |
332 | pay special attention to these parts of Boost.Serialization: | |
333 | ||
334 | 1. Output/saving requires a const-reference:: | |
335 | ||
336 | // | |
337 | // serialization helper: we can't save a non-const object | |
338 | // | |
339 | template< class T > | |
340 | inline T const& as_const( T const& r ) | |
341 | { | |
342 | return r; | |
343 | } | |
344 | ... | |
345 | Container cont; | |
346 | ||
347 | std::ofstream ofs("filename"); | |
348 | boost::archive::text_oarchive oa(ofs); | |
349 | oa << as_const(cont); | |
350 | ||
351 | See `Compile time trap when saving a non-const value`__ for | |
352 | details. | |
353 | ||
354 | .. __: ../../serialization/doc/rationale.html#trap | |
355 | ||
356 | 2. Derived classes need to call ``base_object()`` function:: | |
357 | ||
358 | struct Derived : Base | |
359 | { | |
360 | template< class Archive > | |
361 | void serialize( Archive& ar, const unsigned int version ) | |
362 | { | |
363 | ar & boost::serialization::base_object<Base>( *this ); | |
364 | ... | |
365 | } | |
366 | }; | |
367 | ||
368 | For details, see `Derived Classes`_. | |
369 | ||
370 | .. _`Derived Classes`: ../../serialization/doc/tutorial.html#derivedclasses | |
371 | ||
372 | 3. You need to use ``BOOST_CLASS_EXPORT`` to register the | |
373 | derived classes in your class hierarchy:: | |
374 | ||
375 | BOOST_CLASS_EXPORT( Derived ) | |
376 | ||
377 | See `Export Key`__ and `Object Tracking`_ | |
378 | for details. | |
379 | ||
380 | .. __: ../../serialization/doc/traits.html#export | |
381 | .. _`Object Tracking`: ../../serialization/doc/special.html | |
382 | ||
383 | Remember these three issues and it might save you some trouble. | |
384 | ||
385 | .. | |
386 | Map iterator operations | |
387 | +++++++++++++++++++++++ | |
388 | ||
389 | The map iterators are a bit different compared to the normal ones. The | |
390 | reason is that it is a bit clumsy to access the key and the mapped object | |
391 | through i->first and i->second, and one tends to forget what is what. | |
392 | Moreover, and more importantly, we also want to hide the pointer as much as possibble. | |
393 | The new style can be illustrated with a small example:: | |
394 | ||
395 | typedef ptr_map<string,int> map_t; | |
396 | map_t m; | |
397 | m[ "foo" ] = 4; // insert pair | |
398 | m[ "bar" ] = 5; // ditto | |
399 | ... | |
400 | for( map_t::iterator i = m.begin(); i != m.end(); ++i ) | |
401 | { | |
402 | *i += 42; // add 42 to each value | |
403 | cout << "value=" << *i << ", key=" << i.key() << "n"; | |
404 | } | |
405 | ||
406 | So the difference from the normal map iterator is that | |
407 | ||
408 | - ``operator*()`` returns a reference to the mapped object (normally it returns a reference to a ``std::pair``, and | |
409 | - that the key can be accessed through the ``key()`` function. | |
410 | ||
411 | Class ``nullable`` | |
412 | ++++++++++++++++++ | |
413 | ||
414 | The purpose of the class is simply to tell the containers | |
415 | that null values should be allowed. Its definition is | |
416 | trivial:: | |
417 | ||
418 | namespace boost | |
419 | { | |
420 | template< class T > | |
421 | struct nullable | |
422 | { | |
423 | typedef T type; | |
424 | }; | |
425 | } | |
426 | ||
427 | Please notice that ``nullable`` has no effect on the containers | |
428 | interface (except for ``is_null()`` functions). For example, it | |
429 | does not make sense to do :: | |
430 | ||
431 | boost::ptr_vector< boost::nullable<T> > vec; | |
432 | vec.push_back( 0 ); // ok | |
433 | vec.push_back( new boost::nullable<T> ); // no no! | |
434 | boost::nullable<T>& ref = vec[0]; // also no no! | |
435 | ||
436 | Exception classes | |
437 | +++++++++++++++++ | |
438 | ||
439 | There are three exceptions that are thrown by this library. The exception | |
440 | hierarchy looks as follows:: | |
441 | ||
442 | ||
443 | namespace boost | |
444 | { | |
445 | class bad_ptr_container_operation : public std::exception | |
446 | { | |
447 | public: | |
448 | bad_ptr_container_operation( const char* what ); | |
449 | }; | |
450 | ||
451 | class bad_index : public bad_ptr_container_operation | |
452 | { | |
453 | public: | |
454 | bad_index( const char* what ); | |
455 | }; | |
456 | ||
457 | class bad_pointer : public bad_ptr_container_operation | |
458 | { | |
459 | public: | |
460 | bad_pointer(); | |
461 | bad_pointer( const char* what ); | |
462 | }; | |
463 | } | |
464 | ||
465 | Disabling the use of exceptions | |
466 | +++++++++++++++++++++++++++++++ | |
467 | ||
468 | As of version 1.34.0 of Boost, the library allows you to disable exceptions | |
469 | completely. This means the library is more fit for domains where exceptions | |
470 | are not used. Furthermore, it also speeds up a operations a little. Instead | |
471 | of throwing an exception, the library simply calls `BOOST_ASSERT`__. | |
472 | ||
473 | .. __: ../../utility/assert.html | |
474 | ||
475 | To disable exceptions, simply define this macro before including any header:: | |
476 | ||
477 | #define BOOST_PTR_CONTAINER_NO_EXCEPTIONS 1 | |
478 | #include <boost/ptr_container/ptr_vector.hpp> | |
479 | ||
480 | It is, however, recommended that you define the macro on the command-line, so | |
481 | you are absolutely certain that all headers are compiled the same way. Otherwise | |
482 | you might end up breaking the One Definition Rule. | |
483 | ||
484 | If ``BOOST_NO_EXCEPTIONS`` is defined, then ``BOOST_PTR_CONTAINER_NO_EXCEPTIONS`` | |
485 | is also defined. | |
486 | ||
487 | .. raw:: html | |
488 | ||
489 | <hr> | |
490 | ||
491 | **Navigate:** | |
492 | ||
493 | - `home <ptr_container.html>`_ | |
494 | ||
495 | .. raw:: html | |
496 | ||
497 | <hr> | |
498 | ||
499 | :Copyright: Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). | |
500 | ||
501 | __ http://www.boost.org/LICENSE_1_0.txt | |
502 | ||
503 |