//! 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.

//!

//! [`clone`]: Clone::clone

//!

//! 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 crate::marker::{Destruct, PointeeSized};

#[cfg(not(feature = "ferrocene_certified"))]

mod uninit;

/// A common trait that allows explicit creation of a duplicate value.

///

/// Calling [`clone`] always produces a new value.

/// However, for types that are references to other data (such as smart pointers or references),

/// the new value may still point to the same underlying data, rather than duplicating it.

/// See [`Clone::clone`] for more details.

///

/// This distinction is especially important when using `#[derive(Clone)]` on structs containing

/// smart pointers like `Arc<Mutex<T>>` - the cloned struct will share mutable state with the

/// original.

///

/// Differs from [`Copy`] in that [`Copy`] is implicit and an inexpensive bit-wise copy, 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.

///

/// [`clone`]: Clone::clone

///

/// For a generic struct, `#[derive]` implements `Clone` conditionally by adding bound `Clone` on

/// generic parameters.

///

/// ```

/// // `derive` implements Clone for Reading<T> when T is Clone.

/// #[derive(Clone)]

/// struct Reading<T> {

///     frequency: T,

/// }

/// ```

///

/// ## 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 a generic struct holding a function pointer. In this case, the

/// implementation of `Clone` cannot be `derive`d, but can be implemented as:

///

/// ```

/// struct Generate<T>(fn() -> T);

///

/// impl<T> Copy for Generate<T> {}

///

/// impl<T> Clone for Generate<T> {

///     fn clone(&self) -> Self {

///         *self

///     }

/// }

/// ```

///

/// If we `derive`:

///

/// ```

/// #[derive(Copy, Clone)]

/// struct Generate<T>(fn() -> T);

/// ```

///

/// the auto-derived implementations will have unnecessary `T: Copy` and `T: Clone` bounds:

///

/// ```

/// # struct Generate<T>(fn() -> T);

///

/// // Automatically derived

/// impl<T: Copy> Copy for Generate<T> { }

///

/// // Automatically derived

/// impl<T: Clone> Clone for Generate<T> {

///     fn clone(&self) -> Generate<T> {

///         Generate(Clone::clone(&self.0))

///     }

/// }

/// ```

///

/// The bounds are unnecessary because clearly the function itself should be

/// copy- and cloneable even if its return type is not:

///

/// ```compile_fail,E0599

/// #[derive(Copy, Clone)]

/// struct Generate<T>(fn() -> T);

///

/// struct NotCloneable;

///

/// fn generate_not_cloneable() -> NotCloneable {

///     NotCloneable

/// }

///

/// Generate(generate_not_cloneable).clone(); // error: trait bounds were not satisfied

/// // Note: With the manual implementations the above line will compile.

/// ```

///

/// ## `Clone` and `PartialEq`/`Eq`

/// `Clone` is intended for the duplication of objects. Consequently, when implementing

/// both `Clone` and [`PartialEq`], the following property is expected to hold:

/// ```text

/// x == x -> x.clone() == x

/// ```

/// In other words, if an object compares equal to itself,

/// its clone must also compare equal to the original.

///

/// For types that also implement [`Eq`] – for which `x == x` always holds –

/// this implies that `x.clone() == x` must always be true.

/// Standard library collections such as

/// [`HashMap`], [`HashSet`], [`BTreeMap`], [`BTreeSet`] and [`BinaryHeap`]

/// rely on their keys respecting this property for correct behavior.

/// Furthermore, these collections require that cloning a key preserves the outcome of the

/// [`Hash`] and [`Ord`] methods. Thankfully, this follows automatically from `x.clone() == x`

/// if `Hash` and `Ord` are correctly implemented according to their own requirements.

///

/// When deriving both `Clone` and [`PartialEq`] using `#[derive(Clone, PartialEq)]`

/// or when additionally deriving [`Eq`] using `#[derive(Clone, PartialEq, Eq)]`,

/// then this property is automatically upheld – provided that it is satisfied by

/// the underlying types.

///

/// Violating this property is a logic error. The behavior resulting from a logic error is not

/// specified, but users of the trait must ensure that such logic errors do *not* result in

/// undefined behavior. This means that `unsafe` code **must not** rely on this property

/// being satisfied.

///

/// ## 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`)

/// * 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`.

///

/// [`HashMap`]: ../../std/collections/struct.HashMap.html

