Boost Pointer Container Library

Class ptr_sequence_adapter

This section describes all the common operations for all the pointer sequences:

The ptr_sequence_adapter is also a concrete class that you can use to create custom pointer containers from.

See also:

Navigate:

Synopsis:

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 );
        auto_type pop_back();
        iterator  insert( iterator position, T* 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 );
    
    public: // pointer container requirements

        void  transfer( iterator before, iterator object, 
                        ptr_sequence_adapter& from );
        void  transfer( iterator before, iterator first, iterator last,
                        ptr_sequence_adapter& from );
        void template< class Range> 
        void transfer( iterator before, const Range& r, ptr_sequence_adapter& from );
        void transfer( iterator before, ptr_sequence_adapter& 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'  

Semantics

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) );

Semantics: element access

  • T& front();

    • Requirements: not empty();
    • Effects: return *begin();
    • Throws: bad_ptr_container_operation if empty() == true
  • const T& front() const;

    • Requirements: not empty();
    • Effects: return *begin();
    • Throws: bad_ptr_container_operation if empty() == true
  • T& back();

    • Requirements: not empty();
    • Effects: return *--end();
    • Throws: bad_ptr_container_operation if empty() == true
  • const T& back() const;

    • Requirements: not empty();
    • Effects: return *--end();
    • Throws: bad_ptr_container_operation if empty() == true

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
  • 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 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) );

Semantics: pointer container requirements

  • void transfer( iterator before, iterator object, ptr_sequence_adapter& from );

    • Requirements: not from.empty()
    • Effects: Inserts the object defined by object into the container and remove it from from.
    • Postconditions: size() is one more, from.size() is one less.
    • Exception safety: Strong guarantee
  • void transfer( iterator before, iterator first, iterator last, ptr_sequence_adapter& from );

    • Requirements: not from.empty()
    • Effects: Inserts the objects defined by the range [first,last) into the container and remove it from from.
    • Postconditions: Let N == std::distance(first,last); then size() is N more, from.size() is N less.
    • Exception safety: Strong guarantee
  • template< class Range> void transfer( iterator before, const Range& r, ptr_sequence_adapter& from );

    • Effects: transfer(before, boost::begin(r), boost::end(r), from);
  • void transfer( iterator before, ptr_sequence_adapter& from );

    • Effects: Transfers all objects from from into the container. Insertion takes place before before.
    • Postconditions: from.empty();
    • Exception safety: Strong guarantee

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)
copyright:Thorsten Ottosen 2004-2005.