//! Manually manage memory through raw pointers.

//!

//! *[See also the pointer primitive types](pointer).*

//!

//! # Safety

//!

//! Many functions in this module take raw pointers as arguments and read from or write to them. For

//! this to be safe, these pointers must be *valid* for the given access. Whether a pointer is valid

//! depends on the operation it is used for (read or write), and the extent of the memory that is

//! accessed (i.e., how many bytes are read/written) -- it makes no sense to ask "is this pointer

//! valid"; one has to ask "is this pointer valid for a given access". Most functions use `*mut T`

//! and `*const T` to access only a single value, in which case the documentation omits the size and

//! implicitly assumes it to be `size_of::<T>()` bytes.

//!

//! The precise rules for validity are not determined yet. The guarantees that are

//! provided at this point are very minimal:

//!

//! * For memory accesses of [size zero][zst], *every* pointer is valid, including the [null]

//!   pointer. The following points are only concerned with non-zero-sized accesses.

//! * A [null] pointer is *never* valid.

//! * For a pointer to be valid, it is necessary, but not always sufficient, that the pointer be

//!   *dereferenceable*. The [provenance] of the pointer is used to determine which [allocation]

//!   it is derived from; a pointer is dereferenceable if the memory range of the given size

//!   starting at the pointer is entirely contained within the bounds of that allocation. Note

//!   that in Rust, every (stack-allocated) variable is considered a separate allocation.

//! * All accesses performed by functions in this module are *non-atomic* in the sense

//!   of [atomic operations] used to synchronize between threads. This means it is

//!   undefined behavior to perform two concurrent accesses to the same location from different

//!   threads unless both accesses only read from memory. Notice that this explicitly

//!   includes [`read_volatile`] and [`write_volatile`]: Volatile accesses cannot

//!   be used for inter-thread synchronization, regardless of whether they are acting on

//!   Rust memory or not.

//! * The result of casting a reference to a pointer is valid for as long as the

//!   underlying allocation is live and no reference (just raw pointers) is used to

//!   access the same memory. That is, reference and pointer accesses cannot be

//!   interleaved.

//!

//! These axioms, along with careful use of [`offset`] for pointer arithmetic,

//! are enough to correctly implement many useful things in unsafe code. Stronger guarantees

//! will be provided eventually, as the [aliasing] rules are being determined. For more

//! information, see the [book] as well as the section in the reference devoted

//! to [undefined behavior][ub].

//!

//! We say that a pointer is "dangling" if it is not valid for any non-zero-sized accesses. This

//! means out-of-bounds pointers, pointers to freed memory, null pointers, and pointers created with

//! [`NonNull::dangling`] are all dangling.

//!

//! ## Alignment

//!

//! Valid raw pointers as defined above are not necessarily properly aligned (where

//! "proper" alignment is defined by the pointee type, i.e., `*const T` must be

//! aligned to `align_of::<T>()`). However, most functions require their

//! arguments to be properly aligned, and will explicitly state

//! this requirement in their documentation. Notable exceptions to this are

//! [`read_unaligned`] and [`write_unaligned`].

//!

//! When a function requires proper alignment, it does so even if the access

//! has size 0, i.e., even if memory is not actually touched. Consider using

//! [`NonNull::dangling`] in such cases.

//!

//! ## Pointer to reference conversion

//!

//! When converting a pointer to a reference (e.g. via `&*ptr` or `&mut *ptr`),

//! there are several rules that must be followed:

//!

//! * The pointer must be properly aligned.

//!

//! * It must be non-null.

//!

//! * It must be "dereferenceable" in the sense defined above.

//!

//! * The pointer must point to a [valid value] of type `T`.

//!

//! * You must enforce Rust's aliasing rules. The exact aliasing rules are not decided yet, so we

//!   only give a rough overview here. The rules also depend on whether a mutable or a shared

//!   reference is being created.

//!   * When creating a mutable reference, then while this reference exists, the memory it points to

//!     must not get accessed (read or written) through any other pointer or reference not derived

//!     from this reference.

//!   * When creating a shared reference, then while this reference exists, the memory it points to

//!     must not get mutated (except inside `UnsafeCell`).

//!

//! If a pointer follows all of these rules, it is said to be

//! *convertible to a (mutable or shared) reference*.

// ^ we use this term instead of saying that the produced reference must

// be valid, as the validity of a reference is easily confused for the

// validity of the thing it refers to, and while the two concepts are

// closely related, they are not identical.

//!

//! These rules apply even if the result is unused!

//! (The part about being initialized is not yet fully decided, but until

//! it is, the only safe approach is to ensure that they are indeed initialized.)

//!

//! An example of the implications of the above rules is that an expression such

//! as `unsafe { &*(0 as *const u8) }` is Immediate Undefined Behavior.

//!

//! [valid value]: ../../reference/behavior-considered-undefined.html#invalid-values

//!

//! ## Allocation

//!

//! <a id="allocated-object"></a> <!-- keep old URLs working -->

//!

//! An *allocation* is a subset of program memory which is addressable

//! from Rust, and within which pointer arithmetic is possible. Examples of

//! allocations include heap allocations, stack-allocated variables,

//! statics, and consts. The safety preconditions of some Rust operations -

//! such as `offset` and field projections (`expr.field`) - are defined in

//! terms of the allocations on which they operate.

//!

//! An allocation has a base address, a size, and a set of memory

//! addresses. It is possible for an allocation to have zero size, but

//! such an allocation will still have a base address. The base address

//! of an allocation is not necessarily unique. While it is currently the

//! case that an allocation always has a set of memory addresses which is

//! fully contiguous (i.e., has no "holes"), there is no guarantee that this

//! will not change in the future.

//!

//! Allocations must behave like "normal" memory: in particular, reads must not have

//! side-effects, and writes must become visible to other threads using the usual synchronization

//! primitives.

//!

//! For any allocation with `base` address, `size`, and a set of

//! `addresses`, the following are guaranteed:

//! - For all addresses `a` in `addresses`, `a` is in the range `base .. (base +

//!   size)` (note that this requires `a < base + size`, not `a <= base + size`)

//! - `base` is not equal to [`null()`] (i.e., the address with the numerical

//!   value 0)

//! - `base + size <= usize::MAX`

//! - `size <= isize::MAX`

//!

//! As a consequence of these guarantees, given any address `a` within the set

//! of addresses of an allocation:

//! - It is guaranteed that `a - base` does not overflow `isize`

//! - It is guaranteed that `a - base` is non-negative

//! - It is guaranteed that, given `o = a - base` (i.e., the offset of `a` within

//!   the allocation), `base + o` will not wrap around the address space (in

//!   other words, will not overflow `usize`)

//!

//! [`null()`]: null

//!

//! # Provenance

//!

//! Pointers are not *simply* an "integer" or "address". For instance, it's uncontroversial

//! to say that a Use After Free is clearly Undefined Behavior, even if you "get lucky"

//! and the freed memory gets reallocated before your read/write (in fact this is the

//! worst-case scenario, UAFs would be much less concerning if this didn't happen!).

//! As another example, consider that [`wrapping_offset`] is documented to "remember"

//! the allocation that the original pointer points to, even if it is offset far

