Vec::drain() doesn't document any guarantees on order

[EriKWDev]

Location

rustlib/src/rust/library/alloc/src/vec/mod.rs on pub fn drain<R>(&mut self, range: R) -> Drain<'_, T, A>, line 2603 in stable 1.84.0 (9fc6b4312 2025-01-07)

Summary

/// Removes the specified range from the vector in bulk, returning all
/// removed elements as an iterator. If the iterator is dropped before
/// being fully consumed, it drops the remaining removed elements.

"returning all removed elements as an iterator" remains ambiguous on the order of the elements.

I assume drain will continue to yield the items in the range order so could this be a documented guarantee?

[hkBst]

I was wondering what the documented guarantees for slice iterators were:
"""
Returns an iterator over the slice.

The iterator yields all items from start to end.
"""

so if we document that the iteration is over a slice then we get the ordering guarantees for free.