ptr_sequence_adapter.rst

来自「Boost provides free peer-reviewed portab」· RST 代码 · 共 453 行 · 第 1/2 页

    - 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( std::auto_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, std::auto_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