//! 用于动态类型或类型反射的实用工具。
//!
//! # `Any` 和 `TypeId`
//!
//! `Any` 本身可以用来得到一个 `TypeId`，当用作 trait 对象时，它有更多的特性。
//! 作为 `&dyn Any` (借用的 trait 对象)，它具有 `is` 和 `downcast_ref` 方法，以测试所包含的值是否为给定类型，并对该类型的内部值进行引用。
//! 作为 `&mut dyn Any`，还有 `downcast_mut` 方法，用于获取内部值的变量引用。
//! `Box<dyn Any>` 添加了 `downcast` 方法，该方法尝试转换为 `Box<T>`。
//! 有关完整的详细信息，请参见 [`Box`] 文档。
//!
//! 请注意，`&dyn Any` 仅限于测试值是否为指定的具体类型，而不能用于测试某个类型是否实现 trait。
//!
//! [`Box`]: ../../std/boxed/struct.Box.html
//!
//! # 智能指针和 `dyn Any`
//!
//! 将 `Any` 用作 trait 对象时要记住的一种行为，尤其是对于 `Box<dyn Any>` 或 `Arc<dyn Any>` 之类的类型，只需在值上调用 `.type_id()` 即可生成容器的 `TypeId`，而不是底层 trait 对象。
//!
//! 可以通过将智能指针转换为 `&dyn Any` 来避免，这将返回对象的 `TypeId`。
//! 例如：
//!
//! ```
//! use std::any::{Any, TypeId};
//!
//! let boxed: Box<dyn Any> = Box::new(3_i32);
//!
//! // 您更可能希望这样做：
//! let actual_id = (&*boxed).type_id();
//! // ... 比这个：
//! let boxed_id = boxed.type_id();
//!
//! assert_eq!(actual_id, TypeId::of::<i32>());
//! assert_eq!(boxed_id, TypeId::of::<Box<dyn Any>>());
//! ```
//!
//! ## Examples
//!
//! 考虑一下我们要注销传递给函数的值的情况。
//! 我们知道我们正在实现的值实现了 Debug，但是我们不知道它的具体类型。我们要对某些类型进行特殊处理：在这种情况下，应先打印 String 值的长度，然后再打印它们的值。
//! 我们在编译时不知道我们值的具体类型，因此我们需要使用运行时反射。
//!
//! ```rust
//! use std::fmt::Debug;
//! use std::any::Any;
//!
//! // 用于实现 Debug 的任何类型的 Logger 函数。
//! fn log<T: Any + Debug>(value: &T) {
//!     let value_any = value as &dyn Any;
//!
//!     // 尝试将我们的值转换为 `String`。
//!     // 如果成功，我们希望输出 String 的长度及其值。
//!     // 如果不是，那就是另一种类型：只需将其打印出来即可。
//!     match value_any.downcast_ref::<String>() {
//!         Some(as_string) => {
//!             println!("String ({}): {}", as_string.len(), as_string);
//!         }
//!         None => {
//!             println!("{value:?}");
//!         }
//!     }
//! }
//!
//! // 该函数要先注销其参数，然后再使用它。
//! fn do_work<T: Any + Debug>(value: &T) {
//!     log(value);
//!     // ...做一些其他的工作
//! }
//!
//! fn main() {
//!     let my_string = "Hello World".to_string();
//!     do_work(&my_string);
//!
//!     let my_i8: i8 = 100;
//!     do_work(&my_i8);
//! }
//! ```
//!
//! # `Provider` 和 `Demand`
//!
//! `Provider` 和相关的 API 支持泛型、类型驱动的数据访问，以及实现者提供此类数据的机制。
//! 该接口的关键部分是用于提供数据的对象的 `Provider` trait，以及用于从实现 `Provider` 的对象请求数据的 [`request_value`] 和 [`request_ref`] 函数。
//! 通常，最终用户不应该直接调用 `request_*`，它们是中间实现者用来实现面向用户的接口的辅助函数。
//! 这纯粹是为了人体工程学，这里没有安全问题; 中间实现者通常可以支持方法而不是 free 函数，并使用更具体的名称。
//!
//! 通常，数据提供者是扩展 `Provider` 的 trait 的 trait 对象。用户将通过指定数据的类型从 trait 对象请求数据。
//!
//! ## 数据流
//!
//! * 用户请求特定类型的对象，该对象委托给 `request_value` 或 `request_ref`
//! * `request_*` 创建一个 `Demand` 对象并将其传递给 `Provider::provide`
//! * `Provider::provide` 的数据提供者实现尝试使用 `Demand::provide_*` 提供不同类型的值。如果类型与用户请求的类型匹配，则该值将存储在 `Demand` 对象中。
//! * `request_*` 解包 `Demand` 对象并将任何存储的值返回给用户。
//!
//! ## Examples
//!
//! ```
//! # #![feature(provide_any)]
//! use std::any::{Provider, Demand, request_ref};
//!
//! // MyTrait 的定义，一个数据提供者。
//! trait MyTrait: Provider {
//!     // ...
//! }
//!
//! // `MyTrait` trait 对象的方法。
//! impl dyn MyTrait + '_ {
//!     /// 获取对实现结构体的字段的引用。
//!     pub fn get_context_by_ref<T: ?Sized + 'static>(&self) -> Option<&T> {
//!         request_ref::<T>(self)
//!     }
//! }
//!
//! // `MyTrait` 和 `Provider` 的下游实现。
//! # struct SomeConcreteType { some_string: String }
//! impl MyTrait for SomeConcreteType {
//!     // ...
//! }
//!
//! impl Provider for SomeConcreteType {
//!     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
//!         // 提供一个字符串引用。
//!         // 我们可以在这里提供不同类型的多个值。
//!         demand.provide_ref::<String>(&self.some_string);
//!     }
//! }
//!
//! // `MyTrait` 的下游用法。
//! fn use_my_trait(obj: &dyn MyTrait) {
//!     // 向 obj 请求 &String。
//!     let _ = obj.get_context_by_ref::<String>().unwrap();
//! }
//! ```
//!
//! 在这个例子中，如果 `use_my_trait` 中 `obj` 的具体类型是 `SomeConcreteType`，那么 `get_context_by_ref` 调用将返回一个引用给 `&String` 类型的 `obj.some_string`。
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

