Add hint::assert_unchecked

Author: scottmcm

library/core/src/hint.rs

@@ -106,6 +106,42 @@ pub const unsafe fn unreachable_unchecked() -> ! {
     }
 }
 
+/// 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);`.
+///
+/// You may know this from other places
+/// as [`llvm.assume`](https://llvm.org/docs/LangRef.html#llvm-assume-intrinsic)
+/// or [`__builtin_assume`](https://clang.llvm.org/docs/LanguageExtensions.html#builtin-assume).
+///
+/// This promotes a correctness requirement to a soundness requirement.
+/// Don't do that without very good reason.
+///
+/// # Safety
+///
+/// `cond` must be `true`.  It's immediate UB to call this with `false`.
+///
+#[inline(always)]
+#[doc(alias = "assume")]
+#[unstable(feature = "hint_assert_unchecked", issue = "119131")]
+pub const unsafe fn assert_unchecked(cond: bool) {
+    unsafe { crate::intrinsics::assume(cond) }
+}
+
 /// Emits a machine instruction to signal the processor that it is running in
 /// a busy-wait spin-loop ("spin lock").
 ///