//! outside the memory range occupied by that allocation.

//! To rationalize claims like this, pointers need to somehow be *more* than just their addresses:

//! they must have **provenance**.

//!

//! A pointer value in Rust semantically contains the following information:

//!

//! * The **address** it points to, which can be represented by a `usize`.

//! * The **provenance** it has, defining the memory it has permission to access. Provenance can be

//!   absent, in which case the pointer does not have permission to access any memory.

//!

//! The exact structure of provenance is not yet specified, but the permission defined by a

//! pointer's provenance have a *spatial* component, a *temporal* component, and a *mutability*

//! component:

//!

//! * Spatial: The set of memory addresses that the pointer is allowed to access.

//! * Temporal: The timespan during which the pointer is allowed to access those memory addresses.

//! * Mutability: Whether the pointer may only access the memory for reads, or also access it for

//!   writes. Note that this can interact with the other components, e.g. a pointer might permit

//!   mutation only for a subset of addresses, or only for a subset of its maximal timespan.

//!

//! When an [allocation] is created, it has a unique Original Pointer. For alloc

//! APIs this is literally the pointer the call returns, and for local variables and statics,

//! this is the name of the variable/static. (This is mildly overloading the term "pointer"

//! for the sake of brevity/exposition.)

//!

//! The Original Pointer for an allocation has provenance that constrains the *spatial*

//! permissions of this pointer to the memory range of the allocation, and the *temporal*

//! permissions to the lifetime of the allocation. Provenance is implicitly inherited by all

//! pointers transitively derived from the Original Pointer through operations like [`offset`],

//! borrowing, and pointer casts. Some operations may *shrink* the permissions of the derived

//! provenance, limiting how much memory it can access or how long it's valid for (i.e. borrowing a

//! subfield and subslicing can shrink the spatial component of provenance, and all borrowing can

//! shrink the temporal component of provenance). However, no operation can ever *grow* the

//! permissions of the derived provenance: even if you "know" there is a larger allocation, you

//! can't derive a pointer with a larger provenance. Similarly, you cannot "recombine" two

//! contiguous provenances back into one (i.e. with a `fn merge(&[T], &[T]) -> &[T]`).

//!

//! A reference to a place always has provenance over at least the memory that place occupies.

//! A reference to a slice always has provenance over at least the range that slice describes.

//! Whether and when exactly the provenance of a reference gets "shrunk" to *exactly* fit

//! the memory it points to is not yet determined.

//!

//! A *shared* reference only ever has provenance that permits reading from memory,

//! and never permits writes, except inside [`UnsafeCell`].

//!

//! Provenance can affect whether a program has undefined behavior:

//!

//! * It is undefined behavior to access memory through a pointer that does not have provenance over

//!   that memory. Note that a pointer "at the end" of its provenance is not actually outside its

//!   provenance, it just has 0 bytes it can load/store. Zero-sized accesses do not require any

//!   provenance since they access an empty range of memory.

//!

//! * It is undefined behavior to [`offset`] a pointer across a memory range that is not contained

//!   in the allocation it is derived from, or to [`offset_from`] two pointers not derived

//!   from the same allocation. Provenance is used to say what exactly "derived from" even

//!   means: the lineage of a pointer is traced back to the Original Pointer it descends from, and

//!   that identifies the relevant allocation. In particular, it's always UB to offset a

//!   pointer derived from something that is now deallocated, except if the offset is 0.

//!

//! But it *is* still sound to:

//!

//! * Create a pointer without provenance from just an address (see [`without_provenance`]). Such a

//!   pointer cannot be used for memory accesses (except for zero-sized accesses). This can still be

//!   useful for sentinel values like `null` *or* to represent a tagged pointer that will never be

//!   dereferenceable. In general, it is always sound for an integer to pretend to be a pointer "for

//!   fun" as long as you don't use operations on it which require it to be valid (non-zero-sized

//!   offset, read, write, etc).

//!

//! * Forge an allocation of size zero at any sufficiently aligned non-null address.

//!   i.e. the usual "ZSTs are fake, do what you want" rules apply.

//!

//! * [`wrapping_offset`] a pointer outside its provenance. This includes pointers

//!   which have "no" provenance. In particular, this makes it sound to do pointer tagging tricks.

//!

//! * Compare arbitrary pointers by address. Pointer comparison ignores provenance and addresses

//!   *are* just integers, so there is always a coherent answer, even if the pointers are dangling

//!   or from different provenances. Note that if you get "lucky" and notice that a pointer at the

//!   end of one allocation is the "same" address as the start of another allocation,

//!   anything you do with that fact is *probably* going to be gibberish. The scope of that

//!   gibberish is kept under control by the fact that the two pointers *still* aren't allowed to

//!   access the other's allocation (bytes), because they still have different provenance.

//!

//! Note that the full definition of provenance in Rust is not decided yet, as this interacts

//! with the as-yet undecided [aliasing] rules.

//!

//! ## Pointers Vs Integers

//!

//! From this discussion, it becomes very clear that a `usize` *cannot* accurately represent a pointer,

//! and converting from a pointer to a `usize` is generally an operation which *only* extracts the

//! address. Converting this address back into pointer requires somehow answering the question:

//! which provenance should the resulting pointer have?

//!

//! Rust provides two ways of dealing with this situation: *Strict Provenance* and *Exposed Provenance*.

//!

//! Note that a pointer *can* represent a `usize` (via [`without_provenance`]), so the right type to

//! use in situations where a value is "sometimes a pointer and sometimes a bare `usize`" is a

//! pointer type.

//!

//! ## Strict Provenance

//!

//! "Strict Provenance" refers to a set of APIs designed to make working with provenance more

//! explicit. They are intended as substitutes for casting a pointer to an integer and back.

//!

//! Entirely avoiding integer-to-pointer casts successfully side-steps the inherent ambiguity of

//! that operation. This benefits compiler optimizations, and it is pretty much a requirement for

//! using tools like [Miri] and architectures like [CHERI] that aim to detect and diagnose pointer

//! misuse.

//!

//! The key insight to making programming without integer-to-pointer casts *at all* viable is the

//! [`with_addr`] method:

//!

//! ```text

//!     /// Creates a new pointer with the given address.

//!     ///

//!     /// This performs the same operation as an `addr as ptr` cast, but copies

//!     /// the *provenance* of `self` to the new pointer.

//!     /// This allows us to dynamically preserve and propagate this important

//!     /// information in a way that is otherwise impossible with a unary cast.

//!     ///

//!     /// This is equivalent to using `wrapping_offset` to offset `self` to the

//!     /// given address, and therefore has all the same capabilities and restrictions.

//!     pub fn with_addr(self, addr: usize) -> Self;

//! ```

//!

//! So you're still able to drop down to the address representation and do whatever

//! clever bit tricks you want *as long as* you're able to keep around a pointer

//! into the allocation you care about that can "reconstitute" the provenance.

//! Usually this is very easy, because you only are taking a pointer, messing with the address,

//! and then immediately converting back to a pointer. To make this use case more ergonomic,

//! we provide the [`map_addr`] method.

//!

//! To help make it clear that code is "following" Strict Provenance semantics, we also provide an

