# Module std::intrinsics

source · `core_intrinsics`

)## Expand description

Compiler intrinsics.

The corresponding definitions are in https://github.com/rust-lang/rust/blob/master/compiler/rustc_codegen_llvm/src/intrinsic.rs. The corresponding const implementations are in https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/intrinsics.rs.

## §Const intrinsics

Note: any changes to the constness of intrinsics should be discussed with the language team. This includes changes in the stability of the constness.

In order to make an intrinsic usable at compile-time, one needs to copy the implementation
from https://github.com/rust-lang/miri/blob/master/src/shims/intrinsics to
https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/intrinsics.rs and add a
`#[rustc_const_unstable(feature = "const_such_and_such", issue = "01234")]`

to the intrinsic declaration.

If an intrinsic is supposed to be used from a `const fn`

with a `rustc_const_stable`

attribute,
the intrinsic’s attribute must be `rustc_const_stable`

, too. Such a change should not be done
without T-lang consultation, because it bakes a feature into the language that cannot be
replicated in user code without compiler support.

## §Volatiles

The volatile intrinsics provide operations intended to act on I/O memory, which are guaranteed to not be reordered by the compiler across other volatile intrinsics. See the LLVM documentation on [volatile].

## §Atomics

The atomic intrinsics provide common atomic operations on machine words, with multiple possible memory orderings. They obey the same semantics as C++11. See the LLVM documentation on [atomics].

A quick refresher on memory ordering:

- Acquire - a barrier for acquiring a lock. Subsequent reads and writes take place after the barrier.
- Release - a barrier for releasing a lock. Preceding reads and writes take place before the barrier.
- Sequentially consistent - sequentially consistent operations are
guaranteed to happen in order. This is the standard mode for working
with atomic types and is equivalent to Java’s
`volatile`

.

## §Unwinding

Rust intrinsics may, in general, unwind. If an intrinsic can never unwind, add the
`#[rustc_nounwind]`

attribute so that the compiler can make use of this fact.

However, even for intrinsics that may unwind, rustc assumes that a Rust intrinsics will never initiate a foreign (non-Rust) unwind, and thus for panic=abort we can always assume that these intrinsics cannot unwind.

## Modules§

- mir
Experimental Rustc internal tooling for hand-writing MIR. - simd
Experimental SIMD compiler intrinsics.

## Traits§

- Aggregate
RawPtr Experimental

## Functions§

- copy
^{⚠}Copies`count * size_of::<T>()`

bytes from`src`

to`dst`

. The source and destination may overlap. - Copies
`count * size_of::<T>()`

bytes from`src`

to`dst`

. The source and destination must*not*overlap. - transmute
^{⚠}Reinterprets the bits of a value of one type as another type. - write_
bytes ^{⚠}Sets`count * size_of::<T>()`

bytes of memory starting at`dst`

to`val`

. - abort
Experimental Aborts the execution of the process. - add_
with_ overflow Experimental Performs checked integer addition. - aggregate_
raw_ ptr Experimental Lowers in MIR to`Rvalue::Aggregate`

with`AggregateKind::RawPtr`

. - Calculates the offset from a pointer, potentially wrapping.
- assert_
inhabited Experimental A guard for unsafe functions that cannot ever be executed if`T`

is uninhabited: This will statically either panic, or do nothing. - assert_
mem_ uninitialized_ valid Experimental A guard for`std::mem::uninitialized`

. This will statically either panic, or do nothing. - assert_
zero_ valid Experimental A guard for unsafe functions that cannot ever be executed if`T`

does not permit zero-initialization: This will statically either panic, or do nothing. - Informs the optimizer that a condition is always true. If the condition is false, the behavior is undefined.
- Bitwise and with the current value, returning the previous value.
- Bitwise and with the current value, returning the previous value.
- Bitwise and with the current value, returning the previous value.
- Bitwise and with the current value, returning the previous value.
- Bitwise and with the current value, returning the previous value.
- Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - Stores a value if the current value is the same as the
`old`

value. - An atomic fence.
- An atomic fence.
- An atomic fence.
- An atomic fence.
- Loads the current value of the pointer.
- Loads the current value of the pointer.
- Loads the current value of the pointer.
- Do NOT use this intrinsic; “unordered” operations do not exist in our memory model! In terms of the Rust Abstract Machine, this operation is equivalent to
`src.read()`

