Types whose values can be duplicated simply by copying bits.

By default, variable bindings have ‘move semantics.’ In otherwords:

#[derive(Debug)]structFoo;letx = Foo;lety = x;// `x` has moved into `y`, and so cannot be used// println!("{x:?}"); // error: use of moved value

However, if a type implementsCopy, it instead has ‘copy semantics’:

// We can derive a `Copy` implementation. `Clone` is also required, as it's// a supertrait of `Copy`.#[derive(Debug, Copy, Clone)]structFoo;letx = Foo;lety = x;// `y` is a copy of `x`println!("{x:?}");// A-OK!

It’s important to note that in these two examples, the only difference is whether youare allowed to accessx after the assignment. Under the hood, both a copy and a movecan result in bits being copied in memory, although this is sometimes optimized away.

§How can I implementCopy?

There are two ways to implementCopy on your type. The simplest is to usederive:

#[derive(Copy, Clone)]structMyStruct;

You can also implementCopy andClone manually:

structMyStruct;implCopyforMyStruct { }implCloneforMyStruct {fnclone(&self) -> MyStruct {*self}}

There is a small difference between the two. Thederive strategy will also place aCopybound on type parameters:

#[derive(Clone)]structMyStruct<T>(T);impl<T: Copy> CopyforMyStruct<T> { }

This isn’t always desired. For example, shared references (&T) can be copied regardless ofwhetherT isCopy. Likewise, a generic struct containing markers such asPhantomDatacould potentially be duplicated with a bit-wise copy.

§What’s the difference betweenCopy andClone?

Copies happen implicitly, for example as part of an assignmenty = x. The behavior ofCopy is not overloadable; it is always a simple bit-wise copy.

Cloning is an explicit action,x.clone(). The implementation ofClone canprovide any type-specific behavior necessary to duplicate values safely. For example,the implementation ofClone forString needs to copy the pointed-to stringbuffer in the heap. A simple bitwise copy ofString values would merely copy thepointer, leading to a double free down the line. For this reason,String isClonebut notCopy.

Clone is a supertrait ofCopy, so everything which isCopy must also implementClone. If a type isCopy then itsClone implementation only needs to return*self(see the example above).

§When can my type beCopy?

A type can implementCopy if all of its components implementCopy. For example, thisstruct can beCopy:

#[derive(Copy, Clone)]structPoint {   x: i32,   y: i32,}

A struct can beCopy, andi32 isCopy, thereforePoint is eligible to beCopy.By contrast, consider

structPointList {    points: Vec<Point>,}

The structPointList cannot implementCopy, becauseVec<T> is notCopy. If weattempt to derive aCopy implementation, we’ll get an error:

the trait `Copy` cannot be implemented for this type; field `points` does not implement `Copy`

Shared references (&T) are alsoCopy, so a type can beCopy, even when it holdsshared references of typesT that arenotCopy. Consider the following struct,which can implementCopy, because it only holds ashared reference to our non-CopytypePointList from above:

#[derive(Copy, Clone)]structPointListWrapper<'a> {    point_list_ref:&'aPointList,}

§Whencan’t my type beCopy?

Some types can’t be copied safely. For example, copying&mut T would create an aliasedmutable reference. CopyingString would duplicate responsibility for managing theString’s buffer, leading to a double free.

Generalizing the latter case, any type implementingDrop can’t beCopy, because it’smanaging some resource besides its ownsize_of::<T> bytes.

If you try to implementCopy on a struct or enum containing non-Copy data, you will getthe errorE0204.

§Whenshould my type beCopy?

Generally speaking, if your typecan implementCopy, it should. Keep in mind, though,that implementingCopy is part of the public API of your type. If the type might becomenon-Copy in the future, it could be prudent to omit theCopy implementation now, toavoid a breaking API change.

§Additional implementors

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

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