add binary_search and friends

[Eh2406]

This is a start on fixing #281.

I copied the implementation of these methods from std, except for binary_search_by where I used std directly. Alternatively we could have all implementations directly forward to .as_slice().foobar or .entries.foobar, if you would prefer that.

I left off the plane binary_search{_keys} on set and map, because they already provide a O(1) way to look up the index for a key. I left them in on Slice because they do not.

For documentation I adapted the first sentence of std, and provided a link to std.

how would you like to see these tested?

[cuviper]

Alternatively we could have all implementations directly forward to .as_slice().foobar or .entries.foobar, if you would prefer that.

I would, yeah, at least for partition_point since that's less trivial. The rest can go either way.

I left off the plane binary_search{_keys} on set and map, because they already provide a O(1) way to look up the index for a key. I left them in on Slice because they do not.

That's an interesting point! I wonder if small enough maps/sets might still win by binary search, but if you're too small then even a linear search might be fastest. But anyway, if someone really wants it they can use binary_search_by the same way our impl would, and we could choose to add it later.

how would you like to see these tested?

We haven't been great about that, but let's at least add sanity checks to map/tests.rs and set/tests.rs. But we don't need to be very thorough when it's relying directly on the standard library, and then type checking already proves the remaining differences.

[Eh2406]

I will work on it. I have PackagingCon for then next few days a may not have much time.

[Eh2406]

If I had been more awake you would have gone shorter tests. :-P I was not up to determining interesting test cases. So instead you got tests from STD copied in and adapted. They may be more thorough than you asked for.

[cuviper]

Same vibe as "If I had more time, I would have written a shorter letter." :)

It's a lot, but that's fine.

[cuviper]

Thanks - the implementation looks good, just need some cleanup in the docs and a few comments.

[cuviper]

I left off the plane binary_search{_keys} on set and map, because they already provide a O(1) way to look up the index for a key. I left them in on Slice because they do not.

That's an interesting point! I wonder if small enough maps/sets might still win by binary search, but if you're too small then even a linear search might be fastest. But anyway, if someone really wants it they can use binary_search_by the same way our impl would, and we could choose to add it later.

Actually, there's still a gap there because binary search also finds the insertion point for missing items. So I think it's good to have the doc comment about scalability, but we should still want the map/set methods for the Err case.

I'll go ahead and add this myself while I'm thinking about it...

[cuviper]

Thanks again! I'll put together a release soon.

[cuviper]

FYI, I did publish this as 2.1.0 the other day.

I'd be interested to see where you use this, if that code is open.

[Eh2406]

It is for https://github.com/pubgrub-rs/pubgrub, although the particular performance experiments where this would be useful have not yet pulled their weight. Many data structures have to "backtrack" to reset their state as of some previous point in time. For each individual data structure there are many ways this can be achieved.

• The data structure can be "cleared" and reconstructed from other data sources.
• Items in the data structure can include a "timestamp" and then the reset is .retain(|_, v| v.timestamp < reset_to_timestamp)
• The data structure can be maintained in an ordered fashion and reset by truncating newer modifications. If you need to scan the entire data structure to decide where to cut, then this is the same as the previous. You can have an auxiliary data structure recording timestamp -> cutpoint, for O(1) time reset but additional allocations. Using partition point to make a cut, gives O(ln(size)) reset with no additional space. Which sure seems tempting.

The particular example of this pattern that inspired the PR was contradicted_incompatibilities, which currently uses the first strategy but could easily use the last one. I will definitely drop you a link when/if progress toward using this PR is achieved.