++++++++++++++++++++++++++++++++++
 |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