#![stable(feature = "rust1", since = "1.0.0")]

use crate::fmt;
use crate::intrinsics;

///////////////////////////////////////////////////////////////////////////////
// 任何 trait
///////////////////////////////////////////////////////////////////////////////

/// 一个用来模拟动态类型的 trait。
///
/// 大多数类型都实现了 `Any`。但是，任何包含非 `static' 引用的类型都不会。
/// 有关更多详细信息，请参见 [模块级文档][mod]。
///
/// [mod]: crate::any
// 这个 trait 并不是不安全的，尽管我们依靠不安全代码 (例如 `downcast`) 中唯一的 impl 的 `type_id` 函数的细节。通常，这将是一个问题，但是由于 `Any` 的唯一含义是全面实现，因此没有其他代码可以实现 `Any`。
//
// 我们可以合理地使此 trait 不安全 - 因为我们控制所有实现，因此不会造成破坏 - 但我们选择不这样做，因为这既不是真正必要的，并且可能使用户混淆不安全的 traits 和不安全的方法 (即，`type_id` 仍然可以安全调用，但我们可能希望在文档中对此进行说明。
//
//
//
//
//
//
//
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "Any")]
pub trait Any: 'static {
    /// 获取 `self` 的 `TypeId`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::{Any, TypeId};
    ///
    /// fn is_string(s: &dyn Any) -> bool {
    ///     TypeId::of::<String>() == s.type_id()
    /// }
    ///
    /// assert_eq!(is_string(&0), false);
    /// assert_eq!(is_string(&"cookie monster".to_string()), true);
    /// ```
    #[stable(feature = "get_type_id", since = "1.34.0")]
    fn type_id(&self) -> TypeId;
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: 'static + ?Sized> Any for T {
    fn type_id(&self) -> TypeId {
        TypeId::of::<T>()
    }
}

///////////////////////////////////////////////////////////////////////////////
// 任何 trait 对象的扩展方法。
///////////////////////////////////////////////////////////////////////////////

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Debug for dyn Any {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Any").finish_non_exhaustive()
    }
}

// 确保可以打印出例如连接螺纹的结果，并因此可以与 `unwrap` 一起使用。
// 如果调度与向上转换一起使用，则最终可能不再需要。
//
#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Debug for dyn Any + Send {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Any").finish_non_exhaustive()
    }
}

#[stable(feature = "any_send_sync_methods", since = "1.28.0")]
impl fmt::Debug for dyn Any + Send + Sync {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Any").finish_non_exhaustive()
    }
}

impl dyn Any {
    /// 如果内部类型与 `T` 相同，则返回 `true`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn is_string(s: &dyn Any) {
    ///     if s.is::<String>() {
    ///         println!("It's a string!");
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// is_string(&0);
    /// is_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn is<T: Any>(&self) -> bool {
        // 获取实例化此函数的类型的 `TypeId`。
        let t = TypeId::of::<T>();

        // 在 trait 对象 (`self`) 中获取该类型的 `TypeId`。
        let concrete = self.type_id();

        // 比较两个 `TypeId` 的相等性。
        t == concrete
    }

    /// 如果内部值的类型为 `T` 类型，则返回一些对内部值的引用，如果不是，则返回 `None`。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn print_if_string(s: &dyn Any) {
    ///     if let Some(string) = s.downcast_ref::<String>() {
    ///         println!("It's a string({}): '{}'", string.len(), string);
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// print_if_string(&0);
    /// print_if_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn downcast_ref<T: Any>(&self) -> Option<&T> {
        if self.is::<T>() {
            // SAFETY: 只需检查我们是否指向正确的类型，就可以依靠该检查来检查内存安全性，因为我们对所有类型都实现了 Any； 没有其他迹象可能会存在，因为它们会与我们的迹象发生冲突。
            //
            //
            unsafe { Some(self.downcast_ref_unchecked()) }
        } else {
            None
        }
    }

    /// 如果内部值的类型为 `T` 类型，则返回一些对内部值的引用，如果不是，则返回 `None`。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn modify_if_u32(s: &mut dyn Any) {
    ///     if let Some(num) = s.downcast_mut::<u32>() {
    ///         *num = 42;
    ///     }
    /// }
    ///
    /// let mut x = 10u32;
    /// let mut s = "starlord".to_string();
    ///
    /// modify_if_u32(&mut x);
    /// modify_if_u32(&mut s);
    ///
    /// assert_eq!(x, 42);
    /// assert_eq!(&s, "starlord");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn downcast_mut<T: Any>(&mut self) -> Option<&mut T> {
        if self.is::<T>() {
            // SAFETY: 只需检查我们是否指向正确的类型，就可以依靠该检查来检查内存安全性，因为我们对所有类型都实现了 Any； 没有其他迹象可能会存在，因为它们会与我们的迹象发生冲突。
            //
            //
            unsafe { Some(self.downcast_mut_unchecked()) }
        } else {
            None
        }
    }

    /// 返回对内部值的引用，类型为 `dyn T`。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(downcast_unchecked)]
    ///
    /// use std::any::Any;
    ///
    /// let x: Box<dyn Any> = Box::new(1_usize);
    ///
    /// unsafe {
    ///     assert_eq!(*x.downcast_ref_unchecked::<usize>(), 1);
    /// }
    /// ```
    ///
    /// # Safety
    ///
    /// 包含的值必须是 `T` 类型。
    /// 使用不正确的类型调用此方法是 *未定义的行为*。
    #[unstable(feature = "downcast_unchecked", issue = "90850")]
    #[inline]
    pub unsafe fn downcast_ref_unchecked<T: Any>(&self) -> &T {
        debug_assert!(self.is::<T>());
        // SAFETY: 调用者保证 T 是正确的类型
        unsafe { &*(self as *const dyn Any as *const T) }
    }

    /// 返回对内部值的可变引用，类型为 `dyn T`
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(downcast_unchecked)]
    ///
    /// use std::any::Any;
    ///
    /// let mut x: Box<dyn Any> = Box::new(1_usize);
    ///
    /// unsafe {
    ///     *x.downcast_mut_unchecked::<usize>() += 1;
    /// }
    ///
    /// assert_eq!(*x.downcast_ref::<usize>().unwrap(), 2);
    /// ```
    ///
    /// # Safety
    ///
    /// 包含的值必须是 `T` 类型。
    /// 使用不正确的类型调用此方法是 *未定义的行为*。
    #[unstable(feature = "downcast_unchecked", issue = "90850")]
    #[inline]
    pub unsafe fn downcast_mut_unchecked<T: Any>(&mut self) -> &mut T {
        debug_assert!(self.is::<T>());
        // SAFETY: 调用者保证 T 是正确的类型
        unsafe { &mut *(self as *mut dyn Any as *mut T) }
    }
}

impl dyn Any + Send {
    /// 转发到在类型 `dyn Any` 上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn is_string(s: &(dyn Any + Send)) {
    ///     if s.is::<String>() {
    ///         println!("It's a string!");
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// is_string(&0);
    /// is_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn is<T: Any>(&self) -> bool {
        <dyn Any>::is::<T>(self)
    }

    /// 转发到在类型 `dyn Any` 上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn print_if_string(s: &(dyn Any + Send)) {
    ///     if let Some(string) = s.downcast_ref::<String>() {
    ///         println!("It's a string({}): '{}'", string.len(), string);
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// print_if_string(&0);
    /// print_if_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn downcast_ref<T: Any>(&self) -> Option<&T> {
        <dyn Any>::downcast_ref::<T>(self)
    }

    /// 转发到在类型 `dyn Any` 上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn modify_if_u32(s: &mut (dyn Any + Send)) {
    ///     if let Some(num) = s.downcast_mut::<u32>() {
    ///         *num = 42;
    ///     }
    /// }
    ///
    /// let mut x = 10u32;
    /// let mut s = "starlord".to_string();
    ///
    /// modify_if_u32(&mut x);
    /// modify_if_u32(&mut s);
    ///
    /// assert_eq!(x, 42);
    /// assert_eq!(&s, "starlord");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn downcast_mut<T: Any>(&mut self) -> Option<&mut T> {
        <dyn Any>::downcast_mut::<T>(self)
    }

    /// 转发到在类型 `dyn Any` 上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(downcast_unchecked)]
    ///
    /// use std::any::Any;
    ///
    /// let x: Box<dyn Any> = Box::new(1_usize);
    ///
    /// unsafe {
    ///     assert_eq!(*x.downcast_ref_unchecked::<usize>(), 1);
    /// }
    /// ```
    ///
    /// # Safety
    ///
    /// 与 `dyn Any` 类型上的方法相同。
    #[unstable(feature = "downcast_unchecked", issue = "90850")]
    #[inline]
    pub unsafe fn downcast_ref_unchecked<T: Any>(&self) -> &T {
        // SAFETY: 由调用者保证
        unsafe { <dyn Any>::downcast_ref_unchecked::<T>(self) }
    }

    /// 转发到在类型 `dyn Any` 上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(downcast_unchecked)]
    ///
    /// use std::any::Any;
    ///
    /// let mut x: Box<dyn Any> = Box::new(1_usize);
    ///
    /// unsafe {
    ///     *x.downcast_mut_unchecked::<usize>() += 1;
    /// }
    ///
    /// assert_eq!(*x.downcast_ref::<usize>().unwrap(), 2);
    /// ```
    ///
    /// # Safety
    ///
    /// 与 `dyn Any` 类型上的方法相同。
    #[unstable(feature = "downcast_unchecked", issue = "90850")]
    #[inline]
    pub unsafe fn downcast_mut_unchecked<T: Any>(&mut self) -> &mut T {
        // SAFETY: 由调用者保证
        unsafe { <dyn Any>::downcast_mut_unchecked::<T>(self) }
    }
}

