515 lines
16 KiB
ReStructuredText
515 lines
16 KiB
ReStructuredText
++++++++++++++++++++++++++++++++++
|
||
|Boost| Pointer Container Library
|
||
++++++++++++++++++++++++++++++++++
|
||
|
||
.. |Boost| image:: boost.png
|
||
|
||
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_sequence_adapter.html>`_
|
||
|
||
- `ptr_vector <ptr_vector.html>`_
|
||
- `ptr_list <ptr_list.html>`_
|
||
- `ptr_deque <ptr_deque.html>`_
|
||
- `ptr_array <ptr_array.html>`_
|
||
|
||
- `associative_ptr_container <associative_ptr_container.html>`_
|
||
|
||
- `ptr_set_adapter <ptr_set_adapter.html>`_
|
||
- `ptr_multiset_adapter <ptr_multiset_adapter.html>`_
|
||
- `ptr_map_adapter <ptr_map_adapter.html>`_
|
||
- `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_
|
||
|
||
- `ptr_set <ptr_set.html>`_
|
||
- `ptr_multi_set <ptr_multiset.html>`_
|
||
- `ptr_map <ptr_map.html>`_
|
||
- `ptr_multimap <ptr_multimap.html>`_
|
||
|
||
**Navigate:**
|
||
|
||
- `home <ptr_container.html>`_
|
||
- `reference <reference.html>`_
|
||
|
||
**synopsis:**
|
||
|
||
.. parsed-literal::
|
||
|
||
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
|
||
---------
|
||
|
||
.. _`typedefs`:
|
||
|
||
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.
|
||
|
||
..
|
||
- ``typedef *implementation defined* object_type;``
|
||
- this is ``T`` for sequences and sets
|
||
- this is ``std::pair<const Key, void*>`` for maps
|
||
|
||
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
|
||
|
||
.. parsed-literal::
|
||
|
||
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
|
||
|
||
.. parsed-literal::
|
||
|
||
auto_type ptr = ...;
|
||
auto_type other = boost::ptr_container::move( ptr );
|
||
return boost::ptr_container::move( other );
|
||
|
||
.. _construct/copy/destroy:
|
||
|
||
Semantics: construct/copy/destroy
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
- ``reversible_ptr_container();``
|
||
|
||
- Effects: Constructs an empty container
|
||
|
||
- Postconditions: ``size() == 0``
|
||
|
||
..
|
||
- ``reversible_ptr_container( size_type n, const T& x );``
|
||
|
||
- Effects: Constructs a container with ``n`` clones of ``x``
|
||
|
||
- Postconditions: ``size() == n``
|
||
|
||
- ``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
|
||
|
||
|
||
.. _iterators:
|
||
|
||
Semantics: iterators
|
||
^^^^^^^^^^^^^^^^^^^^
|
||
|
||
**See also:** `iterator invalidation <conventions.html#iterators-are-invalidated-as-in-the-corresponding-standard-container>`_
|
||
|
||
- ``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
|
||
|
||
.. _capacity:
|
||
|
||
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
|
||
|
||
|
||
.. _modifiers:
|
||
|
||
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
|
||
|
||
.. _`pointer container requirements`:
|
||
|
||
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
|
||
|
||
|
||
.. _comparison:
|
||
|
||
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.
|
||
|
||
.. _`cloneability`:
|
||
|
||
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`_.
|
||
|
||
.. _`pointer containers`: ptr_container.html#smart-containers
|
||
.. _`pointer container adapters`: ptr_container.html#smart-container-adapters
|
||
|
||
.. _`null predicate`:
|
||
|
||
Semantics: null predicate
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
- ``template< class Iterator > bool is_null( Iterator i );``
|
||
|
||
- Requirements: ``i`` is a valid dereferencable iterator
|
||
|
||
- Returns: ``*i.base() == 0;``
|
||
|
||
.. _`serialization`:
|
||
|
||
Semantics: serialization
|
||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
All containers can be serialized by means of
|
||
`Boost.Serialization`__. For an overview, see
|
||
`Serialization of Pointer Containers`_.
|
||
|
||
.. __: ../../serialization/index.html
|
||
.. _`Serialization of Pointer Containers`: reference.html#serialization
|
||
|
||
::
|
||
|
||
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
|
||
|
||
|
||
.. raw:: html
|
||
|
||
<hr>
|
||
|
||
:Copyright: Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
|
||
|
||
__ http://www.boost.org/LICENSE_1_0.txt
|
||
|