ceph/src/boost/libs/ptr_container/doc/associative_ptr_container.rst

   1 ++++++++++++++++++++++++++++++++++
   2  |Boost| Pointer Container Library
   3 ++++++++++++++++++++++++++++++++++
   4
   5 .. |Boost| image:: boost.png
   6
   7 Class ``associative_ptr_container``
   8 -------------------------------------
   9
  10 This section describes all the common operations for all associative
  11 pointer containers (in addition to ``reversible_ptr_container``).
  12
  13 **Hierarchy:**
  14
  15 - `reversible_ptr_container <reversible_ptr_container.html>`_
  16
  17   - ``associative_ptr_container``
  18
  19     - `ptr_set_adapter <ptr_set_adapter.html>`_
  20     - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_
  21     - `ptr_map_adapter <ptr_map_adapter.html>`_
  22     - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_
  23
  24       - `ptr_set <ptr_set.html>`_
  25       - `ptr_multi_set <ptr_multiset.html>`_
  26       - `ptr_map <ptr_map.html>`_
  27       - `ptr_multimap <ptr_multimap.html>`_
  28
  29 **See also:**
  30
  31 - `iterator_range <http://www.boost.org/libs/range/doc/utility_class.html#iter_range>`_
  32
  33 **Navigate:**
  34
  35 - `home <ptr_container.html>`_
  36 - `reference <reference.html>`_
  37
  38 **Synopsis:**
  39
  40 .. parsed-literal::
  41
  42         namespace boost
  43         {
  44             template
  45             <
  46                 class Key,
  47                 class CloneAllocator = heap_clone_allocator
  48             >
  49             class associative_ptr_container
  50             {
  51             public: // typedefs_
  52                 typedef ...   key_type;
  53                 typedef ...   key_compare;
  54                 typedef ...   value_compare;
  55
  56             public: // `observers`_
  57                 key_compare    key_comp() const;
  58                 value_compare  value_comp() const;
  59
  60             public: // `modifiers`_
  61                 template< typename InputIterator >
  62                 void       insert( InputIterator first, InputIterator last );
  63                 template< class InputRange >
  64                 void       insert( const InputRange& r );
  65                 void       erase( iterator position );
  66                 size_type  erase( const key_type& x );
  67                 template< class Range >
  68                 void       erase( const Range& r );
  69                 void       erase( iterator first, iterator last );
  70
  71             public: // `algorithms`_
  72                 iterator                        find( const key_type& x );
  73                 const_iterator                  find( const key_type& x ) const;
  74                 size_type                       count( const key_type& x ) const;
  75                 iterator                        lower_bound( const key_type& x );
  76                 const_iterator                  lower_bound( const key_type& x ) const;
  77                 iterator                        upper_bound( const key_type& x );
  78                 const_iterator                  upper_bound( const key_type& x ) const;
  79                 iterator_range<iterator>        equal_range( const key_type& x );
  80                 iterator_range<const_iterator>  equal_range( const key_type& x ) const;
  81
  82             }; //  class 'associative_ptr_container'
  83
  84         } // namespace 'boost'
  85
  86
  87 Semantics
  88 ---------
  89
  90 .. _typedefs:
  91
  92 Semantics: typedefs
  93 ^^^^^^^^^^^^^^^^^^^
  94
  95 - ``typedef ... key_type;``
  96
  97     - if we are dealing with a map, then simply the key type
  98     - if we are dealing with a set, then the *indirected* key type, that is,
  99       given ``ptr_set<T>``, ``key_type*`` will be ``T*``.
 100
 101 - ``typedef ... key_compare;``
 102
 103     -  comparison object type that determines the order of elements in the container
 104
 105 - ``typedef ... value_compare;``
 106
 107     - comparison object type that determines the order of elements in the container
 108     - if we are dealing with a map, then this comparison simply forwards to the ``key_compare`` comparison operation
 109
 110 .. _`observers`:
 111
 112 Semantics: observers
 113 ^^^^^^^^^^^^^^^^^^^^
 114
 115 - ``key_compare key_comp() const;``
 116 - ``value_compare value_comp() const;``
 117
 118     - returns copies of objects used to determine the order of elements
 119
 120 .. _`modifiers`:
 121
 122 Semantics: modifiers
 123 ^^^^^^^^^^^^^^^^^^^^
 124
 125 - ``template< typename InputIterator >
 126   void insert( InputIterator first, InputIterator last );``
 127
 128     - Requirements: ``[first,last)`` is a valid range
 129
 130     - Effects: Inserts a cloned range
 131
 132     - Exception safety: Basic guarantee
 133
 134 - ``template< class InputRange >
 135   void insert( const InputRange& r );``
 136
 137     - Effects: ``insert( boost::begin(r), boost::end(r) );``
 138
 139 - ``void erase( iterator position );``
 140
 141     - Requirements: ``position`` is a valid iterator from the container
 142
 143     - Effects: Removes the element defined by ``position``.
 144
 145     - Throws: Nothing
 146
 147 - ``size_type erase( const key_type& x );``
 148
 149     - Effects: Removes all the elements in the container with a key equivalent to ``x`` and returns the number of erased elements.
 150
 151     - Throws: Nothing
 152
 153 - ``void erase( iterator first, iterator last );``
 154
 155     - Requirements: ``[first,last)`` is a valid range
 156
 157     - Effects: Removes the range of elements defined by ``[first,last)``.
 158
 159     - Throws: Nothing
 160
 161 - ``template< class Range > void erase( const Range& r );``
 162
 163     - Effects: ``erase( boost::begin(r), boost::end(r) );``
 164
 165 .. _`algorithms`:
 166
 167 Semantics: algorithms
 168 ^^^^^^^^^^^^^^^^^^^^^
 169
 170 - ``iterator       find( const Key& x );``
 171 - ``const_iterator find( const Key& x ) const;``
 172
 173     - Effects: Searches for the key and returns ``end()`` on failure.
 174
 175     - Complexity: Logarithmic
 176
 177 - ``size_type count( const Key& x ) const;``
 178
 179     - Effects: Counts the elements with a key equivalent to ``x``
 180
 181     - Complexity: Logarithmic
 182
 183 - ``iterator       lower_bound( const Key& x );``
 184 - ``const_iterator lower_bound( const Key& x ) const;``
 185
 186     - Effects: Returns an iterator pointing to the first element with a key not less than ``x``
 187
 188     - Complexity: Logarithmic
 189
 190 - ``iterator       upper_bound( const Key& x );``
 191 - ``const_iterator upper_bound( const Key& x ) const;``
 192
 193     - Effects: Returns an iterator pointing to the first element with a key greater than ``x``
 194
 195     - Complexity: Logarithmic
 196
 197 - ``iterator_range<iterator>       equal_range( const Key& x );``
 198 - ``iterator_range<const_iterator> equal_range( const Key& x ) const;``
 199
 200     - Effects: ``return boost::make_iterator_range( lower_bound( x ), upper_bound( x ) );``
 201
 202     - Complexity: Logarithmic
 203
 204 ..
 205         - ``reference       at( const key_type& key );``
 206         - ``const_reference at( const key_type& key ) const;``
 207
 208         - Requirements: the key exists
 209
 210         - Effects: returns the object with key ``key``
 211
 212         - Throws: ``bad_ptr_container_operation`` if the key does not exist
 213
 214
 215 .. _`pointer container requirements`:
 216
 217 .. raw:: html
 218
 219         <hr>
 220
 221 :Copyright:     Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
 222
 223 __ http://www.boost.org/LICENSE_1_0.txt
 224