impl dyn Any + Send + Sync {
    /// 转发到在 `Any` 类型上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn is_string(s: &(dyn Any + Send + Sync)) {
    ///     if s.is::<String>() {
    ///         println!("It's a string!");
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// is_string(&0);
    /// is_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "any_send_sync_methods", since = "1.28.0")]
    #[inline]
    pub fn is<T: Any>(&self) -> bool {
        <dyn Any>::is::<T>(self)
    }

    /// 转发到在 `Any` 类型上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn print_if_string(s: &(dyn Any + Send + Sync)) {
    ///     if let Some(string) = s.downcast_ref::<String>() {
    ///         println!("It's a string({}): '{}'", string.len(), string);
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// print_if_string(&0);
    /// print_if_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "any_send_sync_methods", since = "1.28.0")]
    #[inline]
    pub fn downcast_ref<T: Any>(&self) -> Option<&T> {
        <dyn Any>::downcast_ref::<T>(self)
    }

    /// 转发到在 `Any` 类型上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn modify_if_u32(s: &mut (dyn Any + Send + Sync)) {
    ///     if let Some(num) = s.downcast_mut::<u32>() {
    ///         *num = 42;
    ///     }
    /// }
    ///
    /// let mut x = 10u32;
    /// let mut s = "starlord".to_string();
    ///
    /// modify_if_u32(&mut x);
    /// modify_if_u32(&mut s);
    ///
    /// assert_eq!(x, 42);
    /// assert_eq!(&s, "starlord");
    /// ```
    #[stable(feature = "any_send_sync_methods", since = "1.28.0")]
    #[inline]
    pub fn downcast_mut<T: Any>(&mut self) -> Option<&mut T> {
        <dyn Any>::downcast_mut::<T>(self)
    }

    /// 转发到在 `Any` 类型上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(downcast_unchecked)]
    ///
    /// use std::any::Any;
    ///
    /// let x: Box<dyn Any> = Box::new(1_usize);
    ///
    /// unsafe {
    ///     assert_eq!(*x.downcast_ref_unchecked::<usize>(), 1);
    /// }
    /// ```
    #[unstable(feature = "downcast_unchecked", issue = "90850")]
    #[inline]
    pub unsafe fn downcast_ref_unchecked<T: Any>(&self) -> &T {
        // SAFETY: 由调用者保证
        unsafe { <dyn Any>::downcast_ref_unchecked::<T>(self) }
    }

    /// 转发到在 `Any` 类型上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(downcast_unchecked)]
    ///
    /// use std::any::Any;
    ///
    /// let mut x: Box<dyn Any> = Box::new(1_usize);
    ///
    /// unsafe {
    ///     *x.downcast_mut_unchecked::<usize>() += 1;
    /// }
    ///
    /// assert_eq!(*x.downcast_ref::<usize>().unwrap(), 2);
    /// ```
    #[unstable(feature = "downcast_unchecked", issue = "90850")]
    #[inline]
    pub unsafe fn downcast_mut_unchecked<T: Any>(&mut self) -> &mut T {
        // SAFETY: 由调用者保证
        unsafe { <dyn Any>::downcast_mut_unchecked::<T>(self) }
    }
}

///////////////////////////////////////////////////////////////////////////////
// TypeID 及其方法
///////////////////////////////////////////////////////////////////////////////

/// `TypeId` 代表类型的全局唯一标识符。
///
/// 每个 `TypeId` 是不透明的对象，它不允许检查内部内容，但可以进行基本操作，例如克隆，比较，打印和显示。
///
///
/// `TypeId` 当前仅适用于归因于 `'static` 的类型，但是可以在 future 中消除此限制。
///
/// 虽然 `TypeId` 实现 `Hash`，`PartialOrd` 和 `Ord`，但值得注意的是，在 Rust 版本之间，哈希值和顺序将有所不同。
/// 注意不要在代码中依赖它们！
///
///
///
#[derive(Clone, Copy, Debug, Hash, Eq, PartialOrd, Ord)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct TypeId {
    t: u64,
}

#[stable(feature = "rust1", since = "1.0.0")]
impl PartialEq for TypeId {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.t == other.t
    }
}

impl TypeId {
    /// 返回已实例化此泛型函数的类型的 `TypeId`。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::{Any, TypeId};
    ///
    /// fn is_string<T: ?Sized + Any>(_s: &T) -> bool {
    ///     TypeId::of::<String>() == TypeId::of::<T>()
    /// }
    ///
    /// assert_eq!(is_string(&0), false);
    /// assert_eq!(is_string(&"cookie monster".to_string()), true);
    /// ```
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_const_unstable(feature = "const_type_id", issue = "77125")]
    pub const fn of<T: ?Sized + 'static>() -> TypeId {
        TypeId { t: intrinsics::type_id::<T>() }
    }
}

