.RS File Format – Expressions

Operator precedence

Rows are listed from the strongest binding to the weakest (Reference: Expressions). Binary operators at the same level are grouped according to the associativity shown.

Comparison and range operators do not chain: a == b == c and a..b..c are errors, and parentheses are required.

Place and value expressions

A place expression represents a memory location: a variable, a static, a dereference *expr, an index expr[expr], a field expr.f, or a parenthesised place. All others are value expressions. A third, minor category, assignee expressions, is used on the left of a destructuring assignment.

A place is expected as the left operand of a compound assignment, the operand of a unary borrow, raw borrow or dereference, the operand of a field expression, the indexed operand of an array index, the operand of an implicit borrow, the initialiser of a let, the scrutinee of if let, match and while let, and the base of a functional update.

If a value expression is used where a place is expected, a temporary is created, and is usually dropped at the end of the enclosing statement. A place used in a value context is copied or moved; see Moves and copies.

Evaluation order

Operands are evaluated before the expression’s effect, and left to right as written. This applies to the dereference, try, negation, arithmetic, comparison, cast, grouped, array, await, index, tuple, tuple index, struct, call, method call, field, break, range and return expressions. The only operators that may skip an operand are the lazy boolean ones.

Blocks as expressions

A block is a sequence of statements and an optional final expression, in braces. The final expression, if there is one, is the block’s value; a block with no final expression has type (), unless its end is unreachable.

let x = {
    let a = 2;
    let b = 3;
    a * b               // no semicolon: the value of the block
};                      // x is 6

let y = if x > 5 { "big" } else { "small" };

let label = match x {
    0 => "zero",
    n if n < 0 => "negative",
    _ => "positive",
};

Operators

TypeCastExpression: Expression as TypeNoBounds

let (mut a, mut b) = (0, 1);
(b, a) = (a, b);                     // swap

struct S { x: u32, y: u32 }
S { x: a, y: b } = S { x: 3, y: 4 };

[a, .., b] = [1, 2, 3, 4];
(a, _) = (5, 6);                     // _ ignores a value

The try operator

Expression ?

? applied to a Result or Option returns the success value, or returns early from the enclosing function, closure or async block with the failure. It uses the unstable Try trait, so user types cannot implement it.

fn read_number(path: &str) -> Result<i32, Box<dyn std::error::Error>> {
    let text = std::fs::read_to_string(path)?;   // io::Error converted by From
    let n: i32 = text.trim().parse()?;           // ParseIntError converted by From
    Ok(n)
}

The error conversion is why a function can use ? on several error types, provided its return type has a From for each. See Error handling.

Closures

ClosureExpression:
    async? move? ( || | | ClosureParameters? | )
    ( Expression | -> TypeNoBounds BlockExpression )

ClosureParam:
    OuterAttribute* PatternNoTopAlt ( : Type )?

let add = |x, y| x + y;
let typed = |x: i32| -> i32 { x + 1 };

let mut count = 0;
let mut bump = || count += 1;       // captures count by mutable reference
bump();
bump();

let word = String::from("hi");
let owned = move || println!("{word}");   // moves word into the closure

• Parameters are irrefutable patterns with optional types. A return type requires the body to be a block. Types may be inferred from use.
• A closure captures variables from its surroundings, by shared reference, unique borrow, mutable reference or move, whichever is the least the body needs. The move keyword forces capture by value.
• From edition 2021, a closure captures disjoint fields, such as a.x, instead of the whole variable a. In earlier editions it captures the whole variable.
• Every closure implements FnOnce; those that do not move out of a capture implement FnMut; those that also do not mutate a capture implement Fn. The trait depends on what the body does, not on whether the closure is written with move.
• Non-capturing, non-async closures coerce to function pointers.
• Closures are Copy and Clone if their captures are. Closures have no fixed layout.
• async closures return a future when called, and implement AsyncFn, AsyncFnMut and AsyncFnOnce. They are not allowed in edition 2015.

Ranges

The range syntax builds values of standard library types in std::ops.

for i in 1..11 { println!("{i}"); }     // 1 to 10

let s = "hello";
let tail = &s[1..];                     // "ello"
let head = &s[..=2];                    // "hel"

Other expressions

Constant expressions

A const context requires a constant expression and is always evaluated at compile time (Reference: Constant evaluation). The const contexts are:

• Array type length expressions and array repeat lengths
• The initialisers of const items, static items and enum discriminants
• Const generic arguments
• const blocks

Constant expressions may use literals, const generic parameters, paths to functions and constants, tuples, arrays, struct expressions, blocks with let, built-in operators, loop, while, if and match, and calls to const fn. Closures that capture their environment are not allowed.

• A const fn runs at compile time when called in a const context, using the target’s types, and at run time otherwise.
• Overflow and out-of-bounds indexing are compile-time errors in a const context.
• Statics cannot be written during constant evaluation, extern statics cannot be read, and mutable statics can only be read inside a static’s initialiser.
• An expression that runs Drop::drop is not a constant expression.