Clarify Vec's documentation about buffer reuse

[comex]

The documentation for Vec states:

Do not rely on removed data to be erased for security purposes. Even if you drop a Vec, its buffer may simply be reused by another Vec.

Here, "its buffer may simply be reused" is simply meant to refer to the behavior of the underlying allocator. But I have seen people with low-level experience be misled by this into thinking that the implementation of Vec itself has its own global allocation cache. They then thought this cache was responsible for excess memory usage in their programs.

I'm not sure what the best way to clarify this would be. Part of the reason the current wording can be misleading is that "reused by another Vec" suggests a mechanism specific to Vec. On the other hand, it would also help to just explicitly mention the allocator. Here is a possible version that addresses both points, but it's more wordy than the current version:

Even if you drop a Vec, the allocator may reuse its buffer for another Vec or other allocation.

[SkiFire13]

I guess this also includes in-place iteration?

[the8472]

In-place iteration is a fancy case of type-conversion. Simpler examples are conversions to IntoIter, VecDeque and BinaryHeap which also keep the allocation.

[jyn514]

Do not rely on removed data to be erased for security purposes. Even if you drop a Vec, its buffer may simply be reused by another Vec.

Maybe it would be more clear to say "may be reused by another allocation"? That doesn't imply it has to be a Vec that reuses the memory.

[inquisitivecrystal]

@rustbot label +A-collections +C-enhancement +T-libs

[chrismit3s]

@rustbot claim