Pointer Container Library

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. The user is advised not use the functionality unless the one knows what is being done).

• typedef ... auto_type

This declaration hides a pointer pointer type. 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. It might help to think it is just an std::auto_ptr<T>.

Semantics: construct/copy/destroy

• reversible_ptr_container();

  • Effects: Constructs an empty container

  • Postconditions: size() == 0

• 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

  • Throws: Nothing

• void 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

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

• 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 > void save( Archive& ar, const unsigned version ) const;

  • Effects: Saves the container to the archive.

  • Remarks: This function is called automatically be stream operators in Boost.Serialization

• template< class Archive > void load( Archive& ar, const unsigned version );

  • Effects: Clears the container and then loads a new container from the archive.

  • Remarks: This function is called automatically be stream operators in Boost.Serialization

  • Exception safety: Basic guarantee