Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Boost Pointer Container Library

Class reversible_ptr_container

This class is not a real class that can be found in the library. Its purpose is to present the general interface of all the pointer containers.

Hierarchy:

Navigate:

synopsis:

namespace boost
{
    template
    <
        class T,
        class CloneAllocator,
        class VoidPtrContainer
    >
    class reversible_ptr_container
    {
    public: // typedefs
        typedef  T*                                           value_type;
        typedef  T&                                           reference;
        typedef  const T&                                     const_reference;
        typedef  implementation defined                       iterator;
        typedef  implementation defined                       const_iterator;
        typedef  typename VoidPtrContainer::differnce_type    difference_type;
        typedef  typename VoidPtrContainer::size_type         size_type;
        typedef  typename VoidPtrContainer::allocator_type    allocator_type;
        typedef  implementation defined                       reverse_iterator;
        typedef  implementation defined                       const_reverse_iterator;
        typedef  implementation defined                       auto_type;

    public: // construct/copy/destroy
        reversible_ptr_container();
        explicit reversible_ptr_container( const reversible_ptr_container& r );
        template< class Derived >
        explicit reversible_ptr_container( const reversible_ptr_container<Derived>& r );
        explicit reversible_ptr_container( compatible-smart-ptr<reversible_ptr_container> r );
        template< class InputIterator >
        reversible_ptr_container( InputIterator first, InputIterator last );

        ~reversible_ptr_container();

        reversible_ptr_container&  operator=( const reversible_ptr_container& r );
        template<class Derived>
        reversible_ptr_container&  operator=( const reversible_ptr_container<Derived>& r );
        reversible_ptr_container&  operator=( compatible-smart-ptr<reversible_ptr_container> r );
        allocator_type             get_allocator() const;

    public: // iterators
        iterator                begin();
        const_iterator          begin() const;
        iterator                end();
        const_iterator          end() const;
        reverse_iterator        rbegin();
        const_reverse_iterator  rbegin() const;
        reverse_iterator        rend();
        const_reverse_iterator  rend() const;

    public: // capacity
        size_type  size() const;
        size_type  max_size() const;
        bool       empty() const;

    public: // modifiers
        void                     swap( reversible_ptr_container& r );
        void                     clear():
        VoidPtrContainer&        base();
        const VoidPtrContainer&  base() const;

    public: // pointer container requirements
        auto_type                                replace( iterator position, T* x );
        template< class U >
        auto_type                                replace( iterator position, compatible-smart-ptr<U> x );
        compatible-smart-ptr<reversible_ptr_container>  clone() const;
        compatible-smart-ptr<reversible_ptr_container>  release();
        auto_type                                release( iterator position );

    }; //  class 'reversible_ptr_container'

    // comparison
    template < class T, class CA, class VPC >
    bool operator==( const reversible_ptr_container<T,CA,VPC>& x,
                     const reversible_ptr_container<T,CA,VPC>& y);

    template < class T, class CA, class VPC  >
    bool operator<( const reversible_ptr_container<T,CA,VPC>& x,
                    const reversible_ptr_container<T,CA,VPC>& y);

    template < class T, class CA, class VPC  >
    bool operator!=( const reversible_ptr_container<T,CA,VPC>& x,
                     const reversible_ptr_container<T,CA,VPC>& y);

    template < class T,  class CA, class VPC >
    bool operator>( const reversible_ptr_container<T,CA,VPC>& x,
                    const reversible_ptr_container<T,CA,VPC>& y);

    template < class T,  class CA, class VPC >
    bool operator>=( const reversible_ptr_container<T,CA,VPC>& x,
                     const reversible_ptr_container<T,CA,VPC>& y);

    template < class T,  class CA, class VPC >
    bool operator<=( const reversible_ptr_container<T,CA,VPC>& x,
                     const reversible_ptr_container<T,CA,VPC>& y);

    template< class T,  class CA, class VPC  >
    void swap( reversible_ptr_container<T,CA,VPC>& x,
               reversible_ptr_container<T,CA,VPC>& y );

    // cloneability
    template< class T,  class CA, class VPC >
    reversible_ptr_container<T,CA,VPC>*
    new_clone( const reversible_ptr_container<T,CA,VPC>& r );

    // null predicate
    template< class Iterator >
    bool is_null( Iterator i );

    // serialization
    template<class Archive, class T, class CA, class VPC>
    void serialize( Archive& ar, reversible_ptr_container<T,CÁ,VPC>& c, const unsigned int version );


} // namespace 'boost'

Semantics

Semantics: typedefs

Notice how these two types differ:

  • typedef T* value_type;

    • notice this has pointer type
  • typedef T& reference;

    • notice this is not a pointer type

This is done to be able to add pointers directly to the container, but to hide the pointers externally.

Also notice that

  • typedef ... iterator

allows one to iterate over T& objects, not T*. Note that:

iterator i = ...;
i.base();

returns an iterator that allows one to iterate over void* elements (this is very rarely needed and you should not use the functionality unless you know what you are doing).

  • typedef ... auto_type

This declaration hides a pointer pointer type. You can rely on the following operations

T* operator->() const;
T& operator*() const;
T* release();
~auto_type();
operator implementation-defined bool();

The destructor will delete the stored object using the clone allocator of the container (this explains why we cannot use std::auto_ptr<T> nor std::unique_ptr<T>). It might help to think it is just a compatible-smart-ptr<T>. You can also return the pointer from a function or assign it to another pointer via the move() function

