use crate::ops::ControlFlow;

/// `?` 运算符和 `try {}` 块。
///
/// `try_*` 方法通常涉及实现此 trait 的类型。例如，传递给 [`Iterator::try_fold`] 和 [`Iterator::try_for_each`] 的闭包必须返回这样的类型。
///
/// `Try` 类型通常是那些包含两个或更多类别值的类型，其中一些子集通常通过早期返回处理，因此值得提供一个简洁 (但仍然可见) 的语法来简化它。
///
///
/// 这在 [`Result`] 和 [`Option`] 的错误处理中最常见。
/// 这个 trait 的典型实现是在 [`ControlFlow`] 上。
///
/// # 在泛型代码中使用 `Try`
///
/// `Iterator::try_fold` 在 Rust 1.27 中稳定到调用，但是这个 trait 更新了很多。为了说明各种关联类型和方法，让我们实现我们自己的版本。
///
/// 提醒一下，一个可靠的折叠版本看起来像这样:
///
/// ```
/// 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
/// }
/// ```
///
/// 因此，不是 `f` 只返回一个 `A`，我们需要它返回一些在不要短路路径中产生一个 `A` 的其他类型。
/// 方便的是，这也是我们需要从函数返回的类型。
///
/// 让我们为该类型添加一个新的泛型参数 `R`，并将其绑定到我们想要的输出类型:
///
/// ```
/// # #![feature(try_trait_v2)]
/// # use std::ops::Try;
/// 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!()
/// }
/// ```
///
/// 如果我们遍历整个迭代器，我们需要使用 [`Try::from_output`] 将累加器包装成返回类型:
///
/// ```
/// # #![feature(try_trait_v2)]
/// # use std::ops::{ControlFlow, Try};
/// 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)
/// }
/// ```
///
/// 我们还需要 [`FromResidual::from_residual`] 将 residual 恢复为原始类型。但因为它是 `Try` 的一个 super trait，所以我们不必在界限内提及它。
/// 所有实现 `Try` 的类型都可以从它们对应的 residual 中重新创建，所以我们将调用它:
///
/// ```
/// # #![feature(try_trait_v2)]
/// # use std::ops::{ControlFlow, Try};
/// 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)
/// }
/// ```
///
/// 但是这个 "调用`branch`，然后在它上面进行 `match`，如果它是 `Break`，则 `return`" 正是在 `?` 操作符内部发生的事情。因此，我们可以使用 `?` 代替手动完成所有这些操作:
///
/// ```
/// # #![feature(try_trait_v2)]
/// # use std::ops::Try;
/// 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)
/// }
/// ```
///
///
///
///
///
///
///
#[unstable(feature = "try_trait_v2", issue = "84277")]
#[rustc_on_unimplemented(
    on(
        all(from_method = "from_output", from_desugaring = "TryBlock"),
        message = "a `try` block must return `Result` or `Option` \
                    (or another type that implements `{Try}`)",
        label = "could not wrap the final value of the block as `{Self}` doesn't implement `Try`",
    ),
    on(
        all(from_method = "branch", from_desugaring = "QuestionMark"),
        message = "the `?` operator can only be applied to values \
                    that implement `{Try}`",
        label = "the `?` operator cannot be applied to type `{Self}`"
    )
)]
#[doc(alias = "?")]
#[lang = "Try"]
pub trait Try: FromResidual {
    /// 当不短路时，`?` 产生的值的类型。
    #[unstable(feature = "try_trait_v2", issue = "84277")]
    type Output;

    /// 短路时作为 `?` 的一部分传递给 [`FromResidual::from_residual`] 的值的类型。
    ///
    /// 这表示 `Self` 类型的可能值，而不是 `Output` 类型所表示的值。
    ///
    /// # 实现者注意
    ///
    /// 这种类型的选择对于相互转化至关重要。
    /// 与 `Output` 类型不同，它通常是原始泛型类型，这种类型通常是某种类型的 newtype 到 "color" 类型，以便与其他类型的 residual 区别开来。
    ///
    /// 这就是为什么 `Result<T, E>::Residual` 不是 `E`，而是 `Result<Infallible, E>`。
    /// 例如，这样它就不同于 `ControlFlow<E>::Residual`，因此 `ControlFlow` 上的 `?` 不能用于返回 `Result` 的方法中。
    ///
    /// 如果您正在创建实现 `Try<Output = T>` 的泛型 `Foo<T>`，那么通常您可以使用 `Foo<std::convert::Infallible>` 作为它的 `Residual` 类型: 该类型将在正确位置有一个 "hole"，并将保留 residual 的 "foo-ness"，因此其他类型需要选择加入到相互转换中。
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[unstable(feature = "try_trait_v2", issue = "84277")]
    type Residual;

    /// 从它的 `Output` 类型构造类型。
    ///
    /// 这应该与 `branch` 方法一致实现，以便应用 `?` 运算符将返回原始值: `Try::from_output(x).branch() --> ControlFlow::Continue(x)`.
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(try_trait_v2)]
    /// use std::ops::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),
    /// );
    ///
    /// # fn make_question_mark_work() -> Option<()> {
    /// assert_eq!(Option::from_output(4)?, 4);
    /// # None }
    /// # make_question_mark_work();
    ///
    /// // 例如，这用于 `try_fold` 中的累加器:
    /// let r = std::iter::empty().try_fold(4, |_, ()| -> Option<_> { unreachable!() });
    /// assert_eq!(r, Some(4));
    /// ```
    ///
    #[lang = "from_output"]
    #[unstable(feature = "try_trait_v2", issue = "84277")]
    fn from_output(output: Self::Output) -> Self;

    /// 在 `?` 来决定操作符是应该生成一个值 (因为它返回了 [`ControlFlow::Continue`])，还是将一个值传播回调用者(因为它返回了 [`ControlFlow::Break`])。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(try_trait_v2)]
    /// use std::ops::{ControlFlow, 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)),
    /// );
    /// ```
    ///
    ///
    #[lang = "branch"]
    #[unstable(feature = "try_trait_v2", issue = "84277")]
    fn branch(self) -> ControlFlow<Self::Residual, Self::Output>;
}

