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

Callingclone 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.SeeClone::clone for more details.

This distinction is especially important when using#[derive(Clone)] on structs containingsmart pointers likeArc<Mutex<T>> - the cloned struct will share mutable state with theoriginal.

Differs fromCopy in thatCopy is implicit and an inexpensive bit-wise copy, whileClone is always explicit and may or may not be expensive. In order to enforcethese characteristics, Rust does not allow you to reimplementCopy, but youmay reimplementClone and run arbitrary code.

SinceClone is more general thanCopy, you can automatically make anythingCopy beClone as well.

§Derivable

This trait can be used with#[derive] if all fields areClone. Thederivedimplementation ofClone callsclone on each field.

For a generic struct,#[derive] implementsClone conditionally by adding boundClone ongeneric parameters.

// `derive` implements Clone for Reading<T> when T is Clone.#[derive(Clone)]structReading<T> {    frequency: T,}

§How can I implementClone?

Types that areCopy should have a trivial implementation ofClone. More formally:ifT: Copy,x: T, andy: &T, thenlet x = y.clone(); is equivalent tolet x = *y;.Manual implementations should be careful to uphold this invariant; however, unsafe codemust not rely on it to ensure memory safety.

An example is a generic struct holding a function pointer. In this case, theimplementation ofClone cannot bederived, but can be implemented as:

structGenerate<T>(fn() -> T);impl<T> CopyforGenerate<T> {}impl<T> CloneforGenerate<T> {fnclone(&self) ->Self{*self}}

If wederive:

#[derive(Copy, Clone)]structGenerate<T>(fn() -> T);

the auto-derived implementations will have unnecessaryT: Copy andT: Clone bounds:

// Automatically derivedimpl<T: Copy> CopyforGenerate<T> { }// Automatically derivedimpl<T: Clone> CloneforGenerate<T> {fnclone(&self) -> Generate<T> {        Generate(Clone::clone(&self.0))    }}

The bounds are unnecessary because clearly the function itself should becopy- and cloneable even if its return type is not:

#[derive(Copy, Clone)]structGenerate<T>(fn() -> T);structNotCloneable;fngenerate_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 andPartialEq/Eq

Clone is intended for the duplication of objects. Consequently, when implementingbothClone andPartialEq, the following property is expected to hold:

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 implementEq – for whichx == x always holds –this implies thatx.clone() == x must always be true.Standard library collections such asHashMap,HashSet,BTreeMap,BTreeSet andBinaryHeaprely on their keys respecting this property for correct behavior.Furthermore, these collections require that cloning a key preserves the outcome of theHash andOrd methods. Thankfully, this follows automatically fromx.clone() == xifHash andOrd are correctly implemented according to their own requirements.

When deriving bothClone andPartialEq using#[derive(Clone, PartialEq)]or when additionally derivingEq using#[derive(Clone, PartialEq, Eq)],then this property is automatically upheld – provided that it is satisfied bythe underlying types.

Violating this property is a logic error. The behavior resulting from a logic error is notspecified, but users of the trait must ensure that such logic errors donot result inundefined behavior. This means thatunsafe codemust not rely on this propertybeing satisfied.

§Additional implementors

In addition to theimplementors listed below,the following types also implementClone:

• 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 environmentor if all such captured values implementClone themselves.Note that variables captured by shared reference always implementClone(even if the referent doesn’t),while variables captured by mutable reference never implementClone.