documented stats

doc/unordered/unordered_flat_map.adoc

@@ -58,6 +58,8 @@ namespace boost {
     using iterator             = _implementation-defined_;
     using const_iterator       = _implementation-defined_;
 
+    using stats                = xref:stats_stats_type[__stats-type__]; // if statistics are xref:unordered_flat_map_boost_unordered_enable_stats[enabled]
+
     // construct/copy/destroy
     xref:#unordered_flat_map_default_constructor[unordered_flat_map]();
     explicit xref:#unordered_flat_map_bucket_count_constructor[unordered_flat_map](size_type n,
@@ -214,6 +216,10 @@ namespace boost {
     size_type xref:#unordered_flat_map_max_load[max_load]() const noexcept;
     void xref:#unordered_flat_map_rehash[rehash](size_type n);
     void xref:#unordered_flat_map_reserve[reserve](size_type n);
+
+    // statistics (if xref:unordered_flat_map_boost_unordered_enable_stats[enabled])
+    stats xref:#unordered_flat_map_get_stats[get_stats]() const;
+    void xref:#unordered_flat_map_reset_stats[reset_stats]() noexcept;
   };
 
   // Deduction Guides
@@ -343,6 +349,15 @@ at the expense of extra computational cost.
 
 ---
 
+=== Configuration Macros
+
+==== `BOOST_UNORDERED_ENABLE_STATS`
+
+Globally define this macro to enable xref:#stats[statistics calculation] for the container. Note
+that this option decreases the overall performance of many operations.
+
+---
+
 === Typedefs
 
 [source,c++,subs=+quotes]
@@ -439,6 +454,8 @@ unordered_flat_map(unordered_flat_map&& other);
 
 The move constructor. The internal bucket array of `other` is transferred directly to the new container.
 The hash function, predicate and allocator are moved-constructed from `other`.
+If statistics are xref:unordered_flat_map_boost_unordered_enable_stats[enabled],
+transfers the internal statistical information from `other` and calls `other.reset_stats()`.
 
 ---
 
@@ -481,6 +498,9 @@ unordered_flat_map(unordered_flat_map&& other, Allocator const& a);
 If `a == other.get_allocator()`, the elements of `other` are transferred directly to the new container;
 otherwise, elements are moved-constructed from those of `other`. The hash function and predicate are moved-constructed
 from `other`, and the allocator is copy-constructed from `a`.
+If statistics are xref:unordered_flat_map_boost_unordered_enable_stats[enabled],
+transfers the internal statistical information from `other` iff `a == other.get_allocator()`,
+and always calls `other.reset_stats()`.
 
 ---
 
@@ -493,6 +513,8 @@ unordered_flat_map(concurrent_flat_map<Key, T, Hash, Pred, Allocator>&& other);
 Move construction from a xref:#concurrent_flat_map[`concurrent_flat_map`].
 The internal bucket array of `other` is transferred directly to the new container.
 The hash function, predicate and allocator are moved-constructed from `other`.
+If statistics are xref:unordered_flat_map_boost_unordered_enable_stats[enabled],
+transfers the internal statistical information from `other` and calls `other.reset_stats()`.
 
 [horizontal]
 Complexity:;; Constant time.
@@ -651,6 +673,9 @@ The move assignment operator. Destroys previously existing elements, swaps the h
 and move-assigns the allocator from `other` if `Alloc::propagate_on_container_move_assignment` exists and `Alloc::propagate_on_container_move_assignment::value` is `true`.
 If at this point the allocator is equal to `other.get_allocator()`, the internal bucket array of `other` is transferred directly to the new container;
 otherwise, inserts move-constructed copies of the elements of `other`.
+If statistics are xref:unordered_flat_map_boost_unordered_enable_stats[enabled],
+transfers the internal statistical information from `other` iff the final allocator is equal to `other.get_allocator()`,
+and always calls `other.reset_stats()`.
 
 ---
 
@@ -1364,6 +1389,32 @@ Invalidates iterators, pointers and references, and changes the order of element
 [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.
 
+---
+
+=== Statistics
+
+==== get_stats
+```c++
+stats get_stats() const;
+```
+
+[horizontal]
+Returns:;; A statistical description of the insertion and lookup operations performed by the container so far.
+Notes:;; Only available if xref:stats[statistics calculation] is xref:unordered_flat_map_boost_unordered_enable_stats[enabled].
+
+---
+
+==== reset_stats
+```c++
+void reset_stats() noexcept;
+```
+
+[horizontal]
+Effects:;; Sets to zero the internal statistics kept by the container.
+Notes:;; Only available if xref:stats[statistics calculation] is xref:unordered_flat_map_boost_unordered_enable_stats[enabled].
+
+---
+
 === Deduction Guides
 A deduction guide will not participate in overload resolution if any of the following are true: