prepeek 0.1.1

Peekable iterators without mutation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

use std::usize;

/// Wrapper struct to an iterator, offering `peek` and `peek_nth`.
///
/// Internally holds the next `L` elements to allow for peeking without `mut`.
pub struct Prepeek<I: Iterator, const L: usize> {
    iter: I,
    ring: [Option<I::Item>; L],
    ring_index: usize,
}

impl<I: Iterator, const L: usize> Prepeek<I, L> {

    /// Creates a [`Prepeek`] object wrapping the given [`Iterator`].
    ///
    /// Calls next() `L` times on the iterator to fill up the internal buffer.
    pub fn new(iter: I) -> Self {
        let mut s = Self {
            iter,
            ring: [const { None }; L],
            ring_index: 0,
        };
        // fill ring buffer
        for _ in 0..L {
            s.next();
        }
        s
    }

    /// Returns a reference to the next() value without advancing the iterator.
    ///
    /// Like next, if there is a value, it is wrapped in a `Some(T)`. But if the iteration is over, `None` is returned.
    ///
    /// If `L` of this [`Prepeek`] object is 0, None is returned.
    pub fn peek(&self) -> Option<&I::Item> {
        self.peek_nth(0)
    }

    /// Returns a reference to the `nth` value without advancing the iterator.
    ///
    /// If `n` is greater or equal to `L`, None is returned.
    pub fn peek_nth(&self, n: usize) -> Option<&I::Item> {
        if n >= L {
            None
        } else {
            self.ring[(self.ring_index + n) % L].as_ref()
        }
    }
}

impl<I: Iterator, const L: usize> Iterator for Prepeek<I, L> {
    type Item = I::Item;

    fn next(&mut self) -> Option<Self::Item> {
        let mut v = self.iter.next();
        if L != 0 {
            v = std::mem::replace(&mut self.ring[self.ring_index], v);
            self.ring_index = (self.ring_index + 1) % L;
        }
        v
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_simple() {
        let array = [1, 2, 3];
        let mut peekable = Prepeek::<_, 2>::new(array.into_iter());
        assert_eq!(peekable.peek().cloned(), Some(1));
        assert_eq!(peekable.peek_nth(1).cloned(), Some(2));
        assert_eq!(peekable.peek_nth(2).cloned(), None);

        assert_eq!(peekable.next(), Some(1));
        assert_eq!(peekable.peek().cloned(), Some(2));
        assert_eq!(peekable.peek_nth(1).cloned(), Some(3));
        assert_eq!(peekable.peek_nth(2).cloned(), None);

        assert_eq!(peekable.next(), Some(2));
        assert_eq!(peekable.peek().cloned(), Some(3));
        assert_eq!(peekable.peek_nth(1).cloned(), None);
        assert_eq!(peekable.peek_nth(2).cloned(), None);

        assert_eq!(peekable.next(), Some(3));
        assert_eq!(peekable.peek().cloned(), None);
        assert_eq!(peekable.peek_nth(1).cloned(), None);
        assert_eq!(peekable.peek_nth(2).cloned(), None);
    }

    #[test]
    fn test_no_prefetch() {
        let array = [1, 2, 3];
        let mut peekable = Prepeek::<_, 0>::new(array.into_iter());
        assert_eq!(peekable.peek().cloned(), None);
        assert_eq!(peekable.next(), Some(1));
    }

    #[test]
    fn test_overallocated() {
        let array = [1, 2, 3];
        let mut peekable = Prepeek::<_, 5>::new(array.into_iter());
        assert_eq!(peekable.next(), Some(1));
        assert_eq!(peekable.next(), Some(2));
        assert_eq!(peekable.next(), Some(3));
        assert_eq!(peekable.peek_nth(0).cloned(), None);
        assert_eq!(peekable.peek_nth(1).cloned(), None);
        assert_eq!(peekable.peek_nth(2).cloned(), None);
    }
}