453 lines
15 KiB
ReStructuredText
453 lines
15 KiB
ReStructuredText
++++++++++++++++++++++++++++++++++
|
|
|Boost| Pointer Container Library
|
|
++++++++++++++++++++++++++++++++++
|
|
|
|
.. |Boost| image:: boost.png
|
|
|
|
Class ``ptr_sequence_adapter``
|
|
------------------------------
|
|
|
|
This section describes all the common operations for all the pointer
|
|
sequences:
|
|
|
|
- `ptr_vector <ptr_vector.html>`_
|
|
- `ptr_list <ptr_list.html>`_
|
|
- `ptr_deque <ptr_deque.html>`_
|
|
|
|
|
|
The ``ptr_sequence_adapter`` is also a concrete class that you can use to create custom pointer
|
|
containers from.
|
|
|
|
**Hierarchy:**
|
|
|
|
- `reversible_ptr_container <reversible_ptr_container.html>`_
|
|
|
|
- ``ptr_sequence_adapter``
|
|
|
|
- `ptr_vector <ptr_vector.html>`_
|
|
- `ptr_list <ptr_list.html>`_
|
|
- `ptr_deque <ptr_deque.html>`_
|
|
- `ptr_array <ptr_array.html>`_
|
|
|
|
**Navigate:**
|
|
|
|
- `home <ptr_container.html>`_
|
|
- `reference <reference.html>`_
|
|
|
|
|
|
**Synopsis:**
|
|
|
|
.. parsed-literal::
|
|
|
|
namespace boost
|
|
{
|
|
|
|
template
|
|
<
|
|
class T,
|
|
class VoidPtrSeq,
|
|
class CloneAllocator = heap_clone_allocator
|
|
>
|
|
class ptr_sequence_adapter
|
|
{
|
|
public: // `construct/copy/destroy`_
|
|
template< class InputIterator >
|
|
assign( InputIterator first, InputIterator last );
|
|
template< class InputRange >
|
|
assign( const InputRange& e );
|
|
|
|
public: // `element access`_
|
|
T& front();
|
|
const T& front() const;
|
|
T& back();
|
|
const T& back() const;
|
|
|
|
public: // `modifiers`_
|
|
void push_back( T* x );
|
|
template< class U >
|
|
void push_back( compatible-smart-ptr<U> x );
|
|
auto_type pop_back();
|
|
iterator insert( iterator position, T* x );
|
|
template< class U >
|
|
iterator insert( iterator position, compatible-smart-ptr<U> x );
|
|
template< class InputIterator >
|
|
void insert( iterator position, InputIterator first, InputIterator last );
|
|
template< class InputRange >
|
|
void insert( iterator position, const InputRange& r );
|
|
iterator erase( iterator position );
|
|
iterator erase( iterator first, iterator last );
|
|
template< class Range >
|
|
iterator erase( const Range& r );
|
|
void resize( size_type size );
|
|
void resize( size_type size, T* to_clone );
|
|
|
|
public: // `pointer container requirements`_
|
|
template< class PtrSequence >
|
|
void transfer( iterator before, typename PtrSequence::iterator object,
|
|
PtrSequence& from );
|
|
template< class PtrSequence >
|
|
void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last,
|
|
PtrSequence& from );
|
|
void template< class PtrSequence, class Range >
|
|
void transfer( iterator before, const Range& r, PtrSequence& from );
|
|
template< class PtrSequence >
|
|
void transfer( iterator before, PtrSequence& from );
|
|
|
|
public: // `algorithms`_
|
|
|
|
void sort();
|
|
void sort( iterator first, iterator last );
|
|
template< class Compare >
|
|
void sort( Compare comp );
|
|
template< class Compare >
|
|
void sort( iterator begin, iterator end, Compare comp );
|
|
|
|
void unique();
|
|
void unique( iterator first, iterator last );
|
|
template< class Compare >
|
|
void unique( Compare comp );
|
|
template< class Compare >
|
|
void unique( iterator begin, iterator end, Compare comp );
|
|
|
|
template< class Pred >
|
|
void erase_if( Pred pred );
|
|
template< class Pred >
|
|
void erase_if( iterator begin, iterator end, Pred pred );
|
|
|
|
void merge( ptr_sequence_adapter& r );
|
|
template< class Compare >
|
|
void merge( ptr_sequence_adapter& r, Compare comp );
|
|
void merge( iterator first, iterator last, ptr_sequence_adapter& from );
|
|
template< class Compare >
|
|
void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp );
|
|
|
|
public: // `ptr_list interface`_
|
|
|
|
public: // `ptr_vector interface`_
|
|
|
|
public: // `ptr_deque interface`_
|
|
|
|
}; // class 'ptr_sequence_adapter'
|
|
|
|
} // namespace 'boost'
|
|
|
|
.. _`ptr_list interface`: ptr_list.html
|
|
.. _`ptr_vector interface`: ptr_vector.html
|
|
.. _`ptr_deque interface`: ptr_deque.html
|
|
|
|
Semantics
|
|
---------
|
|
|
|
.. _`construct/copy/destroy`:
|
|
|
|
Semantics: construct/copy/destroy
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
- ``template< class InputIterator >
|
|
void assign( InputIterator first, InputIterator last );``
|
|
|
|
- Requirements: ``(first,last]`` is a valid range
|
|
|
|
- Effects: ``clear(); insert( first, last );``
|
|
|
|
- Postconditions: ``size() == std::distance( first, last );``
|
|
|
|
- Exception safety: strong guarantee
|
|
|
|
- ``template< class InputRange >
|
|
void assign( const InputRange& r );``
|
|
|
|
- Effects: ``assign( boost::begin(r), boost::end(r) );``
|
|
|
|
|
|
..
|
|
- ``assign( size_type n, const T& u )``
|
|
|
|
- Effects: ``clear(); insert( begin(), n, u );``
|
|
|
|
- Postconditions: ``size() == n``
|
|
|
|
- Exception safety: Strong guarantee
|
|
|
|
|
|
..
|
|
void resize( size_type sz, const T& x );
|
|
Effects:
|
|
|
|
if ( sz > size() )
|
|
insert( end(), sz-size(), x );
|
|
else if ( sz < size() )
|
|
erase( begin()+sz, end() );
|
|
else
|
|
; //do nothing
|
|
|
|
Postconditions: size() == sz
|
|
|
|
Exception safety: Strong guarantee
|
|
|
|
|
|
.. _`element access`:
|
|
|
|
Semantics: element access
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
- ``T& front();``
|
|
|
|
- Requirements: ``not empty();``
|
|
|
|
- Effects: ``return *begin();``
|
|
|
|
|
|
- ``const T& front() const;``
|
|
|
|
- Requirements: ``not empty();``
|
|
|
|
- Effects: ``return *begin();``
|
|
|
|
|
|
- ``T& back();``
|
|
|
|
- Requirements: ``not empty();``
|
|
|
|
- Effects: ``return *--end();``
|
|
|
|
|
|
- ``const T& back() const;``
|
|
|
|
- Requirements: ``not empty();``
|
|
|
|
- Effects: ``return *--end();``
|
|
|
|
|
|
.. _`modifiers`:
|
|
|
|
Semantics: modifiers
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
- ``void push_back( T* x );``
|
|
|
|
- Requirements: ``x != 0``
|
|
|
|
- Effects: Inserts the pointer into container and takes ownership of it
|
|
|
|
- Throws: ``bad_pointer`` if ``x == 0``
|
|
|
|
- Exception safety: Strong guarantee
|
|
|
|
- ``template< class U > void push_back( compatible-smart-ptr<U> x );``
|
|
|
|
- Effects: ``push_back( x.release() );``
|
|
|
|
..
|
|
- ``void push_back( const T& x );``
|
|
|
|
- Effects: ``push_back( CloneAllocator::clone( x ) );``
|
|
|
|
- Exception safety: Strong guarantee
|
|
|
|
- ``auto_type pop_back();``
|
|
|
|
- Requirements:``not empty()``
|
|
|
|
- Effects: Removes the last element in the container
|
|
|
|
- Postconditions: ``size()`` is one less
|
|
|
|
- Throws: ``bad_ptr_container_operation`` if ``empty() == true``
|
|
|
|
- Exception safety: Strong guarantee
|
|
|
|
|
|
- ``iterator insert( iterator position, T* x );``
|
|
|
|
- Requirements: ``position`` is a valid iterator from the container and
|
|
``x != 0``
|
|
|
|
- Effects: Inserts ``x`` before ``position`` and returns an iterator pointing to it
|
|
|
|
- Throws: ``bad_pointer`` if ``x == 0``
|
|
|
|
- Exception safety: Strong guarantee
|
|
|
|
- ``template< class U > iterator insert( iterator position, compatible-smart-ptr<U> x );``
|
|
|
|
- Effects: ``return insert( position, x.release() );``
|
|
|
|
..
|
|
- ``iterator insert( iterator position, const T& x );``
|
|
|
|
- Requirements: ``position`` is a valid iterator from the container
|
|
|
|
- Effects: ``return insert( position, CloneAllocator::clone( x ) );``
|
|
|
|
- Exception safety: Strong guarantee
|
|
|
|
- ``void insert( iterator position, size_type n, const T& x );``
|
|
|
|
- Requirements: ``position`` is a valid iterator from the container
|
|
|
|
- Effects: Inserts ``n`` clones of ``x`` before position into the container
|
|
|
|
- Exception safety: Strong guarantee
|
|
|
|
- ``template< class InputIterator >
|
|
void insert( iterator position, InputIterator first, InputIterator last );``
|
|
|
|
- Requirements: ``position`` is a valid iterator from the container
|
|
|
|
- Effects: Inserts a cloned range before ``position``
|
|
|
|
- Exception safety: Strong guarantee
|
|
|
|
- ``template< class InputRange >
|
|
void insert( iterator position, const InputRange& r );``
|
|
|
|
- Effects: ``insert( position, boost::begin(r), boost::end(r) );``
|
|
|
|
- ``iterator erase( iterator position );``
|
|
|
|
- Requirements: ``position`` is a valid iterator from the container
|
|
|
|
- Effects: Removes the element defined by ``position`` and returns an iterator to the following element
|
|
|
|
- Throws: Nothing
|
|
|
|
- ``iterator erase( iterator first, iterator last );``
|
|
|
|
- Requirements: ``[first,last)`` is a valid range
|
|
|
|
- Effects: Removes the range of element defined by ``[first,last)`` and returns an iterator to the following element
|
|
|
|
- Throws: Nothing
|
|
|
|
- ``template< class Range >
|
|
void erase( const Range& r );``
|
|
|
|
- Effects: ``erase( boost::begin(r), boost::end(r) );``
|
|
|
|
- ``void resize( size_type size );``
|
|
|
|
- Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, it happens at the back.
|
|
|
|
- Requirements: ``T`` is default constructible
|
|
|
|
- Postcondition: ``size() == size;``
|
|
|
|
- Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise
|
|
|
|
- ``void resize( size_type size, T* to_clone );``
|
|
|
|
- Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, clones of ``*to_clone`` are inserted at the back.
|
|
|
|
- Postcondition: ``size() == size;``
|
|
|
|
- Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise
|
|
|
|
- Remarks: ``to_clone == 0`` is valid if the container supports nulls. The container does not take ownership of ``to_clone``.
|
|
|
|
.. _`pointer container requirements`:
|
|
|
|
Semantics: pointer container requirements
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
You can use ``transfer()`` to move elements between two containers of the same type. Furthermore,
|
|
you can also move elements from a container of type ``T`` to a container of type ``U`` as long as
|
|
``T::value_type`` is convertible to ``U::value_type``. An example would be transferring from ``boost::ptr_vector<Derived>``
|
|
to ``boost::ptr_deque<Base>``.
|
|
|
|
(**Remark:** *When moving elements between two different containers, it is your responsibility to make sure the allocators are compatible.*
|
|
*The special latitude of being able to transfer between two different containers is only available for Sequences and not for Associative Containers.*)
|
|
|
|
..
|
|
|
|
- ``template< class PtrSequence > void transfer( iterator before, typename PtrSequence::iterator object, PtrSequence& from );``
|
|
|
|
- Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``.
|
|
Insertion takes place before ``before``.
|
|
|
|
- Postconditions: If ``from.empty()``, nothing happens. Otherwise
|
|
``size()`` is one more, ``from.size()`` is one less.
|
|
|
|
- Exception safety: Strong guarantee
|
|
|
|
|
|
- ``template< class PtrSequence > void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last, PtrSequence& from );``
|
|
|
|
- Requirements: ``from.size() >= std::distance(first,last)``
|
|
|
|
- Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``.
|
|
Insertion takes place before ``before``.
|
|
|
|
- Postconditions: If ``from.empty()``, nothing happens. Otherwise,
|
|
let ``N == std::distance(first,last);`` then ``size()`` is ``N`` more, ``from.size()`` is ``N`` less.
|
|
|
|
- Exception safety: Strong guarantee
|
|
|
|
- Complexity: Linear or better
|
|
|
|
- ``void template< class PtrSequence, class Range > void transfer( iterator before, const Range& r, PtrSequence& from );``
|
|
|
|
- Effects: ``transfer(before, boost::begin(r), boost::end(r), from);``
|
|
|
|
- ``template< class PtrSequence> void transfer( iterator before, PtrSequence& from );``
|
|
|
|
- Effects: ``transfer(before, from, from);``
|
|
|
|
.. _`algorithms`:
|
|
|
|
Semantics: algorithms
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The general requirement for these algorithms is that the container *does not
|
|
contain any nulls*.
|
|
|
|
- ``void sort();``
|
|
- ``void sort( iterator first, iterator last );``
|
|
- ``template< class Compare > void sort( Compare comp );``
|
|
- ``template< class Compare > void sort( iterator begin, iterator end, Compare comp );``
|
|
|
|
- Requirements: (versions without ``Compare``) ``bool operator<( const T&, const T& )`` is defined
|
|
- Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
|
|
- Effects: sorts the entire container or the specified range
|
|
- Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
|
|
- Remarks: The versions of ``sort()`` that take two iterators are not available for ``ptr_list``
|
|
|
|
- ``void unique();``
|
|
- ``void unique( iterator first, iterator last );``
|
|
- ``template< class Compare > void unique( Compare comp );``
|
|
- ``template< class Compare > void unique( iterator begin, iterator end, Compare comp );``
|
|
|
|
- Requirements: (versions without ``Compare``) ``bool operator==( const T&, const T& )`` is defined
|
|
- Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
|
|
- Effects: removes adjacent and equal objects from the entire container or the specified range
|
|
- Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
|
|
|
|
- ``template< class Pred > void erase_if( Pred pred );``
|
|
- ``template< class Pred > void erase_if( iterator begin, iterator end, Pred pred );``
|
|
|
|
- Requirements: ``Pred`` must take an ``const T&`` argument
|
|
- Effects: removes all elements ``t`` for which ``pred(t)`` returns ``true`` from the entire container or the specified range
|
|
- Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
|
|
|
|
- ``void merge( ptr_sequence_adapter& r );``
|
|
- ``template< class Compare > void merge( ptr_sequence_adapter& r, Compare comp );``
|
|
- ``void merge( iterator first, iterator last, ptr_sequence_adapter& from );``
|
|
- ``template< class Compare > void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp );``
|
|
|
|
- Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
|
|
- Requirements: both sequences are sorted wrt. the same predicate
|
|
- Effects: transfers the entire container or the specified sequence to the container while
|
|
ensuring the new sequence is also sorted
|
|
- Postconditions: (Container versions) ``r.empty()``
|
|
- Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
|
|
|
|
.. raw:: html
|
|
|
|
<hr>
|
|
|
|
:Copyright: Thorsten Ottosen 2004-2006. 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
|
|
|
|
|