//! [`addr`] method which promises that the returned address is not part of a

//! pointer-integer-pointer roundtrip. In the future we may provide a lint for pointer<->integer

//! casts to help you audit if your code conforms to strict provenance.

//!

//! ### Using Strict Provenance

//!

//! Most code needs no changes to conform to strict provenance, as the only really concerning

//! operation is casts from `usize` to a pointer. For code which *does* cast a `usize` to a pointer,

//! the scope of the change depends on exactly what you're doing.

//!

//! In general, you just need to make sure that if you want to convert a `usize` address to a

//! pointer and then use that pointer to read/write memory, you need to keep around a pointer

//! that has sufficient provenance to perform that read/write itself. In this way all of your

//! casts from an address to a pointer are essentially just applying offsets/indexing.

//!

//! This is generally trivial to do for simple cases like tagged pointers *as long as you

//! represent the tagged pointer as an actual pointer and not a `usize`*. For instance:

//!

//! ```

//! unsafe {

//!     // A flag we want to pack into our pointer

//!     static HAS_DATA: usize = 0x1;

//!     static FLAG_MASK: usize = !HAS_DATA;

//!

//!     // Our value, which must have enough alignment to have spare least-significant-bits.

//!     let my_precious_data: u32 = 17;

//!     assert!(align_of::<u32>() > 1);

//!

//!     // Create a tagged pointer

//!     let ptr = &my_precious_data as *const u32;

//!     let tagged = ptr.map_addr(|addr| addr | HAS_DATA);

//!

//!     // Check the flag:

//!     if tagged.addr() & HAS_DATA != 0 {

//!         // Untag and read the pointer

//!         let data = *tagged.map_addr(|addr| addr & FLAG_MASK);

//!         assert_eq!(data, 17);

//!     } else {

//!         unreachable!()

//!     }

//! }

//! ```

//!

//! (Yes, if you've been using [`AtomicUsize`] for pointers in concurrent datastructures, you should

//! be using [`AtomicPtr`] instead. If that messes up the way you atomically manipulate pointers,

//! we would like to know why, and what needs to be done to fix it.)

//!

//! Situations where a valid pointer *must* be created from just an address, such as baremetal code

//! accessing a memory-mapped interface at a fixed address, cannot currently be handled with strict

//! provenance APIs and should use [exposed provenance](#exposed-provenance).

//!

//! ## Exposed Provenance

//!

//! As discussed above, integer-to-pointer casts are not possible with Strict Provenance APIs.

//! This is by design: the goal of Strict Provenance is to provide a clear specification that we are

//! confident can be formalized unambiguously and can be subject to precise formal reasoning.

//! Integer-to-pointer casts do not (currently) have such a clear specification.

//!

//! However, there exist situations where integer-to-pointer casts cannot be avoided, or

//! where avoiding them would require major refactoring. Legacy platform APIs also regularly assume

//! that `usize` can capture all the information that makes up a pointer.

//! Bare-metal platforms can also require the synthesis of a pointer "out of thin air" without

//! anywhere to obtain proper provenance from.

//!

//! Rust's model for dealing with integer-to-pointer casts is called *Exposed Provenance*. However,

//! the semantics of Exposed Provenance are on much less solid footing than Strict Provenance, and

//! at this point it is not yet clear whether a satisfying unambiguous semantics can be defined for

//! Exposed Provenance. (If that sounds bad, be reassured that other popular languages that provide

//! integer-to-pointer casts are not faring any better.) Furthermore, Exposed Provenance will not

//! work (well) with tools like [Miri] and [CHERI].

//!

//! Exposed Provenance is provided by the [`expose_provenance`] and [`with_exposed_provenance`] methods,

//! which are equivalent to `as` casts between pointers and integers.

//! - [`expose_provenance`] is a lot like [`addr`], but additionally adds the provenance of the

//!   pointer to a global list of 'exposed' provenances. (This list is purely conceptual, it exists

//!   for the purpose of specifying Rust but is not materialized in actual executions, except in

//!   tools like [Miri].)

//!   Memory which is outside the control of the Rust abstract machine (MMIO registers, for example)

//!   is always considered to be exposed, so long as this memory is disjoint from memory that will

//!   be used by the abstract machine such as the stack, heap, and statics.

//! - [`with_exposed_provenance`] can be used to construct a pointer with one of these previously

//!   'exposed' provenances. [`with_exposed_provenance`] takes only `addr: usize` as arguments, so

//!   unlike in [`with_addr`] there is no indication of what the correct provenance for the returned

//!   pointer is -- and that is exactly what makes integer-to-pointer casts so tricky to rigorously

//!   specify! The compiler will do its best to pick the right provenance for you, but currently we

//!   cannot provide any guarantees about which provenance the resulting pointer will have. Only one

//!   thing is clear: if there is *no* previously 'exposed' provenance that justifies the way the

//!   returned pointer will be used, the program has undefined behavior.

//!

//! If at all possible, we encourage code to be ported to [Strict Provenance] APIs, thus avoiding

//! the need for Exposed Provenance. Maximizing the amount of such code is a major win for avoiding

//! specification complexity and to facilitate adoption of tools like [CHERI] and [Miri] that can be

//! a big help in increasing the confidence in (unsafe) Rust code. However, we acknowledge that this

//! is not always possible, and offer Exposed Provenance as a way to explicit "opt out" of the

//! well-defined semantics of Strict Provenance, and "opt in" to the unclear semantics of

//! integer-to-pointer casts.

//!

//! [aliasing]: ../../nomicon/aliasing.html

//! [allocation]: #allocation

//! [provenance]: #provenance

//! [book]: ../../book/ch19-01-unsafe-rust.html#dereferencing-a-raw-pointer

//! [ub]: ../../reference/behavior-considered-undefined.html

//! [zst]: ../../nomicon/exotic-sizes.html#zero-sized-types-zsts

//! [atomic operations]: crate::sync::atomic

//! [`offset`]: pointer::offset

//! [`offset_from`]: pointer::offset_from

//! [`wrapping_offset`]: pointer::wrapping_offset

//! [`with_addr`]: pointer::with_addr

//! [`map_addr`]: pointer::map_addr

//! [`addr`]: pointer::addr

//! [`AtomicUsize`]: crate::sync::atomic::AtomicUsize

//! [`AtomicPtr`]: crate::sync::atomic::AtomicPtr

//! [`expose_provenance`]: pointer::expose_provenance

//! [`with_exposed_provenance`]: with_exposed_provenance

//! [Miri]: https://github.com/rust-lang/miri

//! [CHERI]: https://www.cl.cam.ac.uk/research/security/ctsrd/cheri/

//! [Strict Provenance]: #strict-provenance

//! [`UnsafeCell`]: core::cell::UnsafeCell

#![stable(feature = "rust1", since = "1.0.0")]

// There are many unsafe functions taking pointers that don't dereference them.

#![allow(clippy::not_unsafe_ptr_arg_deref)]

#[cfg(not(feature = "ferrocene_certified"))]

use crate::cmp::Ordering;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::intrinsics::const_eval_select;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::marker::{FnPtr, PointeeSized};

#[cfg(not(feature = "ferrocene_certified"))]

