Update documentation for assert_unchecked

Author: tgross35

library/core/src/hint.rs

@@ -111,9 +111,8 @@ 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 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
@@ -130,9 +129,9 @@ pub const unsafe fn unreachable_unchecked() -> ! {
 /// 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`](https://llvm.org/docs/LangRef.html#llvm-assume-intrinsic)
-/// or [`__builtin_assume`](https://clang.llvm.org/docs/LanguageExtensions.html#builtin-assume).
+/// You may know this from other places as
+/// [`llvm.assume`](https://llvm.org/docs/LangRef.html#llvm-assume-intrinsic) or, in C,
+/// [`__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.
@@ -141,6 +140,54 @@ pub const unsafe fn unreachable_unchecked() -> ! {
 ///
 /// `cond` must be `true`.  It's immediate UB to call this with `false`.
 ///
+/// # Example
+///
+/// ```
+/// use core::hint;
+///
+/// /// # Safety
+/// ///
+/// /// `p` must be nonnull and valid
+/// pub unsafe fn next_value(p: *const i32) -> i32 {
+///     // SAFETY: caller invariants guarantee that `p` is not null
+///     unsafe { hint::assert_unchecked(!p.is_null()) }
+///
+///     if p.is_null() {
+///         return -1;
+///     } else {
+///         // SAFETY: caller invariants guarantee that `p` is valid
+///         unsafe { *p + 1 }
+///     }
+/// }
+/// ```
+///
+/// Without the `assert_unchecked`, the above function produces the following with optimizations:
+///
+/// ```asm
+/// next_value:
+///         test    rdi, rdi
+///         je      .LBB0_1
+///         mov     eax, dword ptr [rdi]
+///         inc     eax
+///         ret
+/// .LBB0_1:
+///         mov     eax, -1
+///         ret
+/// ```
+///
+/// Adding the assertion allows the optimizer to remove the extra check:
+///
+/// ```asm
+/// next_value:
+///         mov     eax, dword ptr [rdi]
+///         inc     eax
+///         ret
+/// ```
+///
+/// This example is quite unlike anything that would happen in the real world: it is redundant to
+/// put an an assertion right next to code that checks the same thing, and dereferencing a
+/// pointer already has the builtin assumption that it is nonnull. The optimizer can make use of
+/// this information even when it isn't obvious, such as when checks happen in called functions.
 #[inline(always)]
 #[doc(alias = "assume")]
 #[track_caller]