/// [`HashSet`]: ../../std/collections/struct.HashSet.html

/// [`BTreeMap`]: ../../std/collections/struct.BTreeMap.html

/// [`BTreeSet`]: ../../std/collections/struct.BTreeSet.html

/// [`BinaryHeap`]: ../../std/collections/struct.BinaryHeap.html

/// [impls]: #implementors

#[stable(feature = "rust1", since = "1.0.0")]

#[lang = "clone"]

#[rustc_diagnostic_item = "Clone"]

#[rustc_trivial_field_reads]

#[rustc_const_unstable(feature = "const_clone", issue = "142757")]

#[const_trait]

pub trait Clone: Sized {

    /// Returns a duplicate of the value.

    ///

    /// Note that what "duplicate" means varies by type:

    /// - For most types, this creates a deep, independent copy

    /// - For reference types like `&T`, this creates another reference to the same value

    /// - For smart pointers like [`Arc`] or [`Rc`], this increments the reference count

    ///   but still points to the same underlying data

    ///

    /// [`Arc`]: ../../std/sync/struct.Arc.html

    /// [`Rc`]: ../../std/rc/struct.Rc.html

    ///

    /// # Examples

    ///

    /// ```

    /// # #![allow(noop_method_call)]

    /// let hello = "Hello"; // &str implements Clone

    ///

    /// assert_eq!("Hello", hello.clone());

    /// ```

    ///

    /// Example with a reference-counted type:

    ///

    /// ```

    /// use std::sync::{Arc, Mutex};

    ///

    /// let data = Arc::new(Mutex::new(vec![1, 2, 3]));

    /// let data_clone = data.clone(); // Creates another Arc pointing to the same Mutex

    ///

    /// {

    ///     let mut lock = data.lock().unwrap();

    ///     lock.push(4);

    /// }

    ///

    /// // Changes are visible through the clone because they share the same underlying data

    /// assert_eq!(*data_clone.lock().unwrap(), vec![1, 2, 3, 4]);

    /// ```

    #[stable(feature = "rust1", since = "1.0.0")]

    #[must_use = "cloning is often expensive and is not expected to have side effects"]

    // Clone::clone is special because the compiler generates MIR to implement it for some types.

    // See InstanceKind::CloneShim.

    #[lang = "clone_fn"]

    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)

    where

        Self: [const] Destruct,

    {

        *self = source.clone()

    }

}

/// Derive macro generating an impl of the trait `Clone`.

#[rustc_builtin_macro]

#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]

#[allow_internal_unstable(core_intrinsics, derive_clone_copy)]

pub macro Clone($item:item) {

    /* compiler built-in */

}

/// Trait for objects whose [`Clone`] impl is lightweight (e.g. reference-counted)

///

/// Cloning an object implementing this trait should in general:

/// - be O(1) (constant) time regardless of the amount of data managed by the object,

/// - not require a memory allocation,

/// - not require copying more than roughly 64 bytes (a typical cache line size),

/// - not block the current thread,

/// - not have any semantic side effects (e.g. allocating a file descriptor), and

/// - not have overhead larger than a couple of atomic operations.

///

/// The `UseCloned` trait does not provide a method; instead, it indicates that

/// `Clone::clone` is lightweight, and allows the use of the `.use` syntax.

///

/// ## .use postfix syntax

///

/// Values can be `.use`d by adding `.use` postfix to the value you want to use.

///

/// ```ignore (this won't work until we land use)

/// fn foo(f: Foo) {

///     // if `Foo` implements `Copy` f would be copied into x.

///     // if `Foo` implements `UseCloned` f would be cloned into x.

///     // otherwise f would be moved into x.

///     let x = f.use;

///     // ...

/// }

/// ```

///

/// ## use closures

///

/// Use closures allow captured values to be automatically used.

/// This is similar to have a closure that you would call `.use` over each captured value.

#[unstable(feature = "ergonomic_clones", issue = "132290")]

#[lang = "use_cloned"]

#[cfg(not(feature = "ferrocene_certified"))]

pub trait UseCloned: Clone {

    // Empty.

}

#[cfg(not(feature = "ferrocene_certified"))]

macro_rules! impl_use_cloned {

    ($($t:ty)*) => {

        $(

            #[unstable(feature = "ergonomic_clones", issue = "132290")]

            impl UseCloned for $t {}

        )*

    }

}

