1 ++++++++++++++++++++++++++++++++++
2 |Boost| Pointer Container Library
3 ++++++++++++++++++++++++++++++++++
5 .. |Boost| image:: boost.png
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.
18 - `Conventions <conventions.html>`_
19 - `The Clonable concept`_
20 - `The Clone Allocator concept`_
24 - `reversible_ptr_container <reversible_ptr_container.html>`_
26 - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_
28 - `ptr_vector <ptr_vector.html>`_
29 - `ptr_list <ptr_list.html>`_
30 - `ptr_deque <ptr_deque.html>`_
31 - `ptr_array <ptr_array.html>`_
33 - `associative_ptr_container <associative_ptr_container.html>`_
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>`_
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>`_
46 - `Indirected functions <indirect_fun.html>`_
47 - `Insert iterators <ptr_inserter.html>`_
49 - `Exception classes`_
50 - `Disabling the use of exceptions`_
54 - Class `reversible_ptr_container <reversible_ptr_container.html>`_
55 - Class `associative_ptr_container <associative_ptr_container.html>`_
56 - `Pointer container adapters`_
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`_
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`_
71 - `ptr_set <ptr_set.html>`_
72 - `ptr_multiset <ptr_multiset.html>`_
73 - `ptr_map <ptr_map.html>`_
74 - `ptr_multimap <ptr_multimap.html>`_
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.
93 ======================= ============================================ =================== =====================
94 **Type** **Object** (``const`` or non-``const``) **Pointer** **Describes**
95 ``T`` ``a`` ``ptr`` A Clonable type
96 ======================= ============================================ =================== =====================
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 ===================================== =========================== ======================================================================================== ===================================
107 Default implementation
108 ----------------------
110 In the ``<boost/ptr_container/clone_allocator.hpp>`` header a default implementation
111 of the two functions is given:
118 inline T* new_clone( const T& t )
124 void delete_clone( const T* t )
131 Notice that this implementation makes normal Copy Constructible classes automatically
132 Clonable unless ``operator new()`` or ``operator delete()`` are hidden.
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.
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.**
144 The Clone Allocator concept
145 +++++++++++++++++++++++++++
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.
153 More information can be found below:
155 .. contents:: :depth: 1
159 Clone Allocator requirements
160 ----------------------------
164 ===================== ============================================= ==================================================
165 **Type** **Object** (``const`` or non-``const``) **Describes**
167 ``T*`` ``ptr`` A pointer to ``T``
168 ===================== ============================================= ==================================================
170 **Valid expressions**
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.
179 ============================================== ============= ============================================================================= =============================================================
183 The library comes with two predefined clone allocators.
185 Class ``heap_clone_allocator``
186 ------------------------------
188 This is the default clone allocator used by all pointer containers. For most
189 purposes you will never have to change this default.
197 struct heap_clone_allocator
200 static U* allocate_clone( const U& r )
202 return new_clone( r );
206 static void deallocate_clone( const U* r )
213 Notice that the above definition allows you to support custom allocation
214 schemes by relying on ``new_clone()`` and ``delete_clone()``.
216 Class ``view_clone_allocator``
217 ------------------------------
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
230 struct view_clone_allocator
233 static U* allocate_clone( const U& r )
235 return const_cast<U*>(&r);
239 static void deallocate_clone( const U* )
248 - `Changing the clone allocator <examples.html#changing-the-clone-allocator>`_
253 The library consists of the following types of classes:
255 1. Pointer container adapters
259 2. Pointer containers
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
269 The library provides an adapter for each type
270 of standard container highlighted as links below:
272 - ``reversible_ptr_container``
274 - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_
281 - ``associative_ptr_container``
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>`_
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.
298 - ``reversible_ptr_container``
300 - ``ptr_sequence_adapter``
302 - `ptr_vector <ptr_vector.html>`_
303 - `ptr_list <ptr_list.html>`_
304 - `ptr_deque <ptr_deque.html>`_
305 - `ptr_array <ptr_array.html>`_
307 - ``associative_ptr_container``
309 - ``ptr_set_adapter``
310 - ``ptr_multiset_adapter``
311 - ``ptr_map_adapter``
312 - ``ptr_multi_map_adapter``
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>`_
322 As of version 1.34.0 of Boost, the library supports
323 serialization via `Boost.Serialization`__.
325 .. __: ../../serialization/index.html
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.
331 When dealing with serialization (and serialization of polymophic objects in particular),
332 pay special attention to these parts of Boost.Serialization:
334 1. Output/saving requires a const-reference::
337 // serialization helper: we can't save a non-const object
340 inline T const& as_const( T const& r )
347 std::ofstream ofs("filename");
348 boost::archive::text_oarchive oa(ofs);
349 oa << as_const(cont);
351 See `Compile time trap when saving a non-const value`__ for
354 .. __: ../../serialization/doc/rationale.html#trap
356 2. Derived classes need to call ``base_object()`` function::
358 struct Derived : Base
360 template< class Archive >
361 void serialize( Archive& ar, const unsigned int version )
363 ar & boost::serialization::base_object<Base>( *this );
368 For details, see `Derived Classes`_.
370 .. _`Derived Classes`: ../../serialization/doc/tutorial.html#derivedclasses
372 3. You need to use ``BOOST_CLASS_EXPORT`` to register the
373 derived classes in your class hierarchy::
375 BOOST_CLASS_EXPORT( Derived )
377 See `Export Key`__ and `Object Tracking`_
380 .. __: ../../serialization/doc/traits.html#export
381 .. _`Object Tracking`: ../../serialization/doc/special.html
383 Remember these three issues and it might save you some trouble.
386 Map iterator operations
387 +++++++++++++++++++++++
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::
395 typedef ptr_map<string,int> map_t;
397 m[ "foo" ] = 4; // insert pair
398 m[ "bar" ] = 5; // ditto
400 for( map_t::iterator i = m.begin(); i != m.end(); ++i )
402 *i += 42; // add 42 to each value
403 cout << "value=" << *i << ", key=" << i.key() << "n";
406 So the difference from the normal map iterator is that
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.
414 The purpose of the class is simply to tell the containers
415 that null values should be allowed. Its definition is
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 ::
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!
439 There are three exceptions that are thrown by this library. The exception
440 hierarchy looks as follows::
445 class bad_ptr_container_operation : public std::exception
448 bad_ptr_container_operation( const char* what );
451 class bad_index : public bad_ptr_container_operation
454 bad_index( const char* what );
457 class bad_pointer : public bad_ptr_container_operation
461 bad_pointer( const char* what );
465 Disabling the use of exceptions
466 +++++++++++++++++++++++++++++++
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`__.
473 .. __: ../../utility/assert.html
475 To disable exceptions, simply define this macro before including any header::
477 #define BOOST_PTR_CONTAINER_NO_EXCEPTIONS 1
478 #include <boost/ptr_container/ptr_vector.hpp>
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.
484 If ``BOOST_NO_EXCEPTIONS`` is defined, then ``BOOST_PTR_CONTAINER_NO_EXCEPTIONS``
493 - `home <ptr_container.html>`_
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__).
501 __ http://www.boost.org/LICENSE_1_0.txt