core/ops/try_trait.rs
1use crate::ops::ControlFlow;
2
3/// The `?` operator and `try {}` blocks.
4///
5/// `try_*` methods typically involve a type implementing this trait. For
6/// example, the closures passed to [`Iterator::try_fold`] and
7/// [`Iterator::try_for_each`] must return such a type.
8///
9/// `Try` types are typically those containing two or more categories of values,
10/// some subset of which are so commonly handled via early returns that it's
11/// worth providing a terse (but still visible) syntax to make that easy.
12///
13/// This is most often seen for error handling with [`Result`] and [`Option`].
14/// The quintessential implementation of this trait is on [`ControlFlow`].
15///
16/// # Using `Try` in Generic Code
17///
18/// `Iterator::try_fold` was stabilized to call back in Rust 1.27, but
19/// this trait is much newer. To illustrate the various associated types and
20/// methods, let's implement our own version.
21///
22/// As a reminder, an infallible version of a fold looks something like this:
23/// ```
24/// fn simple_fold<A, T>(
25/// iter: impl Iterator<Item = T>,
26/// mut accum: A,
27/// mut f: impl FnMut(A, T) -> A,
28/// ) -> A {
29/// for x in iter {
30/// accum = f(accum, x);
31/// }
32/// accum
33/// }
34/// ```
35///
36/// So instead of `f` returning just an `A`, we'll need it to return some other
37/// type that produces an `A` in the "don't short circuit" path. Conveniently,
38/// that's also the type we need to return from the function.
39///
40/// Let's add a new generic parameter `R` for that type, and bound it to the
41/// output type that we want:
42/// ```
43/// # #![feature(try_trait_v2)]
44/// # use std::ops::Try;
45/// fn simple_try_fold_1<A, T, R: Try<Output = A>>(
46/// iter: impl Iterator<Item = T>,
47/// mut accum: A,
48/// mut f: impl FnMut(A, T) -> R,
49/// ) -> R {
50/// todo!()
51/// }
52/// ```
53///
54/// If we get through the entire iterator, we need to wrap up the accumulator
55/// into the return type using [`Try::from_output`]:
56/// ```
57/// # #![feature(try_trait_v2)]
58/// # use std::ops::{ControlFlow, Try};
59/// fn simple_try_fold_2<A, T, R: Try<Output = A>>(
60/// iter: impl Iterator<Item = T>,
61/// mut accum: A,
62/// mut f: impl FnMut(A, T) -> R,
63/// ) -> R {
64/// for x in iter {
65/// let cf = f(accum, x).branch();
66/// match cf {
67/// ControlFlow::Continue(a) => accum = a,
68/// ControlFlow::Break(_) => todo!(),
69/// }
70/// }
71/// R::from_output(accum)
72/// }
73/// ```
74///
75/// We'll also need [`FromResidual::from_residual`] to turn the residual back
76/// into the original type. But because it's a supertrait of `Try`, we don't
77/// need to mention it in the bounds. All types which implement `Try` can be
78/// recreated from their corresponding residual, so we'll just call it:
79/// ```
80/// # #![feature(try_trait_v2)]
81/// # use std::ops::{ControlFlow, Try};
82/// pub fn simple_try_fold_3<A, T, R: Try<Output = A>>(
83/// iter: impl Iterator<Item = T>,
84/// mut accum: A,
85/// mut f: impl FnMut(A, T) -> R,
86/// ) -> R {
87/// for x in iter {
88/// let cf = f(accum, x).branch();
89/// match cf {
90/// ControlFlow::Continue(a) => accum = a,
91/// ControlFlow::Break(r) => return R::from_residual(r),
92/// }
93/// }
94/// R::from_output(accum)
95/// }
96/// ```
97///
98/// But this "call `branch`, then `match` on it, and `return` if it was a
99/// `Break`" is exactly what happens inside the `?` operator. So rather than
100/// do all this manually, we can just use `?` instead:
101/// ```
102/// # #![feature(try_trait_v2)]
103/// # use std::ops::Try;
104/// fn simple_try_fold<A, T, R: Try<Output = A>>(
105/// iter: impl Iterator<Item = T>,
106/// mut accum: A,
107/// mut f: impl FnMut(A, T) -> R,
108/// ) -> R {
109/// for x in iter {
110/// accum = f(accum, x)?;
111/// }
112/// R::from_output(accum)
113/// }
114/// ```
115#[unstable(feature = "try_trait_v2", issue = "84277")]
116#[rustc_on_unimplemented(
117 on(
118 all(from_desugaring = "TryBlock"),
119 message = "a `try` block must return `Result` or `Option` \
120 (or another type that implements `{Try}`)",
121 label = "could not wrap the final value of the block as `{Self}` doesn't implement `Try`",
122 ),
123 on(
124 all(from_desugaring = "QuestionMark"),
125 message = "the `?` operator can only be applied to values that implement `{Try}`",
126 label = "the `?` operator cannot be applied to type `{Self}`"
127 )
128)]
129#[doc(alias = "?")]
130#[lang = "Try"]
131pub trait Try: FromResidual {
132 /// The type of the value produced by `?` when *not* short-circuiting.
133 #[unstable(feature = "try_trait_v2", issue = "84277")]
134 type Output;
135
136 /// The type of the value passed to [`FromResidual::from_residual`]
137 /// as part of `?` when short-circuiting.
138 ///
139 /// This represents the possible values of the `Self` type which are *not*
140 /// represented by the `Output` type.
141 ///
142 /// # Note to Implementors
143 ///
144 /// The choice of this type is critical to interconversion.
145 /// Unlike the `Output` type, which will often be a raw generic type,
146 /// this type is typically a newtype of some sort to "color" the type
147 /// so that it's distinguishable from the residuals of other types.
148 ///
149 /// This is why `Result<T, E>::Residual` is not `E`, but `Result<Infallible, E>`.
150 /// That way it's distinct from `ControlFlow<E>::Residual`, for example,
151 /// and thus `?` on `ControlFlow` cannot be used in a method returning `Result`.
152 ///
153 /// If you're making a generic type `Foo<T>` that implements `Try<Output = T>`,
154 /// then typically you can use `Foo<std::convert::Infallible>` as its `Residual`
155 /// type: that type will have a "hole" in the correct place, and will maintain the
156 /// "foo-ness" of the residual so other types need to opt-in to interconversion.
157 #[unstable(feature = "try_trait_v2", issue = "84277")]
158 type Residual;
159
160 /// Constructs the type from its `Output` type.
161 ///
162 /// This should be implemented consistently with the `branch` method
163 /// such that applying the `?` operator will get back the original value:
164 /// `Try::from_output(x).branch() --> ControlFlow::Continue(x)`.
165 ///
166 /// # Examples
167 ///
168 /// ```
169 /// #![feature(try_trait_v2)]
170 /// use std::ops::Try;
171 ///
172 /// assert_eq!(<Result<_, String> as Try>::from_output(3), Ok(3));
173 /// assert_eq!(<Option<_> as Try>::from_output(4), Some(4));
174 /// assert_eq!(
175 /// <std::ops::ControlFlow<String, _> as Try>::from_output(5),
176 /// std::ops::ControlFlow::Continue(5),
177 /// );
178 ///
179 /// # fn make_question_mark_work() -> Option<()> {
180 /// assert_eq!(Option::from_output(4)?, 4);
181 /// # None }
182 /// # make_question_mark_work();
183 ///
184 /// // This is used, for example, on the accumulator in `try_fold`:
185 /// let r = std::iter::empty().try_fold(4, |_, ()| -> Option<_> { unreachable!() });
186 /// assert_eq!(r, Some(4));
187 /// ```
188 #[lang = "from_output"]
189 #[unstable(feature = "try_trait_v2", issue = "84277")]
190 fn from_output(output: Self::Output) -> Self;
191
192 /// Used in `?` to decide whether the operator should produce a value
193 /// (because this returned [`ControlFlow::Continue`])
194 /// or propagate a value back to the caller
195 /// (because this returned [`ControlFlow::Break`]).
196 ///
197 /// # Examples
198 ///
199 /// ```
200 /// #![feature(try_trait_v2)]
201 /// use std::ops::{ControlFlow, Try};
202 ///
203 /// assert_eq!(Ok::<_, String>(3).branch(), ControlFlow::Continue(3));
204 /// assert_eq!(Err::<String, _>(3).branch(), ControlFlow::Break(Err(3)));
205 ///
206 /// assert_eq!(Some(3).branch(), ControlFlow::Continue(3));
207 /// assert_eq!(None::<String>.branch(), ControlFlow::Break(None));
208 ///
209 /// assert_eq!(ControlFlow::<String, _>::Continue(3).branch(), ControlFlow::Continue(3));
210 /// assert_eq!(
211 /// ControlFlow::<_, String>::Break(3).branch(),
212 /// ControlFlow::Break(ControlFlow::Break(3)),
213 /// );
214 /// ```
215 #[lang = "branch"]
216 #[unstable(feature = "try_trait_v2", issue = "84277")]
217 fn branch(self) -> ControlFlow<Self::Residual, Self::Output>;
218}
219
220/// Used to specify which residuals can be converted into which [`crate::ops::Try`] types.
221///
222/// Every `Try` type needs to be recreatable from its own associated
223/// `Residual` type, but can also have additional `FromResidual` implementations
224/// to support interconversion with other `Try` types.
225#[rustc_on_unimplemented(
226 on(
227 all(
228 from_desugaring = "QuestionMark",
229 _Self = "core::result::Result<T, E>",
230 R = "core::option::Option<core::convert::Infallible>",
231 ),
232 message = "the `?` operator can only be used on `Result`s, not `Option`s, \
233 in {ItemContext} that returns `Result`",
234 label = "use `.ok_or(...)?` to provide an error compatible with `{Self}`",
235 parent_label = "this function returns a `Result`"
236 ),
237 on(
238 all(
239 from_desugaring = "QuestionMark",
240 _Self = "core::result::Result<T, E>",
241 ),
242 // There's a special error message in the trait selection code for
243 // `From` in `?`, so this is not shown for result-in-result errors,
244 // and thus it can be phrased more strongly than `ControlFlow`'s.
245 message = "the `?` operator can only be used on `Result`s \
246 in {ItemContext} that returns `Result`",
247 label = "this `?` produces `{R}`, which is incompatible with `{Self}`",
248 parent_label = "this function returns a `Result`"
249 ),
250 on(
251 all(
252 from_desugaring = "QuestionMark",
253 _Self = "core::option::Option<T>",
254 R = "core::result::Result<T, E>",
255 ),
256 message = "the `?` operator can only be used on `Option`s, not `Result`s, \
257 in {ItemContext} that returns `Option`",
258 label = "use `.ok()?` if you want to discard the `{R}` error information",
259 parent_label = "this function returns an `Option`"
260 ),
261 on(
262 all(
263 from_desugaring = "QuestionMark",
264 _Self = "core::option::Option<T>",
265 ),
266 // `Option`-in-`Option` always works, as there's only one possible
267 // residual, so this can also be phrased strongly.
268 message = "the `?` operator can only be used on `Option`s \
269 in {ItemContext} that returns `Option`",
270 label = "this `?` produces `{R}`, which is incompatible with `{Self}`",
271 parent_label = "this function returns an `Option`"
272 ),
273 on(
274 all(
275 from_desugaring = "QuestionMark",
276 _Self = "core::ops::control_flow::ControlFlow<B, C>",
277 R = "core::ops::control_flow::ControlFlow<B, C>",
278 ),
279 message = "the `?` operator in {ItemContext} that returns `ControlFlow<B, _>` \
280 can only be used on other `ControlFlow<B, _>`s (with the same Break type)",
281 label = "this `?` produces `{R}`, which is incompatible with `{Self}`",
282 parent_label = "this function returns a `ControlFlow`",
283 note = "unlike `Result`, there's no `From`-conversion performed for `ControlFlow`"
284 ),
285 on(
286 all(
287 from_desugaring = "QuestionMark",
288 _Self = "core::ops::control_flow::ControlFlow<B, C>",
289 // `R` is not a `ControlFlow`, as that case was matched previously
290 ),
291 message = "the `?` operator can only be used on `ControlFlow`s \
292 in {ItemContext} that returns `ControlFlow`",
293 label = "this `?` produces `{R}`, which is incompatible with `{Self}`",
294 parent_label = "this function returns a `ControlFlow`",
295 ),
296 on(
297 all(from_desugaring = "QuestionMark"),
298 message = "the `?` operator can only be used in {ItemContext} \
299 that returns `Result` or `Option` \
300 (or another type that implements `{FromResidual}`)",
301 label = "cannot use the `?` operator in {ItemContext} that returns `{Self}`",
302 parent_label = "this function should return `Result` or `Option` to accept `?`"
303 ),
304)]
305#[rustc_diagnostic_item = "FromResidual"]
306#[unstable(feature = "try_trait_v2", issue = "84277")]
307pub trait FromResidual<R = <Self as Try>::Residual> {
308 /// Constructs the type from a compatible `Residual` type.
309 ///
310 /// This should be implemented consistently with the `branch` method such
311 /// that applying the `?` operator will get back an equivalent residual:
312 /// `FromResidual::from_residual(r).branch() --> ControlFlow::Break(r)`.
313 /// (The residual is not mandated to be *identical* when interconversion is involved.)
314 ///
315 /// # Examples
316 ///
317 /// ```
318 /// #![feature(try_trait_v2)]
319 /// use std::ops::{ControlFlow, FromResidual};
320 ///
321 /// assert_eq!(Result::<String, i64>::from_residual(Err(3_u8)), Err(3));
322 /// assert_eq!(Option::<String>::from_residual(None), None);
323 /// assert_eq!(
324 /// ControlFlow::<_, String>::from_residual(ControlFlow::Break(5)),
325 /// ControlFlow::Break(5),
326 /// );
327 /// ```
328 #[lang = "from_residual"]
329 #[unstable(feature = "try_trait_v2", issue = "84277")]
330 fn from_residual(residual: R) -> Self;
331}
332
333#[unstable(
334 feature = "yeet_desugar_details",
335 issue = "none",
336 reason = "just here to simplify the desugaring; will never be stabilized"
337)]
338#[inline]
339#[track_caller] // because `Result::from_residual` has it
340#[lang = "from_yeet"]
341#[allow(unreachable_pub)] // not-exposed but still used via lang-item
342pub fn from_yeet<T, Y>(yeeted: Y) -> T
343where
344 T: FromResidual<Yeet<Y>>,
345{
346 FromResidual::from_residual(Yeet(yeeted))
347}
348
349/// Allows retrieving the canonical type implementing [`Try`] that has this type
350/// as its residual and allows it to hold an `O` as its output.
351///
352/// If you think of the `Try` trait as splitting a type into its [`Try::Output`]
353/// and [`Try::Residual`] components, this allows putting them back together.
354///
355/// For example,
356/// `Result<T, E>: Try<Output = T, Residual = Result<Infallible, E>>`,
357/// and in the other direction,
358/// `<Result<Infallible, E> as Residual<T>>::TryType = Result<T, E>`.
359#[unstable(feature = "try_trait_v2_residual", issue = "91285")]
360pub trait Residual<O> {
361 /// The "return" type of this meta-function.
362 #[unstable(feature = "try_trait_v2_residual", issue = "91285")]
363 type TryType: Try<Output = O, Residual = Self>;
364}
365
366#[unstable(feature = "pub_crate_should_not_need_unstable_attr", issue = "none")]
367#[allow(type_alias_bounds)]
368pub(crate) type ChangeOutputType<T: Try<Residual: Residual<V>>, V> =
369 <T::Residual as Residual<V>>::TryType;
370
371/// An adapter for implementing non-try methods via the `Try` implementation.
372///
373/// Conceptually the same as `Result<T, !>`, but requiring less work in trait
374/// solving and inhabited-ness checking and such, by being an obvious newtype
375/// and not having `From` bounds lying around.
376///
377/// Not currently planned to be exposed publicly, so just `pub(crate)`.
378#[repr(transparent)]
379pub(crate) struct NeverShortCircuit<T>(pub T);
380
381impl<T> NeverShortCircuit<T> {
382 /// Wraps a unary function to produce one that wraps the output into a `NeverShortCircuit`.
383 ///
384 /// This is useful for implementing infallible functions in terms of the `try_` ones,
385 /// without accidentally capturing extra generic parameters in a closure.
386 #[inline]
387 pub(crate) fn wrap_mut_1<A>(
388 mut f: impl FnMut(A) -> T,
389 ) -> impl FnMut(A) -> NeverShortCircuit<T> {
390 move |a| NeverShortCircuit(f(a))
391 }
392
393 #[inline]
394 pub(crate) fn wrap_mut_2<A, B>(mut f: impl FnMut(A, B) -> T) -> impl FnMut(A, B) -> Self {
395 move |a, b| NeverShortCircuit(f(a, b))
396 }
397}
398
399pub(crate) enum NeverShortCircuitResidual {}
400
401impl<T> Try for NeverShortCircuit<T> {
402 type Output = T;
403 type Residual = NeverShortCircuitResidual;
404
405 #[inline]
406 fn branch(self) -> ControlFlow<NeverShortCircuitResidual, T> {
407 ControlFlow::Continue(self.0)
408 }
409
410 #[inline]
411 fn from_output(x: T) -> Self {
412 NeverShortCircuit(x)
413 }
414}
415
416impl<T> FromResidual for NeverShortCircuit<T> {
417 #[inline]
418 fn from_residual(never: NeverShortCircuitResidual) -> Self {
419 match never {}
420 }
421}
422
423impl<T> Residual<T> for NeverShortCircuitResidual {
424 type TryType = NeverShortCircuit<T>;
425}
426
427/// Implement `FromResidual<Yeet<T>>` on your type to enable
428/// `do yeet expr` syntax in functions returning your type.
429#[unstable(feature = "try_trait_v2_yeet", issue = "96374")]
430#[derive(Debug)]
431pub struct Yeet<T>(pub T);