Pointer Container LibraryThis 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( 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'
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
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).
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 );
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
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
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
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
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
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.
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.
template< class Iterator > bool is_null( Iterator i );
- Requirements: i is a valid dereferencable iterator
- Returns: *i.base() == 0;
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 );
| Copyright: | Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt). |
|---|