Trait std::marker::Copy

#[lang = "copy"]
pub trait Copy: Clone { }

Types whose values can be duplicated simply by copying bits.

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

#[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':

// We can derive a `Copy` implementation. `Clone` is also required, as it's
// a supertrait of `Copy`.
#[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 whether you are allowed to access x after the assignment. Under the hood, both a copy and a move can result in bits being copied in memory, although this is sometimes optimized away.

How can I implement Copy?

There are two ways to implement Copy on your type. The simplest is to use derive:

#[derive(Copy, Clone)]
struct MyStruct;

You can also implement Copy and Clone manually:

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.

What's the difference between Copy and Clone?

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

Cloning is an explicit action, x.clone(). The implementation of Clone can provide any type-specific behavior necessary to duplicate values safely. For example, the implementation of Clone for String needs to copy the pointed-to string buffer in the heap. A simple bitwise copy of String values would merely copy the pointer, leading to a double free down the line. For this reason, String is Clone but not Copy.

Clone is a supertrait of Copy, so everything which is Copy must also implement Clone. If a type is Copy then its Clone implementation only needs to return *self (see the example above).

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:

struct Point {
   x: i32,
   y: i32,
}

A struct can be Copy, and i32 is Copy, therefore Point is eligible to be Copy. By contrast, consider

struct PointList {
    points: Vec<Point>,
}

The struct PointList 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't my type be Copy?

Some types can't be copied safely. For example, copying &mut T would create an aliased mutable reference. Copying String would duplicate responsibility for managing the String's buffer, leading to a double free.

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.

If you try to implement Copy on a struct or enum containing non-Copy data, you will get the error E0204.

When should my type be Copy?

Generally speaking, if your type can implement Copy, it should. Keep in mind, though, that implementing Copy is part of the public API of your type. If the type might become non-Copy in the future, it could be prudent to omit the Copy implementation now, to avoid a breaking API change.

Implementations on Foreign Types

impl Copy for Isaac64Rng

impl Copy for Exp

impl Copy for LogNormal

impl Copy for IsaacRng

impl Copy for ReseedWithDefault

impl Copy for Normal

impl Copy for StandardNormal

impl Copy for ChaChaRng

impl Copy for Exp1

impl Copy for _Unwind_Reason_Code

impl Copy for _Unwind_Action

impl<T> Copy for NonZero<T> where
    T: Zeroable + Copy, 

impl Copy for pthread_attr_t

impl Copy for timeval

impl Copy for linger

impl Copy for pthread_mutexattr_t

impl Copy for mcontext_t

impl Copy for ipc_perm

impl Copy for ff_envelope

impl Copy for rlimit

impl Copy for epoll_event

impl Copy for ff_rumble_effect

impl Copy for ff_ramp_effect

impl Copy for winsize

impl Copy for stat

impl Copy for sysinfo

impl Copy for addrinfo

impl Copy for rlimit64

impl Copy for _libc_xmmreg

impl Copy for sockaddr_nl

impl Copy for pthread_cond_t

impl Copy for __timeval

impl Copy for ff_replay

impl Copy for iovec

impl Copy for sem_t

impl Copy for termios

impl Copy for sockaddr_in6

impl Copy for ifaddrs

impl Copy for input_event

impl Copy for ip_mreq

impl Copy for sigevent

impl Copy for user

impl Copy for input_keymap_entry

impl Copy for in6_addr

impl Copy for user_regs_struct

impl Copy for glob64_t

impl Copy for stack_t

impl Copy for sigval

impl Copy for ipv6_mreq

impl Copy for ucontext_t

impl Copy for ff_constant_effect

impl Copy for stat64

impl Copy for fd_set

impl Copy for siginfo_t

impl Copy for statvfs

impl Copy for timespec

impl Copy for in_addr

impl Copy for utmpx

impl Copy for pthread_rwlockattr_t

impl Copy for if_nameindex

impl Copy for itimerval

impl Copy for sockaddr_ll

impl Copy for msginfo

impl Copy for pthread_rwlock_t

