Trait core::marker::Copy1.0.0 [−] [src]

pub trait Copy: Clone { }

Types that can be copied by simply copying bits (i.e. memcpy).

By default, variable bindings have 'move semantics.' In other words:

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

let x = Foo;

let y = x;

// `x` has moved into `y`, and so cannot be used

// println!("{:?}", x); // error: use of moved value

However, if a type implements Copy, it instead has 'copy semantics':

fn main() { // we can just derive a `Copy` implementation #[derive(Debug, Copy, Clone)] struct Foo; let x = Foo; let y = x; // `y` is a copy of `x` println!("{:?}", x); // A-OK! }
// we can just derive a `Copy` implementation
#[derive(Debug, Copy, Clone)]
struct Foo;

let x = Foo;

let y = 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 if you are allowed to access x after the assignment: a move is also a bitwise copy under the hood.

When can my type be Copy?

A type can implement Copy if all of its components implement Copy. For example, this struct can be Copy:

fn main() { #[allow(dead_code)] struct Point { x: i32, y: i32, } }
struct Point {
   x: i32,
   y: i32,
}

A struct can be Copy, and i32 is Copy, so therefore, Point is eligible to be Copy.

fn main() { #![allow(dead_code)] struct Point; struct PointList { points: Vec<Point>, } }
struct PointList {
    points: Vec<Point>,
}

The PointList struct cannot implement Copy, because Vec<T> is not Copy. If we attempt to derive a Copy implementation, we'll get an error:

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

When can my type not be Copy?

Some types can't be copied safely. For example, copying &mut T would create an aliased mutable reference, and copying String would result in two attempts to free the same buffer.

Generalizing the latter case, any type implementing Drop can't be Copy, because it's managing some resource besides its own size_of::<T>() bytes.

When should my type be Copy?

Generally speaking, if your type can implement Copy, it should. There's one important thing to consider though: if you think your type may not be able to implement Copy in the future, then it might be prudent to not implement Copy. This is because removing Copy is a breaking change: that second example would fail to compile if we made Foo non-Copy.

Derivable

This trait can be used with #[derive] if all of its components implement Copy and the type implements Clone. The implementation will copy the bytes of each field using memcpy.

How can I implement Copy?

There are two ways to implement Copy on your type:

fn main() { #[derive(Copy, Clone)] struct MyStruct; }
#[derive(Copy, Clone)]
struct MyStruct;

and

fn main() { struct MyStruct; impl Copy for MyStruct {} impl Clone for MyStruct { fn clone(&self) -> MyStruct { *self } } }
struct MyStruct;
impl Copy for MyStruct {}
impl Clone for MyStruct { fn clone(&self) -> MyStruct { *self } }

There is a small difference between the two: the derive strategy will also place a Copy bound on type parameters, which isn't always desired.

Implementors