/// 以字符串切片的形式返回类型的名称。
///
/// # Note
///
/// 这旨在用于诊断。
/// 除了作为尽力而为的类型描述之外，未指定返回的字符串的确切内容和格式。
/// 例如，在 `type_name::<Option<String>>()` 可能返回的字符串中，有 `"Option<String>"` 和 `"std::option::Option<std::string::String>"`。
///
///
/// 返回的字符串不得视为类型的唯一标识符，因为多个类型可能会 map 变为相同的类型名称。
/// 同样，不能保证类型的所有部分都将出现在返回的字符串中：例如，当前不包括生命周期说明符。
/// 此外，输出可能会在编译器的版本之间改变。
///
/// 当前的实现使用与编译器诊断和 debuginfo 相同的基础结构，但这不能保证。
///
/// # Examples
///
/// ```rust
/// assert_eq!(
///     std::any::type_name::<Option<String>>(),
///     "core::option::Option<alloc::string::String>",
/// );
/// ```
///
///
///
///
#[must_use]
#[stable(feature = "type_name", since = "1.38.0")]
#[rustc_const_unstable(feature = "const_type_name", issue = "63084")]
pub const fn type_name<T: ?Sized>() -> &'static str {
    intrinsics::type_name::<T>()
}

/// 以字符串切片的形式返回指向的值的类型的名称。
/// 这与 `type_name::<T>()` 相同，但是可以在不容易获得变量类型的地方使用。
///
/// # Note
///
/// 这旨在用于诊断。没有指定字符串的确切内容和格式，只是对类型的尽力描述。
/// 例如，`type_name_of_val::<Option<String>>(None)` 可以返回 `"Option<String>"` 或 `"std::option::Option<std::string::String>"`，但不能返回 `"foobar"`。
///
/// 此外，输出可能会在编译器的版本之间改变。
///
/// 此函数不能解析 trait 对象，这意味着 `type_name_of_val(&7u32 as &dyn Debug)` 可以返回 `"dyn Debug"`，但不能返回 `"u32"`。
///
/// 类型名称不应视为类型的唯一标识符；
/// 多个类型可以共享相同的类型名称。
///
/// 当前的实现使用与编译器诊断和 debuginfo 相同的基础结构，但这不能保证。
///
/// # Examples
///
/// 打印默认的整数和浮点类型。
///
/// ```rust
/// #![feature(type_name_of_val)]
/// use std::any::type_name_of_val;
///
/// let x = 1;
/// println!("{}", type_name_of_val(&x));
/// let y = 1.0;
/// println!("{}", type_name_of_val(&y));
/// ```
///
///
///
///
///
///
#[must_use]
#[unstable(feature = "type_name_of_val", issue = "66359")]
#[rustc_const_unstable(feature = "const_type_name", issue = "63084")]
pub const fn type_name_of_val<T: ?Sized>(_val: &T) -> &'static str {
    type_name::<T>()
}

///////////////////////////////////////////////////////////////////////////////
// Provider trait
///////////////////////////////////////////////////////////////////////////////

/// Trait 由可以根据类型动态提供值的类型实现。
#[unstable(feature = "provide_any", issue = "96024")]
pub trait Provider {
    /// 数据提供者应实现此方法以提供他们能够通过使用 `demand` 提供的*所有*值。
    ///
    /// 请注意，`Demand` 上的 `provide_*` 方法具有短路语义: 如果较早的方法已成功提供值，则以后的方法将没有机会提供。
    ///
    ///
    /// # Examples
    ///
    /// 提供对类型为 `String` 的字段的引用作为 `&str`，以及类型为 `i32` 的值。
    ///
    /// ```rust
    /// # #![feature(provide_any)]
    /// use std::any::{Provider, Demand};
    /// # struct SomeConcreteType { field: String, num_field: i32 }
    ///
    /// impl Provider for SomeConcreteType {
    ///     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
    ///         demand.provide_ref::<str>(&self.field)
    ///             .provide_value::<i32>(self.num_field);
    ///     }
    /// }
    /// ```
    ///
    ///
    ///
    #[unstable(feature = "provide_any", issue = "96024")]
    fn provide<'a>(&'a self, demand: &mut Demand<'a>);
}

/// 从 `Provider` 请求一个值。
///
/// # Examples
///
/// 从提供者处获取字符串值。
///
/// ```rust
/// # #![feature(provide_any)]
/// use std::any::{Provider, request_value};
///
/// fn get_string(provider: &impl Provider) -> String {
///     request_value::<String>(provider).unwrap()
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn request_value<'a, T>(provider: &'a (impl Provider + ?Sized)) -> Option<T>
where
    T: 'static,
{
    request_by_type_tag::<'a, tags::Value<T>>(provider)
}

/// 从 `Provider` 请求引用。
///
/// # Examples
///
/// 从提供者处获取字符串引用。
///
/// ```rust
/// # #![feature(provide_any)]
/// use std::any::{Provider, request_ref};
///
/// fn get_str(provider: &impl Provider) -> &str {
///     request_ref::<str>(provider).unwrap()
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn request_ref<'a, T>(provider: &'a (impl Provider + ?Sized)) -> Option<&'a T>
where
    T: 'static + ?Sized,
{
    request_by_type_tag::<'a, tags::Ref<tags::MaybeSizedValue<T>>>(provider)
}

