|
| 1 | +use crate::ops::ControlFlow; |
| 2 | + |
| 3 | +/// The trait used for a variety of operations related to short-circuits, |
| 4 | +/// such as the `?` operator, `try {}` blocks, and `try_*` methods. |
| 5 | +/// |
| 6 | +/// # Using `Try` in Generic Code |
| 7 | +/// |
| 8 | +/// `Iterator::try_fold` was stabilized to call back in Rust 1.27, but |
| 9 | +/// this trait is much newer. To illustrate the various associated types and |
| 10 | +/// methods, let's implement our own version. |
| 11 | +/// |
| 12 | +/// As a reminder, an infallible version of a fold looks something like this: |
| 13 | +/// ``` |
| 14 | +/// fn simple_fold<A, T>( |
| 15 | +/// iter: impl Iterator<Item = T>, |
| 16 | +/// mut accum: A, |
| 17 | +/// mut f: impl FnMut(A, T) -> A, |
| 18 | +/// ) -> A { |
| 19 | +/// for x in iter { |
| 20 | +/// accum = f(accum, x); |
| 21 | +/// } |
| 22 | +/// accum |
| 23 | +/// } |
| 24 | +/// ``` |
| 25 | +/// |
| 26 | +/// So instead of `f` returning just an `A`, we'll need it to return some other |
| 27 | +/// type that produces an `A` in the "don't short circuit" path. Conveniently, |
| 28 | +/// that's also the type we need to return from the function. |
| 29 | +/// |
| 30 | +/// Let's add a new generic parameter `R` for that type, and bound it to the |
| 31 | +/// output type that we want: |
| 32 | +/// ``` |
| 33 | +/// # #![feature(try_trait_v2)] |
| 34 | +/// # #![feature(try_trait_transition)] |
| 35 | +/// # use std::ops::TryV2 as Try; |
| 36 | +/// fn simple_try_fold_1<A, T, R: Try<Output = A>>( |
| 37 | +/// iter: impl Iterator<Item = T>, |
| 38 | +/// mut accum: A, |
| 39 | +/// mut f: impl FnMut(A, T) -> R, |
| 40 | +/// ) -> R { |
| 41 | +/// todo!() |
| 42 | +/// } |
| 43 | +/// ``` |
| 44 | +/// |
| 45 | +/// `Try` is also the trait we need to get the updated accumulator from `f`'s return |
| 46 | +/// value and return the result if we manage to get through the entire iterator: |
| 47 | +/// ``` |
| 48 | +/// # #![feature(try_trait_v2)] |
| 49 | +/// # #![feature(try_trait_transition)] |
| 50 | +/// # #![feature(control_flow_enum)] |
| 51 | +/// # use std::ops::{ControlFlow, TryV2 as Try}; |
| 52 | +/// fn simple_try_fold_2<A, T, R: Try<Output = A>>( |
| 53 | +/// iter: impl Iterator<Item = T>, |
| 54 | +/// mut accum: A, |
| 55 | +/// mut f: impl FnMut(A, T) -> R, |
| 56 | +/// ) -> R { |
| 57 | +/// for x in iter { |
| 58 | +/// let cf = f(accum, x).branch(); |
| 59 | +/// match cf { |
| 60 | +/// ControlFlow::Continue(a) => accum = a, |
| 61 | +/// ControlFlow::Break(_) => todo!(), |
| 62 | +/// } |
| 63 | +/// } |
| 64 | +/// R::from_output(accum) |
| 65 | +/// } |
| 66 | +/// ``` |
| 67 | +/// |
| 68 | +/// We'll also need `FromResidual::from_residual` to turn the residual back into |
| 69 | +/// the original type. But because it's a supertrait of `Try`, we don't need to |
| 70 | +/// mention it in the bounds. All types which implement `Try` can always be |
| 71 | +/// recreated from their corresponding residual, so we'll just call it: |
| 72 | +/// ``` |
| 73 | +/// # #![feature(try_trait_v2)] |
| 74 | +/// # #![feature(try_trait_transition)] |
| 75 | +/// # #![feature(control_flow_enum)] |
| 76 | +/// # use std::ops::{ControlFlow, TryV2 as Try}; |
| 77 | +/// pub fn simple_try_fold_3<A, T, R: Try<Output = A>>( |
| 78 | +/// iter: impl Iterator<Item = T>, |
| 79 | +/// mut accum: A, |
| 80 | +/// mut f: impl FnMut(A, T) -> R, |
| 81 | +/// ) -> R { |
| 82 | +/// for x in iter { |
| 83 | +/// let cf = f(accum, x).branch(); |
| 84 | +/// match cf { |
| 85 | +/// ControlFlow::Continue(a) => accum = a, |
| 86 | +/// ControlFlow::Break(r) => return R::from_residual(r), |
| 87 | +/// } |
| 88 | +/// } |
| 89 | +/// R::from_output(accum) |
| 90 | +/// } |
| 91 | +/// ``` |
| 92 | +/// |
| 93 | +/// But this "call `branch`, then `match` on it, and `return` if it was a |
| 94 | +/// `Break`" is exactly what happens inside the `?` operator. So rather than |
| 95 | +/// do all this manually, we can just use `?` instead: |
| 96 | +/// ```compile_fail (enable again once ? converts to the new trait) |
| 97 | +/// # #![feature(try_trait_v2)] |
| 98 | +/// # #![feature(try_trait_transition)] |
| 99 | +/// # use std::ops::TryV2 as Try; |
| 100 | +/// fn simple_try_fold<A, T, R: Try<Output = A>>( |
| 101 | +/// iter: impl Iterator<Item = T>, |
| 102 | +/// mut accum: A, |
| 103 | +/// mut f: impl FnMut(A, T) -> R, |
| 104 | +/// ) -> R { |
| 105 | +/// for x in iter { |
| 106 | +/// accum = f(accum, x)?; |
| 107 | +/// } |
| 108 | +/// R::from_output(accum) |
| 109 | +/// } |
| 110 | +/// ``` |
| 111 | +#[unstable(feature = "try_trait_v2", issue = "84277")] |
| 112 | +pub trait Try: FromResidual { |
| 113 | + /// The type of the value produced by `?` when *not* short-circuiting. |
| 114 | + #[unstable(feature = "try_trait_v2", issue = "84277")] |
| 115 | + type Output; |
| 116 | + |
| 117 | + /// The type of the value passed to [`FromResidual::from_residual`] |
| 118 | + /// as part of `?` when short-circuiting. |
| 119 | + /// |
| 120 | + /// This represents the possible values of the `Self` type which are *not* |
| 121 | + /// represented by the `Output` type. |
| 122 | + /// |
| 123 | + /// # Note to Implementors |
| 124 | + /// |
| 125 | + /// The choice of this type is critical to interconversion. |
| 126 | + /// Unlike the `Output` type, which will often be a raw generic type, |
| 127 | + /// this type is typically a newtype of some sort to "color" the type |
| 128 | + /// so that it's distinguishable from the residuals of other types. |
| 129 | + /// |
| 130 | + /// This is why `Result<T, E>::Residual` is not `E`, but `Result<Infallible, E>`. |
| 131 | + /// That way it's distinct from `ControlFlow<E>::Residual`, for example, |
| 132 | + /// and thus `?` on `ControlFlow` cannot be used in a method returning `Result`. |
| 133 | + /// |
| 134 | + /// In a type that's generic on a parameter that's used as the `Output` type, |
| 135 | + /// call it `Foo<T> : Try` where `Foo<T>::Output == T`, it's typically easiest |
| 136 | + /// to make the corresponding `Residual` type by filling in that generic |
| 137 | + /// with an uninhabited type: `type Residual = Foo<Infallible>;`. |
| 138 | + #[unstable(feature = "try_trait_v2", issue = "84277")] |
| 139 | + type Residual; |
| 140 | + |
| 141 | + /// Wraps up a value such that `?` on the value will produce the original value. |
| 142 | + /// |
| 143 | + /// # Examples |
| 144 | + /// |
| 145 | + /// ``` |
| 146 | + /// #![feature(try_trait_v2)] |
| 147 | + /// #![feature(control_flow_enum)] |
| 148 | + /// #![feature(try_trait_transition)] |
| 149 | + /// use std::ops::TryV2 as Try; |
| 150 | + /// |
| 151 | + /// assert_eq!(<Result<_, String> as Try>::from_output(3), Ok(3)); |
| 152 | + /// assert_eq!(<Option<_> as Try>::from_output(4), Some(4)); |
| 153 | + /// assert_eq!( |
| 154 | + /// <std::ops::ControlFlow<String, _> as Try>::from_output(5), |
| 155 | + /// std::ops::ControlFlow::Continue(5), |
| 156 | + /// ); |
| 157 | + /// |
| 158 | + /// # fn make_question_mark_work() -> Option<()> { |
| 159 | + /// assert_eq!(Option::from_output(4)?, 4); |
| 160 | + /// # None } |
| 161 | + /// # make_question_mark_work(); |
| 162 | + /// |
| 163 | + /// // This is used, for example, on the accumulator in `try_fold`: |
| 164 | + /// let r = std::iter::empty().try_fold(4, |_, ()| -> Option<_> { unreachable!() }); |
| 165 | + /// assert_eq!(r, Some(4)); |
| 166 | + /// ``` |
| 167 | + #[unstable(feature = "try_trait_v2", issue = "84277")] |
| 168 | + fn from_output(output: Self::Output) -> Self; |
| 169 | + |
| 170 | + /// Used in `?` to decide whether the operator should produce a value |
| 171 | + /// (because this returned [`ControlFlow::Continue`]) |
| 172 | + /// or propagate a value back to the caller |
| 173 | + /// (because this returned [`ControlFlow::Break`]). |
| 174 | + /// |
| 175 | + /// # Examples |
| 176 | + /// |
| 177 | + /// ``` |
| 178 | + /// #![feature(try_trait_v2)] |
| 179 | + /// #![feature(control_flow_enum)] |
| 180 | + /// #![feature(try_trait_transition)] |
| 181 | + /// use std::ops::{ControlFlow, TryV2 as Try}; |
| 182 | + /// |
| 183 | + /// assert_eq!(Ok::<_, String>(3).branch(), ControlFlow::Continue(3)); |
| 184 | + /// assert_eq!(Err::<String, _>(3).branch(), ControlFlow::Break(Err(3))); |
| 185 | + /// |
| 186 | + /// assert_eq!(Some(3).branch(), ControlFlow::Continue(3)); |
| 187 | + /// assert_eq!(None::<String>.branch(), ControlFlow::Break(None)); |
| 188 | + /// |
| 189 | + /// assert_eq!(ControlFlow::<String, _>::Continue(3).branch(), ControlFlow::Continue(3)); |
| 190 | + /// assert_eq!( |
| 191 | + /// ControlFlow::<_, String>::Break(3).branch(), |
| 192 | + /// ControlFlow::Break(ControlFlow::Break(3)), |
| 193 | + /// ); |
| 194 | + /// ``` |
| 195 | + #[unstable(feature = "try_trait_v2", issue = "84277")] |
| 196 | + fn branch(self) -> ControlFlow<Self::Residual, Self::Output>; |
| 197 | +} |
| 198 | + |
| 199 | +/// Used to specify which residuals can be converted into which [`Try`] types. |
| 200 | +/// |
| 201 | +/// Every `Try` type needs to be recreatable from its own associated |
| 202 | +/// `Residual` type, but can also have additional `FromResidual` implementations |
| 203 | +/// to support interconversion with other `Try` types. |
| 204 | +#[unstable(feature = "try_trait_v2", issue = "84277")] |
| 205 | +pub trait FromResidual<R = <Self as Try>::Residual> { |
| 206 | + /// Produces the return value of the function from the residual |
| 207 | + /// when the `?` operator results in an early exit. |
| 208 | + /// |
| 209 | + /// # Examples |
| 210 | + /// |
| 211 | + /// ``` |
| 212 | + /// #![feature(try_trait_v2)] |
| 213 | + /// #![feature(control_flow_enum)] |
| 214 | + /// use std::ops::{ControlFlow, FromResidual}; |
| 215 | + /// |
| 216 | + /// assert_eq!(Result::<String, i64>::from_residual(Err(3_u8)), Err(3)); |
| 217 | + /// assert_eq!(Option::<String>::from_residual(None), None); |
| 218 | + /// assert_eq!( |
| 219 | + /// ControlFlow::<_, String>::from_residual(ControlFlow::Break(5)), |
| 220 | + /// ControlFlow::Break(5), |
| 221 | + /// ); |
| 222 | + /// ``` |
| 223 | + #[unstable(feature = "try_trait_v2", issue = "84277")] |
| 224 | + fn from_residual(residual: R) -> Self; |
| 225 | +} |
0 commit comments