Optimize the is_permutation family and _Hash::operator== for multicontainers

[BillyONeal]

<xutility>
4660: _Find_pr is a helper for is_permutation, so move it down to that area.
4684: The SHOUTY banners were attached to functions which were implementation details of is_permutation, so I fixed them up to say is_permutation and removed the banners for helper functions.
4711: Use if constexpr to avoid a tag dispatch call for _Trim_matching_suffixes. Optimizers will like this because they generally hate reference-to-pointer, and it also serves to workaround DevCom-883631 when this algorithm is constexprized.
4766: Indicate that we are trimming matching prefixes in this loop body, and break apart comment block that was incorrectly merged by clang-format.
4817: In the dual range forward version of the algorithm, calculate the distances concurrently to avoid wasting lots of time when the distances vary by a lot. For example, is_permutation( a forward range of length 1, a forward range of length 1'000'000 ) used to do the million increments, now it stops at 1 increment.
4862: In the dual range random-access version, avoid recalculating _Last2 when it has already been supplied to us.

<xhash>
1404: Move down construction of _Bucket_hi in _Equal_range to before the first loop body using it.
1918: Added a new function to calculate equality for unordered multicontainers. We loop over the elements in the left container, find corresponding ranges in the right container, trim prefixes, then dispatch to is_permutation's helper _Check_match_counts.
Improvements over the old implementation:

• For standard containers, we no longer need to hash any elements from the left container; we know that we've found the "run" of equivalent elements because we started with an element in that container. We also never go "backwards" or multiply enumerate _Left (even for !_Standard), which improves cache use when the container becomes large.
• Just like the dual range is_permutation improvement above, when the equal_ranges of the containers are of wildly varying lengths, this will stop on the shorter of the lengths.
• We avoid the 3-arg is_permutation doing a linear time operation to discover _Last2 that we already had calculated in determining _Right's equal_range.

The function _Multi_equal_check_equal_range tests one equal_range from the left container against the corresponding equal_range from the right container, while _Multi_equal invokes _Multi_equal_check_equal_range for each equal_range.

Performance results:

Benchmark code:

#undef NDEBUG
#define _SILENCE_STDEXT_HASH_DEPRECATION_WARNINGS
#include <assert.h>
#include <benchmark/benchmark.h>
#include <hash_map>
#include <random>
#include <stddef.h>
#include <unordered_map>
#include <utility>
#include <vector>

using namespace std;

template <template <class...> class MapType> void HashRandomUnequal(benchmark::State &state) {
    std::minstd_rand rng(std::random_device{}());
    const auto range0 = static_cast<ptrdiff_t>(state.range(0));
    vector<pair<unsigned, unsigned>> testData;
    testData.resize(range0 * 5);
    const auto dataEnd = testData.begin() + range0;
    std::generate(testData.begin(), dataEnd, [&]() { return pair<unsigned, unsigned>{rng(), 0u}; });
    std::copy(testData.begin(), dataEnd,
              std::copy(testData.begin(), dataEnd,
                        std::copy(testData.begin(), dataEnd, std::copy(testData.begin(), dataEnd, dataEnd))));
    std::unordered_multimap<unsigned, unsigned> a(testData.begin(), testData.end());
    testData.clear();
    std::unordered_multimap<unsigned, unsigned> b = a;
    next(b.begin(), b.size() - 1)->second = 1u;
    for (auto &&_ : state) {
        (void)_;
        assert(a != b);
    }
}

