# Trait std::ops::TryV2
[−][src]

    pub trait TryV2: FromResidual<Self::Residual> {
        type Output;
        type Residual;
        pub fn from_output(output: Self::Output) -> Self;
        pub fn branch(self) -> ControlFlow<Self::Residual, Self::Output>;
    }

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

The `?` operator and `try {}` blocks.

`try_*` methods typically involve a type implementing this trait. For example, the closures passed to `Iterator::try_fold` and `Iterator::try_for_each` must return such a type.

`Try` types are typically those containing two or more categories of values, some subset of which are so commonly handled via early returns that it’s worth providing a terse (but still visible) syntax to make that easy.

This is most often seen for error handling with `Result` and `Option`. The quintessential implementation of this trait is on `ControlFlow`.

# Using `Try` in Generic Code

`Iterator::try_fold` was stabilized to call back in Rust 1.27, but this trait is much newer. To illustrate the various associated types and methods, let’s implement our own version.

As a reminder, an infallible version of a fold looks something like this:

    fn simple_fold<A, T>(
        iter: impl Iterator<Item = T>,
        mut accum: A,
        mut f: impl FnMut(A, T) -> A,
    ) -> A {
        for x in iter {
            accum = f(accum, x);
        }
        accum
    }

Run

So instead of `f` returning just an `A`, we’ll need it to return some other type that produces an `A` in the “don’t short circuit” path. Conveniently, that’s also the type we need to return from the function.

Let’s add a new generic parameter `R` for that type, and bound it to the output type that we want:

    fn simple_try_fold_1<A, T, R: Try<Output = A>>(
        iter: impl Iterator<Item = T>,
        mut accum: A,
        mut f: impl FnMut(A, T) -> R,
    ) -> R {
        todo!()
    }

Run

If we get through the entire iterator, we need to wrap up the accumulator into the return type using `Try::from_output`:

    fn simple_try_fold_2<A, T, R: Try<Output = A>>(
        iter: impl Iterator<Item = T>,
        mut accum: A,
        mut f: impl FnMut(A, T) -> R,
    ) -> R {
        for x in iter {
            let cf = f(accum, x).branch();
            match cf {
                ControlFlow::Continue(a) => accum = a,
                ControlFlow::Break(_) => todo!(),
            }
        }
        R::from_output(accum)
    }

Run

We’ll also need `FromResidual::from_residual` to turn the residual back into the original type. But because it’s a supertrait of `Try`, we don’t need to mention it in the bounds. All types which implement `Try` can be recreated from their corresponding residual, so we’ll just call it:

    pub fn simple_try_fold_3<A, T, R: Try<Output = A>>(
        iter: impl Iterator<Item = T>,
        mut accum: A,
        mut f: impl FnMut(A, T) -> R,
    ) -> R {
        for x in iter {
            let cf = f(accum, x).branch();
            match cf {
                ControlFlow::Continue(a) => accum = a,
                ControlFlow::Break(r) => return R::from_residual(r),
            }
        }
        R::from_output(accum)
    }

Run

But this “call `branch`, then `match` on it, and `return` if it was a `Break`” is exactly what happens inside the `?` operator. So rather than do all this manually, we can just use `?` instead:

ⓘ

    fn simple_try_fold<A, T, R: Try<Output = A>>(
        iter: impl Iterator<Item = T>,
        mut accum: A,
        mut f: impl FnMut(A, T) -> R,
    ) -> R {
        for x in iter {
            accum = f(accum, x)?;
        }
        R::from_output(accum)
    }

Run

## Associated Types

### `type Output`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

The type of the value produced by `?` when not short-circuiting.

### `type Residual`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

The type of the value passed to `FromResidual::from_residual` as part of `?` when short-circuiting.

This represents the possible values of the `Self` type which are not represented by the `Output` type.

# Note to Implementors

The choice of this type is critical to interconversion. Unlike the `Output` type, which will often be a raw generic type, this type is typically a newtype of some sort to “color” the type so that it’s distinguishable from the residuals of other types.

This is why `Result<T, E>::Residual` is not `E`, but `Result<Infallible, E>`. That way it’s distinct from `ControlFlow<E>::Residual`, for example, and thus `?` on `ControlFlow` cannot be used in a method returning `Result`.

If you’re making a generic type `Foo<T>` that implements `Try<Output = T>`, then typically you can use `Foo<std::convert::Infallible>` as its `Residual` type: that type will have a “hole” in the correct place, and will maintain the “foo-ness” of the residual so other types need to opt-in to interconversion.