, i.e., it performs a non-atomic read. - Maximum with the current value using a signed comparison.
- Maximum with the current value using a signed comparison.
- Maximum with the current value.
- Maximum with the current value using a signed comparison.
- Maximum with the current value using a signed comparison.
- Minimum with the current value using a signed comparison.
- Minimum with the current value using a signed comparison.
- Minimum with the current value using a signed comparison.
- Minimum with the current value using a signed comparison.
- Minimum with the current value using a signed comparison.
- Bitwise nand with the current value, returning the previous value.
- Bitwise nand with the current value, returning the previous value.
- Bitwise nand with the current value, returning the previous value.
- Bitwise nand with the current value, returning the previous value.
- Bitwise nand with the current value, returning the previous value.
- Bitwise or with the current value, returning the previous value.
- Bitwise or with the current value, returning the previous value.
- Bitwise or with the current value, returning the previous value.
- Bitwise or with the current value, returning the previous value.
- Bitwise or with the current value, returning the previous value.
- A compiler-only memory barrier.
- A compiler-only memory barrier.
- A compiler-only memory barrier.
- A compiler-only memory barrier.
- Stores the value at the specified memory location.
- Stores the value at the specified memory location.
- Stores the value at the specified memory location.
- Do NOT use this intrinsic; “unordered” operations do not exist in our memory model! In terms of the Rust Abstract Machine, this operation is equivalent to
`dst.write(val)`

, i.e., it performs a non-atomic write. - Maximum with the current value using an unsigned comparison.
- Maximum with the current value using an unsigned comparison.
- Maximum with the current value using an unsigned comparison.
- Maximum with the current value using an unsigned comparison.
- Maximum with the current value using an unsigned comparison.
- Minimum with the current value using an unsigned comparison.
- Minimum with the current value using an unsigned comparison.
- Minimum with the current value using an unsigned comparison.
- Minimum with the current value using an unsigned comparison.
- Minimum with the current value using an unsigned comparison.
- Adds to the current value, returning the previous value.
- Adds to the current value, returning the previous value.
- Adds to the current value, returning the previous value.
- Adds to the current value, returning the previous value.
- Adds to the current value, returning the previous value.
- Stores the value at the specified memory location, returning the old value.
- Stores the value at the specified memory location, returning the old value.
- Stores the value at the specified memory location, returning the old value.
- Stores the value at the specified memory location, returning the old value.
- Stores the value at the specified memory location, returning the old value.
- Bitwise xor with the current value, returning the previous value.
- Bitwise xor with the current value, returning the previous value.
- Bitwise xor with the current value, returning the previous value.
- Bitwise xor with the current value, returning the previous value.
- Bitwise xor with the current value, returning the previous value.
- Subtract from the current value, returning the previous value.
- Subtract from the current value, returning the previous value.
- Subtract from the current value, returning the previous value.
- Subtract from the current value, returning the previous value.
- Subtract from the current value, returning the previous value.
- bitreverse
Experimental Reverses the bits in an integer type`T`

. - black_
box Experimental See documentation of`std::hint::black_box`

for details. - Executes a breakpoint trap, for inspection by a debugger.
- bswap
Experimental Reverses the bytes in an integer type`T`

. - caller_
location Experimental Gets a reference to a static`Location`

indicating where it was called. - Rust’s “try catch” construct for unwinding. Invokes the function pointer
`try_fn`

with the data pointer`data`

, and calls`catch_fn`

if unwinding occurs while`try_fn`

runs. - Returns the smallest integer greater than or equal to an
`f16`

. - Returns the smallest integer greater than or equal to an
`f32`

. - Returns the smallest integer greater than or equal to an
`f64`

. - Returns the smallest integer greater than or equal to an
`f128`

. - Lexicographically compare
`[left, left + bytes)`

and`[right, right + bytes)`

as unsigned bytes, returning negative if`left`

is less, zero if all the bytes match, or positive if`right`

is greater. - Allocates a block of memory at compile time. At runtime, just returns a null pointer.
- Deallocates a memory which allocated by
`intrinsics::const_allocate`

at compile time. At runtime, does nothing. - const_
eval_ select Experimental Selects which function to call depending on the context. - Copies the sign from
`y`

to`x`

for`f16`

values. - Copies the sign from
`y`

