src/vendor/itertools/src/rciter_impl.rs

   1
   2 use std::iter::IntoIterator;
   3 use std::rc::Rc;
   4 use std::cell::RefCell;
   5
   6 /// A wrapper for `Rc<RefCell<I>>`, that implements the `Iterator` trait.
   7 pub struct RcIter<I> {
   8     /// The boxed iterator.
   9     pub rciter: Rc<RefCell<I>>,
  10 }
  11
  12 /// Return an iterator inside a `Rc<RefCell<_>>` wrapper.
  13 ///
  14 /// The returned `RcIter` can be cloned, and each clone will refer back to the
  15 /// same original iterator.
  16 ///
  17 /// `RcIter` allows doing interesting things like using `.zip()` on an iterator with
  18 /// itself, at the cost of runtime borrow checking which may have a performance
  19 /// penalty.
  20 ///
  21 /// Iterator element type is `Self::Item`.
  22 ///
  23 /// ```
  24 /// use itertools::rciter;
  25 /// use itertools::zip;
  26 ///
  27 /// // In this example a range iterator is created and we iterate it using
  28 /// // three separate handles (two of them given to zip).
  29 /// // We also use the IntoIterator implementation for `&RcIter`.
  30 ///
  31 /// let mut iter = rciter(0..9);
  32 /// let mut z = zip(&iter, &iter);
  33 ///
  34 /// assert_eq!(z.next(), Some((0, 1)));
  35 /// assert_eq!(z.next(), Some((2, 3)));
  36 /// assert_eq!(z.next(), Some((4, 5)));
  37 /// assert_eq!(iter.next(), Some(6));
  38 /// assert_eq!(z.next(), Some((7, 8)));
  39 /// assert_eq!(z.next(), None);
  40 /// ```
  41 ///
  42 /// **Panics** in iterator methods if a borrow error is encountered in the
  43 /// iterator methods. It can only happen if the `RcIter` is reentered in
  44 /// `.next()`, i.e. if it somehow participates in an “iterator knot”
  45 /// where it is an adaptor of itself.
  46 pub fn rciter<I>(iterable: I) -> RcIter<I::IntoIter>
  47     where I: IntoIterator
  48 {
  49     RcIter { rciter: Rc::new(RefCell::new(iterable.into_iter())) }
  50 }
  51
  52 impl<I> Clone for RcIter<I> {
  53     #[inline]
  54     fn clone(&self) -> RcIter<I> {
  55         RcIter { rciter: self.rciter.clone() }
  56     }
  57 }
  58
  59 impl<A, I> Iterator for RcIter<I>
  60     where I: Iterator<Item = A>
  61 {
  62     type Item = A;
  63     #[inline]
  64     fn next(&mut self) -> Option<A> {
  65         self.rciter.borrow_mut().next()
  66     }
  67
  68     #[inline]
  69     fn size_hint(&self) -> (usize, Option<usize>) {
  70         // To work sanely with other API that assume they own an iterator,
  71         // so it can't change in other places, we can't guarantee as much
  72         // in our size_hint. Other clones may drain values under our feet.
  73         let (_, hi) = self.rciter.borrow().size_hint();
  74         (0, hi)
  75     }
  76 }
  77
  78 impl<I> DoubleEndedIterator for RcIter<I>
  79     where I: DoubleEndedIterator
  80 {
  81     #[inline]
  82     fn next_back(&mut self) -> Option<I::Item> {
  83         self.rciter.borrow_mut().next_back()
  84     }
  85 }
  86
  87 /// Return an iterator from `&RcIter<I>` (by simply cloning it).
  88 impl<'a, I> IntoIterator for &'a RcIter<I>
  89     where I: Iterator
  90 {
  91     type Item = I::Item;
  92     type IntoIter = RcIter<I>;
  93
  94     fn into_iter(self) -> RcIter<I> {
  95         self.clone()
  96     }
  97 }