Merge pull request #146 from cmazakas/feature/rehash-doc-updates

Rehash Doc Updates

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<float>::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]

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<float>::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]

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<float>::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

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<float>::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==