libs/ptr_container/doc/ptr_set_adapter.rst

   1 ++++++++++++++++++++++++++++++++++
   2  |Boost| Pointer Container Library
   3 ++++++++++++++++++++++++++++++++++
   4
   5 .. |Boost| image:: boost.png
   6
   7 Class ``ptr_set_adapter``
   8 -------------------------
   9
  10 This class is used to build custom pointer containers with
  11 an underlying set-like container. The interface of the class is an extension
  12 of the interface from ``associative_ptr_container``.
  13
  14 **Hierarchy:**
  15
  16 - `reversible_ptr_container <reversible_ptr_container.html>`_
  17
  18   - `associative_ptr_container <associative_ptr_container.html>`_
  19
  20     - ``ptr_set_adapter``
  21     - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_
  22     - `ptr_map_adapter <ptr_map_adapter.html>`_
  23     - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_
  24
  25       - `ptr_set <ptr_set.html>`_
  26       - `ptr_multi_set <ptr_multiset.html>`_
  27       - `ptr_map <ptr_map.html>`_
  28       - `ptr_multimap <ptr_multimap.html>`_
  29
  30 **Navigate:**
  31
  32 - `home <ptr_container.html>`_
  33 - `reference <reference.html>`_
  34
  35 .. _reversible_ptr_container: reversible_ptr_container.html
  36 .. _associative_ptr_container: associative_ptr_container.html
  37 .. _ptr_set: ptr_set.html
  38
  39 **Synopsis:**
  40
  41 .. parsed-literal::
  42
  43
  44         namespace boost
  45         {
  46             template
  47             <
  48                 class Key,
  49                 class VoidPtrSet,
  50                 class CloneAllocator = heap_clone_allocator
  51             >
  52             class ptr_set_adapter
  53             {
  54
  55             public: // `modifiers`_
  56                 std::pair<iterator,bool>  insert( Key* x );
  57                 template< class Key2 >
  58                 std::pair<iterator,bool>  insert( std::auto_ptr<Key2> x );
  59
  60             public: // `pointer container requirements`_
  61                 bool      transfer( iterator object, ptr_set_adapter& from );
  62                 size_type transfer( iterator first, iterator last, ptr_set_adapter& from );
  63                 template< class Range >
  64                 size_type transfer( const Range& r, ptr_set_adapter& from );
  65                 size_type transfer( ptr_set_adapter& from );
  66
  67             }; //  class 'ptr_set_adapter'
  68
  69         } // namespace 'boost'
  70
  71
  72 Semantics
  73 ---------
  74
  75 .. _`modifiers`:
  76
  77 Semantics: modifiers
  78 ^^^^^^^^^^^^^^^^^^^^
  79
  80 - ``std::pair<iterator,bool> insert( key_type* x );``
  81
  82     - Requirements: ``x != 0``
  83
  84     - Effects: Takes ownership of ``x`` and insert it if there is no equivalent of it already. The ``bool`` part of the return value indicates insertion and the iterator points to the element with key ``x``.
  85
  86     - Throws: bad_pointer if ``x == 0``
  87
  88     - Exception safety: Strong guarantee
  89
  90 - ``template< class Key2 > std::pair<iterator,bool>  insert( std::auto_ptr<Key2> x );``
  91
  92     - Effects: ``return insert( x.release() );``
  93
  94
  95 ..
  96         - ``std::pair<iterator,bool> insert( const key_type& x );``
  97
  98         - Effects: ``return insert( allocate_clone( x ) );``
  99
 100         - Exception safety: Strong guarantee
 101
 102 .. _`pointer container requirements`:
 103
 104 Semantics: pointer container requirements
 105 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 106
 107 - ``bool transfer( iterator object, ptr_set_adapter& from );``
 108
 109    - Requirements: ``not from.empty()``
 110
 111    - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``
 112      iff no equivalent object exists.
 113
 114    - Returns: whether the object was transfered
 115
 116    - Exception safety: Strong guarantee
 117
 118 - ``void transfer( iterator first, iterator last, ptr__set_adapter& from );``
 119
 120    - Requirements: ``not from.empty()``
 121
 122    - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``.
 123      An object is only transferred if no equivalent object exists.
 124
 125    - Returns: the number of transfered objects
 126
 127    - Exception safety: Basic guarantee
 128
 129 - ``template< class Range > void transfer( const Range& r, ptr_set_adapter& from );``
 130
 131     - Effects: ``return transfer( boost::begin(r), boost::end(r), from );``
 132
 133 - ``size_type transfer( ptr_set_adapter& from );``
 134
 135    - Effects: ``return transfer( from.begin(), from.end(), from );``.
 136
 137 .. raw:: html
 138
 139         <hr>
 140
 141 :Copyright:     Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
 142
 143 __ http://www.boost.org/LICENSE_1_0.txt
 144
 145