This page is a snapshot from the LWG issues list, see the Library Active Issues List for more information and the meaning of NAD status.

764. equal_range on unordered containers should return a pair of local_iterators

Section: 24.2.8 [unord.req] Status: NAD Submitter: Joe Gottman Opened: 2007-11-29 Last modified: 2016-01-28

Priority: Not Prioritized

View other active issues in [unord.req].

View all other issues in [unord.req].

View all issues with NAD status.

Discussion:

A major attribute of the unordered containers is that iterating though them inside a bucket is very fast while iterating between buckets can be much slower. If an unordered container has a low load factor, iterating between the last iterator in one bucket and the next iterator, which is in another bucket, is O(bucket_count()) which may be much larger than O(size()).

If b is an non-const unordered container of type B and k is an object of it's key_type, then b.equal_range(k) currently returns pair<B::iterator, B::iterator>. Consider the following code:

B::iterator lb, ub;
tie(lb, ub) = b.equal_range(k);
for (B::iterator it = lb; it != ub; ++it) {
        // Do something with *it
}

If b.equal_range(k) returns a non-empty range (i.e. b contains at least on element whose key is equivalent to k), then every iterator in the half-open range [lb, ub) will be in the same bucket, but ub will likely either be in a different bucket or be equal to b.end(). In either case, iterating between ub - 1 and ub could take a much longer time than iterating through the rest of the range.

If instead of returning pair<iterator, iterator>, equal_range were to return pair<local_iterator, local_iterator>, then ub (which, like lb, would now be a local_iterator) could be guaranteed to always be in the same bucket as lb. In the cases where currently ub is equal to b.end() or is in a different bucket, ub would be equal to b.end(b.bucket(key)). This would make iterating between lb and ub much faster, as every iteration would be constant time.

[ Bellevue: ]

The proposed resolution breaks consistency with other container types for dubious benefit, and iterators are already constant time.

Proposed resolution:

Change the entry for equal_range in Table 93 (24.2.8 [unord.req]) as follows:

expression return type assertion/note pre/post-condition complexity
b.equal_range(k) pair<local_iterator,local_iterator>; pair<const_local_iterator,const_local_iterator> for const b. Returns a range containing all elements with keys equivalent to k. Returns make_pair(b.end(b.bucket(key)),b.end(b.bucket(key))) if no such elements exist. Average case Θ(b.count(k)). Worst case Θ(b.size()).