devela/code/result/opt_res/
ext_option.rs

Help
1// devela::code::result::option::ext
2//
3//!
4//
5
6use super::{OptionFmt, OptionFmtOr, OptionFmtOrElse};
7use crate::Display;
8
9/// Marker trait to prevent downstream implementations of the [`ExtOption`] trait.
10trait Sealed {}
11impl<T> Sealed for Option<T> {}
12
13/// Extension trait providing additional methods for [`Option`].
14///
15/// This trait is sealed and cannot be implemented for any other type.
16///
17/// See also [`ExtResult`][crate::ExtResult],
18/// [`ExtOptRes`][crate::ExtOptRes].
19///
20/// Based on work from:
21/// - <https://github.com/rust-lang/rust/issues/62358> (contains).
22/// - <https://github.com/rust-lang/rust/pull/87036> (reduce).
23#[cfg_attr(feature = "nightly_doc", doc(notable_trait))]
24#[expect(private_bounds, reason = "Sealed")]
25pub trait ExtOption<T>: Sealed {
26    /// Returns `true` if the option is a [`Some`] value containing the given value.
27    ///
28    /// # Example
29    /// ```
30    /// # use devela::ExtOption;
31    /// assert_eq!(Some(1).contains(&1), true);
32    /// assert_eq!(Some(1).contains(&2), false);
33    /// assert_eq!(None::<u8>.contains(&1), false);
34    /// ```
35    #[must_use]
36    fn contains<U: PartialEq<T>>(&self, x: &U) -> bool;
37
38    /// Merges `self` with another `Option`.
39    ///
40    /// Returns
41    /// - `Some(f(l, r))` if both options are `Some(_)`.
42    /// - `Some(x)` if either of the options is `Some(x)` and the other is `None`.
43    /// - `None` if both options are `None`.
44    ///
45    /// # Example
46    /// ```
47    /// # use devela::ExtOption;
48    /// # use core::{cmp::min, ops::Add};
49    /// let (x, y) = (Some(2), Some(4));
50    ///
51    /// assert_eq!(x.reduce(y, Add::add), Some(6));
52    /// assert_eq!(x.reduce(y, min), Some(2));
53    ///
54    /// assert_eq!(x.reduce(None, Add::add), x);
55    /// assert_eq!(None.reduce(y, min), y);
56    ///
57    /// assert_eq!(None.reduce(None, i32::add), None);
58    /// ```
59    #[must_use]
60    fn reduce<F: FnOnce(T, T) -> T>(self, other: Option<T>, f: F) -> Option<T>;
61
62    /// Format some value, or an alternative if it's `None`.
63    ///
64    /// The alternative value must implement [`Display`]
65    /// regardless of which formatting is used originally.
66    ///
67    /// # Example
68    /// ```
69    /// # use devela::ExtOption;
70    /// assert_eq!("42", format!("{}", Some(Box::new(42)).fmt_or("Nothing")));
71    /// assert_eq!("Nothing", format!("{}", None::<u8>.fmt_or("Nothing")));
72    /// ```
73    #[doc = crate::doc_!(vendor: "fmtor")]
74    #[must_use]
75    fn fmt_or<U: Display>(&self, u: U) -> OptionFmtOr<T, U>;
76
77    /// Format some value, or run an alternative closure if it's `None`.
78    ///
79    /// The value returned from the closure must implement [`Display`]
80    /// regardless of which formatting is used originally.
81    ///
82    /// The value returned from the closure is not stored after use.
83    /// Therefore, using a single [`OptionFmtOrElse`] object for multiple
84    /// formatting operations will run the closure multiple times.
85    ///
86    /// # Example
87    /// ```
88    /// # use devela::ExtOption;
89    /// assert_eq!("42", format!("{}", Some(42).fmt_or_else(|| "Nothing")));
90    /// assert_eq!("Nothing", format!("{}", None::<u8>.fmt_or_else(|| "Nothing")));
91    /// ```
92    #[must_use]
93    fn fmt_or_else<U: Display, F: Fn() -> U>(&self, f: F) -> OptionFmtOrElse<T, F>;
94
95    /// Format some value, or display an empty string if it's `None`.
96    ///
97    /// # Example
98    /// ```
99    /// # use devela::ExtOption;
100    /// assert_eq!("0x42", format!("{:#x}", Some(0x42).fmt_or_empty()));
101    /// assert_eq!("", format!("{:#x}", None::<u8>.fmt_or_empty()));
102    /// ```
103    #[must_use]
104    fn fmt_or_empty(&self) -> OptionFmt<T>;
105}
106
107impl<T> ExtOption<T> for Option<T> {
108    fn contains<U: PartialEq<T>>(&self, x: &U) -> bool {
109        self.as_ref().is_some_and(|y| x == y)
110    }
111
112    fn reduce<F: FnOnce(T, T) -> T>(self, other: Option<T>, f: F) -> Option<T> {
113        match (self, other) {
114            (Some(l), Some(r)) => Some(f(l, r)),
115            (x @ Some(_), None) | (None, x @ Some(_)) => x,
116            (None, None) => None,
117        }
118    }
119
120    fn fmt_or_empty(&self) -> OptionFmt<T> {
121        OptionFmt(self)
122    }
123
124    fn fmt_or<U: Display>(&self, u: U) -> OptionFmtOr<T, U> {
125        OptionFmtOr(self, u)
126    }
127
128    fn fmt_or_else<U: Display, F: Fn() -> U>(&self, f: F) -> OptionFmtOrElse<T, F> {
129        OptionFmtOrElse(self, f)
130    }
131}
devela/code/result/opt_res/ext_option.rs

devela/code/result/opt_res/
ext_option.rs
