ceph/src/boost/libs/ptr_container/doc/reversible_ptr_container.rst

   1 ++++++++++++++++++++++++++++++++++
   2  |Boost| Pointer Container Library
   3 ++++++++++++++++++++++++++++++++++
   4
   5 .. |Boost| image:: boost.png
   6
   7 Class ``reversible_ptr_container``
   8 ------------------------------------
   9
  10 This class is not a real class that can be found in the library.
  11 Its 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( std::auto_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=( std::auto_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, std::auto_ptr<U> x );
 110                 std::auto_ptr<reversible_ptr_container>  clone() const;
 111                 std::auto_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
 163 Semantics
 164 ---------
 165
 166 .. _`typedefs`:
 167
 168 Semantics: typedefs
 169 ^^^^^^^^^^^^^^^^^^^
 170
 171 Notice 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
 182 This is done to be able to add pointers directly
 183 to 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
 190 Also notice that
 191
 192 - ``typedef ... iterator``
 193
 194 allows one to iterate over ``T&`` objects, not ``T*``.
 195 Note that::
 196
 197     iterator i = ...;
 198     i.base();
 199
 200 returns an iterator that allows one to iterate over ``void*``
 201 elements (*this is very rarely needed and you should not use the
 202 functionality unless you know what you are doing*).
 203
 204 - ``typedef ... auto_type``
 205
 206 This declaration hides a pointer pointer type. You can rely on the following
 207 operations
 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 The destructor will delete the stored object *using the clone allocator of the container*
 218 (this explains why we cannot use ``std::auto_ptr<T>``). It might help to
 219 think it is just an ``std::auto_ptr<T>``. You can also return
 220 the pointer from a function or assign it to another pointer via the ``move()``
 221 function
 222
 223 .. parsed-literal::
 224
 225     auto_type ptr   = ...;
 226     auto_type other = boost::ptr_container::move( ptr );
 227     return boost::ptr_container::move( other );
 228
 229 .. _construct/copy/destroy:
 230
 231 Semantics: construct/copy/destroy
 232 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 233
 234 - ``reversible_ptr_container();``
 235
 236     - Effects: Constructs an empty container
 237
 238     - Postconditions: ``size() == 0``
 239
 240 ..
 241         - ``reversible_ptr_container( size_type n, const T& x );``
 242
 243         - Effects: Constructs a container with ``n`` clones of ``x``
 244
 245         - Postconditions: ``size() == n``
 246
 247 - ``explicit reversible_ptr_container( const reversible_ptr_container& r );``
 248
 249     - Effects: Constructs a container by cloning all elements of ``r``
 250
 251 - ``template< class Derived > explicit reversible_ptr_container( const reversible_ptr_container<Derived>& r );``
 252
 253     - Effects: Constructs a container by cloning all elements of ``r``
 254
 255     - Requirements: ``Derived`` is derived from ``T``
 256
 257 - ``explicit reversible_ptr_container( std::auto_ptr< reversible_ptr_container > r );``
 258
 259     - Effects: Constructs a container by taking ownership of the supplied pointers
 260
 261
 262 - ``template< class InputIterator >``
 263   ``reversible_ptr_container( InputIterator first, InputIterator last );``
 264
 265     - Requirements: ``(first,last]`` is a valid range
 266
 267     - Effects: Constructs a container with a cloned range of ``(first,last]``
 268
 269     - Postconditions: ``size() == std::distance( first, last )``
 270
 271 - ``~reversible_ptr_container();``
 272
 273     - Effects: Deletes the stored objects via the clone allocator
 274
 275     - Throws: Nothing
 276
 277 - ``reversible_ptr_container& operator=( const reversible_ptr_container& r );``
 278
 279     - Effects: Assigns a clone of ``r``
 280
 281     - Exception safety: strong guarantee
 282
 283 - ``template<class Derived> reversible_ptr_container& operator=( const reversible_ptr_container<Derived>& r );``
 284
 285     - Effects: Assigns a clone of ``r``
 286
 287     - Requirements: ``Derived`` is derived from ``T``
 288
 289     - Exception safety: Strong guarantee
 290
 291 - ``reversible_ptr_container& operator=( std::auto_ptr<reversible_ptr_container> r );``
 292
 293     - Effects: Deletes the stored objects and then takes ownership of the supplied pointers
 294
 295     - Throws: Nothing
 296
 297 - ``allocator_type get_allocator() const;``
 298
 299     - Effects: Returns a copy of the allocator of the container object
 300
 301
 302 .. _iterators:
 303
 304 Semantics: iterators
 305 ^^^^^^^^^^^^^^^^^^^^
 306
 307 **See also:** `iterator invalidation <conventions.html#iterators-are-invalidated-as-in-the-corresponding-standard-container>`_
 308
 309 - ``iterator begin();``
 310 - ``const_iterator begin() const;``
 311
 312     - Effects: Returns a mutable/non-mutable iterator with ``value_type T``
 313
 314     - Throws: Nothing
 315
 316 - ``iterator end();``
 317 - ``const_iterator end() const;``
 318
 319     - Effects: Returns a mutable/non-mutable iterator with ``value_type T``
 320
 321     - Throws: Nothing
 322
 323 - ``reverse_iterator rbegin();``
 324
 325 - ``const_reverse_iterator rbegin() const;``
 326
 327     - Effects: Returns a mutable/non-mutable reverse iterator with ``value_type T``
 328
 329     - Throws: Nothing
 330
 331 - ``reverse_iterator rend();``
 332
 333 - ``const_reverse_iterator rend() const;``
 334
 335     - Effects: Returns a mutable/non-mutable reverse iterator with ``value_type T``
 336
 337     - Throws: Nothing
 338
 339 .. _capacity:
 340
 341 Semantics: capacity
 342 ^^^^^^^^^^^^^^^^^^^
 343
 344 - ``size_type size() const;``
 345
 346     - Effects: Returns the number of stored elements
 347
 348     - Throws: Nothing
 349
 350 - ``size_type max_size() const;``
 351
 352     - Effects: Returns the maximum number of stored elements
 353
 354     - Throws: Nothing
 355
 356 - ``bool empty() const;``
 357
 358     - Effects: Returns whether the container is empty or not
 359
 360     - Throws: Nothing
 361
 362
 363 .. _modifiers:
 364
 365 Semantics: modifiers
 366 ^^^^^^^^^^^^^^^^^^^^
 367
 368 - ``void swap( reversible_ptr_container& r );``
 369
 370     - Effects: Swaps the content of the two containers
 371
 372     - Throws: Nothing
 373
 374 - ``void clear();``
 375
 376     - Effects: Destroys all object of the container
 377
 378     - Postconditions: ``empty() == true``
 379
 380     - Throws: Nothing
 381
 382 - ``VoidPtrContainer& base();``
 383
 384 - ``const VoidPtrContainer& base() const;``
 385
 386     - Returns: a reference to the wrapped container
 387
 388 .. _`pointer container requirements`:
 389
 390 Semantics: pointer container requirements
 391 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 392
 393 - ``auto_type replace( iterator position, T* x );``
 394
 395     - Requirements: ``not empty() and x != 0``
 396
 397     - Effects: returns the object pointed to by ``position`` and replaces it with ``x``.
 398
 399     - Throws: ``bad_ptr_container_operation`` if the container is empty and ``bad_pointer`` if ``x == 0``.
 400
 401     - Exception safety: Strong guarantee
 402
 403 - ``template< class U > auto_type replace( iterator position, std::auto_ptr<U> x );``
 404
 405     - Effects: ``return replace( position, x.release() );``
 406
 407 - ``std::auto_ptr< reversible_ptr_container > clone() const;``
 408
 409     - Effects: Returns a deep copy of the container
 410
 411     - Throws: ``std::bad_alloc`` if there is not enough memory to make a clone of the container
 412
 413     - Complexity: Linear
 414
 415 - ``std::auto_ptr< reversible_ptr_container > release();``
 416
 417     - Effects: Releases ownership of the container. This is a useful way of returning a container from a function.
 418
 419     - Postconditions: ``empty() == true``
 420
 421     - Throws: ``std::bad_alloc`` if the return value cannot be allocated
 422
 423     - Exception safety: Strong guarantee
 424
 425 - ``auto_type release( iterator position );``
 426
 427     - Requirements: ``not empty();``
 428
 429     - Effects: Releases ownership of the pointer referred to by position
 430
 431     - Postconditions: ``size()`` is one less
 432
 433     - Throws: ``bad_ptr_container_operation`` if the container is empty
 434
 435     - Exception safety: Strong guarantee
 436
 437
 438 .. _comparison:
 439
 440 Semantics: comparison
 441 ^^^^^^^^^^^^^^^^^^^^^
 442
 443 These functions compare the underlying range of objects.
 444 So ::
 445
 446         operation( const ptr_container& l, const ptr_container& r );
 447
 448 has the effect one would expect of normal standard containers. Hence
 449 objects are compared and not the pointers to objects.
 450
 451 .. _`cloneability`:
 452
 453 Semantics: cloneability
 454 ^^^^^^^^^^^^^^^^^^^^^^^
 455
 456 -  ``template< class T, class CloneAllocator >
 457    reversible_ptr_container<T,CA,VPC>*
 458    new_clone( const reversible_ptr_container<T,CA,VPC>& r );``
 459
 460
 461     - Effects: ``return r.clone().release();``
 462
 463     - Remarks: This function is only defined for concrete `pointer containers`_, but not for
 464       `pointer container adapters`_.
 465
 466 .. _`pointer containers`: ptr_container.html#smart-containers
 467 .. _`pointer container adapters`: ptr_container.html#smart-container-adapters
 468
 469 .. _`null predicate`:
 470
 471 Semantics: null predicate
 472 ^^^^^^^^^^^^^^^^^^^^^^^^^
 473
 474 - ``template< class Iterator > bool is_null( Iterator i );``
 475
 476     - Requirements: ``i`` is a valid dereferencable iterator
 477
 478     - Returns: ``*i.base() == 0;``
 479
 480 .. _`serialization`:
 481
 482 Semantics: serialization
 483 ^^^^^^^^^^^^^^^^^^^^^^^^
 484
 485 All containers can be serialized by means of
 486 `Boost.Serialization`__. For an overview, see
 487 `Serialization of Pointer Containers`_.
 488
 489 .. __: ../../serialization/index.html
 490 .. _`Serialization of Pointer Containers`: reference.html#serialization
 491
 492  ::
 493
 494     template<class Archive, class T, class CA, class VPC>
 495     void serialize( Archive& ar, reversible_ptr_container<T,CA,VPC>& c, const unsigned int version );
 496
 497
 498 - Effects: Saves or loads the container to/from the archive.
 499
 500 - Remarks: This function is called automatically be stream operators in
 501   Boost.Serialization
 502
 503 - Exception safety: Loading gives the basic guarantee
 504
 505
 506 .. raw:: html
 507
 508         <hr>
 509
 510 :Copyright:     Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
 511
 512 __ http://www.boost.org/LICENSE_1_0.txt
 513