//! 该模块实现了 `Any` trait，它可以通过运行时反射来动态键入任何 `'static` 类型。
//!
//! `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);
//! }
//! ```
//!
//!
//!
//!
//!
//!
//!
//!
//!

#![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 {
    /// 如果 boxed 类型与 `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
    }

    /// 如果 boxed 的类型为 `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 as *const dyn Any as *const T)) }
        } else {
            None
        }
    }

    /// 如果 boxed 的类型为 `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(&mut *(self as *mut dyn Any as *mut T)) }
        } else {
            None
        }
    }
}

impl dyn Any + Send {
    /// 转发到在 `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)
    }

    /// 转发到在 `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)
    }

    /// 转发到在 `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)
    }
}

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)
    }
}

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

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

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);
    /// ```
    #[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>",
/// );
/// ```
///
///
///
///
#[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));
/// ```
///
///
///
///
///
///
#[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>()
}