use crate::mem::{self, MaybeUninit, SizedTypeProperties};

#[cfg(not(feature = "ferrocene_certified"))]

use crate::num::NonZero;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::{fmt, hash, intrinsics, ub_checks};

#[cfg(feature = "ferrocene_certified")]

use crate::{intrinsics, marker::PointeeSized, mem};

#[cfg(all(debug_assertions, feature = "ferrocene_certified"))]

use crate::{mem::SizedTypeProperties, ub_checks};

mod alignment;

#[unstable(feature = "ptr_alignment_type", issue = "102070")]

pub use alignment::Alignment;

mod metadata;

#[unstable(feature = "ptr_metadata", issue = "81513")]

#[cfg(not(feature = "ferrocene_certified"))]

pub use metadata::{DynMetadata, Pointee, Thin, from_raw_parts, from_raw_parts_mut, metadata};

#[unstable(feature = "ptr_metadata", issue = "81513")]

#[cfg(feature = "ferrocene_certified")]

pub use metadata::{Pointee, Thin, from_raw_parts, from_raw_parts_mut};

mod non_null;

#[stable(feature = "nonnull", since = "1.25.0")]

pub use non_null::NonNull;

#[cfg(not(feature = "ferrocene_certified"))]

mod unique;

#[unstable(feature = "ptr_internals", issue = "none")]

#[cfg(not(feature = "ferrocene_certified"))]

pub use unique::Unique;

mod const_ptr;

mod mut_ptr;

// Some functions are defined here because they accidentally got made

// available in this module on stable. See <https://github.com/rust-lang/rust/issues/15702>.

// (`transmute` also falls into this category, but it cannot be wrapped due to the

// check that `T` and `U` have the same size.)

/// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source

/// and destination must *not* overlap.

///

/// For regions of memory which might overlap, use [`copy`] instead.

///

/// `copy_nonoverlapping` is semantically equivalent to C's [`memcpy`], but

/// with the source and destination arguments swapped,

/// and `count` counting the number of `T`s instead of bytes.

///

/// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the

/// requirements of `T`. The initialization state is preserved exactly.

///

/// [`memcpy`]: https://en.cppreference.com/w/c/string/byte/memcpy

///

/// # Safety

///

/// Behavior is undefined if any of the following conditions are violated:

///

/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.

///

/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.

///

/// * Both `src` and `dst` must be properly aligned.

///

/// * The region of memory beginning at `src` with a size of `count *

///   size_of::<T>()` bytes must *not* overlap with the region of memory

///   beginning at `dst` with the same size.

///

/// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of

/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values

/// in the region beginning at `*src` and the region beginning at `*dst` can

/// [violate memory safety][read-ownership].

///

/// Note that even if the effectively copied size (`count * size_of::<T>()`) is

/// `0`, the pointers must be properly aligned.

///

/// [`read`]: crate::ptr::read

/// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value

/// [valid]: crate::ptr#safety

///

/// # Examples

///

/// Manually implement [`Vec::append`]:

///

/// ```

/// use std::ptr;

///

/// /// Moves all the elements of `src` into `dst`, leaving `src` empty.

/// fn append<T>(dst: &mut Vec<T>, src: &mut Vec<T>) {

///     let src_len = src.len();

///     let dst_len = dst.len();

///

///     // Ensure that `dst` has enough capacity to hold all of `src`.

///     dst.reserve(src_len);

///

///     unsafe {

///         // The call to add is always safe because `Vec` will never

///         // allocate more than `isize::MAX` bytes.

///         let dst_ptr = dst.as_mut_ptr().add(dst_len);

///         let src_ptr = src.as_ptr();

///

///         // Truncate `src` without dropping its contents. We do this first,

///         // to avoid problems in case something further down panics.

///         src.set_len(0);

///

///         // The two regions cannot overlap because mutable references do

///         // not alias, and two different vectors cannot own the same

///         // memory.

///         ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len);

///

///         // Notify `dst` that it now holds the contents of `src`.

///         dst.set_len(dst_len + src_len);

///     }

/// }

///

/// let mut a = vec!['r'];

/// let mut b = vec!['u', 's', 't'];

///

/// append(&mut a, &mut b);

///

/// assert_eq!(a, &['r', 'u', 's', 't']);

/// assert!(b.is_empty());

/// ```

///

/// [`Vec::append`]: ../../std/vec/struct.Vec.html#method.append

#[doc(alias = "memcpy")]

#[stable(feature = "rust1", since = "1.0.0")]

#[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]

#[inline(always)]

#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

#[rustc_diagnostic_item = "ptr_copy_nonoverlapping"]

#[cfg(not(feature = "ferrocene_certified"))]

pub const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize) {

    ub_checks::assert_unsafe_precondition!(

        check_language_ub,

        "ptr::copy_nonoverlapping requires that both pointer arguments are aligned and non-null \

        and the specified memory ranges do not overlap",

        (

            src: *const () = src as *const (),

            dst: *mut () = dst as *mut (),

            size: usize = size_of::<T>(),

            align: usize = align_of::<T>(),

            count: usize = count,

        ) => {

            let zero_size = count == 0 || size == 0;

            ub_checks::maybe_is_aligned_and_not_null(src, align, zero_size)

                && ub_checks::maybe_is_aligned_and_not_null(dst, align, zero_size)

                && ub_checks::maybe_is_nonoverlapping(src, dst, size, count)

        }

    );

    // SAFETY: the safety contract for `copy_nonoverlapping` must be

    // upheld by the caller.

    unsafe { crate::intrinsics::copy_nonoverlapping(src, dst, count) }

}

/// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source

/// and destination may overlap.

///

/// If the source and destination will *never* overlap,

/// [`copy_nonoverlapping`] can be used instead.

///

/// `copy` is semantically equivalent to C's [`memmove`], but

/// with the source and destination arguments swapped,

/// and `count` counting the number of `T`s instead of bytes.

/// Copying takes place as if the bytes were copied from `src`

/// to a temporary array and then copied from the array to `dst`.

///

/// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the

/// requirements of `T`. The initialization state is preserved exactly.

///

/// [`memmove`]: https://en.cppreference.com/w/c/string/byte/memmove

///

/// # Safety

///

/// Behavior is undefined if any of the following conditions are violated:

///

/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.

///

/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes, and must remain valid even

///   when `src` is read for `count * size_of::<T>()` bytes. (This means if the memory ranges

///   overlap, the `dst` pointer must not be invalidated by `src` reads.)

///

/// * Both `src` and `dst` must be properly aligned.

///

/// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of

/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values

/// in the region beginning at `*src` and the region beginning at `*dst` can

/// [violate memory safety][read-ownership].

///

/// Note that even if the effectively copied size (`count * size_of::<T>()`) is

/// `0`, the pointers must be properly aligned.

///

/// [`read`]: crate::ptr::read

/// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value

/// [valid]: crate::ptr#safety

///

/// # Examples

///

/// Efficiently create a Rust vector from an unsafe buffer:

///

/// ```

/// use std::ptr;

///

/// /// # Safety

/// ///

/// /// * `ptr` must be correctly aligned for its type and non-zero.

/// /// * `ptr` must be valid for reads of `elts` contiguous elements of type `T`.

