Rollup merge of #87574 - cuviper:retain-examples, r=joshtriplett

Update the examples in `String` and `VecDeque::retain`

The examples added in #60396 used a "clever" post-increment hack,
unrelated to the actual point of the examples. That hack was found
[confusing] in the users forum, and #81811 already changed the `Vec`
example to use a more direct iterator. This commit changes `String` and
`VecDeque` in the same way for consistency.

[confusing]: https://users.rust-lang.org/t/help-understand-strange-expression/62858

1 files changed, 4 insertions, 3 deletions

diff --git a/library/alloc/src/string.rs b/library/alloc/src/string.rs
index bc5ab3637ae..5411316f55a 100644
--- a/library/alloc/src/string.rs
+++ b/library/alloc/src/string.rs
@@ -1350,13 +1350,14 @@ impl String {
     /// assert_eq!(s, "foobar");
     /// ```
     ///
-    /// The exact order may be useful for tracking external state, like an index.
+    /// Because the elements are visited exactly once in the original order,
+    /// external state may be used to decide which elements to keep.
     ///
     /// ```
     /// let mut s = String::from("abcde");
     /// let keep = [false, true, true, false, true];
-    /// let mut i = 0;
-    /// s.retain(|_| (keep[i], i += 1).0);
+    /// let mut iter = keep.iter();
+    /// s.retain(|_| *iter.next().unwrap());
     /// assert_eq!(s, "bce");
     /// ```
     #[inline]