size_hinter 0.4.2

Iterator adaptors allowing overriding or specifying size_hint.
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
112
113
114
115
116
117

use core::{iter::FusedIterator, panic};

use crate::SizeHint;

/// A test [`Iterator`] that can not be iterated over, but has an arbitrary size hint.
///
/// This is useful for testing how consumers handle various size hints.
///
/// # Type parameters
///
/// * `T` - The nominal item type of the iterator.
///
/// /// # Examples
///
/// ```rust
/// # use size_hinter::TestIterator;
/// let iter = TestIterator::<()>::new((5, Some(10)));
/// assert_eq!(iter.size_hint(), (5, Some(10)));
/// ```
pub struct TestIterator<T = ()> {
    size_hint: (usize, Option<usize>),
    _marker: core::marker::PhantomData<T>,
}

impl<T> TestIterator<T> {
    /// Creates a new [`TestIterator`] with the given `size_hint` as its size hint.
    ///
    /// The validity of the size hint is not checked.
    ///
    /// # Arguments
    ///
    /// * `size_hint` - The size hint to use. It's validity is not checked.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use size_hinter::TestIterator;
    /// let iter = TestIterator::<()>::new((5, Some(10)));
    /// assert_eq!(iter.size_hint(), (5, Some(10)));
    /// ```
    #[must_use]
    pub const fn new(size_hint: (usize, Option<usize>)) -> Self {
        Self { size_hint, _marker: core::marker::PhantomData }
    }

    /// Creates a new [`TestIterator`] with an exact size hint.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use size_hinter::TestIterator;
    /// let iter = TestIterator::<()>::exact(5);
    /// assert_eq!(iter.size_hint(), (5, Some(5)));
    /// ```
    #[must_use]
    pub const fn exact(len: usize) -> Self {
        Self::new((len, Some(len)))
    }

    /// Creates a new [`TestIterator`] with an invalid size hint.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use size_hinter::TestIterator;
    /// let iter = TestIterator::<()>::invalid();
    /// let (lower, upper) = iter.size_hint();
    /// assert!(lower > upper.unwrap(), "Size hint should be invalid");
    /// ```
    #[must_use]
    pub const fn invalid() -> Self {
        Self::INVALID
    }

    /// A [`TestIterator`] with a [`SizeHint::UNIVERSAL`] size hint.
    pub const UNIVERSAL: Self = Self::new(SizeHint::UNIVERSAL.as_hint());

    /// A [`TestIterator`] with a [`SizeHint::ZERO`] size hint.
    pub const ZERO: Self = Self::new(SizeHint::ZERO.as_hint());

    /// A [`TestIterator`] with an invalid size hint.
    pub const INVALID: Self = Self::new((10, Some(5)));
}

impl<T> Iterator for TestIterator<T> {
    type Item = T;

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.size_hint
    }

    fn next(&mut self) -> Option<Self::Item> {
        unimplemented!("TestIterator is not iteratable");
    }
}

impl<T> FusedIterator for TestIterator<T> {}

impl<T> ExactSizeIterator for TestIterator<T> {
    /// Returns the exact length of the iterator.
    ///
    /// # Panics
    ///
    /// Panics if the size hint is not exact.
    fn len(&self) -> usize {
        match self.size_hint() {
            (lower, Some(upper)) if lower == upper => lower,
            _ => panic!("Inexact size hint"),
        }
    }
}

impl<T> DoubleEndedIterator for TestIterator<T> {
    fn next_back(&mut self) -> Option<Self::Item> {
        unimplemented!("TestIterator is not iteratable");
    }
}