/// /// * Those elements must not be used after calling this function unless `T: Copy`.

/// # #[allow(dead_code)]

/// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {

///     let mut dst = Vec::with_capacity(elts);

///

///     // SAFETY: Our precondition ensures the source is aligned and valid,

///     // and `Vec::with_capacity` ensures that we have usable space to write them.

///     unsafe { ptr::copy(ptr, dst.as_mut_ptr(), elts); }

///

///     // SAFETY: We created it with this much capacity earlier,

///     // and the previous `copy` has initialized these elements.

///     unsafe { dst.set_len(elts); }

///     dst

/// }

/// ```

#[doc(alias = "memmove")]

#[stable(feature = "rust1", since = "1.0.0")]

#[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]

#[inline(always)]

#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

#[rustc_diagnostic_item = "ptr_copy"]

#[cfg(not(feature = "ferrocene_certified"))]

pub const unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize) {

    // SAFETY: the safety contract for `copy` must be upheld by the caller.

    unsafe {

        ub_checks::assert_unsafe_precondition!(

            check_language_ub,

            "ptr::copy requires that both pointer arguments are aligned and non-null",

            (

                src: *const () = src as *const (),

                dst: *mut () = dst as *mut (),

                align: usize = align_of::<T>(),

                zero_size: bool = T::IS_ZST || count == 0,

            ) =>

            ub_checks::maybe_is_aligned_and_not_null(src, align, zero_size)

                && ub_checks::maybe_is_aligned_and_not_null(dst, align, zero_size)

        );

        crate::intrinsics::copy(src, dst, count)

    }

}

/// Sets `count * size_of::<T>()` bytes of memory starting at `dst` to

/// `val`.

///

/// `write_bytes` is similar to C's [`memset`], but sets `count *

/// size_of::<T>()` bytes to `val`.

///

/// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset

///

/// # Safety

///

/// Behavior is undefined if any of the following conditions are violated:

///

/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.

///

/// * `dst` must be properly aligned.

///

/// Note that even if the effectively copied size (`count * size_of::<T>()`) is

/// `0`, the pointer must be properly aligned.

///

/// Additionally, note that changing `*dst` in this way can easily lead to undefined behavior (UB)

/// later if the written bytes are not a valid representation of some `T`. For instance, the

/// following is an **incorrect** use of this function:

///

/// ```rust,no_run

/// unsafe {

///     let mut value: u8 = 0;

///     let ptr: *mut bool = &mut value as *mut u8 as *mut bool;

///     let _bool = ptr.read(); // This is fine, `ptr` points to a valid `bool`.

///     ptr.write_bytes(42u8, 1); // This function itself does not cause UB...

///     let _bool = ptr.read(); // ...but it makes this operation UB! ⚠️

/// }

/// ```

///

/// [valid]: crate::ptr#safety

///

/// # Examples

///

/// Basic usage:

///

/// ```

/// use std::ptr;

///

/// let mut vec = vec![0u32; 4];

/// unsafe {

///     let vec_ptr = vec.as_mut_ptr();

///     ptr::write_bytes(vec_ptr, 0xfe, 2);

/// }

/// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]);

/// ```

#[doc(alias = "memset")]

#[stable(feature = "rust1", since = "1.0.0")]

#[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]

#[inline(always)]

#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

#[rustc_diagnostic_item = "ptr_write_bytes"]

#[cfg(not(feature = "ferrocene_certified"))]

pub const unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize) {

    // SAFETY: the safety contract for `write_bytes` must be upheld by the caller.

    unsafe {

        ub_checks::assert_unsafe_precondition!(

            check_language_ub,

            "ptr::write_bytes requires that the destination pointer is aligned and non-null",

            (

                addr: *const () = dst as *const (),

                align: usize = align_of::<T>(),

                zero_size: bool = T::IS_ZST || count == 0,

            ) => ub_checks::maybe_is_aligned_and_not_null(addr, align, zero_size)

        );

        crate::intrinsics::write_bytes(dst, val, count)

    }

}

/// Executes the destructor (if any) of the pointed-to value.

///

/// This is almost the same as calling [`ptr::read`] and discarding

/// the result, but has the following advantages:

// FIXME: say something more useful than "almost the same"?

// There are open questions here: `read` requires the value to be fully valid, e.g. if `T` is a

// `bool` it must be 0 or 1, if it is a reference then it must be dereferenceable. `drop_in_place`

// only requires that `*to_drop` be "valid for dropping" and we have not defined what that means. In

// Miri it currently (May 2024) requires nothing at all for types without drop glue.

///

/// * It is *required* to use `drop_in_place` to drop unsized types like

///   trait objects, because they can't be read out onto the stack and

///   dropped normally.

///

/// * It is friendlier to the optimizer to do this over [`ptr::read`] when

///   dropping manually allocated memory (e.g., in the implementations of

///   `Box`/`Rc`/`Vec`), as the compiler doesn't need to prove that it's

///   sound to elide the copy.

///

/// * It can be used to drop [pinned] data when `T` is not `repr(packed)`

///   (pinned data must not be moved before it is dropped).

///

/// Unaligned values cannot be dropped in place, they must be copied to an aligned

/// location first using [`ptr::read_unaligned`]. For packed structs, this move is

/// done automatically by the compiler. This means the fields of packed structs

/// are not dropped in-place.

///

/// [`ptr::read`]: self::read

/// [`ptr::read_unaligned`]: self::read_unaligned

/// [pinned]: crate::pin

///

/// # Safety

///

/// Behavior is undefined if any of the following conditions are violated:

///

/// * `to_drop` must be [valid] for both reads and writes.

///

/// * `to_drop` must be properly aligned, even if `T` has size 0.

///

/// * `to_drop` must be nonnull, even if `T` has size 0.

///

/// * The value `to_drop` points to must be valid for dropping, which may mean

///   it must uphold additional invariants. These invariants depend on the type

///   of the value being dropped. For instance, when dropping a Box, the box's

///   pointer to the heap must be valid.

///

/// * While `drop_in_place` is executing, the only way to access parts of

///   `to_drop` is through the `&mut self` references supplied to the

///   `Drop::drop` methods that `drop_in_place` invokes.

///

/// Additionally, if `T` is not [`Copy`], using the pointed-to value after

/// calling `drop_in_place` can cause undefined behavior. Note that `*to_drop =

/// foo` counts as a use because it will cause the value to be dropped

/// again. [`write()`] can be used to overwrite data without causing it to be

/// dropped.

///

/// [valid]: self#safety

///

/// # Examples

///

/// Manually remove the last item from a vector:

///

/// ```

/// use std::ptr;

/// use std::rc::Rc;

///

/// let last = Rc::new(1);

/// let weak = Rc::downgrade(&last);

///

/// let mut v = vec![Rc::new(0), last];

///

/// unsafe {

///     // Get a raw pointer to the last element in `v`.

///     let ptr = &mut v[1] as *mut _;

///     // Shorten `v` to prevent the last item from being dropped. We do that first,

///     // to prevent issues if the `drop_in_place` below panics.

///     v.set_len(1);

///     // Without a call `drop_in_place`, the last item would never be dropped,

///     // and the memory it manages would be leaked.

