use crate::future::Future;

/// 转换为 `Future`。
///
/// 通过为类型实现 `IntoFuture`，您可以定义如何将其转换为 future。
///
/// # `.await` 脱糖
///
/// 在轮询 future 完成之前，`.await` 关键字首先脱糖到 `IntoFuture::into_future` 的调用中。
/// `IntoFuture` 适用于所有 `T: Future`，这意味着 `into_future` 方法将适用于所有 futures。
///
/// ```no_run
/// use std::future::IntoFuture;
///
/// # async fn foo() {
/// let v = async { "meow" };
/// let mut fut = v.into_future();
/// assert_eq!("meow", fut.await);
/// # }
/// ```
///
/// # 异步构建器
///
/// 当手动实现 futures 时，通常会在为一个类型实现 `Future` 或 `IntoFuture` 之间做出选择。
/// 在大多数情况下，实现 `Future` 是一个不错的选择。
/// 但是在实现 "async builder" 类型时实现 `IntoFuture` 是最有用的，它允许在被 `.await` 编辑之前多次修改它们的值。
///
/// ```rust
/// use std::future::{ready, Ready, IntoFuture};
///
/// /// 最终将两个数字相乘
/// pub struct Multiply {
///     num: u16,
///     factor: u16,
/// }
///
/// impl Multiply {
///     /// 创建一个新的 `Multiply` 实例。
///     pub fn new(num: u16, factor: u16) -> Self {
///         Self { num, factor }
///     }
///
///     /// 设置要乘以因子的数字。
///     pub fn number(mut self, num: u16) -> Self {
///         self.num = num;
///         self
///     }
///
///     /// 设置要与数字相乘的因子。
///     pub fn factor(mut self, factor: u16) -> Self {
///         self.factor = factor;
///         self
///     }
/// }
///
/// impl IntoFuture for Multiply {
///     type Output = u16;
///     type IntoFuture = Ready<Self::Output>;
///
///     fn into_future(self) -> Self::IntoFuture {
///         ready(self.num * self.factor)
///     }
/// }
///
/// // NOTE: Rust 还没有 `async fn main` 函数，该功能目前仅存在于生态系统中。
/////
/// async fn run() {
///     let num = Multiply::new(0, 0)  // 将构建器初始化为数字: 0，因子: 0
///         .number(2)                 // 将数字更改为 2
///         .factor(2)                 // 将因子更改为 2
///         .await;                    // 转换为 future 和 .await
///
///     assert_eq!(num, 4);
/// }
/// ```
///
/// # trait bounds 中的用法
///
/// 在 trait 中使用 `IntoFuture` bounds 允许函数在 `Future` 和 `IntoFuture` 上都是泛型。
/// 这对函数的用户来说很方便，所以当他们使用它时，他们不必对 `IntoFuture::into_future` 进行额外的调用来获取 `Future` 的实例:
///
///
/// ```rust
/// use std::future::IntoFuture;
///
/// /// 将 future 的输出转换为字符串。
/// async fn fut_to_string<Fut>(fut: Fut) -> String
/// where
///     Fut: IntoFuture,
///     Fut::Output: std::fmt::Debug,
/// {
///     format!("{:?}", fut.await)
/// }
/// ```
///
///
///
///
///
///
#[stable(feature = "into_future", since = "1.64.0")]
#[rustc_diagnostic_item = "IntoFuture"]
pub trait IntoFuture {
    /// future 完成时将产生的输出。
    #[stable(feature = "into_future", since = "1.64.0")]
    type Output;

    /// 我们要把它变成哪种 future?
    #[stable(feature = "into_future", since = "1.64.0")]
    type IntoFuture: Future<Output = Self::Output>;

    /// 根据一个值创建一个 future。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```no_run
    /// use std::future::IntoFuture;
    ///
    /// # async fn foo() {
    /// let v = async { "meow" };
    /// let mut fut = v.into_future();
    /// assert_eq!("meow", fut.await);
    /// # }
    /// ```
    #[stable(feature = "into_future", since = "1.64.0")]
    #[lang = "into_future"]
    fn into_future(self) -> Self::IntoFuture;
}

#[stable(feature = "into_future", since = "1.64.0")]
impl<F: Future> IntoFuture for F {
    type Output = F::Output;
    type IntoFuture = F;

    fn into_future(self) -> Self::IntoFuture {
        self
    }
}