drain_filter for all collections

For all collections, provide a method drain_filter. For some discussion of the method name and signature, see https://github.com/rust-lang/rust/issues/43244, especially this comment.

Status

Implemented, awaiting stabilization

• Vec, LinkedList: https://github.com/rust-lang/rust/issues/43244
• BTreeMap, BTreeSet: https://github.com/rust-lang/rust/issues/70530
• HashMap, HashSet: https://github.com/rust-lang/rust/issues/59618

Unimplemented

• BinaryHeap: https://github.com/rust-lang/rust/issues/42849
• VecDeque
• String

Description

This method mutably borrows the collection and takes a predicate on the elements of the collection (e.g. values for lists and key-value pairs for maps). It then creates an iterator over the elements of the collection where the predicate returned truthfully and accessing that element in the iterator removes it from the collection. For ordered collections, it should return them in order.

Example usage

let v = vec![1, 2, 3, 4, 5, 6, 7, 8];
let primes = v.drain_filter(|n| n.is_prime()).collect::Vec<_>();
assert!(v == vec![1, 4, 6, 8]);
assert!(primes == vec![2, 3, 5, 7]);

Related ideas

Also of use would be a method that finds and removes the first element matching a predicate, as it would not have to do things like pre-poop its pants in case the Drain Where iterator leaks nor would it have to traverse the entire collection if e.g. the first element checked matches the predicate.

Start with the linked Rust issues for the proposed signature and the collection-specific status: Vec and LinkedList, BTreeMap and BTreeSet, HashMap and HashSet, BinaryHeap, VecDeque, and String. Done means determining and implementing the drain_filter API across the listed collections, including predicate-based removal and ordered iteration where applicable.