From 1fb43f66624554d3fd63afc8e141386cbd6d414b Mon Sep 17 00:00:00 2001 From: Andre Bogus Date: Sun, 16 Jan 2022 01:33:19 +0100 Subject: [PATCH] add perf side effect docs to `Iterator::cloned()` --- library/core/src/iter/traits/iterator.rs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs index b62e8dfe1d6..53fbe4cbc42 100644 --- a/library/core/src/iter/traits/iterator.rs +++ b/library/core/src/iter/traits/iterator.rs @@ -3189,6 +3189,10 @@ fn copied<'a, T: 'a>(self) -> Copied /// This is useful when you have an iterator over `&T`, but you need an /// iterator over `T`. /// + /// There is no guarantee whatsoever about the `clone` method actually + /// being called *or* optimized away. So code should not depend on + /// either. + /// /// [`clone`]: Clone::clone /// /// # Examples @@ -3206,6 +3210,18 @@ fn copied<'a, T: 'a>(self) -> Copied /// assert_eq!(v_cloned, vec![1, 2, 3]); /// assert_eq!(v_map, vec![1, 2, 3]); /// ``` + /// + /// To get the best performance, try to clone late: + /// + /// ``` + /// let a = [vec![0_u8, 1, 2], vec![3, 4], vec![23]]; + /// // don't do this: + /// let slower: Vec<_> = a.iter().cloned().filter(|s| s.len() == 1).collect(); + /// assert_eq!(&[vec![23]], &slower[..]); + /// // instead call `cloned` late + /// let faster: Vec<_> = a.iter().filter(|s| s.len() == 1).cloned().collect(); + /// assert_eq!(&[vec![23]], &faster[..]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn cloned<'a, T: 'a>(self) -> Cloned where