Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Primitive Types

Rust never type !

Reference for Rust's never type !: functions that never return, expressions that diverge, coercion to any type, and Infallible for impossible errors.

The never type, written !, is the type of computations that never produce a value. A function declared -> ! cannot return normally: it loops forever, panics, exits the process, or calls another diverging function. Since no value of type ! can exist, the compiler lets an expression of that type stand in for a value of any type.

That is why let n: u32 = match s.parse() { Ok(n) => n, Err(_) => return }; compiles: the return arm has type !, which coerces to u32. The same holds for panic!, break, continue, unreachable! and an endless loop without break.

Rust
fn fail(msg: &str) -> ! {
    panic!("fatal: {msg}");
}

Try it

Rust Diverging functions and expressions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Infallible: an error that cannot happen

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Rust
fn name(args) -> ! { ... }
let f: fn() -> ! = fail;
enum Void {}                 // an empty enum is the stable stand-in for !
use std::convert::Infallible; // the standard library's empty enum
Part Description
-> ! Marks a function that never returns. Its body must end in a diverging expression.
Infallible An enum with no variants, used as the error type of conversions that cannot fail.

Edge cases: a function declared -> ! that can reach its end is a compile error (E0308, mismatched types). main may be fn main() -> ! in programs that serve forever.

Usage notes

  • Diverging expressions: return, break, continue, panic!, todo!, unimplemented!, unreachable!, std::process::exit and loop {} all have type !.
  • Coercion to any type is what makes match arms and let ... else blocks of different "shapes" fit together.
  • Usable on stable: ! as the return type of functions and function pointers. Using it as an ordinary type argument, such as Result<T, !>, depends on the toolchain, so prefer Infallible, which does the same job and is always available.
  • Empty match: match never {} is accepted for a value of an empty type, and let Ok(v) = result_with_infallible_error; is accepted as an irrefutable pattern.
  • Zero size: Infallible and other empty enums have size 0, and Result<T, Infallible> has the same size as T.
  • Warning signs: a loop {} with no break after it makes later code unreachable, and the compiler warns about it.
  • Process exit: std::process::exit(code) returns ! and skips destructors; panic! unwinds (or aborts) and runs them.
  • Edition 2024: the fallback type used when inference cannot decide the type of a diverging expression changed to !. A lint explains any affected code.