7. Values¶

Legality Rules

7:1 A value is either a literal or the result of a computation, that may be stored in a memory location, and interpreted based on some type.

7:2 An allocated object is a value stored at some memory address.

7:3 The base address of an allocated object is the memory address where the object is stored.

7:4 An allocated objects memory size is the number of bytes the object spans in memory from its base address.

7:5 Two values overlap when

7:6 Both values are the same, or
7:7 One value is of an abstract data type and the other denotes a field of the same value, or
7:8 One value denotes an array and the other denotes an element of the same value, or
7:9 Both values are elements of the same array.

Undefined Behavior

7:10 It is undefined behavior to create a value from uninitialized memory unless the type of the value is a union type.

7:11 It is undefined behavior to create an allocated object at base address null.

7:12 It is undefined behavior to create an allocated object with memory size size at a base address base where base + size is greater than the architectures maximum usize value.

7:13 It is undefined behavior to create an allocated object with memory size size where size is greater than the architectures maximum isize value.

7.1. Constants¶

Syntax

ConstantDeclaration ::=
    const (Name | _) TypeAscription ConstantInitializer? ;

ConstantInitializer ::=
    = Expression

Legality Rules

7.1:1 A constant is an immutable value expression whose uses are substituted by the value.

7.1:2 An unnamed constant is a constant declared with character 0x5F (low line).

7.1:3 The type specification of a constant shall have 'static lifetime.

7.1:4 The type of a constant shall implement the core::marker::Sized trait.

7.1:5 A constant initializer is a construct that provides the value of its related constant.

7.1:6 A constant shall have a constant initializer, unless it is an associated trait constant.

7.1:7 The expression of a constant initializer shall be a constant expression.

7.1:8 If the value produced by evaluating a constant initializer is or contains a pointer, then each such pointer shall be a non-dangling well-formed pointer.

Dynamic Semantics

7.1:9 The elaboration of a constant evaluates its constant initializer.

7.1:10 A path that refers to a constant is replaced with the value of the constant.

Examples

const ZERO: u32 = 0;

7.2. Pointers¶

Legality Rules

7.2:1 A pointer is a value of a pointer type.

7.2:2 A pointer is dangling if it is either null or not all of the bytes at the referred memory location are part of the same allocation.

7.2:3 A thin pointer is a value of a thin pointer type.

7.2:4 A fat pointer is a value of a fat pointer type.

7.2:5 An original pointer is a pointer created via allocation.

7.2:6 A derived pointer is a pointer obtained by borrowing, copying a pointer, reading a stored pointer, performing pointer arithmetic, or casting a pointer.

7.2.1. Raw Pointers¶

Legality Rules

7.2.1:1 A raw pointer is a value of a raw pointer type.

7.2.1:2 Comparing two raw pointers compares the addresses of the raw pointers.

7.2.1:3 Comparing a raw pointer to a value of a dynamically sized type compares the data being pointed to.

7.2.2. References¶

Legality Rules

7.2.2:1 A shared reference is a value of a shared reference type.

7.2.2:2 Copying a shared reference performs a shallow copy.

7.2.2:3 Releasing a shared reference has no effect on the value it refers to.

7.2.2:4 A mutable reference is a value of a mutable reference type.

Undefined Behavior

7.2.2:5 It is validity invariant for a value of a reference type to be not null.

7.2.3. Provenance¶

Legality Rules

7.2.3:1 Provenance is an optional property of pointers that restricts the memory locations the pointer may access, the timespan during which the accesses may occur, and whether the accesses may read from or write to said memory locations.

7.2.3:2 An original pointer carries provenance over all or part of the allocated object it was created from.

7.2.3:3 A derived pointer inherits the provenance of the pointer it was created from, if any.

7.2.3:4 A well-formed pointer is a pointer where either no byte of the pointer carries provenance, or every byte of the pointer is the corresponding byte of a single pointer with provenance.

Undefined Behavior

7.2.3:5 It is undefined behavior to access memory through a pointer that does not have provenance permitting the access.

7.3. Statics¶

Syntax

StaticDeclaration ::=
    ItemSafety? static mut? Name TypeAscription StaticInitializer? ;

StaticInitializer ::=
    = Expression

Legality Rules

7.3:1 A static is a value that is associated with a specific memory location.

7.3:2 A static defined within a generic function exists once in the output executable or library.

7.3:3 The type specification of a static shall have 'static lifetime.

7.3:4 The type of a static shall implement the core::marker::Sized trait.

7.3:5 A static shall only be subject to an ItemSafety if it is an external static in an unsafe external block.

7.3:6 A mutable static is a static with keyword mut whose value can be modified.

7.3:7 Access to a mutable static shall require unsafe context.

7.3:8 An immutable static is a static whose value cannot be modified.

7.3:9 The type of an immutable static shall implement the core::marker::Sync trait.

7.3:10 A static initializer is a construct that provides the value of its related static.

7.3:11 A static shall have a static initializer, unless it is an external static.

7.3:12 The expression of a static initializer shall be a constant expression.

7.3:13 If the value produced by evaluating a static initializer is or contains a pointer, then each such pointer shall be a non-dangling well-formed pointer.

7.3:14 A use of a static is a place expression referring to the unique location of the static.

Dynamic Semantics

7.3:15 The elaboration of a static evaluates its static initializer.

7.3:16 All paths that refer to a static refer to the same memory location.

7.3:17 A static is not dropped during destruction.

7.3:18 An immutable static whose type is not subject to interior mutability may reside in read-only memory.

Undefined Behavior

7.3:19 It is undefined behavior to mutate an immutable static whose type is not subject to interior mutability.

Examples

static mut GLOBAL: u32 = 0;

7.4. Temporaries¶

Legality Rules

7.4:1 A temporary is an anonymous variable produced by some intermediate computation.

7.5. Variables¶

Legality Rules

7.5:1 A variable is a placeholder for a value that is allocated on the stack.

7.5:2 The following constructs are variables:

7.5:3 A binding.
7.5:4 A temporary.

7.5:5 A variable shall be used only after it has been initialized through all reachable control flow paths up to the point of its usage.

Dynamic Semantics

7.5:6 A variable is not initialized when allocated.

7.5.1. Constant Promotion¶

Legality Rules

7.5.1:1 Constant promotion is the process of converting a value expression into a constant.

7.5.1:2 Constant promotion is possible only when

7.5.1:3 The value expression is a constant expression, and
7.5.1:4 The type of the value expression does not have a destructor, and
7.5.1:5 The value expression does not employ a struct expression constructing a core::cell::UnsafeCell, and
7.5.1:6 The value expression only consists of operations that will always succeed evaluation, and
7.5.1:7 The value expression is the operand of an immutable borrow expression.

7.5.1:8 Constant promotion is always possible for expression &mut [], promoting the produced mutable borrow to have 'static lifetime.

7.5.1:9 Constant promotion proceeds as follows:

7.5.1:10 An anonymous constant is created, whose constant initializer holds the result of the value expression.
7.5.1:11 The value of the anonymous constant is borrowed with 'static lifetime.