Function std::hint::assert_unchecked

source ·
pub const unsafe fn assert_unchecked(cond: bool)
🔬This is a nightly-only experimental API. (hint_assert_unchecked #119131)
Expand description

Makes a soundness promise to the compiler that cond holds.

This may allow the optimizer to simplify things, but it might also make the generated code slower. Either way, calling it will most likely make compilation take longer.

This is a situational tool for micro-optimization, and is allowed to do nothing. Any use should come with a repeatable benchmark to show the value and allow removing it later should the optimizer get smarter and no longer need it.

The more complicated the condition the less likely this is to be fruitful. For example, assert_unchecked(foo.is_sorted()) is a complex enough value that the compiler is unlikely to be able to take advantage of it.

There’s also no need to assert_unchecked basic properties of things. For example, the compiler already knows the range of count_ones, so there’s no benefit to let n = u32::count_ones(x); assert_unchecked(n <= u32::BITS);.

If ever you’re tempted to write assert_unchecked(false), then you’re actually looking for unreachable_unchecked().

You may know this from other places as llvm.assume or __builtin_assume.

This promotes a correctness requirement to a soundness requirement. Don’t do that without very good reason.


cond must be true. It’s immediate UB to call this with false.