use crate::marker::Tuple;

/// 采用不可变接收者的调用运算符的版本。
///
/// `Fn` 的实例可以在不改变状态的情况下重复调用。
///
/// *请勿将此 trait (`Fn`) 与 [函数指针][function pointers] (`fn`) 混淆。*
///
/// `Fn` 是由闭包自动实现的，闭包只接受对捕获变量的不可变引用或根本不捕获任何东西，以及 (safe) [函数指针][function pointers] (有一些注意事项，请参见他们的文档以获取更多详细信息)。
///
/// 此外，对于实现 `Fn` 的任何类型 `F`，`&F` 也实现了 `Fn`。
///
/// 由于 [`FnMut`] 和 [`FnOnce`] 都是 `Fn` 的 supertraits，因此 `Fn` 的任何实例都可以用作参数，其中需要 [`FnMut`] 或 [`FnOnce`]。
///
/// 当您要接受类似函数类型的参数并且需要反复调用且不改变状态 (例如，同时调用它) 时，请使用 `Fn` 作为绑定。
/// 如果不需要严格的要求，请使用 [`FnMut`] 或 [`FnOnce`] 作为界限。
///
/// 有关此主题的更多信息，请参见 [Rust 编程语言][book] 中关于闭包的章节。
///
/// 还要注意的是 `Fn` traits 的特殊语法 (例如
/// `Fn(usize, bool) -> usize`)。对此技术细节感兴趣的人可以参考 [Rustonomicon 中的相关部分][nomicon]。
///
/// [book]: ../../book/ch13-01-closures.html
/// [function pointers]: fn
/// [nomicon]: ../../nomicon/hrtb.html
///
/// # Examples
///
/// ## 调用一个闭包
///
/// ```
/// let square = |x| x * x;
/// assert_eq!(square(5), 25);
/// ```
///
/// ## 使用 `Fn` 参数
///
/// ```
/// fn call_with_one<F>(func: F) -> usize
///     where F: Fn(usize) -> usize {
///     func(1)
/// }
///
/// let double = |x| x * 2;
/// assert_eq!(call_with_one(double), 2);
/// ```
///
///
///
///
///
///
///
///
///
#[lang = "fn"]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_paren_sugar]
#[rustc_on_unimplemented(
    on(
        Args = "()",
        note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
    ),
    on(
        _Self = "unsafe fn",
        note = "unsafe function cannot be called generically without an unsafe block",
        // SAFETY: tidy 不够聪明，无法判断下面的 unsafe 块是字符串
        label = "call the function in a closure: `|| unsafe {{ /* code */ }}`"
    ),
    message = "expected a `{Fn}<{Args}>` closure, found `{Self}`",
    label = "expected an `Fn<{Args}>` closure, found `{Self}`"
)]
#[fundamental] // 这样 regex 可以依靠 `&str: !FnMut`
#[must_use = "closures are lazy and do nothing unless called"]
#[const_trait]
pub trait Fn<Args: Tuple>: FnMut<Args> {
    /// 执行调用操作。
    #[unstable(feature = "fn_traits", issue = "29625")]
    extern "rust-call" fn call(&self, args: Args) -> Self::Output;
}

/// 采用可变接收者的调用运算符的版本。
///
/// `FnMut` 的实例可以重复调用，并且可以改变状态。
///
/// `FnMut` 是由闭包自动实现的，闭包采用对捕获变量的可变引用，以及实现 [`Fn`] 的所有类型，例如 (safe) [函数指针][function pointers] (因为 `FnMut` 是 [`Fn`] 的 super trait)。
/// 另外，对于任何实现 `FnMut` 的 `F` 类型，`&mut F` 也实现 `FnMut`。
///
/// 由于 [`FnOnce`] 是 `FnMut` 的 super trait，因此可以在期望 [`FnOnce`] 的地方使用 `FnMut` 的任何实例，并且由于 [`Fn`] 是 `FnMut` 的子特性，因此可以在预期 `FnMut` 的地方使用 [`Fn`] 的任何实例。
///
/// 当您想接受类似函数类型的参数并需要反复调用它，同时允许其改变状态时，请使用 `FnMut` 作为绑定。
/// 如果您不希望参数改变状态，请使用 [`Fn`] 作为绑定； 如果不需要重复调用，请使用 [`FnOnce`]。
///
/// 有关此主题的更多信息，请参见 [Rust 编程语言][book] 中关于闭包的章节。
///
/// 还要注意的是 `Fn` traits 的特殊语法 (例如
/// `Fn(usize, bool) -> usize`)。对此技术细节感兴趣的人可以参考 [Rustonomicon 中的相关部分][nomicon]。
///
/// [book]: ../../book/ch13-01-closures.html
/// [function pointers]: fn
/// [nomicon]: ../../nomicon/hrtb.html
///
/// # Examples
///
/// ## 调用可变捕获闭包
///
/// ```
/// let mut x = 5;
/// {
///     let mut square_x = || x *= x;
///     square_x();
/// }
/// assert_eq!(x, 25);
/// ```
///
/// ## 使用 `FnMut` 参数
///
/// ```
/// fn do_twice<F>(mut func: F)
///     where F: FnMut()
/// {
///     func();
///     func();
/// }
///
/// let mut x: usize = 1;
/// {
///     let add_two_to_x = || x += 2;
///     do_twice(add_two_to_x);
/// }
///
/// assert_eq!(x, 5);
/// ```
///
///
///
///
///
///
///
///
///
#[lang = "fn_mut"]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_paren_sugar]
#[rustc_on_unimplemented(
    on(
        Args = "()",
        note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
    ),
    on(
        _Self = "unsafe fn",
        note = "unsafe function cannot be called generically without an unsafe block",
        // SAFETY: tidy 不够聪明，无法判断下面的 unsafe 块是字符串
        label = "call the function in a closure: `|| unsafe {{ /* code */ }}`"
    ),
    message = "expected a `{FnMut}<{Args}>` closure, found `{Self}`",
    label = "expected an `FnMut<{Args}>` closure, found `{Self}`"
)]
#[fundamental] // 这样 regex 可以依靠 `&str: !FnMut`
#[must_use = "closures are lazy and do nothing unless called"]
#[const_trait]
pub trait FnMut<Args: Tuple>: FnOnce<Args> {
    /// 执行调用操作。
    #[unstable(feature = "fn_traits", issue = "29625")]
    extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
}

