Function std::hint::unreachable_unchecked

pub unsafe fn unreachable_unchecked() -> !

Informs the compiler that this point in the code is not reachable, enabling further optimizations.

Safety

Reaching this function is completely undefined behavior (UB). In particular, the compiler assumes that all UB must never happen, and therefore will eliminate all branches that reach to a call to unreachable_unchecked().

Like all instances of UB, if this assumption turns out to be wrong, i.e. the unreachable_unchecked() call is actually reachable among all possible control flow, the compiler will apply the wrong optimization strategy, and may sometimes even corrupt seemingly unrelated code, causing difficult-to-debug problems.

Use this function only when you can prove that the code will never call it.

The unreachable!() macro is the safe counterpart of this function, which will panic instead when executed.

Example

fn div_1(a: u32, b: u32) -> u32 {
    use std::hint::unreachable_unchecked;

    // `b.saturating_add(1)` is always positive (not zero),
    // hence `checked_div` will never return None.
    // Therefore, the else branch is unreachable.
    a.checked_div(b.saturating_add(1))
        .unwrap_or_else(|| unsafe { unreachable_unchecked() })
}

assert_eq!(div_1(7, 0), 7);
assert_eq!(div_1(9, 1), 4);
assert_eq!(div_1(11, std::u32::MAX), 0);