/// 用于指定哪些残差可以转换为哪些 [`crate::ops::Try`] 类型。
///
/// 每个 `Try` 类型都需要从它自己关联的 `Residual` 类型重新创建，但也可以有额外的 `FromResidual` 实现来支持与其他 `Try` 类型的相互转换。
///
///
#[rustc_on_unimplemented(
    on(
        all(
            from_method = "from_residual",
            from_desugaring = "QuestionMark",
            _Self = "std::result::Result<T, E>",
            R = "std::option::Option<std::convert::Infallible>"
        ),
        message = "the `?` operator can only be used on `Result`s, not `Option`s, \
            in {ItemContext} that returns `Result`",
        label = "use `.ok_or(...)?` to provide an error compatible with `{Self}`",
        enclosing_scope = "this function returns a `Result`"
    ),
    on(
        all(
            from_method = "from_residual",
            from_desugaring = "QuestionMark",
            _Self = "std::result::Result<T, E>",
        ),
        // 在 `?` 中 `From` 的 trait 选择代码中有一条特殊的错误消息，因此对于结果中的错误没有显示，因此它可以比 `ControlFlow` 更强烈地表达。
        //
        //
        message = "the `?` operator can only be used on `Result`s \
            in {ItemContext} that returns `Result`",
        label = "this `?` produces `{R}`, which is incompatible with `{Self}`",
        enclosing_scope = "this function returns a `Result`"
    ),
    on(
        all(
            from_method = "from_residual",
            from_desugaring = "QuestionMark",
            _Self = "std::option::Option<T>",
            R = "std::result::Result<T, E>",
        ),
        message = "the `?` operator can only be used on `Option`s, not `Result`s, \
            in {ItemContext} that returns `Option`",
        label = "use `.ok()?` if you want to discard the `{R}` error information",
        enclosing_scope = "this function returns an `Option`"
    ),
    on(
        all(
            from_method = "from_residual",
            from_desugaring = "QuestionMark",
            _Self = "std::option::Option<T>",
        ),
        // `Option`-in-`Option` 总是有效，因为只有一种可能的残差，所以这也可以用强烈的措辞表达。
        //
        message = "the `?` operator can only be used on `Option`s \
            in {ItemContext} that returns `Option`",
        label = "this `?` produces `{R}`, which is incompatible with `{Self}`",
        enclosing_scope = "this function returns an `Option`"
    ),
    on(
        all(
            from_method = "from_residual",
            from_desugaring = "QuestionMark",
            _Self = "std::ops::ControlFlow<B, C>",
            R = "std::ops::ControlFlow<B, C>",
        ),
        message = "the `?` operator in {ItemContext} that returns `ControlFlow<B, _>` \
            can only be used on other `ControlFlow<B, _>`s (with the same Break type)",
        label = "this `?` produces `{R}`, which is incompatible with `{Self}`",
        enclosing_scope = "this function returns a `ControlFlow`",
        note = "unlike `Result`, there's no `From`-conversion performed for `ControlFlow`"
    ),
    on(
        all(
            from_method = "from_residual",
            from_desugaring = "QuestionMark",
            _Self = "std::ops::ControlFlow<B, C>",
            // `R` 不是 `ControlFlow`，正如前面匹配的那样
        ),
        message = "the `?` operator can only be used on `ControlFlow`s \
            in {ItemContext} that returns `ControlFlow`",
        label = "this `?` produces `{R}`, which is incompatible with `{Self}`",
        enclosing_scope = "this function returns a `ControlFlow`",
    ),
    on(
        all(
            from_method = "from_residual",
            from_desugaring = "QuestionMark"
        ),
        message = "the `?` operator can only be used in {ItemContext} \
                    that returns `Result` or `Option` \
                    (or another type that implements `{FromResidual}`)",
        label = "cannot use the `?` operator in {ItemContext} that returns `{Self}`",
        enclosing_scope = "this function should return `Result` or `Option` to accept `?`"
    ),
)]
#[unstable(feature = "try_trait_v2", issue = "84277")]
pub trait FromResidual<R = <Self as Try>::Residual> {
    /// 从兼容的 `Residual` 类型构造类型。
    ///
    /// 这应该与 `branch` 方法一致地实现，以便应用 `?` 运算符将得到等效的 residual: `FromResidual::from_residual(r).branch() --> ControlFlow::Break(r)`.
    ///
    /// (当涉及到相互转换时，它可能不是一个相同的 residual。)
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(try_trait_v2)]
    /// use std::ops::{ControlFlow, FromResidual};
    ///
    /// assert_eq!(Result::<String, i64>::from_residual(Err(3_u8)), Err(3));
    /// assert_eq!(Option::<String>::from_residual(None), None);
    /// assert_eq!(
    ///     ControlFlow::<_, String>::from_residual(ControlFlow::Break(5)),
    ///     ControlFlow::Break(5),
    /// );
    /// ```
    ///
    #[lang = "from_residual"]
    #[unstable(feature = "try_trait_v2", issue = "84277")]
    fn from_residual(residual: R) -> Self;
}