///     ptr::drop_in_place(ptr);

/// }

///

/// assert_eq!(v, &[0.into()]);

///

/// // Ensure that the last item was dropped.

/// assert!(weak.upgrade().is_none());

/// ```

#[stable(feature = "drop_in_place", since = "1.8.0")]

#[lang = "drop_in_place"]

#[allow(unconditional_recursion)]

#[rustc_diagnostic_item = "ptr_drop_in_place"]

#[cfg(not(feature = "ferrocene_certified"))]

pub unsafe fn drop_in_place<T: PointeeSized>(to_drop: *mut T) {

    // Code here does not matter - this is replaced by the

    // real drop glue by the compiler.

    // SAFETY: see comment above

    unsafe { drop_in_place(to_drop) }

}

/// Creates a null raw pointer.

///

/// This function is equivalent to zero-initializing the pointer:

/// `MaybeUninit::<*const T>::zeroed().assume_init()`.

/// The resulting pointer has the address 0.

///

/// # Examples

///

/// ```

/// use std::ptr;

///

/// let p: *const i32 = ptr::null();

/// assert!(p.is_null());

/// assert_eq!(p as usize, 0); // this pointer has the address 0

/// ```

#[inline(always)]

#[must_use]

#[stable(feature = "rust1", since = "1.0.0")]

#[rustc_promotable]

#[rustc_const_stable(feature = "const_ptr_null", since = "1.24.0")]

#[rustc_diagnostic_item = "ptr_null"]

/// Creates a null mutable raw pointer.

///

/// This function is equivalent to zero-initializing the pointer:

/// `MaybeUninit::<*mut T>::zeroed().assume_init()`.

/// The resulting pointer has the address 0.

///

/// # Examples

///

/// ```

/// use std::ptr;

///

/// let p: *mut i32 = ptr::null_mut();

/// assert!(p.is_null());

/// assert_eq!(p as usize, 0); // this pointer has the address 0

/// ```

#[inline(always)]

#[must_use]

#[stable(feature = "rust1", since = "1.0.0")]

#[rustc_promotable]

#[rustc_const_stable(feature = "const_ptr_null", since = "1.24.0")]

#[rustc_diagnostic_item = "ptr_null_mut"]

/// Creates a pointer with the given address and no [provenance][crate::ptr#provenance].

///

/// This is equivalent to `ptr::null().with_addr(addr)`.

///

/// Without provenance, this pointer is not associated with any actual allocation. Such a

/// no-provenance pointer may be used for zero-sized memory accesses (if suitably aligned), but

/// non-zero-sized memory accesses with a no-provenance pointer are UB. No-provenance pointers are

/// little more than a `usize` address in disguise.

///

/// This is different from `addr as *const T`, which creates a pointer that picks up a previously

/// exposed provenance. See [`with_exposed_provenance`] for more details on that operation.

///

/// This is a [Strict Provenance][crate::ptr#strict-provenance] API.

#[inline(always)]

#[must_use]

#[stable(feature = "strict_provenance", since = "1.84.0")]

#[rustc_const_stable(feature = "strict_provenance", since = "1.84.0")]

/// Creates a new pointer that is dangling, but non-null and well-aligned.

///

/// This is useful for initializing types which lazily allocate, like

/// `Vec::new` does.

///

/// Note that the address of the returned pointer may potentially

/// be that of a valid pointer, which means this must not be used

/// as a "not yet initialized" sentinel value.

/// Types that lazily allocate must track initialization by some other means.

#[inline(always)]

#[must_use]

#[stable(feature = "strict_provenance", since = "1.84.0")]

#[rustc_const_stable(feature = "strict_provenance", since = "1.84.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub const fn dangling<T>() -> *const T {

    dangling_mut()

}

/// Creates a pointer with the given address and no [provenance][crate::ptr#provenance].

///

/// This is equivalent to `ptr::null_mut().with_addr(addr)`.

///

/// Without provenance, this pointer is not associated with any actual allocation. Such a

/// no-provenance pointer may be used for zero-sized memory accesses (if suitably aligned), but

/// non-zero-sized memory accesses with a no-provenance pointer are UB. No-provenance pointers are

/// little more than a `usize` address in disguise.

///

/// This is different from `addr as *mut T`, which creates a pointer that picks up a previously

/// exposed provenance. See [`with_exposed_provenance_mut`] for more details on that operation.

///

/// This is a [Strict Provenance][crate::ptr#strict-provenance] API.

#[inline(always)]

#[must_use]

#[stable(feature = "strict_provenance", since = "1.84.0")]

#[rustc_const_stable(feature = "strict_provenance", since = "1.84.0")]

#[allow(integer_to_ptr_transmutes)] // Expected semantics here.

    // An int-to-pointer transmute currently has exactly the intended semantics: it creates a

    // pointer without provenance. Note that this is *not* a stable guarantee about transmute

    // semantics, it relies on sysroot crates having special status.

    // SAFETY: every valid integer is also a valid pointer (as long as you don't dereference that

    // pointer).

/// Creates a new pointer that is dangling, but non-null and well-aligned.

///

/// This is useful for initializing types which lazily allocate, like

/// `Vec::new` does.

///

/// Note that the address of the returned pointer may potentially

/// be that of a valid pointer, which means this must not be used

/// as a "not yet initialized" sentinel value.

/// Types that lazily allocate must track initialization by some other means.

#[inline(always)]

#[must_use]

#[stable(feature = "strict_provenance", since = "1.84.0")]

#[rustc_const_stable(feature = "strict_provenance", since = "1.84.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub const fn dangling_mut<T>() -> *mut T {

    NonNull::dangling().as_ptr()

}

/// Converts an address back to a pointer, picking up some previously 'exposed'

/// [provenance][crate::ptr#provenance].

///

/// This is fully equivalent to `addr as *const T`. The provenance of the returned pointer is that

/// of *some* pointer that was previously exposed by passing it to

/// [`expose_provenance`][pointer::expose_provenance], or a `ptr as usize` cast. In addition, memory

/// which is outside the control of the Rust abstract machine (MMIO registers, for example) is

/// always considered to be accessible with an exposed provenance, so long as this memory is disjoint

/// from memory that will be used by the abstract machine such as the stack, heap, and statics.

///

/// The exact provenance that gets picked is not specified. The compiler will do its best to pick

/// the "right" provenance for you (whatever that may be), but currently we cannot provide any

/// guarantees about which provenance the resulting pointer will have -- and therefore there

/// is no definite specification for which memory the resulting pointer may access.

///

/// If there is *no* previously 'exposed' provenance that justifies the way the returned pointer

/// will be used, the program has undefined behavior. In particular, the aliasing rules still apply:

/// pointers and references that have been invalidated due to aliasing accesses cannot be used

/// anymore, even if they have been exposed!

///

/// Due to its inherent ambiguity, this operation may not be supported by tools that help you to

/// stay conformant with the Rust memory model. It is recommended to use [Strict

/// Provenance][self#strict-provenance] APIs such as [`with_addr`][pointer::with_addr] wherever

/// possible.

///

/// On most platforms this will produce a value with the same bytes as the address. Platforms

/// which need to store additional information in a pointer may not support this operation,

