      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

    // 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` method.
    //!
    //! 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")]

    use marker::Sized;

    /// A common trait for cloning an object.
    ///
    /// This trait can be used with `#[derive]`.
    ///
    /// 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.
    #[stable(feature = "rust1", since = "1.0.0")]
    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(always)]
        #[stable(feature = "rust1", since = "1.0.0")]
        fn clone_from(&mut self, source: &Self) {
            *self = source.clone()
        }
    }

    // FIXME(aburka): this method is used solely by #[derive] to
    // assert that every component of a type implements Clone.
    //
    // This should never be called by user code.
    #[doc(hidden)]
    #[inline(always)]
    #[unstable(feature = "derive_clone_copy",
               reason = "deriving hack, should not be public",
               issue = "0")]
    pub fn assert_receiver_is_clone<T: Clone + ?Sized>(_: &T) {}

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<'a, T: ?Sized> Clone for &'a T {
        /// Returns a shallow copy of the reference.
        #[inline]
        fn clone(&self) -> &'a T { *self }
    }

    macro_rules! clone_impl {
        ($t:ty) => {
            #[stable(feature = "rust1", since = "1.0.0")]
            impl Clone for $t {
                /// Returns a deep copy of the value.
                #[inline]
                fn clone(&self) -> $t { *self }
            }
        }
    }

    clone_impl! { isize }
    clone_impl! { i8 }
    clone_impl! { i16 }
    clone_impl! { i32 }
    clone_impl! { i64 }

    clone_impl! { usize }
    clone_impl! { u8 }
    clone_impl! { u16 }
    clone_impl! { u32 }
    clone_impl! { u64 }

    clone_impl! { f32 }
    clone_impl! { f64 }

    clone_impl! { () }
    clone_impl! { bool }
    clone_impl! { char }

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)