1//! The `Clone` trait for types that cannot be 'implicitly copied'.2//!3//! In Rust, some simple types are "implicitly copyable" and when you4//! assign them or pass them as arguments, the receiver will get a copy,5//! leaving the original value in place. These types do not require6//! allocation to copy and do not have finalizers (i.e., they do not7//! contain owned boxes or implement [`Drop`]), so the compiler considers8//! them cheap and safe to copy. For other types copies must be made9//! explicitly, by convention implementing the [`Clone`] trait and calling10//! the [`clone`] method.11//!12//! [`clone`]: Clone::clone13//!14//! Basic usage example:15//!16//! ```17//! let s = String::new(); // String type implements Clone18//! let copy = s.clone(); // so we can clone it19//! ```20//!21//! To easily implement the Clone trait, you can also use22//! `#[derive(Clone)]`. Example:23//!24//! ```25//! #[derive(Clone)] // we add the Clone trait to Morpheus struct26//! struct Morpheus {27//! blue_pill: f32,28//! red_pill: i64,29//! }30//!31//! fn main() {32//! let f = Morpheus { blue_pill: 0.0, red_pill: 0 };33//! let copy = f.clone(); // and now we can clone it!34//! }35//! ```3637#![stable(feature ="rust1", since ="1.0.0")]3839usecrate::marker::{Destruct, PointeeSized};4041moduninit;4243/// A common trait that allows explicit creation of a duplicate value.44///45/// Calling [`clone`] always produces a new value.46/// However, for types that are references to other data (such as smart pointers or references),47/// the new value may still point to the same underlying data, rather than duplicating it.48/// See [`Clone::clone`] for more details.49///50/// This distinction is especially important when using `#[derive(Clone)]` on structs containing51/// smart pointers like `Arc<Mutex<T>>` - the cloned struct will share mutable state with the52/// original.53///54/// Differs from [`Copy`] in that [`Copy`] is implicit and an inexpensive bit-wise copy, while55/// `Clone` is always explicit and may or may not be expensive. In order to enforce56/// these characteristics, Rust does not allow you to reimplement [`Copy`], but you57/// may reimplement `Clone` and run arbitrary code.58///59/// Since `Clone` is more general than [`Copy`], you can automatically make anything60/// [`Copy`] be `Clone` as well.61///62/// ## Derivable63///64/// This trait can be used with `#[derive]` if all fields are `Clone`. The `derive`d65/// implementation of [`Clone`] calls [`clone`] on each field.66///67/// [`clone`]: Clone::clone68///69/// For a generic struct, `#[derive]` implements `Clone` conditionally by adding bound `Clone` on70/// generic parameters.71///72/// ```73/// // `derive` implements Clone for Reading<T> when T is Clone.74/// #[derive(Clone)]75/// struct Reading<T> {76/// frequency: T,77/// }78/// ```79///80/// ## How can I implement `Clone`?81///82/// Types that are [`Copy`] should have a trivial implementation of `Clone`. More formally:83/// if `T: Copy`, `x: T`, and `y: &T`, then `let x = y.clone();` is equivalent to `let x = *y;`.84/// Manual implementations should be careful to uphold this invariant; however, unsafe code85/// must not rely on it to ensure memory safety.86///87/// An example is a generic struct holding a function pointer. In this case, the88/// implementation of `Clone` cannot be `derive`d, but can be implemented as:89///90/// ```91/// struct Generate<T>(fn() -> T);92///93/// impl<T> Copy for Generate<T> {}94///95/// impl<T> Clone for Generate<T> {96/// fn clone(&self) -> Self {97/// *self98/// }99/// }100/// ```101///102/// If we `derive`:103///104/// ```105/// #[derive(Copy, Clone)]106/// struct Generate<T>(fn() -> T);107/// ```108///109/// the auto-derived implementations will have unnecessary `T: Copy` and `T: Clone` bounds:110///111/// ```112/// # struct Generate<T>(fn() -> T);113///114/// // Automatically derived115/// impl<T: Copy> Copy for Generate<T> { }116///117/// // Automatically derived118/// impl<T: Clone> Clone for Generate<T> {119/// fn clone(&self) -> Generate<T> {120/// Generate(Clone::clone(&self.0))121/// }122/// }123/// ```124///125/// The bounds are unnecessary because clearly the function itself should be126/// copy- and cloneable even if its return type is not:127///128/// ```compile_fail,E0599129/// #[derive(Copy, Clone)]130/// struct Generate<T>(fn() -> T);131///132/// struct NotCloneable;133///134/// fn generate_not_cloneable() -> NotCloneable {135/// NotCloneable136/// }137///138/// Generate(generate_not_cloneable).clone(); // error: trait bounds were not satisfied139/// // Note: With the manual implementations the above line will compile.140/// ```141///142/// ## `Clone` and `PartialEq`/`Eq`143/// `Clone` is intended for the duplication of objects. Consequently, when implementing144/// both `Clone` and [`PartialEq`], the following property is expected to hold:145/// ```text146/// x == x -> x.clone() == x147/// ```148/// In other words, if an object compares equal to itself,149/// its clone must also compare equal to the original.150///151/// For types that also implement [`Eq`] – for which `x == x` always holds –152/// this implies that `x.clone() == x` must always be true.153/// Standard library collections such as154/// [`HashMap`], [`HashSet`], [`BTreeMap`], [`BTreeSet`] and [`BinaryHeap`]155/// rely on their keys respecting this property for correct behavior.156/// Furthermore, these collections require that cloning a key preserves the outcome of the157/// [`Hash`] and [`Ord`] methods. Thankfully, this follows automatically from `x.clone() == x`158/// if `Hash` and `Ord` are correctly implemented according to their own requirements.159///160/// When deriving both `Clone` and [`PartialEq`] using `#[derive(Clone, PartialEq)]`161/// or when additionally deriving [`Eq`] using `#[derive(Clone, PartialEq, Eq)]`,162/// then this property is automatically upheld – provided that it is satisfied by163/// the underlying types.164///165/// Violating this property is a logic error. The behavior resulting from a logic error is not166/// specified, but users of the trait must ensure that such logic errors do *not* result in167/// undefined behavior. This means that `unsafe` code **must not** rely on this property168/// being satisfied.169///170/// ## Additional implementors171///172/// In addition to the [implementors listed below][impls],173/// the following types also implement `Clone`:174///175/// * Function item types (i.e., the distinct types defined for each function)176/// * Function pointer types (e.g., `fn() -> i32`)177/// * Closure types, if they capture no value from the environment178/// or if all such captured values implement `Clone` themselves.179/// Note that variables captured by shared reference always implement `Clone`180/// (even if the referent doesn't),181/// while variables captured by mutable reference never implement `Clone`.182///183/// [`HashMap`]: ../../std/collections/struct.HashMap.html184/// [`HashSet`]: ../../std/collections/struct.HashSet.html185/// [`BTreeMap`]: ../../std/collections/struct.BTreeMap.html186/// [`BTreeSet`]: ../../std/collections/struct.BTreeSet.html187/// [`BinaryHeap`]: ../../std/collections/struct.BinaryHeap.html188/// [impls]: #implementors189#[stable(feature ="rust1", since ="1.0.0")]190#[lang ="clone"]191#[rustc_diagnostic_item ="Clone"]192#[rustc_trivial_field_reads]193#[rustc_const_unstable(feature ="const_clone", issue ="142757")]194pub const traitClone: Sized {195/// Returns a duplicate of the value.196 ///197 /// Note that what "duplicate" means varies by type:198 /// - For most types, this creates a deep, independent copy199 /// - For reference types like `&T`, this creates another reference to the same value200 /// - For smart pointers like [`Arc`] or [`Rc`], this increments the reference count201 /// but still points to the same underlying data202 ///203 /// [`Arc`]: ../../std/sync/struct.Arc.html204 /// [`Rc`]: ../../std/rc/struct.Rc.html205 ///206 /// # Examples207 ///208 /// ```209 /// # #![allow(noop_method_call)]210 /// let hello = "Hello"; // &str implements Clone211 ///212 /// assert_eq!("Hello", hello.clone());213 /// ```214 ///215 /// Example with a reference-counted type:216 ///217 /// ```218 /// use std::sync::{Arc, Mutex};219 ///220 /// let data = Arc::new(Mutex::new(vec![1, 2, 3]));221 /// let data_clone = data.clone(); // Creates another Arc pointing to the same Mutex222 ///223 /// {224 /// let mut lock = data.lock().unwrap();225 /// lock.push(4);226 /// }227 ///228 /// // Changes are visible through the clone because they share the same underlying data229 /// assert_eq!(*data_clone.lock().unwrap(), vec![1, 2, 3, 4]);230 /// ```231#[stable(feature ="rust1", since ="1.0.0")]232 #[must_use ="cloning is often expensive and is not expected to have side effects"]233// Clone::clone is special because the compiler generates MIR to implement it for some types.234 // See InstanceKind::CloneShim.235#[lang ="clone_fn"]236fnclone(&self) ->Self;237238/// Performs copy-assignment from `source`.239 ///240 /// `a.clone_from(&b)` is equivalent to `a = b.clone()` in functionality,241 /// but can be overridden to reuse the resources of `a` to avoid unnecessary242 /// allocations.243#[inline]244 #[stable(feature ="rust1", since ="1.0.0")]245fnclone_from(&mutself, source:&Self)246where247Self: [const] Destruct,248 {249*self= source.clone()250 }251}252253/// Derive macro generating an impl of the trait `Clone`.254#[rustc_builtin_macro]255#[stable(feature ="builtin_macro_prelude", since ="1.38.0")]256#[allow_internal_unstable(core_intrinsics, derive_clone_copy)]257pub macroClone($item:item) {258/* compiler built-in */259}260261/// Trait for objects whose [`Clone`] impl is lightweight (e.g. reference-counted)262///263/// Cloning an object implementing this trait should in general:264/// - be O(1) (constant) time regardless of the amount of data managed by the object,265/// - not require a memory allocation,266/// - not require copying more than roughly 64 bytes (a typical cache line size),267/// - not block the current thread,268/// - not have any semantic side effects (e.g. allocating a file descriptor), and269/// - not have overhead larger than a couple of atomic operations.270///271/// The `UseCloned` trait does not provide a method; instead, it indicates that272/// `Clone::clone` is lightweight, and allows the use of the `.use` syntax.273///274/// ## .use postfix syntax275///276/// Values can be `.use`d by adding `.use` postfix to the value you want to use.277///278/// ```ignore (this won't work until we land use)279/// fn foo(f: Foo) {280/// // if `Foo` implements `Copy` f would be copied into x.281/// // if `Foo` implements `UseCloned` f would be cloned into x.282/// // otherwise f would be moved into x.283/// let x = f.use;284/// // ...285/// }286/// ```287///288/// ## use closures289///290/// Use closures allow captured values to be automatically used.291/// This is similar to have a closure that you would call `.use` over each captured value.292#[unstable(feature ="ergonomic_clones", issue ="132290")]293#[lang ="use_cloned"]294pub traitUseCloned: Clone {295// Empty.296}297298macro_rules! impl_use_cloned {299 ($($t:ty)*) => {300 $(301#[unstable(feature ="ergonomic_clones", issue ="132290")]302implUseClonedfor$t{}303 )*304 }305}306307impl_use_cloned! {308 usize u8 u16 u32 u64 u128309 isize i8 i16 i32 i64 i128310 f16 f32 f64 f128311 bool char312}313314// FIXME(aburka): these structs are used solely by #[derive] to315// assert that every component of a type implements Clone or Copy.316//317// These structs should never appear in user code.318#[doc(hidden)]319#[allow(missing_debug_implementations)]320#[unstable(321 feature ="derive_clone_copy",322 reason ="deriving hack, should not be public",323 issue ="none"324)]325pub structAssertParamIsClone<T: Clone + PointeeSized> {326 _field:crate::marker::PhantomData<T>,327}328#[doc(hidden)]329#[allow(missing_debug_implementations)]330#[unstable(331 feature ="derive_clone_copy",332 reason ="deriving hack, should not be public",333 issue ="none"334)]335pub structAssertParamIsCopy<T: Copy + PointeeSized> {336 _field:crate::marker::PhantomData<T>,337}338339/// A generalization of [`Clone`] to [dynamically-sized types][DST] stored in arbitrary containers.340///341/// This trait is implemented for all types implementing [`Clone`], [slices](slice) of all342/// such types, and other dynamically-sized types in the standard library.343/// You may also implement this trait to enable cloning custom DSTs344/// (structures containing dynamically-sized fields), or use it as a supertrait to enable345/// cloning a [trait object].346///347/// This trait is normally used via operations on container types which support DSTs,348/// so you should not typically need to call `.clone_to_uninit()` explicitly except when349/// implementing such a container or otherwise performing explicit management of an allocation,350/// or when implementing `CloneToUninit` itself.351///352/// # Safety353///354/// Implementations must ensure that when `.clone_to_uninit(dest)` returns normally rather than355/// panicking, it always leaves `*dest` initialized as a valid value of type `Self`.356///357/// # Examples358///359// FIXME(#126799): when `Box::clone` allows use of `CloneToUninit`, rewrite these examples with it360// since `Rc` is a distraction.361///362/// If you are defining a trait, you can add `CloneToUninit` as a supertrait to enable cloning of363/// `dyn` values of your trait:364///365/// ```366/// #![feature(clone_to_uninit)]367/// use std::rc::Rc;368///369/// trait Foo: std::fmt::Debug + std::clone::CloneToUninit {370/// fn modify(&mut self);371/// fn value(&self) -> i32;372/// }373///374/// impl Foo for i32 {375/// fn modify(&mut self) {376/// *self *= 10;377/// }378/// fn value(&self) -> i32 {379/// *self380/// }381/// }382///383/// let first: Rc<dyn Foo> = Rc::new(1234);384///385/// let mut second = first.clone();386/// Rc::make_mut(&mut second).modify(); // make_mut() will call clone_to_uninit()387///388/// assert_eq!(first.value(), 1234);389/// assert_eq!(second.value(), 12340);390/// ```391///392/// The following is an example of implementing `CloneToUninit` for a custom DST.393/// (It is essentially a limited form of what `derive(CloneToUninit)` would do,394/// if such a derive macro existed.)395///396/// ```397/// #![feature(clone_to_uninit)]398/// use std::clone::CloneToUninit;399/// use std::mem::offset_of;400/// use std::rc::Rc;401///402/// #[derive(PartialEq)]403/// struct MyDst<T: ?Sized> {404/// label: String,405/// contents: T,406/// }407///408/// unsafe impl<T: ?Sized + CloneToUninit> CloneToUninit for MyDst<T> {409/// unsafe fn clone_to_uninit(&self, dest: *mut u8) {410/// // The offset of `self.contents` is dynamic because it depends on the alignment of T411/// // which can be dynamic (if `T = dyn SomeTrait`). Therefore, we have to obtain it412/// // dynamically by examining `self`, rather than using `offset_of!`.413/// //414/// // SAFETY: `self` by definition points somewhere before `&self.contents` in the same415/// // allocation.416/// let offset_of_contents = unsafe {417/// (&raw const self.contents).byte_offset_from_unsigned(self)418/// };419///420/// // Clone the *sized* fields of `self` (just one, in this example).421/// // (By cloning this first and storing it temporarily in a local variable, we avoid422/// // leaking it in case of any panic, using the ordinary automatic cleanup of local423/// // variables. Such a leak would be sound, but undesirable.)424/// let label = self.label.clone();425///426/// // SAFETY: The caller must provide a `dest` such that these field offsets are valid427/// // to write to.428/// unsafe {429/// // Clone the unsized field directly from `self` to `dest`.430/// self.contents.clone_to_uninit(dest.add(offset_of_contents));431///432/// // Now write all the sized fields.433/// //434/// // Note that we only do this once all of the clone() and clone_to_uninit() calls435/// // have completed, and therefore we know that there are no more possible panics;436/// // this ensures no memory leaks in case of panic.437/// dest.add(offset_of!(Self, label)).cast::<String>().write(label);438/// }439/// // All fields of the struct have been initialized; therefore, the struct is initialized,440/// // and we have satisfied our `unsafe impl CloneToUninit` obligations.441/// }442/// }443///444/// fn main() {445/// // Construct MyDst<[u8; 4]>, then coerce to MyDst<[u8]>.446/// let first: Rc<MyDst<[u8]>> = Rc::new(MyDst {447/// label: String::from("hello"),448/// contents: [1, 2, 3, 4],449/// });450///451/// let mut second = first.clone();452/// // make_mut() will call clone_to_uninit().453/// for elem in Rc::make_mut(&mut second).contents.iter_mut() {454/// *elem *= 10;455/// }456///457/// assert_eq!(first.contents, [1, 2, 3, 4]);458/// assert_eq!(second.contents, [10, 20, 30, 40]);459/// assert_eq!(second.label, "hello");460/// }461/// ```462///463/// # See Also464///465/// * [`Clone::clone_from`] is a safe function which may be used instead when [`Self: Sized`](Sized)466/// and the destination is already initialized; it may be able to reuse allocations owned by467/// the destination, whereas `clone_to_uninit` cannot, since its destination is assumed to be468/// uninitialized.469/// * [`ToOwned`], which allocates a new destination container.470///471/// [`ToOwned`]: ../../std/borrow/trait.ToOwned.html472/// [DST]: https://doc.rust-lang.org/reference/dynamically-sized-types.html473/// [trait object]: https://doc.rust-lang.org/reference/types/trait-object.html474#[unstable(feature ="clone_to_uninit", issue ="126799")]475pub unsafe traitCloneToUninit {476/// Performs copy-assignment from `self` to `dest`.477 ///478 /// This is analogous to `std::ptr::write(dest.cast(), self.clone())`,479 /// except that `Self` may be a dynamically-sized type ([`!Sized`](Sized)).480 ///481 /// Before this function is called, `dest` may point to uninitialized memory.482 /// After this function is called, `dest` will point to initialized memory; it will be483 /// sound to create a `&Self` reference from the pointer with the [pointer metadata]484 /// from `self`.485 ///486 /// # Safety487 ///488 /// Behavior is undefined if any of the following conditions are violated:489 ///490 /// * `dest` must be [valid] for writes for `size_of_val(self)` bytes.491 /// * `dest` must be properly aligned to `align_of_val(self)`.492 ///493 /// [valid]: crate::ptr#safety494 /// [pointer metadata]: crate::ptr::metadata()495 ///496 /// # Panics497 ///498 /// This function may panic. (For example, it might panic if memory allocation for a clone499 /// of a value owned by `self` fails.)500 /// If the call panics, then `*dest` should be treated as uninitialized memory; it must not be501 /// read or dropped, because even if it was previously valid, it may have been partially502 /// overwritten.503 ///504 /// The caller may wish to take care to deallocate the allocation pointed to by `dest`,505 /// if applicable, to avoid a memory leak (but this is not a requirement).506 ///507 /// Implementors should avoid leaking values by, upon unwinding, dropping all component values508 /// that might have already been created. (For example, if a `[Foo]` of length 3 is being509 /// cloned, and the second of the three calls to `Foo::clone()` unwinds, then the first `Foo`510 /// cloned should be dropped.)511unsafe fnclone_to_uninit(&self, dest:*mutu8);512}513514#[unstable(feature ="clone_to_uninit", issue ="126799")]515unsafe impl<T: Clone> CloneToUninitforT {516#[inline]517unsafe fnclone_to_uninit(&self, dest:*mutu8) {518// SAFETY: we're calling a specialization with the same contract519unsafe{ <Tasself::uninit::CopySpec>::clone_one(self, dest.cast::<T>()) }520 }521}522523#[unstable(feature ="clone_to_uninit", issue ="126799")]524unsafe impl<T: Clone> CloneToUninitfor[T] {525#[inline]526 #[cfg_attr(debug_assertions, track_caller)]527unsafe fnclone_to_uninit(&self, dest:*mutu8) {528letdest:*mut[T] = dest.with_metadata_of(self);529// SAFETY: we're calling a specialization with the same contract530unsafe{ <Tasself::uninit::CopySpec>::clone_slice(self, dest) }531 }532}533534#[unstable(feature ="clone_to_uninit", issue ="126799")]535unsafe implCloneToUninitforstr {536#[inline]537 #[cfg_attr(debug_assertions, track_caller)]538unsafe fnclone_to_uninit(&self, dest:*mutu8) {539// SAFETY: str is just a [u8] with UTF-8 invariant540unsafe{self.as_bytes().clone_to_uninit(dest) }541 }542}543544#[unstable(feature ="clone_to_uninit", issue ="126799")]545unsafe implCloneToUninitforcrate::ffi::CStr {546#[cfg_attr(debug_assertions, track_caller)]547unsafe fnclone_to_uninit(&self, dest:*mutu8) {548// SAFETY: For now, CStr is just a #[repr(trasnsparent)] [c_char] with some invariants.549 // And we can cast [c_char] to [u8] on all supported platforms (see: to_bytes_with_nul).550 // The pointer metadata properly preserves the length (so NUL is also copied).551 // See: `cstr_metadata_is_length_with_nul` in tests.552unsafe{self.to_bytes_with_nul().clone_to_uninit(dest) }553 }554}555556#[unstable(feature ="bstr", issue ="134915")]557unsafe implCloneToUninitforcrate::bstr::ByteStr {558#[inline]559 #[cfg_attr(debug_assertions, track_caller)]560unsafe fnclone_to_uninit(&self, dst:*mutu8) {561// SAFETY: ByteStr is a `#[repr(transparent)]` wrapper around `[u8]`562unsafe{self.as_bytes().clone_to_uninit(dst) }563 }564}565566/// Implementations of `Clone` for primitive types.567///568/// Implementations that cannot be described in Rust569/// are implemented in `traits::SelectionContext::copy_clone_conditions()`570/// in `rustc_trait_selection`.571modimpls {572usecrate::marker::PointeeSized;573574macro_rules! impl_clone {575 ($($t:ty)*) => {576 $(577#[stable(feature ="rust1", since ="1.0.0")]578 #[rustc_const_unstable(feature ="const_clone", issue ="142757")]579impl constClonefor$t{580#[inline(always)]581fnclone(&self) ->Self{582*self583}584 }585 )*586 }587 }588589impl_clone! {590 usize u8 u16 u32 u64 u128591 isize i8 i16 i32 i64 i128592 f16 f32 f64 f128593 bool char594 }595596#[unstable(feature ="never_type", issue ="35121")]597 #[rustc_const_unstable(feature ="const_clone", issue ="142757")]598impl constClonefor ! {599#[inline]600fnclone(&self) ->Self{601*self602}603 }604605#[stable(feature ="rust1", since ="1.0.0")]606 #[rustc_const_unstable(feature ="const_clone", issue ="142757")]607impl<T: PointeeSized>constClonefor*constT {608#[inline(always)]609fnclone(&self) ->Self{610*self611}612 }613614#[stable(feature ="rust1", since ="1.0.0")]615 #[rustc_const_unstable(feature ="const_clone", issue ="142757")]616impl<T: PointeeSized>constClonefor*mutT {617#[inline(always)]618fnclone(&self) ->Self{619*self620}621 }622623/// Shared references can be cloned, but mutable references *cannot*!624#[stable(feature ="rust1", since ="1.0.0")]625 #[rustc_const_unstable(feature ="const_clone", issue ="142757")]626impl<T: PointeeSized>constClonefor&T {627#[inline(always)]628 #[rustc_diagnostic_item ="noop_method_clone"]629fnclone(&self) ->Self{630self631}632 }633634/// Shared references can be cloned, but mutable references *cannot*!635#[stable(feature ="rust1", since ="1.0.0")]636impl<T: PointeeSized> !Clonefor&mutT {}637}