Add Iterator comparison methods that take a comparison function by timvermeulen · Pull Request #62205 · rust-lang/rust (original) (raw)

This PR adds Iterator::{cmp_by, partial_cmp_by, eq_by, ne_by, lt_by, le_by, gt_by, ge_by}. We already have Iterator::{cmp, partial_cmp, ...} which are less general (but not any simpler) than the ones I'm proposing here.

I'm submitting this PR now because #61505 has been merged, so this change should not have a noticeable effect on the Iterator docs page size.

The diff is quite messy, here's what I changed:

• The logic of cmp / partial_cmp / eq is moved to cmp_by / partial_cmp_by / eq_by respectively, changing x.cmp(&y) to cmp(&x, &y) in the cmp method where cmp is the given comparison function (and similar for partial_cmp_by and eq_by).
• ne_by / lt_by / le_by / gt_by / ge_by are each implemented in terms of one of the three methods above.
• The existing comparison methods are each forwarded to their _by counterpart, passing one of Ord::cmp / PartialOrd::partial_cmp / PartialEq::eq as the comparison function.

The corresponding _by_key methods aren't included because they're not as fundamental as the _by methods and can easily be implemented in terms of them. Is that reasonable, or would adding the _by_key methods be desirable for the sake of completeness?

I didn't add any tests – I couldn't think of any that weren't already covered by our existing tests. Let me know if there's a particular test that would be useful to add.