.RS File Format – Types

Type expressions

Type:
      TypeNoBounds | ImplTraitType | TraitObjectType

TypeNoBounds:
      ParenthesizedType | ImplTraitTypeOneBound | TraitObjectTypeOneBound
    | TypePath | TupleType | NeverType | RawPointerType | ReferenceType
    | ArrayType | SliceType | InferredType | QualifiedPathInType
    | BareFunctionType | MacroInvocation

Parentheses are sometimes required to tell where a bound ends: &'a (dyn Any + Send). A recursive type must pass through a nominal type (a struct, enum or union) and have finite size, so a recursive field needs a pointer such as Box.

Numeric types

f32 and f64 are IEEE 754 binary32 and binary64. Signed integers are two’s complement. Each usize is the same size as a pointer on the target; the size of any one object cannot exceed isize::MAX bytes. A literal’s type comes from its suffix or from inference.

Boolean, character and string slice

• bool is one byte, 0 for false and 1 for true. Any other value is undefined behaviour.
• char is four bytes and holds one Unicode scalar value: U+0000 to U+D7FF or U+E000 to U+10FFFF. A surrogate value is undefined behaviour.
• str is a string slice. It is a sequence of bytes with the layout of [u8], and standard library code assumes it holds valid UTF-8. It is unsized, and is normally used behind a reference, as &str.

The never type

! is the type with no values. It marks a computation that never finishes, and it coerces to any other type. Today it can appear only in function return types (Reference: Never type). The fall-back type of an expression of type ! whose type is otherwise unconstrained changed in edition 2024.

fn fail() -> ! {
    panic!("This call never returns.");
}

let n: u32 = if ok { 1 } else { fail() };  // the else arm has type !, which coerces to u32

Tuples, arrays and slices

Indexing an array or slice outside its bounds panics at run time. A mutable reference to a slice lets its elements be changed but not its length.

Pointer types

BareFunctionType:
    ForLifetimes? FunctionTypeQualifiers fn ( FunctionParametersMaybeNamedVariadic? ) ( -> TypeNoBounds )?
FunctionTypeQualifiers:
    unsafe? ( extern Abi? )?

fn add(x: i32, y: i32) -> i32 { x + y }

type Binop = fn(i32, i32) -> i32;
let bo: Binop = add;              // a function item coerces to a function pointer
let z = bo(5, 7);

A function pointer is never null. Null or nullable C pointers are modelled with Option<fn(…)>. Pointers to sized types have the same size as usize. Pointers to unsized types are wide: they hold a second word, the length of a slice or the vtable of a trait object.

Function items and closures

Each function, and each tuple struct or enum variant constructor, has its own zero-sized function item type, which can be called and coerces to a function pointer of the matching signature. Each closure has a unique anonymous type, which is roughly a struct holding its captured values. Neither type can be written in source.

Closures implement FnOnce; those that do not move out of captures also implement FnMut; those that also do not mutate captures implement Fn. A closure that captures nothing coerces to a function pointer.

Trait objects

TraitObjectType:         Bounds | dyn Bounds?
TraitObjectTypeOneBound: TraitBound | dyn TraitBound?

A trait object is an opaque value of some other type that implements a set of traits: one dyn compatible base trait plus any number of auto traits (Reference: Trait object types).

• There must be at least one trait, no more than one non-auto trait and no more than one lifetime. ?Sized and use<…> bounds are not allowed.
• A trait object is dynamically sized, so it must be behind a pointer such as &dyn Trait or Box<dyn Trait>. The pointer holds a data pointer and a pointer to a vtable, and method calls go through the vtable.
• Bare trait objects without dyn are accepted only in editions 2015 and 2018. From edition 2021 dyn is required.
• The default lifetime bound of a trait object is described under default object lifetimes.

trait Printable { fn stringify(&self) -> String; }

impl Printable for i32 {
    fn stringify(&self) -> String { self.to_string() }
}

fn print(a: Box<dyn Printable>) {
    println!("{}", a.stringify());    // dynamic dispatch through the vtable
}

impl Trait

ImplTraitType:         impl Bounds?
ImplTraitTypeOneBound: impl TraitBound?

impl Trait may appear only as a parameter type or return type of a non-extern function, not as the type of a let binding or a field, and not in a type alias (Reference: Impl trait type).

fn with_generic<T: Trait>(arg: T) {}       // the caller picks T
fn with_impl(arg: impl Trait) {}           // nearly the same; the type has no name

fn adder(n: i32) -> impl Fn(i32) -> i32 {  // the function picks the type
    move |x| x + n
}

A return-position impl Trait captures generic parameters that its hidden type may use. In edition 2024, all in-scope type, const and lifetime parameters are captured automatically. Before edition 2024, free functions and inherent methods do not capture a lifetime parameter that does not appear in the bounds.

A use<…> bound gives the exact list: impl Sized + use<'a, T> captures only 'a and T. All in-scope type and const parameters must be listed, every lifetime named in the other bounds must be listed, and lifetimes come first. The bound cannot be used on a function with an argument-position impl Trait, whose parameters cannot be named.

The inferred type

_ asks the compiler to infer a type, as in let v: Vec<_> = iter.collect();. It cannot be used in item signatures.

Coercions

A coercion is an implicit type change at specific sites: let statements with an explicit type, static and const items, function call arguments, struct field initialisers, function results and assigned values. If an array, tuple, parenthesised expression or block is at such a site, its relevant sub-expressions are too (Reference: Type coercions).

The unsized coercions are [T; n] to [T], T to dyn U when T: U + Sized and U is dyn compatible, and dyn T to dyn U when U is a supertrait of T. Explicit conversions use the as cast operator.

Layout

A type’s size, alignment and field offsets are its layout. Only the rules below are guaranteed; other details can change between compilations (Reference: Type layout). Size is always a multiple of alignment.

A pointer to an unsized type is currently twice the size of usize; this is not guaranteed. () and types with only zero-sized fields are zero-sized.

#[repr(C)]
struct Demo { first: u8, second: u32, third: u64 }    // offsets 0, 4, 8; size 16; alignment 8

#[repr(u8)]
enum Colour { Red = 1, Green = 2, Blue = 4 }          // one byte, with discriminant values given

#[repr(transparent)]
struct Meters(f64);                                   // same layout and ABI as f64