From 2d5d6fbca49c29287c29aa8194be79db6b7de89f Mon Sep 17 00:00:00 2001
From: Tshepang Lekhonkhobe <tshepang@gmail.com>
Date: Sun, 24 May 2015 23:38:26 +0200
Subject: [PATCH] doc: add example for Iterator::cloned()

---
 src/libcore/iter.rs | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs
index ed7cdbbb6e2..5042d44b288 100644
--- a/src/libcore/iter.rs
+++ b/src/libcore/iter.rs
@@ -1009,8 +1009,19 @@ pub trait Iterator {
         (ts, us)
     }
 
-    /// Creates an iterator that clones the elements it yields. Useful for
-    /// converting an Iterator<&T> to an Iterator<T>.
+    /// Creates an iterator that clones the elements it yields.
+    ///
+    /// This is useful for converting an Iterator<&T> to an Iterator<T>,
+    /// so it's a more convenient form of `map(|&x| x)`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let a = [0, 1, 2];
+    /// let v_cloned: Vec<_> = a.iter().cloned().collect();
+    /// let v_map: Vec<_> = a.iter().map(|&x| x).collect();
+    /// assert_eq!(v_cloned, v_map);
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     fn cloned<'a, T: 'a>(self) -> Cloned<Self>
         where Self: Sized + Iterator<Item=&'a T>, T: Clone