Function core::hint::unreachable_unchecked
1.27.0 (const: 1.57.0) · source · [−]pub const unsafe fn unreachable_unchecked() -> !
Expand description
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);
Run