rust/src/doc/trpl/const-and-static.md
2015-06-09 16:30:39 -04:00

2.5 KiB
Raw Blame History

% const and static

Rust has a way of defining constants with the const keyword:

const N: i32 = 5;

Unlike let bindings, you must annotate the type of a const.

Constants live for the entire lifetime of a program. More specifically, constants in Rust have no fixed address in memory. This is because theyre effectively inlined to each place that theyre used. References to the same constant are not necessarily guaranteed to refer to the same memory address for this reason.

static

Rust provides a global variable sort of facility in static items. Theyre similar to constants, but static items arent inlined upon use. This means that there is only one instance for each value, and its at a fixed location in memory.

Heres an example:

static N: i32 = 5;

Unlike let bindings, you must annotate the type of a static.

Statics live for the entire lifetime of a program, and therefore any reference stored in a constant has a 'static lifetime:

static NAME: &'static str = "Steve";

Mutability

You can introduce mutability with the mut keyword:

static mut N: i32 = 5;

Because this is mutable, one thread could be updating N while another is reading it, causing memory unsafety. As such both accessing and mutating a static mut is unsafe, and so must be done in an unsafe block:

# static mut N: i32 = 5;

unsafe {
    N += 1;

    println!("N: {}", N);
}

Furthermore, any type stored in a static must be Sync, and may not have a Drop implementation.

Initializing

Both const and static have requirements for giving them a value. They may only be given a value thats a constant expression. In other words, you cannot use the result of a function call or anything similarly complex or at runtime.

Which construct should I use?

Almost always, if you can choose between the two, choose const. Its pretty rare that you actually want a memory location associated with your constant, and using a const allows for optimizations like constant propagation not only in your crate but downstream crates.

A const can be thought of as a #define in C: it has metadata overhead but it has no runtime overhead. “Should I use a #define or a static in C,” is largely the same question as whether you should use a const or a static in Rust.