Boost Pointer Container Library

# Pointer Container Library

# Class `ptr_sequence_adapter`

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

- ptr_vector
- ptr_list
- ptr_deque

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

Hierarchy:

- reversible_ptr_container
  - `ptr_sequence_adapter`
    - ptr_vector
    - ptr_list
    - ptr_deque
    - ptr_array

Navigate:

- home
- reference

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

# 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();`

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

## 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() );`

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

- `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`.

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

## 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-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt).