1++++++++++++++++++++++++++++++++++ 2 |Boost| Pointer Container Library 3++++++++++++++++++++++++++++++++++ 4 5.. |Boost| image:: boost.png 6 7========= 8Reference 9========= 10 11The documentation is divided into an explanation for 12each container. When containers have the same interface, that common interface is explained only once, 13but links are always provided to more relevant information. 14Please make sure you understand 15the `Clonable <reference.html#the-Clonable-concept>`_ concept and 16the `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 78The Clonable concept 79++++++++++++++++++++ 80 81**Refinement of** 82 83- Heap Allocable 84- Heap Deallocable 85 86The Clonable concept is introduced to formalize the requirements for 87copying heap-allocated objects. A type ``T`` might be Clonable even though it 88is not Assignable or Copy Constructible. Notice that many operations on 89the 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 107Default implementation 108---------------------- 109 110In the ``<boost/ptr_container/clone_allocator.hpp>`` header a default implementation 111of 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 131Notice that this implementation makes normal Copy Constructible classes automatically 132Clonable unless ``operator new()`` or ``operator delete()`` are hidden. 133 134The two functions represent a layer of indirection which is necessary to support 135classes that are not Copy Constructible by default. Notice that the implementation 136relies 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 138the function in the boost namespace, but it can be placed together with 139the rest of the interface of the class. If you are implementing a class 140inline 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 144The Clone Allocator concept 145+++++++++++++++++++++++++++ 146 147The Clone Allocator concept is introduced to formalize the way 148pointer containers control memory of 149the stored objects (and not the pointers to the stored objects). 150The clone allocator allows 151users to apply custom allocators/deallocators for the cloned objects. 152 153More information can be found below: 154 155.. contents:: :depth: 1 156 :local: 157 158 159Clone 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 183The library comes with two predefined clone allocators. 184 185Class ``heap_clone_allocator`` 186------------------------------ 187 188This is the default clone allocator used by all pointer containers. For most 189purposes 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 213Notice that the above definition allows you to support custom allocation 214schemes by relying on ``new_clone()`` and ``delete_clone()``. 215 216Class ``view_clone_allocator`` 217------------------------------ 218 219This class provides a way to remove ownership properties of the 220pointer containers. As its name implies, this means that you can 221instead use the pointer containers as a view into an existing 222container. 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 250Class hierarchy 251+++++++++++++++ 252 253The library consists of the following types of classes: 254 2551. Pointer container adapters 256 257.. 258 2592. Pointer containers 260 261The pointer container adapters are used when you 262want to make a pointer container starting from 263your own "normal" container. For example, you 264might have a map class that extends ``std::map`` 265in some way; the adapter class then allows you 266to use your map class as a basis for a new 267pointer container. 268 269The library provides an adapter for each type 270of 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 294The pointer containers of this library are all built using 295the adapters. There is a pointer container 296for 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 319Serialization 320+++++++++++++ 321 322As of version 1.34.0 of Boost, the library supports 323serialization via `Boost.Serialization`__. 324 325.. __: ../../serialization/index.html 326 327Of course, for serialization to work it is required 328that the stored type itself is serializable. For maps, both 329the key type and the mapped type must be serializable. 330 331When dealing with serialization (and serialization of polymophic objects in particular), 332pay special attention to these parts of Boost.Serialization: 333 3341. 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 3562. 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 3723. 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 383Remember 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 411Class ``nullable`` 412++++++++++++++++++ 413 414The purpose of the class is simply to tell the containers 415that null values should be allowed. Its definition is 416trivial:: 417 418 namespace boost 419 { 420 template< class T > 421 struct nullable 422 { 423 typedef T type; 424 }; 425 } 426 427Please notice that ``nullable`` has no effect on the containers 428interface (except for ``is_null()`` functions). For example, it 429does 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 436Exception classes 437+++++++++++++++++ 438 439There are three exceptions that are thrown by this library. The exception 440hierarchy 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 465Disabling the use of exceptions 466+++++++++++++++++++++++++++++++ 467 468As of version 1.34.0 of Boost, the library allows you to disable exceptions 469completely. This means the library is more fit for domains where exceptions 470are not used. Furthermore, it also speeds up a operations a little. Instead 471of throwing an exception, the library simply calls `BOOST_ASSERT`__. 472 473.. __: ../../utility/assert.html 474 475To 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 480It is, however, recommended that you define the macro on the command-line, so 481you are absolutely certain that all headers are compiled the same way. Otherwise 482you might end up breaking the One Definition Rule. 483 484If ``BOOST_NO_EXCEPTIONS`` is defined, then ``BOOST_PTR_CONTAINER_NO_EXCEPTIONS`` 485is 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 504