library/core/src/iter/adapters/scan.rs

   1 use crate::fmt;
   2 use crate::iter::{adapters::SourceIter, InPlaceIterable};
   3 use crate::ops::{ControlFlow, Try};
   4
   5 /// An iterator to maintain state while iterating another iterator.
   6 ///
   7 /// This `struct` is created by the [`scan`] method on [`Iterator`]. See its
   8 /// documentation for more.
   9 ///
  10 /// [`scan`]: Iterator::scan
  11 /// [`Iterator`]: trait.Iterator.html
  12 #[must_use = "iterators are lazy and do nothing unless consumed"]
  13 #[stable(feature = "rust1", since = "1.0.0")]
  14 #[derive(Clone)]
  15 pub struct Scan<I, St, F> {
  16     iter: I,
  17     f: F,
  18     state: St,
  19 }
  20
  21 impl<I, St, F> Scan<I, St, F> {
  22     pub(in crate::iter) fn new(iter: I, state: St, f: F) -> Scan<I, St, F> {
  23         Scan { iter, state, f }
  24     }
  25 }
  26
  27 #[stable(feature = "core_impl_debug", since = "1.9.0")]
  28 impl<I: fmt::Debug, St: fmt::Debug, F> fmt::Debug for Scan<I, St, F> {
  29     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  30         f.debug_struct("Scan").field("iter", &self.iter).field("state", &self.state).finish()
  31     }
  32 }
  33
  34 #[stable(feature = "rust1", since = "1.0.0")]
  35 impl<B, I, St, F> Iterator for Scan<I, St, F>
  36 where
  37     I: Iterator,
  38     F: FnMut(&mut St, I::Item) -> Option<B>,
  39 {
  40     type Item = B;
  41
  42     #[inline]
  43     fn next(&mut self) -> Option<B> {
  44         let a = self.iter.next()?;
  45         (self.f)(&mut self.state, a)
  46     }
  47
  48     #[inline]
  49     fn size_hint(&self) -> (usize, Option<usize>) {
  50         let (_, upper) = self.iter.size_hint();
  51         (0, upper) // can't know a lower bound, due to the scan function
  52     }
  53
  54     #[inline]
  55     fn try_fold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R
  56     where
  57         Self: Sized,
  58         Fold: FnMut(Acc, Self::Item) -> R,
  59         R: Try<Output = Acc>,
  60     {
  61         fn scan<'a, T, St, B, Acc, R: Try<Output = Acc>>(
  62             state: &'a mut St,
  63             f: &'a mut impl FnMut(&mut St, T) -> Option<B>,
  64             mut fold: impl FnMut(Acc, B) -> R + 'a,
  65         ) -> impl FnMut(Acc, T) -> ControlFlow<R, Acc> + 'a {
  66             move |acc, x| match f(state, x) {
  67                 None => ControlFlow::Break(try { acc }),
  68                 Some(x) => ControlFlow::from_try(fold(acc, x)),
  69             }
  70         }
  71
  72         let state = &mut self.state;
  73         let f = &mut self.f;
  74         self.iter.try_fold(init, scan(state, f, fold)).into_try()
  75     }
  76
  77     impl_fold_via_try_fold! { fold -> try_fold }
  78 }
  79
  80 #[unstable(issue = "none", feature = "inplace_iteration")]
  81 unsafe impl<St, F, I> SourceIter for Scan<I, St, F>
  82 where
  83     I: SourceIter,
  84 {
  85     type Source = I::Source;
  86
  87     #[inline]
  88     unsafe fn as_inner(&mut self) -> &mut I::Source {
  89         // SAFETY: unsafe function forwarding to unsafe function with the same requirements
  90         unsafe { SourceIter::as_inner(&mut self.iter) }
  91     }
  92 }
  93
  94 #[unstable(issue = "none", feature = "inplace_iteration")]
  95 unsafe impl<St, F, B, I: InPlaceIterable> InPlaceIterable for Scan<I, St, F> where
  96     F: FnMut(&mut St, I::Item) -> Option<B>
  97 {
  98 }