Tracking Issue for `option_result_unwrap_unchecked`

[ojeda]

Feature gate: #![feature(option_result_unwrap_unchecked)]

This is a tracking issue for the unchecked variants of unwrap() and unwrap_err() of Option and Result.

These are unsafe functions intended to be used in hot paths of performance sensitive applications where the variant an Option/Result holds is known, allowing to skip the branch that the safe version introduces. They complement other *_unchecked() methods already available, such as get_unchecked() in slices.

Public API

impl<T> Option<T> {
    pub unsafe fn unwrap_unchecked(self) -> T;
}

impl<T, E> Result<T, E> {
    pub unsafe fn unwrap_unchecked(self) -> T;
    pub unsafe fn unwrap_err_unchecked(self) -> E;
}

Steps / History

• Implementation: Add unwrap_unchecked() methods for Option and Result #80876
• Stabilization report: Tracking Issue for option_result_unwrap_unchecked #81383 (comment)
• Final commenting period (FCP): Tracking Issue for option_result_unwrap_unchecked #81383 (comment)
• Stabilization PR: Stabilize option_result_unwrap_unchecked #89951

Unresolved Questions

• Should we add expect_unchecked, and if yes, do it within another feature flag, to unblock unwrap_unchecked? Tracking Issue for option_result_unwrap_unchecked #81383 (comment)

  • It seems best to have it under another feature flag to avoid blocking this one.

• Should we panic on failure in debug (i.e. for those projects that build core themselves)? If yes, that would mean there is no way to actually remove the check for those projects, which could be potentially needed by someone. If we do, should it be documented? Tracking Issue for option_result_unwrap_unchecked #81383 (comment)

  • The current implementation uses debug_assert!, which may be useful for projects that build core with debug assertions enabled (e.g. the bors test suite or some embedded projects), but this is not documented, and indeed most users will not see such behavior, since core is shipped in release mode.
  • Furthermore, since it is UB anyway, we have room for changing the implementation, e.g. if we end up distributing the standard library with debug assertions enabled for some use cases.

• Should we name them unchecked_unwrap instead? Tracking Issue for option_result_unwrap_unchecked #81383 (comment).

  • The current name (unwrap_unchecked) follows the convention of other stable methods in the standard library such as get_unchecked, map_unchecked, new_unchecked, unreachable_unchecked... (see as well https://rust-lang.github.io/api-guidelines/naming.html#getter-names-follow-rust-convention-c-getter).
  • On the other hand, the unchecked_{add,...} methods seem to follow the opposite convention, but those are unstable and they likely do it because the stable {checked,...}_{add,...} exist.

[camelid]

Also: start dogfooding this in std.

[ojeda]

@camelid Indeed! I just submitted the first two PRs for that.

[ojeda]

There are a couple more that can be replaced in library/core/src/iter/adapters/fuse.rs (not counting the macro ones, which are quite a few, but those would require several equivalent functions), but it may make codegen worse due to missed optimizations in LLVM.

I have filled https://bugs.llvm.org/show_bug.cgi?id=48975 with the IR reduction and an analysis of why manually integrating the function (e.g. via a macro) helps sometimes. This may also help other *_unchecked() functions too, e.g. #81354.