/// 通过 `Provider` 的标签请求特定值。
fn request_by_type_tag<'a, I>(provider: &'a (impl Provider + ?Sized)) -> Option<I::Reified>
where
    I: tags::Type<'a>,
{
    let mut tagged = TaggedOption::<'a, I>(None);
    provider.provide(tagged.as_demand());
    tagged.0
}

///////////////////////////////////////////////////////////////////////////////
// 需求及其方法
///////////////////////////////////////////////////////////////////////////////

/// 用于按类型提供数据的帮助器对象。
///
/// 数据提供者通过调用此类型的提供方法来提供值。
#[unstable(feature = "provide_any", issue = "96024")]
#[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/90435
pub struct Demand<'a>(dyn Erased<'a> + 'a);

impl<'a> Demand<'a> {
    /// 从 `&mut dyn Erased` trait 对象创建一个新的 `&mut Demand`。
    fn new<'b>(erased: &'b mut (dyn Erased<'a> + 'a)) -> &'b mut Demand<'a> {
        // SAFETY: 将 `&mut (dyn Erased<'a> + 'a)` 转换为 `&mut Demand<'a>` 是安全的，因为 `Demand` 是 repr(transparent)。
        //
        unsafe { &mut *(erased as *mut dyn Erased<'a> as *mut Demand<'a>) }
    }

    /// 提供仅具有静态生命周期的值或其他类型。
    ///
    /// # Examples
    ///
    /// 提供 `u8`。
    ///
    /// ```rust
    /// #![feature(provide_any)]
    ///
    /// use std::any::{Provider, Demand};
    /// # struct SomeConcreteType { field: u8 }
    ///
    /// impl Provider for SomeConcreteType {
    ///     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
    ///         demand.provide_value::<u8>(self.field);
    ///     }
    /// }
    /// ```
    #[unstable(feature = "provide_any", issue = "96024")]
    pub fn provide_value<T>(&mut self, value: T) -> &mut Self
    where
        T: 'static,
    {
        self.provide::<tags::Value<T>>(value)
    }

    /// 提供仅使用闭包计算的静态生命周期的值或其他类型。
    ///
    /// # Examples
    ///
    /// 通过克隆提供 `String`。
    ///
    /// ```rust
    /// #![feature(provide_any)]
    ///
    /// use std::any::{Provider, Demand};
    /// # struct SomeConcreteType { field: String }
    ///
    /// impl Provider for SomeConcreteType {
    ///     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
    ///         demand.provide_value_with::<String>(|| self.field.clone());
    ///     }
    /// }
    /// ```
    #[unstable(feature = "provide_any", issue = "96024")]
    pub fn provide_value_with<T>(&mut self, fulfil: impl FnOnce() -> T) -> &mut Self
    where
        T: 'static,
    {
        self.provide_with::<tags::Value<T>>(fulfil)
    }

    /// 提供引用。
    /// 裁判类型必须以 `'static` 为界，但可以是未定义大小的。
    ///
    /// # Examples
    ///
    /// 以 `&str` 的形式提供对字段的引用。
    ///
    /// ```rust
    /// #![feature(provide_any)]
    ///
    /// use std::any::{Provider, Demand};
    /// # struct SomeConcreteType { field: String }
    ///
    /// impl Provider for SomeConcreteType {
    ///     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
    ///         demand.provide_ref::<str>(&self.field);
    ///     }
    /// }
    /// ```
    #[unstable(feature = "provide_any", issue = "96024")]
    pub fn provide_ref<T: ?Sized + 'static>(&mut self, value: &'a T) -> &mut Self {
        self.provide::<tags::Ref<tags::MaybeSizedValue<T>>>(value)
    }

    /// 提供使用闭包计算的引用。
    /// 裁判类型必须以 `'static` 为界，但可以是未定义大小的。
    ///
    /// # Examples
    ///
    /// 以 `&str` 的形式提供对字段的引用。
    ///
    /// ```rust
    /// #![feature(provide_any)]
    ///
    /// use std::any::{Provider, Demand};
    /// # struct SomeConcreteType { business: String, party: String }
    /// # fn today_is_a_weekday() -> bool { true }
    ///
    /// impl Provider for SomeConcreteType {
    ///     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
    ///         demand.provide_ref_with::<str>(|| {
    ///             if today_is_a_weekday() {
    ///                 &self.business
    ///             } else {
    ///                 &self.party
    ///             }
    ///         });
    ///     }
    /// }
    /// ```
    #[unstable(feature = "provide_any", issue = "96024")]
    pub fn provide_ref_with<T: ?Sized + 'static>(
        &mut self,
        fulfil: impl FnOnce() -> &'a T,
    ) -> &mut Self {
        self.provide_with::<tags::Ref<tags::MaybeSizedValue<T>>>(fulfil)
    }

    /// 使用给定的 `Type` 标记提供一个值。
    fn provide<I>(&mut self, value: I::Reified) -> &mut Self
    where
        I: tags::Type<'a>,
    {
        if let Some(res @ TaggedOption(None)) = self.0.downcast_mut::<I>() {
            res.0 = Some(value);
        }
        self
    }

    /// 使用给定的 `Type` 标记提供一个值，使用闭包来防止不必要的工作。
    fn provide_with<I>(&mut self, fulfil: impl FnOnce() -> I::Reified) -> &mut Self
    where
        I: tags::Type<'a>,
    {
        if let Some(res @ TaggedOption(None)) = self.0.downcast_mut::<I>() {
            res.0 = Some(fulfil());
        }
        self
    }

    /// 如果提供指定类型的值，请检查是否满足 `Demand`。
    /// 如果类型不匹配或已提供，则返回 false。
    ///
    /// # Examples
    ///
    /// 检查是否仍需要提供 `u8`，然后提供。
    ///
    /// ```rust
    /// #![feature(provide_any)]
    ///
    /// use std::any::{Provider, Demand};
    ///
    /// struct Parent(Option<u8>);
    ///
    /// impl Provider for Parent {
    ///     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
    ///         if let Some(v) = self.0 {
    ///             demand.provide_value::<u8>(v);
    ///         }
    ///     }
    /// }
    ///
    /// struct Child {
    ///     parent: Parent,
    /// }
    ///
    /// impl Child {
    ///     // 假装这需要大量资源来评估。
    ///     fn an_expensive_computation(&self) -> Option<u8> {
    ///         Some(99)
    ///     }
    /// }
    ///
    /// impl Provider for Child {
    ///     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
    ///         // 一般来说，我们不知道这个调用会不会提供一个 `u8` 值...
    /////
    ///         self.parent.provide(demand);
    ///
    ///         // ...所以我们在运行昂贵的计算之前检查是否需要 `u8`。
    /////
    ///         if demand.would_be_satisfied_by_value_of::<u8>() {
    ///             if let Some(v) = self.an_expensive_computation() {
    ///                 demand.provide_value::<u8>(v);
    ///             }
    ///         }
    ///
    ///         // 无论父母提供值还是我们提供值，现在都将满足需求。
    /////
    ///         assert!(!demand.would_be_satisfied_by_value_of::<u8>());
    ///     }
    /// }
    ///
    /// let parent = Parent(Some(42));
    /// let child = Child { parent };
    /// assert_eq!(Some(42), std::any::request_value::<u8>(&child));
    ///
    /// let parent = Parent(None);
    /// let child = Child { parent };
    /// assert_eq!(Some(99), std::any::request_value::<u8>(&child));
    /// ```
    ///
    ///
    #[unstable(feature = "provide_any", issue = "96024")]
    pub fn would_be_satisfied_by_value_of<T>(&self) -> bool
    where
        T: 'static,
    {
        self.would_be_satisfied_by::<tags::Value<T>>()
    }

    /// 如果提供对指定类型值的引用，检查是否满足 `Demand`。
    /// 如果类型不匹配或已提供，则返回 false。
    ///
    /// # Examples
    ///
    /// 检查是否仍需要提供 `&str`，然后提供。
    ///
    /// ```rust
    /// #![feature(provide_any)]
    ///
    /// use std::any::{Provider, Demand};
    ///
    /// struct Parent(Option<String>);
    ///
    /// impl Provider for Parent {
    ///     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
    ///         if let Some(v) = &self.0 {
    ///             demand.provide_ref::<str>(v);
    ///         }
    ///     }
    /// }
    ///
    /// struct Child {
    ///     parent: Parent,
    ///     name: String,
    /// }
    ///
    /// impl Child {
    ///     // 假装这需要大量资源来评估。
    ///     fn an_expensive_computation(&self) -> Option<&str> {
    ///         Some(&self.name)
    ///     }
    /// }
    ///
    /// impl Provider for Child {
    ///     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
    ///         // 一般来说，不知道这个调用会不会提供 `str` 引用...
    /////
    ///         self.parent.provide(demand);
    ///
    ///         // ...所以我们在运行昂贵的计算之前检查是否需要 `&str`。
    /////
    ///         if demand.would_be_satisfied_by_ref_of::<str>() {
    ///             if let Some(v) = self.an_expensive_computation() {
    ///                 demand.provide_ref::<str>(v);
    ///             }
    ///         }
    ///
    ///         // 无论父母是否提供了引用或我们提供了，现在都将满足需求。
    /////
    ///         assert!(!demand.would_be_satisfied_by_ref_of::<str>());
    ///     }
    /// }
    ///
    /// let parent = Parent(Some("parent".into()));
    /// let child = Child { parent, name: "child".into() };
    /// assert_eq!(Some("parent"), std::any::request_ref::<str>(&child));
    ///
    /// let parent = Parent(None);
    /// let child = Child { parent, name: "child".into() };
    /// assert_eq!(Some("child"), std::any::request_ref::<str>(&child));
    /// ```
    ///
    ///
    #[unstable(feature = "provide_any", issue = "96024")]
    pub fn would_be_satisfied_by_ref_of<T>(&self) -> bool
    where
        T: ?Sized + 'static,
    {
        self.would_be_satisfied_by::<tags::Ref<tags::MaybeSizedValue<T>>>()
    }

    fn would_be_satisfied_by<I>(&self) -> bool
    where
        I: tags::Type<'a>,
    {
        matches!(self.0.downcast::<I>(), Some(TaggedOption(None)))
    }
}

