not_empty 0.1.3

Slices and vectors that are statically guaranteed to be not empty.
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

use crate::{EmptyError, NonEmptyVec};

/// Extends [`Iterator`] with methods for collecting [`NonEmptyVec`]s as a
/// stop-gap to retain a fallible [`Iterator::collect`] functionality.
///
/// Unlike [`Iterator::collect`], the use of the turbo-fish operator is likely
/// not required as the method only collects into a [`NonEmptyVec`].
pub trait IteratorExt: Iterator {
    /// Transforms an iterator into a [`NonEmptyVec<Self::Item>`] without
    /// validating if the iterator has items.
    ///
    /// If you're not certain that the iterator won't be empty, use
    /// [`IteratorExt::collect_nonempty`] instead.
    ///
    /// # Safety
    ///
    /// The iterator must not be empty.
    ///
    /// # Examples
    ///
    /// ```
    /// use not_empty::{IteratorExt, NonEmptyVec};
    ///
    /// let array = [1, 2, 3];
    ///
    /// unsafe {
    ///     let doubled = array
    ///         .iter()
    ///         .map(|&x| x * 2)
    ///         .collect_nonempty_unchecked();
    ///     assert_eq!(doubled, not_empty::vec![2, 4, 6]);
    /// }
    /// ```
    #[cfg(all(any(feature = "alloc", feature = "std"), not(no_global_oom_handling)))]
    #[cfg_attr(
        doc_cfg,
        doc(cfg(all(any(feature = "alloc", feature = "std"), not(no_global_oom_handling))))
    )]
    #[inline]
    #[must_use = "if you really need to exhaust the iterator, consider `.for_each(drop)` instead"]
    #[track_caller]
    unsafe fn collect_nonempty_unchecked(self) -> NonEmptyVec<Self::Item>
    where
        Self: Sized,
    {
        let vec = self.collect();
        NonEmptyVec::new_unchecked(vec)
    }

    /// Transforms an iterator into a [`NonEmptyVec<Self::Item>`].
    ///
    /// # Errors
    ///
    /// Returns an [`EmptyError`] if the iterator yields no values.
    ///
    /// # Examples
    ///
    /// ```
    /// use not_empty::IteratorExt;
    ///
    /// # fn main() -> Result<(), not_empty::EmptyError> {
    /// let array = [1, 2, 3];
    /// let doubled = array.iter().map(|&x| x * 2).collect_nonempty()?;
    /// assert_eq!(doubled, not_empty::vec![2, 4, 6]);
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(all(any(feature = "alloc", feature = "std"), not(no_global_oom_handling)))]
    #[cfg_attr(
        doc_cfg,
        doc(cfg(all(any(feature = "alloc", feature = "std"), not(no_global_oom_handling))))
    )]
    #[inline]
    fn collect_nonempty(self) -> Result<NonEmptyVec<Self::Item>, EmptyError>
    where
        Self: Sized,
    {
        let vec = self.collect();
        NonEmptyVec::new(vec)
    }
}

impl<I> IteratorExt for I where I: Iterator {}