1++++++++++++++++++++++++++++++++++
2 |Boost| Pointer Container Library
3++++++++++++++++++++++++++++++++++
4
5.. |Boost| image:: boost.png
6
7Class ``associative_ptr_container``
8-------------------------------------
9
10This section describes all the common operations for all associative
11pointer 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
87Semantics
88---------
89
90.. _typedefs:
91
92Semantics: 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
112Semantics: 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
122Semantics: 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
167Semantics: 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
225