Constant items

A constant item is an optionally named constant value which is not associated with a specific memory location in the program.

Constants are essentially inlined wherever they are used, meaning that they are copied directly into the relevant context when used. This includes usage of constants from external crates, and non-Copy types. References to the same constant are not necessarily guaranteed to refer to the same memory address.

The constant declaration defines the constant value in the value namespace of the module or block where it is located.

Constants must be explicitly typed. The type must have a 'static lifetime: any references in the initializer must have 'static lifetimes. References in the type of a constant default to 'static lifetime; see static lifetime elision.

A reference to a constant will have 'static lifetime if the constant value is eligible for promotion; otherwise, a temporary will be created.

#![allow(unused)]
fn main() {
const BIT1: u32 = 1 << 0;
const BIT2: u32 = 1 << 1;

const BITS: [u32; 2] = [BIT1, BIT2];
const STRING: &'static str = "bitstring";

struct BitsNStrings<'a> {
    mybits: [u32; 2],
    mystring: &'a str,
}

const BITS_N_STRINGS: BitsNStrings<'static> = BitsNStrings {
    mybits: BITS,
    mystring: STRING,
};
}

The final value of a const item, after the initializer is evaluated to a value that has the declared type of the constant, cannot contain any mutable references except as described below.

#![allow(unused)]
fn main() {
#![allow(static_mut_refs)]
static mut S: u8 = 0;
const _: &u8 = unsafe { &mut S }; // OK.
//                      ^^^^^^
// Allowed since this is coerced to `&S`.
}

#![allow(unused)]
fn main() {
use core::sync::atomic::AtomicU8;
static S: AtomicU8 = AtomicU8::new(0);
const _: &AtomicU8 = &S; // OK.
//                   ^^
// Allowed even though the shared reference is to an interior
// mutable value.
}

#![allow(unused)]
fn main() {
#![allow(static_mut_refs)]
static mut S: u8 = 0;
const _: &mut u8 = unsafe { &mut S }; // ERROR.
//                          ^^^^^^
// Not allowed as the mutable reference appears in the final value.
}

#![allow(unused)]
fn main() {
#![allow(static_mut_refs)]
static mut S: u8 = 0;
const _: &dyn Send = &unsafe { &mut S }; // ERROR.
//                             ^^^^^^
// Not allowed as the mutable reference appears in the final value,
// even though type erasure occurs.
}

Mutable references where the referent is a value of a zero-sized type are allowed.

#![allow(unused)]
fn main() {
#![allow(static_mut_refs)]
static mut S: () = ();
const _: &mut () = unsafe { &mut S }; // OK.
//            ^^ This is a zero-sized type.
}

#![allow(unused)]
fn main() {
#![allow(static_mut_refs)]
static mut S: [u8; 0] = [0; 0];
const _: &mut [u8; 0] = unsafe { &mut S }; // OK.
//            ^^^^^^^ This is a zero-sized type.
}

Values of union type are not considered to contain any references; for this purpose, a value of union type is treated as a sequence of untyped bytes.

#![allow(unused)]
fn main() {
#![allow(static_mut_refs)]
union U { f: &'static mut u8 }
static mut S: u8 = 0;
const _: U = unsafe { U { f: &mut S }}; // OK.
//                    ^^^^^^^^^^^^^^^
// This is treated as a sequence of untyped bytes.
}

Mutable references contained within a mutable static may be referenced in the final value of a constant.

#![allow(unused)]
fn main() {
#![allow(static_mut_refs)]
static mut S: &mut u8 = unsafe { static mut I: u8 = 0; &mut I };
const _: &&mut u8 = unsafe { &S }; // OK.
//        ^^^^^^^
// This mutable reference comes from a `static mut`.
}

Mutable references contained within an external static may be referenced in the final value of a constant.

#![allow(unused)]
fn main() {
#![allow(static_mut_refs)]
unsafe extern "C" { static S: &'static mut u8; }
const _: &&mut u8 = unsafe { &S }; // OK.
//        ^^^^^^^
// This mutable references comes from an extern static.
}

The constant expression may only be omitted in a trait definition.

Constants with destructors

Constants can contain destructors. Destructors are run when the value goes out of scope.

#![allow(unused)]
fn main() {
struct TypeWithDestructor(i32);

impl Drop for TypeWithDestructor {
    fn drop(&mut self) {
        println!("Dropped. Held {}.", self.0);
    }
}

const ZERO_WITH_DESTRUCTOR: TypeWithDestructor = TypeWithDestructor(0);

fn create_and_drop_zero_with_destructor() {
    let x = ZERO_WITH_DESTRUCTOR;
    // x gets dropped at end of function, calling drop.
    // prints "Dropped. Held 0.".
}
}

Unnamed constant

Unlike an associated constant, a free constant may be unnamed by using an underscore instead of the name. For example:

#![allow(unused)]
fn main() {
const _: () =  { struct _SameNameTwice; };

// OK although it is the same name as above:
const _: () =  { struct _SameNameTwice; };
}

As with underscore imports, macros may safely emit the same unnamed constant in the same scope more than once. For example, the following should not produce an error:

#![allow(unused)]
fn main() {
macro_rules! m {
    ($item: item) => { $item $item }
}

m!(const _: () = (););
// This expands to:
// const _: () = ();
// const _: () = ();
}

Evaluation

Free constants are always evaluated at compile-time to surface panics. This happens even within an unused function:

#![allow(unused)]
fn main() {
// Compile-time panic
const PANIC: () = std::unimplemented!();

fn unused_generic_function<T>() {
    // A failing compile-time assertion
    const _: () = assert!(usize::BITS == 0);
}
}