#[cfg(not(feature = "ferrocene_certified"))]

impl_use_cloned! {

    usize u8 u16 u32 u64 u128

    isize i8 i16 i32 i64 i128

             f16 f32 f64 f128

    bool char

}

// 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 = "none"

)]

pub struct AssertParamIsClone<T: Clone + PointeeSized> {

    _field: crate::marker::PhantomData<T>,

}

#[doc(hidden)]

#[allow(missing_debug_implementations)]

#[unstable(

    feature = "derive_clone_copy",

    reason = "deriving hack, should not be public",

    issue = "none"

)]

#[cfg(not(feature = "ferrocene_certified"))]

pub struct AssertParamIsCopy<T: Copy + PointeeSized> {

    _field: crate::marker::PhantomData<T>,

}

/// A generalization of [`Clone`] to [dynamically-sized types][DST] stored in arbitrary containers.

///

/// This trait is implemented for all types implementing [`Clone`], [slices](slice) of all

/// such types, and other dynamically-sized types in the standard library.

/// You may also implement this trait to enable cloning custom DSTs

/// (structures containing dynamically-sized fields), or use it as a supertrait to enable

/// cloning a [trait object].

///

/// This trait is normally used via operations on container types which support DSTs,

/// so you should not typically need to call `.clone_to_uninit()` explicitly except when

/// implementing such a container or otherwise performing explicit management of an allocation,

/// or when implementing `CloneToUninit` itself.

///

/// # Safety

///

/// Implementations must ensure that when `.clone_to_uninit(dest)` returns normally rather than

/// panicking, it always leaves `*dest` initialized as a valid value of type `Self`.

///

/// # Examples

///

// FIXME(#126799): when `Box::clone` allows use of `CloneToUninit`, rewrite these examples with it

// since `Rc` is a distraction.

///

/// If you are defining a trait, you can add `CloneToUninit` as a supertrait to enable cloning of

/// `dyn` values of your trait:

///

/// ```

/// #![feature(clone_to_uninit)]

/// use std::rc::Rc;

///

/// trait Foo: std::fmt::Debug + std::clone::CloneToUninit {

///     fn modify(&mut self);

///     fn value(&self) -> i32;

/// }

///

/// impl Foo for i32 {

///     fn modify(&mut self) {

///         *self *= 10;

///     }

///     fn value(&self) -> i32 {

///         *self

///     }

/// }

///

/// let first: Rc<dyn Foo> = Rc::new(1234);

///

/// let mut second = first.clone();

/// Rc::make_mut(&mut second).modify(); // make_mut() will call clone_to_uninit()

///

/// assert_eq!(first.value(), 1234);

/// assert_eq!(second.value(), 12340);

/// ```

///

/// The following is an example of implementing `CloneToUninit` for a custom DST.

/// (It is essentially a limited form of what `derive(CloneToUninit)` would do,

/// if such a derive macro existed.)

///

/// ```

/// #![feature(clone_to_uninit)]

/// use std::clone::CloneToUninit;

/// use std::mem::offset_of;

/// use std::rc::Rc;

///

/// #[derive(PartialEq)]

/// struct MyDst<T: ?Sized> {

///     label: String,

///     contents: T,

/// }

///

/// unsafe impl<T: ?Sized + CloneToUninit> CloneToUninit for MyDst<T> {

///     unsafe fn clone_to_uninit(&self, dest: *mut u8) {

///         // The offset of `self.contents` is dynamic because it depends on the alignment of T

///         // which can be dynamic (if `T = dyn SomeTrait`). Therefore, we have to obtain it

///         // dynamically by examining `self`, rather than using `offset_of!`.

///         //

///         // SAFETY: `self` by definition points somewhere before `&self.contents` in the same

///         // allocation.

///         let offset_of_contents = unsafe {

///             (&raw const self.contents).byte_offset_from_unsigned(self)

///         };

///

///         // Clone the *sized* fields of `self` (just one, in this example).

///         // (By cloning this first and storing it temporarily in a local variable, we avoid

///         // leaking it in case of any panic, using the ordinary automatic cleanup of local

///         // variables. Such a leak would be sound, but undesirable.)

///         let label = self.label.clone();

///

///         // SAFETY: The caller must provide a `dest` such that these field offsets are valid

///         // to write to.

///         unsafe {

///             // Clone the unsized field directly from `self` to `dest`.

