diff options
| author | Josh Stone <jistone@redhat.com> | 2019-04-29 18:32:05 -0700 |
|---|---|---|
| committer | Josh Stone <jistone@redhat.com> | 2019-04-29 18:32:05 -0700 |
| commit | 9b3583375dbd45b19b8ce8822b89ff79529354d6 (patch) | |
| tree | 137494b5e5c41e94a3e33f9fe09bada8cb07541c /src/liballoc | |
| parent | 00859e3e653973120006aaf3227823062dde1ba7 (diff) | |
| download | rust-9b3583375dbd45b19b8ce8822b89ff79529354d6.tar.gz rust-9b3583375dbd45b19b8ce8822b89ff79529354d6.zip | |
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.
Diffstat (limited to 'src/liballoc')
| -rw-r--r-- | src/liballoc/collections/vec_deque.rs | 4 | ||||
| -rw-r--r-- | src/liballoc/string.rs | 4 | ||||
| -rw-r--r-- | src/liballoc/vec.rs | 4 |
3 files changed, 6 insertions, 6 deletions
diff --git a/src/liballoc/collections/vec_deque.rs b/src/liballoc/collections/vec_deque.rs index d65c24f7350..82a60f92444 100644 --- a/src/liballoc/collections/vec_deque.rs +++ b/src/liballoc/collections/vec_deque.rs @@ -1835,8 +1835,8 @@ impl<T> VecDeque<T> { /// Retains only the elements specified by the predicate. /// /// In other words, remove all elements `e` such that `f(&e)` returns false. - /// This method operates in place and preserves the order of the retained - /// elements. + /// This method operates in place, visiting each element exactly once in the + /// original order, and preserves the order of the retained elements. /// /// # Examples /// diff --git a/src/liballoc/string.rs b/src/liballoc/string.rs index a3e2098695f..aaa38142693 100644 --- a/src/liballoc/string.rs +++ b/src/liballoc/string.rs @@ -1200,8 +1200,8 @@ impl String { /// Retains only the characters specified by the predicate. /// /// In other words, remove all characters `c` such that `f(c)` returns `false`. - /// This method operates in place and preserves the order of the retained - /// characters. + /// This method operates in place, visiting each character exactly once in the + /// original order, and preserves the order of the retained characters. /// /// # Examples /// diff --git a/src/liballoc/vec.rs b/src/liballoc/vec.rs index cd62c3e0524..a9bc835010f 100644 --- a/src/liballoc/vec.rs +++ b/src/liballoc/vec.rs @@ -937,8 +937,8 @@ impl<T> Vec<T> { /// Retains only the elements specified by the predicate. /// /// In other words, remove all elements `e` such that `f(&e)` returns `false`. - /// This method operates in place and preserves the order of the retained - /// elements. + /// This method operates in place, visiting each element exactly once in the + /// original order, and preserves the order of the retained elements. /// /// # Examples /// |