/// since it is generally not possible to actually *compute* which provenance the returned

/// pointer has to pick up.

///

/// This is an [Exposed Provenance][crate::ptr#exposed-provenance] API.

#[must_use]

#[inline(always)]

#[stable(feature = "exposed_provenance", since = "1.84.0")]

#[rustc_const_stable(feature = "const_exposed_provenance", since = "CURRENT_RUSTC_VERSION")]

#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

#[allow(fuzzy_provenance_casts)] // this *is* the explicit provenance API one should use instead

#[cfg(not(feature = "ferrocene_certified"))]

pub const fn with_exposed_provenance<T>(addr: usize) -> *const T {

    addr as *const T

}

/// Converts an address back to a mutable pointer, picking up some previously 'exposed'

/// [provenance][crate::ptr#provenance].

///

/// This is fully equivalent to `addr as *mut T`. The provenance of the returned pointer is that

/// of *some* pointer that was previously exposed by passing it to

/// [`expose_provenance`][pointer::expose_provenance], or a `ptr as usize` cast. In addition, memory

/// which is outside the control of the Rust abstract machine (MMIO registers, for example) is

/// always considered to be accessible with an exposed provenance, so long as this memory is disjoint

/// from memory that will be used by the abstract machine such as the stack, heap, and statics.

///

/// The exact provenance that gets picked is not specified. The compiler will do its best to pick

/// the "right" provenance for you (whatever that may be), but currently we cannot provide any

/// guarantees about which provenance the resulting pointer will have -- and therefore there

/// is no definite specification for which memory the resulting pointer may access.

///

/// If there is *no* previously 'exposed' provenance that justifies the way the returned pointer

/// will be used, the program has undefined behavior. In particular, the aliasing rules still apply:

/// pointers and references that have been invalidated due to aliasing accesses cannot be used

/// anymore, even if they have been exposed!

///

/// Due to its inherent ambiguity, this operation may not be supported by tools that help you to

/// stay conformant with the Rust memory model. It is recommended to use [Strict

/// Provenance][self#strict-provenance] APIs such as [`with_addr`][pointer::with_addr] wherever

/// possible.

///

/// On most platforms this will produce a value with the same bytes as the address. Platforms

/// which need to store additional information in a pointer may not support this operation,

/// since it is generally not possible to actually *compute* which provenance the returned

/// pointer has to pick up.

///

/// This is an [Exposed Provenance][crate::ptr#exposed-provenance] API.

#[must_use]

#[inline(always)]

#[stable(feature = "exposed_provenance", since = "1.84.0")]

#[rustc_const_stable(feature = "const_exposed_provenance", since = "CURRENT_RUSTC_VERSION")]

#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

#[allow(fuzzy_provenance_casts)] // this *is* the explicit provenance API one should use instead

#[cfg(not(feature = "ferrocene_certified"))]

pub const fn with_exposed_provenance_mut<T>(addr: usize) -> *mut T {

    addr as *mut T

}

/// Converts a reference to a raw pointer.

///

/// For `r: &T`, `from_ref(r)` is equivalent to `r as *const T` (except for the caveat noted below),

/// but is a bit safer since it will never silently change type or mutability, in particular if the

/// code is refactored.

///

/// The caller must ensure that the pointee outlives the pointer this function returns, or else it

/// will end up dangling.

///

/// The caller must also ensure that the memory the pointer (non-transitively) points to is never

/// written to (except inside an `UnsafeCell`) using this pointer or any pointer derived from it. If

/// you need to mutate the pointee, use [`from_mut`]. Specifically, to turn a mutable reference `m:

/// &mut T` into `*const T`, prefer `from_mut(m).cast_const()` to obtain a pointer that can later be

/// used for mutation.

///

/// ## Interaction with lifetime extension

///

/// Note that this has subtle interactions with the rules for lifetime extension of temporaries in

/// tail expressions. This code is valid, albeit in a non-obvious way:

/// ```rust

/// # type T = i32;

/// # fn foo() -> T { 42 }

/// // The temporary holding the return value of `foo` has its lifetime extended,

/// // because the surrounding expression involves no function call.

/// let p = &foo() as *const T;

/// unsafe { p.read() };

/// ```

/// Naively replacing the cast with `from_ref` is not valid:

/// ```rust,no_run

/// # use std::ptr;

/// # type T = i32;

/// # fn foo() -> T { 42 }

/// // The temporary holding the return value of `foo` does *not* have its lifetime extended,

/// // because the surrounding expression involves a function call.

/// let p = ptr::from_ref(&foo());

/// unsafe { p.read() }; // UB! Reading from a dangling pointer ⚠️

/// ```

/// The recommended way to write this code is to avoid relying on lifetime extension

/// when raw pointers are involved:

/// ```rust

/// # use std::ptr;

/// # type T = i32;

/// # fn foo() -> T { 42 }

/// let x = foo();

/// let p = ptr::from_ref(&x);

/// unsafe { p.read() };

/// ```

#[inline(always)]

#[must_use]

#[stable(feature = "ptr_from_ref", since = "1.76.0")]

#[rustc_const_stable(feature = "ptr_from_ref", since = "1.76.0")]

#[rustc_never_returns_null_ptr]

#[rustc_diagnostic_item = "ptr_from_ref"]

#[cfg(not(feature = "ferrocene_certified"))]

pub const fn from_ref<T: PointeeSized>(r: &T) -> *const T {

    r

}

/// Converts a mutable reference to a raw pointer.

///

/// For `r: &mut T`, `from_mut(r)` is equivalent to `r as *mut T` (except for the caveat noted

/// below), but is a bit safer since it will never silently change type or mutability, in particular

/// if the code is refactored.

///

/// The caller must ensure that the pointee outlives the pointer this function returns, or else it

/// will end up dangling.

///

/// ## Interaction with lifetime extension

///

/// Note that this has subtle interactions with the rules for lifetime extension of temporaries in

/// tail expressions. This code is valid, albeit in a non-obvious way:

/// ```rust

/// # type T = i32;

/// # fn foo() -> T { 42 }

/// // The temporary holding the return value of `foo` has its lifetime extended,

/// // because the surrounding expression involves no function call.

/// let p = &mut foo() as *mut T;

/// unsafe { p.write(T::default()) };

/// ```

/// Naively replacing the cast with `from_mut` is not valid:

/// ```rust,no_run

/// # use std::ptr;

/// # type T = i32;

/// # fn foo() -> T { 42 }

/// // The temporary holding the return value of `foo` does *not* have its lifetime extended,

/// // because the surrounding expression involves a function call.

/// let p = ptr::from_mut(&mut foo());

/// unsafe { p.write(T::default()) }; // UB! Writing to a dangling pointer ⚠️

/// ```

/// The recommended way to write this code is to avoid relying on lifetime extension

/// when raw pointers are involved:

/// ```rust

/// # use std::ptr;

/// # type T = i32;

/// # fn foo() -> T { 42 }

/// let mut x = foo();

/// let p = ptr::from_mut(&mut x);

/// unsafe { p.write(T::default()) };

/// ```

#[inline(always)]

#[must_use]

#[stable(feature = "ptr_from_ref", since = "1.76.0")]

