1//! Compiler intrinsics.
2//!
3//! These are the imports making intrinsics available to Rust code. The actual implementations live in the compiler.
4//! Some of these intrinsics are lowered to MIR in <https://github.com/rust-lang/rust/blob/master/compiler/rustc_mir_transform/src/lower_intrinsics.rs>.
5//! The remaining intrinsics are implemented for the LLVM backend in <https://github.com/rust-lang/rust/blob/master/compiler/rustc_codegen_ssa/src/mir/intrinsic.rs>
6//! and <https://github.com/rust-lang/rust/blob/master/compiler/rustc_codegen_llvm/src/intrinsic.rs>,
7//! and for const evaluation in <https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/intrinsics.rs>.
8//!
9//! # Const intrinsics
10//!
11//! In order to make an intrinsic unstable usable at compile-time, copy the implementation from
12//! <https://github.com/rust-lang/miri/blob/master/src/intrinsics> to
13//! <https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/intrinsics.rs>
14//! and make the intrinsic declaration below a `const fn`. This should be done in coordination with
15//! wg-const-eval.
16//!
17//! If an intrinsic is supposed to be used from a `const fn` with a `rustc_const_stable` attribute,
18//! `#[rustc_intrinsic_const_stable_indirect]` needs to be added to the intrinsic. Such a change requires
19//! T-lang approval, because it may bake a feature into the language that cannot be replicated in
20//! user code without compiler support.
21//!
22//! # Volatiles
23//!
24//! The volatile intrinsics provide operations intended to act on I/O
25//! memory, which are guaranteed to not be reordered by the compiler
26//! across other volatile intrinsics. See [`read_volatile`][ptr::read_volatile]
27//! and [`write_volatile`][ptr::write_volatile].
28//!
29//! # Atomics
30//!
31//! The atomic intrinsics provide common atomic operations on machine
32//! words, with multiple possible memory orderings. See the
33//! [atomic types][atomic] docs for details.
34//!
35//! # Unwinding
36//!
37//! Rust intrinsics may, in general, unwind. If an intrinsic can never unwind, add the
38//! `#[rustc_nounwind]` attribute so that the compiler can make use of this fact.
39//!
40//! However, even for intrinsics that may unwind, rustc assumes that a Rust intrinsics will never
41//! initiate a foreign (non-Rust) unwind, and thus for panic=abort we can always assume that these
42//! intrinsics cannot unwind.
43
44#![unstable(
45 feature = "core_intrinsics",
46 reason = "intrinsics are unlikely to ever be stabilized, instead \
47 they should be used through stabilized interfaces \
48 in the rest of the standard library",
49 issue = "none"
50)]
51#![allow(missing_docs)]
52
53use crate::marker::{ConstParamTy, DiscriminantKind, Tuple};
54use crate::ptr;
55
56mod bounds;
57pub mod fallback;
58pub mod mir;
59pub mod simd;
60
61// These imports are used for simplifying intra-doc links
62#[allow(unused_imports)]
63#[cfg(all(target_has_atomic = "8", target_has_atomic = "32", target_has_atomic = "ptr"))]
64use crate::sync::atomic::{self, AtomicBool, AtomicI32, AtomicIsize, AtomicU32, Ordering};
65
66/// A type for atomic ordering parameters for intrinsics. This is a separate type from
67/// `atomic::Ordering` so that we can make it `ConstParamTy` and fix the values used here without a
68/// risk of leaking that to stable code.
69#[derive(Debug, ConstParamTy, PartialEq, Eq)]
70pub enum AtomicOrdering {
71 // These values must match the compiler's `AtomicOrdering` defined in
72 // `rustc_middle/src/ty/consts/int.rs`!
73 Relaxed = 0,
74 Release = 1,
75 Acquire = 2,
76 AcqRel = 3,
77 SeqCst = 4,
78}
79
80// N.B., these intrinsics take raw pointers because they mutate aliased
81// memory, which is not valid for either `&` or `&mut`.
82
83/// Stores a value if the current value is the same as the `old` value.
84/// `T` must be an integer or pointer type.
85///
86/// The stabilized version of this intrinsic is available on the
87/// [`atomic`] types via the `compare_exchange` method.
88/// For example, [`AtomicBool::compare_exchange`].
89#[rustc_intrinsic]
90#[rustc_nounwind]
91pub unsafe fn atomic_cxchg<
92 T: Copy,
93 const ORD_SUCC: AtomicOrdering,
94 const ORD_FAIL: AtomicOrdering,
95>(
96 dst: *mut T,
97 old: T,
98 src: T,
99) -> (T, bool);
100
101/// Stores a value if the current value is the same as the `old` value.
102/// `T` must be an integer or pointer type. The comparison may spuriously fail.
103///
104/// The stabilized version of this intrinsic is available on the
105/// [`atomic`] types via the `compare_exchange_weak` method.
106/// For example, [`AtomicBool::compare_exchange_weak`].
107#[rustc_intrinsic]
108#[rustc_nounwind]
109pub unsafe fn atomic_cxchgweak<
110 T: Copy,
111 const ORD_SUCC: AtomicOrdering,
112 const ORD_FAIL: AtomicOrdering,
113>(
114 _dst: *mut T,
115 _old: T,
116 _src: T,
117) -> (T, bool);
118
119/// Loads the current value of the pointer.
120/// `T` must be an integer or pointer type.
121///
122/// The stabilized version of this intrinsic is available on the
123/// [`atomic`] types via the `load` method. For example, [`AtomicBool::load`].
124#[rustc_intrinsic]
125#[rustc_nounwind]
126pub unsafe fn atomic_load<T: Copy, const ORD: AtomicOrdering>(src: *const T) -> T;
127
128/// Stores the value at the specified memory location.
129/// `T` must be an integer or pointer type.
130///
131/// The stabilized version of this intrinsic is available on the
132/// [`atomic`] types via the `store` method. For example, [`AtomicBool::store`].
133#[rustc_intrinsic]
134#[rustc_nounwind]
135pub unsafe fn atomic_store<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, val: T);
136
137/// Stores the value at the specified memory location, returning the old value.
138/// `T` must be an integer or pointer type.
139///
140/// The stabilized version of this intrinsic is available on the
141/// [`atomic`] types via the `swap` method. For example, [`AtomicBool::swap`].
142#[rustc_intrinsic]
143#[rustc_nounwind]
144pub unsafe fn atomic_xchg<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, src: T) -> T;
145
146/// Adds to the current value, returning the previous value.
147/// `T` must be an integer or pointer type.
148/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
149/// value stored at `*dst` will have the provenance of the old value stored there.
150///
151/// The stabilized version of this intrinsic is available on the
152/// [`atomic`] types via the `fetch_add` method. For example, [`AtomicIsize::fetch_add`].
153#[rustc_intrinsic]
154#[rustc_nounwind]
155pub unsafe fn atomic_xadd<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, src: T) -> T;
156
157/// Subtract from the current value, returning the previous value.
158/// `T` must be an integer or pointer type.
159/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
160/// value stored at `*dst` will have the provenance of the old value stored there.
161///
162/// The stabilized version of this intrinsic is available on the
163/// [`atomic`] types via the `fetch_sub` method. For example, [`AtomicIsize::fetch_sub`].
164#[rustc_intrinsic]
165#[rustc_nounwind]
166pub unsafe fn atomic_xsub<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, src: T) -> T;
167
168/// Bitwise and with the current value, returning the previous value.
169/// `T` must be an integer or pointer type.
170/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
171/// value stored at `*dst` will have the provenance of the old value stored there.
172///
173/// The stabilized version of this intrinsic is available on the
174/// [`atomic`] types via the `fetch_and` method. For example, [`AtomicBool::fetch_and`].
175#[rustc_intrinsic]
176#[rustc_nounwind]
177pub unsafe fn atomic_and<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, src: T) -> T;
178
179/// Bitwise nand with the current value, returning the previous value.
180/// `T` must be an integer or pointer type.
181/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
182/// value stored at `*dst` will have the provenance of the old value stored there.
183///
184/// The stabilized version of this intrinsic is available on the
185/// [`AtomicBool`] type via the `fetch_nand` method. For example, [`AtomicBool::fetch_nand`].
186#[rustc_intrinsic]
187#[rustc_nounwind]
188pub unsafe fn atomic_nand<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, src: T) -> T;
189
190/// Bitwise or with the current value, returning the previous value.
191/// `T` must be an integer or pointer type.
192/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
193/// value stored at `*dst` will have the provenance of the old value stored there.
194///
195/// The stabilized version of this intrinsic is available on the
196/// [`atomic`] types via the `fetch_or` method. For example, [`AtomicBool::fetch_or`].
197#[rustc_intrinsic]
198#[rustc_nounwind]
199pub unsafe fn atomic_or<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, src: T) -> T;
200
201/// Bitwise xor with the current value, returning the previous value.
202/// `T` must be an integer or pointer type.
203/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
204/// value stored at `*dst` will have the provenance of the old value stored there.
205///
206/// The stabilized version of this intrinsic is available on the
207/// [`atomic`] types via the `fetch_xor` method. For example, [`AtomicBool::fetch_xor`].
208#[rustc_intrinsic]
209#[rustc_nounwind]
210pub unsafe fn atomic_xor<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, src: T) -> T;
211
212/// Maximum with the current value using a signed comparison.
213/// `T` must be a signed integer type.
214///
215/// The stabilized version of this intrinsic is available on the
216/// [`atomic`] signed integer types via the `fetch_max` method. For example, [`AtomicI32::fetch_max`].
217#[rustc_intrinsic]
218#[rustc_nounwind]
219pub unsafe fn atomic_max<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, src: T) -> T;
220
221/// Minimum with the current value using a signed comparison.
222/// `T` must be a signed integer type.
223///
224/// The stabilized version of this intrinsic is available on the
225/// [`atomic`] signed integer types via the `fetch_min` method. For example, [`AtomicI32::fetch_min`].
226#[rustc_intrinsic]
227#[rustc_nounwind]
228pub unsafe fn atomic_min<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, src: T) -> T;
229
230/// Minimum with the current value using an unsigned comparison.
231/// `T` must be an unsigned integer type.
232///
233/// The stabilized version of this intrinsic is available on the
234/// [`atomic`] unsigned integer types via the `fetch_min` method. For example, [`AtomicU32::fetch_min`].
235#[rustc_intrinsic]
236#[rustc_nounwind]
237pub unsafe fn atomic_umin<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, src: T) -> T;
238
239/// Maximum with the current value using an unsigned comparison.
240/// `T` must be an unsigned integer type.
241///
242/// The stabilized version of this intrinsic is available on the
243/// [`atomic`] unsigned integer types via the `fetch_max` method. For example, [`AtomicU32::fetch_max`].
244#[rustc_intrinsic]
245#[rustc_nounwind]
246pub unsafe fn atomic_umax<T: Copy, const ORD: AtomicOrdering>(dst: *mut T, src: T) -> T;
247
248/// An atomic fence.
249///
250/// The stabilized version of this intrinsic is available in
251/// [`atomic::fence`].
252#[rustc_intrinsic]
253#[rustc_nounwind]
254pub unsafe fn atomic_fence<const ORD: AtomicOrdering>();
255
256/// An atomic fence for synchronization within a single thread.
257///
258/// The stabilized version of this intrinsic is available in
259/// [`atomic::compiler_fence`].
260#[rustc_intrinsic]
261#[rustc_nounwind]
262pub unsafe fn atomic_singlethreadfence<const ORD: AtomicOrdering>();
263
264/// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
265/// if supported; otherwise, it is a no-op.
266/// Prefetches have no effect on the behavior of the program but can change its performance
267/// characteristics.
268///
269/// The `locality` argument must be a constant integer and is a temporal locality specifier
270/// ranging from (0) - no locality, to (3) - extremely local keep in cache.
271///
272/// This intrinsic does not have a stable counterpart.
273#[rustc_intrinsic]
274#[rustc_nounwind]
275pub unsafe fn prefetch_read_data<T>(data: *const T, locality: i32);
276/// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
277/// if supported; otherwise, it is a no-op.
278/// Prefetches have no effect on the behavior of the program but can change its performance
279/// characteristics.
280///
281/// The `locality` argument must be a constant integer and is a temporal locality specifier
282/// ranging from (0) - no locality, to (3) - extremely local keep in cache.
283///
284/// This intrinsic does not have a stable counterpart.
285#[rustc_intrinsic]
286#[rustc_nounwind]
287pub unsafe fn prefetch_write_data<T>(data: *const T, locality: i32);
288/// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
289/// if supported; otherwise, it is a no-op.
290/// Prefetches have no effect on the behavior of the program but can change its performance
291/// characteristics.
292///
293/// The `locality` argument must be a constant integer and is a temporal locality specifier
294/// ranging from (0) - no locality, to (3) - extremely local keep in cache.
295///
296/// This intrinsic does not have a stable counterpart.
297#[rustc_intrinsic]
298#[rustc_nounwind]
299pub unsafe fn prefetch_read_instruction<T>(data: *const T, locality: i32);
300/// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
301/// if supported; otherwise, it is a no-op.
302/// Prefetches have no effect on the behavior of the program but can change its performance
303/// characteristics.
304///
305/// The `locality` argument must be a constant integer and is a temporal locality specifier
306/// ranging from (0) - no locality, to (3) - extremely local keep in cache.
307///
308/// This intrinsic does not have a stable counterpart.
309#[rustc_intrinsic]
310#[rustc_nounwind]
311pub unsafe fn prefetch_write_instruction<T>(data: *const T, locality: i32);
312
313/// Executes a breakpoint trap, for inspection by a debugger.
314///
315/// This intrinsic does not have a stable counterpart.
316#[rustc_intrinsic]
317#[rustc_nounwind]
318pub fn breakpoint();
319
320/// Magic intrinsic that derives its meaning from attributes
321/// attached to the function.
322///
323/// For example, dataflow uses this to inject static assertions so
324/// that `rustc_peek(potentially_uninitialized)` would actually
325/// double-check that dataflow did indeed compute that it is
326/// uninitialized at that point in the control flow.
327///
328/// This intrinsic should not be used outside of the compiler.
329#[rustc_nounwind]
330#[rustc_intrinsic]
331pub fn rustc_peek<T>(_: T) -> T;
332
333/// Aborts the execution of the process.
334///
335/// Note that, unlike most intrinsics, this is safe to call;
336/// it does not require an `unsafe` block.
337/// Therefore, implementations must not require the user to uphold
338/// any safety invariants.
339///
340/// [`std::process::abort`](../../std/process/fn.abort.html) is to be preferred if possible,
341/// as its behavior is more user-friendly and more stable.
342///
343/// The current implementation of `intrinsics::abort` is to invoke an invalid instruction,
344/// on most platforms.
345/// On Unix, the
346/// process will probably terminate with a signal like `SIGABRT`, `SIGILL`, `SIGTRAP`, `SIGSEGV` or
347/// `SIGBUS`. The precise behavior is not guaranteed and not stable.
348#[rustc_nounwind]
349#[rustc_intrinsic]
350pub fn abort() -> !;
351
352/// Informs the optimizer that this point in the code is not reachable,
353/// enabling further optimizations.
354///
355/// N.B., this is very different from the `unreachable!()` macro: Unlike the
356/// macro, which panics when it is executed, it is *undefined behavior* to
357/// reach code marked with this function.
358///
359/// The stabilized version of this intrinsic is [`core::hint::unreachable_unchecked`].
360#[rustc_intrinsic_const_stable_indirect]
361#[rustc_nounwind]
362#[rustc_intrinsic]
363pub const unsafe fn unreachable() -> !;
364
365/// Informs the optimizer that a condition is always true.
366/// If the condition is false, the behavior is undefined.
367///
368/// No code is generated for this intrinsic, but the optimizer will try
369/// to preserve it (and its condition) between passes, which may interfere
370/// with optimization of surrounding code and reduce performance. It should
371/// not be used if the invariant can be discovered by the optimizer on its
372/// own, or if it does not enable any significant optimizations.
373///
374/// The stabilized version of this intrinsic is [`core::hint::assert_unchecked`].
375#[rustc_intrinsic_const_stable_indirect]
376#[rustc_nounwind]
377#[unstable(feature = "core_intrinsics", issue = "none")]
378#[rustc_intrinsic]
379pub const unsafe fn assume(b: bool) {
380 if !b {
381 // SAFETY: the caller must guarantee the argument is never `false`
382 unsafe { unreachable() }
383 }
384}
385
386/// Hints to the compiler that current code path is cold.
387///
388/// Note that, unlike most intrinsics, this is safe to call;
389/// it does not require an `unsafe` block.
390/// Therefore, implementations must not require the user to uphold
391/// any safety invariants.
392///
393/// This intrinsic does not have a stable counterpart.
394#[unstable(feature = "core_intrinsics", issue = "none")]
395#[rustc_intrinsic]
396#[rustc_nounwind]
397#[miri::intrinsic_fallback_is_spec]
398#[cold]
399pub const fn cold_path() {}
400
401/// Hints to the compiler that branch condition is likely to be true.
402/// Returns the value passed to it.
403///
404/// Any use other than with `if` statements will probably not have an effect.
405///
406/// Note that, unlike most intrinsics, this is safe to call;
407/// it does not require an `unsafe` block.
408/// Therefore, implementations must not require the user to uphold
409/// any safety invariants.
410///
411/// This intrinsic does not have a stable counterpart.
412#[unstable(feature = "core_intrinsics", issue = "none")]
413#[rustc_nounwind]
414#[inline(always)]
415pub const fn likely(b: bool) -> bool {
416 if b {
417 true
418 } else {
419 cold_path();
420 false
421 }
422}
423
424/// Hints to the compiler that branch condition is likely to be false.
425/// Returns the value passed to it.
426///
427/// Any use other than with `if` statements will probably not have an effect.
428///
429/// Note that, unlike most intrinsics, this is safe to call;
430/// it does not require an `unsafe` block.
431/// Therefore, implementations must not require the user to uphold
432/// any safety invariants.
433///
434/// This intrinsic does not have a stable counterpart.
435#[unstable(feature = "core_intrinsics", issue = "none")]
436#[rustc_nounwind]
437#[inline(always)]
438pub const fn unlikely(b: bool) -> bool {
439 if b {
440 cold_path();
441 true
442 } else {
443 false
444 }
445}
446
447/// Returns either `true_val` or `false_val` depending on condition `b` with a
448/// hint to the compiler that this condition is unlikely to be correctly
449/// predicted by a CPU's branch predictor (e.g. a binary search).
450///
451/// This is otherwise functionally equivalent to `if b { true_val } else { false_val }`.
452///
453/// Note that, unlike most intrinsics, this is safe to call;
454/// it does not require an `unsafe` block.
455/// Therefore, implementations must not require the user to uphold
456/// any safety invariants.
457///
458/// The public form of this instrinsic is [`core::hint::select_unpredictable`].
459/// However unlike the public form, the intrinsic will not drop the value that
460/// is not selected.
461#[unstable(feature = "core_intrinsics", issue = "none")]
462#[rustc_intrinsic]
463#[rustc_nounwind]
464#[miri::intrinsic_fallback_is_spec]
465#[inline]
466pub fn select_unpredictable<T>(b: bool, true_val: T, false_val: T) -> T {
467 if b { true_val } else { false_val }
468}
469
470/// A guard for unsafe functions that cannot ever be executed if `T` is uninhabited:
471/// This will statically either panic, or do nothing.
472///
473/// This intrinsic does not have a stable counterpart.
474#[rustc_intrinsic_const_stable_indirect]
475#[rustc_nounwind]
476#[rustc_intrinsic]
477pub const fn assert_inhabited<T>();
478
479/// A guard for unsafe functions that cannot ever be executed if `T` does not permit
480/// zero-initialization: This will statically either panic, or do nothing.
481///
482/// This intrinsic does not have a stable counterpart.
483#[rustc_intrinsic_const_stable_indirect]
484#[rustc_nounwind]
485#[rustc_intrinsic]
486pub const fn assert_zero_valid<T>();
487
488/// A guard for `std::mem::uninitialized`. This will statically either panic, or do nothing.
489///
490/// This intrinsic does not have a stable counterpart.
491#[rustc_intrinsic_const_stable_indirect]
492#[rustc_nounwind]
493#[rustc_intrinsic]
494pub const fn assert_mem_uninitialized_valid<T>();
495
496/// Gets a reference to a static `Location` indicating where it was called.
497///
498/// Note that, unlike most intrinsics, this is safe to call;
499/// it does not require an `unsafe` block.
500/// Therefore, implementations must not require the user to uphold
501/// any safety invariants.
502///
503/// Consider using [`core::panic::Location::caller`] instead.
504#[rustc_intrinsic_const_stable_indirect]
505#[rustc_nounwind]
506#[rustc_intrinsic]
507pub const fn caller_location() -> &'static crate::panic::Location<'static>;
508
509/// Moves a value out of scope without running drop glue.
510///
511/// This exists solely for [`crate::mem::forget_unsized`]; normal `forget` uses
512/// `ManuallyDrop` instead.
513///
514/// Note that, unlike most intrinsics, this is safe to call;
515/// it does not require an `unsafe` block.
516/// Therefore, implementations must not require the user to uphold
517/// any safety invariants.
518#[rustc_intrinsic_const_stable_indirect]
519#[rustc_nounwind]
520#[rustc_intrinsic]
521pub const fn forget<T: ?Sized>(_: T);
522
523/// Reinterprets the bits of a value of one type as another type.
524///
525/// Both types must have the same size. Compilation will fail if this is not guaranteed.
526///
527/// `transmute` is semantically equivalent to a bitwise move of one type
528/// into another. It copies the bits from the source value into the
529/// destination value, then forgets the original. Note that source and destination
530/// are passed by-value, which means if `Src` or `Dst` contain padding, that padding
531/// is *not* guaranteed to be preserved by `transmute`.
532///
533/// Both the argument and the result must be [valid](../../nomicon/what-unsafe-does.html) at
534/// their given type. Violating this condition leads to [undefined behavior][ub]. The compiler
535/// will generate code *assuming that you, the programmer, ensure that there will never be
536/// undefined behavior*. It is therefore your responsibility to guarantee that every value
537/// passed to `transmute` is valid at both types `Src` and `Dst`. Failing to uphold this condition
538/// may lead to unexpected and unstable compilation results. This makes `transmute` **incredibly
539/// unsafe**. `transmute` should be the absolute last resort.
540///
541/// Because `transmute` is a by-value operation, alignment of the *transmuted values
542/// themselves* is not a concern. As with any other function, the compiler already ensures
543/// both `Src` and `Dst` are properly aligned. However, when transmuting values that *point
544/// elsewhere* (such as pointers, references, boxes…), the caller has to ensure proper
545/// alignment of the pointed-to values.
546///
547/// The [nomicon](../../nomicon/transmutes.html) has additional documentation.
548///
549/// [ub]: ../../reference/behavior-considered-undefined.html
550///
551/// # Transmutation between pointers and integers
552///
553/// Special care has to be taken when transmuting between pointers and integers, e.g.
554/// transmuting between `*const ()` and `usize`.
555///
556/// Transmuting *pointers to integers* in a `const` context is [undefined behavior][ub], unless
557/// the pointer was originally created *from* an integer. (That includes this function
558/// specifically, integer-to-pointer casts, and helpers like [`dangling`][crate::ptr::dangling],
559/// but also semantically-equivalent conversions such as punning through `repr(C)` union
560/// fields.) Any attempt to use the resulting value for integer operations will abort
561/// const-evaluation. (And even outside `const`, such transmutation is touching on many
562/// unspecified aspects of the Rust memory model and should be avoided. See below for
563/// alternatives.)
564///
565/// Transmuting *integers to pointers* is a largely unspecified operation. It is likely *not*
566/// equivalent to an `as` cast. Doing non-zero-sized memory accesses with a pointer constructed
567/// this way is currently considered undefined behavior.
568///
569/// All this also applies when the integer is nested inside an array, tuple, struct, or enum.
570/// However, `MaybeUninit<usize>` is not considered an integer type for the purpose of this
571/// section. Transmuting `*const ()` to `MaybeUninit<usize>` is fine---but then calling
572/// `assume_init()` on that result is considered as completing the pointer-to-integer transmute
573/// and thus runs into the issues discussed above.
574///
575/// In particular, doing a pointer-to-integer-to-pointer roundtrip via `transmute` is *not* a
576/// lossless process. If you want to round-trip a pointer through an integer in a way that you
577/// can get back the original pointer, you need to use `as` casts, or replace the integer type
578/// by `MaybeUninit<$int>` (and never call `assume_init()`). If you are looking for a way to
579/// store data of arbitrary type, also use `MaybeUninit<T>` (that will also handle uninitialized
580/// memory due to padding). If you specifically need to store something that is "either an
581/// integer or a pointer", use `*mut ()`: integers can be converted to pointers and back without
582/// any loss (via `as` casts or via `transmute`).
583///
584/// # Examples
585///
586/// There are a few things that `transmute` is really useful for.
587///
588/// Turning a pointer into a function pointer. This is *not* portable to
589/// machines where function pointers and data pointers have different sizes.
590///
591/// ```
592/// fn foo() -> i32 {
593/// 0
594/// }
595/// // Crucially, we `as`-cast to a raw pointer before `transmute`ing to a function pointer.
596/// // This avoids an integer-to-pointer `transmute`, which can be problematic.
597/// // Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine.
598/// let pointer = foo as *const ();
599/// let function = unsafe {
600/// std::mem::transmute::<*const (), fn() -> i32>(pointer)
601/// };
602/// assert_eq!(function(), 0);
603/// ```
604///
605/// Extending a lifetime, or shortening an invariant lifetime. This is
606/// advanced, very unsafe Rust!
607///
608/// ```
609/// struct R<'a>(&'a i32);
610/// unsafe fn extend_lifetime<'b>(r: R<'b>) -> R<'static> {
611/// unsafe { std::mem::transmute::<R<'b>, R<'static>>(r) }
612/// }
613///
614/// unsafe fn shorten_invariant_lifetime<'b, 'c>(r: &'b mut R<'static>)
615/// -> &'b mut R<'c> {
616/// unsafe { std::mem::transmute::<&'b mut R<'static>, &'b mut R<'c>>(r) }
617/// }
618/// ```
619///
620/// # Alternatives
621///
622/// Don't despair: many uses of `transmute` can be achieved through other means.
623/// Below are common applications of `transmute` which can be replaced with safer
624/// constructs.
625///
626/// Turning raw bytes (`[u8; SZ]`) into `u32`, `f64`, etc.:
627///
628/// ```
629/// # #![allow(unnecessary_transmutes)]
630/// let raw_bytes = [0x78, 0x56, 0x34, 0x12];
631///
632/// let num = unsafe {
633/// std::mem::transmute::<[u8; 4], u32>(raw_bytes)
634/// };
635///
636/// // use `u32::from_ne_bytes` instead
637/// let num = u32::from_ne_bytes(raw_bytes);
638/// // or use `u32::from_le_bytes` or `u32::from_be_bytes` to specify the endianness
639/// let num = u32::from_le_bytes(raw_bytes);
640/// assert_eq!(num, 0x12345678);
641/// let num = u32::from_be_bytes(raw_bytes);
642/// assert_eq!(num, 0x78563412);
643/// ```
644///
645/// Turning a pointer into a `usize`:
646///
647/// ```no_run
648/// let ptr = &0;
649/// let ptr_num_transmute = unsafe {
650/// std::mem::transmute::<&i32, usize>(ptr)
651/// };
652///
653/// // Use an `as` cast instead
654/// let ptr_num_cast = ptr as *const i32 as usize;
655/// ```
656///
657/// Note that using `transmute` to turn a pointer to a `usize` is (as noted above) [undefined
658/// behavior][ub] in `const` contexts. Also outside of consts, this operation might not behave
659/// as expected -- this is touching on many unspecified aspects of the Rust memory model.
660/// Depending on what the code is doing, the following alternatives are preferable to
661/// pointer-to-integer transmutation:
662/// - If the code just wants to store data of arbitrary type in some buffer and needs to pick a
663/// type for that buffer, it can use [`MaybeUninit`][crate::mem::MaybeUninit].
664/// - If the code actually wants to work on the address the pointer points to, it can use `as`
665/// casts or [`ptr.addr()`][pointer::addr].
666///
667/// Turning a `*mut T` into a `&mut T`:
668///
669/// ```
670/// let ptr: *mut i32 = &mut 0;
671/// let ref_transmuted = unsafe {
672/// std::mem::transmute::<*mut i32, &mut i32>(ptr)
673/// };
674///
675/// // Use a reborrow instead
676/// let ref_casted = unsafe { &mut *ptr };
677/// ```
678///
679/// Turning a `&mut T` into a `&mut U`:
680///
681/// ```
682/// let ptr = &mut 0;
683/// let val_transmuted = unsafe {
684/// std::mem::transmute::<&mut i32, &mut u32>(ptr)
685/// };
686///
687/// // Now, put together `as` and reborrowing - note the chaining of `as`
688/// // `as` is not transitive
689/// let val_casts = unsafe { &mut *(ptr as *mut i32 as *mut u32) };
690/// ```
691///
692/// Turning a `&str` into a `&[u8]`:
693///
694/// ```
695/// // this is not a good way to do this.
696/// let slice = unsafe { std::mem::transmute::<&str, &[u8]>("Rust") };
697/// assert_eq!(slice, &[82, 117, 115, 116]);
698///
699/// // You could use `str::as_bytes`
700/// let slice = "Rust".as_bytes();
701/// assert_eq!(slice, &[82, 117, 115, 116]);
702///
703/// // Or, just use a byte string, if you have control over the string
704/// // literal
705/// assert_eq!(b"Rust", &[82, 117, 115, 116]);
706/// ```
707///
708/// Turning a `Vec<&T>` into a `Vec<Option<&T>>`.
709///
710/// To transmute the inner type of the contents of a container, you must make sure to not
711/// violate any of the container's invariants. For `Vec`, this means that both the size
712/// *and alignment* of the inner types have to match. Other containers might rely on the
713/// size of the type, alignment, or even the `TypeId`, in which case transmuting wouldn't
714/// be possible at all without violating the container invariants.
715///
716/// ```
717/// let store = [0, 1, 2, 3];
718/// let v_orig = store.iter().collect::<Vec<&i32>>();
719///
720/// // clone the vector as we will reuse them later
721/// let v_clone = v_orig.clone();
722///
723/// // Using transmute: this relies on the unspecified data layout of `Vec`, which is a
724/// // bad idea and could cause Undefined Behavior.
725/// // However, it is no-copy.
726/// let v_transmuted = unsafe {
727/// std::mem::transmute::<Vec<&i32>, Vec<Option<&i32>>>(v_clone)
728/// };
729///
730/// let v_clone = v_orig.clone();
731///
732/// // This is the suggested, safe way.
733/// // It may copy the entire vector into a new one though, but also may not.
734/// let v_collected = v_clone.into_iter()
735/// .map(Some)
736/// .collect::<Vec<Option<&i32>>>();
737///
738/// let v_clone = v_orig.clone();
739///
740/// // This is the proper no-copy, unsafe way of "transmuting" a `Vec`, without relying on the
741/// // data layout. Instead of literally calling `transmute`, we perform a pointer cast, but
742/// // in terms of converting the original inner type (`&i32`) to the new one (`Option<&i32>`),
743/// // this has all the same caveats. Besides the information provided above, also consult the
744/// // [`from_raw_parts`] documentation.
745/// let v_from_raw = unsafe {
746// FIXME Update this when vec_into_raw_parts is stabilized
747/// // Ensure the original vector is not dropped.
748/// let mut v_clone = std::mem::ManuallyDrop::new(v_clone);
749/// Vec::from_raw_parts(v_clone.as_mut_ptr() as *mut Option<&i32>,
750/// v_clone.len(),
751/// v_clone.capacity())
752/// };
753/// ```
754///
755/// [`from_raw_parts`]: ../../std/vec/struct.Vec.html#method.from_raw_parts
756///
757/// Implementing `split_at_mut`:
758///
759/// ```
760/// use std::{slice, mem};
761///
762/// // There are multiple ways to do this, and there are multiple problems
763/// // with the following (transmute) way.
764/// fn split_at_mut_transmute<T>(slice: &mut [T], mid: usize)
765/// -> (&mut [T], &mut [T]) {
766/// let len = slice.len();
767/// assert!(mid <= len);
768/// unsafe {
769/// let slice2 = mem::transmute::<&mut [T], &mut [T]>(slice);
770/// // first: transmute is not type safe; all it checks is that T and
771/// // U are of the same size. Second, right here, you have two
772/// // mutable references pointing to the same memory.
773/// (&mut slice[0..mid], &mut slice2[mid..len])
774/// }
775/// }
776///
777/// // This gets rid of the type safety problems; `&mut *` will *only* give
778/// // you a `&mut T` from a `&mut T` or `*mut T`.
779/// fn split_at_mut_casts<T>(slice: &mut [T], mid: usize)
780/// -> (&mut [T], &mut [T]) {
781/// let len = slice.len();
782/// assert!(mid <= len);
783/// unsafe {
784/// let slice2 = &mut *(slice as *mut [T]);
785/// // however, you still have two mutable references pointing to
786/// // the same memory.
787/// (&mut slice[0..mid], &mut slice2[mid..len])
788/// }
789/// }
790///
791/// // This is how the standard library does it. This is the best method, if
792/// // you need to do something like this
793/// fn split_at_stdlib<T>(slice: &mut [T], mid: usize)
794/// -> (&mut [T], &mut [T]) {
795/// let len = slice.len();
796/// assert!(mid <= len);
797/// unsafe {
798/// let ptr = slice.as_mut_ptr();
799/// // This now has three mutable references pointing at the same
800/// // memory. `slice`, the rvalue ret.0, and the rvalue ret.1.
801/// // `slice` is never used after `let ptr = ...`, and so one can
802/// // treat it as "dead", and therefore, you only have two real
803/// // mutable slices.
804/// (slice::from_raw_parts_mut(ptr, mid),
805/// slice::from_raw_parts_mut(ptr.add(mid), len - mid))
806/// }
807/// }
808/// ```
809#[stable(feature = "rust1", since = "1.0.0")]
810#[rustc_allowed_through_unstable_modules = "import this function via `std::mem` instead"]
811#[rustc_const_stable(feature = "const_transmute", since = "1.56.0")]
812#[rustc_diagnostic_item = "transmute"]
813#[rustc_nounwind]
814#[rustc_intrinsic]
815pub const unsafe fn transmute<Src, Dst>(src: Src) -> Dst;
816
817/// Like [`transmute`], but even less checked at compile-time: rather than
818/// giving an error for `size_of::<Src>() != size_of::<Dst>()`, it's
819/// **Undefined Behavior** at runtime.
820///
821/// Prefer normal `transmute` where possible, for the extra checking, since
822/// both do exactly the same thing at runtime, if they both compile.
823///
824/// This is not expected to ever be exposed directly to users, rather it
825/// may eventually be exposed through some more-constrained API.
826#[rustc_intrinsic_const_stable_indirect]
827#[rustc_nounwind]
828#[rustc_intrinsic]
829pub const unsafe fn transmute_unchecked<Src, Dst>(src: Src) -> Dst;
830
831/// Returns `true` if the actual type given as `T` requires drop
832/// glue; returns `false` if the actual type provided for `T`
833/// implements `Copy`.
834///
835/// If the actual type neither requires drop glue nor implements
836/// `Copy`, then the return value of this function is unspecified.
837///
838/// Note that, unlike most intrinsics, this is safe to call;
839/// it does not require an `unsafe` block.
840/// Therefore, implementations must not require the user to uphold
841/// any safety invariants.
842///
843/// The stabilized version of this intrinsic is [`mem::needs_drop`](crate::mem::needs_drop).
844#[rustc_intrinsic_const_stable_indirect]
845#[rustc_nounwind]
846#[rustc_intrinsic]
847pub const fn needs_drop<T: ?Sized>() -> bool;
848
849/// Calculates the offset from a pointer.
850///
851/// This is implemented as an intrinsic to avoid converting to and from an
852/// integer, since the conversion would throw away aliasing information.
853///
854/// This can only be used with `Ptr` as a raw pointer type (`*mut` or `*const`)
855/// to a `Sized` pointee and with `Delta` as `usize` or `isize`. Any other
856/// instantiations may arbitrarily misbehave, and that's *not* a compiler bug.
857///
858/// # Safety
859///
860/// If the computed offset is non-zero, then both the starting and resulting pointer must be
861/// either in bounds or at the end of an allocation. If either pointer is out
862/// of bounds or arithmetic overflow occurs then this operation is undefined behavior.
863///
864/// The stabilized version of this intrinsic is [`pointer::offset`].
865#[must_use = "returns a new pointer rather than modifying its argument"]
866#[rustc_intrinsic_const_stable_indirect]
867#[rustc_nounwind]
868#[rustc_intrinsic]
869pub const unsafe fn offset<Ptr: bounds::BuiltinDeref, Delta>(dst: Ptr, offset: Delta) -> Ptr;
870
871/// Calculates the offset from a pointer, potentially wrapping.
872///
873/// This is implemented as an intrinsic to avoid converting to and from an
874/// integer, since the conversion inhibits certain optimizations.
875///
876/// # Safety
877///
878/// Unlike the `offset` intrinsic, this intrinsic does not restrict the
879/// resulting pointer to point into or at the end of an allocated
880/// object, and it wraps with two's complement arithmetic. The resulting
881/// value is not necessarily valid to be used to actually access memory.
882///
883/// The stabilized version of this intrinsic is [`pointer::wrapping_offset`].
884#[must_use = "returns a new pointer rather than modifying its argument"]
885#[rustc_intrinsic_const_stable_indirect]
886#[rustc_nounwind]
887#[rustc_intrinsic]
888pub const unsafe fn arith_offset<T>(dst: *const T, offset: isize) -> *const T;
889
890/// Projects to the `index`-th element of `slice_ptr`, as the same kind of pointer
891/// as the slice was provided -- so `&mut [T] → &mut T`, `&[T] → &T`,
892/// `*mut [T] → *mut T`, or `*const [T] → *const T` -- without a bounds check.
893///
894/// This is exposed via `<usize as SliceIndex>::get(_unchecked)(_mut)`,
895/// and isn't intended to be used elsewhere.
896///
897/// Expands in MIR to `{&, &mut, &raw const, &raw mut} (*slice_ptr)[index]`,
898/// depending on the types involved, so no backend support is needed.
899///
900/// # Safety
901///
902/// - `index < PtrMetadata(slice_ptr)`, so the indexing is in-bounds for the slice
903/// - the resulting offsetting is in-bounds of the allocated object, which is
904/// always the case for references, but needs to be upheld manually for pointers
905#[rustc_nounwind]
906#[rustc_intrinsic]
907pub const unsafe fn slice_get_unchecked<
908 ItemPtr: bounds::ChangePointee<[T], Pointee = T, Output = SlicePtr>,
909 SlicePtr,
910 T,
911>(
912 slice_ptr: SlicePtr,
913 index: usize,
914) -> ItemPtr;
915
916/// Masks out bits of the pointer according to a mask.
917///
918/// Note that, unlike most intrinsics, this is safe to call;
919/// it does not require an `unsafe` block.
920/// Therefore, implementations must not require the user to uphold
921/// any safety invariants.
922///
923/// Consider using [`pointer::mask`] instead.
924#[rustc_nounwind]
925#[rustc_intrinsic]
926pub fn ptr_mask<T>(ptr: *const T, mask: usize) -> *const T;
927
928/// Equivalent to the appropriate `llvm.memcpy.p0i8.0i8.*` intrinsic, with
929/// a size of `count` * `size_of::<T>()` and an alignment of
930/// `min_align_of::<T>()`
931///
932/// This intrinsic does not have a stable counterpart.
933/// # Safety
934///
935/// The safety requirements are consistent with [`copy_nonoverlapping`]
936/// while the read and write behaviors are volatile,
937/// which means it will not be optimized out unless `_count` or `size_of::<T>()` is equal to zero.
938///
939/// [`copy_nonoverlapping`]: ptr::copy_nonoverlapping
940#[rustc_intrinsic]
941#[rustc_nounwind]
942pub unsafe fn volatile_copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: usize);
943/// Equivalent to the appropriate `llvm.memmove.p0i8.0i8.*` intrinsic, with
944/// a size of `count * size_of::<T>()` and an alignment of
945/// `min_align_of::<T>()`
946///
947/// The volatile parameter is set to `true`, so it will not be optimized out
948/// unless size is equal to zero.
949///
950/// This intrinsic does not have a stable counterpart.
951#[rustc_intrinsic]
952#[rustc_nounwind]
953pub unsafe fn volatile_copy_memory<T>(dst: *mut T, src: *const T, count: usize);
954/// Equivalent to the appropriate `llvm.memset.p0i8.*` intrinsic, with a
955/// size of `count * size_of::<T>()` and an alignment of
956/// `min_align_of::<T>()`.
957///
958/// This intrinsic does not have a stable counterpart.
959/// # Safety
960///
961/// The safety requirements are consistent with [`write_bytes`] while the write behavior is volatile,
962/// which means it will not be optimized out unless `_count` or `size_of::<T>()` is equal to zero.
963///
964/// [`write_bytes`]: ptr::write_bytes
965#[rustc_intrinsic]
966#[rustc_nounwind]
967pub unsafe fn volatile_set_memory<T>(dst: *mut T, val: u8, count: usize);
968
969/// Performs a volatile load from the `src` pointer.
970///
971/// The stabilized version of this intrinsic is [`core::ptr::read_volatile`].
972#[rustc_intrinsic]
973#[rustc_nounwind]
974pub unsafe fn volatile_load<T>(src: *const T) -> T;
975/// Performs a volatile store to the `dst` pointer.
976///
977/// The stabilized version of this intrinsic is [`core::ptr::write_volatile`].
978#[rustc_intrinsic]
979#[rustc_nounwind]
980pub unsafe fn volatile_store<T>(dst: *mut T, val: T);
981
982/// Performs a volatile load from the `src` pointer
983/// The pointer is not required to be aligned.
984///
985/// This intrinsic does not have a stable counterpart.
986#[rustc_intrinsic]
987#[rustc_nounwind]
988#[rustc_diagnostic_item = "intrinsics_unaligned_volatile_load"]
989pub unsafe fn unaligned_volatile_load<T>(src: *const T) -> T;
990/// Performs a volatile store to the `dst` pointer.
991/// The pointer is not required to be aligned.
992///
993/// This intrinsic does not have a stable counterpart.
994#[rustc_intrinsic]
995#[rustc_nounwind]
996#[rustc_diagnostic_item = "intrinsics_unaligned_volatile_store"]
997pub unsafe fn unaligned_volatile_store<T>(dst: *mut T, val: T);
998
999/// Returns the square root of an `f16`
1000///
1001/// The stabilized version of this intrinsic is
1002/// [`f16::sqrt`](../../std/primitive.f16.html#method.sqrt)
1003#[rustc_intrinsic]
1004#[rustc_nounwind]
1005pub unsafe fn sqrtf16(x: f16) -> f16;
1006/// Returns the square root of an `f32`
1007///
1008/// The stabilized version of this intrinsic is
1009/// [`f32::sqrt`](../../std/primitive.f32.html#method.sqrt)
1010#[rustc_intrinsic]
1011#[rustc_nounwind]
1012pub unsafe fn sqrtf32(x: f32) -> f32;
1013/// Returns the square root of an `f64`
1014///
1015/// The stabilized version of this intrinsic is
1016/// [`f64::sqrt`](../../std/primitive.f64.html#method.sqrt)
1017#[rustc_intrinsic]
1018#[rustc_nounwind]
1019pub unsafe fn sqrtf64(x: f64) -> f64;
1020/// Returns the square root of an `f128`
1021///
1022/// The stabilized version of this intrinsic is
1023/// [`f128::sqrt`](../../std/primitive.f128.html#method.sqrt)
1024#[rustc_intrinsic]
1025#[rustc_nounwind]
1026pub unsafe fn sqrtf128(x: f128) -> f128;
1027
1028/// Raises an `f16` to an integer power.
1029///
1030/// The stabilized version of this intrinsic is
1031/// [`f16::powi`](../../std/primitive.f16.html#method.powi)
1032#[rustc_intrinsic]
1033#[rustc_nounwind]
1034pub unsafe fn powif16(a: f16, x: i32) -> f16;
1035/// Raises an `f32` to an integer power.
1036///
1037/// The stabilized version of this intrinsic is
1038/// [`f32::powi`](../../std/primitive.f32.html#method.powi)
1039#[rustc_intrinsic]
1040#[rustc_nounwind]
1041pub unsafe fn powif32(a: f32, x: i32) -> f32;
1042/// Raises an `f64` to an integer power.
1043///
1044/// The stabilized version of this intrinsic is
1045/// [`f64::powi`](../../std/primitive.f64.html#method.powi)
1046#[rustc_intrinsic]
1047#[rustc_nounwind]
1048pub unsafe fn powif64(a: f64, x: i32) -> f64;
1049/// Raises an `f128` to an integer power.
1050///
1051/// The stabilized version of this intrinsic is
1052/// [`f128::powi`](../../std/primitive.f128.html#method.powi)
1053#[rustc_intrinsic]
1054#[rustc_nounwind]
1055pub unsafe fn powif128(a: f128, x: i32) -> f128;
1056
1057/// Returns the sine of an `f16`.
1058///
1059/// The stabilized version of this intrinsic is
1060/// [`f16::sin`](../../std/primitive.f16.html#method.sin)
1061#[rustc_intrinsic]
1062#[rustc_nounwind]
1063pub unsafe fn sinf16(x: f16) -> f16;
1064/// Returns the sine of an `f32`.
1065///
1066/// The stabilized version of this intrinsic is
1067/// [`f32::sin`](../../std/primitive.f32.html#method.sin)
1068#[rustc_intrinsic]
1069#[rustc_nounwind]
1070pub unsafe fn sinf32(x: f32) -> f32;
1071/// Returns the sine of an `f64`.
1072///
1073/// The stabilized version of this intrinsic is
1074/// [`f64::sin`](../../std/primitive.f64.html#method.sin)
1075#[rustc_intrinsic]
1076#[rustc_nounwind]
1077pub unsafe fn sinf64(x: f64) -> f64;
1078/// Returns the sine of an `f128`.
1079///
1080/// The stabilized version of this intrinsic is
1081/// [`f128::sin`](../../std/primitive.f128.html#method.sin)
1082#[rustc_intrinsic]
1083#[rustc_nounwind]
1084pub unsafe fn sinf128(x: f128) -> f128;
1085
1086/// Returns the cosine of an `f16`.
1087///
1088/// The stabilized version of this intrinsic is
1089/// [`f16::cos`](../../std/primitive.f16.html#method.cos)
1090#[rustc_intrinsic]
1091#[rustc_nounwind]
1092pub unsafe fn cosf16(x: f16) -> f16;
1093/// Returns the cosine of an `f32`.
1094///
1095/// The stabilized version of this intrinsic is
1096/// [`f32::cos`](../../std/primitive.f32.html#method.cos)
1097#[rustc_intrinsic]
1098#[rustc_nounwind]
1099pub unsafe fn cosf32(x: f32) -> f32;
1100/// Returns the cosine of an `f64`.
1101///
1102/// The stabilized version of this intrinsic is
1103/// [`f64::cos`](../../std/primitive.f64.html#method.cos)
1104#[rustc_intrinsic]
1105#[rustc_nounwind]
1106pub unsafe fn cosf64(x: f64) -> f64;
1107/// Returns the cosine of an `f128`.
1108///
1109/// The stabilized version of this intrinsic is
1110/// [`f128::cos`](../../std/primitive.f128.html#method.cos)
1111#[rustc_intrinsic]
1112#[rustc_nounwind]
1113pub unsafe fn cosf128(x: f128) -> f128;
1114
1115/// Raises an `f16` to an `f16` power.
1116///
1117/// The stabilized version of this intrinsic is
1118/// [`f16::powf`](../../std/primitive.f16.html#method.powf)
1119#[rustc_intrinsic]
1120#[rustc_nounwind]
1121pub unsafe fn powf16(a: f16, x: f16) -> f16;
1122/// Raises an `f32` to an `f32` power.
1123///
1124/// The stabilized version of this intrinsic is
1125/// [`f32::powf`](../../std/primitive.f32.html#method.powf)
1126#[rustc_intrinsic]
1127#[rustc_nounwind]
1128pub unsafe fn powf32(a: f32, x: f32) -> f32;
1129/// Raises an `f64` to an `f64` power.
1130///
1131/// The stabilized version of this intrinsic is
1132/// [`f64::powf`](../../std/primitive.f64.html#method.powf)
1133#[rustc_intrinsic]
1134#[rustc_nounwind]
1135pub unsafe fn powf64(a: f64, x: f64) -> f64;
1136/// Raises an `f128` to an `f128` power.
1137///
1138/// The stabilized version of this intrinsic is
1139/// [`f128::powf`](../../std/primitive.f128.html#method.powf)
1140#[rustc_intrinsic]
1141#[rustc_nounwind]
1142pub unsafe fn powf128(a: f128, x: f128) -> f128;
1143
1144/// Returns the exponential of an `f16`.
1145///
1146/// The stabilized version of this intrinsic is
1147/// [`f16::exp`](../../std/primitive.f16.html#method.exp)
1148#[rustc_intrinsic]
1149#[rustc_nounwind]
1150pub unsafe fn expf16(x: f16) -> f16;
1151/// Returns the exponential of an `f32`.
1152///
1153/// The stabilized version of this intrinsic is
1154/// [`f32::exp`](../../std/primitive.f32.html#method.exp)
1155#[rustc_intrinsic]
1156#[rustc_nounwind]
1157pub unsafe fn expf32(x: f32) -> f32;
1158/// Returns the exponential of an `f64`.
1159///
1160/// The stabilized version of this intrinsic is
1161/// [`f64::exp`](../../std/primitive.f64.html#method.exp)
1162#[rustc_intrinsic]
1163#[rustc_nounwind]
1164pub unsafe fn expf64(x: f64) -> f64;
1165/// Returns the exponential of an `f128`.
1166///
1167/// The stabilized version of this intrinsic is
1168/// [`f128::exp`](../../std/primitive.f128.html#method.exp)
1169#[rustc_intrinsic]
1170#[rustc_nounwind]
1171pub unsafe fn expf128(x: f128) -> f128;
1172
1173/// Returns 2 raised to the power of an `f16`.
1174///
1175/// The stabilized version of this intrinsic is
1176/// [`f16::exp2`](../../std/primitive.f16.html#method.exp2)
1177#[rustc_intrinsic]
1178#[rustc_nounwind]
1179pub unsafe fn exp2f16(x: f16) -> f16;
1180/// Returns 2 raised to the power of an `f32`.
1181///
1182/// The stabilized version of this intrinsic is
1183/// [`f32::exp2`](../../std/primitive.f32.html#method.exp2)
1184#[rustc_intrinsic]
1185#[rustc_nounwind]
1186pub unsafe fn exp2f32(x: f32) -> f32;
1187/// Returns 2 raised to the power of an `f64`.
1188///
1189/// The stabilized version of this intrinsic is
1190/// [`f64::exp2`](../../std/primitive.f64.html#method.exp2)
1191#[rustc_intrinsic]
1192#[rustc_nounwind]
1193pub unsafe fn exp2f64(x: f64) -> f64;
1194/// Returns 2 raised to the power of an `f128`.
1195///
1196/// The stabilized version of this intrinsic is
1197/// [`f128::exp2`](../../std/primitive.f128.html#method.exp2)
1198#[rustc_intrinsic]
1199#[rustc_nounwind]
1200pub unsafe fn exp2f128(x: f128) -> f128;
1201
1202/// Returns the natural logarithm of an `f16`.
1203///
1204/// The stabilized version of this intrinsic is
1205/// [`f16::ln`](../../std/primitive.f16.html#method.ln)
1206#[rustc_intrinsic]
1207#[rustc_nounwind]
1208pub unsafe fn logf16(x: f16) -> f16;
1209/// Returns the natural logarithm of an `f32`.
1210///
1211/// The stabilized version of this intrinsic is
1212/// [`f32::ln`](../../std/primitive.f32.html#method.ln)
1213#[rustc_intrinsic]
1214#[rustc_nounwind]
1215pub unsafe fn logf32(x: f32) -> f32;
1216/// Returns the natural logarithm of an `f64`.
1217///
1218/// The stabilized version of this intrinsic is
1219/// [`f64::ln`](../../std/primitive.f64.html#method.ln)
1220#[rustc_intrinsic]
1221#[rustc_nounwind]
1222pub unsafe fn logf64(x: f64) -> f64;
1223/// Returns the natural logarithm of an `f128`.
1224///
1225/// The stabilized version of this intrinsic is
1226/// [`f128::ln`](../../std/primitive.f128.html#method.ln)
1227#[rustc_intrinsic]
1228#[rustc_nounwind]
1229pub unsafe fn logf128(x: f128) -> f128;
1230
1231/// Returns the base 10 logarithm of an `f16`.
1232///
1233/// The stabilized version of this intrinsic is
1234/// [`f16::log10`](../../std/primitive.f16.html#method.log10)
1235#[rustc_intrinsic]
1236#[rustc_nounwind]
1237pub unsafe fn log10f16(x: f16) -> f16;
1238/// Returns the base 10 logarithm of an `f32`.
1239///
1240/// The stabilized version of this intrinsic is
1241/// [`f32::log10`](../../std/primitive.f32.html#method.log10)
1242#[rustc_intrinsic]
1243#[rustc_nounwind]
1244pub unsafe fn log10f32(x: f32) -> f32;
1245/// Returns the base 10 logarithm of an `f64`.
1246///
1247/// The stabilized version of this intrinsic is
1248/// [`f64::log10`](../../std/primitive.f64.html#method.log10)
1249#[rustc_intrinsic]
1250#[rustc_nounwind]
1251pub unsafe fn log10f64(x: f64) -> f64;
1252/// Returns the base 10 logarithm of an `f128`.
1253///
1254/// The stabilized version of this intrinsic is
1255/// [`f128::log10`](../../std/primitive.f128.html#method.log10)
1256#[rustc_intrinsic]
1257#[rustc_nounwind]
1258pub unsafe fn log10f128(x: f128) -> f128;
1259
1260/// Returns the base 2 logarithm of an `f16`.
1261///
1262/// The stabilized version of this intrinsic is
1263/// [`f16::log2`](../../std/primitive.f16.html#method.log2)
1264#[rustc_intrinsic]
1265#[rustc_nounwind]
1266pub unsafe fn log2f16(x: f16) -> f16;
1267/// Returns the base 2 logarithm of an `f32`.
1268///
1269/// The stabilized version of this intrinsic is
1270/// [`f32::log2`](../../std/primitive.f32.html#method.log2)
1271#[rustc_intrinsic]
1272#[rustc_nounwind]
1273pub unsafe fn log2f32(x: f32) -> f32;
1274/// Returns the base 2 logarithm of an `f64`.
1275///
1276/// The stabilized version of this intrinsic is
1277/// [`f64::log2`](../../std/primitive.f64.html#method.log2)
1278#[rustc_intrinsic]
1279#[rustc_nounwind]
1280pub unsafe fn log2f64(x: f64) -> f64;
1281/// Returns the base 2 logarithm of an `f128`.
1282///
1283/// The stabilized version of this intrinsic is
1284/// [`f128::log2`](../../std/primitive.f128.html#method.log2)
1285#[rustc_intrinsic]
1286#[rustc_nounwind]
1287pub unsafe fn log2f128(x: f128) -> f128;
1288
1289/// Returns `a * b + c` for `f16` values.
1290///
1291/// The stabilized version of this intrinsic is
1292/// [`f16::mul_add`](../../std/primitive.f16.html#method.mul_add)
1293#[rustc_intrinsic]
1294#[rustc_nounwind]
1295pub unsafe fn fmaf16(a: f16, b: f16, c: f16) -> f16;
1296/// Returns `a * b + c` for `f32` values.
1297///
1298/// The stabilized version of this intrinsic is
1299/// [`f32::mul_add`](../../std/primitive.f32.html#method.mul_add)
1300#[rustc_intrinsic]
1301#[rustc_nounwind]
1302pub unsafe fn fmaf32(a: f32, b: f32, c: f32) -> f32;
1303/// Returns `a * b + c` for `f64` values.
1304///
1305/// The stabilized version of this intrinsic is
1306/// [`f64::mul_add`](../../std/primitive.f64.html#method.mul_add)
1307#[rustc_intrinsic]
1308#[rustc_nounwind]
1309pub unsafe fn fmaf64(a: f64, b: f64, c: f64) -> f64;
1310/// Returns `a * b + c` for `f128` values.
1311///
1312/// The stabilized version of this intrinsic is
1313/// [`f128::mul_add`](../../std/primitive.f128.html#method.mul_add)
1314#[rustc_intrinsic]
1315#[rustc_nounwind]
1316pub unsafe fn fmaf128(a: f128, b: f128, c: f128) -> f128;
1317
1318/// Returns `a * b + c` for `f16` values, non-deterministically executing
1319/// either a fused multiply-add or two operations with rounding of the
1320/// intermediate result.
1321///
1322/// The operation is fused if the code generator determines that target
1323/// instruction set has support for a fused operation, and that the fused
1324/// operation is more efficient than the equivalent, separate pair of mul
1325/// and add instructions. It is unspecified whether or not a fused operation
1326/// is selected, and that may depend on optimization level and context, for
1327/// example.
1328#[rustc_intrinsic]
1329#[rustc_nounwind]
1330pub unsafe fn fmuladdf16(a: f16, b: f16, c: f16) -> f16;
1331/// Returns `a * b + c` for `f32` values, non-deterministically executing
1332/// either a fused multiply-add or two operations with rounding of the
1333/// intermediate result.
1334///
1335/// The operation is fused if the code generator determines that target
1336/// instruction set has support for a fused operation, and that the fused
1337/// operation is more efficient than the equivalent, separate pair of mul
1338/// and add instructions. It is unspecified whether or not a fused operation
1339/// is selected, and that may depend on optimization level and context, for
1340/// example.
1341#[rustc_intrinsic]
1342#[rustc_nounwind]
1343pub unsafe fn fmuladdf32(a: f32, b: f32, c: f32) -> f32;
1344/// Returns `a * b + c` for `f64` values, non-deterministically executing
1345/// either a fused multiply-add or two operations with rounding of the
1346/// intermediate result.
1347///
1348/// The operation is fused if the code generator determines that target
1349/// instruction set has support for a fused operation, and that the fused
1350/// operation is more efficient than the equivalent, separate pair of mul
1351/// and add instructions. It is unspecified whether or not a fused operation
1352/// is selected, and that may depend on optimization level and context, for
1353/// example.
1354#[rustc_intrinsic]
1355#[rustc_nounwind]
1356pub unsafe fn fmuladdf64(a: f64, b: f64, c: f64) -> f64;
1357/// Returns `a * b + c` for `f128` values, non-deterministically executing
1358/// either a fused multiply-add or two operations with rounding of the
1359/// intermediate result.
1360///
1361/// The operation is fused if the code generator determines that target
1362/// instruction set has support for a fused operation, and that the fused
1363/// operation is more efficient than the equivalent, separate pair of mul
1364/// and add instructions. It is unspecified whether or not a fused operation
1365/// is selected, and that may depend on optimization level and context, for
1366/// example.
1367#[rustc_intrinsic]
1368#[rustc_nounwind]
1369pub unsafe fn fmuladdf128(a: f128, b: f128, c: f128) -> f128;
1370
1371/// Returns the largest integer less than or equal to an `f16`.
1372///
1373/// The stabilized version of this intrinsic is
1374/// [`f16::floor`](../../std/primitive.f16.html#method.floor)
1375#[rustc_intrinsic]
1376#[rustc_nounwind]
1377pub const unsafe fn floorf16(x: f16) -> f16;
1378/// Returns the largest integer less than or equal to an `f32`.
1379///
1380/// The stabilized version of this intrinsic is
1381/// [`f32::floor`](../../std/primitive.f32.html#method.floor)
1382#[rustc_intrinsic]
1383#[rustc_nounwind]
1384pub const unsafe fn floorf32(x: f32) -> f32;
1385/// Returns the largest integer less than or equal to an `f64`.
1386///
1387/// The stabilized version of this intrinsic is
1388/// [`f64::floor`](../../std/primitive.f64.html#method.floor)
1389#[rustc_intrinsic]
1390#[rustc_nounwind]
1391pub const unsafe fn floorf64(x: f64) -> f64;
1392/// Returns the largest integer less than or equal to an `f128`.
1393///
1394/// The stabilized version of this intrinsic is
1395/// [`f128::floor`](../../std/primitive.f128.html#method.floor)
1396#[rustc_intrinsic]
1397#[rustc_nounwind]
1398pub const unsafe fn floorf128(x: f128) -> f128;
1399
1400/// Returns the smallest integer greater than or equal to an `f16`.
1401///
1402/// The stabilized version of this intrinsic is
1403/// [`f16::ceil`](../../std/primitive.f16.html#method.ceil)
1404#[rustc_intrinsic]
1405#[rustc_nounwind]
1406pub const unsafe fn ceilf16(x: f16) -> f16;
1407/// Returns the smallest integer greater than or equal to an `f32`.
1408///
1409/// The stabilized version of this intrinsic is
1410/// [`f32::ceil`](../../std/primitive.f32.html#method.ceil)
1411#[rustc_intrinsic]
1412#[rustc_nounwind]
1413pub const unsafe fn ceilf32(x: f32) -> f32;
1414/// Returns the smallest integer greater than or equal to an `f64`.
1415///
1416/// The stabilized version of this intrinsic is
1417/// [`f64::ceil`](../../std/primitive.f64.html#method.ceil)
1418#[rustc_intrinsic]
1419#[rustc_nounwind]
1420pub const unsafe fn ceilf64(x: f64) -> f64;
1421/// Returns the smallest integer greater than or equal to an `f128`.
1422///
1423/// The stabilized version of this intrinsic is
1424/// [`f128::ceil`](../../std/primitive.f128.html#method.ceil)
1425#[rustc_intrinsic]
1426#[rustc_nounwind]
1427pub const unsafe fn ceilf128(x: f128) -> f128;
1428
1429/// Returns the integer part of an `f16`.
1430///
1431/// The stabilized version of this intrinsic is
1432/// [`f16::trunc`](../../std/primitive.f16.html#method.trunc)
1433#[rustc_intrinsic]
1434#[rustc_nounwind]
1435pub const unsafe fn truncf16(x: f16) -> f16;
1436/// Returns the integer part of an `f32`.
1437///
1438/// The stabilized version of this intrinsic is
1439/// [`f32::trunc`](../../std/primitive.f32.html#method.trunc)
1440#[rustc_intrinsic]
1441#[rustc_nounwind]
1442pub const unsafe fn truncf32(x: f32) -> f32;
1443/// Returns the integer part of an `f64`.
1444///
1445/// The stabilized version of this intrinsic is
1446/// [`f64::trunc`](../../std/primitive.f64.html#method.trunc)
1447#[rustc_intrinsic]
1448#[rustc_nounwind]
1449pub const unsafe fn truncf64(x: f64) -> f64;
1450/// Returns the integer part of an `f128`.
1451///
1452/// The stabilized version of this intrinsic is
1453/// [`f128::trunc`](../../std/primitive.f128.html#method.trunc)
1454#[rustc_intrinsic]
1455#[rustc_nounwind]
1456pub const unsafe fn truncf128(x: f128) -> f128;
1457
1458/// Returns the nearest integer to an `f16`. Rounds half-way cases to the number with an even
1459/// least significant digit.
1460///
1461/// The stabilized version of this intrinsic is
1462/// [`f16::round_ties_even`](../../std/primitive.f16.html#method.round_ties_even)
1463#[rustc_intrinsic]
1464#[rustc_nounwind]
1465pub const fn round_ties_even_f16(x: f16) -> f16;
1466
1467/// Returns the nearest integer to an `f32`. Rounds half-way cases to the number with an even
1468/// least significant digit.
1469///
1470/// The stabilized version of this intrinsic is
1471/// [`f32::round_ties_even`](../../std/primitive.f32.html#method.round_ties_even)
1472#[rustc_intrinsic]
1473#[rustc_nounwind]
1474pub const fn round_ties_even_f32(x: f32) -> f32;
1475
1476/// Returns the nearest integer to an `f64`. Rounds half-way cases to the number with an even
1477/// least significant digit.
1478///
1479/// The stabilized version of this intrinsic is
1480/// [`f64::round_ties_even`](../../std/primitive.f64.html#method.round_ties_even)
1481#[rustc_intrinsic]
1482#[rustc_nounwind]
1483pub const fn round_ties_even_f64(x: f64) -> f64;
1484
1485/// Returns the nearest integer to an `f128`. Rounds half-way cases to the number with an even
1486/// least significant digit.
1487///
1488/// The stabilized version of this intrinsic is
1489/// [`f128::round_ties_even`](../../std/primitive.f128.html#method.round_ties_even)
1490#[rustc_intrinsic]
1491#[rustc_nounwind]
1492pub const fn round_ties_even_f128(x: f128) -> f128;
1493
1494/// Returns the nearest integer to an `f16`. Rounds half-way cases away from zero.
1495///
1496/// The stabilized version of this intrinsic is
1497/// [`f16::round`](../../std/primitive.f16.html#method.round)
1498#[rustc_intrinsic]
1499#[rustc_nounwind]
1500pub const unsafe fn roundf16(x: f16) -> f16;
1501/// Returns the nearest integer to an `f32`. Rounds half-way cases away from zero.
1502///
1503/// The stabilized version of this intrinsic is
1504/// [`f32::round`](../../std/primitive.f32.html#method.round)
1505#[rustc_intrinsic]
1506#[rustc_nounwind]
1507pub const unsafe fn roundf32(x: f32) -> f32;
1508/// Returns the nearest integer to an `f64`. Rounds half-way cases away from zero.
1509///
1510/// The stabilized version of this intrinsic is
1511/// [`f64::round`](../../std/primitive.f64.html#method.round)
1512#[rustc_intrinsic]
1513#[rustc_nounwind]
1514pub const unsafe fn roundf64(x: f64) -> f64;
1515/// Returns the nearest integer to an `f128`. Rounds half-way cases away from zero.
1516///
1517/// The stabilized version of this intrinsic is
1518/// [`f128::round`](../../std/primitive.f128.html#method.round)
1519#[rustc_intrinsic]
1520#[rustc_nounwind]
1521pub const unsafe fn roundf128(x: f128) -> f128;
1522
1523/// Float addition that allows optimizations based on algebraic rules.
1524/// May assume inputs are finite.
1525///
1526/// This intrinsic does not have a stable counterpart.
1527#[rustc_intrinsic]
1528#[rustc_nounwind]
1529pub unsafe fn fadd_fast<T: Copy>(a: T, b: T) -> T;
1530
1531/// Float subtraction that allows optimizations based on algebraic rules.
1532/// May assume inputs are finite.
1533///
1534/// This intrinsic does not have a stable counterpart.
1535#[rustc_intrinsic]
1536#[rustc_nounwind]
1537pub unsafe fn fsub_fast<T: Copy>(a: T, b: T) -> T;
1538
1539/// Float multiplication that allows optimizations based on algebraic rules.
1540/// May assume inputs are finite.
1541///
1542/// This intrinsic does not have a stable counterpart.
1543#[rustc_intrinsic]
1544#[rustc_nounwind]
1545pub unsafe fn fmul_fast<T: Copy>(a: T, b: T) -> T;
1546
1547/// Float division that allows optimizations based on algebraic rules.
1548/// May assume inputs are finite.
1549///
1550/// This intrinsic does not have a stable counterpart.
1551#[rustc_intrinsic]
1552#[rustc_nounwind]
1553pub unsafe fn fdiv_fast<T: Copy>(a: T, b: T) -> T;
1554
1555/// Float remainder that allows optimizations based on algebraic rules.
1556/// May assume inputs are finite.
1557///
1558/// This intrinsic does not have a stable counterpart.
1559#[rustc_intrinsic]
1560#[rustc_nounwind]
1561pub unsafe fn frem_fast<T: Copy>(a: T, b: T) -> T;
1562
1563/// Converts with LLVM’s fptoui/fptosi, which may return undef for values out of range
1564/// (<https://github.com/rust-lang/rust/issues/10184>)
1565///
1566/// Stabilized as [`f32::to_int_unchecked`] and [`f64::to_int_unchecked`].
1567#[rustc_intrinsic]
1568#[rustc_nounwind]
1569pub unsafe fn float_to_int_unchecked<Float: Copy, Int: Copy>(value: Float) -> Int;
1570
1571/// Float addition that allows optimizations based on algebraic rules.
1572///
1573/// Stabilized as [`f16::algebraic_add`], [`f32::algebraic_add`], [`f64::algebraic_add`] and [`f128::algebraic_add`].
1574#[rustc_nounwind]
1575#[rustc_intrinsic]
1576pub const fn fadd_algebraic<T: Copy>(a: T, b: T) -> T;
1577
1578/// Float subtraction that allows optimizations based on algebraic rules.
1579///
1580/// Stabilized as [`f16::algebraic_sub`], [`f32::algebraic_sub`], [`f64::algebraic_sub`] and [`f128::algebraic_sub`].
1581#[rustc_nounwind]
1582#[rustc_intrinsic]
1583pub const fn fsub_algebraic<T: Copy>(a: T, b: T) -> T;
1584
1585/// Float multiplication that allows optimizations based on algebraic rules.
1586///
1587/// Stabilized as [`f16::algebraic_mul`], [`f32::algebraic_mul`], [`f64::algebraic_mul`] and [`f128::algebraic_mul`].
1588#[rustc_nounwind]
1589#[rustc_intrinsic]
1590pub const fn fmul_algebraic<T: Copy>(a: T, b: T) -> T;
1591
1592/// Float division that allows optimizations based on algebraic rules.
1593///
1594/// Stabilized as [`f16::algebraic_div`], [`f32::algebraic_div`], [`f64::algebraic_div`] and [`f128::algebraic_div`].
1595#[rustc_nounwind]
1596#[rustc_intrinsic]
1597pub const fn fdiv_algebraic<T: Copy>(a: T, b: T) -> T;
1598
1599/// Float remainder that allows optimizations based on algebraic rules.
1600///
1601/// Stabilized as [`f16::algebraic_rem`], [`f32::algebraic_rem`], [`f64::algebraic_rem`] and [`f128::algebraic_rem`].
1602#[rustc_nounwind]
1603#[rustc_intrinsic]
1604pub const fn frem_algebraic<T: Copy>(a: T, b: T) -> T;
1605
1606/// Returns the number of bits set in an integer type `T`
1607///
1608/// Note that, unlike most intrinsics, this is safe to call;
1609/// it does not require an `unsafe` block.
1610/// Therefore, implementations must not require the user to uphold
1611/// any safety invariants.
1612///
1613/// The stabilized versions of this intrinsic are available on the integer
1614/// primitives via the `count_ones` method. For example,
1615/// [`u32::count_ones`]
1616#[rustc_intrinsic_const_stable_indirect]
1617#[rustc_nounwind]
1618#[rustc_intrinsic]
1619pub const fn ctpop<T: Copy>(x: T) -> u32;
1620
1621/// Returns the number of leading unset bits (zeroes) in an integer type `T`.
1622///
1623/// Note that, unlike most intrinsics, this is safe to call;
1624/// it does not require an `unsafe` block.
1625/// Therefore, implementations must not require the user to uphold
1626/// any safety invariants.
1627///
1628/// The stabilized versions of this intrinsic are available on the integer
1629/// primitives via the `leading_zeros` method. For example,
1630/// [`u32::leading_zeros`]
1631///
1632/// # Examples
1633///
1634/// ```
1635/// #![feature(core_intrinsics)]
1636/// # #![allow(internal_features)]
1637///
1638/// use std::intrinsics::ctlz;
1639///
1640/// let x = 0b0001_1100_u8;
1641/// let num_leading = ctlz(x);
1642/// assert_eq!(num_leading, 3);
1643/// ```
1644///
1645/// An `x` with value `0` will return the bit width of `T`.
1646///
1647/// ```
1648/// #![feature(core_intrinsics)]
1649/// # #![allow(internal_features)]
1650///
1651/// use std::intrinsics::ctlz;
1652///
1653/// let x = 0u16;
1654/// let num_leading = ctlz(x);
1655/// assert_eq!(num_leading, 16);
1656/// ```
1657#[rustc_intrinsic_const_stable_indirect]
1658#[rustc_nounwind]
1659#[rustc_intrinsic]
1660pub const fn ctlz<T: Copy>(x: T) -> u32;
1661
1662/// Like `ctlz`, but extra-unsafe as it returns `undef` when
1663/// given an `x` with value `0`.
1664///
1665/// This intrinsic does not have a stable counterpart.
1666///
1667/// # Examples
1668///
1669/// ```
1670/// #![feature(core_intrinsics)]
1671/// # #![allow(internal_features)]
1672///
1673/// use std::intrinsics::ctlz_nonzero;
1674///
1675/// let x = 0b0001_1100_u8;
1676/// let num_leading = unsafe { ctlz_nonzero(x) };
1677/// assert_eq!(num_leading, 3);
1678/// ```
1679#[rustc_intrinsic_const_stable_indirect]
1680#[rustc_nounwind]
1681#[rustc_intrinsic]
1682pub const unsafe fn ctlz_nonzero<T: Copy>(x: T) -> u32;
1683
1684/// Returns the number of trailing unset bits (zeroes) in an integer type `T`.
1685///
1686/// Note that, unlike most intrinsics, this is safe to call;
1687/// it does not require an `unsafe` block.
1688/// Therefore, implementations must not require the user to uphold
1689/// any safety invariants.
1690///
1691/// The stabilized versions of this intrinsic are available on the integer
1692/// primitives via the `trailing_zeros` method. For example,
1693/// [`u32::trailing_zeros`]
1694///
1695/// # Examples
1696///
1697/// ```
1698/// #![feature(core_intrinsics)]
1699/// # #![allow(internal_features)]
1700///
1701/// use std::intrinsics::cttz;
1702///
1703/// let x = 0b0011_1000_u8;
1704/// let num_trailing = cttz(x);
1705/// assert_eq!(num_trailing, 3);
1706/// ```
1707///
1708/// An `x` with value `0` will return the bit width of `T`:
1709///
1710/// ```
1711/// #![feature(core_intrinsics)]
1712/// # #![allow(internal_features)]
1713///
1714/// use std::intrinsics::cttz;
1715///
1716/// let x = 0u16;
1717/// let num_trailing = cttz(x);
1718/// assert_eq!(num_trailing, 16);
1719/// ```
1720#[rustc_intrinsic_const_stable_indirect]
1721#[rustc_nounwind]
1722#[rustc_intrinsic]
1723pub const fn cttz<T: Copy>(x: T) -> u32;
1724
1725/// Like `cttz`, but extra-unsafe as it returns `undef` when
1726/// given an `x` with value `0`.
1727///
1728/// This intrinsic does not have a stable counterpart.
1729///
1730/// # Examples
1731///
1732/// ```
1733/// #![feature(core_intrinsics)]
1734/// # #![allow(internal_features)]
1735///
1736/// use std::intrinsics::cttz_nonzero;
1737///
1738/// let x = 0b0011_1000_u8;
1739/// let num_trailing = unsafe { cttz_nonzero(x) };
1740/// assert_eq!(num_trailing, 3);
1741/// ```
1742#[rustc_intrinsic_const_stable_indirect]
1743#[rustc_nounwind]
1744#[rustc_intrinsic]
1745pub const unsafe fn cttz_nonzero<T: Copy>(x: T) -> u32;
1746
1747/// Reverses the bytes in an integer type `T`.
1748///
1749/// Note that, unlike most intrinsics, this is safe to call;
1750/// it does not require an `unsafe` block.
1751/// Therefore, implementations must not require the user to uphold
1752/// any safety invariants.
1753///
1754/// The stabilized versions of this intrinsic are available on the integer
1755/// primitives via the `swap_bytes` method. For example,
1756/// [`u32::swap_bytes`]
1757#[rustc_intrinsic_const_stable_indirect]
1758#[rustc_nounwind]
1759#[rustc_intrinsic]
1760pub const fn bswap<T: Copy>(x: T) -> T;
1761
1762/// Reverses the bits in an integer type `T`.
1763///
1764/// Note that, unlike most intrinsics, this is safe to call;
1765/// it does not require an `unsafe` block.
1766/// Therefore, implementations must not require the user to uphold
1767/// any safety invariants.
1768///
1769/// The stabilized versions of this intrinsic are available on the integer
1770/// primitives via the `reverse_bits` method. For example,
1771/// [`u32::reverse_bits`]
1772#[rustc_intrinsic_const_stable_indirect]
1773#[rustc_nounwind]
1774#[rustc_intrinsic]
1775pub const fn bitreverse<T: Copy>(x: T) -> T;
1776
1777/// Does a three-way comparison between the two arguments,
1778/// which must be of character or integer (signed or unsigned) type.
1779///
1780/// This was originally added because it greatly simplified the MIR in `cmp`
1781/// implementations, and then LLVM 20 added a backend intrinsic for it too.
1782///
1783/// The stabilized version of this intrinsic is [`Ord::cmp`].
1784#[rustc_intrinsic_const_stable_indirect]
1785#[rustc_nounwind]
1786#[rustc_intrinsic]
1787pub const fn three_way_compare<T: Copy>(lhs: T, rhss: T) -> crate::cmp::Ordering;
1788
1789/// Combine two values which have no bits in common.
1790///
1791/// This allows the backend to implement it as `a + b` *or* `a | b`,
1792/// depending which is easier to implement on a specific target.
1793///
1794/// # Safety
1795///
1796/// Requires that `(a & b) == 0`, or equivalently that `(a | b) == (a + b)`.
1797///
1798/// Otherwise it's immediate UB.
1799#[rustc_const_unstable(feature = "disjoint_bitor", issue = "135758")]
1800#[rustc_nounwind]
1801#[rustc_intrinsic]
1802#[track_caller]
1803#[miri::intrinsic_fallback_is_spec] // the fallbacks all `assume` to tell Miri
1804pub const unsafe fn disjoint_bitor<T: ~const fallback::DisjointBitOr>(a: T, b: T) -> T {
1805 // SAFETY: same preconditions as this function.
1806 unsafe { fallback::DisjointBitOr::disjoint_bitor(self:a, other:b) }
1807}
1808
1809/// Performs checked integer addition.
1810///
1811/// Note that, unlike most intrinsics, this is safe to call;
1812/// it does not require an `unsafe` block.
1813/// Therefore, implementations must not require the user to uphold
1814/// any safety invariants.
1815///
1816/// The stabilized versions of this intrinsic are available on the integer
1817/// primitives via the `overflowing_add` method. For example,
1818/// [`u32::overflowing_add`]
1819#[rustc_intrinsic_const_stable_indirect]
1820#[rustc_nounwind]
1821#[rustc_intrinsic]
1822pub const fn add_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
1823
1824/// Performs checked integer subtraction
1825///
1826/// Note that, unlike most intrinsics, this is safe to call;
1827/// it does not require an `unsafe` block.
1828/// Therefore, implementations must not require the user to uphold
1829/// any safety invariants.
1830///
1831/// The stabilized versions of this intrinsic are available on the integer
1832/// primitives via the `overflowing_sub` method. For example,
1833/// [`u32::overflowing_sub`]
1834#[rustc_intrinsic_const_stable_indirect]
1835#[rustc_nounwind]
1836#[rustc_intrinsic]
1837pub const fn sub_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
1838
1839/// Performs checked integer multiplication
1840///
1841/// Note that, unlike most intrinsics, this is safe to call;
1842/// it does not require an `unsafe` block.
1843/// Therefore, implementations must not require the user to uphold
1844/// any safety invariants.
1845///
1846/// The stabilized versions of this intrinsic are available on the integer
1847/// primitives via the `overflowing_mul` method. For example,
1848/// [`u32::overflowing_mul`]
1849#[rustc_intrinsic_const_stable_indirect]
1850#[rustc_nounwind]
1851#[rustc_intrinsic]
1852pub const fn mul_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
1853
1854/// Performs full-width multiplication and addition with a carry:
1855/// `multiplier * multiplicand + addend + carry`.
1856///
1857/// This is possible without any overflow. For `uN`:
1858/// MAX * MAX + MAX + MAX
1859/// => (2ⁿ-1) × (2ⁿ-1) + (2ⁿ-1) + (2ⁿ-1)
1860/// => (2²ⁿ - 2ⁿ⁺¹ + 1) + (2ⁿ⁺¹ - 2)
1861/// => 2²ⁿ - 1
1862///
1863/// For `iN`, the upper bound is MIN * MIN + MAX + MAX => 2²ⁿ⁻² + 2ⁿ - 2,
1864/// and the lower bound is MAX * MIN + MIN + MIN => -2²ⁿ⁻² - 2ⁿ + 2ⁿ⁺¹.
1865///
1866/// This currently supports unsigned integers *only*, no signed ones.
1867/// The stabilized versions of this intrinsic are available on integers.
1868#[unstable(feature = "core_intrinsics", issue = "none")]
1869#[rustc_const_unstable(feature = "const_carrying_mul_add", issue = "85532")]
1870#[rustc_nounwind]
1871#[rustc_intrinsic]
1872#[miri::intrinsic_fallback_is_spec]
1873pub const fn carrying_mul_add<T: ~const fallback::CarryingMulAdd<Unsigned = U>, U>(
1874 multiplier: T,
1875 multiplicand: T,
1876 addend: T,
1877 carry: T,
1878) -> (U, T) {
1879 multiplier.carrying_mul_add(multiplicand, addend, carry)
1880}
1881
1882/// Performs an exact division, resulting in undefined behavior where
1883/// `x % y != 0` or `y == 0` or `x == T::MIN && y == -1`
1884///
1885/// This intrinsic does not have a stable counterpart.
1886#[rustc_intrinsic_const_stable_indirect]
1887#[rustc_nounwind]
1888#[rustc_intrinsic]
1889pub const unsafe fn exact_div<T: Copy>(x: T, y: T) -> T;
1890
1891/// Performs an unchecked division, resulting in undefined behavior
1892/// where `y == 0` or `x == T::MIN && y == -1`
1893///
1894/// Safe wrappers for this intrinsic are available on the integer
1895/// primitives via the `checked_div` method. For example,
1896/// [`u32::checked_div`]
1897#[rustc_intrinsic_const_stable_indirect]
1898#[rustc_nounwind]
1899#[rustc_intrinsic]
1900pub const unsafe fn unchecked_div<T: Copy>(x: T, y: T) -> T;
1901/// Returns the remainder of an unchecked division, resulting in
1902/// undefined behavior when `y == 0` or `x == T::MIN && y == -1`
1903///
1904/// Safe wrappers for this intrinsic are available on the integer
1905/// primitives via the `checked_rem` method. For example,
1906/// [`u32::checked_rem`]
1907#[rustc_intrinsic_const_stable_indirect]
1908#[rustc_nounwind]
1909#[rustc_intrinsic]
1910pub const unsafe fn unchecked_rem<T: Copy>(x: T, y: T) -> T;
1911
1912/// Performs an unchecked left shift, resulting in undefined behavior when
1913/// `y < 0` or `y >= N`, where N is the width of T in bits.
1914///
1915/// Safe wrappers for this intrinsic are available on the integer
1916/// primitives via the `checked_shl` method. For example,
1917/// [`u32::checked_shl`]
1918#[rustc_intrinsic_const_stable_indirect]
1919#[rustc_nounwind]
1920#[rustc_intrinsic]
1921pub const unsafe fn unchecked_shl<T: Copy, U: Copy>(x: T, y: U) -> T;
1922/// Performs an unchecked right shift, resulting in undefined behavior when
1923/// `y < 0` or `y >= N`, where N is the width of T in bits.
1924///
1925/// Safe wrappers for this intrinsic are available on the integer
1926/// primitives via the `checked_shr` method. For example,
1927/// [`u32::checked_shr`]
1928#[rustc_intrinsic_const_stable_indirect]
1929#[rustc_nounwind]
1930#[rustc_intrinsic]
1931pub const unsafe fn unchecked_shr<T: Copy, U: Copy>(x: T, y: U) -> T;
1932
1933/// Returns the result of an unchecked addition, resulting in
1934/// undefined behavior when `x + y > T::MAX` or `x + y < T::MIN`.
1935///
1936/// The stable counterpart of this intrinsic is `unchecked_add` on the various
1937/// integer types, such as [`u16::unchecked_add`] and [`i64::unchecked_add`].
1938#[rustc_intrinsic_const_stable_indirect]
1939#[rustc_nounwind]
1940#[rustc_intrinsic]
1941pub const unsafe fn unchecked_add<T: Copy>(x: T, y: T) -> T;
1942
1943/// Returns the result of an unchecked subtraction, resulting in
1944/// undefined behavior when `x - y > T::MAX` or `x - y < T::MIN`.
1945///
1946/// The stable counterpart of this intrinsic is `unchecked_sub` on the various
1947/// integer types, such as [`u16::unchecked_sub`] and [`i64::unchecked_sub`].
1948#[rustc_intrinsic_const_stable_indirect]
1949#[rustc_nounwind]
1950#[rustc_intrinsic]
1951pub const unsafe fn unchecked_sub<T: Copy>(x: T, y: T) -> T;
1952
1953/// Returns the result of an unchecked multiplication, resulting in
1954/// undefined behavior when `x * y > T::MAX` or `x * y < T::MIN`.
1955///
1956/// The stable counterpart of this intrinsic is `unchecked_mul` on the various
1957/// integer types, such as [`u16::unchecked_mul`] and [`i64::unchecked_mul`].
1958#[rustc_intrinsic_const_stable_indirect]
1959#[rustc_nounwind]
1960#[rustc_intrinsic]
1961pub const unsafe fn unchecked_mul<T: Copy>(x: T, y: T) -> T;
1962
1963/// Performs rotate left.
1964///
1965/// Note that, unlike most intrinsics, this is safe to call;
1966/// it does not require an `unsafe` block.
1967/// Therefore, implementations must not require the user to uphold
1968/// any safety invariants.
1969///
1970/// The stabilized versions of this intrinsic are available on the integer
1971/// primitives via the `rotate_left` method. For example,
1972/// [`u32::rotate_left`]
1973#[rustc_intrinsic_const_stable_indirect]
1974#[rustc_nounwind]
1975#[rustc_intrinsic]
1976pub const fn rotate_left<T: Copy>(x: T, shift: u32) -> T;
1977
1978/// Performs rotate right.
1979///
1980/// Note that, unlike most intrinsics, this is safe to call;
1981/// it does not require an `unsafe` block.
1982/// Therefore, implementations must not require the user to uphold
1983/// any safety invariants.
1984///
1985/// The stabilized versions of this intrinsic are available on the integer
1986/// primitives via the `rotate_right` method. For example,
1987/// [`u32::rotate_right`]
1988#[rustc_intrinsic_const_stable_indirect]
1989#[rustc_nounwind]
1990#[rustc_intrinsic]
1991pub const fn rotate_right<T: Copy>(x: T, shift: u32) -> T;
1992
1993/// Returns (a + b) mod 2<sup>N</sup>, where N is the width of T in bits.
1994///
1995/// Note that, unlike most intrinsics, this is safe to call;
1996/// it does not require an `unsafe` block.
1997/// Therefore, implementations must not require the user to uphold
1998/// any safety invariants.
1999///
2000/// The stabilized versions of this intrinsic are available on the integer
2001/// primitives via the `wrapping_add` method. For example,
2002/// [`u32::wrapping_add`]
2003#[rustc_intrinsic_const_stable_indirect]
2004#[rustc_nounwind]
2005#[rustc_intrinsic]
2006pub const fn wrapping_add<T: Copy>(a: T, b: T) -> T;
2007/// Returns (a - b) mod 2<sup>N</sup>, where N is the width of T in bits.
2008///
2009/// Note that, unlike most intrinsics, this is safe to call;
2010/// it does not require an `unsafe` block.
2011/// Therefore, implementations must not require the user to uphold
2012/// any safety invariants.
2013///
2014/// The stabilized versions of this intrinsic are available on the integer
2015/// primitives via the `wrapping_sub` method. For example,
2016/// [`u32::wrapping_sub`]
2017#[rustc_intrinsic_const_stable_indirect]
2018#[rustc_nounwind]
2019#[rustc_intrinsic]
2020pub const fn wrapping_sub<T: Copy>(a: T, b: T) -> T;
2021/// Returns (a * b) mod 2<sup>N</sup>, where N is the width of T in bits.
2022///
2023/// Note that, unlike most intrinsics, this is safe to call;
2024/// it does not require an `unsafe` block.
2025/// Therefore, implementations must not require the user to uphold
2026/// any safety invariants.
2027///
2028/// The stabilized versions of this intrinsic are available on the integer
2029/// primitives via the `wrapping_mul` method. For example,
2030/// [`u32::wrapping_mul`]
2031#[rustc_intrinsic_const_stable_indirect]
2032#[rustc_nounwind]
2033#[rustc_intrinsic]
2034pub const fn wrapping_mul<T: Copy>(a: T, b: T) -> T;
2035
2036/// Computes `a + b`, saturating at numeric bounds.
2037///
2038/// Note that, unlike most intrinsics, this is safe to call;
2039/// it does not require an `unsafe` block.
2040/// Therefore, implementations must not require the user to uphold
2041/// any safety invariants.
2042///
2043/// The stabilized versions of this intrinsic are available on the integer
2044/// primitives via the `saturating_add` method. For example,
2045/// [`u32::saturating_add`]
2046#[rustc_intrinsic_const_stable_indirect]
2047#[rustc_nounwind]
2048#[rustc_intrinsic]
2049pub const fn saturating_add<T: Copy>(a: T, b: T) -> T;
2050/// Computes `a - b`, saturating at numeric bounds.
2051///
2052/// Note that, unlike most intrinsics, this is safe to call;
2053/// it does not require an `unsafe` block.
2054/// Therefore, implementations must not require the user to uphold
2055/// any safety invariants.
2056///
2057/// The stabilized versions of this intrinsic are available on the integer
2058/// primitives via the `saturating_sub` method. For example,
2059/// [`u32::saturating_sub`]
2060#[rustc_intrinsic_const_stable_indirect]
2061#[rustc_nounwind]
2062#[rustc_intrinsic]
2063pub const fn saturating_sub<T: Copy>(a: T, b: T) -> T;
2064
2065/// This is an implementation detail of [`crate::ptr::read`] and should
2066/// not be used anywhere else. See its comments for why this exists.
2067///
2068/// This intrinsic can *only* be called where the pointer is a local without
2069/// projections (`read_via_copy(ptr)`, not `read_via_copy(*ptr)`) so that it
2070/// trivially obeys runtime-MIR rules about derefs in operands.
2071#[rustc_intrinsic_const_stable_indirect]
2072#[rustc_nounwind]
2073#[rustc_intrinsic]
2074pub const unsafe fn read_via_copy<T>(ptr: *const T) -> T;
2075
2076/// This is an implementation detail of [`crate::ptr::write`] and should
2077/// not be used anywhere else. See its comments for why this exists.
2078///
2079/// This intrinsic can *only* be called where the pointer is a local without
2080/// projections (`write_via_move(ptr, x)`, not `write_via_move(*ptr, x)`) so
2081/// that it trivially obeys runtime-MIR rules about derefs in operands.
2082#[rustc_intrinsic_const_stable_indirect]
2083#[rustc_nounwind]
2084#[rustc_intrinsic]
2085pub const unsafe fn write_via_move<T>(ptr: *mut T, value: T);
2086
2087/// Returns the value of the discriminant for the variant in 'v';
2088/// if `T` has no discriminant, returns `0`.
2089///
2090/// Note that, unlike most intrinsics, this is safe to call;
2091/// it does not require an `unsafe` block.
2092/// Therefore, implementations must not require the user to uphold
2093/// any safety invariants.
2094///
2095/// The stabilized version of this intrinsic is [`core::mem::discriminant`].
2096#[rustc_intrinsic_const_stable_indirect]
2097#[rustc_nounwind]
2098#[rustc_intrinsic]
2099pub const fn discriminant_value<T>(v: &T) -> <T as DiscriminantKind>::Discriminant;
2100
2101/// Rust's "try catch" construct for unwinding. Invokes the function pointer `try_fn` with the
2102/// data pointer `data`, and calls `catch_fn` if unwinding occurs while `try_fn` runs.
2103/// Returns `1` if unwinding occurred and `catch_fn` was called; returns `0` otherwise.
2104///
2105/// `catch_fn` must not unwind.
2106///
2107/// The third argument is a function called if an unwind occurs (both Rust `panic` and foreign
2108/// unwinds). This function takes the data pointer and a pointer to the target- and
2109/// runtime-specific exception object that was caught.
2110///
2111/// Note that in the case of a foreign unwinding operation, the exception object data may not be
2112/// safely usable from Rust, and should not be directly exposed via the standard library. To
2113/// prevent unsafe access, the library implementation may either abort the process or present an
2114/// opaque error type to the user.
2115///
2116/// For more information, see the compiler's source, as well as the documentation for the stable
2117/// version of this intrinsic, `std::panic::catch_unwind`.
2118#[rustc_intrinsic]
2119#[rustc_nounwind]
2120pub unsafe fn catch_unwind(
2121 _try_fn: fn(*mut u8),
2122 _data: *mut u8,
2123 _catch_fn: fn(*mut u8, *mut u8),
2124) -> i32;
2125
2126/// Emits a `nontemporal` store, which gives a hint to the CPU that the data should not be held
2127/// in cache. Except for performance, this is fully equivalent to `ptr.write(val)`.
2128///
2129/// Not all architectures provide such an operation. For instance, x86 does not: while `MOVNT`
2130/// exists, that operation is *not* equivalent to `ptr.write(val)` (`MOVNT` writes can be reordered
2131/// in ways that are not allowed for regular writes).
2132#[rustc_intrinsic]
2133#[rustc_nounwind]
2134pub unsafe fn nontemporal_store<T>(ptr: *mut T, val: T);
2135
2136/// See documentation of `<*const T>::offset_from` for details.
2137#[rustc_intrinsic_const_stable_indirect]
2138#[rustc_nounwind]
2139#[rustc_intrinsic]
2140pub const unsafe fn ptr_offset_from<T>(ptr: *const T, base: *const T) -> isize;
2141
2142/// See documentation of `<*const T>::offset_from_unsigned` for details.
2143#[rustc_nounwind]
2144#[rustc_intrinsic]
2145#[rustc_intrinsic_const_stable_indirect]
2146pub const unsafe fn ptr_offset_from_unsigned<T>(ptr: *const T, base: *const T) -> usize;
2147
2148/// See documentation of `<*const T>::guaranteed_eq` for details.
2149/// Returns `2` if the result is unknown.
2150/// Returns `1` if the pointers are guaranteed equal.
2151/// Returns `0` if the pointers are guaranteed inequal.
2152#[rustc_intrinsic]
2153#[rustc_nounwind]
2154#[rustc_do_not_const_check]
2155#[inline]
2156#[miri::intrinsic_fallback_is_spec]
2157pub const fn ptr_guaranteed_cmp<T>(ptr: *const T, other: *const T) -> u8 {
2158 (ptr == other) as u8
2159}
2160
2161/// Determines whether the raw bytes of the two values are equal.
2162///
2163/// This is particularly handy for arrays, since it allows things like just
2164/// comparing `i96`s instead of forcing `alloca`s for `[6 x i16]`.
2165///
2166/// Above some backend-decided threshold this will emit calls to `memcmp`,
2167/// like slice equality does, instead of causing massive code size.
2168///
2169/// Since this works by comparing the underlying bytes, the actual `T` is
2170/// not particularly important. It will be used for its size and alignment,
2171/// but any validity restrictions will be ignored, not enforced.
2172///
2173/// # Safety
2174///
2175/// It's UB to call this if any of the *bytes* in `*a` or `*b` are uninitialized.
2176/// Note that this is a stricter criterion than just the *values* being
2177/// fully-initialized: if `T` has padding, it's UB to call this intrinsic.
2178///
2179/// At compile-time, it is furthermore UB to call this if any of the bytes
2180/// in `*a` or `*b` have provenance.
2181///
2182/// (The implementation is allowed to branch on the results of comparisons,
2183/// which is UB if any of their inputs are `undef`.)
2184#[rustc_nounwind]
2185#[rustc_intrinsic]
2186pub const unsafe fn raw_eq<T>(a: &T, b: &T) -> bool;
2187
2188/// Lexicographically compare `[left, left + bytes)` and `[right, right + bytes)`
2189/// as unsigned bytes, returning negative if `left` is less, zero if all the
2190/// bytes match, or positive if `left` is greater.
2191///
2192/// This underlies things like `<[u8]>::cmp`, and will usually lower to `memcmp`.
2193///
2194/// # Safety
2195///
2196/// `left` and `right` must each be [valid] for reads of `bytes` bytes.
2197///
2198/// Note that this applies to the whole range, not just until the first byte
2199/// that differs. That allows optimizations that can read in large chunks.
2200///
2201/// [valid]: crate::ptr#safety
2202#[rustc_nounwind]
2203#[rustc_intrinsic]
2204pub const unsafe fn compare_bytes(left: *const u8, right: *const u8, bytes: usize) -> i32;
2205
2206/// See documentation of [`std::hint::black_box`] for details.
2207///
2208/// [`std::hint::black_box`]: crate::hint::black_box
2209#[rustc_nounwind]
2210#[rustc_intrinsic]
2211#[rustc_intrinsic_const_stable_indirect]
2212pub const fn black_box<T>(dummy: T) -> T;
2213
2214/// Selects which function to call depending on the context.
2215///
2216/// If this function is evaluated at compile-time, then a call to this
2217/// intrinsic will be replaced with a call to `called_in_const`. It gets
2218/// replaced with a call to `called_at_rt` otherwise.
2219///
2220/// This function is safe to call, but note the stability concerns below.
2221///
2222/// # Type Requirements
2223///
2224/// The two functions must be both function items. They cannot be function
2225/// pointers or closures. The first function must be a `const fn`.
2226///
2227/// `arg` will be the tupled arguments that will be passed to either one of
2228/// the two functions, therefore, both functions must accept the same type of
2229/// arguments. Both functions must return RET.
2230///
2231/// # Stability concerns
2232///
2233/// Rust has not yet decided that `const fn` are allowed to tell whether
2234/// they run at compile-time or at runtime. Therefore, when using this
2235/// intrinsic anywhere that can be reached from stable, it is crucial that
2236/// the end-to-end behavior of the stable `const fn` is the same for both
2237/// modes of execution. (Here, Undefined Behavior is considered "the same"
2238/// as any other behavior, so if the function exhibits UB at runtime then
2239/// it may do whatever it wants at compile-time.)
2240///
2241/// Here is an example of how this could cause a problem:
2242/// ```no_run
2243/// #![feature(const_eval_select)]
2244/// #![feature(core_intrinsics)]
2245/// # #![allow(internal_features)]
2246/// use std::intrinsics::const_eval_select;
2247///
2248/// // Standard library
2249/// pub const fn inconsistent() -> i32 {
2250/// fn runtime() -> i32 { 1 }
2251/// const fn compiletime() -> i32 { 2 }
2252///
2253/// // ⚠ This code violates the required equivalence of `compiletime`
2254/// // and `runtime`.
2255/// const_eval_select((), compiletime, runtime)
2256/// }
2257///
2258/// // User Crate
2259/// const X: i32 = inconsistent();
2260/// let x = inconsistent();
2261/// assert_eq!(x, X);
2262/// ```
2263///
2264/// Currently such an assertion would always succeed; until Rust decides
2265/// otherwise, that principle should not be violated.
2266#[rustc_const_unstable(feature = "const_eval_select", issue = "124625")]
2267#[rustc_intrinsic]
2268pub const fn const_eval_select<ARG: Tuple, F, G, RET>(
2269 _arg: ARG,
2270 _called_in_const: F,
2271 _called_at_rt: G,
2272) -> RET
2273where
2274 G: FnOnce<ARG, Output = RET>,
2275 F: FnOnce<ARG, Output = RET>;
2276
2277/// A macro to make it easier to invoke const_eval_select. Use as follows:
2278/// ```rust,ignore (just a macro example)
2279/// const_eval_select!(
2280/// @capture { arg1: i32 = some_expr, arg2: T = other_expr } -> U:
2281/// if const #[attributes_for_const_arm] {
2282/// // Compile-time code goes here.
2283/// } else #[attributes_for_runtime_arm] {
2284/// // Run-time code goes here.
2285/// }
2286/// )
2287/// ```
2288/// The `@capture` block declares which surrounding variables / expressions can be
2289/// used inside the `if const`.
2290/// Note that the two arms of this `if` really each become their own function, which is why the
2291/// macro supports setting attributes for those functions. The runtime function is always
2292/// markes as `#[inline]`.
2293///
2294/// See [`const_eval_select()`] for the rules and requirements around that intrinsic.
2295pub(crate) macro const_eval_select {
2296 (
2297 @capture$([$($binders:tt)*])? { $($arg:ident : $ty:ty = $val:expr),* $(,)? } $( -> $ret:ty )? :
2298 if const
2299 $(#[$compiletime_attr:meta])* $compiletime:block
2300 else
2301 $(#[$runtime_attr:meta])* $runtime:block
2302 ) => {
2303 // Use the `noinline` arm, after adding explicit `inline` attributes
2304 $crate::intrinsics::const_eval_select!(
2305 @capture$([$($binders)*])? { $($arg : $ty = $val),* } $(-> $ret)? :
2306 #[noinline]
2307 if const
2308 #[inline] // prevent codegen on this function
2309 $(#[$compiletime_attr])*
2310 $compiletime
2311 else
2312 #[inline] // avoid the overhead of an extra fn call
2313 $(#[$runtime_attr])*
2314 $runtime
2315 )
2316 },
2317 // With a leading #[noinline], we don't add inline attributes
2318 (
2319 @capture$([$($binders:tt)*])? { $($arg:ident : $ty:ty = $val:expr),* $(,)? } $( -> $ret:ty )? :
2320 #[noinline]
2321 if const
2322 $(#[$compiletime_attr:meta])* $compiletime:block
2323 else
2324 $(#[$runtime_attr:meta])* $runtime:block
2325 ) => {{
2326 $(#[$runtime_attr])*
2327 fn runtime$(<$($binders)*>)?($($arg: $ty),*) $( -> $ret )? {
2328 $runtime
2329 }
2330
2331 $(#[$compiletime_attr])*
2332 const fn compiletime$(<$($binders)*>)?($($arg: $ty),*) $( -> $ret )? {
2333 // Don't warn if one of the arguments is unused.
2334 $(let _ = $arg;)*
2335
2336 $compiletime
2337 }
2338
2339 const_eval_select(($($val,)*), compiletime, runtime)
2340 }},
2341 // We support leaving away the `val` expressions for *all* arguments
2342 // (but not for *some* arguments, that's too tricky).
2343 (
2344 @capture$([$($binders:tt)*])? { $($arg:ident : $ty:ty),* $(,)? } $( -> $ret:ty )? :
2345 if const
2346 $(#[$compiletime_attr:meta])* $compiletime:block
2347 else
2348 $(#[$runtime_attr:meta])* $runtime:block
2349 ) => {
2350 $crate::intrinsics::const_eval_select!(
2351 @capture$([$($binders)*])? { $($arg : $ty = $arg),* } $(-> $ret)? :
2352 if const
2353 $(#[$compiletime_attr])* $compiletime
2354 else
2355 $(#[$runtime_attr])* $runtime
2356 )
2357 },
2358}
2359
2360/// Returns whether the argument's value is statically known at
2361/// compile-time.
2362///
2363/// This is useful when there is a way of writing the code that will
2364/// be *faster* when some variables have known values, but *slower*
2365/// in the general case: an `if is_val_statically_known(var)` can be used
2366/// to select between these two variants. The `if` will be optimized away
2367/// and only the desired branch remains.
2368///
2369/// Formally speaking, this function non-deterministically returns `true`
2370/// or `false`, and the caller has to ensure sound behavior for both cases.
2371/// In other words, the following code has *Undefined Behavior*:
2372///
2373/// ```no_run
2374/// #![feature(core_intrinsics)]
2375/// # #![allow(internal_features)]
2376/// use std::hint::unreachable_unchecked;
2377/// use std::intrinsics::is_val_statically_known;
2378///
2379/// if !is_val_statically_known(0) { unsafe { unreachable_unchecked(); } }
2380/// ```
2381///
2382/// This also means that the following code's behavior is unspecified; it
2383/// may panic, or it may not:
2384///
2385/// ```no_run
2386/// #![feature(core_intrinsics)]
2387/// # #![allow(internal_features)]
2388/// use std::intrinsics::is_val_statically_known;
2389///
2390/// assert_eq!(is_val_statically_known(0), is_val_statically_known(0));
2391/// ```
2392///
2393/// Unsafe code may not rely on `is_val_statically_known` returning any
2394/// particular value, ever. However, the compiler will generally make it
2395/// return `true` only if the value of the argument is actually known.
2396///
2397/// # Stability concerns
2398///
2399/// While it is safe to call, this intrinsic may behave differently in
2400/// a `const` context than otherwise. See the [`const_eval_select()`]
2401/// documentation for an explanation of the issues this can cause. Unlike
2402/// `const_eval_select`, this intrinsic isn't guaranteed to behave
2403/// deterministically even in a `const` context.
2404///
2405/// # Type Requirements
2406///
2407/// `T` must be either a `bool`, a `char`, a primitive numeric type (e.g. `f32`,
2408/// but not `NonZeroISize`), or any thin pointer (e.g. `*mut String`).
2409/// Any other argument types *may* cause a compiler error.
2410///
2411/// ## Pointers
2412///
2413/// When the input is a pointer, only the pointer itself is
2414/// ever considered. The pointee has no effect. Currently, these functions
2415/// behave identically:
2416///
2417/// ```
2418/// #![feature(core_intrinsics)]
2419/// # #![allow(internal_features)]
2420/// use std::intrinsics::is_val_statically_known;
2421///
2422/// fn foo(x: &i32) -> bool {
2423/// is_val_statically_known(x)
2424/// }
2425///
2426/// fn bar(x: &i32) -> bool {
2427/// is_val_statically_known(
2428/// (x as *const i32).addr()
2429/// )
2430/// }
2431/// # _ = foo(&5_i32);
2432/// # _ = bar(&5_i32);
2433/// ```
2434#[rustc_const_stable_indirect]
2435#[rustc_nounwind]
2436#[unstable(feature = "core_intrinsics", issue = "none")]
2437#[rustc_intrinsic]
2438pub const fn is_val_statically_known<T: Copy>(_arg: T) -> bool {
2439 false
2440}
2441
2442/// Non-overlapping *typed* swap of a single value.
2443///
2444/// The codegen backends will replace this with a better implementation when
2445/// `T` is a simple type that can be loaded and stored as an immediate.
2446///
2447/// The stabilized form of this intrinsic is [`crate::mem::swap`].
2448///
2449/// # Safety
2450/// Behavior is undefined if any of the following conditions are violated:
2451///
2452/// * Both `x` and `y` must be [valid] for both reads and writes.
2453///
2454/// * Both `x` and `y` must be properly aligned.
2455///
2456/// * The region of memory beginning at `x` must *not* overlap with the region of memory
2457/// beginning at `y`.
2458///
2459/// * The memory pointed by `x` and `y` must both contain values of type `T`.
2460///
2461/// [valid]: crate::ptr#safety
2462#[rustc_nounwind]
2463#[inline]
2464#[rustc_intrinsic]
2465#[rustc_intrinsic_const_stable_indirect]
2466pub const unsafe fn typed_swap_nonoverlapping<T>(x: *mut T, y: *mut T) {
2467 // SAFETY: The caller provided single non-overlapping items behind
2468 // pointers, so swapping them with `count: 1` is fine.
2469 unsafe { ptr::swap_nonoverlapping(x, y, count:1) };
2470}
2471
2472/// Returns whether we should perform some UB-checking at runtime. This eventually evaluates to
2473/// `cfg!(ub_checks)`, but behaves different from `cfg!` when mixing crates built with different
2474/// flags: if the crate has UB checks enabled or carries the `#[rustc_preserve_ub_checks]`
2475/// attribute, evaluation is delayed until monomorphization (or until the call gets inlined into
2476/// a crate that does not delay evaluation further); otherwise it can happen any time.
2477///
2478/// The common case here is a user program built with ub_checks linked against the distributed
2479/// sysroot which is built without ub_checks but with `#[rustc_preserve_ub_checks]`.
2480/// For code that gets monomorphized in the user crate (i.e., generic functions and functions with
2481/// `#[inline]`), gating assertions on `ub_checks()` rather than `cfg!(ub_checks)` means that
2482/// assertions are enabled whenever the *user crate* has UB checks enabled. However, if the
2483/// user has UB checks disabled, the checks will still get optimized out. This intrinsic is
2484/// primarily used by [`crate::ub_checks::assert_unsafe_precondition`].
2485#[rustc_intrinsic_const_stable_indirect] // just for UB checks
2486#[inline(always)]
2487#[rustc_intrinsic]
2488pub const fn ub_checks() -> bool {
2489 cfg!(ub_checks)
2490}
2491
2492/// Allocates a block of memory at compile time.
2493/// At runtime, just returns a null pointer.
2494///
2495/// # Safety
2496///
2497/// - The `align` argument must be a power of two.
2498/// - At compile time, a compile error occurs if this constraint is violated.
2499/// - At runtime, it is not checked.
2500#[rustc_const_unstable(feature = "const_heap", issue = "79597")]
2501#[rustc_nounwind]
2502#[rustc_intrinsic]
2503#[miri::intrinsic_fallback_is_spec]
2504pub const unsafe fn const_allocate(_size: usize, _align: usize) -> *mut u8 {
2505 // const eval overrides this function, but runtime code for now just returns null pointers.
2506 // See <https://github.com/rust-lang/rust/issues/93935>.
2507 crate::ptr::null_mut()
2508}
2509
2510/// Deallocates a memory which allocated by `intrinsics::const_allocate` at compile time.
2511/// At runtime, does nothing.
2512///
2513/// # Safety
2514///
2515/// - The `align` argument must be a power of two.
2516/// - At compile time, a compile error occurs if this constraint is violated.
2517/// - At runtime, it is not checked.
2518/// - If the `ptr` is created in an another const, this intrinsic doesn't deallocate it.
2519/// - If the `ptr` is pointing to a local variable, this intrinsic doesn't deallocate it.
2520#[rustc_const_unstable(feature = "const_heap", issue = "79597")]
2521#[unstable(feature = "core_intrinsics", issue = "none")]
2522#[rustc_nounwind]
2523#[rustc_intrinsic]
2524#[miri::intrinsic_fallback_is_spec]
2525pub const unsafe fn const_deallocate(_ptr: *mut u8, _size: usize, _align: usize) {
2526 // Runtime NOP
2527}
2528
2529/// Returns whether we should perform contract-checking at runtime.
2530///
2531/// This is meant to be similar to the ub_checks intrinsic, in terms
2532/// of not prematurely commiting at compile-time to whether contract
2533/// checking is turned on, so that we can specify contracts in libstd
2534/// and let an end user opt into turning them on.
2535#[rustc_const_unstable(feature = "contracts_internals", issue = "128044" /* compiler-team#759 */)]
2536#[unstable(feature = "contracts_internals", issue = "128044" /* compiler-team#759 */)]
2537#[inline(always)]
2538#[rustc_intrinsic]
2539pub const fn contract_checks() -> bool {
2540 // FIXME: should this be `false` or `cfg!(contract_checks)`?
2541
2542 // cfg!(contract_checks)
2543 false
2544}
2545
2546/// Check if the pre-condition `cond` has been met.
2547///
2548/// By default, if `contract_checks` is enabled, this will panic with no unwind if the condition
2549/// returns false.
2550///
2551/// Note that this function is a no-op during constant evaluation.
2552#[unstable(feature = "contracts_internals", issue = "128044")]
2553// Calls to this function get inserted by an AST expansion pass, which uses the equivalent of
2554// `#[allow_internal_unstable]` to allow using `contracts_internals` functions. Const-checking
2555// doesn't honor `#[allow_internal_unstable]`, so for the const feature gate we use the user-facing
2556// `contracts` feature rather than the perma-unstable `contracts_internals`
2557#[rustc_const_unstable(feature = "contracts", issue = "128044")]
2558#[lang = "contract_check_requires"]
2559#[rustc_intrinsic]
2560pub const fn contract_check_requires<C: Fn() -> bool + Copy>(cond: C) {
2561 const_eval_select!(
2562 @capture[C: Fn() -> bool + Copy] { cond: C } :
2563 if const {
2564 // Do nothing
2565 } else {
2566 if contract_checks() && !cond() {
2567 // Emit no unwind panic in case this was a safety requirement.
2568 crate::panicking::panic_nounwind("failed requires check");
2569 }
2570 }
2571 )
2572}
2573
2574/// Check if the post-condition `cond` has been met.
2575///
2576/// By default, if `contract_checks` is enabled, this will panic with no unwind if the condition
2577/// returns false.
2578///
2579/// Note that this function is a no-op during constant evaluation.
2580#[unstable(feature = "contracts_internals", issue = "128044")]
2581// Similar to `contract_check_requires`, we need to use the user-facing
2582// `contracts` feature rather than the perma-unstable `contracts_internals`.
2583// Const-checking doesn't honor allow_internal_unstable logic used by contract expansion.
2584#[rustc_const_unstable(feature = "contracts", issue = "128044")]
2585#[lang = "contract_check_ensures"]
2586#[rustc_intrinsic]
2587pub const fn contract_check_ensures<C: Fn(&Ret) -> bool + Copy, Ret>(cond: C, ret: Ret) -> Ret {
2588 const_eval_select!(
2589 @capture[C: Fn(&Ret) -> bool + Copy, Ret] { cond: C, ret: Ret } -> Ret :
2590 if const {
2591 // Do nothing
2592 ret
2593 } else {
2594 if contract_checks() && !cond(&ret) {
2595 // Emit no unwind panic in case this was a safety requirement.
2596 crate::panicking::panic_nounwind("failed ensures check");
2597 }
2598 ret
2599 }
2600 )
2601}
2602
2603/// The intrinsic will return the size stored in that vtable.
2604///
2605/// # Safety
2606///
2607/// `ptr` must point to a vtable.
2608#[rustc_nounwind]
2609#[unstable(feature = "core_intrinsics", issue = "none")]
2610#[rustc_intrinsic]
2611pub unsafe fn vtable_size(ptr: *const ()) -> usize;
2612
2613/// The intrinsic will return the alignment stored in that vtable.
2614///
2615/// # Safety
2616///
2617/// `ptr` must point to a vtable.
2618#[rustc_nounwind]
2619#[unstable(feature = "core_intrinsics", issue = "none")]
2620#[rustc_intrinsic]
2621pub unsafe fn vtable_align(ptr: *const ()) -> usize;
2622
2623/// The size of a type in bytes.
2624///
2625/// Note that, unlike most intrinsics, this is safe to call;
2626/// it does not require an `unsafe` block.
2627/// Therefore, implementations must not require the user to uphold
2628/// any safety invariants.
2629///
2630/// More specifically, this is the offset in bytes between successive
2631/// items of the same type, including alignment padding.
2632///
2633/// The stabilized version of this intrinsic is [`size_of`].
2634#[rustc_nounwind]
2635#[unstable(feature = "core_intrinsics", issue = "none")]
2636#[rustc_intrinsic_const_stable_indirect]
2637#[rustc_intrinsic]
2638pub const fn size_of<T>() -> usize;
2639
2640/// The minimum alignment of a type.
2641///
2642/// Note that, unlike most intrinsics, this is safe to call;
2643/// it does not require an `unsafe` block.
2644/// Therefore, implementations must not require the user to uphold
2645/// any safety invariants.
2646///
2647/// The stabilized version of this intrinsic is [`align_of`].
2648#[rustc_nounwind]
2649#[unstable(feature = "core_intrinsics", issue = "none")]
2650#[rustc_intrinsic_const_stable_indirect]
2651#[rustc_intrinsic]
2652pub const fn min_align_of<T>() -> usize;
2653
2654/// Returns the number of variants of the type `T` cast to a `usize`;
2655/// if `T` has no variants, returns `0`. Uninhabited variants will be counted.
2656///
2657/// Note that, unlike most intrinsics, this is safe to call;
2658/// it does not require an `unsafe` block.
2659/// Therefore, implementations must not require the user to uphold
2660/// any safety invariants.
2661///
2662/// The to-be-stabilized version of this intrinsic is [`crate::mem::variant_count`].
2663#[rustc_nounwind]
2664#[unstable(feature = "core_intrinsics", issue = "none")]
2665#[rustc_intrinsic]
2666pub const fn variant_count<T>() -> usize;
2667
2668/// The size of the referenced value in bytes.
2669///
2670/// The stabilized version of this intrinsic is [`size_of_val`].
2671///
2672/// # Safety
2673///
2674/// See [`crate::mem::size_of_val_raw`] for safety conditions.
2675#[rustc_nounwind]
2676#[unstable(feature = "core_intrinsics", issue = "none")]
2677#[rustc_intrinsic]
2678#[rustc_intrinsic_const_stable_indirect]
2679pub const unsafe fn size_of_val<T: ?Sized>(ptr: *const T) -> usize;
2680
2681/// The required alignment of the referenced value.
2682///
2683/// The stabilized version of this intrinsic is [`align_of_val`].
2684///
2685/// # Safety
2686///
2687/// See [`crate::mem::align_of_val_raw`] for safety conditions.
2688#[rustc_nounwind]
2689#[unstable(feature = "core_intrinsics", issue = "none")]
2690#[rustc_intrinsic]
2691#[rustc_intrinsic_const_stable_indirect]
2692pub const unsafe fn min_align_of_val<T: ?Sized>(ptr: *const T) -> usize;
2693
2694/// Gets a static string slice containing the name of a type.
2695///
2696/// Note that, unlike most intrinsics, this is safe to call;
2697/// it does not require an `unsafe` block.
2698/// Therefore, implementations must not require the user to uphold
2699/// any safety invariants.
2700///
2701/// The stabilized version of this intrinsic is [`core::any::type_name`].
2702#[rustc_nounwind]
2703#[unstable(feature = "core_intrinsics", issue = "none")]
2704#[rustc_intrinsic]
2705pub const fn type_name<T: ?Sized>() -> &'static str;
2706
2707/// Gets an identifier which is globally unique to the specified type. This
2708/// function will return the same value for a type regardless of whichever
2709/// crate it is invoked in.
2710///
2711/// Note that, unlike most intrinsics, this is safe to call;
2712/// it does not require an `unsafe` block.
2713/// Therefore, implementations must not require the user to uphold
2714/// any safety invariants.
2715///
2716/// The stabilized version of this intrinsic is [`core::any::TypeId::of`].
2717#[rustc_nounwind]
2718#[unstable(feature = "core_intrinsics", issue = "none")]
2719#[rustc_intrinsic]
2720pub const fn type_id<T: ?Sized + 'static>() -> u128;
2721
2722/// Lowers in MIR to `Rvalue::Aggregate` with `AggregateKind::RawPtr`.
2723///
2724/// This is used to implement functions like `slice::from_raw_parts_mut` and
2725/// `ptr::from_raw_parts` in a way compatible with the compiler being able to
2726/// change the possible layouts of pointers.
2727#[rustc_nounwind]
2728#[unstable(feature = "core_intrinsics", issue = "none")]
2729#[rustc_intrinsic_const_stable_indirect]
2730#[rustc_intrinsic]
2731pub const fn aggregate_raw_ptr<P: bounds::BuiltinDeref, D, M>(data: D, meta: M) -> P
2732where
2733 <P as bounds::BuiltinDeref>::Pointee: ptr::Pointee<Metadata = M>;
2734
2735/// Lowers in MIR to `Rvalue::UnaryOp` with `UnOp::PtrMetadata`.
2736///
2737/// This is used to implement functions like `ptr::metadata`.
2738#[rustc_nounwind]
2739#[unstable(feature = "core_intrinsics", issue = "none")]
2740#[rustc_intrinsic_const_stable_indirect]
2741#[rustc_intrinsic]
2742pub const fn ptr_metadata<P: ptr::Pointee<Metadata = M> + ?Sized, M>(ptr: *const P) -> M;
2743
2744/// This is an accidentally-stable alias to [`ptr::copy_nonoverlapping`]; use that instead.
2745// Note (intentionally not in the doc comment): `ptr::copy_nonoverlapping` adds some extra
2746// debug assertions; if you are writing compiler tests or code inside the standard library
2747// that wants to avoid those debug assertions, directly call this intrinsic instead.
2748#[stable(feature = "rust1", since = "1.0.0")]
2749#[rustc_allowed_through_unstable_modules = "import this function via `std::ptr` instead"]
2750#[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
2751#[rustc_nounwind]
2752#[rustc_intrinsic]
2753pub const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize);
2754
2755/// This is an accidentally-stable alias to [`ptr::copy`]; use that instead.
2756// Note (intentionally not in the doc comment): `ptr::copy` adds some extra
2757// debug assertions; if you are writing compiler tests or code inside the standard library
2758// that wants to avoid those debug assertions, directly call this intrinsic instead.
2759#[stable(feature = "rust1", since = "1.0.0")]
2760#[rustc_allowed_through_unstable_modules = "import this function via `std::ptr` instead"]
2761#[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
2762#[rustc_nounwind]
2763#[rustc_intrinsic]
2764pub const unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize);
2765
2766/// This is an accidentally-stable alias to [`ptr::write_bytes`]; use that instead.
2767// Note (intentionally not in the doc comment): `ptr::write_bytes` adds some extra
2768// debug assertions; if you are writing compiler tests or code inside the standard library
2769// that wants to avoid those debug assertions, directly call this intrinsic instead.
2770#[stable(feature = "rust1", since = "1.0.0")]
2771#[rustc_allowed_through_unstable_modules = "import this function via `std::ptr` instead"]
2772#[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
2773#[rustc_nounwind]
2774#[rustc_intrinsic]
2775pub const unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize);
2776
2777/// Returns the minimum (IEEE 754-2008 minNum) of two `f16` values.
2778///
2779/// Note that, unlike most intrinsics, this is safe to call;
2780/// it does not require an `unsafe` block.
2781/// Therefore, implementations must not require the user to uphold
2782/// any safety invariants.
2783///
2784/// The stabilized version of this intrinsic is
2785/// [`f16::min`]
2786#[rustc_nounwind]
2787#[rustc_intrinsic]
2788pub const fn minnumf16(x: f16, y: f16) -> f16;
2789
2790/// Returns the minimum (IEEE 754-2008 minNum) of two `f32` values.
2791///
2792/// Note that, unlike most intrinsics, this is safe to call;
2793/// it does not require an `unsafe` block.
2794/// Therefore, implementations must not require the user to uphold
2795/// any safety invariants.
2796///
2797/// The stabilized version of this intrinsic is
2798/// [`f32::min`]
2799#[rustc_nounwind]
2800#[rustc_intrinsic_const_stable_indirect]
2801#[rustc_intrinsic]
2802pub const fn minnumf32(x: f32, y: f32) -> f32;
2803
2804/// Returns the minimum (IEEE 754-2008 minNum) of two `f64` values.
2805///
2806/// Note that, unlike most intrinsics, this is safe to call;
2807/// it does not require an `unsafe` block.
2808/// Therefore, implementations must not require the user to uphold
2809/// any safety invariants.
2810///
2811/// The stabilized version of this intrinsic is
2812/// [`f64::min`]
2813#[rustc_nounwind]
2814#[rustc_intrinsic_const_stable_indirect]
2815#[rustc_intrinsic]
2816pub const fn minnumf64(x: f64, y: f64) -> f64;
2817
2818/// Returns the minimum (IEEE 754-2008 minNum) of two `f128` values.
2819///
2820/// Note that, unlike most intrinsics, this is safe to call;
2821/// it does not require an `unsafe` block.
2822/// Therefore, implementations must not require the user to uphold
2823/// any safety invariants.
2824///
2825/// The stabilized version of this intrinsic is
2826/// [`f128::min`]
2827#[rustc_nounwind]
2828#[rustc_intrinsic]
2829pub const fn minnumf128(x: f128, y: f128) -> f128;
2830
2831/// Returns the minimum (IEEE 754-2019 minimum) of two `f16` values.
2832///
2833/// Note that, unlike most intrinsics, this is safe to call;
2834/// it does not require an `unsafe` block.
2835/// Therefore, implementations must not require the user to uphold
2836/// any safety invariants.
2837#[rustc_nounwind]
2838#[rustc_intrinsic]
2839pub const fn minimumf16(x: f16, y: f16) -> f16 {
2840 if x < y {
2841 x
2842 } else if y < x {
2843 y
2844 } else if x == y {
2845 if x.is_sign_negative() && y.is_sign_positive() { x } else { y }
2846 } else {
2847 // At least one input is NaN. Use `+` to perform NaN propagation and quieting.
2848 x + y
2849 }
2850}
2851
2852/// Returns the minimum (IEEE 754-2019 minimum) of two `f32` values.
2853///
2854/// Note that, unlike most intrinsics, this is safe to call;
2855/// it does not require an `unsafe` block.
2856/// Therefore, implementations must not require the user to uphold
2857/// any safety invariants.
2858#[rustc_nounwind]
2859#[rustc_intrinsic]
2860pub const fn minimumf32(x: f32, y: f32) -> f32 {
2861 if x < y {
2862 x
2863 } else if y < x {
2864 y
2865 } else if x == y {
2866 if x.is_sign_negative() && y.is_sign_positive() { x } else { y }
2867 } else {
2868 // At least one input is NaN. Use `+` to perform NaN propagation and quieting.
2869 x + y
2870 }
2871}
2872
2873/// Returns the minimum (IEEE 754-2019 minimum) of two `f64` values.
2874///
2875/// Note that, unlike most intrinsics, this is safe to call;
2876/// it does not require an `unsafe` block.
2877/// Therefore, implementations must not require the user to uphold
2878/// any safety invariants.
2879#[rustc_nounwind]
2880#[rustc_intrinsic]
2881pub const fn minimumf64(x: f64, y: f64) -> f64 {
2882 if x < y {
2883 x
2884 } else if y < x {
2885 y
2886 } else if x == y {
2887 if x.is_sign_negative() && y.is_sign_positive() { x } else { y }
2888 } else {
2889 // At least one input is NaN. Use `+` to perform NaN propagation and quieting.
2890 x + y
2891 }
2892}
2893
2894/// Returns the minimum (IEEE 754-2019 minimum) of two `f128` values.
2895///
2896/// Note that, unlike most intrinsics, this is safe to call;
2897/// it does not require an `unsafe` block.
2898/// Therefore, implementations must not require the user to uphold
2899/// any safety invariants.
2900#[rustc_nounwind]
2901#[rustc_intrinsic]
2902pub const fn minimumf128(x: f128, y: f128) -> f128 {
2903 if x < y {
2904 x
2905 } else if y < x {
2906 y
2907 } else if x == y {
2908 if x.is_sign_negative() && y.is_sign_positive() { x } else { y }
2909 } else {
2910 // At least one input is NaN. Use `+` to perform NaN propagation and quieting.
2911 x + y
2912 }
2913}
2914
2915/// Returns the maximum (IEEE 754-2008 maxNum) of two `f16` values.
2916///
2917/// Note that, unlike most intrinsics, this is safe to call;
2918/// it does not require an `unsafe` block.
2919/// Therefore, implementations must not require the user to uphold
2920/// any safety invariants.
2921///
2922/// The stabilized version of this intrinsic is
2923/// [`f16::max`]
2924#[rustc_nounwind]
2925#[rustc_intrinsic]
2926pub const fn maxnumf16(x: f16, y: f16) -> f16;
2927
2928/// Returns the maximum (IEEE 754-2008 maxNum) of two `f32` values.
2929///
2930/// Note that, unlike most intrinsics, this is safe to call;
2931/// it does not require an `unsafe` block.
2932/// Therefore, implementations must not require the user to uphold
2933/// any safety invariants.
2934///
2935/// The stabilized version of this intrinsic is
2936/// [`f32::max`]
2937#[rustc_nounwind]
2938#[rustc_intrinsic_const_stable_indirect]
2939#[rustc_intrinsic]
2940pub const fn maxnumf32(x: f32, y: f32) -> f32;
2941
2942/// Returns the maximum (IEEE 754-2008 maxNum) of two `f64` values.
2943///
2944/// Note that, unlike most intrinsics, this is safe to call;
2945/// it does not require an `unsafe` block.
2946/// Therefore, implementations must not require the user to uphold
2947/// any safety invariants.
2948///
2949/// The stabilized version of this intrinsic is
2950/// [`f64::max`]
2951#[rustc_nounwind]
2952#[rustc_intrinsic_const_stable_indirect]
2953#[rustc_intrinsic]
2954pub const fn maxnumf64(x: f64, y: f64) -> f64;
2955
2956/// Returns the maximum (IEEE 754-2008 maxNum) of two `f128` values.
2957///
2958/// Note that, unlike most intrinsics, this is safe to call;
2959/// it does not require an `unsafe` block.
2960/// Therefore, implementations must not require the user to uphold
2961/// any safety invariants.
2962///
2963/// The stabilized version of this intrinsic is
2964/// [`f128::max`]
2965#[rustc_nounwind]
2966#[rustc_intrinsic]
2967pub const fn maxnumf128(x: f128, y: f128) -> f128;
2968
2969/// Returns the maximum (IEEE 754-2019 maximum) of two `f16` values.
2970///
2971/// Note that, unlike most intrinsics, this is safe to call;
2972/// it does not require an `unsafe` block.
2973/// Therefore, implementations must not require the user to uphold
2974/// any safety invariants.
2975#[rustc_nounwind]
2976#[rustc_intrinsic]
2977pub const fn maximumf16(x: f16, y: f16) -> f16 {
2978 if x > y {
2979 x
2980 } else if y > x {
2981 y
2982 } else if x == y {
2983 if x.is_sign_positive() && y.is_sign_negative() { x } else { y }
2984 } else {
2985 x + y
2986 }
2987}
2988
2989/// Returns the maximum (IEEE 754-2019 maximum) of two `f32` values.
2990///
2991/// Note that, unlike most intrinsics, this is safe to call;
2992/// it does not require an `unsafe` block.
2993/// Therefore, implementations must not require the user to uphold
2994/// any safety invariants.
2995#[rustc_nounwind]
2996#[rustc_intrinsic]
2997pub const fn maximumf32(x: f32, y: f32) -> f32 {
2998 if x > y {
2999 x
3000 } else if y > x {
3001 y
3002 } else if x == y {
3003 if x.is_sign_positive() && y.is_sign_negative() { x } else { y }
3004 } else {
3005 x + y
3006 }
3007}
3008
3009/// Returns the maximum (IEEE 754-2019 maximum) of two `f64` values.
3010///
3011/// Note that, unlike most intrinsics, this is safe to call;
3012/// it does not require an `unsafe` block.
3013/// Therefore, implementations must not require the user to uphold
3014/// any safety invariants.
3015#[rustc_nounwind]
3016#[rustc_intrinsic]
3017pub const fn maximumf64(x: f64, y: f64) -> f64 {
3018 if x > y {
3019 x
3020 } else if y > x {
3021 y
3022 } else if x == y {
3023 if x.is_sign_positive() && y.is_sign_negative() { x } else { y }
3024 } else {
3025 x + y
3026 }
3027}
3028
3029/// Returns the maximum (IEEE 754-2019 maximum) of two `f128` values.
3030///
3031/// Note that, unlike most intrinsics, this is safe to call;
3032/// it does not require an `unsafe` block.
3033/// Therefore, implementations must not require the user to uphold
3034/// any safety invariants.
3035#[rustc_nounwind]
3036#[rustc_intrinsic]
3037pub const fn maximumf128(x: f128, y: f128) -> f128 {
3038 if x > y {
3039 x
3040 } else if y > x {
3041 y
3042 } else if x == y {
3043 if x.is_sign_positive() && y.is_sign_negative() { x } else { y }
3044 } else {
3045 x + y
3046 }
3047}
3048
3049/// Returns the absolute value of an `f16`.
3050///
3051/// The stabilized version of this intrinsic is
3052/// [`f16::abs`](../../std/primitive.f16.html#method.abs)
3053#[rustc_nounwind]
3054#[rustc_intrinsic]
3055pub const unsafe fn fabsf16(x: f16) -> f16;
3056
3057/// Returns the absolute value of an `f32`.
3058///
3059/// The stabilized version of this intrinsic is
3060/// [`f32::abs`](../../std/primitive.f32.html#method.abs)
3061#[rustc_nounwind]
3062#[rustc_intrinsic_const_stable_indirect]
3063#[rustc_intrinsic]
3064pub const unsafe fn fabsf32(x: f32) -> f32;
3065
3066/// Returns the absolute value of an `f64`.
3067///
3068/// The stabilized version of this intrinsic is
3069/// [`f64::abs`](../../std/primitive.f64.html#method.abs)
3070#[rustc_nounwind]
3071#[rustc_intrinsic_const_stable_indirect]
3072#[rustc_intrinsic]
3073pub const unsafe fn fabsf64(x: f64) -> f64;
3074
3075/// Returns the absolute value of an `f128`.
3076///
3077/// The stabilized version of this intrinsic is
3078/// [`f128::abs`](../../std/primitive.f128.html#method.abs)
3079#[rustc_nounwind]
3080#[rustc_intrinsic]
3081pub const unsafe fn fabsf128(x: f128) -> f128;
3082
3083/// Copies the sign from `y` to `x` for `f16` values.
3084///
3085/// The stabilized version of this intrinsic is
3086/// [`f16::copysign`](../../std/primitive.f16.html#method.copysign)
3087#[rustc_nounwind]
3088#[rustc_intrinsic]
3089pub const unsafe fn copysignf16(x: f16, y: f16) -> f16;
3090
3091/// Copies the sign from `y` to `x` for `f32` values.
3092///
3093/// The stabilized version of this intrinsic is
3094/// [`f32::copysign`](../../std/primitive.f32.html#method.copysign)
3095#[rustc_nounwind]
3096#[rustc_intrinsic_const_stable_indirect]
3097#[rustc_intrinsic]
3098pub const unsafe fn copysignf32(x: f32, y: f32) -> f32;
3099/// Copies the sign from `y` to `x` for `f64` values.
3100///
3101/// The stabilized version of this intrinsic is
3102/// [`f64::copysign`](../../std/primitive.f64.html#method.copysign)
3103#[rustc_nounwind]
3104#[rustc_intrinsic_const_stable_indirect]
3105#[rustc_intrinsic]
3106pub const unsafe fn copysignf64(x: f64, y: f64) -> f64;
3107
3108/// Copies the sign from `y` to `x` for `f128` values.
3109///
3110/// The stabilized version of this intrinsic is
3111/// [`f128::copysign`](../../std/primitive.f128.html#method.copysign)
3112#[rustc_nounwind]
3113#[rustc_intrinsic]
3114pub const unsafe fn copysignf128(x: f128, y: f128) -> f128;
3115
3116/// Inform Miri that a given pointer definitely has a certain alignment.
3117#[cfg(miri)]
3118#[rustc_allow_const_fn_unstable(const_eval_select)]
3119pub(crate) const fn miri_promise_symbolic_alignment(ptr: *const (), align: usize) {
3120 unsafe extern "Rust" {
3121 /// Miri-provided extern function to promise that a given pointer is properly aligned for
3122 /// "symbolic" alignment checks. Will fail if the pointer is not actually aligned or `align` is
3123 /// not a power of two. Has no effect when alignment checks are concrete (which is the default).
3124 unsafefn miri_promise_symbolic_alignment(ptr: *const (), align: usize);
3125 }
3126
3127 const_eval_select!(
3128 @capture { ptr: *const (), align: usize}:
3129 if const {
3130 // Do nothing.
3131 } else {
3132 // SAFETY: this call is always safe.
3133 unsafe {
3134 miri_promise_symbolic_alignment(ptr, align);
3135 }
3136 }
3137 )
3138}
3139