/// 具有按值接收者的调用运算符的版本。
///
/// 可以调用 `FnOnce` 的实例，但可能无法多次调用。因此，如果唯一知道类型的是它实现 `FnOnce`，则只能调用一次。
///
/// `FnOnce` 由可能消耗捕获的变量的闭包以及所有实现 [`FnMut`] 的类型自动实现，例如 (safe) [函数指针][function pointers] (因为 `FnOnce` 是 [`FnMut`] 的 super trait)。
///
///
/// 由于 [`Fn`] 和 [`FnMut`] 都是 `FnOnce` 的子特性，因此可以在期望使用 `FnOnce` 的情况下使用 [`Fn`] 或 [`FnMut`] 的任何实例。
///
/// 当您想接受类似函数类型的参数并且只需要调用一次时，可以使用 `FnOnce` 作为绑定。
/// 如果需要重复调用该参数，请使用 [`FnMut`] 作为界限； 如果还需要它不改变状态，请使用 [`Fn`]。
///
/// 有关此主题的更多信息，请参见 [Rust 编程语言][book] 中关于闭包的章节。
///
/// 还要注意的是 `Fn` traits 的特殊语法 (例如
/// `Fn(usize, bool) -> usize`)。对此技术细节感兴趣的人可以参考 [Rustonomicon 中的相关部分][nomicon]。
///
/// [book]: ../../book/ch13-01-closures.html
/// [function pointers]: fn
/// [nomicon]: ../../nomicon/hrtb.html
///
/// # Examples
///
/// ## 使用 `FnOnce` 参数
///
/// ```
/// fn consume_with_relish<F>(func: F)
///     where F: FnOnce() -> String
/// {
///     // `func` 消耗其捕获的变量，因此不能多次运行。
/////
///     println!("Consumed: {}", func());
///
///     println!("Delicious!");
///
///     // 再次尝试调用 `func()` 将为 `func` 引发 `use of moved value` 错误。
/////
/// }
///
/// let x = String::from("x");
/// let consume_and_return_x = move || x;
/// consume_with_relish(consume_and_return_x);
///
/// // 此时无法再调用 `consume_and_return_x`
/// ```
///
///
///
///
///
///
///
///
#[lang = "fn_once"]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_paren_sugar]
#[rustc_on_unimplemented(
    on(
        Args = "()",
        note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
    ),
    on(
        _Self = "unsafe fn",
        note = "unsafe function cannot be called generically without an unsafe block",
        // SAFETY: tidy 不够聪明，无法判断下面的 unsafe 块是字符串
        label = "call the function in a closure: `|| unsafe {{ /* code */ }}`"
    ),
    message = "expected a `{FnOnce}<{Args}>` closure, found `{Self}`",
    label = "expected an `FnOnce<{Args}>` closure, found `{Self}`"
)]
#[fundamental] // 这样 regex 可以依靠 `&str: !FnMut`
#[must_use = "closures are lazy and do nothing unless called"]
#[const_trait]
pub trait FnOnce<Args: Tuple> {
    /// 使用调用运算符后的返回类型。
    #[lang = "fn_once_output"]
    #[stable(feature = "fn_once_output", since = "1.12.0")]
    type Output;

    /// 执行调用操作。
    #[unstable(feature = "fn_traits", issue = "29625")]
    extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
}

mod impls {
    use crate::marker::Tuple;

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<A: Tuple, F: ?Sized> Fn<A> for &F
    where
        F: Fn<A>,
    {
        extern "rust-call" fn call(&self, args: A) -> F::Output {
            (**self).call(args)
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<A: Tuple, F: ?Sized> FnMut<A> for &F
    where
        F: Fn<A>,
    {
        extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
            (**self).call(args)
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<A: Tuple, F: ?Sized> FnOnce<A> for &F
    where
        F: Fn<A>,
    {
        type Output = F::Output;

        extern "rust-call" fn call_once(self, args: A) -> F::Output {
            (*self).call(args)
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<A: Tuple, F: ?Sized> FnMut<A> for &mut F
    where
        F: FnMut<A>,
    {
        extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
            (*self).call_mut(args)
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<A: Tuple, F: ?Sized> FnOnce<A> for &mut F
    where
        F: FnMut<A>,
    {
        type Output = F::Output;
        extern "rust-call" fn call_once(self, args: A) -> F::Output {
            (*self).call_mut(args)
        }
    }
}