Skip to content

Expand docs on std::hint::assert_unchecked - #161262

Open
lukaslueg wants to merge 1 commit into
rust-lang:mainfrom
lukaslueg:assertuncheckeddocs
Open

Expand docs on std::hint::assert_unchecked#161262
lukaslueg wants to merge 1 commit into
rust-lang:mainfrom
lukaslueg:assertuncheckeddocs

Conversation

@lukaslueg

@lukaslueg lukaslueg commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

This expands the documentation for std::hint::assert_unchecked(). I tried to rework+expand some rather imprecise language ("simplify things", "UB", "quite unlike anything that would be used in the real world"), reworked the "good usage"-example to not rely on assembly to make its point, and added a "a bool may answer more than you asked for"-counter-example / too-narrow / too-broad. Most importantly for review

  • Language was introduced to the effect that UB may time-travel, without getting into the weeds of it; one consequence of UB is that the argument to assert_unchecked is not guaranteed to be evaluated to the extend the programmer might expect from a bool; parts of the paragraph were aligned with the unreachable_unchecked docs.
  • Language was introduced to the effect that a panic is guaranteed in debug mode; I'm not sure if ub_checks::assert_unsafe_precondition() should be guaranteed, but if it is, it is good to know for the reader.

All tokens used in generating this PR were of purely biological nature.

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Aug 17, 2026
@rustbot

rustbot commented Aug 17, 2026

Copy link
Copy Markdown
Collaborator

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

  • Owners of files modified in this PR: libs
  • libs expanded to 12 candidates
  • Random selection from JohnTitor, Mark-Simulacrum, clarfonthey, nia-e, tgross35

@rust-log-analyzer

Copy link
Copy Markdown
Collaborator

The job pr-check-2 failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)
---- library/core/src/hint.rs - hint::assert_unchecked (line 187) stdout ----
error[E0425]: cannot find function `assert_unchecked` in this scope
   --> library/core/src/hint.rs:197:13
    |
197 |    unsafe { assert_unchecked(x >= 0.) };
    |             ^^^^^^^^^^^^^^^^ not found in this scope
    |
help: consider importing this function
    |
188 + use std::hint::assert_unchecked;
    |

error[E0133]: call to unsafe function `classify_not_negative` is unsafe and requires unsafe block
   --> library/core/src/hint.rs:220:9
    |
220 |    dbg!(classify_not_negative(nan));
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^ call to unsafe function
    |
    = note: consult the function's documentation for information on how to avoid undefined behavior

error: aborting due to 2 previous errors

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants