123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514 |
- ++++++++++++++++++++++++++++++++++
- |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
|