to`x`

for`f32`

values. - Copies the sign from
`y`

to`x`

for`f64`

values. - Copies the sign from
`y`

to`x`

for`f128`

values. - Returns the cosine of an
`f16`

. - Returns the cosine of an
`f32`

. - Returns the cosine of an
`f64`

. - Returns the cosine of an
`f128`

. - ctlz
Experimental Returns the number of leading unset bits (zeroes) in an integer type`T`

. - Like
`ctlz`

, but extra-unsafe as it returns`undef`

when given an`x`

with value`0`

. - ctpop
Experimental Returns the number of bits set in an integer type`T`

- cttz
Experimental Returns the number of trailing unset bits (zeroes) in an integer type`T`

. - Like
`cttz`

, but extra-unsafe as it returns`undef`

when given an`x`

with value`0`

. - discriminant_
value Experimental Returns the value of the discriminant for the variant in ‘v’; if`T`

has no discriminant, returns`0`

. - Performs an exact division, resulting in undefined behavior where
`x % y != 0`

or`y == 0`

or`x == T::MIN && y == -1`

- Returns 2 raised to the power of an
`f16`

. - Returns 2 raised to the power of an
`f32`

. - Returns 2 raised to the power of an
`f64`

. - Returns 2 raised to the power of an
`f128`

. - Returns the exponential of an
`f16`

. - Returns the exponential of an
`f32`

. - Returns the exponential of an
`f64`

. - Returns the exponential of an
`f128`

. - Returns the absolute value of an
`f16`

. - Returns the absolute value of an
`f32`

. - Returns the absolute value of an
`f64`

. - Returns the absolute value of an
`f128`

