drain() doc of vector is unclear

[Stargateur]

I wanted to move out a number of front element from a vector, like my_vec.drain(..x) but I wonder if this is the right way to do this cause doc is unclear, note 1 and note 2 say the opposite each other:

Creates a draining iterator that removes the specified range in the vector and yields the removed items.

Note 1: The element range is removed even if the iterator is only partially consumed or not consumed at all.

Note 2: It is unspecified how many elements are removed from the vector if the Drain value is leaked.

https://doc.rust-lang.org/std/vec/struct.Vec.html#method.drain

This issue has been assigned to @poliorcetics via this comment.

[jonas-schievink]

"partially consumed" means taking a few elements out and then dropping the Drain value. Note 2 talks specifically about leaking the Drain value.

Is there any way to make this more clear in the docs?

[Stargateur]

What leaked mean for you ? How would I leak drain struct ? Drop it ?

[jonas-schievink]

No, leaking means specifically destroying a value without running its destructor, for example via mem::forget

[Stargateur]

So I think write:

The element range is removed even if the iterator is only partially consumed or not consumed at all.

Note: Be aware that If you leak the iterator (eg: mem::forget), It's cancel this property so it is unspecified how many elements are removed from the vector in this case.

Because in the current form the two note look like they apply both whereas it's two difference case, leaked or not. (I'm not sure leak is the good word here for me leak mean leak memory not forget it, so maybe say "without run it's destructor" is more clear)

[yvt]

I myself am familiar with this usage of "to leak", but I don't know how I picked up that, why this is called leaking, or where it's explained in the docs. I suspect that this usage originates from smart pointers, for which destroying them without running destructors would leak the referenced objects. If we generalize this to something that is not a smart pointer, it's called jargon. Although it's convenient to use (in fact, there are more than ten instances of this usage in the standard library), it's not something we can expect to be understood for sure.

For this reason, I agree with @Stargateur. Replacing the word with something like “destroyed without running its destructor” or at least adding a reference to std::mem::forget in parentheses would make sense.

[poliorcetics]

@rustbot claim