add examples to `vec::Drain{,Filter}::keep_rest` docs

2 files changed, 37 insertions, 0 deletions

diff --git a/library/alloc/src/vec/drain.rs b/library/alloc/src/vec/drain.rs
index 3e350c2b38e..2a3f7ff6d2a 100644
--- a/library/alloc/src/vec/drain.rs
+++ b/library/alloc/src/vec/drain.rs
@@ -67,6 +67,24 @@ impl<'a, T, A: Allocator> Drain<'a, T, A> {
     }
 
     /// Keep unyielded elements in the source `Vec`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(drain_keep_rest)]
+    ///
+    /// let mut vec = vec!['a', 'b', 'c'];
+    /// let mut drain = vec.drain(..);
+    ///
+    /// assert_eq!(drain.next().unwrap(), 'a');
+    ///
+    /// // This call keeps 'b' and 'c' in the vec.
+    /// drain.keep_rest();
+    ///
+    /// // If we wouldn't call `keep_rest()`,
+    /// // `vec` would be empty.
+    /// assert_eq!(vec, ['b', 'c']);
+    /// ```
     #[unstable(feature = "drain_keep_rest", issue = "none")]
     pub fn keep_rest(self) {
         // At this moment layout looks like this:
diff --git a/library/alloc/src/vec/drain_filter.rs b/library/alloc/src/vec/drain_filter.rs
index a5c1eab94ee..3130c1f1cca 100644
--- a/library/alloc/src/vec/drain_filter.rs
+++ b/library/alloc/src/vec/drain_filter.rs
@@ -57,6 +57,25 @@ where
     }
 
     /// Keep unyielded elements in the source `Vec`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(drain_filter)]
+    /// #![feature(drain_keep_rest)]
+    ///
+    /// let mut vec = vec!['a', 'b', 'c'];
+    /// let mut drain = vec.drain_filter(|_| true);
+    ///
+    /// assert_eq!(drain.next().unwrap(), 'a');
+    ///
+    /// // This call keeps 'b' and 'c' in the vec.
+    /// drain.keep_rest();
+    ///
+    /// // If we wouldn't call `keep_rest()`,
+    /// // `vec` would be empty.
+    /// assert_eq!(vec, ['b', 'c']);
+    /// ```
     #[unstable(feature = "drain_keep_rest", issue = "none")]
     pub fn keep_rest(self) {
         // At this moment layout looks like this: