Divergence

A diverging expression is an expression that never completes normal execution.

fn diverges() -> ! {
    panic!("This function never returns!");
}

fn example() {
    let x: i32 = diverges(); // This line never completes.
    println!("This is never printed: {x}");
}

See the following rules for specific expression divergence behavior:

expr.block.diverging --- Block expressions.
expr.if.diverging --- if expressions.
expr.loop.block-labels.type --- Labeled block expressions with break.
expr.loop.break-value.diverging --- loop expressions with break.
expr.loop.break.diverging --- break expressions.
expr.loop.continue.diverging --- continue expressions.
expr.loop.infinite.diverging --- Infinite loop expressions.
expr.match.diverging --- match expressions.
expr.match.empty --- Empty match expressions.
expr.return.diverging --- return expressions.
type.never.constraint --- Function calls returning !.

Note

The [panic!] macro and related panic-generating macros like [unreachable!] also have the type ! and are diverging.

[divergence.never]

Any expression of type ! is a diverging expression. However, diverging expressions are not limited to type !; expressions of other types may also diverge (e.g., Some(loop {}) has type Option<!>).

Note

Though ! is considered an uninhabited type, a type being uninhabited is not sufficient for it to diverge.

enum Empty {}
fn make_never() -> ! {loop{}}
fn make_empty() -> Empty {loop{}}

fn diverging() -> ! {
    // This has a type of `!`.
    // So, the entire function is considered diverging.
    make_never();
    // OK: The type of the body is `!` which matches the return type.
}
fn not_diverging() -> ! {
    // This type is uninhabited.
    // However, the entire function is not considered diverging.
    make_empty();
    // ERROR: The type of the body is `()` but expected type `!`.
}

Note

Divergence can propagate to the surrounding block. See expr.block.diverging.

[divergence.fallback]

Fallback

If a type to be inferred is only unified with diverging expressions, then that type will be inferred to be !.

Example

fn foo() -> i32 { 22 }
match foo() {
    // ERROR: The trait bound `!: Default` is not satisfied.
    4 => Default::default(),
    _ => return,
};

2024 Edition differences

Before the 2024 edition, the type was inferred to instead be ().

Note

Importantly, type unification may happen structurally, so the fallback ! may be part of a larger type. The following compiles:
fn foo() -> i32 { 22 }
// This has the type `Option<!>`, not `!`
match foo() {
    4 => Default::default(),
    _ => Some(return),
};