add filter functionality

[cavemanloverboy]

This provides a drain_filter and filter functionality on the red black tree implementation.

Inspiration: in phoenix-v1's CancelAllOrders instruction, the tree is traversed and matching ids are collected. These ids are then used via book.remove(...) which traverses the tree to remove the entry. Instead of traversing the tree, this implementation records allocator node addresses and removes them all upon dropping the new RedBlackTreeDrainFilter type.

A quick and dirty benchmark of 128 removals from a full tree of 4096 items yields the following results on an M2 Max:

./target/release/examples/bench_filter
average id + remove: 59280 micros
average drain_alloc: 44410 micros
average drain: 43759 micros

which is an O(30%) reduction in the wall time of the removals.

[jarry-xiao]

The gist of the speed up here is that the traversal traversal to remove nodes is O(K) instead of O(K log N) right?

[jarry-xiao]

Actually still O(K log N) but you save a log N on the find

[cavemanloverboy]

Essentially, with remove you have to traverse the tree from the root to the entry to re-find the node addr of the entry you just found.

If you iterate through the elements and record the addr instead of the keys, you don't have to do that traversal to remove the entry. That's the gist

[jarry-xiao]

is there not a helper function to perform this lookup?

[cavemanloverboy]

This part was mostly copied from the iterator implementation, but perhaps

[cavemanloverboy]

switched to get_node. much neater

[jarry-xiao]

Clever change! Please bump the version in the Cargo.toml

[cavemanloverboy]

Clever change! Please bump the version in the Cargo.toml

Will do. Also, it's come to my attention that the drain_filter method for std::vec::Vec that this was supposed to be analogous to has been renamed to extract_if:

rust-lang/rust#43244

I'll try to come up with some better names for the methods.

[cavemanloverboy]

1. I switched to extract_if to match the method on std collections (btreemap, vec, etc, e.g. https://doc.rust-lang.org/nightly/std/vec/struct.Vec.html#method.extract_if).
2. I added a docstring w/ test on the method w/ some notes.
3. I removed the filter method since you can just do extract_if and collect into collection of your choice -- instead of locking user into Vec.
4. Bumped to 0.4.0

[cavemanloverboy]

One final thing we may want to do is either implement DoubleEndedIterator or remove the rev fields from the ExtractIf type