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. Otherwise, consider using the unreachable! macro, which does not allow optimizations but will panic 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, u32::MAX), 0);