1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
//! 不能隐式复制的类型的 `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 {}
}