devela/code/result/own/
mod.rs

Help
1// devela::code::result::own
2//
3//!
4//
5
6mod general;
7mod state;
8mod value;
9
10#[doc = crate::TAG_RESULT!()]
11/// A return type encapsulating an owned **state** `S` and a **value** `V`.
12///
13/// It is designed to be used by methods that take ownership of `self`,
14/// and return it alongside the operation-specific result.
15///
16/// By convention methods that return an `Own` should to be prefixed with `own_`,
17/// and any [`Result`] or [`Option`] should be part of the `state` field for the
18/// constructors, and part of the `value` field for most other methods, allowing
19/// `self` to be passed along a chain of operations.
20///
21/// ## Methods
22///
23/// ### [General methods](#impl-Own<S,+V>)
24/// Additional [*const* methods](#impl-Own<S,+V>-1) are available when both types are `Copy`.
25/// - Construct:
26///   [`new`](#method.new),
27///   [`empty`](#method.empty).
28/// - Deconstruct:
29///   [`sv`](#method.sv)*([const](#method.sv_const))*
30///   [`sv_ref`](#method.sv_ref),
31///   [`sv_mut`](#method.sv_mut).
32/// - Replace:
33///   [`s_replace`](#method.s_replace)*([const](#method.s_const_replace))*,
34///   [`v_replace`](#method.v_replace)*([const](#method.v_const_replace))*,
35///   [`sv_replace`](#method.sv_replace)*([const](#method.sv_const_replace))*,
36/// - Wrap:
37///   [`s_wrap_ok`](#method.s_wrap_ok)*([const](#method.s_const_wrap_ok))*,
38///   [`s_wrap_some`](#method.s_wrap_some)*([const](#method.s_const_wrap_some))*,
39///   [`v_wrap_ok`](#method.v_wrap_ok)*([const](#method.v_const_wrap_ok))*,
40///   [`v_wrap_some`](#method.v_wrap_some)*([const](#method.v_const_wrap_some))*,
41/// - Map:
42///   [`s_map`](#method.s_map),
43///   [`v_map`](#method.v_map),
44///   [`sv_map`](#method.sv_map).
45/// - Query:
46///   [`s_eq`](#method.s_eq),
47///   [`v_eq`](#method.v_eq),
48///   [`sv_eq`](#method.sv_eq).
49/// - Assert:
50///   [`s_assert`](#method.s_assert)*([or](#method.s_assert_or),
51///     [eq](#method.s_assert_eq), [eq_or](#method.s_assert_eq_or))*,
52///   [`v_assert`](#method.v_assert)*([or](#method.v_assert_or)
53///     [eq](#method.v_assert_eq), [eq_or](#method.v_assert_eq_or))*,
54///   [`sv_assert`](#method.sv_assert)*([or](#method.sv_assert_or),
55///     [eq](#method.sv_assert_eq), [eq_or](#method.sv_assert_eq_or))*.
56///
57/// ### [Methods for when `state` is a `Result`](#impl-Own<Result<S,+E>,+V>)
58/// - Map:
59///   [`s_map_ok`](#method.s_map_ok),
60///   [`s_map_err`](#method.s_map_err),
61///   [`s_and`](#method.s_and),
62///   [`s_and_then`](#method.s_and_then).
63/// - Assert:
64///   [`s_assert_ok`](#method.s_assert_ok)*([or](#method.s_assert_ok_or))*,
65///   [`s_assert_err`](#method.s_assert_err)*([or](#method.s_assert_err_or))*.
66/// - Unwrap:
67///   [`s_unwrap`](#method.s_unwrap)*([const](#method.s_const_unwrap))*,
68///   [`s_unwrap_or`](#method.s_unwrap_or)*([const](#method.s_const_unwrap_or))*,
69///   [`s_expect`](#method.s_expect)*([const](#method.s_const_expect))*.
70///
71/// ### [Methods for when `state` is an `Option`](#impl-Own<Option<S>,+V>)
72/// - Map:
73///   [`s_map_some`](#method.s_map_some),
74///   [`s_and`](#method.s_and-1),
75///   [`s_and_then`](#method.s_and_then-1).
76/// - Assert:
77///   [`s_assert_some`](#method.s_assert_some)*([or](#method.s_assert_some_or))*,
78///   [`s_assert_none`](#method.s_assert_none)*([or](#method.s_assert_none_or))*.
79/// - Unwrap:
80///   [`s_unwrap`](#method.s_unwrap-1)*([const](#method.s_const_unwrap-1))*,
81///   [`s_unwrap_or`](#method.s_unwrap_or-1)*([const](#method.s_const_unwrap_or-1))*,
82///   [`s_expect`](#method.s_expect-1)*([const](#method.s_const_expect-1))*.
83///
84/// ### [Methods for when `value` is a `Result`](#impl-Own<S,+Result<V,+E>>)
85/// - Map:
86///   [`v_map_ok`](#method.v_map_ok),
87///   [`v_map_err`](#method.v_map_err),
88///   [`v_and`](#method.v_and),
89///   [`v_and_then`](#method.v_and_then).
90/// - Assert:
91///   [`v_assert_ok`](#method.v_assert_ok)*([or](#method.v_assert_ok_or))*,
92///   [`v_assert_err`](#method.v_assert_err)*([or](#method.v_assert_err_or))*.
93/// - Unwrap:
94///   [`v_unwrap`](#method.v_unwrap)*([const](#method.v_const_unwrap))*,
95///   [`v_unwrap_or`](#method.v_unwrap_or)*([const](#method.v_const_unwrap_or))*,
96///   [`v_expect`](#method.v_expect)*([const](#method.v_const_expect))*.
97///
98/// ### [Methods for when `value` is an `Option`](#impl-Own<S,+Option<V>>)
99/// - Map:
100///   [`v_map_some`](#method.v_map_some),
101///   [`v_and`](#method.v_and-1),
102///   [`v_and_then`](#method.v_and_then-1).
103/// - Assert:
104///   [`v_assert_some`](#method.v_assert_some)*([or](#method.v_assert_some_or))*,
105///   [`v_assert_none`](#method.v_assert_none)*([or](#method.v_assert_none_or))*.
106/// - Unwrap:
107///   [`v_unwrap`](#method.v_unwrap-1)*([const](#method.v_const_unwrap-1))*,
108///   [`v_unwrap_or`](#method.v_unwrap_or-1)*([const](#method.v_const_unwrap_or-1))*,
109///   [`v_expect`](#method.v_expect-1)*([const](#method.v_const_expect-1))*.
110#[must_use]
111pub struct Own<S, V> {
112    /// The `state` after the operation.
113    pub s: S,
114
115    /// The `value` resulting from the operation.
116    pub v: V,
117}
118
119mod core_impls {
120    use crate::{ConstDefault, Debug, Display, FmtResult, Formatter, Ordering, Own};
121
122    impl<S: Default, V: Default> Default for Own<S, V> {
123        fn default() -> Self {
124            Own::new(S::default(), V::default())
125        }
126    }
127    impl<S: ConstDefault, V: ConstDefault> ConstDefault for Own<S, V> {
128        const DEFAULT: Self = Own::new(S::DEFAULT, V::DEFAULT);
129    }
130
131    impl<S: Debug, V: Debug> Debug for Own<S, V> {
132        fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult<()> {
133            let mut debug = f.debug_struct("Own");
134            debug.field("state", &self.s).field("value", &self.v).finish()
135        }
136    }
137    impl<S: Display, V: Display> Display for Own<S, V> {
138        fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult<()> {
139            write!(f, "State: {}, Value: {}", self.s, self.v)
140        }
141    }
142
143    impl<S: Clone, V: Clone> Clone for Own<S, V> {
144        fn clone(&self) -> Self {
145            Own::new(self.s.clone(), self.v.clone())
146        }
147    }
148    impl<S: Copy, V: Copy> Copy for Own<S, V> {}
149
150    impl<S: PartialEq, V: PartialEq> PartialEq for Own<S, V> {
151        fn eq(&self, other: &Self) -> bool {
152            self.s == other.s && self.v == other.v
153        }
154    }
155    impl<S: Eq, V: Eq> Eq for Own<S, V> {}
156
157    impl<S: PartialOrd, V: PartialOrd> PartialOrd for Own<S, V> {
158        /// State's ordering takes precedence over value's ordering.
159        fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
160            match self.s.partial_cmp(&other.s) {
161                Some(Ordering::Equal) => self.v.partial_cmp(&other.v),
162                other => other,
163            }
164        }
165    }
166    impl<S: Ord, V: Ord> Ord for Own<S, V> {
167        /// State's ordering takes precedence over value's ordering.
168        fn cmp(&self, other: &Self) -> Ordering {
169            match self.s.cmp(&other.s) {
170                Ordering::Equal => self.v.cmp(&other.v),
171                other => other,
172            }
173        }
174    }
175}
devela/code/result/own/mod.rs

devela/code/result/own/
mod.rs