#[unstable(feature = "provide_any", issue = "96024")]
impl<'a> fmt::Debug for Demand<'a> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Demand").finish_non_exhaustive()
    }
}

///////////////////////////////////////////////////////////////////////////////
// 类型标签
///////////////////////////////////////////////////////////////////////////////

mod tags {
    //! 类型标签用于使用单独的值来标识类型。这个模块包括一些非常常见的类型的类型标签。
    //!
    //! 当前类型标签不向用户公开。
    //! 但是在 future 中，如果您想使用更复杂类型的 Provider API (通常包括生命周期参数)，您需要编写自己的标签。
    //!
    //!

    use crate::marker::PhantomData;

    /// 这个 trait 由特定的标签类型实现，以便允许描述可以为给定的生命周期 `'a` 请求的类型。
    ///
    /// 在这个模块中可以找到一些类型驱动标签的示例实现，尽管 crates 也可以为具有内部生命周期的更复杂类型实现自己的标签。
    ///
    ///
    ///
    pub trait Type<'a>: Sized + 'static {
        /// 对于给定的生命周期，此标签可能标记的值的类型。
        ///
        type Reified: 'a;
    }

    /// 与 [`Type`] trait 类似，但表示可能是未定义大小的类型 (即，具有 `?Sized` 边界)。
    /// 例如，`str`。
    pub trait MaybeSizedType<'a>: Sized + 'static {
        type Reified: 'a + ?Sized;
    }

