123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452 |
- ++++++++++++++++++++++++++++++++++
- |Boost| Pointer Container Library
- ++++++++++++++++++++++++++++++++++
- .. |Boost| image:: boost.png
- Class ``ptr_sequence_adapter``
- ------------------------------
- This section describes all the common operations for all the pointer
- sequences:
- - `ptr_vector <ptr_vector.html>`_
- - `ptr_list <ptr_list.html>`_
- - `ptr_deque <ptr_deque.html>`_
- The ``ptr_sequence_adapter`` is also a concrete class that you can use to create custom pointer
- containers from.
- **Hierarchy:**
- - `reversible_ptr_container <reversible_ptr_container.html>`_
- - ``ptr_sequence_adapter``
- - `ptr_vector <ptr_vector.html>`_
- - `ptr_list <ptr_list.html>`_
- - `ptr_deque <ptr_deque.html>`_
- - `ptr_array <ptr_array.html>`_
- **Navigate:**
- - `home <ptr_container.html>`_
- - `reference <reference.html>`_
- **Synopsis:**
- .. parsed-literal::
- namespace boost
- {
- template
- <
- class T,
- class VoidPtrSeq,
- class CloneAllocator = heap_clone_allocator
- >
- class ptr_sequence_adapter
- {
- public: // `construct/copy/destroy`_
- template< class InputIterator >
- assign( InputIterator first, InputIterator last );
- template< class InputRange >
- assign( const InputRange& e );
- public: // `element access`_
- T& front();
- const T& front() const;
- T& back();
- const T& back() const;
- public: // `modifiers`_
- void push_back( T* x );
- template< class U >
- void push_back( compatible-smart-ptr<U> x );
- auto_type pop_back();
- iterator insert( iterator position, T* x );
- template< class U >
- iterator insert( iterator position, compatible-smart-ptr<U> x );
- template< class InputIterator >
- void insert( iterator position, InputIterator first, InputIterator last );
- template< class InputRange >
- void insert( iterator position, const InputRange& r );
- iterator erase( iterator position );
- iterator erase( iterator first, iterator last );
- template< class Range >
- iterator erase( const Range& r );
- void resize( size_type size );
- void resize( size_type size, T* to_clone );
- public: // `pointer container requirements`_
- template< class PtrSequence >
- void transfer( iterator before, typename PtrSequence::iterator object,
- PtrSequence& from );
- template< class PtrSequence >
- void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last,
- PtrSequence& from );
- void template< class PtrSequence, class Range >
- void transfer( iterator before, const Range& r, PtrSequence& from );
- template< class PtrSequence >
- void transfer( iterator before, PtrSequence& from );
- public: // `algorithms`_
- void sort();
- void sort( iterator first, iterator last );
- template< class Compare >
- void sort( Compare comp );
- template< class Compare >
- void sort( iterator begin, iterator end, Compare comp );
- void unique();
- void unique( iterator first, iterator last );
- template< class Compare >
- void unique( Compare comp );
- template< class Compare >
- void unique( iterator begin, iterator end, Compare comp );
- template< class Pred >
- void erase_if( Pred pred );
- template< class Pred >
- void erase_if( iterator begin, iterator end, Pred pred );
- void merge( ptr_sequence_adapter& r );
- template< class Compare >
- void merge( ptr_sequence_adapter& r, Compare comp );
- void merge( iterator first, iterator last, ptr_sequence_adapter& from );
- template< class Compare >
- void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp );
- public: // `ptr_list interface`_
- public: // `ptr_vector interface`_
- public: // `ptr_deque interface`_
- }; // class 'ptr_sequence_adapter'
- } // namespace 'boost'
- .. _`ptr_list interface`: ptr_list.html
- .. _`ptr_vector interface`: ptr_vector.html
- .. _`ptr_deque interface`: ptr_deque.html
- Semantics
- ---------
- .. _`construct/copy/destroy`:
- Semantics: construct/copy/destroy
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- - ``template< class InputIterator >
- void assign( InputIterator first, InputIterator last );``
- - Requirements: ``(first,last]`` is a valid range
- - Effects: ``clear(); insert( first, last );``
- - Postconditions: ``size() == std::distance( first, last );``
- - Exception safety: strong guarantee
- - ``template< class InputRange >
- void assign( const InputRange& r );``
- - Effects: ``assign( boost::begin(r), boost::end(r) );``
- ..
- - ``assign( size_type n, const T& u )``
- - Effects: ``clear(); insert( begin(), n, u );``
- - Postconditions: ``size() == n``
- - Exception safety: Strong guarantee
- ..
- void resize( size_type sz, const T& x );
- Effects:
- if ( sz > size() )
- insert( end(), sz-size(), x );
- else if ( sz < size() )
- erase( begin()+sz, end() );
- else
- ; //do nothing
- Postconditions: size() == sz
- Exception safety: Strong guarantee
- .. _`element access`:
- Semantics: element access
- ^^^^^^^^^^^^^^^^^^^^^^^^^
- - ``T& front();``
- - Requirements: ``not empty();``
- - Effects: ``return *begin();``
- - ``const T& front() const;``
- - Requirements: ``not empty();``
- - Effects: ``return *begin();``
- - ``T& back();``
- - Requirements: ``not empty();``
- - Effects: ``return *--end();``
- - ``const T& back() const;``
- - Requirements: ``not empty();``
- - Effects: ``return *--end();``
- .. _`modifiers`:
- Semantics: modifiers
- ^^^^^^^^^^^^^^^^^^^^
- - ``void push_back( T* x );``
- - Requirements: ``x != 0``
- - Effects: Inserts the pointer into container and takes ownership of it
- - Throws: ``bad_pointer`` if ``x == 0``
- - Exception safety: Strong guarantee
- - ``template< class U > void push_back( compatible-smart-ptr<U> x );``
- - Effects: ``push_back( x.release() );``
-
- ..
- - ``void push_back( const T& x );``
- - Effects: ``push_back( CloneAllocator::clone( x ) );``
- - Exception safety: Strong guarantee
- - ``auto_type pop_back();``
- - Requirements:``not empty()``
- - Effects: Removes the last element in the container
- - Postconditions: ``size()`` is one less
- - Throws: ``bad_ptr_container_operation`` if ``empty() == true``
- - Exception safety: Strong guarantee
- - ``iterator insert( iterator position, T* x );``
- - Requirements: ``position`` is a valid iterator from the container and
- ``x != 0``
- - Effects: Inserts ``x`` before ``position`` and returns an iterator pointing to it
- - Throws: ``bad_pointer`` if ``x == 0``
- - Exception safety: Strong guarantee
-
- - ``template< class U > iterator insert( iterator position, compatible-smart-ptr<U> x );``
- - Effects: ``return insert( position, x.release() );``
- ..
- - ``iterator insert( iterator position, const T& x );``
- - Requirements: ``position`` is a valid iterator from the container
- - Effects: ``return insert( position, CloneAllocator::clone( x ) );``
- - Exception safety: Strong guarantee
- - ``void insert( iterator position, size_type n, const T& x );``
- - Requirements: ``position`` is a valid iterator from the container
- - Effects: Inserts ``n`` clones of ``x`` before position into the container
- - Exception safety: Strong guarantee
- - ``template< class InputIterator >
- void insert( iterator position, InputIterator first, InputIterator last );``
- - Requirements: ``position`` is a valid iterator from the container
- - Effects: Inserts a cloned range before ``position``
- - Exception safety: Strong guarantee
- - ``template< class InputRange >
- void insert( iterator position, const InputRange& r );``
- - Effects: ``insert( position, boost::begin(r), boost::end(r) );``
- - ``iterator erase( iterator position );``
- - Requirements: ``position`` is a valid iterator from the container
- - Effects: Removes the element defined by ``position`` and returns an iterator to the following element
- - Throws: Nothing
- - ``iterator erase( iterator first, iterator last );``
- - Requirements: ``[first,last)`` is a valid range
- - Effects: Removes the range of element defined by ``[first,last)`` and returns an iterator to the following element
- - Throws: Nothing
- - ``template< class Range >
- void erase( const Range& r );``
- - Effects: ``erase( boost::begin(r), boost::end(r) );``
- - ``void resize( size_type size );``
- - Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, it happens at the back.
-
- - Requirements: ``T`` is default constructible
-
- - Postcondition: ``size() == size;``
-
- - Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise
-
- - ``void resize( size_type size, T* to_clone );``
- - 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.
-
- - Postcondition: ``size() == size;``
-
- - Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise
- - Remarks: ``to_clone == 0`` is valid if the container supports nulls. The container does not take ownership of ``to_clone``.
- .. _`pointer container requirements`:
- Semantics: pointer container requirements
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- You can use ``transfer()`` to move elements between two containers of the same type. Furthermore,
- you can also move elements from a container of type ``T`` to a container of type ``U`` as long as
- ``T::value_type`` is convertible to ``U::value_type``. An example would be transferring from ``boost::ptr_vector<Derived>``
- to ``boost::ptr_deque<Base>``.
- (**Remark:** *When moving elements between two different containers, it is your responsibility to make sure the allocators are compatible.*
- *The special latitude of being able to transfer between two different containers is only available for Sequences and not for Associative Containers.*)
- ..
- - ``template< class PtrSequence > void transfer( iterator before, typename PtrSequence::iterator object, PtrSequence& from );``
- - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``.
- Insertion takes place before ``before``.
- - Postconditions: If ``from.empty()``, nothing happens. Otherwise
- ``size()`` is one more, ``from.size()`` is one less.
- - Exception safety: Strong guarantee
- - ``template< class PtrSequence > void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last, PtrSequence& from );``
- - Requirements: ``from.size() >= std::distance(first,last)``
- - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``.
- Insertion takes place before ``before``.
- - Postconditions: If ``from.empty()``, nothing happens. Otherwise,
- let ``N == std::distance(first,last);`` then ``size()`` is ``N`` more, ``from.size()`` is ``N`` less.
- - Exception safety: Strong guarantee
-
- - Complexity: Linear or better
- - ``void template< class PtrSequence, class Range > void transfer( iterator before, const Range& r, PtrSequence& from );``
- - Effects: ``transfer(before, boost::begin(r), boost::end(r), from);``
- - ``template< class PtrSequence> void transfer( iterator before, PtrSequence& from );``
- - Effects: ``transfer(before, from, from);``
- .. _`algorithms`:
- Semantics: algorithms
- ^^^^^^^^^^^^^^^^^^^^^
- The general requirement for these algorithms is that the container *does not
- contain any nulls*.
- - ``void sort();``
- - ``void sort( iterator first, iterator last );``
- - ``template< class Compare > void sort( Compare comp );``
- - ``template< class Compare > void sort( iterator begin, iterator end, Compare comp );``
- - Requirements: (versions without ``Compare``) ``bool operator<( const T&, const T& )`` is defined
- - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
- - Effects: sorts the entire container or the specified range
- - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
- - Remarks: The versions of ``sort()`` that take two iterators are not available for ``ptr_list``
- - ``void unique();``
- - ``void unique( iterator first, iterator last );``
- - ``template< class Compare > void unique( Compare comp );``
- - ``template< class Compare > void unique( iterator begin, iterator end, Compare comp );``
- - Requirements: (versions without ``Compare``) ``bool operator==( const T&, const T& )`` is defined
- - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
- - Effects: removes adjacent and equal objects from the entire container or the specified range
- - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
-
- - ``template< class Pred > void erase_if( Pred pred );``
- - ``template< class Pred > void erase_if( iterator begin, iterator end, Pred pred );``
- - Requirements: ``Pred`` must take an ``const T&`` argument
- - Effects: removes all elements ``t`` for which ``pred(t)`` returns ``true`` from the entire container or the specified range
- - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
-
- - ``void merge( ptr_sequence_adapter& r );``
- - ``template< class Compare > void merge( ptr_sequence_adapter& r, Compare comp );``
- - ``void merge( iterator first, iterator last, ptr_sequence_adapter& from );``
- - ``template< class Compare > void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp );``
- - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
- - Requirements: both sequences are sorted wrt. the same predicate
- - Effects: transfers the entire container or the specified sequence to the container while
- ensuring the new sequence is also sorted
- - Postconditions: (Container versions) ``r.empty()``
- - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
- .. raw:: html
- <hr>
-
- :Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
- __ http://www.boost.org/LICENSE_1_0.txt
-
|