| // 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 } |
| /// } |
| /// ``` |
| /// |
| /// ## Additional implementors |
| /// |
| /// In addition to the [implementors listed below][impls], |
| /// the following types also implement `Clone`: |
| /// |
| /// * Function item types (i.e. the distinct types defined for each function) |
| /// * Function pointer types (e.g. `fn() -> i32`) |
| /// * Array types, for all sizes, if the item type also implements `Clone` (e.g. `[i32; 123456]`) |
| /// * Tuple types, if each component also implements `Clone` (e.g. `()`, `(i32, bool)`) |
| /// * Closure types, if they capture no value from the environment |
| /// or if all such captured values implement `Clone` themselves. |
| /// Note that variables captured by shared reference always implement `Clone` |
| /// (even if the referent doesn't), |
| /// while variables captured by mutable reference never implement `Clone`. |
| /// |
| /// [impls]: #implementors |
| #[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")] |
| #[must_use = "cloning is often expensive and is not expected to have side effects"] |
| 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> } |
| |
| /// Implementations of `Clone` for primitive types. |
| /// |
| /// Implementations that cannot be described in Rust |
| /// are implemented in `SelectionContext::copy_clone_conditions()` in librustc. |
| mod impls { |
| |
| use super::Clone; |
| |
| macro_rules! impl_clone { |
| ($($t:ty)*) => { |
| $( |
| #[stable(feature = "rust1", since = "1.0.0")] |
| impl Clone for $t { |
| #[inline] |
| 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] |
| fn clone(&self) -> Self { |
| *self |
| } |
| } |
| |
| #[stable(feature = "rust1", since = "1.0.0")] |
| impl<T: ?Sized> Clone for *mut T { |
| #[inline] |
| fn clone(&self) -> Self { |
| *self |
| } |
| } |
| |
| // Shared references can be cloned, but mutable references *cannot*! |
| #[stable(feature = "rust1", since = "1.0.0")] |
| impl<T: ?Sized> Clone for &T { |
| #[inline] |
| fn clone(&self) -> Self { |
| *self |
| } |
| } |
| |
| } |