Tracking Issue for {BTreeMap,BTreeSet}::drain

[ssomers]

This is a tracking issue for a range-based drain method on BTreeMap and BTreeSet, similar to the one in Vec.
The feature gate for the issue is #![feature(btree_drain)].

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Steps

• Implement the main method
• Adjust documentation (see instructions on rustc-dev-guide)
• Stabilization PR (see instructions on rustc-dev-guide)

Unresolved Questions

• Is plain drain the right name for a range-based function? It's equivalent to Vec::drain if you consider a Vec<T> to be a BTreeMap<usize, T> with consecutive keys. It's not equivalent to the HashMap::drain() without argument, and BTreeMap::drain(..) doesn't compile without a type annotation if the key type has additional Borrow implementations, whereas Vec::drain(..) is always a simple way to drain everything.
• An efficient implementation of draining implies most of the drained key-value pairs are in entirely preserved (and not even visited) subtrees. Therefore, the return value can be relatively easily adapted to obtain a range-based method much like split_off. Is it OK to add split_off_range along the way?

Implementation history

• First real shot: BTree: add drain methods #81075
• Early attempt at argumentless drain: BTreeMap/BTreeSet drain & retain #66747

[ssomers]

@rustbot modify labels: +S-A-collections +S-B-unstable +S-C-tracking-issue +S-Libs-Tracked +S-T-libs

[JohnTitor]

@ssomers The implementation PR has been closed, do you want to follow up or could we close this tracking issue for now?