rust/src/doc/trpl/const-and-static.md
Steve Klabnik 6b6b380fd1 Rollup merge of #26144 - steveklabnik:static_doc_fix, r=alexcrichton
Fixes #25851

I am 99% sure this is true for all `static`s and not just `static mut`, yes?
2015-06-09 17:24:45 -04:00

84 lines
2.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

% `const` and `static`
Rust has a way of defining constants with the `const` keyword:
```rust
const N: i32 = 5;
```
Unlike [`let`][let] bindings, you must annotate the type of a `const`.
[let]: variable-bindings.html
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:
```rust
static N: i32 = 5;
```
Unlike [`let`][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][lifetimes]:
```rust
static NAME: &'static str = "Steve";
```
[lifetimes]: lifetimes.html
## Mutability
You can introduce mutability with the `mut` keyword:
```rust
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`][unsafe], and so must be done in an `unsafe` block:
```rust
# static mut N: i32 = 5;
unsafe {
N += 1;
println!("N: {}", N);
}
```
[unsafe]: unsafe.html
Furthermore, any type stored in a `static` must be `Sync`, and may not have
a [`Drop`][drop] implementation.
[drop]: drop.html
# 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.