src/libcore/clone.rs

   1 // Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! The `Clone` trait for types that cannot be 'implicitly copied'
  12 //!
  13 //! In Rust, some simple types are "implicitly copyable" and when you
  14 //! assign them or pass them as arguments, the receiver will get a copy,
  15 //! leaving the original value in place. These types do not require
  16 //! allocation to copy and do not have finalizers (i.e. they do not
  17 //! contain owned boxes or implement `Drop`), so the compiler considers
  18 //! them cheap and safe to copy. For other types copies must be made
  19 //! explicitly, by convention implementing the `Clone` trait and calling
  20 //! the `clone` method.
  21
  22 #![stable(feature = "rust1", since = "1.0.0")]
  23
  24 use marker::Sized;
  25
  26 /// A common trait for cloning an object.
  27 #[stable(feature = "rust1", since = "1.0.0")]
  28 pub trait Clone : Sized {
  29     /// Returns a copy of the value.
  30     ///
  31     /// # Examples
  32     ///
  33     /// ```
  34     /// let hello = "Hello"; // &str implements Clone
  35     ///
  36     /// assert_eq!("Hello", hello.clone());
  37     /// ```
  38     #[stable(feature = "rust1", since = "1.0.0")]
  39     fn clone(&self) -> Self;
  40
  41     /// Performs copy-assignment from `source`.
  42     ///
  43     /// `a.clone_from(&b)` is equivalent to `a = b.clone()` in functionality,
  44     /// but can be overridden to reuse the resources of `a` to avoid unnecessary
  45     /// allocations.
  46     #[inline(always)]
  47     #[stable(feature = "rust1", since = "1.0.0")]
  48     fn clone_from(&mut self, source: &Self) {
  49         *self = source.clone()
  50     }
  51 }
  52
  53 #[stable(feature = "rust1", since = "1.0.0")]
  54 impl<'a, T: ?Sized> Clone for &'a T {
  55     /// Returns a shallow copy of the reference.
  56     #[inline]
  57     fn clone(&self) -> &'a T { *self }
  58 }
  59
  60 macro_rules! clone_impl {
  61     ($t:ty) => {
  62         #[stable(feature = "rust1", since = "1.0.0")]
  63         impl Clone for $t {
  64             /// Returns a deep copy of the value.
  65             #[inline]
  66             fn clone(&self) -> $t { *self }
  67         }
  68     }
  69 }
  70
  71 clone_impl! { isize }
  72 clone_impl! { i8 }
  73 clone_impl! { i16 }
  74 clone_impl! { i32 }
  75 clone_impl! { i64 }
  76
  77 clone_impl! { usize }
  78 clone_impl! { u8 }
  79 clone_impl! { u16 }
  80 clone_impl! { u32 }
  81 clone_impl! { u64 }
  82
  83 clone_impl! { f32 }
  84 clone_impl! { f64 }
  85
  86 clone_impl! { () }
  87 clone_impl! { bool }
  88 clone_impl! { char }