Tracking Issue for `{BTreeMap, BTreeSet}::drain` with a range

[frank-king]

Feature gate: #![feature(btree_drain_range)]

This is a tracking issue for the implementation of a drain method with a range on BTreeMap and BTreeSet, which removes a range from the collection.

Public API

pub mod alloc {
    pub mod collections {
        pub mod btree_map {
            impl<K, V> BTreeMap<K, V> {
                pub fn drain<T: ?Sized, R>(&mut self, range: R) -> DrainRange<'_, K, V>
                where 
                    T: Ord,
                    K: Borrow<T> + Ord,
                    R: RangeBounds<T>,
                { }
            }

            pub struct DrainRange<'a, K: 'a, V: 'a> {}

            impl<K, V> Iterator for DrainRange<'_, K, V> {
                type Item = (K, V);
                fn next(&mut self) -> Option<(K, V)> {}
                fn min(self) -> Option<(K, V)> {}
                fn max(self) -> Option<(K, V)> {}
            }

            impl<K, V> FuseIterator for DrainRange<'_, K, V> {}

            impl<K, V> DoubleEndedIterator for DrainRange<'_, K, V> {
                fn next_back(&mut self) -> Option<(K, V)> {}
            }

            impl<K, V> Drop for DrainRange<'_, K, V> {
                fn drop(&mut self) {}
            }

            impl<K, V> Debug for DrainRange<'_, K, V> {
                fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {}
            }
        }

        pub mod btree_set {
            impl<T> BTreeSet<T> {
                pub fn drain<K: ?Sized, R>(&mut self, range: R) -> DrainRange<'_, T>
                where 
                    K: Ord,
                    T: Borrow<K> + Ord,
                    R: RangeBounds<K>,
                { }
            }

            pub struct DrainRange<'a, T: 'a> {}

            impl<T> Iterator for DrainRange<'_, T> {
                type Item = T;
                fn next(&mut self) -> Option<T> {}
                fn min(self) -> Option<T> {}
                fn max(self) -> Option<T> {}
            }

            impl<T> FuseIterator for DrainRange<'_, T> {}

            impl<T> DoubleEndedIterator for DrainRange<'_, T> {
                fn next_back(&mut self) -> Option<T> {}
            }

            impl<T> Drop for DrainRange<'_, T> {
                fn drop(&mut self) {}
            }

            impl<T> Debug for DrainRange<'_, T> {
                fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {}
            }
        }
    }
}

Steps / History

• Implementation: WIP
• Final comment period (FCP)
• Stabilization PR

Unresolved Questions

• Should the method be named drain_range?

[frank-king]

Close in favor of #81075.