collect_exact 0.1.1

Allows zero-cost collection into exact-size arrays and tuples.
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

//! Allows zero-cost collection into exact-size arrays and tuples.
//!
//! ## Usage
//!
//! ```rust
//! use collect_exact::CollectExact;
//!
//! let iter = [1, 2, 3].into_iter();
//! let result = iter.collect_exact::<[u32; 3]>();
//!
//! assert_eq!(result, Ok([1, 2, 3]));
//! ```

#![warn(missing_docs)]
#![warn(clippy::pedantic)]

mod error;
mod impls;
mod result;
mod tuples;

pub use error::{Error, PrefixError};

/// Extension trait for collecting into collections whose length is known at compile time.
pub trait CollectExact {
    /// The type of items in the iterator.
    type Item;

    /// Transforms an iterator into a collection whose length is known at compile time.
    ///
    /// See also [`Iterator::collect`].
    ///
    /// # Errors
    ///
    /// Returns an error if the iterator does not contain the same number of items as the collection.
    fn collect_exact<B: FromIteratorExact<Self::Item>>(self) -> Result<B, Error>
    where
        Self: Sized;

    /// Transforms a prefix of the iterator into a collection whose length is known at compile time.
    /// Drops the iterator once it has collected enough items.
    ///
    /// See also [`CollectExact::collect_exact`].
    ///
    /// # Errors
    ///
    /// Returns an error if the iterator contains fewer items than the collection.
    fn collect_exact_prefix<B: FromIteratorExact<Self::Item>>(self) -> Result<B, PrefixError>
    where
        Self: Sized;
}

/// Conversion from an [`Iterator`] for a collection whose length is known at compile time.
pub trait FromIteratorExact<T>: Sized {
    /// Creates a collection from an iterator.
    ///
    /// See also [`CollectExact::collect_exact`].
    ///
    /// # Errors
    ///
    /// Returns an error if the iterator does not contain the same number of items as the collection.
    fn from_iter_exact<I: IntoIterator<Item = T>>(iter: I) -> Result<Self, Error>;

    /// Creates a collection from a prefix of an iterator.
    ///
    /// See also [`CollectExact::collect_exact_prefix`].
    ///
    /// # Errors
    ///
    /// Returns an error if the iterator contains fewer items than the collection.
    fn from_iter_exact_prefix<I: IntoIterator<Item = T>>(iter: I) -> Result<Self, PrefixError>;
}

impl<Iter> CollectExact for Iter
where
    Iter: Iterator,
{
    type Item = <Self as Iterator>::Item;

    fn collect_exact<B: FromIteratorExact<Self::Item>>(self) -> Result<B, Error>
    where
        Self: Sized,
    {
        FromIteratorExact::from_iter_exact(self)
    }

    fn collect_exact_prefix<B: FromIteratorExact<Self::Item>>(self) -> Result<B, PrefixError>
    where
        Self: Sized,
    {
        FromIteratorExact::from_iter_exact_prefix(self)
    }
}

impl<T, const N: usize> FromIteratorExact<T> for [T; N] {
    fn from_iter_exact<I: IntoIterator<Item = T>>(iter: I) -> Result<Self, Error> {
        impls::collect_exact(iter.into_iter())
    }

    fn from_iter_exact_prefix<I: IntoIterator<Item = T>>(iter: I) -> Result<Self, PrefixError> {
        impls::collect_exact_prefix(iter.into_iter())
    }
}