1++++++++++++++++++++++++++++++++++ 2 |Boost| Pointer Container Library 3++++++++++++++++++++++++++++++++++ 4 5.. |Boost| image:: boost.png 6 7Class ``ptr_sequence_adapter`` 8------------------------------ 9 10This section describes all the common operations for all the pointer 11sequences: 12 13- `ptr_vector <ptr_vector.html>`_ 14- `ptr_list <ptr_list.html>`_ 15- `ptr_deque <ptr_deque.html>`_ 16 17 18The ``ptr_sequence_adapter`` is also a concrete class that you can use to create custom pointer 19containers 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 138Semantics 139--------- 140 141.. _`construct/copy/destroy`: 142 143Semantics: 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 191Semantics: 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 224Semantics: 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 350Semantics: pointer container requirements 351^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 352 353You can use ``transfer()`` to move elements between two containers of the same type. Furthermore, 354you 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>`` 356to ``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 398Semantics: algorithms 399^^^^^^^^^^^^^^^^^^^^^ 400 401The general requirement for these algorithms is that the container *does not 402contain 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 453