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

   1 ++++++++++++++++++++++++++++++++++
   2  |Boost| Pointer Container Library
   3 ++++++++++++++++++++++++++++++++++
   4
   5 .. |Boost| image:: boost.png
   6
   7 Class ``ptr_sequence_adapter``
   8 ------------------------------
   9
  10 This section describes all the common operations for all the pointer
  11 sequences:
  12
  13 - `ptr_vector <ptr_vector.html>`_
  14 - `ptr_list <ptr_list.html>`_
  15 - `ptr_deque <ptr_deque.html>`_
  16
  17
  18 The ``ptr_sequence_adapter`` is also a concrete class that you can use to create custom pointer
  19 containers from.
  20
  21 **Hierarchy:**
  22
  23 - `reversible_ptr_container <reversible_ptr_container.html>`_
  24
  25   - ``ptr_sequence_adapter``
  26
  27     - `ptr_vector <ptr_vector.html>`_
  28     - `ptr_list <ptr_list.html>`_
  29     - `ptr_deque <ptr_deque.html>`_
  30     - `ptr_array <ptr_array.html>`_
  31
  32 **Navigate:**
  33
  34 - `home <ptr_container.html>`_
  35 - `reference <reference.html>`_
  36
  37
  38 **Synopsis:**
  39
  40 .. parsed-literal::
  41
  42         namespace boost
  43         {
  44
  45             template
  46             <
  47                 class T,
  48                 class VoidPtrSeq,
  49                 class CloneAllocator = heap_clone_allocator
  50             >
  51             class ptr_sequence_adapter
  52             {
  53             public: // `construct/copy/destroy`_
  54                 template< class InputIterator >
  55                 assign( InputIterator first, InputIterator last );
  56                 template< class InputRange >
  57                 assign( const InputRange& e );
  58
  59             public: // `element access`_
  60                 T&        front();
  61                 const T&  front() const;
  62                 T&        back();
  63                 const T&  back() const;
  64
  65             public: // `modifiers`_
  66                 void      push_back( T* x );
  67                 template< class U >
  68                 void      push_back( std::auto_ptr<U> x );
  69                 auto_type pop_back();
  70                 iterator  insert( iterator position, T* x );
  71                 template< class U >
  72                 iterator  insert( iterator position, std::auto_ptr<U> x );
  73                 template< class InputIterator >
  74                 void      insert( iterator position, InputIterator first, InputIterator last );
  75                 template< class InputRange >
  76                 void      insert( iterator position, const InputRange& r );
  77                 iterator  erase( iterator position );
  78                 iterator  erase( iterator first, iterator last );
  79                 template< class Range >
  80                 iterator  erase( const Range& r );
  81                 void      resize( size_type size );
  82                 void      resize( size_type size, T* to_clone );
  83
  84             public: // `pointer container requirements`_
  85                 template< class PtrSequence >
  86                 void transfer( iterator before, typename PtrSequence::iterator object,
  87                                PtrSequence& from );
  88                 template< class PtrSequence >
  89                 void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last,
  90                                PtrSequence& from );
  91                 void template< class PtrSequence, class Range >
  92                 void transfer( iterator before, const Range& r, PtrSequence& from );
  93                 template< class PtrSequence >
  94                 void transfer( iterator before, PtrSequence& from );
  95
  96             public: // `algorithms`_
  97
  98                 void sort();
  99                 void sort( iterator first, iterator last );
 100                 template< class Compare >
 101                 void sort( Compare comp );
 102                 template< class Compare >
 103                 void sort( iterator begin, iterator end, Compare comp );
 104
 105                 void unique();
 106                 void unique( iterator first, iterator last );
 107                 template< class Compare >
 108                 void unique( Compare comp );
 109                 template< class Compare >
 110                 void unique( iterator begin, iterator end, Compare comp );
 111
 112                 template< class Pred >
 113                 void erase_if( Pred pred );
 114                 template< class Pred >
 115                 void erase_if( iterator begin, iterator end, Pred pred );
 116
 117                 void merge( ptr_sequence_adapter& r );
 118                 template< class Compare >
 119                 void merge( ptr_sequence_adapter& r, Compare comp );
 120                 void merge( iterator first, iterator last, ptr_sequence_adapter& from );
 121                 template< class Compare >
 122                 void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp );
 123
 124             public: // `ptr_list interface`_
 125
 126             public: // `ptr_vector interface`_
 127
 128             public: // `ptr_deque interface`_
 129
 130             }; //  class 'ptr_sequence_adapter'
 131
 132         } // namespace 'boost'
 133
 134 .. _`ptr_list interface`: ptr_list.html
 135 .. _`ptr_vector interface`: ptr_vector.html
 136 .. _`ptr_deque interface`: ptr_deque.html
 137
 138 Semantics
 139 ---------
 140
 141 .. _`construct/copy/destroy`:
 142
 143 Semantics: construct/copy/destroy
 144 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 145
 146 - ``template< class InputIterator >
 147   void assign( InputIterator first, InputIterator last );``
 148
 149     - Requirements: ``(first,last]`` is a valid range
 150
 151     - Effects: ``clear(); insert( first, last );``
 152
 153     - Postconditions: ``size() == std::distance( first, last );``
 154
 155     - Exception safety: strong guarantee
 156
 157 - ``template< class InputRange >
 158   void assign( const InputRange& r );``
 159
 160     - Effects: ``assign( boost::begin(r), boost::end(r) );``
 161
 162
 163 ..
 164         - ``assign( size_type n, const T& u )``
 165
 166         - Effects: ``clear(); insert( begin(), n, u );``
 167
 168         - Postconditions: ``size() == n``
 169
 170         - Exception safety: Strong guarantee
 171
 172
 173 ..
 174         void resize( size_type sz, const T& x );
 175         Effects:
 176
 177         if ( sz > size() )
 178             insert( end(), sz-size(), x );
 179             else if ( sz < size() )
 180             erase( begin()+sz, end() );
 181             else
 182             ; //do nothing
 183
 184         Postconditions: size() == sz
 185
 186         Exception safety: Strong guarantee
 187
 188
 189 .. _`element access`:
 190
 191 Semantics: element access
 192 ^^^^^^^^^^^^^^^^^^^^^^^^^
 193
 194 - ``T& front();``
 195
 196     - Requirements: ``not empty();``
 197
 198     - Effects: ``return *begin();``
 199
 200
 201 - ``const T& front() const;``
 202
 203     - Requirements: ``not empty();``
 204
 205     - Effects: ``return *begin();``
 206
 207
 208 - ``T& back();``
 209
 210     - Requirements: ``not empty();``
 211
 212     - Effects: ``return *--end();``
 213
 214
 215 - ``const T& back() const;``
 216
 217     - Requirements: ``not empty();``
 218
 219     - Effects: ``return *--end();``
 220
 221
 222 .. _`modifiers`:
 223
 224 Semantics: modifiers
 225 ^^^^^^^^^^^^^^^^^^^^
 226
 227 - ``void push_back( T* x );``
 228
 229     - Requirements: ``x != 0``
 230
 231     - Effects: Inserts the pointer into container and takes ownership of it
 232
 233     - Throws: ``bad_pointer`` if ``x == 0``
 234
 235     - Exception safety: Strong guarantee
 236
 237 - ``template< class U > void push_back( std::auto_ptr<U> x );``
 238
 239     - Effects: ``push_back( x.release() );``
 240
 241 ..
 242         - ``void push_back( const T& x );``
 243
 244         - Effects: ``push_back( CloneAllocator::clone( x ) );``
 245
 246         - Exception safety: Strong guarantee
 247
 248 - ``auto_type pop_back();``
 249
 250     - Requirements:``not empty()``
 251
 252     - Effects: Removes the last element in the container
 253
 254     - Postconditions: ``size()`` is one less
 255
 256     - Throws: ``bad_ptr_container_operation`` if ``empty() == true``
 257
 258     - Exception safety: Strong guarantee
 259
 260
 261 - ``iterator insert( iterator position, T* x );``
 262
 263     - Requirements: ``position`` is a valid iterator from the container and
 264       ``x != 0``
 265
 266     - Effects: Inserts ``x`` before ``position`` and returns an iterator pointing to it
 267
 268     - Throws: ``bad_pointer`` if ``x == 0``
 269
 270     - Exception safety: Strong guarantee
 271
 272 - ``template< class U > iterator insert( iterator position, std::auto_ptr<U> x );``
 273
 274     - Effects: ``return insert( position, x.release() );``
 275
 276 ..
 277         - ``iterator insert( iterator position, const T& x );``
 278
 279         - Requirements: ``position`` is a valid iterator from the container
 280
 281         - Effects: ``return insert( position, CloneAllocator::clone( x ) );``
 282
 283         - Exception safety: Strong guarantee
 284
 285         - ``void insert( iterator position, size_type n, const T& x );``
 286
 287         - Requirements: ``position`` is a valid iterator from the container
 288
 289         - Effects: Inserts ``n`` clones of ``x`` before position into the container
 290
 291         - Exception safety: Strong guarantee
 292
 293 - ``template< class InputIterator >
 294   void insert( iterator position, InputIterator first, InputIterator last );``
 295
 296     - Requirements: ``position`` is a valid iterator from the container
 297
 298     - Effects: Inserts a cloned range before ``position``
 299
 300     - Exception safety: Strong guarantee
 301
 302 - ``template< class InputRange >
 303   void insert( iterator position, const InputRange& r );``
 304
 305     - Effects: ``insert( position, boost::begin(r), boost::end(r) );``
 306
 307 - ``iterator erase( iterator position );``
 308
 309     - Requirements: ``position`` is a valid iterator from the container
 310
 311     - Effects: Removes the element defined by ``position`` and returns an iterator to the following element
 312
 313     - Throws: Nothing
 314
 315 - ``iterator erase( iterator first, iterator last );``
 316
 317     - Requirements: ``[first,last)`` is a valid range
 318
 319     - Effects: Removes the range of element defined by ``[first,last)`` and returns an iterator to the following element
 320
 321     - Throws: Nothing
 322
 323 - ``template< class Range >
 324   void erase( const Range& r );``
 325
 326     - Effects: ``erase( boost::begin(r), boost::end(r) );``
 327
 328 - ``void resize( size_type size );``
 329
 330     - Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, it happens at the back.
 331
 332     - Requirements: ``T`` is default constructible
 333
 334     - Postcondition: ``size() == size;``
 335
 336     - Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise
 337
 338 - ``void resize( size_type size, T* to_clone );``
 339
 340     - Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, clones of ``*to_clone`` are inserted at the back.
 341
 342     - Postcondition: ``size() == size;``
 343
 344     - Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise
 345
 346     - Remarks: ``to_clone == 0`` is valid if the container supports nulls. The container does not take ownership of ``to_clone``.
 347
 348 .. _`pointer container requirements`:
 349
 350 Semantics: pointer container requirements
 351 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 352
 353 You can use ``transfer()`` to move elements between two containers of the same type. Furthermore,
 354 you can also move elements from a container of type ``T`` to a container of type ``U`` as long as
 355 ``T::value_type`` is convertible to ``U::value_type``. An example would be transferring from ``boost::ptr_vector<Derived>``
 356 to ``boost::ptr_deque<Base>``.
 357
 358 (**Remark:** *When moving elements between two different containers, it is your responsibility to make sure the allocators are compatible.*
 359 *The special latitude of being able to transfer between two different containers is only available for Sequences and not for Associative Containers.*)
 360
 361 ..
 362
 363 - ``template< class PtrSequence > void transfer( iterator before, typename PtrSequence::iterator object, PtrSequence& from );``
 364
 365     - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``.
 366       Insertion takes place before ``before``.
 367
 368     - Postconditions: If ``from.empty()``, nothing happens. Otherwise
 369       ``size()`` is one more, ``from.size()`` is one less.
 370
 371     - Exception safety: Strong guarantee
 372
 373
 374 - ``template< class PtrSequence > void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last, PtrSequence& from );``
 375
 376     - Requirements: ``from.size() >= std::distance(first,last)``
 377
 378     - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``.
 379       Insertion takes place before ``before``.
 380
 381     - Postconditions: If ``from.empty()``, nothing happens. Otherwise,
 382       let ``N == std::distance(first,last);`` then ``size()`` is ``N`` more, ``from.size()`` is ``N`` less.
 383
 384     - Exception safety: Strong guarantee
 385
 386     - Complexity: Linear or better
 387
 388 - ``void template< class PtrSequence, class Range > void transfer( iterator before, const Range& r, PtrSequence& from );``
 389
 390     - Effects: ``transfer(before, boost::begin(r), boost::end(r), from);``
 391
 392 - ``template< class PtrSequence> void transfer( iterator before, PtrSequence& from );``
 393
 394     - Effects: ``transfer(before, from, from);``
 395
 396 .. _`algorithms`:
 397
 398 Semantics: algorithms
 399 ^^^^^^^^^^^^^^^^^^^^^
 400
 401 The general requirement for these algorithms is that the container *does not
 402 contain any nulls*.
 403
 404 - ``void sort();``
 405 - ``void sort( iterator first, iterator last );``
 406 - ``template< class Compare > void sort( Compare comp );``
 407 - ``template< class Compare > void sort( iterator begin, iterator end, Compare comp );``
 408
 409     - Requirements: (versions without ``Compare``) ``bool operator<( const T&, const T& )`` is defined
 410     - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
 411     - Effects: sorts the entire container or the specified range
 412     - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
 413     - Remarks: The versions of ``sort()`` that take two iterators are not available for ``ptr_list``
 414
 415 - ``void unique();``
 416 - ``void unique( iterator first, iterator last );``
 417 - ``template< class Compare > void unique( Compare comp );``
 418 - ``template< class Compare > void unique( iterator begin, iterator end, Compare comp );``
 419
 420     - Requirements: (versions without ``Compare``) ``bool operator==( const T&, const T& )`` is defined
 421     - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
 422     - Effects: removes adjacent and equal objects from the entire container or the specified range
 423     - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
 424
 425 - ``template< class Pred > void erase_if( Pred pred );``
 426 - ``template< class Pred > void erase_if( iterator begin, iterator end, Pred pred );``
 427
 428     - Requirements: ``Pred`` must take an ``const T&`` argument
 429     - Effects: removes all elements ``t`` for which ``pred(t)`` returns ``true`` from the entire container or the specified range
 430     - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
 431
 432 - ``void merge( ptr_sequence_adapter& r );``
 433 - ``template< class Compare > void merge( ptr_sequence_adapter& r, Compare comp );``
 434 - ``void merge( iterator first, iterator last, ptr_sequence_adapter& from );``
 435 - ``template< class Compare > void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp );``
 436
 437     - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
 438     - Requirements: both sequences are sorted wrt. the same predicate
 439     - Effects: transfers the entire container or the specified sequence to the container while
 440       ensuring the new sequence is also sorted
 441     - Postconditions: (Container versions) ``r.empty()``
 442     - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
 443
 444 .. raw:: html
 445
 446         <hr>
 447
 448 :Copyright:     Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
 449
 450 __ http://www.boost.org/LICENSE_1_0.txt
 451
 452