libstdc++

unordered_map.h
Go to the documentation of this file.
1 // unordered_map implementation -*- C++ -*-
2
3 // Copyright (C) 2010-2013 Free Software Foundation, Inc.
4 //
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 3, or (at your option)
9 // any later version.
10
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
15
16 // Under Section 7 of GPL version 3, you are granted additional
17 // permissions described in the GCC Runtime Library Exception, version
18 // 3.1, as published by the Free Software Foundation.
19
20 // You should have received a copy of the GNU General Public License and
21 // a copy of the GCC Runtime Library Exception along with this program;
22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 // <http://www.gnu.org/licenses/>.
24
25 /** @file bits/unordered_map.h
26 * This is an internal header file, included by other library headers.
27 * Do not attempt to use it directly. @headername{unordered_map}
28 */
29
30 #ifndef _UNORDERED_MAP_H
31 #define _UNORDERED_MAP_H
32
33 namespace std _GLIBCXX_VISIBILITY(default)
34 {
35 _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
36
37 /// Base types for unordered_map.
38 template<bool _Cache>
39 using __umap_traits = __detail::_Hashtable_traits<_Cache, false, true>;
40
41 template<typename _Key,
42 typename _Tp,
43 typename _Hash = hash<_Key>,
44 typename _Pred = std::equal_to<_Key>,
45 typename _Alloc = std::allocator<std::pair<const _Key, _Tp> >,
46 typename _Tr = __umap_traits<__cache_default<_Key, _Hash>::value>>
47 using __umap_hashtable = _Hashtable<_Key, std::pair<const _Key, _Tp>,
48 _Alloc, __detail::_Select1st,
49 _Pred, _Hash,
50 __detail::_Mod_range_hashing,
51 __detail::_Default_ranged_hash,
52 __detail::_Prime_rehash_policy, _Tr>;
53
54 /// Base types for unordered_multimap.
55 template<bool _Cache>
56 using __ummap_traits = __detail::_Hashtable_traits<_Cache, false, false>;
57
58 template<typename _Key,
59 typename _Tp,
60 typename _Hash = hash<_Key>,
61 typename _Pred = std::equal_to<_Key>,
62 typename _Alloc = std::allocator<std::pair<const _Key, _Tp> >,
63 typename _Tr = __ummap_traits<__cache_default<_Key, _Hash>::value>>
64 using __ummap_hashtable = _Hashtable<_Key, std::pair<const _Key, _Tp>,
65 _Alloc, __detail::_Select1st,
66 _Pred, _Hash,
67 __detail::_Mod_range_hashing,
68 __detail::_Default_ranged_hash,
69 __detail::_Prime_rehash_policy, _Tr>;
70
71 /**
72 * @brief A standard container composed of unique keys (containing
73 * at most one of each key value) that associates values of another type
74 * with the keys.
75 *
76 * @ingroup unordered_associative_containers
77 *
78 * @tparam _Key Type of key objects.
79 * @tparam _Tp Type of mapped objects.
80 * @tparam _Hash Hashing function object type, defaults to hash<_Value>.
81 * @tparam _Pred Predicate function object type, defaults
82 * to equal_to<_Value>.
83 * @tparam _Alloc Allocator type, defaults to allocator<_Key>.
84 *
85 * Meets the requirements of a <a href="tables.html#65">container</a>, and
86 * <a href="tables.html#xx">unordered associative container</a>
87 *
88 * The resulting value type of the container is std::pair<const _Key, _Tp>.
89 *
90 * Base is _Hashtable, dispatched at compile time via template
91 * alias __umap_hashtable.
92 */
93 template<class _Key, class _Tp,
94 class _Hash = hash<_Key>,
95 class _Pred = std::equal_to<_Key>,
96 class _Alloc = std::allocator<std::pair<const _Key, _Tp> > >
97 class unordered_map : __check_copy_constructible<_Alloc>
98 {
99 typedef __umap_hashtable<_Key, _Tp, _Hash, _Pred, _Alloc> _Hashtable;
100 _Hashtable _M_h;
101
102 public:
103 // typedefs:
104 //@{
105 /// Public typedefs.
106 typedef typename _Hashtable::key_type key_type;
107 typedef typename _Hashtable::value_type value_type;
108 typedef typename _Hashtable::mapped_type mapped_type;
109 typedef typename _Hashtable::hasher hasher;
110 typedef typename _Hashtable::key_equal key_equal;
111 typedef typename _Hashtable::allocator_type allocator_type;
112 //@}
113
114 //@{
115 /// Iterator-related typedefs.
116 typedef typename allocator_type::pointer pointer;
117 typedef typename allocator_type::const_pointer const_pointer;
118 typedef typename allocator_type::reference reference;
119 typedef typename allocator_type::const_reference const_reference;
120 typedef typename _Hashtable::iterator iterator;
121 typedef typename _Hashtable::const_iterator const_iterator;
122 typedef typename _Hashtable::local_iterator local_iterator;
123 typedef typename _Hashtable::const_local_iterator const_local_iterator;
124 typedef typename _Hashtable::size_type size_type;
125 typedef typename _Hashtable::difference_type difference_type;
126 //@}
127
128 //construct/destroy/copy
129
130 /**
131 * @brief Default constructor creates no elements.
132 * @param __n Initial number of buckets.
133 * @param __hf A hash functor.
134 * @param __eql A key equality functor.
135 * @param __a An allocator object.
136 */
137 explicit
138 unordered_map(size_type __n = 10,
139 const hasher& __hf = hasher(),
140 const key_equal& __eql = key_equal(),
141 const allocator_type& __a = allocator_type())
142 : _M_h(__n, __hf, __eql, __a)
143 { }
144
145 /**
146 * @brief Builds an %unordered_map from a range.
147 * @param __first An input iterator.
148 * @param __last An input iterator.
149 * @param __n Minimal initial number of buckets.
150 * @param __hf A hash functor.
151 * @param __eql A key equality functor.
152 * @param __a An allocator object.
153 *
154 * Create an %unordered_map consisting of copies of the elements from
155 * [__first,__last). This is linear in N (where N is
156 * distance(__first,__last)).
157 */
158 template<typename _InputIterator>
159 unordered_map(_InputIterator __f, _InputIterator __l,
160 size_type __n = 0,
161 const hasher& __hf = hasher(),
162 const key_equal& __eql = key_equal(),
163 const allocator_type& __a = allocator_type())
164 : _M_h(__f, __l, __n, __hf, __eql, __a)
165 { }
166
167 /// Copy constructor.
168 unordered_map(const unordered_map&) = default;
169
170 /// Move constructor.
171 unordered_map(unordered_map&&) = default;
172
173 /**
174 * @brief Builds an %unordered_map from an initializer_list.
175 * @param __l An initializer_list.
176 * @param __n Minimal initial number of buckets.
177 * @param __hf A hash functor.
178 * @param __eql A key equality functor.
179 * @param __a An allocator object.
180 *
181 * Create an %unordered_map consisting of copies of the elements in the
182 * list. This is linear in N (where N is @a __l.size()).
183 */
184 unordered_map(initializer_list<value_type> __l,
185 size_type __n = 0,
186 const hasher& __hf = hasher(),
187 const key_equal& __eql = key_equal(),
188 const allocator_type& __a = allocator_type())
189 : _M_h(__l, __n, __hf, __eql, __a)
190 { }
191
192 /// Copy assignment operator.
193 unordered_map&
194 operator=(const unordered_map&) = default;
195
196 /// Move assignment operator.
197 unordered_map&
198 operator=(unordered_map&&) = default;
199
200 /**
201 * @brief %Unordered_map list assignment operator.
202 * @param __l An initializer_list.
203 *
204 * This function fills an %unordered_map with copies of the elements in
205 * the initializer list @a __l.
206 *
207 * Note that the assignment completely changes the %unordered_map and
208 * that the resulting %unordered_map's size is the same as the number
209 * of elements assigned. Old data may be lost.
210 */
211 unordered_map&
212 operator=(initializer_list<value_type> __l)
213 {
214 _M_h = __l;
215 return *this;
216 }
217
218 /// Returns the allocator object with which the %unordered_map was
219 /// constructed.
220 allocator_type
221 get_allocator() const noexcept
222 { return _M_h.get_allocator(); }
223
224 // size and capacity:
225
226 /// Returns true if the %unordered_map is empty.
227 bool
228 empty() const noexcept
229 { return _M_h.empty(); }
230
231 /// Returns the size of the %unordered_map.
232 size_type
233 size() const noexcept
234 { return _M_h.size(); }
235
236 /// Returns the maximum size of the %unordered_map.
237 size_type
238 max_size() const noexcept
239 { return _M_h.max_size(); }
240
241 // iterators.
242
243 /**
244 * Returns a read/write iterator that points to the first element in the
245 * %unordered_map.
246 */
247 iterator
248 begin() noexcept
249 { return _M_h.begin(); }
250
251 //@{
252 /**
253 * Returns a read-only (constant) iterator that points to the first
254 * element in the %unordered_map.
255 */
256 const_iterator
257 begin() const noexcept
258 { return _M_h.begin(); }
259
260 const_iterator
261 cbegin() const noexcept
262 { return _M_h.begin(); }
263 //@}
264
265 /**
266 * Returns a read/write iterator that points one past the last element in
267 * the %unordered_map.
268 */
269 iterator
270 end() noexcept
271 { return _M_h.end(); }
272
273 //@{
274 /**
275 * Returns a read-only (constant) iterator that points one past the last
276 * element in the %unordered_map.
277 */
278 const_iterator
279 end() const noexcept
280 { return _M_h.end(); }
281
282 const_iterator
283 cend() const noexcept
284 { return _M_h.end(); }
285 //@}
286
287 // modifiers.
288
289 /**
290 * @brief Attempts to build and insert a std::pair into the %unordered_map.
291 *
292 * @param __args Arguments used to generate a new pair instance (see
293 * std::piecewise_contruct for passing arguments to each
294 * part of the pair constructor).
295 *
296 * @return A pair, of which the first element is an iterator that points
297 * to the possibly inserted pair, and the second is a bool that
298 * is true if the pair was actually inserted.
299 *
300 * This function attempts to build and insert a (key, value) %pair into
301 * the %unordered_map.
302 * An %unordered_map relies on unique keys and thus a %pair is only
303 * inserted if its first element (the key) is not already present in the
304 * %unordered_map.
305 *
306 * Insertion requires amortized constant time.
307 */
308 template<typename... _Args>
309 std::pair<iterator, bool>
310 emplace(_Args&&... __args)
311 { return _M_h.emplace(std::forward<_Args>(__args)...); }
312
313 /**
314 * @brief Attempts to build and insert a std::pair into the %unordered_map.
315 *
316 * @param __pos An iterator that serves as a hint as to where the pair
317 * should be inserted.
318 * @param __args Arguments used to generate a new pair instance (see
319 * std::piecewise_contruct for passing arguments to each
320 * part of the pair constructor).
321 * @return An iterator that points to the element with key of the
322 * std::pair built from @a __args (may or may not be that
323 * std::pair).
324 *
325 * This function is not concerned about whether the insertion took place,
326 * and thus does not return a boolean like the single-argument emplace()
327 * does.
328 * Note that the first parameter is only a hint and can potentially
329 * improve the performance of the insertion process. A bad hint would
330 * cause no gains in efficiency.
331 *
332 * See
333 * http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt07ch17.html
334 * for more on @a hinting.
335 *
336 * Insertion requires amortized constant time.
337 */
338 template<typename... _Args>
339 iterator
340 emplace_hint(const_iterator __pos, _Args&&... __args)
341 { return _M_h.emplace_hint(__pos, std::forward<_Args>(__args)...); }
342
343 //@{
344 /**
345 * @brief Attempts to insert a std::pair into the %unordered_map.
346
347 * @param __x Pair to be inserted (see std::make_pair for easy
348 * creation of pairs).
349 *
350 * @return A pair, of which the first element is an iterator that
351 * points to the possibly inserted pair, and the second is
352 * a bool that is true if the pair was actually inserted.
353 *
354 * This function attempts to insert a (key, value) %pair into the
355 * %unordered_map. An %unordered_map relies on unique keys and thus a
356 * %pair is only inserted if its first element (the key) is not already
357 * present in the %unordered_map.
358 *
359 * Insertion requires amortized constant time.
360 */
361 std::pair<iterator, bool>
362 insert(const value_type& __x)
363 { return _M_h.insert(__x); }
364
365 template<typename _Pair, typename = typename
366 std::enable_if<std::is_constructible<value_type,
367 _Pair&&>::value>::type>
368 std::pair<iterator, bool>
369 insert(_Pair&& __x)
370 { return _M_h.insert(std::move(__x)); }
371 //@}
372
373 //@{
374 /**
375 * @brief Attempts to insert a std::pair into the %unordered_map.
376 * @param __hint An iterator that serves as a hint as to where the
377 * pair should be inserted.
378 * @param __x Pair to be inserted (see std::make_pair for easy creation
379 * of pairs).
380 * @return An iterator that points to the element with key of
381 * @a __x (may or may not be the %pair passed in).
382 *
383 * This function is not concerned about whether the insertion took place,
384 * and thus does not return a boolean like the single-argument insert()
385 * does. Note that the first parameter is only a hint and can
386 * potentially improve the performance of the insertion process. A bad
387 * hint would cause no gains in efficiency.
388 *
389 * See
390 * http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt07ch17.html
391 * for more on @a hinting.
392 *
393 * Insertion requires amortized constant time.
394 */
395 iterator
396 insert(const_iterator __hint, const value_type& __x)
397 { return _M_h.insert(__hint, __x); }
398
399 template<typename _Pair, typename = typename
400 std::enable_if<std::is_constructible<value_type,
401 _Pair&&>::value>::type>
402 iterator
403 insert(const_iterator __hint, _Pair&& __x)
404 { return _M_h.insert(__hint, std::move(__x)); }
405 //@}
406
407 /**
408 * @brief A template function that attempts to insert a range of
409 * elements.
410 * @param __first Iterator pointing to the start of the range to be
411 * inserted.
412 * @param __last Iterator pointing to the end of the range.
413 *
414 * Complexity similar to that of the range constructor.
415 */
416 template<typename _InputIterator>
417 void
418 insert(_InputIterator __first, _InputIterator __last)
419 { _M_h.insert(__first, __last); }
420
421 /**
422 * @brief Attempts to insert a list of elements into the %unordered_map.
423 * @param __l A std::initializer_list<value_type> of elements
424 * to be inserted.
425 *
426 * Complexity similar to that of the range constructor.
427 */
428 void
429 insert(initializer_list<value_type> __l)
430 { _M_h.insert(__l); }
431
432 //@{
433 /**
434 * @brief Erases an element from an %unordered_map.
435 * @param __position An iterator pointing to the element to be erased.
436 * @return An iterator pointing to the element immediately following
437 * @a __position prior to the element being erased. If no such
438 * element exists, end() is returned.
439 *
440 * This function erases an element, pointed to by the given iterator,
441 * from an %unordered_map.
442 * Note that this function only erases the element, and that if the
443 * element is itself a pointer, the pointed-to memory is not touched in
444 * any way. Managing the pointer is the user's responsibility.
445 */
446 iterator
447 erase(const_iterator __position)
448 { return _M_h.erase(__position); }
449
450 // LWG 2059.
451 iterator
452 erase(iterator __it)
453 { return _M_h.erase(__it); }
454 //@}
455
456 /**
457 * @brief Erases elements according to the provided key.
458 * @param __x Key of element to be erased.
459 * @return The number of elements erased.
460 *
461 * This function erases all the elements located by the given key from
462 * an %unordered_map. For an %unordered_map the result of this function
463 * can only be 0 (not present) or 1 (present).
464 * Note that this function only erases the element, and that if the
465 * element is itself a pointer, the pointed-to memory is not touched in
466 * any way. Managing the pointer is the user's responsibility.
467 */
468 size_type
469 erase(const key_type& __x)
470 { return _M_h.erase(__x); }
471
472 /**
473 * @brief Erases a [__first,__last) range of elements from an
474 * %unordered_map.
475 * @param __first Iterator pointing to the start of the range to be
476 * erased.
477 * @param __last Iterator pointing to the end of the range to
478 * be erased.
479 * @return The iterator @a __last.
480 *
481 * This function erases a sequence of elements from an %unordered_map.
482 * Note that this function only erases the elements, and that if
483 * the element is itself a pointer, the pointed-to memory is not touched
484 * in any way. Managing the pointer is the user's responsibility.
485 */
486 iterator
487 erase(const_iterator __first, const_iterator __last)
488 { return _M_h.erase(__first, __last); }
489
490 /**
491 * Erases all elements in an %unordered_map.
492 * Note that this function only erases the elements, and that if the
493 * elements themselves are pointers, the pointed-to memory is not touched
494 * in any way. Managing the pointer is the user's responsibility.
495 */
496 void
497 clear() noexcept
498 { _M_h.clear(); }
499
500 /**
501 * @brief Swaps data with another %unordered_map.
502 * @param __x An %unordered_map of the same element and allocator
503 * types.
504 *
505 * This exchanges the elements between two %unordered_map in constant time.
506 * Note that the global std::swap() function is specialized such that
507 * std::swap(m1,m2) will feed to this function.
508 */
509 void
510 swap(unordered_map& __x)
511 { _M_h.swap(__x._M_h); }
512
513 // observers.
514
515 /// Returns the hash functor object with which the %unordered_map was
516 /// constructed.
517 hasher
518 hash_function() const
519 { return _M_h.hash_function(); }
520
521 /// Returns the key comparison object with which the %unordered_map was
522 /// constructed.
523 key_equal
524 key_eq() const
525 { return _M_h.key_eq(); }
526
527 // lookup.
528
529 //@{
530 /**
531 * @brief Tries to locate an element in an %unordered_map.
532 * @param __x Key to be located.
533 * @return Iterator pointing to sought-after element, or end() if not
534 * found.
535 *
536 * This function takes a key and tries to locate the element with which
537 * the key matches. If successful the function returns an iterator
538 * pointing to the sought after element. If unsuccessful it returns the
539 * past-the-end ( @c end() ) iterator.
540 */
541 iterator
542 find(const key_type& __x)
543 { return _M_h.find(__x); }
544
545 const_iterator
546 find(const key_type& __x) const
547 { return _M_h.find(__x); }
548 //@}
549
550 /**
551 * @brief Finds the number of elements.
552 * @param __x Key to count.
553 * @return Number of elements with specified key.
554 *
555 * This function only makes sense for %unordered_multimap; for
556 * %unordered_map the result will either be 0 (not present) or 1
557 * (present).
558 */
559 size_type
560 count(const key_type& __x) const
561 { return _M_h.count(__x); }
562
563 //@{
564 /**
565 * @brief Finds a subsequence matching given key.
566 * @param __x Key to be located.
567 * @return Pair of iterators that possibly points to the subsequence
568 * matching given key.
569 *
570 * This function probably only makes sense for %unordered_multimap.
571 */
572 std::pair<iterator, iterator>
573 equal_range(const key_type& __x)
574 { return _M_h.equal_range(__x); }
575
576 std::pair<const_iterator, const_iterator>
577 equal_range(const key_type& __x) const
578 { return _M_h.equal_range(__x); }
579 //@}
580
581 //@{
582 /**
583 * @brief Subscript ( @c [] ) access to %unordered_map data.
584 * @param __k The key for which data should be retrieved.
585 * @return A reference to the data of the (key,data) %pair.
586 *
587 * Allows for easy lookup with the subscript ( @c [] )operator. Returns
588 * data associated with the key specified in subscript. If the key does
589 * not exist, a pair with that key is created using default values, which
590 * is then returned.
591 *
592 * Lookup requires constant time.
593 */
594 mapped_type&
595 operator[](const key_type& __k)
596 { return _M_h[__k]; }
597
598 mapped_type&
599 operator[](key_type&& __k)
600 { return _M_h[std::move(__k)]; }
601 //@}
602
603 //@{
604 /**
605 * @brief Access to %unordered_map data.
606 * @param __k The key for which data should be retrieved.
607 * @return A reference to the data whose key is equal to @a __k, if
608 * such a data is present in the %unordered_map.
609 * @throw std::out_of_range If no such data is present.
610 */
611 mapped_type&
612 at(const key_type& __k)
613 { return _M_h.at(__k); }
614
615 const mapped_type&
616 at(const key_type& __k) const
617 { return _M_h.at(__k); }
618 //@}
619
620 // bucket interface.
621
622 /// Returns the number of buckets of the %unordered_map.
623 size_type
624 bucket_count() const noexcept
625 { return _M_h.bucket_count(); }
626
627 /// Returns the maximum number of buckets of the %unordered_map.
628 size_type
629 max_bucket_count() const noexcept
630 { return _M_h.max_bucket_count(); }
631
632 /*
633 * @brief Returns the number of elements in a given bucket.
634 * @param __n A bucket index.
635 * @return The number of elements in the bucket.
636 */
637 size_type
638 bucket_size(size_type __n) const
639 { return _M_h.bucket_size(__n); }
640
641 /*
642 * @brief Returns the bucket index of a given element.
643 * @param __key A key instance.
644 * @return The key bucket index.
645 */
646 size_type
647 bucket(const key_type& __key) const
648 { return _M_h.bucket(__key); }
649
650 /**
651 * @brief Returns a read/write iterator pointing to the first bucket
652 * element.
653 * @param __n The bucket index.
654 * @return A read/write local iterator.
655 */
656 local_iterator
657 begin(size_type __n)
658 { return _M_h.begin(__n); }
659
660 //@{
661 /**
662 * @brief Returns a read-only (constant) iterator pointing to the first
663 * bucket element.
664 * @param __n The bucket index.
665 * @return A read-only local iterator.
666 */
667 const_local_iterator
668 begin(size_type __n) const
669 { return _M_h.begin(__n); }
670
671 const_local_iterator
672 cbegin(size_type __n) const
673 { return _M_h.cbegin(__n); }
674 //@}
675
676 /**
677 * @brief Returns a read/write iterator pointing to one past the last
678 * bucket elements.
679 * @param __n The bucket index.
680 * @return A read/write local iterator.
681 */
682 local_iterator
683 end(size_type __n)
684 { return _M_h.end(__n); }
685
686 //@{
687 /**
688 * @brief Returns a read-only (constant) iterator pointing to one past
689 * the last bucket elements.
690 * @param __n The bucket index.
691 * @return A read-only local iterator.
692 */
693 const_local_iterator
694 end(size_type __n) const
695 { return _M_h.end(__n); }
696
697 const_local_iterator
698 cend(size_type __n) const
699 { return _M_h.cend(__n); }
700 //@}
701
702 // hash policy.
703
704 /// Returns the average number of elements per bucket.
705 float
706 load_factor() const noexcept
707 { return _M_h.load_factor(); }
708
709 /// Returns a positive number that the %unordered_map tries to keep the
710 /// load factor less than or equal to.
711 float
712 max_load_factor() const noexcept
713 { return _M_h.max_load_factor(); }
714
715 /**
716 * @brief Change the %unordered_map maximum load factor.
717 * @param __z The new maximum load factor.
718 */
719 void
720 max_load_factor(float __z)
721 { _M_h.max_load_factor(__z); }
722
723 /**
724 * @brief May rehash the %unordered_map.
725 * @param __n The new number of buckets.
726 *
727 * Rehash will occur only if the new number of buckets respect the
728 * %unordered_map maximum load factor.
729 */
730 void
731 rehash(size_type __n)
732 { _M_h.rehash(__n); }
733
734 /**
735 * @brief Prepare the %unordered_map for a specified number of
736 * elements.
737 * @param __n Number of elements required.
738 *
739 * Same as rehash(ceil(n / max_load_factor())).
740 */
741 void
742 reserve(size_type __n)
743 { _M_h.reserve(__n); }
744
745 template<typename _Key1, typename _Tp1, typename _Hash1, typename _Pred1,
746 typename _Alloc1>
747 friend bool
748 operator==(const unordered_map<_Key1, _Tp1, _Hash1, _Pred1, _Alloc1>&,
749 const unordered_map<_Key1, _Tp1, _Hash1, _Pred1, _Alloc1>&);
750 };
751
752 /**
753 * @brief A standard container composed of equivalent keys
754 * (possibly containing multiple of each key value) that associates
755 * values of another type with the keys.
756 *
757 * @ingroup unordered_associative_containers
758 *
759 * @tparam _Key Type of key objects.
760 * @tparam _Tp Type of mapped objects.
761 * @tparam _Hash Hashing function object type, defaults to hash<_Value>.
762 * @tparam _Pred Predicate function object type, defaults
763 * to equal_to<_Value>.
764 * @tparam _Alloc Allocator type, defaults to allocator<_Key>.
765 *
766 * Meets the requirements of a <a href="tables.html#65">container</a>, and
767 * <a href="tables.html#xx">unordered associative container</a>
768 *
769 * The resulting value type of the container is std::pair<const _Key, _Tp>.
770 *
771 * Base is _Hashtable, dispatched at compile time via template
772 * alias __ummap_hashtable.
773 */
774 template<class _Key, class _Tp,
775 class _Hash = hash<_Key>,
776 class _Pred = std::equal_to<_Key>,
777 class _Alloc = std::allocator<std::pair<const _Key, _Tp> > >
778 class unordered_multimap : __check_copy_constructible<_Alloc>
779 {
780 typedef __ummap_hashtable<_Key, _Tp, _Hash, _Pred, _Alloc> _Hashtable;
781 _Hashtable _M_h;
782
783 public:
784 // typedefs:
785 //@{
786 /// Public typedefs.
787 typedef typename _Hashtable::key_type key_type;
788 typedef typename _Hashtable::value_type value_type;
789 typedef typename _Hashtable::mapped_type mapped_type;
790 typedef typename _Hashtable::hasher hasher;
791 typedef typename _Hashtable::key_equal key_equal;
792 typedef typename _Hashtable::allocator_type allocator_type;
793 //@}
794
795 //@{
796 /// Iterator-related typedefs.
797 typedef typename allocator_type::pointer pointer;
798 typedef typename allocator_type::const_pointer const_pointer;
799 typedef typename allocator_type::reference reference;
800 typedef typename allocator_type::const_reference const_reference;
801 typedef typename _Hashtable::iterator iterator;
802 typedef typename _Hashtable::const_iterator const_iterator;
803 typedef typename _Hashtable::local_iterator local_iterator;
804 typedef typename _Hashtable::const_local_iterator const_local_iterator;
805 typedef typename _Hashtable::size_type size_type;
806 typedef typename _Hashtable::difference_type difference_type;
807 //@}
808
809 //construct/destroy/copy
810
811 /**
812 * @brief Default constructor creates no elements.
813 * @param __n Initial number of buckets.
814 * @param __hf A hash functor.
815 * @param __eql A key equality functor.
816 * @param __a An allocator object.
817 */
818 explicit
819 unordered_multimap(size_type __n = 10,
820 const hasher& __hf = hasher(),
821 const key_equal& __eql = key_equal(),
822 const allocator_type& __a = allocator_type())
823 : _M_h(__n, __hf, __eql, __a)
824 { }
825
826 /**
827 * @brief Builds an %unordered_multimap from a range.
828 * @param __first An input iterator.
829 * @param __last An input iterator.
830 * @param __n Minimal initial number of buckets.
831 * @param __hf A hash functor.
832 * @param __eql A key equality functor.
833 * @param __a An allocator object.
834 *
835 * Create an %unordered_multimap consisting of copies of the elements
836 * from [__first,__last). This is linear in N (where N is
837 * distance(__first,__last)).
838 */
839 template<typename _InputIterator>
840 unordered_multimap(_InputIterator __f, _InputIterator __l,
841 size_type __n = 0,
842 const hasher& __hf = hasher(),
843 const key_equal& __eql = key_equal(),
844 const allocator_type& __a = allocator_type())
845 : _M_h(__f, __l, __n, __hf, __eql, __a)
846 { }
847
848 /// Copy constructor.
849 unordered_multimap(const unordered_multimap&) = default;
850
851 /// Move constructor.
852 unordered_multimap(unordered_multimap&&) = default;
853
854 /**
855 * @brief Builds an %unordered_multimap from an initializer_list.
856 * @param __l An initializer_list.
857 * @param __n Minimal initial number of buckets.
858 * @param __hf A hash functor.
859 * @param __eql A key equality functor.
860 * @param __a An allocator object.
861 *
862 * Create an %unordered_multimap consisting of copies of the elements in
863 * the list. This is linear in N (where N is @a __l.size()).
864 */
865 unordered_multimap(initializer_list<value_type> __l,
866 size_type __n = 0,
867 const hasher& __hf = hasher(),
868 const key_equal& __eql = key_equal(),
869 const allocator_type& __a = allocator_type())
870 : _M_h(__l, __n, __hf, __eql, __a)
871 { }
872
873 /// Copy assignment operator.
874 unordered_multimap&
875 operator=(const unordered_multimap&) = default;
876
877 /// Move assignment operator.
878 unordered_multimap&
879 operator=(unordered_multimap&&) = default;
880
881 /**
882 * @brief %Unordered_multimap list assignment operator.
883 * @param __l An initializer_list.
884 *
885 * This function fills an %unordered_multimap with copies of the elements
886 * in the initializer list @a __l.
887 *
888 * Note that the assignment completely changes the %unordered_multimap
889 * and that the resulting %unordered_multimap's size is the same as the
890 * number of elements assigned. Old data may be lost.
891 */
892 unordered_multimap&
893 operator=(initializer_list<value_type> __l)
894 {
895 _M_h = __l;
896 return *this;
897 }
898
899 /// Returns the allocator object with which the %unordered_multimap was
900 /// constructed.
901 allocator_type
902 get_allocator() const noexcept
903 { return _M_h.get_allocator(); }
904
905 // size and capacity:
906
907 /// Returns true if the %unordered_multimap is empty.
908 bool
909 empty() const noexcept
910 { return _M_h.empty(); }
911
912 /// Returns the size of the %unordered_multimap.
913 size_type
914 size() const noexcept
915 { return _M_h.size(); }
916
917 /// Returns the maximum size of the %unordered_multimap.
918 size_type
919 max_size() const noexcept
920 { return _M_h.max_size(); }
921
922 // iterators.
923
924 /**
925 * Returns a read/write iterator that points to the first element in the
926 * %unordered_multimap.
927 */
928 iterator
929 begin() noexcept
930 { return _M_h.begin(); }
931
932 //@{
933 /**
934 * Returns a read-only (constant) iterator that points to the first
935 * element in the %unordered_multimap.
936 */
937 const_iterator
938 begin() const noexcept
939 { return _M_h.begin(); }
940
941 const_iterator
942 cbegin() const noexcept
943 { return _M_h.begin(); }
944 //@}
945
946 /**
947 * Returns a read/write iterator that points one past the last element in
948 * the %unordered_multimap.
949 */
950 iterator
951 end() noexcept
952 { return _M_h.end(); }
953
954 //@{
955 /**
956 * Returns a read-only (constant) iterator that points one past the last
957 * element in the %unordered_multimap.
958 */
959 const_iterator
960 end() const noexcept
961 { return _M_h.end(); }
962
963 const_iterator
964 cend() const noexcept
965 { return _M_h.end(); }
966 //@}
967
968 // modifiers.
969
970 /**
971 * @brief Attempts to build and insert a std::pair into the
972 * %unordered_multimap.
973 *
974 * @param __args Arguments used to generate a new pair instance (see
975 * std::piecewise_contruct for passing arguments to each
976 * part of the pair constructor).
977 *
978 * @return An iterator that points to the inserted pair.
979 *
980 * This function attempts to build and insert a (key, value) %pair into
981 * the %unordered_multimap.
982 *
983 * Insertion requires amortized constant time.
984 */
985 template<typename... _Args>
986 iterator
987 emplace(_Args&&... __args)
988 { return _M_h.emplace(std::forward<_Args>(__args)...); }
989
990 /**
991 * @brief Attempts to build and insert a std::pair into the %unordered_multimap.
992 *
993 * @param __pos An iterator that serves as a hint as to where the pair
994 * should be inserted.
995 * @param __args Arguments used to generate a new pair instance (see
996 * std::piecewise_contruct for passing arguments to each
997 * part of the pair constructor).
998 * @return An iterator that points to the element with key of the
999 * std::pair built from @a __args.
1000 *
1001 * Note that the first parameter is only a hint and can potentially
1002 * improve the performance of the insertion process. A bad hint would
1003 * cause no gains in efficiency.
1004 *
1005 * See
1006 * http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt07ch17.html
1007 * for more on @a hinting.
1008 *
1009 * Insertion requires amortized constant time.
1010 */
1011 template<typename... _Args>
1012 iterator
1013 emplace_hint(const_iterator __pos, _Args&&... __args)
1014 { return _M_h.emplace_hint(__pos, std::forward<_Args>(__args)...); }
1015
1016 //@{
1017 /**
1018 * @brief Inserts a std::pair into the %unordered_multimap.
1019 * @param __x Pair to be inserted (see std::make_pair for easy
1020 * creation of pairs).
1021 *
1022 * @return An iterator that points to the inserted pair.
1023 *
1024 * Insertion requires amortized constant time.
1025 */
1026 iterator
1027 insert(const value_type& __x)
1028 { return _M_h.insert(__x); }
1029
1030 template<typename _Pair, typename = typename
1031 std::enable_if<std::is_constructible<value_type,
1032 _Pair&&>::value>::type>
1033 iterator
1034 insert(_Pair&& __x)
1035 { return _M_h.insert(std::move(__x)); }
1036 //@}
1037
1038 //@{
1039 /**
1040 * @brief Inserts a std::pair into the %unordered_multimap.
1041 * @param __hint An iterator that serves as a hint as to where the
1042 * pair should be inserted.
1043 * @param __x Pair to be inserted (see std::make_pair for easy creation
1044 * of pairs).
1045 * @return An iterator that points to the element with key of
1046 * @a __x (may or may not be the %pair passed in).
1047 *
1048 * Note that the first parameter is only a hint and can potentially
1049 * improve the performance of the insertion process. A bad hint would
1050 * cause no gains in efficiency.
1051 *
1052 * See
1053 * http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt07ch17.html
1054 * for more on @a hinting.
1055 *
1056 * Insertion requires amortized constant time.
1057 */
1058 iterator
1059 insert(const_iterator __hint, const value_type& __x)
1060 { return _M_h.insert(__hint, __x); }
1061
1062 template<typename _Pair, typename = typename
1063 std::enable_if<std::is_constructible<value_type,
1064 _Pair&&>::value>::type>
1065 iterator
1066 insert(const_iterator __hint, _Pair&& __x)
1067 { return _M_h.insert(__hint, std::move(__x)); }
1068 //@}
1069
1070 /**
1071 * @brief A template function that attempts to insert a range of
1072 * elements.
1073 * @param __first Iterator pointing to the start of the range to be
1074 * inserted.
1075 * @param __last Iterator pointing to the end of the range.
1076 *
1077 * Complexity similar to that of the range constructor.
1078 */
1079 template<typename _InputIterator>
1080 void
1081 insert(_InputIterator __first, _InputIterator __last)
1082 { _M_h.insert(__first, __last); }
1083
1084 /**
1085 * @brief Attempts to insert a list of elements into the
1086 * %unordered_multimap.
1087 * @param __l A std::initializer_list<value_type> of elements
1088 * to be inserted.
1089 *
1090 * Complexity similar to that of the range constructor.
1091 */
1092 void
1093 insert(initializer_list<value_type> __l)
1094 { _M_h.insert(__l); }
1095
1096 //@{
1097 /**
1098 * @brief Erases an element from an %unordered_multimap.
1099 * @param __position An iterator pointing to the element to be erased.
1100 * @return An iterator pointing to the element immediately following
1101 * @a __position prior to the element being erased. If no such
1102 * element exists, end() is returned.
1103 *
1104 * This function erases an element, pointed to by the given iterator,
1105 * from an %unordered_multimap.
1106 * Note that this function only erases the element, and that if the
1107 * element is itself a pointer, the pointed-to memory is not touched in
1108 * any way. Managing the pointer is the user's responsibility.
1109 */
1110 iterator
1111 erase(const_iterator __position)
1112 { return _M_h.erase(__position); }
1113
1114 // LWG 2059.
1115 iterator
1116 erase(iterator __it)
1117 { return _M_h.erase(__it); }
1118 //@}
1119
1120 /**
1121 * @brief Erases elements according to the provided key.
1122 * @param __x Key of elements to be erased.
1123 * @return The number of elements erased.
1124 *
1125 * This function erases all the elements located by the given key from
1126 * an %unordered_multimap.
1127 * Note that this function only erases the element, and that if the
1128 * element is itself a pointer, the pointed-to memory is not touched in
1129 * any way. Managing the pointer is the user's responsibility.
1130 */
1131 size_type
1132 erase(const key_type& __x)
1133 { return _M_h.erase(__x); }
1134
1135 /**
1136 * @brief Erases a [__first,__last) range of elements from an
1137 * %unordered_multimap.
1138 * @param __first Iterator pointing to the start of the range to be
1139 * erased.
1140 * @param __last Iterator pointing to the end of the range to
1141 * be erased.
1142 * @return The iterator @a __last.
1143 *
1144 * This function erases a sequence of elements from an
1145 * %unordered_multimap.
1146 * Note that this function only erases the elements, and that if
1147 * the element is itself a pointer, the pointed-to memory is not touched
1148 * in any way. Managing the pointer is the user's responsibility.
1149 */
1150 iterator
1151 erase(const_iterator __first, const_iterator __last)
1152 { return _M_h.erase(__first, __last); }
1153
1154 /**
1155 * Erases all elements in an %unordered_multimap.
1156 * Note that this function only erases the elements, and that if the
1157 * elements themselves are pointers, the pointed-to memory is not touched
1158 * in any way. Managing the pointer is the user's responsibility.
1159 */
1160 void
1161 clear() noexcept
1162 { _M_h.clear(); }
1163
1164 /**
1165 * @brief Swaps data with another %unordered_multimap.
1166 * @param __x An %unordered_multimap of the same element and allocator
1167 * types.
1168 *
1169 * This exchanges the elements between two %unordered_multimap in
1170 * constant time.
1171 * Note that the global std::swap() function is specialized such that
1172 * std::swap(m1,m2) will feed to this function.
1173 */
1174 void
1175 swap(unordered_multimap& __x)
1176 { _M_h.swap(__x._M_h); }
1177
1178 // observers.
1179
1180 /// Returns the hash functor object with which the %unordered_multimap
1181 /// was constructed.
1182 hasher
1183 hash_function() const
1184 { return _M_h.hash_function(); }
1185
1186 /// Returns the key comparison object with which the %unordered_multimap
1187 /// was constructed.
1188 key_equal
1189 key_eq() const
1190 { return _M_h.key_eq(); }
1191
1192 // lookup.
1193
1194 //@{
1195 /**
1196 * @brief Tries to locate an element in an %unordered_multimap.
1197 * @param __x Key to be located.
1198 * @return Iterator pointing to sought-after element, or end() if not
1199 * found.
1200 *
1201 * This function takes a key and tries to locate the element with which
1202 * the key matches. If successful the function returns an iterator
1203 * pointing to the sought after element. If unsuccessful it returns the
1204 * past-the-end ( @c end() ) iterator.
1205 */
1206 iterator
1207 find(const key_type& __x)
1208 { return _M_h.find(__x); }
1209
1210 const_iterator
1211 find(const key_type& __x) const
1212 { return _M_h.find(__x); }
1213 //@}
1214
1215 /**
1216 * @brief Finds the number of elements.
1217 * @param __x Key to count.
1218 * @return Number of elements with specified key.
1219 */
1220 size_type
1221 count(const key_type& __x) const
1222 { return _M_h.count(__x); }
1223
1224 //@{
1225 /**
1226 * @brief Finds a subsequence matching given key.
1227 * @param __x Key to be located.
1228 * @return Pair of iterators that possibly points to the subsequence
1229 * matching given key.
1230 */
1231 std::pair<iterator, iterator>
1232 equal_range(const key_type& __x)
1233 { return _M_h.equal_range(__x); }
1234
1235 std::pair<const_iterator, const_iterator>
1236 equal_range(const key_type& __x) const
1237 { return _M_h.equal_range(__x); }
1238 //@}
1239
1240 // bucket interface.
1241
1242 /// Returns the number of buckets of the %unordered_multimap.
1243 size_type
1244 bucket_count() const noexcept
1245 { return _M_h.bucket_count(); }
1246
1247 /// Returns the maximum number of buckets of the %unordered_multimap.
1248 size_type
1249 max_bucket_count() const noexcept
1250 { return _M_h.max_bucket_count(); }
1251
1252 /*
1253 * @brief Returns the number of elements in a given bucket.
1254 * @param __n A bucket index.
1255 * @return The number of elements in the bucket.
1256 */
1257 size_type
1258 bucket_size(size_type __n) const
1259 { return _M_h.bucket_size(__n); }
1260
1261 /*
1262 * @brief Returns the bucket index of a given element.
1263 * @param __key A key instance.
1264 * @return The key bucket index.
1265 */
1266 size_type
1267 bucket(const key_type& __key) const
1268 { return _M_h.bucket(__key); }
1269
1270 /**
1271 * @brief Returns a read/write iterator pointing to the first bucket
1272 * element.
1273 * @param __n The bucket index.
1274 * @return A read/write local iterator.
1275 */
1276 local_iterator
1277 begin(size_type __n)
1278 { return _M_h.begin(__n); }
1279
1280 //@{
1281 /**
1282 * @brief Returns a read-only (constant) iterator pointing to the first
1283 * bucket element.
1284 * @param __n The bucket index.
1285 * @return A read-only local iterator.
1286 */
1287 const_local_iterator
1288 begin(size_type __n) const
1289 { return _M_h.begin(__n); }
1290
1291 const_local_iterator
1292 cbegin(size_type __n) const
1293 { return _M_h.cbegin(__n); }
1294 //@}
1295
1296 /**
1297 * @brief Returns a read/write iterator pointing to one past the last
1298 * bucket elements.
1299 * @param __n The bucket index.
1300 * @return A read/write local iterator.
1301 */
1302 local_iterator
1303 end(size_type __n)
1304 { return _M_h.end(__n); }
1305
1306 //@{
1307 /**
1308 * @brief Returns a read-only (constant) iterator pointing to one past
1309 * the last bucket elements.
1310 * @param __n The bucket index.
1311 * @return A read-only local iterator.
1312 */
1313 const_local_iterator
1314 end(size_type __n) const
1315 { return _M_h.end(__n); }
1316
1317 const_local_iterator
1318 cend(size_type __n) const
1319 { return _M_h.cend(__n); }
1320 //@}
1321
1322 // hash policy.
1323
1324 /// Returns the average number of elements per bucket.
1325 float
1326 load_factor() const noexcept
1327 { return _M_h.load_factor(); }
1328
1329 /// Returns a positive number that the %unordered_multimap tries to keep
1330 /// the load factor less than or equal to.
1331 float
1332 max_load_factor() const noexcept
1333 { return _M_h.max_load_factor(); }
1334
1335 /**
1336 * @brief Change the %unordered_multimap maximum load factor.
1337 * @param __z The new maximum load factor.
1338 */
1339 void
1340 max_load_factor(float __z)
1341 { _M_h.max_load_factor(__z); }
1342
1343 /**
1344 * @brief May rehash the %unordered_multimap.
1345 * @param __n The new number of buckets.
1346 *
1347 * Rehash will occur only if the new number of buckets respect the
1348 * %unordered_multimap maximum load factor.
1349 */
1350 void
1351 rehash(size_type __n)
1352 { _M_h.rehash(__n); }
1353
1354 /**
1355 * @brief Prepare the %unordered_multimap for a specified number of
1356 * elements.
1357 * @param __n Number of elements required.
1358 *
1359 * Same as rehash(ceil(n / max_load_factor())).
1360 */
1361 void
1362 reserve(size_type __n)
1363 { _M_h.reserve(__n); }
1364
1365 template<typename _Key1, typename _Tp1, typename _Hash1, typename _Pred1,
1366 typename _Alloc1>
1367 friend bool
1368 operator==(const unordered_multimap<_Key1, _Tp1,
1369 _Hash1, _Pred1, _Alloc1>&,
1370 const unordered_multimap<_Key1, _Tp1,
1371 _Hash1, _Pred1, _Alloc1>&);
1372 };
1373
1374 template<class _Key, class _Tp, class _Hash, class _Pred, class _Alloc>
1375 inline void
1376 swap(unordered_map<_Key, _Tp, _Hash, _Pred, _Alloc>& __x,
1377 unordered_map<_Key, _Tp, _Hash, _Pred, _Alloc>& __y)
1378 { __x.swap(__y); }
1379
1380 template<class _Key, class _Tp, class _Hash, class _Pred, class _Alloc>
1381 inline void
1382 swap(unordered_multimap<_Key, _Tp, _Hash, _Pred, _Alloc>& __x,
1383 unordered_multimap<_Key, _Tp, _Hash, _Pred, _Alloc>& __y)
1384 { __x.swap(__y); }
1385
1386 template<class _Key, class _Tp, class _Hash, class _Pred, class _Alloc>
1387 inline bool
1388 operator==(const unordered_map<_Key, _Tp, _Hash, _Pred, _Alloc>& __x,
1389 const unordered_map<_Key, _Tp, _Hash, _Pred, _Alloc>& __y)
1390 { return __x._M_h._M_equal(__y._M_h); }
1391
1392 template<class _Key, class _Tp, class _Hash, class _Pred, class _Alloc>
1393 inline bool
1394 operator!=(const unordered_map<_Key, _Tp, _Hash, _Pred, _Alloc>& __x,
1395 const unordered_map<_Key, _Tp, _Hash, _Pred, _Alloc>& __y)
1396 { return !(__x == __y); }
1397
1398 template<class _Key, class _Tp, class _Hash, class _Pred, class _Alloc>
1399 inline bool
1400 operator==(const unordered_multimap<_Key, _Tp, _Hash, _Pred, _Alloc>& __x,
1401 const unordered_multimap<_Key, _Tp, _Hash, _Pred, _Alloc>& __y)
1402 { return __x._M_h._M_equal(__y._M_h); }
1403
1404 template<class _Key, class _Tp, class _Hash, class _Pred, class _Alloc>
1405 inline bool
1406 operator!=(const unordered_multimap<_Key, _Tp, _Hash, _Pred, _Alloc>& __x,
1407 const unordered_multimap<_Key, _Tp, _Hash, _Pred, _Alloc>& __y)
1408 { return !(__x == __y); }
1409
1410 _GLIBCXX_END_NAMESPACE_CONTAINER
1411 } // namespace std
1412
1413 #endif /* _UNORDERED_MAP_H */