1use crate::fmt;
2
3/// Creates a new iterator where each iteration calls the provided closure
4/// `F: FnMut() -> Option<T>`.
5///
6/// This allows creating a custom iterator with any behavior
7/// without using the more verbose syntax of creating a dedicated type
8/// and implementing the [`Iterator`] trait for it.
9///
10/// Note that the `FromFn` iterator doesn’t make assumptions about the behavior of the closure,
11/// and therefore conservatively does not implement [`FusedIterator`],
12/// or override [`Iterator::size_hint()`] from its default `(0, None)`.
13///
14/// The closure can use captures and its environment to track state across iterations. Depending on
15/// how the iterator is used, this may require specifying the [`move`] keyword on the closure.
16///
17/// [`move`]: ../../std/keyword.move.html
18/// [`FusedIterator`]: crate::iter::FusedIterator
19///
20/// # Examples
21///
22/// Let’s re-implement the counter iterator from [module-level documentation]:
23///
24/// [module-level documentation]: crate::iter
25///
26/// ```
27/// let mut count = 0;
28/// let counter = std::iter::from_fn(move || {
29/// // Increment our count. This is why we started at zero.
30/// count += 1;
31///
32/// // Check to see if we've finished counting or not.
33/// if count < 6 {
34/// Some(count)
35/// } else {
36/// None
37/// }
38/// });
39/// assert_eq!(counter.collect::<Vec<_>>(), &[1, 2, 3, 4, 5]);
40/// ```
41#[inline]
42#[stable(feature = "iter_from_fn", since = "1.34.0")]
43pub fn from_fn<T, F>(f: F) -> FromFn<F>
44where
45 F: FnMut() -> Option<T>,
46{
47 FromFn(f)
48}
49
50/// An iterator where each iteration calls the provided closure `F: FnMut() -> Option<T>`.
51///
52/// This `struct` is created by the [`iter::from_fn()`] function.
53/// See its documentation for more.
54///
55/// [`iter::from_fn()`]: from_fn
56#[derive(Clone)]
57#[stable(feature = "iter_from_fn", since = "1.34.0")]
58pub struct FromFn<F>(F);
59
60#[stable(feature = "iter_from_fn", since = "1.34.0")]
61impl<T, F> Iterator for FromFn<F>
62where
63 F: FnMut() -> Option<T>,
64{
65 type Item = T;
66
67 #[inline]
68 fn next(&mut self) -> Option<Self::Item> {
69 (self.0)()
70 }
71}
72
73#[stable(feature = "iter_from_fn", since = "1.34.0")]
74impl<F> fmt::Debug for FromFn<F> {
75 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
76 f.debug_struct(name:"FromFn").finish()
77 }
78}
79