From d4a60ab34f4f612365e353fafdfb4e28f1484e47 Mon Sep 17 00:00:00 2001
From: Josh Stone <jistone@redhat.com>
Date: Wed, 28 Jul 2021 16:35:59 -0700
Subject: [PATCH] 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 | 7 ++++---
 library/alloc/src/string.rs                    | 7 ++++---
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/library/alloc/src/collections/vec_deque/mod.rs b/library/alloc/src/collections/vec_deque/mod.rs
index 386c7c2612d57..3cf6c56f43a57 100644
--- a/library/alloc/src/collections/vec_deque/mod.rs
+++ b/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")]
diff --git a/library/alloc/src/string.rs b/library/alloc/src/string.rs
index 0d8678291bef7..6a02de7f9a24f 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]