@@ -57,6 +57,12 @@ unsafe impl<A: Clone> TrustedLen for Repeat<A> {}
5757///
5858/// [`take`]: trait.Iterator.html#method.take
5959///
60+ /// If the element type of the iterator you need does not implement `Clone`,
61+ /// or if you do not want to keep the repeated element in memory, you can
62+ /// instead use the [`repeat_with`] function.
63+ ///
64+ /// [`repeat_with`]: fn.repeat_with.html
65+ ///
6066/// # Examples
6167///
6268/// Basic usage:
@@ -99,6 +105,115 @@ pub fn repeat<T: Clone>(elt: T) -> Repeat<T> {
99105 Repeat { element : elt}
100106}
101107
108+ /// An iterator that repeats elements of type `A` endlessly by
109+ /// applying the provided closure `F: FnMut() -> A`.
110+ ///
111+ /// This `struct` is created by the [`repeat_with`] function.
112+ /// See its documentation for more.
113+ ///
114+ /// [`repeat_with`]: fn.repeat_with.html
115+ #[ derive( Copy , Clone , Debug ) ]
116+ #[ unstable( feature = "iterator_repeat_with" , issue = "48169" ) ]
117+ pub struct RepeatWith < F > {
118+ repeater : F
119+ }
120+
121+ #[ unstable( feature = "iterator_repeat_with" , issue = "48169" ) ]
122+ impl < A , F : FnMut ( ) -> A > Iterator for RepeatWith < F > {
123+ type Item = A ;
124+
125+ #[ inline]
126+ fn next ( & mut self ) -> Option < A > { Some ( ( self . repeater ) ( ) ) }
127+
128+ #[ inline]
129+ fn size_hint ( & self ) -> ( usize , Option < usize > ) { ( usize:: MAX , None ) }
130+ }
131+
132+ #[ unstable( feature = "iterator_repeat_with" , issue = "48169" ) ]
133+ impl < A , F : FnMut ( ) -> A > DoubleEndedIterator for RepeatWith < F > {
134+ #[ inline]
135+ fn next_back ( & mut self ) -> Option < A > { self . next ( ) }
136+ }
137+
138+ #[ unstable( feature = "fused" , issue = "35602" ) ]
139+ impl < A , F : FnMut ( ) -> A > FusedIterator for RepeatWith < F > { }
140+
141+ #[ unstable( feature = "trusted_len" , issue = "37572" ) ]
142+ unsafe impl < A , F : FnMut ( ) -> A > TrustedLen for RepeatWith < F > { }
143+
144+ /// Creates a new iterator that repeats elements of type `A` endlessly by
145+ /// applying the provided closure, the repeater, `F: FnMut() -> A`.
146+ ///
147+ /// The `repeat_with()` function calls the repeater over and over and over and
148+ /// over and over and 🔁.
149+ ///
150+ /// Infinite iterators like `repeat_with()` are often used with adapters like
151+ /// [`take`], in order to make them finite.
152+ ///
153+ /// [`take`]: trait.Iterator.html#method.take
154+ ///
155+ /// If the element type of the iterator you need implements `Clone`, and
156+ /// it is OK to keep the source element in memory, you should instead use
157+ /// the [`repeat`] function.
158+ ///
159+ /// [`repeat`]: fn.repeat.html
160+ ///
161+ /// An iterator produced by `repeat_with()` is a `DoubleEndedIterator`.
162+ /// It is important to not that reversing `repeat_with(f)` will produce
163+ /// the exact same sequence as the non-reversed iterator. In other words,
164+ /// `repeat_with(f).rev().collect::<Vec<_>>()` is equivalent to
165+ /// `repeat_with(f).collect::<Vec<_>>()`.
166+ ///
167+ /// # Examples
168+ ///
169+ /// Basic usage:
170+ ///
171+ /// ```
172+ /// #![feature(iterator_repeat_with)]
173+ ///
174+ /// use std::iter;
175+ ///
176+ /// // let's assume we have some value of a type that is not `Clone`
177+ /// // or which don't want to have in memory just yet because it is expensive:
178+ /// #[derive(PartialEq, Debug)]
179+ /// struct Expensive;
180+ ///
181+ /// // a particular value forever:
182+ /// let mut things = iter::repeat_with(|| Expensive);
183+ ///
184+ /// assert_eq!(Some(Expensive), things.next());
185+ /// assert_eq!(Some(Expensive), things.next());
186+ /// assert_eq!(Some(Expensive), things.next());
187+ /// assert_eq!(Some(Expensive), things.next());
188+ /// assert_eq!(Some(Expensive), things.next());
189+ /// ```
190+ ///
191+ /// Using mutation and going finite:
192+ ///
193+ /// ```rust
194+ /// #![feature(iterator_repeat_with)]
195+ ///
196+ /// use std::iter;
197+ ///
198+ /// // From the zeroth to the third power of two:
199+ /// let mut curr = 1;
200+ /// let mut pow2 = iter::repeat_with(|| { let tmp = curr; curr *= 2; tmp })
201+ /// .take(4);
202+ ///
203+ /// assert_eq!(Some(1), pow2.next());
204+ /// assert_eq!(Some(2), pow2.next());
205+ /// assert_eq!(Some(4), pow2.next());
206+ /// assert_eq!(Some(8), pow2.next());
207+ ///
208+ /// // ... and now we're done
209+ /// assert_eq!(None, pow2.next());
210+ /// ```
211+ #[ inline]
212+ #[ unstable( feature = "iterator_repeat_with" , issue = "48169" ) ]
213+ pub fn repeat_with < A , F : FnMut ( ) -> A > ( repeater : F ) -> RepeatWith < F > {
214+ RepeatWith { repeater }
215+ }
216+
102217/// An iterator that yields nothing.
103218///
104219/// This `struct` is created by the [`empty`] function. See its documentation for more.
0 commit comments