///             self.contents.clone_to_uninit(dest.add(offset_of_contents));

///

///             // Now write all the sized fields.

///             //

///             // Note that we only do this once all of the clone() and clone_to_uninit() calls

///             // have completed, and therefore we know that there are no more possible panics;

///             // this ensures no memory leaks in case of panic.

///             dest.add(offset_of!(Self, label)).cast::<String>().write(label);

///         }

///         // All fields of the struct have been initialized; therefore, the struct is initialized,

///         // and we have satisfied our `unsafe impl CloneToUninit` obligations.

///     }

/// }

///

/// fn main() {

///     // Construct MyDst<[u8; 4]>, then coerce to MyDst<[u8]>.

///     let first: Rc<MyDst<[u8]>> = Rc::new(MyDst {

///         label: String::from("hello"),

///         contents: [1, 2, 3, 4],

///     });

///

///     let mut second = first.clone();

///     // make_mut() will call clone_to_uninit().

///     for elem in Rc::make_mut(&mut second).contents.iter_mut() {

///         *elem *= 10;

///     }

///

///     assert_eq!(first.contents, [1, 2, 3, 4]);

///     assert_eq!(second.contents, [10, 20, 30, 40]);

///     assert_eq!(second.label, "hello");

/// }

/// ```

///

/// # See Also

///

/// * [`Clone::clone_from`] is a safe function which may be used instead when [`Self: Sized`](Sized)

///   and the destination is already initialized; it may be able to reuse allocations owned by

///   the destination, whereas `clone_to_uninit` cannot, since its destination is assumed to be

///   uninitialized.

/// * [`ToOwned`], which allocates a new destination container.

///

/// [`ToOwned`]: ../../std/borrow/trait.ToOwned.html

/// [DST]: https://doc.rust-lang.org/reference/dynamically-sized-types.html

/// [trait object]: https://doc.rust-lang.org/reference/types/trait-object.html

#[unstable(feature = "clone_to_uninit", issue = "126799")]

#[cfg(not(feature = "ferrocene_certified"))]

pub unsafe trait CloneToUninit {

    /// Performs copy-assignment from `self` to `dest`.

    ///

    /// This is analogous to `std::ptr::write(dest.cast(), self.clone())`,

    /// except that `Self` may be a dynamically-sized type ([`!Sized`](Sized)).

    ///

    /// Before this function is called, `dest` may point to uninitialized memory.

    /// After this function is called, `dest` will point to initialized memory; it will be

    /// sound to create a `&Self` reference from the pointer with the [pointer metadata]

    /// from `self`.

    ///

    /// # Safety

    ///

    /// Behavior is undefined if any of the following conditions are violated:

    ///

    /// * `dest` must be [valid] for writes for `size_of_val(self)` bytes.

    /// * `dest` must be properly aligned to `align_of_val(self)`.

    ///

    /// [valid]: crate::ptr#safety

    /// [pointer metadata]: crate::ptr::metadata()

    ///

    /// # Panics

    ///

    /// This function may panic. (For example, it might panic if memory allocation for a clone

    /// of a value owned by `self` fails.)

    /// If the call panics, then `*dest` should be treated as uninitialized memory; it must not be

    /// read or dropped, because even if it was previously valid, it may have been partially

    /// overwritten.

    ///

    /// The caller may wish to take care to deallocate the allocation pointed to by `dest`,

    /// if applicable, to avoid a memory leak (but this is not a requirement).

    ///

    /// Implementors should avoid leaking values by, upon unwinding, dropping all component values

    /// that might have already been created. (For example, if a `[Foo]` of length 3 is being

    /// cloned, and the second of the three calls to `Foo::clone()` unwinds, then the first `Foo`

    /// cloned should be dropped.)

    unsafe fn clone_to_uninit(&self, dest: *mut u8);

}

#[unstable(feature = "clone_to_uninit", issue = "126799")]

#[cfg(not(feature = "ferrocene_certified"))]

unsafe impl<T: Clone> CloneToUninit for T {

    #[inline]

    unsafe fn clone_to_uninit(&self, dest: *mut u8) {

        // SAFETY: we're calling a specialization with the same contract

        unsafe { <T as self::uninit::CopySpec>::clone_one(self, dest.cast::<T>()) }

    }

}

#[unstable(feature = "clone_to_uninit", issue = "126799")]

