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

library/alloc/src/collections/vec_deque/mod.rs

@@ -2107,7 +2107,8 @@ impl<T, A: Allocator> VecDeque<T, A> {
     /// assert_eq!(buf, [2, 4]);
     /// ```
     ///
-    /// 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.
     ///
     /// ```
     /// use std::collections::VecDeque;
@@ -2116,8 +2117,8 @@ impl<T, A: Allocator> VecDeque<T, A> {
     /// buf.extend(1..6);
     ///
     /// let keep = [false, true, true, false, true];
-    /// let mut i = 0;
-    /// buf.retain(|_| (keep[i], i += 1).0);
+    /// let mut iter = keep.iter();
+    /// buf.retain(|_| *iter.next().unwrap());
     /// assert_eq!(buf, [2, 3, 5]);
     /// ```
     #[stable(feature = "vec_deque_retain", since = "1.4.0")]

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]