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