#[cfg(not(feature = "ferrocene_certified"))]

unsafe impl<T: Clone> CloneToUninit for [T] {

    #[inline]

    #[cfg_attr(debug_assertions, track_caller)]

    unsafe fn clone_to_uninit(&self, dest: *mut u8) {

        let dest: *mut [T] = dest.with_metadata_of(self);

        // SAFETY: we're calling a specialization with the same contract

        unsafe { <T as self::uninit::CopySpec>::clone_slice(self, dest) }

    }

}

#[unstable(feature = "clone_to_uninit", issue = "126799")]

#[cfg(not(feature = "ferrocene_certified"))]

unsafe impl CloneToUninit for str {

    #[inline]

    #[cfg_attr(debug_assertions, track_caller)]

    unsafe fn clone_to_uninit(&self, dest: *mut u8) {

        // SAFETY: str is just a [u8] with UTF-8 invariant

        unsafe { self.as_bytes().clone_to_uninit(dest) }

    }

}

#[unstable(feature = "clone_to_uninit", issue = "126799")]

#[cfg(not(feature = "ferrocene_certified"))]

unsafe impl CloneToUninit for crate::ffi::CStr {

    #[cfg_attr(debug_assertions, track_caller)]

    unsafe fn clone_to_uninit(&self, dest: *mut u8) {

        // SAFETY: For now, CStr is just a #[repr(trasnsparent)] [c_char] with some invariants.

        // And we can cast [c_char] to [u8] on all supported platforms (see: to_bytes_with_nul).

        // The pointer metadata properly preserves the length (so NUL is also copied).

        // See: `cstr_metadata_is_length_with_nul` in tests.

        unsafe { self.to_bytes_with_nul().clone_to_uninit(dest) }

    }

}

#[unstable(feature = "bstr", issue = "134915")]

#[cfg(not(feature = "ferrocene_certified"))]

unsafe impl CloneToUninit for crate::bstr::ByteStr {

    #[inline]

    #[cfg_attr(debug_assertions, track_caller)]

    unsafe fn clone_to_uninit(&self, dst: *mut u8) {

        // SAFETY: ByteStr is a `#[repr(transparent)]` wrapper around `[u8]`

        unsafe { self.as_bytes().clone_to_uninit(dst) }

    }

}

/// Implementations of `Clone` for primitive types.

///

/// Implementations that cannot be described in Rust

/// are implemented in `traits::SelectionContext::copy_clone_conditions()`

/// in `rustc_trait_selection`.

mod impls {

    use crate::marker::PointeeSized;

    macro_rules! impl_clone {

        ($($t:ty)*) => {

            $(

                #[stable(feature = "rust1", since = "1.0.0")]

                impl Clone for $t {

                    #[inline(always)]

                }

            )*

        }

    }

    #[cfg(not(feature = "ferrocene_certified"))]

    impl_clone! {

        usize u8 u16 u32 u64 u128

        isize i8 i16 i32 i64 i128

        f16 f32 f64 f128

        bool char

    }

    #[cfg(feature = "ferrocene_certified")]

    impl_clone! {

        usize u8 u16 u32 u64 u128

        isize i8 i16 i32 i64 i128

        f32 f64

        bool

    }

    #[unstable(feature = "never_type", issue = "35121")]

    #[cfg(not(feature = "ferrocene_certified"))]

    impl Clone for ! {

        #[inline]

        fn clone(&self) -> Self {

            *self

        }

    }

    #[stable(feature = "rust1", since = "1.0.0")]

    impl<T: PointeeSized> Clone for *const T {

        #[inline(always)]

        fn clone(&self) -> Self {

            *self

        }

    }

    #[stable(feature = "rust1", since = "1.0.0")]

    impl<T: PointeeSized> Clone for *mut T {

        #[inline(always)]

        fn clone(&self) -> Self {

            *self

        }

    }

    /// Shared references can be cloned, but mutable references *cannot*!

    #[stable(feature = "rust1", since = "1.0.0")]

    impl<T: PointeeSized> Clone for &T {

        #[inline(always)]

        #[rustc_diagnostic_item = "noop_method_clone"]

    }

    /// Shared references can be cloned, but mutable references *cannot*!

    #[stable(feature = "rust1", since = "1.0.0")]

    #[cfg(not(feature = "ferrocene_certified"))]

    impl<T: PointeeSized> !Clone for &mut T {}

}