Function core::intrinsics::is_val_statically_known

const: unstable · source ·
pub fn is_val_statically_known<T: Copy>(_arg: T) -> bool
🔬This is a nightly-only experimental API. (core_intrinsics)
Expand description

Returns whether the argument’s value is statically known at compile-time.

This is useful when there is a way of writing the code that will be faster when some variables have known values, but slower in the general case: an if is_val_statically_known(var) can be used to select between these two variants. The if will be optimized away and only the desired branch remains.

Formally speaking, this function non-deterministically returns true or false, and the caller has to ensure sound behavior for both cases. In other words, the following code has Undefined Behavior:

#![feature(is_val_statically_known)]
#![feature(core_intrinsics)]
use std::hint::unreachable_unchecked;
use std::intrinsics::is_val_statically_known;

if !is_val_statically_known(0) { unsafe { unreachable_unchecked(); } }
Run

This also means that the following code’s behavior is unspecified; it may panic, or it may not:

#![feature(is_val_statically_known)]
#![feature(core_intrinsics)]
use std::intrinsics::is_val_statically_known;

assert_eq!(is_val_statically_known(0), is_val_statically_known(0));
Run

Unsafe code may not rely on is_val_statically_known returning any particular value, ever. However, the compiler will generally make it return true only if the value of the argument is actually known.

When calling this in a const fn, both paths must be semantically equivalent, that is, the result of the true branch and the false branch must return the same value and have the same side-effects no matter what.