. - fadd_
algebraic Experimental Float addition that allows optimizations based on algebraic rules. - Float addition that allows optimizations based on algebraic rules. May assume inputs are finite.
- fdiv_
algebraic Experimental Float division that allows optimizations based on algebraic rules. - Float division that allows optimizations based on algebraic rules. May assume inputs are finite.
- Converts with LLVM’s fptoui/fptosi, which may return undef for values out of range (https://github.com/rust-lang/rust/issues/10184)
- Returns the largest integer less than or equal to an
`f16`

. - Returns the largest integer less than or equal to an
`f32`

. - Returns the largest integer less than or equal to an
`f64`

. - Returns the largest integer less than or equal to an
`f128`

. - Returns
`a * b + c`

for`f16`

values. - Returns
`a * b + c`

for`f32`

values. - Returns
`a * b + c`

for`f64`

values. - Returns
`a * b + c`

for`f128`

values. - fmul_
algebraic Experimental Float multiplication that allows optimizations based on algebraic rules. - Float multiplication that allows optimizations based on algebraic rules. May assume inputs are finite.
- forget
Experimental Moves a value out of scope without running drop glue. - frem_
algebraic Experimental Float remainder that allows optimizations based on algebraic rules. - Float remainder that allows optimizations based on algebraic rules. May assume inputs are finite.
- fsub_
algebraic Experimental Float subtraction that allows optimizations based on algebraic rules. - Float subtraction that allows optimizations based on algebraic rules. May assume inputs are finite.
- is_
val_ statically_ known Experimental Returns whether the argument’s value is statically known at compile-time. - likely
Experimental Hints to the compiler that branch condition is likely to be true. Returns the value passed to it. - Returns the base 2 logarithm of an
`f16`

. - Returns the base 2 logarithm of an
`f32`

. - Returns the base 2 logarithm of an
`f64`

. - Returns the base 2 logarithm of an
`f128`

. - Returns the base 10 logarithm of an
`f16`

. - Returns the base 10 logarithm of an
`f32`

. - Returns the base 10 logarithm of an
`f64`

. - Returns the base 10 logarithm of an
`f128`

. - Returns the natural logarithm of an
`f16`

. - Returns the natural logarithm of an
`f32`

. - Returns the natural logarithm of an
`f64`

. - Returns the natural logarithm of an
`f128`

. - maxnumf16
Experimental Returns the maximum of two`f16`

values. - maxnumf32
Experimental Returns the maximum of two`f32`

values. - maxnumf64
Experimental Returns the maximum of two`f64`

values. - maxnumf128
Experimental Returns the maximum of two`f128`

values. - min_
align_ of Experimental The minimum alignment of a type. - The required alignment of the referenced value.
- minnumf16
Experimental Returns the minimum of two`f16`

values. - minnumf32
Experimental Returns the minimum of two`f32`

values. - minnumf64
Experimental Returns the minimum of two`f64`

values. - minnumf128
Experimental Returns the minimum of two`f128`

values. - mul_
with_ overflow Experimental Performs checked integer multiplication - Returns the nearest integer to an
`f16`

. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit. - Returns the nearest integer to an
`f32`

. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit. - Returns the nearest integer to an
`f64`

. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit. - Returns the nearest integer to an
`f128`

. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit. - needs_
drop Experimental Returns`true`

if the actual type given as`T`

requires drop glue; returns`false`

if the actual type provided for`T`

implements`Copy`

. - Emits a
`nontemporal`

store, which gives a hint to the CPU that the data should not be held in cache. Except for performance, this is fully equivalent to`ptr.write(val)`

. - Calculates the offset from a pointer.
- Raises an
`f16`

to an`f16`

power. - Raises an
`f32`

to an`f32`

power. - Raises an
`f64`

to an`f64`

power. - Raises an
`f128`

to an`f128`

power. - Raises an
`f16`

to an integer power. - Raises an
`f32`

to an integer power. - Raises an
`f64`

to an integer power. - Raises an
`f128`

to an integer power. - The preferred alignment of a type.
- The
`prefetch`

intrinsic is a hint to the code generator to insert a prefetch instruction if supported; otherwise, it is a no-op. Prefetches have no effect on the behavior of the program but can change its performance characteristics. - The
`prefetch`

intrinsic is a hint to the code generator to insert a prefetch instruction if supported; otherwise, it is a no-op. Prefetches have no effect on the behavior of the program but can change its performance characteristics. - The
`prefetch`

intrinsic is a hint to the code generator to insert a prefetch instruction if supported; otherwise, it is a no-op. Prefetches have no effect on the behavior of the program but can change its performance characteristics. `prefetch`

intrinsic is a hint to the code generator to insert a prefetch instruction if supported; otherwise, it is a no-op. Prefetches have no effect on the behavior of the program but can change its performance characteristics.- ptr_
guaranteed_ cmp Experimental See documentation of`<*const T>::guaranteed_eq`

for details. Returns`2`

if the result is unknown. Returns`1`

if the pointers are guaranteed equal Returns`0`

if the pointers are guaranteed inequal - ptr_
mask Experimental Masks out bits of the pointer according to a mask. - ptr_
metadata Experimental Lowers in MIR to`Rvalue::UnaryOp`

with`UnOp::PtrMetadata`

. - See documentation of
`<*const T>::offset_from`

for details. - See documentation of
`<*const T>::sub_ptr`

for details. - Determines whether the raw bytes of the two values are equal.
- This is an implementation detail of
`crate::ptr::read`

and should not be used anywhere else. See its comments for why this exists. - Returns the nearest integer to an
`f16`

. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit. - Returns the nearest integer to an
`f32`

. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit. - Returns the nearest integer to an
`f64`

. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit. - Returns the nearest integer to an
`f128`

. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit. - rotate_
left Experimental Performs rotate left. - rotate_
right Experimental Performs rotate right. - Returns the nearest integer to an
`f16`

. Rounds half-way cases to the number with an even least significant digit. - Returns the nearest integer to an
`f32`

. Rounds half-way cases to the number with an even least significant digit. - Returns the nearest integer to an
`f64`

. Rounds half-way cases to the number with an even least significant digit. - Returns the nearest integer to an
`f128`

. Rounds half-way cases to the number with an even least significant digit. - Returns the nearest integer to an
`f16`

. Rounds half-way cases away from zero. - Returns the nearest integer to an
`f32`

. Rounds half-way cases away from zero. - Returns the nearest integer to an
`f64`

. Rounds half-way cases away from zero. - Returns the nearest integer to an
`f128`

. Rounds half-way cases away from zero. - rustc_
peek Experimental Magic intrinsic that derives its meaning from attributes attached to the function. - saturating_
add Experimental Computes`a + b`

, saturating at numeric bounds. - saturating_
sub Experimental Computes`a - b`

, saturating at numeric bounds. - select_
unpredictable Experimental Returns either`true_val`

or`false_val`

depending on condition`b`

with a hint to the compiler that this condition is unlikely to be correctly predicted by a CPU’s branch predictor (e.g. a binary search). - Returns the sine of an
`f16`

. - Returns the sine of an
`f32`

. - Returns the sine of an
`f64`

. - Returns the sine of an
`f128`

. - size_of
Experimental The size of a type in bytes. - The size of the referenced value in bytes.
- Returns the square root of an
`f16`

- Returns the square root of an
`f32`

- Returns the square root of an
`f64`

- Returns the square root of an
`f128`

- sub_
with_ overflow Experimental Performs checked integer subtraction - three_
way_ compare Experimental Does a three-way comparison between the two integer arguments. - Like
`transmute`

, but even less checked at compile-time: rather than giving an error for`size_of::<Src>() != size_of::<Dst>()`

, it’s**Undefined Behaviour**at runtime. - Returns the integer part of an
`f16`

. - Returns the integer part of an
`f32`

. - Returns the integer part of an
`f64`

. - Returns the integer part of an
`f128`

. - type_id
Experimental Gets an identifier which is globally unique to the specified type. This function will return the same value for a type regardless of whichever crate it is invoked in. - type_
name Experimental Gets a static string slice containing the name of a type. - Non-overlapping
*typed*swap of a single value. - ub_
checks Experimental Returns whether we should perform some UB-checking at runtime. This eventually evaluates to`cfg!(ub_checks)`

, but behaves different from`cfg!`

when mixing crates built with different flags: if the crate has UB checks enabled or carries the`#[rustc_preserve_ub_checks]`

attribute, evaluation is delayed until monomorphization (or until the call gets inlined into a crate that does not delay evaluation further); otherwise it can happen any time. - Performs a volatile load from the
`src`

pointer The pointer is not required to be aligned. - Performs a volatile store to the
`dst`

pointer. The pointer is not required to be aligned. - Returns the result of an unchecked addition, resulting in undefined behavior when
`x + y > T::MAX`

or`x + y < T::MIN`

. - Performs an unchecked division, resulting in undefined behavior where
`y == 0`

or`x == T::MIN && y == -1`

- Returns the result of an unchecked multiplication, resulting in undefined behavior when
`x * y > T::MAX`

or`x * y < T::MIN`

. - Returns the remainder of an unchecked division, resulting in undefined behavior when
`y == 0`

or`x == T::MIN && y == -1`

- Performs an unchecked left shift, resulting in undefined behavior when
`y < 0`

or`y >= N`

, where N is the width of T in bits. - Performs an unchecked right shift, resulting in undefined behavior when
`y < 0`

or`y >= N`

, where N is the width of T in bits. - Returns the result of an unchecked subtraction, resulting in undefined behavior when
`x - y > T::MAX`

or`x - y < T::MIN`

. - unlikely
Experimental Hints to the compiler that branch condition is likely to be false. Returns the value passed to it. - Informs the optimizer that this point in the code is not reachable, enabling further optimizations.
- variant_
count Experimental Returns the number of variants of the type`T`

cast to a`usize`

; if`T`

has no variants, returns`0`

. Uninhabited variants will be counted. - Equivalent to the appropriate
`llvm.memmove.p0i8.0i8.*`

intrinsic, with a size of`count * size_of::<T>()`

and an alignment of`min_align_of::<T>()`

- Equivalent to the appropriate
`llvm.memcpy.p0i8.0i8.*`

intrinsic, with a size of`count`

*`size_of::<T>()`

and an alignment of`min_align_of::<T>()`

- Performs a volatile load from the
`src`

pointer. - Equivalent to the appropriate
`llvm.memset.p0i8.*`

intrinsic, with a size of`count * size_of::<T>()`

and an alignment of`min_align_of::<T>()`

. - Performs a volatile store to the
`dst`

pointer. - The intrinsic will return the alignment stored in that vtable.
- The intrinsic will return the size stored in that vtable.
- wrapping_
add Experimental Returns (a + b) mod 2^{N}, where N is the width of T in bits. - wrapping_
mul Experimental Returns (a * b) mod 2^{N}, where N is the width of T in bits. - wrapping_
sub Experimental Returns (a - b) mod 2^{N}, where N is the width of T in bits. - This is an implementation detail of
`crate::ptr::write`

and should not be used anywhere else. See its comments for why this exists.