BENCHMARK_TEMPLATE1(HashRandomUnequal, unordered_multimap)->Arg(1)->Arg(10)->Range(100, 100'000);
BENCHMARK_TEMPLATE1(HashRandomUnequal, hash_multimap)->Arg(1)->Arg(10)->Range(100, 100'000);

template <template <class...> class MapType> void HashRandomEqual(benchmark::State &state) {
    std::minstd_rand rng(std::random_device{}());
    const auto range0 = static_cast<ptrdiff_t>(state.range(0));
    vector<pair<unsigned, unsigned>> testData;
    testData.resize(range0 * 5);
    const auto dataEnd = testData.begin() + range0;
    std::generate(testData.begin(), dataEnd, [&]() { return pair<unsigned, unsigned>{rng(), 0}; });
    std::copy(testData.begin(), dataEnd,
              std::copy(testData.begin(), dataEnd,
                        std::copy(testData.begin(), dataEnd, std::copy(testData.begin(), dataEnd, dataEnd))));
    std::unordered_multimap<unsigned, unsigned> a(testData.begin(), testData.end());
    testData.clear();
    std::unordered_multimap<unsigned, unsigned> b = a;
    for (auto &&_ : state) {
        (void)_;
        assert(a == b);
    }
}

BENCHMARK_TEMPLATE1(HashRandomEqual, unordered_multimap)->Arg(1)->Arg(10)->Range(100, 100'000);
BENCHMARK_TEMPLATE1(HashRandomEqual, hash_multimap)->Arg(1)->Arg(10)->Range(100, 100'000);

template <template <class...> class MapType> void HashUnequalDifferingBuckets(benchmark::State &state) {
    std::unordered_multimap<unsigned, unsigned> a;
    std::unordered_multimap<unsigned, unsigned> b;
    const auto range0 = static_cast<ptrdiff_t>(state.range(0));
    for (ptrdiff_t idx = 0; idx < range0; ++idx) {
        a.emplace(0, 1);
        b.emplace(1, 0);
    }

    a.emplace(1, 0);
    b.emplace(0, 1);
    for (auto &&_ : state) {
        (void)_;
        assert(a != b);
    }
}

BENCHMARK_TEMPLATE1(HashUnequalDifferingBuckets, unordered_multimap)->Arg(2)->Arg(10)->Range(100, 100'000);
BENCHMARK_TEMPLATE1(HashUnequalDifferingBuckets, hash_multimap)->Arg(2)->Arg(10)->Range(100, 100'000);

BENCHMARK_MAIN();

Checklist

Be sure you've read README.md and understand the scope of this repo.

If you're unsure about a box, leave it unchecked. A maintainer will help you.

• Identifiers in product code changes are properly _Ugly as per
  https://eel.is/c++draft/lex.name#3.1 or there are no product code changes.
• The STL builds successfully and all tests have passed (must be manually
  verified by an STL maintainer before automated testing is enabled on GitHub,
  leave this unchecked for initial submission).
• These changes introduce no known ABI breaks (adding members, renaming
  members, adding virtual functions, changing whether a type is an aggregate
  or trivially copyable, etc.).
• These changes were written from scratch using only this repository,
  the C++ Working Draft (including any cited standards), other WG21 papers
  (excluding reference implementations outside of proposed standard wording),
  and LWG issues as reference material. If they were derived from a project
  that's already listed in NOTICE.txt, that's fine, but please mention it.
  If they were derived from any other project (including Boost and libc++,
  which are not yet listed in NOTICE.txt), you must mention it here,
  so we can determine whether the license is compatible and what else needs
  to be done.

[BillyONeal]

I am specifically interested in more perf tests folks think I should run.

[BillyONeal]

The SHOUTY banners were attached to functions which were implmentation details

s/implmentation/implementation/

Fixed, feel free to just edit stuff like that :P

[CaseyCarter]

Fixed, feel free to just edit stuff like that :P

I started to, but was concerned you might have a dual internal PR that needs to be corrected also.

[BillyONeal]

Fixed, feel free to just edit stuff like that :P

I started to, but was concerned you might have a dual internal PR that needs to be corrected also.

There are no test changes needed for this so I'm going to let it be approved here before making a dual one

[miscco]

If I had sufficient coffee this time this is the main difference between the two if constexpr branches.

I you would store the pointer after _LBucket_hi you could also write

    ++_First1;
    const bool _Left_range_end =  
        _First1 == _LBucket_hi_next || _Traitsobj(_Keyval, _Traits::_Kfn(*_First1));

With that the only difference between the two loops (besides comments) is _LBucket_hi_next vs _Unchecked_end(). Given that you use a temporary variable anyway you could assign _Unchecked_end() to _LBucket_hi_next in the _Traits::_Standard case

Dunno if that is truly worth it

[BillyONeal]

That will do one extra pointer dereference per bucket (to find _LBucket_hi_next); but maybe we don't care about the perf of !_Standard (that is, hash_foo rather than unordered_foo) ...

[BillyONeal]

Looks good, applied.

[CaseyCarter]

My non-resolved comments are suggestions, so I "Approve with suggestions."

[BillyONeal]

My non-resolved comments are suggestions, so I "Approve with suggestions."

Is there anything I missed other than the !_Pred thing?

[CaseyCarter]

Is there anything I missed other than the !_Pred thing?

No - I think I was confused by clicking the through the comments and observing old state which I thought was current state.

[StephanTLavavej]

FYI, #279 tracks a possible improvement to is_permutation, although it isn't necessary to implement at this time.

[BillyONeal]

I do agree that looks interesting but would prefer that be a separate change (as it'll need its own perf tests and similar justification)

[StephanTLavavej]

I am mildly uncomfortable with the lack of DMIs here; return {} initializes this bool to false but the risk of garbage-init is higher than I would like. Would it be better to add DMIs for {false} and {} for the iterator?

[BillyONeal]

In my tests all the functions returning this type were inlined so I have no objection to DMIs.

[StephanTLavavej]

This comment grammar is difficult to parse.

[StephanTLavavej]

Can _Result be const?

[StephanTLavavej]

Style: I recommend saying "second" and "first" instead of aggressively abbreviating.

[BillyONeal]

I agree, though technically I didn't edit that here :P. Will fix!

[StephanTLavavej]

This comment is only true if we return true, although I suppose it is fairly obvious.