diff --git a/doc/unordered/buckets.adoc b/doc/unordered/buckets.adoc index 0844b81d..42ec9189 100644 --- a/doc/unordered/buckets.adoc +++ b/doc/unordered/buckets.adoc @@ -142,14 +142,13 @@ h|*Method* h|*Description* |=== -A note on `max_load` for open-addressing containers: the maximum load will naturally decrease when -new insertions are performed, but _won't_ increase at the same rate when erasing: for instance, -adding 1,000 elements to a <> under high load -conditions and then erasing 1,000 elements will typically reduce the maximum load by around -a few dozen elements rather than restoring it to its original value. This is done internally by Boost.Unordered in order +A note on `max_load` for open-addressing containers: the maximum load will be +(`max_load_factor() * bucket_count()`) right after `rehash` or on container creation, but may +slightly decrease when erasing elements in high-load situations. For instance, if we +have a <> with `size()` almost +at `max_load()` level and then erase 1,000 elements, `max_load()` may decrease by around a +few dozen elements. This is done internally by Boost.Unordered in order to keep its performance stable, and must be taken into account when planning for rehash-free insertions. -The maximum load will be reset to its theoretical maximum -(`max_load_factor() * bucket_count()`) right after `rehash`. == Iterator Invalidation diff --git a/doc/unordered/compliance.adoc b/doc/unordered/compliance.adoc index f8e0b05d..16e869db 100644 --- a/doc/unordered/compliance.adoc +++ b/doc/unordered/compliance.adoc @@ -139,5 +139,5 @@ The main differences with C++ unordered associative containers are: * `erase(iterator)` returns `void` instead of an iterator to the following element. * There is no API for bucket handling (except `bucket_count`) or node extraction/insertion. * The maximum load factor of the container is managed internally and can't be set by the user. The maximum load, -exposed through the public function `max_load`, does not increase monotonically with the number of erasures. +exposed through the public function `max_load`, may decrease on erasure under high-load conditions. diff --git a/doc/unordered/unordered_flat_map.adoc b/doc/unordered/unordered_flat_map.adoc index 92a233c8..8d747f55 100644 --- a/doc/unordered/unordered_flat_map.adoc +++ b/doc/unordered/unordered_flat_map.adoc @@ -1173,8 +1173,8 @@ size_type max_load() const noexcept; [horizontal] Returns:;; The maximum number of elements the container can hold without rehashing, assuming that no further elements will be erased. -Note:;; After construction, rehash or clearance, the container's maximum load is at least `max_load_factor() * bucket_count()`. This load will decrease by the number of elements inserted, -but won't increase at the same rate on erasure. +Note:;; After construction, rehash or clearance, the container's maximum load is at least `max_load_factor() * bucket_count()`. +This number may decrease on erasure under high-load conditions. --- diff --git a/doc/unordered/unordered_flat_set.adoc b/doc/unordered/unordered_flat_set.adoc index b03b4801..0fff40d3 100644 --- a/doc/unordered/unordered_flat_set.adoc +++ b/doc/unordered/unordered_flat_set.adoc @@ -972,8 +972,8 @@ size_type max_load() const noexcept; [horizontal] Returns:;; The maximum number of elements the container can hold without rehashing, assuming that no further elements will be erased. -Note:;; After construction, rehash or clearance, the container's maximum load is at least `max_load_factor() * bucket_count()`. This load will decrease by the number of elements inserted, -but won't increase at the same rate on erasure. +Note:;; After construction, rehash or clearance, the container's maximum load is at least `max_load_factor() * bucket_count()`. +This number may decrease on erasure under high-load conditions. ---