    impl<'a, T: Type<'a>> MaybeSizedType<'a> for T {
        type Reified = T::Reified;
    }

    /// 以 `'static` 为界的类型的基于类型的标记，即没有借用元素。
    #[derive(Debug)]
    pub struct Value<T: 'static>(PhantomData<T>);

    impl<'a, T: 'static> Type<'a> for Value<T> {
        type Reified = T;
    }

    /// 基于类型的标记类似于 [`Value`]，但可能是未定义大小的 (即，具有 `?Sized` 边界)。
    #[derive(Debug)]
    pub struct MaybeSizedValue<T: ?Sized + 'static>(PhantomData<T>);

    impl<'a, T: ?Sized + 'static> MaybeSizedType<'a> for MaybeSizedValue<T> {
        type Reified = T;
    }

    /// 引用类型的基于类型的标记 (`&'a T`，其中 T 由 `<I as MaybeSizedType<'a>>::Reified` 表示。
    ///
    #[derive(Debug)]
    pub struct Ref<I>(PhantomData<I>);

    impl<'a, I: MaybeSizedType<'a>> Type<'a> for Ref<I> {
        type Reified = &'a I::Reified;
    }
}

/// 带有类型标签 `I` 的 `Option`。
///
/// 由于这个结构体实现了 `Erased`，所以类型可以是 erased 来做一个动态类型的选项。
/// 可以使用 `Erased::tag_id` 动态检查类型，并且由于这是针对具体类型静态检查的，因此存在一定程度的类型安全性。
///
#[repr(transparent)]
struct TaggedOption<'a, I: tags::Type<'a>>(Option<I::Reified>);

impl<'a, I: tags::Type<'a>> TaggedOption<'a, I> {
    fn as_demand(&mut self) -> &mut Demand<'a> {
        Demand::new(self as &mut (dyn Erased<'a> + 'a))
    }
}

/// 表示一个类型为 erased 但可识别的对象。
///
/// 这个 trait 是由 `TaggedOption` 类型专门实现的。
unsafe trait Erased<'a>: 'a {
    /// erased 类型的 `TypeId`。
    fn tag_id(&self) -> TypeId;
}

unsafe impl<'a, I: tags::Type<'a>> Erased<'a> for TaggedOption<'a, I> {
    fn tag_id(&self) -> TypeId {
        TypeId::of::<I>()
    }
}

#[unstable(feature = "provide_any", issue = "96024")]
impl<'a> dyn Erased<'a> + 'a {
    /// 如果它被标记为 `I`，则返回一些对动态值的引用，否则返回 `None`。
    ///
    #[inline]
    fn downcast<I>(&self) -> Option<&TaggedOption<'a, I>>
    where
        I: tags::Type<'a>,
    {
        if self.tag_id() == TypeId::of::<I>() {
            // SAFETY: 刚刚检查了我们是否指向一个 I。
            Some(unsafe { &*(self as *const Self).cast::<TaggedOption<'a, I>>() })
        } else {
            None
        }
    }

    /// 如果它被标记为 `I`，则返回一些对动态值的引用，否则返回 `None`。
    ///
    #[inline]
    fn downcast_mut<I>(&mut self) -> Option<&mut TaggedOption<'a, I>>
    where
        I: tags::Type<'a>,
    {
        if self.tag_id() == TypeId::of::<I>() {
            // SAFETY: 刚刚检查了我们是否指向一个 I。
            Some(unsafe { &mut *(self as *mut Self).cast::<TaggedOption<'a, I>>() })
        } else {
            None
        }
    }
}