//! 不能隐式复制的类型的 `Clone` trait。
//!
//! 在 Rust 中，一些简单类型是 "隐式可复制的"，当您分配它们或将它们作为参数传递时，接收者将获得一个副本，而将原始值保留在原位。
//! 这些类型不需要分配就可以复制并且没有终结器 (即，它们不包含拥有的 boxes 或实现 [`Drop`])，因此编译器认为它们便宜且安全地进行复制。
//!
//! 对于其他类型，必须通过约定实现 [`Clone`] trait 并调用 [`clone`] 方法来显式复制。
//!
//! [`clone`]: Clone::clone
//!
//! 基本用法示例：
//!
//! ```
//! let s = String::new(); // 字符串类型实现克隆
//! let copy = s.clone(); // 所以我们可以克隆它
//! ```
//!
//! 要轻松实现 Clone trait，还可以使用 `#[derive(Clone)]`。Example:
//!
//! ```
//! #[derive(Clone)] // 我们将克隆 trait 添加到 Morpheus 结构体
//! struct Morpheus {
//!    blue_pill: f32,
//!    red_pill: i64,
//! }
//!
//! fn main() {
//!    let f = Morpheus { blue_pill: 0.0, red_pill: 0 };
//!    let copy = f.clone(); // 现在我们可以克隆它了！
//! }
//! ```
//!
//!
//!
//!
//!

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

/// 通用的 trait，用于显式复制对象。
///
/// 与 [`Copy`] 的不同之处在于 [`Copy`] 是隐式的并且是廉价的按位复制，而 `Clone` 始终是显式的并且可能昂贵也可能不昂贵。
/// 为了强制执行这些特性，Rust 不允许您重新实现 [`Copy`]，但是您可以重新实现 `Clone` 并运行任意代码。
///
/// 由于 `Clone` 比 [`Copy`] 更通用，因此您可以自动将 [`Copy`] 设为 `Clone`。
///
/// ## Derivable
///
/// 如果所有字段均为 `Clone`，则此 trait 可以与 `#[derive]` 一起使用。[`Clone`] 的 `derive`d 实现在每个字段上调用 [`clone`]。
///
/// [`clone`]: Clone::clone
///
/// 对于泛型结构体，`#[derive]` 通过在泛型参数上添加绑定的 `Clone` 有条件地实现 `Clone`。
///
/// ```
/// // 当 T 是 Clone 时，`derive` 为 Reading<T> 实现了 Clone。
/// #[derive(Clone)]
/// struct Reading<T> {
///     frequency: T,
/// }
/// ```
///
/// ## 如何实现 `Clone`？
///
/// [`Copy`] 类型应该实现 `Clone` 的简单实现。更正式地：
/// 如果 `T: Copy`，`x: T` 和 `y: &T`，则 `let x = y.clone();` 等效于 `let x = *y;`。
/// 手动执行时应注意保持不变。但是，不安全的代码一定不能依靠它来确保内存安全。
///
/// 一个示例是持有函数指针的泛型结构体。在这种情况下，不能对 `Clone` 的实现进行派生操作，而可以将其实现为：
///
/// ```
/// struct Generate<T>(fn() -> T);
///
/// impl<T> Copy for Generate<T> {}
///
/// impl<T> Clone for Generate<T> {
///     fn clone(&self) -> Self {
///         *self
///     }
/// }
/// ```
///
/// ## 其他实现者
///
/// 除了下面列出的 [实现者][impls] 外，以下类型还实现了 `Clone`：
///
/// * 函数项类型 (即，为每个函数定义的不同类型)
/// * 函数指针类型 (例如 `fn() -> i32`)
/// * 闭包类型，如果它们没有从环境中捕获任何值，或者所有此类捕获的值本身都实现了 `Clone`。
///   请注意，由共享引用捕获的变量始终实现 `Clone` (即使引用对象没有实现)，而由变量引用捕获的变量从不实现 `Clone`。
///
///
/// [impls]: #implementors
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[lang = "clone"]
#[rustc_diagnostic_item = "Clone"]
#[rustc_trivial_field_reads]
pub trait Clone: Sized {
    /// 返回值的副本。
    ///
    /// # Examples
    ///
    /// ```
    /// # #![allow(noop_method_call)]
    /// let hello = "Hello"; // &str 实现克隆
    ///
    /// assert_eq!("Hello", hello.clone());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[must_use = "cloning is often expensive and is not expected to have side effects"]
    fn clone(&self) -> Self;

    /// 从 `source` 执行复制分配。
    ///
    /// `a.clone_from(&b)` 在功能上等同于 `a = b.clone()`，但可以被覆盖以重用 `a` 的资源以避免不必要的分配。
    ///
    ///
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    fn clone_from(&mut self, source: &Self) {
        *self = source.clone()
    }
}

/// 派生宏，生成 `Clone` trait 的 impl。
#[rustc_builtin_macro]
#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
#[allow_internal_unstable(core_intrinsics, derive_clone_copy)]
pub macro Clone($item:item) {
    /* compiler built-in */
}

// FIXME(aburka): 这些结构仅由 #[derivate] 用来断言类型的每个组件都实现了 Clone 或 Copy。
//
//
// 这些结构体永远不会出现在用户代码中。
#[doc(hidden)]
#[allow(missing_debug_implementations)]
#[unstable(
    feature = "derive_clone_copy",
    reason = "deriving hack, should not be public",
    issue = "none"
)]
pub struct AssertParamIsClone<T: Clone + ?Sized> {
    _field: crate::marker::PhantomData<T>,
}
#[doc(hidden)]
#[allow(missing_debug_implementations)]
#[unstable(
    feature = "derive_clone_copy",
    reason = "deriving hack, should not be public",
    issue = "none"
)]
pub struct AssertParamIsCopy<T: Copy + ?Sized> {
    _field: crate::marker::PhantomData<T>,
}

/// 原始类型的 `Clone` 实现。
///
/// `rustc_trait_selection` 中的 `traits::SelectionContext::copy_clone_conditions()` 中实现了 Rust 中无法描述的实现。
///
///
mod impls {
    use super::Clone;

    macro_rules! impl_clone {
        ($($t:ty)*) => {
            $(
                #[stable(feature = "rust1", since = "1.0.0")]
                impl Clone for $t {
                    #[inline(always)]
                    fn clone(&self) -> Self {
                        *self
                    }
                }
            )*
        }
    }

    impl_clone! {
        usize u8 u16 u32 u64 u128
        isize i8 i16 i32 i64 i128
        f32 f64
        bool char
    }

    #[unstable(feature = "never_type", issue = "35121")]
    impl Clone for ! {
        #[inline]
        fn clone(&self) -> Self {
            *self
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: ?Sized> Clone for *const T {
        #[inline(always)]
        fn clone(&self) -> Self {
            *self
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: ?Sized> Clone for *mut T {
        #[inline(always)]
        fn clone(&self) -> Self {
            *self
        }
    }

    /// 共享的引用可以被克隆，但是可变引用 *不能*!
    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: ?Sized> Clone for &T {
        #[inline(always)]
        #[rustc_diagnostic_item = "noop_method_clone"]
        fn clone(&self) -> Self {
            *self
        }
    }

    /// 共享的引用可以被克隆，但是可变引用 *不能*!
    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: ?Sized> !Clone for &mut T {}
}