1++++++++++++++++++++++++++++++++++ 2 |Boost| Pointer Container Library 3++++++++++++++++++++++++++++++++++ 4 5.. |Boost| image:: boost.png 6 7Class ``reversible_ptr_container`` 8------------------------------------ 9 10This class is not a real class that can be found in the library. 11Its purpose is to present the general interface of all the pointer containers. 12 13**Hierarchy:** 14 15- ``reversible_ptr_container`` 16 17 - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ 18 19 - `ptr_vector <ptr_vector.html>`_ 20 - `ptr_list <ptr_list.html>`_ 21 - `ptr_deque <ptr_deque.html>`_ 22 - `ptr_array <ptr_array.html>`_ 23 24 - `associative_ptr_container <associative_ptr_container.html>`_ 25 26 - `ptr_set_adapter <ptr_set_adapter.html>`_ 27 - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ 28 - `ptr_map_adapter <ptr_map_adapter.html>`_ 29 - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ 30 31 - `ptr_set <ptr_set.html>`_ 32 - `ptr_multi_set <ptr_multiset.html>`_ 33 - `ptr_map <ptr_map.html>`_ 34 - `ptr_multimap <ptr_multimap.html>`_ 35 36**Navigate:** 37 38- `home <ptr_container.html>`_ 39- `reference <reference.html>`_ 40 41**synopsis:** 42 43.. parsed-literal:: 44 45 namespace boost 46 { 47 template 48 < 49 class T, 50 class CloneAllocator, 51 class VoidPtrContainer 52 > 53 class reversible_ptr_container 54 { 55 public: // `typedefs`_ 56 typedef T* value_type; 57 typedef T& reference; 58 typedef const T& const_reference; 59 typedef *implementation defined* iterator; 60 typedef *implementation defined* const_iterator; 61 typedef typename VoidPtrContainer::differnce_type difference_type; 62 typedef typename VoidPtrContainer::size_type size_type; 63 typedef typename VoidPtrContainer::allocator_type allocator_type; 64 typedef *implementation defined* reverse_iterator; 65 typedef *implementation defined* const_reverse_iterator; 66 typedef *implementation defined* auto_type; 67 68 public: // `construct/copy/destroy`_ 69 reversible_ptr_container(); 70 explicit reversible_ptr_container( const reversible_ptr_container& r ); 71 template< class Derived > 72 explicit reversible_ptr_container( const reversible_ptr_container<Derived>& r ); 73 explicit reversible_ptr_container( compatible-smart-ptr<reversible_ptr_container> r ); 74 template< class InputIterator > 75 reversible_ptr_container( InputIterator first, InputIterator last ); 76 77 ~reversible_ptr_container(); 78 79 reversible_ptr_container& operator=( const reversible_ptr_container& r ); 80 template<class Derived> 81 reversible_ptr_container& operator=( const reversible_ptr_container<Derived>& r ); 82 reversible_ptr_container& operator=( compatible-smart-ptr<reversible_ptr_container> r ); 83 allocator_type get_allocator() const; 84 85 public: // `iterators`_ 86 iterator begin(); 87 const_iterator begin() const; 88 iterator end(); 89 const_iterator end() const; 90 reverse_iterator rbegin(); 91 const_reverse_iterator rbegin() const; 92 reverse_iterator rend(); 93 const_reverse_iterator rend() const; 94 95 public: // `capacity`_ 96 size_type size() const; 97 size_type max_size() const; 98 bool empty() const; 99 100 public: // `modifiers`_ 101 void swap( reversible_ptr_container& r ); 102 void clear(): 103 VoidPtrContainer& base(); 104 const VoidPtrContainer& base() const; 105 106 public: // `pointer container requirements`_ 107 auto_type replace( iterator position, T* x ); 108 template< class U > 109 auto_type replace( iterator position, compatible-smart-ptr<U> x ); 110 compatible-smart-ptr<reversible_ptr_container> clone() const; 111 compatible-smart-ptr<reversible_ptr_container> release(); 112 auto_type release( iterator position ); 113 114 }; // class 'reversible_ptr_container' 115 116 // `comparison`_ 117 template < class T, class CA, class VPC > 118 bool operator==( const reversible_ptr_container<T,CA,VPC>& x, 119 const reversible_ptr_container<T,CA,VPC>& y); 120 121 template < class T, class CA, class VPC > 122 bool operator<( const reversible_ptr_container<T,CA,VPC>& x, 123 const reversible_ptr_container<T,CA,VPC>& y); 124 125 template < class T, class CA, class VPC > 126 bool operator!=( const reversible_ptr_container<T,CA,VPC>& x, 127 const reversible_ptr_container<T,CA,VPC>& y); 128 129 template < class T, class CA, class VPC > 130 bool operator>( const reversible_ptr_container<T,CA,VPC>& x, 131 const reversible_ptr_container<T,CA,VPC>& y); 132 133 template < class T, class CA, class VPC > 134 bool operator>=( const reversible_ptr_container<T,CA,VPC>& x, 135 const reversible_ptr_container<T,CA,VPC>& y); 136 137 template < class T, class CA, class VPC > 138 bool operator<=( const reversible_ptr_container<T,CA,VPC>& x, 139 const reversible_ptr_container<T,CA,VPC>& y); 140 141 template< class T, class CA, class VPC > 142 void swap( reversible_ptr_container<T,CA,VPC>& x, 143 reversible_ptr_container<T,CA,VPC>& y ); 144 145 // cloneability_ 146 template< class T, class CA, class VPC > 147 reversible_ptr_container<T,CA,VPC>* 148 new_clone( const reversible_ptr_container<T,CA,VPC>& r ); 149 150 // `null predicate`_ 151 template< class Iterator > 152 bool is_null( Iterator i ); 153 154 // `serialization`_ 155 template<class Archive, class T, class CA, class VPC> 156 void serialize( Archive& ar, reversible_ptr_container<T,C�,VPC>& c, const unsigned int version ); 157 158 159 } // namespace 'boost' 160 161 162 163Semantics 164--------- 165 166.. _`typedefs`: 167 168Semantics: typedefs 169^^^^^^^^^^^^^^^^^^^ 170 171Notice how these two types differ: 172 173 174- ``typedef T* value_type;`` 175 176 - notice this has pointer type 177 178- ``typedef T& reference;`` 179 180 - notice this is not a pointer type 181 182This is done to be able to add pointers directly 183to the container, but to hide the pointers externally. 184 185.. 186 - ``typedef *implementation defined* object_type;`` 187 - this is ``T`` for sequences and sets 188 - this is ``std::pair<const Key, void*>`` for maps 189 190Also notice that 191 192- ``typedef ... iterator`` 193 194allows one to iterate over ``T&`` objects, not ``T*``. 195Note that:: 196 197 iterator i = ...; 198 i.base(); 199 200returns an iterator that allows one to iterate over ``void*`` 201elements (*this is very rarely needed and you should not use the 202functionality unless you know what you are doing*). 203 204- ``typedef ... auto_type`` 205 206This declaration hides a pointer pointer type. You can rely on the following 207operations 208 209.. parsed-literal:: 210 211 T* operator->() const; 212 T& operator*() const; 213 T* release(); 214 ~auto_type(); 215 operator *implementation-defined bool*\ (); 216 217 218The destructor will delete the stored object *using the clone allocator of the container* 219(this explains why we cannot use ``std::auto_ptr<T>`` nor ``std::unique_ptr<T>``). It might help to 220think it is just a ``compatible-smart-ptr<T>``. You can also return 221the pointer from a function or assign it to another pointer via the ``move()`` 222function 223 224.. parsed-literal:: 225 226 auto_type ptr = ...; 227 auto_type other = boost::ptr_container::move( ptr ); 228 return boost::ptr_container::move( other ); 229 230.. _construct/copy/destroy: 231 232Semantics: construct/copy/destroy 233^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 234 235- ``reversible_ptr_container();`` 236 237 - Effects: Constructs an empty container 238 239 - Postconditions: ``size() == 0`` 240 241.. 242 - ``reversible_ptr_container( size_type n, const T& x );`` 243 244 - Effects: Constructs a container with ``n`` clones of ``x`` 245 246 - Postconditions: ``size() == n`` 247 248- ``explicit reversible_ptr_container( const reversible_ptr_container& r );`` 249 250 - Effects: Constructs a container by cloning all elements of ``r`` 251 252- ``template< class Derived > explicit reversible_ptr_container( const reversible_ptr_container<Derived>& r );`` 253 254 - Effects: Constructs a container by cloning all elements of ``r`` 255 256 - Requirements: ``Derived`` is derived from ``T`` 257 258- ``explicit reversible_ptr_container( compatible-smart-ptr< reversible_ptr_container > r );`` 259 260 - Effects: Constructs a container by taking ownership of the supplied pointers 261 262 263- ``template< class InputIterator >`` 264 ``reversible_ptr_container( InputIterator first, InputIterator last );`` 265 266 - Requirements: ``(first,last]`` is a valid range 267 268 - Effects: Constructs a container with a cloned range of ``(first,last]`` 269 270 - Postconditions: ``size() == std::distance( first, last )`` 271 272- ``~reversible_ptr_container();`` 273 274 - Effects: Deletes the stored objects via the clone allocator 275 276 - Throws: Nothing 277 278- ``reversible_ptr_container& operator=( const reversible_ptr_container& r );`` 279 280 - Effects: Assigns a clone of ``r`` 281 282 - Exception safety: strong guarantee 283 284- ``template<class Derived> reversible_ptr_container& operator=( const reversible_ptr_container<Derived>& r );`` 285 286 - Effects: Assigns a clone of ``r`` 287 288 - Requirements: ``Derived`` is derived from ``T`` 289 290 - Exception safety: Strong guarantee 291 292- ``reversible_ptr_container& operator=( compatible-smart-ptr<reversible_ptr_container> r );`` 293 294 - Effects: Deletes the stored objects and then takes ownership of the supplied pointers 295 296 - Throws: Nothing 297 298- ``allocator_type get_allocator() const;`` 299 300 - Effects: Returns a copy of the allocator of the container object 301 302 303.. _iterators: 304 305Semantics: iterators 306^^^^^^^^^^^^^^^^^^^^ 307 308**See also:** `iterator invalidation <conventions.html#iterators-are-invalidated-as-in-the-corresponding-standard-container>`_ 309 310- ``iterator begin();`` 311- ``const_iterator begin() const;`` 312 313 - Effects: Returns a mutable/non-mutable iterator with ``value_type T`` 314 315 - Throws: Nothing 316 317- ``iterator end();`` 318- ``const_iterator end() const;`` 319 320 - Effects: Returns a mutable/non-mutable iterator with ``value_type T`` 321 322 - Throws: Nothing 323 324- ``reverse_iterator rbegin();`` 325 326- ``const_reverse_iterator rbegin() const;`` 327 328 - Effects: Returns a mutable/non-mutable reverse iterator with ``value_type T`` 329 330 - Throws: Nothing 331 332- ``reverse_iterator rend();`` 333 334- ``const_reverse_iterator rend() const;`` 335 336 - Effects: Returns a mutable/non-mutable reverse iterator with ``value_type T`` 337 338 - Throws: Nothing 339 340.. _capacity: 341 342Semantics: capacity 343^^^^^^^^^^^^^^^^^^^ 344 345- ``size_type size() const;`` 346 347 - Effects: Returns the number of stored elements 348 349 - Throws: Nothing 350 351- ``size_type max_size() const;`` 352 353 - Effects: Returns the maximum number of stored elements 354 355 - Throws: Nothing 356 357- ``bool empty() const;`` 358 359 - Effects: Returns whether the container is empty or not 360 361 - Throws: Nothing 362 363 364.. _modifiers: 365 366Semantics: modifiers 367^^^^^^^^^^^^^^^^^^^^ 368 369- ``void swap( reversible_ptr_container& r );`` 370 371 - Effects: Swaps the content of the two containers 372 373 - Throws: Nothing 374 375- ``void clear();`` 376 377 - Effects: Destroys all object of the container 378 379 - Postconditions: ``empty() == true`` 380 381 - Throws: Nothing 382 383- ``VoidPtrContainer& base();`` 384 385- ``const VoidPtrContainer& base() const;`` 386 387 - Returns: a reference to the wrapped container 388 389.. _`pointer container requirements`: 390 391Semantics: pointer container requirements 392^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 393 394- ``auto_type replace( iterator position, T* x );`` 395 396 - Requirements: ``not empty() and x != 0`` 397 398 - Effects: returns the object pointed to by ``position`` and replaces it with ``x``. 399 400 - Throws: ``bad_ptr_container_operation`` if the container is empty and ``bad_pointer`` if ``x == 0``. 401 402 - Exception safety: Strong guarantee 403 404- ``template< class U > auto_type replace( iterator position, compatible-smart-ptr<U> x );`` 405 406 - Effects: ``return replace( position, x.release() );`` 407 408- ``compatible-smart-ptr< reversible_ptr_container > clone() const;`` 409 410 - Effects: Returns a deep copy of the container 411 412 - Throws: ``std::bad_alloc`` if there is not enough memory to make a clone of the container 413 414 - Complexity: Linear 415 416- ``compatible-smart-ptr< reversible_ptr_container > release();`` 417 418 - Effects: Releases ownership of the container. This is a useful way of returning a container from a function. 419 420 - Postconditions: ``empty() == true`` 421 422 - Throws: ``std::bad_alloc`` if the return value cannot be allocated 423 424 - Exception safety: Strong guarantee 425 426- ``auto_type release( iterator position );`` 427 428 - Requirements: ``not empty();`` 429 430 - Effects: Releases ownership of the pointer referred to by position 431 432 - Postconditions: ``size()`` is one less 433 434 - Throws: ``bad_ptr_container_operation`` if the container is empty 435 436 - Exception safety: Strong guarantee 437 438 439.. _comparison: 440 441Semantics: comparison 442^^^^^^^^^^^^^^^^^^^^^ 443 444These functions compare the underlying range of objects. 445So :: 446 447 operation( const ptr_container& l, const ptr_container& r ); 448 449has the effect one would expect of normal standard containers. Hence 450objects are compared and not the pointers to objects. 451 452.. _`cloneability`: 453 454Semantics: cloneability 455^^^^^^^^^^^^^^^^^^^^^^^ 456 457- ``template< class T, class CloneAllocator > 458 reversible_ptr_container<T,CA,VPC>* 459 new_clone( const reversible_ptr_container<T,CA,VPC>& r );`` 460 461 462 - Effects: ``return r.clone().release();`` 463 464 - Remarks: This function is only defined for concrete `pointer containers`_, but not for 465 `pointer container adapters`_. 466 467.. _`pointer containers`: ptr_container.html#smart-containers 468.. _`pointer container adapters`: ptr_container.html#smart-container-adapters 469 470.. _`null predicate`: 471 472Semantics: null predicate 473^^^^^^^^^^^^^^^^^^^^^^^^^ 474 475- ``template< class Iterator > bool is_null( Iterator i );`` 476 477 - Requirements: ``i`` is a valid dereferencable iterator 478 479 - Returns: ``*i.base() == 0;`` 480 481.. _`serialization`: 482 483Semantics: serialization 484^^^^^^^^^^^^^^^^^^^^^^^^ 485 486All containers can be serialized by means of 487`Boost.Serialization`__. For an overview, see 488`Serialization of Pointer Containers`_. 489 490.. __: ../../serialization/index.html 491.. _`Serialization of Pointer Containers`: reference.html#serialization 492 493 :: 494 495 template<class Archive, class T, class CA, class VPC> 496 void serialize( Archive& ar, reversible_ptr_container<T,CA,VPC>& c, const unsigned int version ); 497 498 499- Effects: Saves or loads the container to/from the archive. 500 501- Remarks: This function is called automatically be stream operators in 502 Boost.Serialization 503 504- Exception safety: Loading gives the basic guarantee 505 506 507.. raw:: html 508 509 <hr> 510 511:Copyright: Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). 512 513__ http://www.boost.org/LICENSE_1_0.txt 514 515
