For now, this reference is a best-effort document. We strive for validity and completeness, but are not yet there. In the future, the docs and lang teams will work together to figure out how best to do this. Until then, this is a best-effort attempt. If you find something wrong or missing, file an issue or send in a pull request.

Special types and traits

Certain types and traits that exist in the standard library are known to the Rust compiler. This chapter documents the special features of these types and traits.

Box<T>

Box<T> has a few special features that Rust doesn't currently allow for user defined types.

  • The dereference operator for Box<T> produces a place which can be moved from. This means that the * operator and the destructor of Box<T> are built-in to the language.
  • Methods can take Box<Self> as a receiver.
  • A trait may be implemented for Box<T> in the same crate as T, which the orphan rules prevent for other generic types.

Rc<T>

Methods can take Rc<Self> as a receiver.

Arc<T>

Methods can take Arc<Self> as a receiver.

Pin<P>

Methods can take Pin<P> as a receiver.

UnsafeCell<T>

std::cell::UnsafeCell<T> is used for interior mutability. It ensures that the compiler doesn't perform optimisations that are incorrect for such types. It also ensures that static items which have a type with interior mutability aren't placed in memory marked as read only.

PhantomData<T>

std::marker::PhantomData<T> is a zero-sized, minimum alignment, type that is considered to own a T for the purposes of variance, drop check, and auto traits.

Operator Traits

The traits in std::ops and std::cmp are used to overload operators, indexing expressions, and call expressions.

Deref and DerefMut

As well as overloading the unary * operator, Deref and DerefMut are also used in method resolution and deref coercions.

Drop

The Drop trait provides a destructor, to be run whenever a value of this type is to be destroyed.

Copy

The Copy trait changes the semantics of a type implementing it. Values whose type implements Copy are copied rather than moved upon assignment. Copy cannot be implemented for types which implement Drop, or which have fields that are not Copy. Copy is implemented by the compiler for

Clone

The Clone trait is a supertrait of Copy, so it also needs compiler generated implementations. It is implemented by the compiler for the following types:

  • Types with a built-in Copy implementation (see above)
  • Tuples of Clone types
  • Arrays of Clone types

Send

The Send trait indicates that a value of this type is safe to send from one thread to another.

Sync

The Sync trait indicates that a value of this type is safe to share between multiple threads. This trait must be implemented for all types used in immutable static items.

Auto traits

The Send, Sync, UnwindSafe, and RefUnwindSafe traits are auto traits. Auto traits have special properties.

If no explicit implementation or negative implementation is written out for an auto trait for a given type, then the compiler implements it automatically according to the following rules:

  • &T, &mut T, *const T, *mut T, [T; n], and [T] implement the trait if T does.
  • Function item types and function pointers automatically implement the trait.
  • Structs, enums, unions, and tuples implement the trait if all of their fields do.
  • Closures implement the trait if the types of all of their captures do. A closure that captures a T by shared reference and a U by value implements any auto traits that both &T and U do.

For generic types (counting the built-in types above as generic over T), if a generic implementation is available, then the compiler does not automatically implement it for types that could use the implementation except that they do not meet the requisite trait bounds. For instance, the standard library implements Send for all &T where T is Sync; this means that the compiler will not implement Send for &T if T is Send but not Sync.

Auto traits can also have negative implementations, shown as impl !AutoTrait for T in the standard library documentation, that override the automatic implementations. For example *mut T has a negative implementation of Send, and so *mut T is not Send, even if T is. There is currently no stable way to specify additional negative implementations; they exist only in the standard library.

Auto traits may be added as an additional bound to any trait object, even though normally only one trait is allowed. For instance, Box<dyn Debug + Send + UnwindSafe> is a valid type.

Sized

The Sized trait indicates that the size of this type is known at compile-time; that is, it's not a dynamically sized type. Type parameters are Sized by default. Sized is always implemented automatically by the compiler, not by implementation items.