count-to-non-zero 0.3.0

Extends Rust's Iterator trait to include a `count_to_non_zero` method, returning an Option<NonZeroUsize> for a more expressive and type-safe way of counting elements. This crate provides a convenient and idiomatic approach to obtaining non-zero element counts from iterators, enhancing code readability and safety by leveraging Rust's type system. Perfect for applications where distinguishing between empty and non-empty iterators is crucial, without the overhead of manual count checks.
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

#![doc = include_str!("../README.md")]

use std::num::NonZeroUsize;

/// An extension trait for iterators to count non-zero elements.
///
/// This trait provides an additional method to iterators, `count_to_non_zero`,
/// which returns an `Option<NonZeroUsize>` representing the number of elements
/// iterated over that are not zero. This method leverages Rust's type system
/// to provide a guarantee at compile time that the count is non-zero when
/// Some value is returned.
pub trait CountToNonZeroExt: Iterator {
    /// Counts the number of non-zero elements the iterator iterates over.
    ///
    /// # Returns
    ///
    /// - `Some(NonZeroUsize)` if the iterator contains non-zero elements, with
    /// the count of those elements.
    /// - `None` if the iterator is empty or only contains zeros.
    ///
    /// # Examples
    ///
    /// ```
    /// use count_to_non_zero::CountToNonZeroExt;
    /// let data = vec![0, 1, 2, 0, 3];
    /// let count = data.into_iter().count_to_non_zero();
    /// assert_eq!(count, Some(std::num::NonZeroUsize::new(5).unwrap()));
    /// ```
    fn count_to_non_zero(self) -> Option<NonZeroUsize>;
}

impl<T> CountToNonZeroExt for T
where
    T: Iterator,
{
    fn count_to_non_zero(self) -> Option<NonZeroUsize> {
        let count = self.count();
        NonZeroUsize::new(count)
    }
}

#[cfg(test)]
mod tests {
    use std::num::NonZeroUsize;

    use super::*;

    #[test]
    fn empty_iterator() {
        let data: Vec<u32> = vec![];
        let count = data.into_iter().count_to_non_zero();
        assert_eq!(count, None);
    }

    #[test]
    fn all_non_zeros_iterator() {
        let data = vec![1, 2, 3];
        let count = data.into_iter().count_to_non_zero();
        assert_eq!(count, Some(NonZeroUsize::new(3).unwrap()));
    }
}