Constant evaluation

Constant evaluation is the process of computing the result of expressions during compilation. Only a subset of all expressions can be evaluated at compile-time.

Constant expressions

Certain forms of expressions, called constant expressions, can be evaluated at compile time.

In const contexts, these are the only allowed expressions, and are always evaluated at compile time.

In other places, such as let statements, constant expressions may be, but are not guaranteed to be, evaluated at compile time.

Behaviors such as out of bounds array indexing or overflow are compiler errors if the value must be evaluated at compile time (i.e. in const contexts). Otherwise, these behaviors are warnings, but will likely panic at run-time.

The following expressions are constant expressions, so long as any operands are also constant expressions and do not cause any Drop::drop calls to be run.

• Literals.

• Const parameters.

• Paths to functions and constants. Recursively defining constants is not allowed.

• Paths to statics with these restrictions:
  • Writes to static items are not allowed in any constant evaluation context.
  • Reads from extern statics are not allowed in any constant evaluation context.
  • If the evaluation is not carried out in an initializer of a static item, then reads from any mutable static are not allowed. A mutable static is a static mut item, or a static item with an interior-mutable type.

These requirements are checked only when the constant is evaluated. In other words, having such accesses syntactically occur in const contexts is allowed as long as they never get executed.

• Tuple expressions.

• Array expressions.

• Struct expressions.

• Block expressions, including unsafe and const blocks.
  • let statements and thus irrefutable patterns, including mutable bindings
  • assignment expressions
  • compound assignment expressions
  • expression statements

• Field expressions.

• Index expressions, array indexing or slice with a usize.

• Range expressions.

• Closure expressions which don’t capture variables from the environment.

• Built-in negation, arithmetic, logical, comparison or lazy boolean operators used on integer and floating point types, bool, and char.

• All forms of borrows, including raw borrows, with one limitation: mutable borrows and shared borrows to values with interior mutability are only allowed to refer to transient places. A place is transient if its lifetime is strictly contained inside the current const context.

• The dereference operator except for raw pointers.

• Grouped expressions.

• Cast expressions, except
  • pointer to address casts and
  • function pointer to address casts.

• Calls of const functions and const methods.

• loop, while and while let expressions.

• if, if let and match expressions.

Const context

A const context is one of the following:

• Array type length expressions

• Array repeat length expressions

• The initializer of
  • constants
  • statics
  • enum discriminants

• A const generic argument

• A const block

Const contexts that are used as parts of types (array type and repeat length expressions as well as const generic arguments) can only make restricted use of surrounding generic parameters: such an expression must either be a single bare const generic parameter, or an arbitrary expression not making use of any generics.

Const Functions

A const fn is a function that one is permitted to call from a const context.

Declaring a function const has no effect on any existing uses, it only restricts the types that arguments and the return type may use, and restricts the function body to constant expressions.

When called from a const context, the function is interpreted by the compiler at compile time. The interpretation happens in the environment of the compilation target and not the host. So usize is 32 bits if you are compiling against a 32 bit system, irrelevant of whether you are building on a 64 bit or a 32 bit system.