lender/traits/
collect.rs

1use crate::{FallibleLend, FallibleLender, Lend, Lender};
2
3/// A trait for creating a value from a [`Lender`].
4///
5/// # Examples
6/// ```
7/// # use lender::prelude::*;
8/// struct MyStruct;
9/// impl<L: IntoLender> FromLender<L> for MyStruct
10/// where
11///     L::Lender: for<'all> Lending<'all, Lend = &'all mut [i32]>,
12/// {
13///     fn from_lender(lender: L) -> Self {
14///         lender.into_lender().for_each(|lend| drop(lend));
15///         Self
16///     }
17/// }
18/// ```
19pub trait FromLender<L: IntoLender>: Sized {
20    /// Creates a value from a [`Lender`].
21    fn from_lender(lender: L) -> Self;
22}
23
24/// A trait for creating a value from a [`FallibleLender`].
25///
26/// This is the fallible counterpart to [`FromLender`].
27///
28/// # Examples
29/// ```
30/// # use lender::prelude::*;
31/// # use std::convert::Infallible;
32/// struct MyVec(Vec<i32>);
33///
34/// impl<L: IntoFallibleLender<Error = Infallible>> FromFallibleLender<L> for MyVec
35/// where
36///     L::FallibleLender: for<'all> FallibleLending<'all, Lend = i32>,
37/// {
38///     fn from_fallible_lender(lender: L) -> Result<Self, Infallible> {
39///         let mut vec = Vec::new();
40///         lender.into_fallible_lender().for_each(|x| {
41///             vec.push(x);
42///             Ok(())
43///         })?;
44///         Ok(MyVec(vec))
45///     }
46/// }
47/// ```
48pub trait FromFallibleLender<L: IntoFallibleLender>: Sized {
49    /// Creates a value from a [`FallibleLender`],
50    /// returning an error if the lender produces one.
51    fn from_fallible_lender(lender: L) -> Result<Self, L::Error>;
52}
53
54/// Conversion into a [`Lender`].
55///
56/// This is the [`Lender`] version of [`core::iter::IntoIterator`].
57///
58/// Every [`Lender`] implements `IntoLender` for itself (returning `self`).
59pub trait IntoLender {
60    /// The lender type that this type converts into.
61    type Lender: Lender;
62    /// Converts this type into a [`Lender`].
63    fn into_lender(self) -> <Self as IntoLender>::Lender;
64}
65
66impl<L: Lender> IntoLender for L {
67    type Lender = L;
68    #[inline]
69    fn into_lender(self) -> L {
70        self
71    }
72}
73
74/// The [`Lender`] version of [`core::iter::Extend`].
75pub trait ExtendLender<L: IntoLender> {
76    /// Extends a collection with the contents of a lender.
77    fn extend_lender(&mut self, lender: L);
78    /// Extends a collection with exactly one element.
79    fn extend_lender_one(&mut self, item: Lend<'_, L::Lender>);
80    /// Reserves capacity in a collection for the given number
81    /// of additional elements.
82    ///
83    /// The default implementation does nothing.
84    #[inline]
85    fn extend_lender_reserve(&mut self, additional: usize) {
86        let _ = additional;
87    }
88}
89
90/// The [`FallibleLender`] version of [`core::iter::Extend`].
91///
92/// This is the fallible counterpart to [`ExtendLender`].
93pub trait ExtendFallibleLender<L: IntoFallibleLender> {
94    /// Extends a collection with elements from a fallible lender.
95    ///
96    /// Returns an error if the lender produces an error during iteration.
97    fn extend_fallible_lender(&mut self, lender: L) -> Result<(), L::Error>;
98
99    /// Extends a collection with exactly one element.
100    fn extend_fallible_lender_one(&mut self, item: FallibleLend<'_, L::FallibleLender>);
101
102    /// Reserves capacity in a collection for the given number
103    /// of additional elements.
104    ///
105    /// The default implementation does nothing.
106    #[inline]
107    fn extend_fallible_lender_reserve(&mut self, additional: usize) {
108        let _ = additional;
109    }
110}
111
112/// Conversion into a [`FallibleLender`].
113///
114/// This is the [`FallibleLender`] version of [`core::iter::IntoIterator`].
115///
116/// By implementing `IntoFallibleLender` for a type, you define how it will be
117/// converted to a fallible lender.
118///
119/// Every [`FallibleLender`] implements `IntoFallibleLender` for itself
120/// (returning `self`).
121pub trait IntoFallibleLender {
122    /// The error type of the resulting fallible lender.
123    type Error;
124    /// The fallible lender type that this type converts into.
125    type FallibleLender: FallibleLender<Error = Self::Error>;
126    /// Converts this type into a [`FallibleLender`].
127    fn into_fallible_lender(self) -> Self::FallibleLender;
128}
129
130impl<L: FallibleLender> IntoFallibleLender for L {
131    type Error = L::Error;
132    type FallibleLender = L;
133    #[inline]
134    fn into_fallible_lender(self) -> L {
135        self
136    }
137}
lender/traits/collect.rs

lender/traits/
collect.rs
