Document the order of {Vec,VecDeque,String}::retain

It's natural for `retain` to work in order from beginning to end, but
this wasn't actually documented to be the case. If we actually promise
this, then the caller can do useful things like track the index of each
element being tested, as [discussed in the forum][1]. This is now
documented for `Vec`, `VecDeque`, and `String`.

[1]: https://users.rust-lang.org/t/vec-retain-by-index/27697

`HashMap` and `HashSet` also have `retain`, and the `hashbrown`
implementation does happen to use a plain `iter()` order too, but it's
not certain that this should always be the case for these types.

0 files changed, 0 insertions, 0 deletions