What are some uses of local iterator for STL unordered containers?

In §23.2.7 Unordered associative containers [unord.req] of the C++ standard table 91 describes the additional requirements a STL unordered associative container must meet. In this table the standard dictates that the STL unordered containers (i.e., unordered_set, unordered_map, unordered_multiset and unordered_multimap) must provide as member types local_iterator and const_local_iterator.

• local_iterator is an iterator type whose category, value, difference, pointer and reference types are the same as the unordered container's iterator. This iterator can be used to iterate through a single bucket but not across buckets.
• const_local_iterator is an iterator type whose category, value, difference, pointer and reference types are the same as the unordered container's const_iterator. This iterator can be used to iterate through a single bucket but not across buckets.

Q

What are some uses for these iterators?

The main thing I can see it being used for is to check how many collisions you have. Using bucket you can get what bucket a key is stored in. You can then pass that bucket value to begin which will return a local_iterator to the items in that bucket. Now you can iterate that bucket and see if you collide with any other elements and if you do, what those elements are. This, in turn, allows you to tune your hashing function.