Loading content...

## Required methods

### `pub fn from_output(output: Self::Output) -> Self`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

Constructs the type from its `Output` type.

This should be implemented consistently with the `branch` method such that applying the `?` operator will get back the original value: `Try::from_output(x).branch() --> ControlFlow::Continue(x)`.

# Examples

    #![feature(try_trait_v2)]
    #![feature(control_flow_enum)]
    #![feature(try_trait_transition)]
    use std::ops::TryV2 as Try;

    assert_eq!(<Result<_, String> as Try>::from_output(3), Ok(3));
    assert_eq!(<Option<_> as Try>::from_output(4), Some(4));
    assert_eq!(
        <std::ops::ControlFlow<String, _> as Try>::from_output(5),
        std::ops::ControlFlow::Continue(5),
    );

    assert_eq!(Option::from_output(4)?, 4);

    // This is used, for example, on the accumulator in `try_fold`:
    let r = std::iter::empty().try_fold(4, |_, ()| -> Option<_> { unreachable!() });
    assert_eq!(r, Some(4));

Run

### `pub fn branch(self) -> ControlFlow<Self::Residual, Self::Output>`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

Used in `?` to decide whether the operator should produce a value (because this returned `ControlFlow::Continue`) or propagate a value back to the caller (because this returned `ControlFlow::Break`).

# Examples

    #![feature(try_trait_v2)]
    #![feature(control_flow_enum)]
    #![feature(try_trait_transition)]
    use std::ops::{ControlFlow, TryV2 as Try};

    assert_eq!(Ok::<_, String>(3).branch(), ControlFlow::Continue(3));
    assert_eq!(Err::<String, _>(3).branch(), ControlFlow::Break(Err(3)));

    assert_eq!(Some(3).branch(), ControlFlow::Continue(3));
    assert_eq!(None::<String>.branch(), ControlFlow::Break(None));

    assert_eq!(ControlFlow::<String, _>::Continue(3).branch(), ControlFlow::Continue(3));
    assert_eq!(
        ControlFlow::<_, String>::Break(3).branch(),
        ControlFlow::Break(ControlFlow::Break(3)),
    );

Run
Loading content...

## Implementors

### `impl<B, C> Try for ControlFlow<B, C>`[src]

#### `type Output = C`

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `type Residual = ControlFlow<B, Infallible>`

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `pub fn from_output(
output: <ControlFlow<B, C> as Try>::Output
) -> ControlFlow<B, C>`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `pub fn branch(
self
) -> ControlFlow<<ControlFlow<B, C> as Try>::Residual, <ControlFlow<B, C> as Try>::Output>`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

### `impl<T> Try for Option<T>`[src]

#### `type Output = T`

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `type Residual = Option<Infallible>`

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `pub fn from_output(output: <Option<T> as Try>::Output) -> Option<T>`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `pub fn branch(
self
) -> ControlFlow<<Option<T> as Try>::Residual, <Option<T> as Try>::Output>`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

### `impl<T, E> Try for Result<T, E>`[src]

#### `type Output = T`

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `type Residual = Result<Infallible, E>`

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `pub fn from_output(output: <Result<T, E> as Try>::Output) -> Result<T, E>`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `pub fn branch(
self
) -> ControlFlow<<Result<T, E> as Try>::Residual, <Result<T, E> as Try>::Output>`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

### `impl<T, E> Try for Poll<Option<Result<T, E>>>`[src]

#### `type Output = Poll<Option<T>>`

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `type Residual = Result<Infallible, E>`

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `pub fn from_output(
c: <Poll<Option<Result<T, E>>> as Try>::Output
) -> Poll<Option<Result<T, E>>>`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `pub fn branch(
self
) -> ControlFlow<<Poll<Option<Result<T, E>>> as Try>::Residual, <Poll<Option<Result<T, E>>> as Try>::Output>`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

### `impl<T, E> Try for Poll<Result<T, E>>`[src]

#### `type Output = Poll<T>`

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `type Residual = Result<Infallible, E>`

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `pub fn from_output(c: <Poll<Result<T, E>> as Try>::Output) -> Poll<Result<T, E>>`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)

#### `pub fn branch(
self
) -> ControlFlow<<Poll<Result<T, E>> as Try>::Residual, <Poll<Result<T, E>> as Try>::Output>`[src]

🔬 This is a nightly-only experimental API. (`try_trait_v2` #84277)
Loading content...