collect_failable 0.18.0

A trait for collecting values into a container which has an invariant to uphold and whose construction may fail
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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

#[cfg(feature = "alloc")]
use alloc::boxed::Box;

use core::error::Error;
use core::fmt::{Debug, Display, Formatter};
use core::ops::Deref;

use display_as_debug::fmt::DebugStructExt;
use display_as_debug::types::{Full, Short};
use nameof::name_of;
use tap::Pipe;

/// An error that occurs when extending a tuple of collections fails.
///
/// This error preserves the error from the side that failed, any pending item from the other side,
/// and the remaining iterator for error recovery.
///
/// Note this type is *read-only*. The fields are accessible via a hidden [`Deref`]
/// implementation into a hidden `TupleExtendErrorData` type, with identical fields. If necessary,
/// you can consume an instance of this type via [`TupleExtendError::into_data`] to get owned data.
///
/// # Type Parameters
///
/// - `E`: The error type from the failing collection.
/// - `P`: The type of the pending item from the other collection.
/// - `I`: The type of the remaining iterator.
#[subdef::subdef]
pub struct TupleExtendError<E, P, I> {
    #[cfg(doc)]
    /// The error that occurred during extension.
    pub error: E,
    #[cfg(doc)]
    /// The pending item from the other side, if any.
    pub pending: Option<P>,
    #[cfg(doc)]
    /// The remaining iterator after the error occurred
    pub remaining: I,

    #[cfg(all(not(doc), feature = "alloc"))]
    data: Box<TupleExtendErrorData<E, P, I>>,
    #[cfg(all(not(doc), not(feature = "alloc")))]
    data: TupleExtendErrorData<E, P, I>,
}

/// The internal data of a [`TupleExtendError`].
#[doc(hidden)]
pub struct TupleExtendErrorData<E, P, I> {
    /// The error that occurred during extension.
    pub error: E,
    /// The pending item from the other side, if any.
    pub pending: Option<P>,
    /// The remaining iterator after the error occurred
    pub remaining: I,
}

#[doc(hidden)]
impl<E, P, I> TupleExtendError<E, P, I> {
    /// Creates a new [`TupleExtendError`].
    #[must_use]
    #[cfg(feature = "alloc")]
    pub fn new(error: E, pending: Option<P>, remaining: I) -> Self {
        TupleExtendErrorData { error, pending, remaining }.pipe(Box::new).pipe(|data| Self { data })
    }

    /// Creates a new [`TupleExtendError`].
    #[must_use]
    #[cfg(not(feature = "alloc"))]
    pub fn new(error: E, pending: Option<P>, remaining: I) -> Self {
        TupleExtendErrorData { error, pending, remaining }.pipe(|data| Self { data })
    }
}

impl<E, P, I> TupleExtendError<E, P, I> {
    /// Consumes the error, returning the data.
    #[must_use]
    #[cfg(feature = "alloc")]
    pub fn into_data(self) -> TupleExtendErrorData<E, P, I> {
        *self.data
    }

    /// Consumes the error, returning the data.
    #[must_use]
    #[cfg(not(feature = "alloc"))]
    pub fn into_data(self) -> TupleExtendErrorData<E, P, I> {
        self.data
    }
}

#[doc(hidden)]
impl<E, P, I> Deref for TupleExtendError<E, P, I> {
    type Target = TupleExtendErrorData<E, P, I>;

    fn deref(&self) -> &Self::Target {
        &self.data
    }
}

impl<E: Debug, P, I> Debug for TupleExtendError<E, P, I> {
    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("TupleExtendError")
            .field(name_of!(error in Self), &self.error)
            .field_type::<P, Short>(name_of!(pending in Self))
            .field_type::<I, Full>(name_of!(remaining in Self))
            .finish()
    }
}

#[doc(hidden)]
#[allow(clippy::missing_fields_in_debug, reason = "All fields actually covered")]
impl<E: Debug, P, I> Debug for TupleExtendErrorData<E, P, I> {
    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("TupleExtendErrorData")
            .field(name_of!(error in Self), &self.error)
            .field_type::<P, Short>(name_of!(pending in Self))
            .field_type::<I, Full>(name_of!(remaining in Self))
            .finish()
    }
}

impl<E: Display, P, I> Display for TupleExtendError<E, P, I> {
    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
        write!(f, "Error while extending collection: {}", self.error)
    }
}

impl<E: Error + 'static, P, I> Error for TupleExtendError<E, P, I> {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.error)
    }
}

#[doc(hidden)]
impl<E: Display, P, I> Display for TupleExtendErrorData<E, P, I> {
    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
        write!(f, "Error while extending collection: {}", self.error)
    }
}

#[doc(hidden)]
impl<E: Error + 'static, P, I> Error for TupleExtendErrorData<E, P, I> {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.error)
    }
}