auto_type ptr   = ...;
auto_type other = boost::ptr_container::move( ptr );
return boost::ptr_container::move( other );

Semantics: construct/copy/destroy

  • reversible_ptr_container();

    • Effects: Constructs an empty container
    • Postconditions: size() == 0
  • explicit reversible_ptr_container( const reversible_ptr_container& r );

    • Effects: Constructs a container by cloning all elements of r
  • template< class Derived > explicit reversible_ptr_container( const reversible_ptr_container<Derived>& r );

    • Effects: Constructs a container by cloning all elements of r
    • Requirements: Derived is derived from T
  • explicit reversible_ptr_container( compatible-smart-ptr< reversible_ptr_container > r );

    • Effects: Constructs a container by taking ownership of the supplied pointers
  • template< class InputIterator > reversible_ptr_container( InputIterator first, InputIterator last );

    • Requirements: (first,last] is a valid range
    • Effects: Constructs a container with a cloned range of (first,last]
    • Postconditions: size() == std::distance( first, last )
  • ~reversible_ptr_container();

    • Effects: Deletes the stored objects via the clone allocator
    • Throws: Nothing
  • reversible_ptr_container& operator=( const reversible_ptr_container& r );

    • Effects: Assigns a clone of r
    • Exception safety: strong guarantee
  • template<class Derived> reversible_ptr_container& operator=( const reversible_ptr_container<Derived>& r );

    • Effects: Assigns a clone of r
    • Requirements: Derived is derived from T
    • Exception safety: Strong guarantee
  • reversible_ptr_container& operator=( compatible-smart-ptr<reversible_ptr_container> r );

    • Effects: Deletes the stored objects and then takes ownership of the supplied pointers
    • Throws: Nothing
  • allocator_type get_allocator() const;

    • Effects: Returns a copy of the allocator of the container object

Semantics: iterators

See also: iterator invalidation

  • iterator begin();

  • const_iterator begin() const;

    • Effects: Returns a mutable/non-mutable iterator with value_type T
    • Throws: Nothing
  • iterator end();

  • const_iterator end() const;

    • Effects: Returns a mutable/non-mutable iterator with value_type T
    • Throws: Nothing
  • reverse_iterator rbegin();

  • const_reverse_iterator rbegin() const;

    • Effects: Returns a mutable/non-mutable reverse iterator with value_type T
    • Throws: Nothing
  • reverse_iterator rend();

  • const_reverse_iterator rend() const;

    • Effects: Returns a mutable/non-mutable reverse iterator with value_type T
    • Throws: Nothing

Semantics: capacity

  • size_type size() const;

    • Effects: Returns the number of stored elements
    • Throws: Nothing
  • size_type max_size() const;

    • Effects: Returns the maximum number of stored elements
    • Throws: Nothing
  • bool empty() const;

    • Effects: Returns whether the container is empty or not
    • Throws: Nothing

Semantics: modifiers

  • void swap( reversible_ptr_container& r );

    • Effects: Swaps the content of the two containers
    • Throws: Nothing
  • void clear();

    • Effects: Destroys all object of the container
    • Postconditions: empty() == true
    • Throws: Nothing
  • VoidPtrContainer& base();

  • const VoidPtrContainer& base() const;

    • Returns: a reference to the wrapped container

Semantics: pointer container requirements

  • auto_type replace( iterator position, T* x );

    • Requirements: not empty() and x != 0
    • Effects: returns the object pointed to by position and replaces it with x.
    • Throws: bad_ptr_container_operation if the container is empty and bad_pointer if x == 0.
    • Exception safety: Strong guarantee
  • template< class U > auto_type replace( iterator position, compatible-smart-ptr<U> x );

    • Effects: return replace( position, x.release() );
  • compatible-smart-ptr< reversible_ptr_container > clone() const;

    • Effects: Returns a deep copy of the container
    • Throws: std::bad_alloc if there is not enough memory to make a clone of the container
    • Complexity: Linear
  • compatible-smart-ptr< reversible_ptr_container > release();

    • Effects: Releases ownership of the container. This is a useful way of returning a container from a function.
    • Postconditions: empty() == true
    • Throws: std::bad_alloc if the return value cannot be allocated
    • Exception safety: Strong guarantee
  • auto_type release( iterator position );

    • Requirements: not empty();
    • Effects: Releases ownership of the pointer referred to by position
    • Postconditions: size() is one less
    • Throws: bad_ptr_container_operation if the container is empty
    • Exception safety: Strong guarantee

Semantics: comparison

These functions compare the underlying range of objects. So

operation( const ptr_container& l, const ptr_container& r );

has the effect one would expect of normal standard containers. Hence objects are compared and not the pointers to objects.

Semantics: cloneability

  • template< class T, class CloneAllocator > reversible_ptr_container<T,CA,VPC>* new_clone( const reversible_ptr_container<T,CA,VPC>& r );

Semantics: null predicate

  • template< class Iterator > bool is_null( Iterator i );

    • Requirements: i is a valid dereferencable iterator
    • Returns: *i.base() == 0;

Semantics: serialization

All containers can be serialized by means of Boost.Serialization. For an overview, see Serialization of Pointer Containers.

template<class Archive, class T, class CA, class VPC>
void serialize( Archive& ar, reversible_ptr_container<T,CA,VPC>& c, const unsigned int version );
  • Effects: Saves or loads the container to/from the archive.
  • Remarks: This function is called automatically be stream operators in Boost.Serialization
  • Exception safety: Loading gives the basic guarantee

Copyright:Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt).