# 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:

- `reversible_ptr_container`
  - ptr_sequence_adapter
    - ptr_vector
    - ptr_list
    - ptr_deque
    - ptr_array
  - associative_ptr_container
    - ptr_set_adapter
    - ptr_multiset_adapter
    - ptr_map_adapter
    - ptr_multi_map_adapter
      - ptr_set
      - ptr_multi_set
      - ptr_map
      - ptr_multimap

Navigate:

- home
- reference

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( std::auto_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=( std::auto_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, std::auto_ptr<U> x );
            std::auto_ptr<reversible_ptr_container>  clone() const;
            std::auto_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>`). It might help to think it is just an `std::auto_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( std::auto_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=( std::auto_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, std::auto_ptr<U> x );`

  > - Effects: `return replace( position, x.release() );`

- `std::auto_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

- `std::auto_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 );`

  > - Effects: `return r.clone().release();`
  > - Remarks: This function is only defined for concrete pointer containers, but not for pointer container adapters.

## 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).