From 42abfe3c7d217dd36c547ff7eaca442e99837d15 Mon Sep 17 00:00:00 2001 From: Christian Mazakas Date: Tue, 13 Sep 2022 14:53:14 -0700 Subject: [PATCH 1/4] Update docs for rehash/reserve for unordered_map --- doc/unordered/unordered_map.adoc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/unordered/unordered_map.adoc b/doc/unordered/unordered_map.adoc index 1ba03803..a174a580 100644 --- a/doc/unordered/unordered_map.adoc +++ b/doc/unordered/unordered_map.adoc @@ -1566,7 +1566,9 @@ Effects:;; Changes the container's maximum load factor, using `z` as a hint. void rehash(size_type n); ``` -Changes the number of buckets so that there at least `n` buckets, and so that the load factor is less than the maximum load factor. +Changes the number of buckets so that there are at least `n` buckets, and so that the load factor is less than or equal to the maximum load factor. When applicable, this will either grow or shrink the `bucket_count()` associated with the container. + +When `size() == 0`, `rehash(0)` will deallocate the underlying buckets array. Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated. @@ -1580,6 +1582,10 @@ Throws:;; The function has no effect if an exception is thrown, unless it is thr void reserve(size_type n); ``` +Equivalent to `a.rehash(ceil(n / a.max_load_factor()))`, or `a.rehash(1)` if `n > 0` and `a.max_load_factor() == std::numeric_limits::infinity()`. + +Similar to `rehash`, this function can be used to grow or shrink the number of buckets in the container. + Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated. [horizontal] From d338e9426729b2bb2c1aff99fd660cc0b22fbe20 Mon Sep 17 00:00:00 2001 From: Christian Mazakas Date: Wed, 14 Sep 2022 15:20:59 -0700 Subject: [PATCH 2/4] Update docs for rehash/reserve for unordered_set --- doc/unordered/unordered_set.adoc | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/unordered/unordered_set.adoc b/doc/unordered/unordered_set.adoc index 88645126..e9bb9312 100644 --- a/doc/unordered/unordered_set.adoc +++ b/doc/unordered/unordered_set.adoc @@ -1329,7 +1329,9 @@ Effects:;; Changes the container's maximum load factor, using `z` as a hint. void rehash(size_type n); ``` -Changes the number of buckets so that there at least `n` buckets, and so that the load factor is less than the maximum load factor. +Changes the number of buckets so that there are at least `n` buckets, and so that the load factor is less than or equal to the maximum load factor. When applicable, this will either grow or shrink the `bucket_count()` associated with the container. + +When `size() == 0`, `rehash(0)` will deallocate the underlying buckets array. Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated. @@ -1343,11 +1345,16 @@ Throws:;; The function has no effect if an exception is thrown, unless it is thr void reserve(size_type n); ``` +Equivalent to `a.rehash(ceil(n / a.max_load_factor()))`, or `a.rehash(1)` if `n > 0` and `a.max_load_factor() == std::numeric_limits::infinity()`. + +Similar to `rehash`, this function can be used to grow or shrink the number of buckets in the container. + Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated. [horizontal] Throws:;; The function has no effect if an exception is thrown, unless it is thrown by the container's hash function or comparison function. + === Equality Comparisons ==== operator== From 56b271850a7d24fec9bec10988a8d9b781df0be7 Mon Sep 17 00:00:00 2001 From: Christian Mazakas Date: Wed, 14 Sep 2022 15:21:07 -0700 Subject: [PATCH 3/4] Update docs for rehash/reserve for unordered_multiset --- doc/unordered/unordered_multiset.adoc | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/unordered/unordered_multiset.adoc b/doc/unordered/unordered_multiset.adoc index 5539b080..69f94bbe 100644 --- a/doc/unordered/unordered_multiset.adoc +++ b/doc/unordered/unordered_multiset.adoc @@ -1306,7 +1306,9 @@ Effects:;; Changes the container's maximum load factor, using `z` as a hint. void rehash(size_type n); ``` -Changes the number of buckets so that there at least `n` buckets, and so that the load factor is less than the maximum load factor. +Changes the number of buckets so that there are at least `n` buckets, and so that the load factor is less than or equal to the maximum load factor. When applicable, this will either grow or shrink the `bucket_count()` associated with the container. + +When `size() == 0`, `rehash(0)` will deallocate the underlying buckets array. Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated. @@ -1320,11 +1322,16 @@ Throws:;; The function has no effect if an exception is thrown, unless it is thr void reserve(size_type n); ``` +Equivalent to `a.rehash(ceil(n / a.max_load_factor()))`, or `a.rehash(1)` if `n > 0` and `a.max_load_factor() == std::numeric_limits::infinity()`. + +Similar to `rehash`, this function can be used to grow or shrink the number of buckets in the container. + Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated. [horizontal] Throws:;; The function has no effect if an exception is thrown, unless it is thrown by the container's hash function or comparison function. + --- === Equality Comparisons From 5dcccfda3b64cebcd6ce0afdf133548d1fafba43 Mon Sep 17 00:00:00 2001 From: Christian Mazakas Date: Wed, 14 Sep 2022 15:21:14 -0700 Subject: [PATCH 4/4] Update docs for rehash/reserve for unordered_multimap --- doc/unordered/unordered_multimap.adoc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/unordered/unordered_multimap.adoc b/doc/unordered/unordered_multimap.adoc index 08189570..f14f6a61 100644 --- a/doc/unordered/unordered_multimap.adoc +++ b/doc/unordered/unordered_multimap.adoc @@ -1345,7 +1345,9 @@ Effects:;; Changes the container's maximum load factor, using `z` as a hint. void rehash(size_type n); ``` -Changes the number of buckets so that there at least `n` buckets, and so that the load factor is less than the maximum load factor. +Changes the number of buckets so that there are at least `n` buckets, and so that the load factor is less than or equal to the maximum load factor. When applicable, this will either grow or shrink the `bucket_count()` associated with the container. + +When `size() == 0`, `rehash(0)` will deallocate the underlying buckets array. Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated. @@ -1359,6 +1361,10 @@ Throws:;; The function has no effect if an exception is thrown, unless it is thr void reserve(size_type n); ``` +Equivalent to `a.rehash(ceil(n / a.max_load_factor()))`, or `a.rehash(1)` if `n > 0` and `a.max_load_factor() == std::numeric_limits::infinity()`. + +Similar to `rehash`, this function can be used to grow or shrink the number of buckets in the container. + Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated. [horizontal]