impl Copy for cmsghdr

impl Copy for sockaddr

impl Copy for dqblk

impl Copy for glob_t

impl Copy for sembuf

impl Copy for pollfd

impl Copy for signalfd_siginfo

impl Copy for sigaction

impl Copy for hostent

impl Copy for user_fpregs_struct

impl Copy for __exit_status

impl Copy for msghdr

impl Copy for tms

impl Copy for rusage

impl Copy for _libc_fpstate

impl Copy for flock

impl Copy for dirent64

impl Copy for aiocb

impl Copy for sigset_t

impl Copy for cpu_set_t

impl Copy for fsid_t

impl Copy for dirent

impl Copy for input_id

impl Copy for msqid_ds

impl Copy for sockaddr_storage

impl Copy for group

impl Copy for ff_effect

impl Copy for ff_trigger

impl Copy for sched_param

impl Copy for mq_attr

impl Copy for _libc_fpxreg

impl Copy for statfs64

impl Copy for ff_condition_effect

impl Copy for input_mask

impl Copy for mmsghdr

impl Copy for utsname

impl Copy for sockaddr_in

impl Copy for ff_periodic_effect

impl Copy for pthread_mutex_t

impl Copy for Dl_info

impl Copy for utimbuf

impl Copy for statfs

impl Copy for sockaddr_un

impl Copy for pthread_condattr_t

impl Copy for passwd

impl Copy for lconv

impl Copy for spwd

impl Copy for tm

impl Copy for shmid_ds

impl Copy for statvfs64

impl Copy for ucred

impl Copy for input_absinfo

Implementors

• impl<Y, R> Copy for GeneratorState<Y, R> where
    R: Copy,
    Y: Copy, 
• impl<T> Copy for Wrapping<T> where
    T: Copy, 
• impl Copy for Error
• impl Copy for FpCategory
• impl Copy for TypeId
• impl<T> Copy for Option<T> where
    T: Copy, 
• impl<T, E> Copy for Result<T, E> where
    E: Copy,
    T: Copy, 
• impl<T> Copy for Unique<T> where
    T: ?Sized, 
• impl Copy for std::sync::atomic::Ordering
• impl Copy for TryFromIntError
• impl Copy for RangeFull
• impl<'a> Copy for Arguments<'a>
• impl Copy for std::cmp::Ordering
• impl Copy for TraitObject
• impl<T> Copy for Discriminant<T>
• impl<Idx> Copy for RangeToInclusive<Idx> where
    Idx: Copy, 
• impl Copy for SearchStep
• impl Copy for CharTryFromError
• impl Copy for Utf8Error
• impl<T> Copy for Shared<T> where
    T: ?Sized, 
• impl<T> Copy for PhantomData<T> where
    T: ?Sized, 
• impl<Idx> Copy for RangeTo<Idx> where
    Idx: Copy, 
• impl Copy for ParseError
• impl Copy for Heap
• impl<T> Copy for Bound<T> where
    T: Copy, 
• impl Copy for ExchangeHeapSingleton
• impl Copy for LocalKeyState
• impl Copy for ThreadId
• impl Copy for FileType
• impl Copy for ErrorKind
• impl Copy for SeekFrom
• impl Copy for IpAddr
• impl Copy for Ipv4Addr
• impl Copy for Ipv6Addr
• impl Copy for Ipv6MulticastScope
• impl Copy for SocketAddr
• impl Copy for SocketAddrV4
• impl Copy for SocketAddrV6
• impl Copy for Shutdown
• impl<'a> Copy for Prefix<'a>
• impl<'a> Copy for PrefixComponent<'a>
• impl<'a> Copy for Component<'a>
• impl Copy for ExitStatus
• impl<T: Copy> Copy for SendError<T>
• impl Copy for RecvError
• impl Copy for TryRecvError
• impl Copy for RecvTimeoutError
• impl<T: Copy> Copy for TrySendError<T>
• impl Copy for WaitTimeoutResult
• impl Copy for Duration
• impl Copy for Instant
• impl Copy for SystemTime