diff options
Diffstat (limited to 'libcore/clone.rs')
| -rw-r--r-- | libcore/clone.rs | 37 |
1 files changed, 35 insertions, 2 deletions
diff --git a/libcore/clone.rs b/libcore/clone.rs index ad2a205..e8cd36f 100644 --- a/libcore/clone.rs +++ b/libcore/clone.rs @@ -46,9 +46,42 @@ use marker::Sized; -/// A common trait for cloning an object. +/// A common trait for the ability to explicitly duplicate an object. /// -/// This trait can be used with `#[derive]`. +/// Differs from `Copy` in that `Copy` is implicit and extremely inexpensive, while +/// `Clone` is always explicit and may or may not be expensive. In order to enforce +/// these characteristics, Rust does not allow you to reimplement `Copy`, but you +/// may reimplement `Clone` and run arbitrary code. +/// +/// Since `Clone` is more general than `Copy`, you can automatically make anything +/// `Copy` be `Clone` as well. +/// +/// ## Derivable +/// +/// This trait can be used with `#[derive]` if all fields are `Clone`. The `derive`d +/// implementation of `clone()` calls `clone()` on each field. +/// +/// ## How can I implement `Clone`? +/// +/// Types that are `Copy` should have a trivial implementation of `Clone`. More formally: +/// if `T: Copy`, `x: T`, and `y: &T`, then `let x = y.clone();` is equivalent to `let x = *y;`. +/// Manual implementations should be careful to uphold this invariant; however, unsafe code +/// must not rely on it to ensure memory safety. +/// +/// An example is an array holding more than 32 elements of a type that is `Clone`; the standard +/// library only implements `Clone` up until arrays of size 32. In this case, the implementation of +/// `Clone` cannot be `derive`d, but can be implemented as: +/// +/// ``` +/// #[derive(Copy)] +/// struct Stats { +/// frequencies: [i32; 100], +/// } +/// +/// impl Clone for Stats { +/// fn clone(&self) -> Stats { *self } +/// } +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub trait Clone : Sized { /// Returns a copy of the value. |