#[rustc_const_stable(feature = "ptr_from_ref", since = "1.76.0")]

#[rustc_never_returns_null_ptr]

#[cfg(not(feature = "ferrocene_certified"))]

pub const fn from_mut<T: PointeeSized>(r: &mut T) -> *mut T {

    r

}

/// Forms a raw slice from a pointer and a length.

///

/// The `len` argument is the number of **elements**, not the number of bytes.

///

/// This function is safe, but actually using the return value is unsafe.

/// See the documentation of [`slice::from_raw_parts`] for slice safety requirements.

///

/// [`slice::from_raw_parts`]: crate::slice::from_raw_parts

///

/// # Examples

///

/// ```rust

/// use std::ptr;

///

/// // create a slice pointer when starting out with a pointer to the first element

/// let x = [5, 6, 7];

/// let raw_pointer = x.as_ptr();

/// let slice = ptr::slice_from_raw_parts(raw_pointer, 3);

/// assert_eq!(unsafe { &*slice }[2], 7);

/// ```

///

/// You must ensure that the pointer is valid and not null before dereferencing

/// the raw slice. A slice reference must never have a null pointer, even if it's empty.

///

/// ```rust,should_panic

/// use std::ptr;

/// let danger: *const [u8] = ptr::slice_from_raw_parts(ptr::null(), 0);

/// unsafe {

///     danger.as_ref().expect("references must not be null");

/// }

/// ```

#[inline]

#[stable(feature = "slice_from_raw_parts", since = "1.42.0")]

#[rustc_const_stable(feature = "const_slice_from_raw_parts", since = "1.64.0")]

#[rustc_diagnostic_item = "ptr_slice_from_raw_parts"]

#[cfg(not(feature = "ferrocene_certified"))]

pub const fn slice_from_raw_parts<T>(data: *const T, len: usize) -> *const [T] {

    from_raw_parts(data, len)

}

/// Forms a raw mutable slice from a pointer and a length.

///

/// The `len` argument is the number of **elements**, not the number of bytes.

///

/// Performs the same functionality as [`slice_from_raw_parts`], except that a

/// raw mutable slice is returned, as opposed to a raw immutable slice.

///

/// This function is safe, but actually using the return value is unsafe.

/// See the documentation of [`slice::from_raw_parts_mut`] for slice safety requirements.

///

/// [`slice::from_raw_parts_mut`]: crate::slice::from_raw_parts_mut

///

/// # Examples

///

/// ```rust

/// use std::ptr;

///

/// let x = &mut [5, 6, 7];

/// let raw_pointer = x.as_mut_ptr();

/// let slice = ptr::slice_from_raw_parts_mut(raw_pointer, 3);

///

/// unsafe {

///     (*slice)[2] = 99; // assign a value at an index in the slice

/// };

///

/// assert_eq!(unsafe { &*slice }[2], 99);

/// ```

///

/// You must ensure that the pointer is valid and not null before dereferencing

/// the raw slice. A slice reference must never have a null pointer, even if it's empty.

///

/// ```rust,should_panic

/// use std::ptr;

/// let danger: *mut [u8] = ptr::slice_from_raw_parts_mut(ptr::null_mut(), 0);

/// unsafe {

///     danger.as_mut().expect("references must not be null");

/// }

/// ```

#[inline]

#[stable(feature = "slice_from_raw_parts", since = "1.42.0")]

#[rustc_const_stable(feature = "const_slice_from_raw_parts_mut", since = "1.83.0")]

#[rustc_diagnostic_item = "ptr_slice_from_raw_parts_mut"]

#[cfg(not(feature = "ferrocene_certified"))]

pub const fn slice_from_raw_parts_mut<T>(data: *mut T, len: usize) -> *mut [T] {

    from_raw_parts_mut(data, len)

}

/// Swaps the values at two mutable locations of the same type, without

/// deinitializing either.

///

/// But for the following exceptions, this function is semantically

/// equivalent to [`mem::swap`]:

///

/// * It operates on raw pointers instead of references. When references are

///   available, [`mem::swap`] should be preferred.

///

/// * The two pointed-to values may overlap. If the values do overlap, then the

///   overlapping region of memory from `x` will be used. This is demonstrated

///   in the second example below.

///

/// * The operation is "untyped" in the sense that data may be uninitialized or otherwise violate

///   the requirements of `T`. The initialization state is preserved exactly.

///

/// # Safety

///

/// Behavior is undefined if any of the following conditions are violated:

///

/// * Both `x` and `y` must be [valid] for both reads and writes. They must remain valid even when the

///   other pointer is written. (This means if the memory ranges overlap, the two pointers must not

///   be subject to aliasing restrictions relative to each other.)

///

/// * Both `x` and `y` must be properly aligned.

///

/// Note that even if `T` has size `0`, the pointers must be properly aligned.

///

/// [valid]: self#safety

///

/// # Examples

///

/// Swapping two non-overlapping regions:

///

/// ```

/// use std::ptr;

///

/// let mut array = [0, 1, 2, 3];

///

/// let (x, y) = array.split_at_mut(2);

/// let x = x.as_mut_ptr().cast::<[u32; 2]>(); // this is `array[0..2]`

/// let y = y.as_mut_ptr().cast::<[u32; 2]>(); // this is `array[2..4]`

///

/// unsafe {

///     ptr::swap(x, y);

///     assert_eq!([2, 3, 0, 1], array);

/// }

/// ```

///

/// Swapping two overlapping regions:

///

/// ```

/// use std::ptr;

///

/// let mut array: [i32; 4] = [0, 1, 2, 3];

///

/// let array_ptr: *mut i32 = array.as_mut_ptr();

///

/// let x = array_ptr as *mut [i32; 3]; // this is `array[0..3]`

/// let y = unsafe { array_ptr.add(1) } as *mut [i32; 3]; // this is `array[1..4]`

///

/// unsafe {

///     ptr::swap(x, y);

///     // The indices `1..3` of the slice overlap between `x` and `y`.

///     // Reasonable results would be for to them be `[2, 3]`, so that indices `0..3` are

///     // `[1, 2, 3]` (matching `y` before the `swap`); or for them to be `[0, 1]`

///     // so that indices `1..4` are `[0, 1, 2]` (matching `x` before the `swap`).

///     // This implementation is defined to make the latter choice.

///     assert_eq!([1, 0, 1, 2], array);

/// }

/// ```

#[inline]

#[stable(feature = "rust1", since = "1.0.0")]

#[rustc_const_stable(feature = "const_swap", since = "1.85.0")]

#[rustc_diagnostic_item = "ptr_swap"]

#[cfg(not(feature = "ferrocene_certified"))]

pub const unsafe fn swap<T>(x: *mut T, y: *mut T) {

    // Give ourselves some scratch space to work with.

    // We do not have to worry about drops: `MaybeUninit` does nothing when dropped.

    let mut tmp = MaybeUninit::<T>::uninit();

    // Perform the swap

    // SAFETY: the caller must guarantee that `x` and `y` are

    // valid for writes and properly aligned. `tmp` cannot be

    // overlapping either `x` or `y` because `tmp` was just allocated

    // on the stack as a separate allocation.

    unsafe {