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
// Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT // file at the top-level directory of this distribution and at // http://rust-lang.org/COPYRIGHT. // // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your // option. This file may not be copied, modified, or distributed // except according to those terms. //! The `Clone` trait for types that cannot be 'implicitly copied'. //! //! In Rust, some simple types are "implicitly copyable" and when you //! assign them or pass them as arguments, the receiver will get a copy, //! leaving the original value in place. These types do not require //! allocation to copy and do not have finalizers (i.e. they do not //! contain owned boxes or implement [`Drop`]), so the compiler considers //! them cheap and safe to copy. For other types copies must be made //! explicitly, by convention implementing the [`Clone`] trait and calling //! the [`clone`][clone] method. //! //! [`Clone`]: trait.Clone.html //! [clone]: trait.Clone.html#tymethod.clone //! [`Drop`]: ../../std/ops/trait.Drop.html //! //! Basic usage example: //! //! ``` //! let s = String::new(); // String type implements Clone //! let copy = s.clone(); // so we can clone it //! ``` //! //! To easily implement the Clone trait, you can also use //! `#[derive(Clone)]`. Example: //! //! ``` //! #[derive(Clone)] // we add the Clone trait to Morpheus struct //! struct Morpheus { //! blue_pill: f32, //! red_pill: i64, //! } //! //! fn main() { //! let f = Morpheus { blue_pill: 0.0, red_pill: 0 }; //! let copy = f.clone(); // and now we can clone it! //! } //! ``` #![stable(feature = "rust1", since = "1.0.0")] /// A common trait for the ability to explicitly duplicate an object. /// /// 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: /// /// [`Copy`]: ../../std/marker/trait.Copy.html /// [`clone`]: trait.Clone.html#tymethod.clone /// /// ``` /// #[derive(Copy)] /// struct Stats { /// frequencies: [i32; 100], /// } /// /// impl Clone for Stats { /// fn clone(&self) -> Stats { *self } /// } /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[lang = "clone"] pub trait Clone : Sized { /// Returns a copy of the value. /// /// # Examples /// /// ``` /// let hello = "Hello"; // &str implements Clone /// /// assert_eq!("Hello", hello.clone()); /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn clone(&self) -> Self; /// Performs copy-assignment from `source`. /// /// `a.clone_from(&b)` is equivalent to `a = b.clone()` in functionality, /// but can be overridden to reuse the resources of `a` to avoid unnecessary /// allocations. #[inline] #[stable(feature = "rust1", since = "1.0.0")] fn clone_from(&mut self, source: &Self) { *self = source.clone() } } // FIXME(aburka): these structs are used solely by #[derive] to // assert that every component of a type implements Clone or Copy. // // These structs should never appear in user code. #[doc(hidden)] #[allow(missing_debug_implementations)] #[unstable(feature = "derive_clone_copy", reason = "deriving hack, should not be public", issue = "0")] pub struct AssertParamIsClone<T: Clone + ?Sized> { _field: ::marker::PhantomData<T> } #[doc(hidden)] #[allow(missing_debug_implementations)] #[unstable(feature = "derive_clone_copy", reason = "deriving hack, should not be public", issue = "0")] pub struct AssertParamIsCopy<T: Copy + ?Sized> { _field: ::marker::PhantomData<T> }