Add custom comparators

[matthew-mcallister]

Closes #1180.

The diff is large due to having to add a type parameter C and update constraints in numerous places, but the logic changes are not large.

This trait adds the Comparator and Equivalator traits, which generalize the Comparable and Equivalent traits by taking a self parameter in addition to the two keys to compare, making it possible to change the comparison function used without changing the key type.

Summary

• Adds trait Comparator<L, R> and trait Equivalator<L, R>.
• Adds struct OrdComparator, which is a zero-sized type that implements Comparator using Borrow and Ord.
• Adds a type parameter C to SkipList, SkipMap, and SkipSet.
  • C is defaulted to OrdComparator. This preserves the existing behavior of functions like get(), insert(), etc.
• Adds SkipList::with_comparator(), SkipSet::with_comparator(), and SkipMap::with_comparator() constructors.
  • SkipList::new(), SkipMap::new(), and SkipSet::new() always use C = OrdComparator. It would be nice if it worked for any C that implements Default, but that would break type inference. This is exactly the reason std::collections::HashMap::new() always uses S = RandomState for its defaulted parameter even if S implements Default.
• Adds a test using a wrapper around Box<dyn Fn(&[u8], &[u8]) -> Ordering> as the comparator.

Hashing

Because the goal of these traits is to support totally different comparison operations from the default for the underlying key type, Equivalator explicitly does not require two equivalent keys to have the same hash. If someone, someday wants to support Equivalator on their hash map, they will have to generalize the Hash trait as well.

Safety

My one minor question is whether unsafe impl<Q, R, K, V, C> Send for RefRange<'_, Q, R, K, V, C> should require C: Sync. I don't think so because it doesn't require K or V to be sync, but it was enough to make me second-guess myself.

[taiki-e]

This seems like an unfortunate increase in complexity for users who want to make stateless comparisons.

[matthew-mcallister]

It's about a dozen lines of new boilerplate. Regardless, it would be very easy to support Equivalent/Comparable on the default comparator. Rename OrdComparator to BasicComparator and define it like this:

struct BasicComparator;

impl<K: ?Sized, Q: ?Sized> Equivalator<K, Q> for BasicComparator
where
    K: Equivalent<Q>,
{
    #[inline]
    fn equivalent(&self, lhs: &K, rhs: &Q) -> bool {
        <K as Equivalent<Q>>::equivalent(lhs, rhs)
    }
}

impl<K: ?Sized, Q: ?Sized> Comparator<K, Q> for BasicComparator
where
    K: Comparable<Q>,
{
    #[inline]
    fn compare(&self, lhs: &K, rhs: &Q) -> Ordering {
        <K as Comparable<Q>>::compare(lhs, rhs)
    }
}

In some sense this is the best of both worlds. The only downside would be that there are now two sets of traits (Equivalent/Comparable, Equivalator/Comparator), which might be mildly confusing at first sight.

[al8n]

IMO, two sets of traits are reasonable. Actually, it is just one set of traits for stateless comparison, because, for stateless comparison, users just use the BasicComparator (the default one) and only need to implement Equivalent and Comparable. They do not need to care about Equivalentor and Comparator.

[taiki-e]

cc @al8n