use super::*;

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

use crate::cmp::Ordering::{Equal, Greater, Less};

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

use crate::intrinsics::const_eval_select;

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

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

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

use crate::slice::{self, SliceIndex};

// Ferrocene addition: imports used by certified subset

#[cfg(feature = "ferrocene_certified")]

use crate::{intrinsics::const_eval_select, mem};

impl<T: PointeeSized> *const T {

    #[doc = include_str!("docs/is_null.md")]

    ///

    /// # Examples

    ///

    /// ```

    /// let s: &str = "Follow the rabbit";

    /// let ptr: *const u8 = s.as_ptr();

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

    /// ```

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

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

    #[rustc_diagnostic_item = "ptr_const_is_null"]

    #[inline]

    #[rustc_allow_const_fn_unstable(const_eval_select)]

        // Compare via a cast to a thin pointer, so fat pointers are only

        // considering their "data" part for null-ness.

            @capture { ptr: *const u8 } -> bool:

            // This use of `const_raw_ptr_comparison` has been explicitly blessed by t-lang.

            if const #[rustc_allow_const_fn_unstable(const_raw_ptr_comparison)] {

                match (ptr).guaranteed_eq(null_mut()) {

                    Some(res) => res,

                    // To remain maximally conservative, we stop execution when we don't

                    // know whether the pointer is null or not.

                    // We can *not* return `false` here, that would be unsound in `NonNull::new`!

                    None => panic!("null-ness of this pointer cannot be determined in const context"),

                }

            } else {

                ptr.addr() == 0

            }

        )

    /// Casts to a pointer of another type.

    #[stable(feature = "ptr_cast", since = "1.38.0")]

    #[rustc_const_stable(feature = "const_ptr_cast", since = "1.38.0")]

    #[rustc_diagnostic_item = "const_ptr_cast"]

    #[inline(always)]

    /// Try to cast to a pointer of another type by checking alignment.

    ///

    /// If the pointer is properly aligned to the target type, it will be

    /// cast to the target type. Otherwise, `None` is returned.

    ///

    /// # Examples

    ///

    /// ```rust

    /// #![feature(pointer_try_cast_aligned)]

    ///

    /// let x = 0u64;

    ///

    /// let aligned: *const u64 = &x;

    /// let unaligned = unsafe { aligned.byte_add(1) };

    ///

    /// assert!(aligned.try_cast_aligned::<u32>().is_some());

    /// assert!(unaligned.try_cast_aligned::<u32>().is_none());

    /// ```

    #[unstable(feature = "pointer_try_cast_aligned", issue = "141221")]

    #[must_use = "this returns the result of the operation, \

                  without modifying the original"]

    #[inline]

    pub fn try_cast_aligned<U>(self) -> Option<*const U> {

        if self.is_aligned_to(align_of::<U>()) { Some(self.cast()) } else { None }

    }

    /// Uses the address value in a new pointer of another type.

    ///

    /// This operation will ignore the address part of its `meta` operand and discard existing

    /// metadata of `self`. For pointers to a sized types (thin pointers), this has the same effect

    /// as a simple cast. For pointers to an unsized type (fat pointers) this recombines the address

    /// with new metadata such as slice lengths or `dyn`-vtable.

    ///

    /// The resulting pointer will have provenance of `self`. This operation is semantically the

    /// same as creating a new pointer with the data pointer value of `self` but the metadata of

    /// `meta`, being fat or thin depending on the `meta` operand.

    ///

    /// # Examples

    ///

    /// This function is primarily useful for enabling pointer arithmetic on potentially fat

    /// pointers. The pointer is cast to a sized pointee to utilize offset operations and then

    /// recombined with its own original metadata.

    ///

    /// ```

    /// #![feature(set_ptr_value)]

    /// # use core::fmt::Debug;

    /// let arr: [i32; 3] = [1, 2, 3];

    /// let mut ptr = arr.as_ptr() as *const dyn Debug;

    /// let thin = ptr as *const u8;

    /// unsafe {

    ///     ptr = thin.add(8).with_metadata_of(ptr);

    ///     # assert_eq!(*(ptr as *const i32), 3);

    ///     println!("{:?}", &*ptr); // will print "3"

    /// }

    /// ```

    ///

    /// # *Incorrect* usage

    ///

    /// The provenance from pointers is *not* combined. The result must only be used to refer to the

    /// address allowed by `self`.

    ///

    /// ```rust,no_run

    /// #![feature(set_ptr_value)]

    /// let x = 0u32;

    /// let y = 1u32;

    ///

    /// let x = (&x) as *const u32;

    /// let y = (&y) as *const u32;

    ///

    /// let offset = (x as usize - y as usize) / 4;

    /// let bad = x.wrapping_add(offset).with_metadata_of(y);

    ///

    /// // This dereference is UB. The pointer only has provenance for `x` but points to `y`.

    /// println!("{:?}", unsafe { &*bad });

    /// ```

    #[unstable(feature = "set_ptr_value", issue = "75091")]

    #[must_use = "returns a new pointer rather than modifying its argument"]

    #[inline]

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

    pub const fn with_metadata_of<U>(self, meta: *const U) -> *const U

    where

        U: PointeeSized,

    {

        from_raw_parts::<U>(self as *const (), metadata(meta))

    }

    /// Changes constness without changing the type.

    ///

    /// This is a bit safer than `as` because it wouldn't silently change the type if the code is

    /// refactored.

    #[stable(feature = "ptr_const_cast", since = "1.65.0")]

    #[rustc_const_stable(feature = "ptr_const_cast", since = "1.65.0")]

    #[rustc_diagnostic_item = "ptr_cast_mut"]

    #[inline(always)]

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

    pub const fn cast_mut(self) -> *mut T {

        self as _

    }

    /// Gets the "address" portion of the pointer.

    ///

    /// This is similar to `self as usize`, except that the [provenance][crate::ptr#provenance] of

    /// the pointer is discarded and not [exposed][crate::ptr#exposed-provenance]. This means that

    /// casting the returned address back to a pointer yields a [pointer without

    /// provenance][without_provenance], which is undefined behavior to dereference. To properly

    /// restore the lost information and obtain a dereferenceable pointer, use

    /// [`with_addr`][pointer::with_addr] or [`map_addr`][pointer::map_addr].

    ///

    /// If using those APIs is not possible because there is no way to preserve a pointer with the

    /// required provenance, then Strict Provenance might not be for you. Use pointer-integer casts

    /// or [`expose_provenance`][pointer::expose_provenance] and [`with_exposed_provenance`][with_exposed_provenance]

    /// instead. However, note that this makes your code less portable and less amenable to tools

    /// that check for compliance with the Rust memory model.

    ///

    /// On most platforms this will produce a value with the same bytes as the original

    /// pointer, because all the bytes are dedicated to describing the address.

    /// Platforms which need to store additional information in the pointer may

    /// perform a change of representation to produce a value containing only the address

    /// portion of the pointer. What that means is up to the platform to define.

    ///

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

    #[must_use]

    #[inline(always)]

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

        // A pointer-to-integer transmute currently has exactly the right semantics: it returns the

        // address without exposing the provenance. Note that this is *not* a stable guarantee about

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

        // SAFETY: Pointer-to-integer transmutes are valid (if you are okay with losing the

        // provenance).

    /// Exposes the ["provenance"][crate::ptr#provenance] part of the pointer for future use in

    /// [`with_exposed_provenance`] and returns the "address" portion.

    ///

    /// This is equivalent to `self as usize`, which semantically discards provenance information.

    /// Furthermore, this (like the `as` cast) has the implicit side-effect of marking the

    /// provenance as 'exposed', so on platforms that support it you can later call

    /// [`with_exposed_provenance`] to reconstitute the original pointer including its provenance.

    ///

    /// Due to its inherent ambiguity, [`with_exposed_provenance`] may not be supported by tools

    /// that help you to stay conformant with the Rust memory model. It is recommended to use

    /// [Strict Provenance][crate::ptr#strict-provenance] APIs such as [`with_addr`][pointer::with_addr]

    /// wherever possible, in which case [`addr`][pointer::addr] should be used instead of `expose_provenance`.

    ///

    /// On most platforms this will produce a value with the same bytes as the original pointer,

    /// because all the bytes are dedicated to describing the address. Platforms which need to store

    /// additional information in the pointer may not support this operation, since the 'expose'

    /// side-effect which is required for [`with_exposed_provenance`] to work is typically not

    /// available.

    ///

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

    ///

    /// [`with_exposed_provenance`]: with_exposed_provenance

    #[inline(always)]

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

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

    pub fn expose_provenance(self) -> usize {

        self.cast::<()>() as usize

    }

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

    /// `self`.

    ///

    /// This is similar to a `addr as *const T` cast, but copies

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

    /// This avoids the inherent ambiguity of the unary cast.

    ///

    /// This is equivalent to using [`wrapping_offset`][pointer::wrapping_offset] to offset

    /// `self` to the given address, and therefore has all the same capabilities and restrictions.

    ///

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

    #[must_use]

    #[inline]

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

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

    pub fn with_addr(self, addr: usize) -> Self {

        // This should probably be an intrinsic to avoid doing any sort of arithmetic, but

        // meanwhile, we can implement it with `wrapping_offset`, which preserves the pointer's

        // provenance.

        let self_addr = self.addr() as isize;

        let dest_addr = addr as isize;

        let offset = dest_addr.wrapping_sub(self_addr);

        self.wrapping_byte_offset(offset)

    }

    /// Creates a new pointer by mapping `self`'s address to a new one, preserving the

    /// [provenance][crate::ptr#provenance] of `self`.

    ///

    /// This is a convenience for [`with_addr`][pointer::with_addr], see that method for details.

    ///

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

    #[must_use]

    #[inline]

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

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

    pub fn map_addr(self, f: impl FnOnce(usize) -> usize) -> Self {

        self.with_addr(f(self.addr()))

    }

    /// Decompose a (possibly wide) pointer into its data pointer and metadata components.

    ///

    /// The pointer can be later reconstructed with [`from_raw_parts`].

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

    #[inline]

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

    pub const fn to_raw_parts(self) -> (*const (), <T as super::Pointee>::Metadata) {

        (self.cast(), metadata(self))

    }

    /// Returns `None` if the pointer is null, or else returns a shared reference to

    /// the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_ref`]

    /// must be used instead.

    ///

    /// [`as_uninit_ref`]: #method.as_uninit_ref

    ///

    /// # Safety

    ///

    /// When calling this method, you have to ensure that *either* the pointer is null *or*

    /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).

    ///

    /// # Panics during const evaluation

    ///

    /// This method will panic during const evaluation if the pointer cannot be

    /// determined to be null or not. See [`is_null`] for more information.

    ///

    /// [`is_null`]: #method.is_null

    ///

    /// # Examples

    ///

    /// ```

    /// let ptr: *const u8 = &10u8 as *const u8;

    ///

    /// unsafe {

    ///     if let Some(val_back) = ptr.as_ref() {

    ///         assert_eq!(val_back, &10);

    ///     }

    /// }

    /// ```

    ///

    /// # Null-unchecked version

    ///

    /// If you are sure the pointer can never be null and are looking for some kind of

    /// `as_ref_unchecked` that returns the `&T` instead of `Option<&T>`, know that you can

    /// dereference the pointer directly.

    ///

    /// ```

    /// let ptr: *const u8 = &10u8 as *const u8;

    ///

    /// unsafe {

    ///     let val_back = &*ptr;

    ///     assert_eq!(val_back, &10);

    /// }

    /// ```

    #[stable(feature = "ptr_as_ref", since = "1.9.0")]

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

    #[inline]

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

    pub const unsafe fn as_ref<'a>(self) -> Option<&'a T> {

        // SAFETY: the caller must guarantee that `self` is valid

        // for a reference if it isn't null.

        if self.is_null() { None } else { unsafe { Some(&*self) } }

    }

    /// Returns a shared reference to the value behind the pointer.

    /// If the pointer may be null or the value may be uninitialized, [`as_uninit_ref`] must be used instead.

    /// If the pointer may be null, but the value is known to have been initialized, [`as_ref`] must be used instead.

    ///

    /// [`as_ref`]: #method.as_ref

    /// [`as_uninit_ref`]: #method.as_uninit_ref

    ///

    /// # Safety

    ///

    /// When calling this method, you have to ensure that

    /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).

    ///

    /// # Examples

    ///

    /// ```

    /// #![feature(ptr_as_ref_unchecked)]

    /// let ptr: *const u8 = &10u8 as *const u8;

    ///

    /// unsafe {

    ///     assert_eq!(ptr.as_ref_unchecked(), &10);

    /// }

    /// ```

    // FIXME: mention it in the docs for `as_ref` and `as_uninit_ref` once stabilized.

    #[unstable(feature = "ptr_as_ref_unchecked", issue = "122034")]

    #[inline]

    #[must_use]

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

    pub const unsafe fn as_ref_unchecked<'a>(self) -> &'a T {

        // SAFETY: the caller must guarantee that `self` is valid for a reference

        unsafe { &*self }

    }

    /// Returns `None` if the pointer is null, or else returns a shared reference to

    /// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require

    /// that the value has to be initialized.

    ///

    /// [`as_ref`]: #method.as_ref

    ///

    /// # Safety

    ///

    /// When calling this method, you have to ensure that *either* the pointer is null *or*

    /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).

    ///

    /// # Panics during const evaluation

    ///

    /// This method will panic during const evaluation if the pointer cannot be

    /// determined to be null or not. See [`is_null`] for more information.

    ///

    /// [`is_null`]: #method.is_null

    ///

    /// # Examples

    ///

    /// ```

    /// #![feature(ptr_as_uninit)]

    ///

    /// let ptr: *const u8 = &10u8 as *const u8;

    ///

    /// unsafe {

    ///     if let Some(val_back) = ptr.as_uninit_ref() {

    ///         assert_eq!(val_back.assume_init(), 10);

    ///     }

    /// }

    /// ```

    #[inline]

    #[unstable(feature = "ptr_as_uninit", issue = "75402")]

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

    pub const unsafe fn as_uninit_ref<'a>(self) -> Option<&'a MaybeUninit<T>>

    where

        T: Sized,

    {

        // SAFETY: the caller must guarantee that `self` meets all the

        // requirements for a reference.

        if self.is_null() { None } else { Some(unsafe { &*(self as *const MaybeUninit<T>) }) }

    }

    #[doc = include_str!("./docs/offset.md")]

    ///

    /// # Examples

    ///

    /// ```

    /// let s: &str = "123";

    /// let ptr: *const u8 = s.as_ptr();

    ///

    /// unsafe {

    ///     assert_eq!(*ptr.offset(1) as char, '2');

    ///     assert_eq!(*ptr.offset(2) as char, '3');

    /// }

    /// ```

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

    #[must_use = "returns a new pointer rather than modifying its argument"]

    #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]

    #[inline(always)]

    #[track_caller]

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

    pub const unsafe fn offset(self, count: isize) -> *const T

    where

        T: Sized,

    {

        #[inline]

        #[rustc_allow_const_fn_unstable(const_eval_select)]

        const fn runtime_offset_nowrap(this: *const (), count: isize, size: usize) -> bool {

            // We can use const_eval_select here because this is only for UB checks.

            const_eval_select!(

                @capture { this: *const (), count: isize, size: usize } -> bool:

                if const {

                    true

                } else {

                    // `size` is the size of a Rust type, so we know that

                    // `size <= isize::MAX` and thus `as` cast here is not lossy.

                    let Some(byte_offset) = count.checked_mul(size as isize) else {

                        return false;

                    };

                    let (_, overflow) = this.addr().overflowing_add_signed(byte_offset);

                    !overflow

                }

            )

        }

        ub_checks::assert_unsafe_precondition!(

            check_language_ub,

            "ptr::offset requires the address calculation to not overflow",

            (

                this: *const () = self as *const (),

                count: isize = count,

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

            ) => runtime_offset_nowrap(this, count, size)

        );

        // SAFETY: the caller must uphold the safety contract for `offset`.

        unsafe { intrinsics::offset(self, count) }

    }

    /// Adds a signed offset in bytes to a pointer.

    ///

    /// `count` is in units of **bytes**.

    ///

    /// This is purely a convenience for casting to a `u8` pointer and

    /// using [offset][pointer::offset] on it. See that method for documentation

    /// and safety requirements.

    ///

    /// For non-`Sized` pointees this operation changes only the data pointer,

    /// leaving the metadata untouched.

    #[must_use]

    #[inline(always)]

    #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]

    #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]

    #[track_caller]

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

    pub const unsafe fn byte_offset(self, count: isize) -> Self {

        // SAFETY: the caller must uphold the safety contract for `offset`.

        unsafe { self.cast::<u8>().offset(count).with_metadata_of(self) }

    }

    /// Adds a signed offset to a pointer using wrapping arithmetic.

    ///

    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer

    /// offset of `3 * size_of::<T>()` bytes.

    ///

    /// # Safety

    ///

    /// This operation itself is always safe, but using the resulting pointer is not.

    ///

    /// The resulting pointer "remembers" the [allocation] that `self` points to

    /// (this is called "[Provenance](ptr/index.html#provenance)").

    /// The pointer must not be used to read or write other allocations.

    ///

    /// In other words, `let z = x.wrapping_offset((y as isize) - (x as isize))` does *not* make `z`

    /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still

    /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless

    /// `x` and `y` point into the same allocation.

    ///

    /// Compared to [`offset`], this method basically delays the requirement of staying within the

    /// same allocation: [`offset`] is immediate Undefined Behavior when crossing object

    /// boundaries; `wrapping_offset` produces a pointer but still leads to Undefined Behavior if a

    /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`offset`]

    /// can be optimized better and is thus preferable in performance-sensitive code.

    ///

    /// The delayed check only considers the value of the pointer that was dereferenced, not the

    /// intermediate values used during the computation of the final result. For example,

    /// `x.wrapping_offset(o).wrapping_offset(o.wrapping_neg())` is always the same as `x`. In other

    /// words, leaving the allocation and then re-entering it later is permitted.

    ///

    /// [`offset`]: #method.offset

    /// [allocation]: crate::ptr#allocation

    ///

    /// # Examples

    ///

    /// ```

    /// # use std::fmt::Write;

    /// // Iterate using a raw pointer in increments of two elements

    /// let data = [1u8, 2, 3, 4, 5];

    /// let mut ptr: *const u8 = data.as_ptr();

    /// let step = 2;

    /// let end_rounded_up = ptr.wrapping_offset(6);

    ///

    /// let mut out = String::new();

    /// while ptr != end_rounded_up {

    ///     unsafe {

    ///         write!(&mut out, "{}, ", *ptr)?;

    ///     }

    ///     ptr = ptr.wrapping_offset(step);

    /// }

    /// assert_eq!(out.as_str(), "1, 3, 5, ");

    /// # std::fmt::Result::Ok(())

    /// ```

    #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")]

    #[must_use = "returns a new pointer rather than modifying its argument"]

    #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]

    #[inline(always)]

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

    pub const fn wrapping_offset(self, count: isize) -> *const T

    where

        T: Sized,

    {

        // SAFETY: the `arith_offset` intrinsic has no prerequisites to be called.

        unsafe { intrinsics::arith_offset(self, count) }

    }

    /// Adds a signed offset in bytes to a pointer using wrapping arithmetic.

    ///

    /// `count` is in units of **bytes**.

    ///

    /// This is purely a convenience for casting to a `u8` pointer and

    /// using [wrapping_offset][pointer::wrapping_offset] on it. See that method

    /// for documentation.

    ///

    /// For non-`Sized` pointees this operation changes only the data pointer,

    /// leaving the metadata untouched.

    #[must_use]

    #[inline(always)]

    #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]

    #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]

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

    pub const fn wrapping_byte_offset(self, count: isize) -> Self {

        self.cast::<u8>().wrapping_offset(count).with_metadata_of(self)

    }

    /// Masks out bits of the pointer according to a mask.

    ///

    /// This is convenience for `ptr.map_addr(|a| a & mask)`.

    ///

    /// For non-`Sized` pointees this operation changes only the data pointer,

    /// leaving the metadata untouched.

    ///

    /// ## Examples

    ///

    /// ```

    /// #![feature(ptr_mask)]

    /// let v = 17_u32;

    /// let ptr: *const u32 = &v;

    ///

    /// // `u32` is 4 bytes aligned,

    /// // which means that lower 2 bits are always 0.

    /// let tag_mask = 0b11;

    /// let ptr_mask = !tag_mask;

    ///

    /// // We can store something in these lower bits

    /// let tagged_ptr = ptr.map_addr(|a| a | 0b10);

    ///

    /// // Get the "tag" back

    /// let tag = tagged_ptr.addr() & tag_mask;

    /// assert_eq!(tag, 0b10);

    ///

    /// // Note that `tagged_ptr` is unaligned, it's UB to read from it.

    /// // To get original pointer `mask` can be used:

    /// let masked_ptr = tagged_ptr.mask(ptr_mask);

    /// assert_eq!(unsafe { *masked_ptr }, 17);

    /// ```

    #[unstable(feature = "ptr_mask", issue = "98290")]

    #[must_use = "returns a new pointer rather than modifying its argument"]

    #[inline(always)]

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

    pub fn mask(self, mask: usize) -> *const T {

        intrinsics::ptr_mask(self.cast::<()>(), mask).with_metadata_of(self)

    }

    /// Calculates the distance between two pointers within the same allocation. The returned value is in

    /// units of T: the distance in bytes divided by `size_of::<T>()`.

    ///

    /// This is equivalent to `(self as isize - origin as isize) / (size_of::<T>() as isize)`,

    /// except that it has a lot more opportunities for UB, in exchange for the compiler

    /// better understanding what you are doing.

    ///

    /// The primary motivation of this method is for computing the `len` of an array/slice

    /// of `T` that you are currently representing as a "start" and "end" pointer

    /// (and "end" is "one past the end" of the array).

    /// In that case, `end.offset_from(start)` gets you the length of the array.

    ///

    /// All of the following safety requirements are trivially satisfied for this usecase.

    ///

    /// [`offset`]: #method.offset

    ///

    /// # Safety

    ///

    /// If any of the following conditions are violated, the result is Undefined Behavior:

    ///

    /// * `self` and `origin` must either

    ///

    ///   * point to the same address, or

    ///   * both be [derived from][crate::ptr#provenance] a pointer to the same [allocation], and the memory range between

    ///     the two pointers must be in bounds of that object. (See below for an example.)

    ///

    /// * The distance between the pointers, in bytes, must be an exact multiple

    ///   of the size of `T`.

    ///

    /// As a consequence, the absolute distance between the pointers, in bytes, computed on

    /// mathematical integers (without "wrapping around"), cannot overflow an `isize`. This is

    /// implied by the in-bounds requirement, and the fact that no allocation can be larger

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

    ///

    /// The requirement for pointers to be derived from the same allocation is primarily

    /// needed for `const`-compatibility: the distance between pointers into *different* allocated

    /// objects is not known at compile-time. However, the requirement also exists at

    /// runtime and may be exploited by optimizations. If you wish to compute the difference between

    /// pointers that are not guaranteed to be from the same allocation, use `(self as isize -

    /// origin as isize) / size_of::<T>()`.

    // FIXME: recommend `addr()` instead of `as usize` once that is stable.

    ///

    /// [`add`]: #method.add

    /// [allocation]: crate::ptr#allocation

    ///

    /// # Panics

    ///

    /// This function panics if `T` is a Zero-Sized Type ("ZST").

    ///

    /// # Examples

    ///

    /// Basic usage:

    ///

    /// ```

    /// let a = [0; 5];

    /// let ptr1: *const i32 = &a[1];

    /// let ptr2: *const i32 = &a[3];

    /// unsafe {

    ///     assert_eq!(ptr2.offset_from(ptr1), 2);

    ///     assert_eq!(ptr1.offset_from(ptr2), -2);

    ///     assert_eq!(ptr1.offset(2), ptr2);

    ///     assert_eq!(ptr2.offset(-2), ptr1);

    /// }

    /// ```

    ///

    /// *Incorrect* usage:

    ///

    /// ```rust,no_run

    /// let ptr1 = Box::into_raw(Box::new(0u8)) as *const u8;

    /// let ptr2 = Box::into_raw(Box::new(1u8)) as *const u8;

    /// let diff = (ptr2 as isize).wrapping_sub(ptr1 as isize);

    /// // Make ptr2_other an "alias" of ptr2.add(1), but derived from ptr1.

    /// let ptr2_other = (ptr1 as *const u8).wrapping_offset(diff).wrapping_offset(1);

    /// assert_eq!(ptr2 as usize, ptr2_other as usize);

    /// // Since ptr2_other and ptr2 are derived from pointers to different objects,

    /// // computing their offset is undefined behavior, even though

    /// // they point to addresses that are in-bounds of the same object!

    /// unsafe {

    ///     let one = ptr2_other.offset_from(ptr2); // Undefined Behavior! ⚠️

    /// }

    /// ```

    #[stable(feature = "ptr_offset_from", since = "1.47.0")]

    #[rustc_const_stable(feature = "const_ptr_offset_from", since = "1.65.0")]

    #[inline]

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

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

    pub const unsafe fn offset_from(self, origin: *const T) -> isize

    where

        T: Sized,

    {

        let pointee_size = size_of::<T>();

        assert!(0 < pointee_size && pointee_size <= isize::MAX as usize);

        // SAFETY: the caller must uphold the safety contract for `ptr_offset_from`.

        unsafe { intrinsics::ptr_offset_from(self, origin) }

    }

    /// Calculates the distance between two pointers within the same allocation. The returned value is in

    /// units of **bytes**.

    ///

    /// This is purely a convenience for casting to a `u8` pointer and

    /// using [`offset_from`][pointer::offset_from] on it. See that method for

    /// documentation and safety requirements.

    ///

    /// For non-`Sized` pointees this operation considers only the data pointers,

    /// ignoring the metadata.

    #[inline(always)]

    #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]

    #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]

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

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

    pub const unsafe fn byte_offset_from<U: ?Sized>(self, origin: *const U) -> isize {

        // SAFETY: the caller must uphold the safety contract for `offset_from`.

        unsafe { self.cast::<u8>().offset_from(origin.cast::<u8>()) }

    }

    /// Calculates the distance between two pointers within the same allocation, *where it's known that

    /// `self` is equal to or greater than `origin`*. The returned value is in

    /// units of T: the distance in bytes is divided by `size_of::<T>()`.

    ///

    /// This computes the same value that [`offset_from`](#method.offset_from)

    /// would compute, but with the added precondition that the offset is

    /// guaranteed to be non-negative.  This method is equivalent to

    /// `usize::try_from(self.offset_from(origin)).unwrap_unchecked()`,

    /// but it provides slightly more information to the optimizer, which can

    /// sometimes allow it to optimize slightly better with some backends.

    ///

    /// This method can be thought of as recovering the `count` that was passed

    /// to [`add`](#method.add) (or, with the parameters in the other order,

    /// to [`sub`](#method.sub)).  The following are all equivalent, assuming

    /// that their safety preconditions are met:

    /// ```rust

    /// # unsafe fn blah(ptr: *const i32, origin: *const i32, count: usize) -> bool { unsafe {

    /// ptr.offset_from_unsigned(origin) == count

    /// # &&

    /// origin.add(count) == ptr

    /// # &&

    /// ptr.sub(count) == origin

    /// # } }

    /// ```

    ///

    /// # Safety

    ///

    /// - The distance between the pointers must be non-negative (`self >= origin`)

    ///

    /// - *All* the safety conditions of [`offset_from`](#method.offset_from)

    ///   apply to this method as well; see it for the full details.

    ///

    /// Importantly, despite the return type of this method being able to represent

    /// a larger offset, it's still *not permitted* to pass pointers which differ

    /// by more than `isize::MAX` *bytes*.  As such, the result of this method will

    /// always be less than or equal to `isize::MAX as usize`.

    ///

    /// # Panics

    ///

    /// This function panics if `T` is a Zero-Sized Type ("ZST").

    ///

    /// # Examples

    ///

    /// ```

    /// let a = [0; 5];

    /// let ptr1: *const i32 = &a[1];

    /// let ptr2: *const i32 = &a[3];

    /// unsafe {

    ///     assert_eq!(ptr2.offset_from_unsigned(ptr1), 2);

    ///     assert_eq!(ptr1.add(2), ptr2);

    ///     assert_eq!(ptr2.sub(2), ptr1);

    ///     assert_eq!(ptr2.offset_from_unsigned(ptr2), 0);

    /// }

    ///

    /// // This would be incorrect, as the pointers are not correctly ordered:

    /// // ptr1.offset_from_unsigned(ptr2)

    /// ```

    #[stable(feature = "ptr_sub_ptr", since = "1.87.0")]

    #[rustc_const_stable(feature = "const_ptr_sub_ptr", since = "1.87.0")]

    #[inline]

    #[track_caller]

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

    pub const unsafe fn offset_from_unsigned(self, origin: *const T) -> usize

    where

        T: Sized,

    {

        #[rustc_allow_const_fn_unstable(const_eval_select)]

        const fn runtime_ptr_ge(this: *const (), origin: *const ()) -> bool {

            const_eval_select!(

                @capture { this: *const (), origin: *const () } -> bool:

                if const {

                    true

                } else {

                    this >= origin

                }

            )

        }

        ub_checks::assert_unsafe_precondition!(

            check_language_ub,

            "ptr::offset_from_unsigned requires `self >= origin`",

            (

                this: *const () = self as *const (),

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

            ) => runtime_ptr_ge(this, origin)

        );

        let pointee_size = size_of::<T>();

        assert!(0 < pointee_size && pointee_size <= isize::MAX as usize);

        // SAFETY: the caller must uphold the safety contract for `ptr_offset_from_unsigned`.

        unsafe { intrinsics::ptr_offset_from_unsigned(self, origin) }

    }

    /// Calculates the distance between two pointers within the same allocation, *where it's known that

    /// `self` is equal to or greater than `origin`*. The returned value is in

    /// units of **bytes**.

    ///

    /// This is purely a convenience for casting to a `u8` pointer and

    /// using [`offset_from_unsigned`][pointer::offset_from_unsigned] on it.

    /// See that method for documentation and safety requirements.

    ///

    /// For non-`Sized` pointees this operation considers only the data pointers,

    /// ignoring the metadata.

    #[stable(feature = "ptr_sub_ptr", since = "1.87.0")]

    #[rustc_const_stable(feature = "const_ptr_sub_ptr", since = "1.87.0")]

    #[inline]

    #[track_caller]

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

    pub const unsafe fn byte_offset_from_unsigned<U: ?Sized>(self, origin: *const U) -> usize {

        // SAFETY: the caller must uphold the safety contract for `offset_from_unsigned`.

        unsafe { self.cast::<u8>().offset_from_unsigned(origin.cast::<u8>()) }

    }

    /// Returns whether two pointers are guaranteed to be equal.

    ///

    /// At runtime this function behaves like `Some(self == other)`.

    /// However, in some contexts (e.g., compile-time evaluation),

    /// it is not always possible to determine equality of two pointers, so this function may

    /// spuriously return `None` for pointers that later actually turn out to have its equality known.

    /// But when it returns `Some`, the pointers' equality is guaranteed to be known.

    ///

    /// The return value may change from `Some` to `None` and vice versa depending on the compiler

    /// version and unsafe code must not

    /// rely on the result of this function for soundness. It is suggested to only use this function

    /// for performance optimizations where spurious `None` return values by this function do not

    /// affect the outcome, but just the performance.

    /// The consequences of using this method to make runtime and compile-time code behave

    /// differently have not been explored. This method should not be used to introduce such

    /// differences, and it should also not be stabilized before we have a better understanding

    /// of this issue.

    #[unstable(feature = "const_raw_ptr_comparison", issue = "53020")]

    #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")]

    #[inline]

    pub const fn guaranteed_eq(self, other: *const T) -> Option<bool>

    where

        T: Sized,

    {

        match intrinsics::ptr_guaranteed_cmp(self, other) {

            2 => None,

            other => Some(other == 1),

        }

    }

    /// Returns whether two pointers are guaranteed to be inequal.

    ///

    /// At runtime this function behaves like `Some(self != other)`.

    /// However, in some contexts (e.g., compile-time evaluation),

    /// it is not always possible to determine inequality of two pointers, so this function may

    /// spuriously return `None` for pointers that later actually turn out to have its inequality known.

    /// But when it returns `Some`, the pointers' inequality is guaranteed to be known.

    ///

    /// The return value may change from `Some` to `None` and vice versa depending on the compiler

    /// version and unsafe code must not

    /// rely on the result of this function for soundness. It is suggested to only use this function

    /// for performance optimizations where spurious `None` return values by this function do not

    /// affect the outcome, but just the performance.

    /// The consequences of using this method to make runtime and compile-time code behave

    /// differently have not been explored. This method should not be used to introduce such

    /// differences, and it should also not be stabilized before we have a better understanding

    /// of this issue.

    #[unstable(feature = "const_raw_ptr_comparison", issue = "53020")]

    #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")]

    #[inline]

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

    pub const fn guaranteed_ne(self, other: *const T) -> Option<bool>

    where

        T: Sized,

    {

        match self.guaranteed_eq(other) {

            None => None,

            Some(eq) => Some(!eq),

        }

    }

    #[doc = include_str!("./docs/add.md")]

    ///

    /// # Examples

    ///

    /// ```

    /// let s: &str = "123";

    /// let ptr: *const u8 = s.as_ptr();

    ///

    /// unsafe {

    ///     assert_eq!(*ptr.add(1), b'2');

    ///     assert_eq!(*ptr.add(2), b'3');

    /// }

    /// ```

    #[stable(feature = "pointer_methods", since = "1.26.0")]

    #[must_use = "returns a new pointer rather than modifying its argument"]

    #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]

    #[inline(always)]

    #[track_caller]

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

    pub const unsafe fn add(self, count: usize) -> Self

    where

        T: Sized,

    {

        #[cfg(debug_assertions)]

        #[inline]

        #[rustc_allow_const_fn_unstable(const_eval_select)]

        const fn runtime_add_nowrap(this: *const (), count: usize, size: usize) -> bool {

            const_eval_select!(

                @capture { this: *const (), count: usize, size: usize } -> bool:

                if const {

                    true

                } else {

                    let Some(byte_offset) = count.checked_mul(size) else {

                        return false;

                    };

                    let (_, overflow) = this.addr().overflowing_add(byte_offset);

                    byte_offset <= (isize::MAX as usize) && !overflow

                }

            )

        }

        #[cfg(debug_assertions)] // Expensive, and doesn't catch much in the wild.

        ub_checks::assert_unsafe_precondition!(

            check_language_ub,

            "ptr::add requires that the address calculation does not overflow",

            (

                this: *const () = self as *const (),

                count: usize = count,

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

            ) => runtime_add_nowrap(this, count, size)

        );

        // SAFETY: the caller must uphold the safety contract for `offset`.

        unsafe { intrinsics::offset(self, count) }

    }

    /// Adds an unsigned offset in bytes to a pointer.

    ///

    /// `count` is in units of bytes.

    ///

    /// This is purely a convenience for casting to a `u8` pointer and

    /// using [add][pointer::add] on it. See that method for documentation

    /// and safety requirements.

    ///

    /// For non-`Sized` pointees this operation changes only the data pointer,

    /// leaving the metadata untouched.

    #[must_use]

    #[inline(always)]

    #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]

    #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]

    #[track_caller]

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

    pub const unsafe fn byte_add(self, count: usize) -> Self {

        // SAFETY: the caller must uphold the safety contract for `add`.

        unsafe { self.cast::<u8>().add(count).with_metadata_of(self) }

    }

    /// Subtracts an unsigned offset from a pointer.

    ///

    /// This can only move the pointer backward (or not move it). If you need to move forward or

    /// backward depending on the value, then you might want [`offset`](#method.offset) instead

    /// which takes a signed offset.

    ///

    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer

    /// offset of `3 * size_of::<T>()` bytes.

    ///

    /// # Safety

    ///

    /// If any of the following conditions are violated, the result is Undefined Behavior:

    ///

    /// * The offset in bytes, `count * size_of::<T>()`, computed on mathematical integers (without

    ///   "wrapping around"), must fit in an `isize`.

    ///

    /// * If the computed offset is non-zero, then `self` must be [derived from][crate::ptr#provenance] a pointer to some

    ///   [allocation], and the entire memory range between `self` and the result must be in

    ///   bounds of that allocation. In particular, this range must not "wrap around" the edge

    ///   of the address space.

    ///

    /// Allocations can never be larger than `isize::MAX` bytes, so if the computed offset

    /// stays in bounds of the allocation, it is guaranteed to satisfy the first requirement.

    /// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always

    /// safe.

    ///

    /// Consider using [`wrapping_sub`] instead if these constraints are

    /// difficult to satisfy. The only advantage of this method is that it

    /// enables more aggressive compiler optimizations.

    ///

    /// [`wrapping_sub`]: #method.wrapping_sub

    /// [allocation]: crate::ptr#allocation

    ///

    /// # Examples

    ///

    /// ```

    /// let s: &str = "123";

    ///

    /// unsafe {

    ///     let end: *const u8 = s.as_ptr().add(3);

    ///     assert_eq!(*end.sub(1), b'3');

    ///     assert_eq!(*end.sub(2), b'2');

    /// }

    /// ```

    #[stable(feature = "pointer_methods", since = "1.26.0")]

    #[must_use = "returns a new pointer rather than modifying its argument"]

    #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]

    #[inline(always)]

    #[track_caller]

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

    pub const unsafe fn sub(self, count: usize) -> Self

    where

        T: Sized,

    {

        #[cfg(debug_assertions)]

        #[inline]

        #[rustc_allow_const_fn_unstable(const_eval_select)]

        const fn runtime_sub_nowrap(this: *const (), count: usize, size: usize) -> bool {

            const_eval_select!(

                @capture { this: *const (), count: usize, size: usize } -> bool:

                if const {

                    true

                } else {

                    let Some(byte_offset) = count.checked_mul(size) else {

                        return false;

                    };

                    byte_offset <= (isize::MAX as usize) && this.addr() >= byte_offset

                }

            )

        }

        #[cfg(debug_assertions)] // Expensive, and doesn't catch much in the wild.

        ub_checks::assert_unsafe_precondition!(

            check_language_ub,

            "ptr::sub requires that the address calculation does not overflow",

            (

                this: *const () = self as *const (),

                count: usize = count,

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

            ) => runtime_sub_nowrap(this, count, size)

        );

        if T::IS_ZST {

            // Pointer arithmetic does nothing when the pointee is a ZST.

            self

        } else {

            // SAFETY: the caller must uphold the safety contract for `offset`.

            // Because the pointee is *not* a ZST, that means that `count` is

            // at most `isize::MAX`, and thus the negation cannot overflow.

            unsafe { intrinsics::offset(self, intrinsics::unchecked_sub(0, count as isize)) }

        }

    }

    /// Subtracts an unsigned offset in bytes from a pointer.

    ///

    /// `count` is in units of bytes.

    ///

    /// This is purely a convenience for casting to a `u8` pointer and

    /// using [sub][pointer::sub] on it. See that method for documentation

    /// and safety requirements.

    ///

    /// For non-`Sized` pointees this operation changes only the data pointer,

    /// leaving the metadata untouched.

    #[must_use]

    #[inline(always)]

    #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]

    #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]

    #[track_caller]

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

    pub const unsafe fn byte_sub(self, count: usize) -> Self {

        // SAFETY: the caller must uphold the safety contract for `sub`.

        unsafe { self.cast::<u8>().sub(count).with_metadata_of(self) }

    }

    /// Adds an unsigned offset to a pointer using wrapping arithmetic.

    ///

    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer

    /// offset of `3 * size_of::<T>()` bytes.

    ///

    /// # Safety

    ///

    /// This operation itself is always safe, but using the resulting pointer is not.

    ///

    /// The resulting pointer "remembers" the [allocation] that `self` points to; it must not

    /// be used to read or write other allocations.

    ///

    /// In other words, `let z = x.wrapping_add((y as usize) - (x as usize))` does *not* make `z`

    /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still

    /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless

    /// `x` and `y` point into the same allocation.

    ///

    /// Compared to [`add`], this method basically delays the requirement of staying within the

    /// same allocation: [`add`] is immediate Undefined Behavior when crossing object

    /// boundaries; `wrapping_add` produces a pointer but still leads to Undefined Behavior if a

    /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`add`]

    /// can be optimized better and is thus preferable in performance-sensitive code.

    ///

    /// The delayed check only considers the value of the pointer that was dereferenced, not the

    /// intermediate values used during the computation of the final result. For example,

    /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the

    /// allocation and then re-entering it later is permitted.

    ///

    /// [`add`]: #method.add

    /// [allocation]: crate::ptr#allocation

    ///

    /// # Examples

    ///

    /// ```

    /// # use std::fmt::Write;

    /// // Iterate using a raw pointer in increments of two elements

    /// let data = [1u8, 2, 3, 4, 5];

    /// let mut ptr: *const u8 = data.as_ptr();

    /// let step = 2;

    /// let end_rounded_up = ptr.wrapping_add(6);

    ///

    /// let mut out = String::new();

    /// while ptr != end_rounded_up {

    ///     unsafe {

    ///         write!(&mut out, "{}, ", *ptr)?;

    ///     }

    ///     ptr = ptr.wrapping_add(step);

    /// }

    /// assert_eq!(out, "1, 3, 5, ");

    /// # std::fmt::Result::Ok(())

    /// ```

    #[stable(feature = "pointer_methods", since = "1.26.0")]

    #[must_use = "returns a new pointer rather than modifying its argument"]

    #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]

    #[inline(always)]

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

    pub const fn wrapping_add(self, count: usize) -> Self

    where

        T: Sized,

    {

        self.wrapping_offset(count as isize)

    }

    /// Adds an unsigned offset in bytes to a pointer using wrapping arithmetic.

    ///

    /// `count` is in units of bytes.

    ///

    /// This is purely a convenience for casting to a `u8` pointer and

    /// using [wrapping_add][pointer::wrapping_add] on it. See that method for documentation.

    ///

    /// For non-`Sized` pointees this operation changes only the data pointer,

    /// leaving the metadata untouched.

    #[must_use]

    #[inline(always)]

    #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]

    #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]

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

    pub const fn wrapping_byte_add(self, count: usize) -> Self {

        self.cast::<u8>().wrapping_add(count).with_metadata_of(self)

    }

    /// Subtracts an unsigned offset from a pointer using wrapping arithmetic.

    ///

    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer

    /// offset of `3 * size_of::<T>()` bytes.

    ///

    /// # Safety

    ///

    /// This operation itself is always safe, but using the resulting pointer is not.

    ///

    /// The resulting pointer "remembers" the [allocation] that `self` points to; it must not

    /// be used to read or write other allocations.

    ///

    /// In other words, `let z = x.wrapping_sub((x as usize) - (y as usize))` does *not* make `z`

    /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still

    /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless

    /// `x` and `y` point into the same allocation.

    ///

    /// Compared to [`sub`], this method basically delays the requirement of staying within the

    /// same allocation: [`sub`] is immediate Undefined Behavior when crossing object

    /// boundaries; `wrapping_sub` produces a pointer but still leads to Undefined Behavior if a

    /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`sub`]

    /// can be optimized better and is thus preferable in performance-sensitive code.

    ///

    /// The delayed check only considers the value of the pointer that was dereferenced, not the

    /// intermediate values used during the computation of the final result. For example,

    /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the

    /// allocation and then re-entering it later is permitted.

    ///

    /// [`sub`]: #method.sub

    /// [allocation]: crate::ptr#allocation

    ///

    /// # Examples

    ///

    /// ```

    /// # use std::fmt::Write;

    /// // Iterate using a raw pointer in increments of two elements (backwards)

    /// let data = [1u8, 2, 3, 4, 5];

    /// let mut ptr: *const u8 = data.as_ptr();

    /// let start_rounded_down = ptr.wrapping_sub(2);

    /// ptr = ptr.wrapping_add(4);

    /// let step = 2;

    /// let mut out = String::new();

    /// while ptr != start_rounded_down {

    ///     unsafe {

    ///         write!(&mut out, "{}, ", *ptr)?;

    ///     }

    ///     ptr = ptr.wrapping_sub(step);

    /// }

    /// assert_eq!(out, "5, 3, 1, ");

    /// # std::fmt::Result::Ok(())

    /// ```

    #[stable(feature = "pointer_methods", since = "1.26.0")]

    #[must_use = "returns a new pointer rather than modifying its argument"]

    #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]

    #[inline(always)]

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

    pub const fn wrapping_sub(self, count: usize) -> Self

    where

        T: Sized,

    {

        self.wrapping_offset((count as isize).wrapping_neg())

    }

    /// Subtracts an unsigned offset in bytes from a pointer using wrapping arithmetic.

    ///

    /// `count` is in units of bytes.

    ///

    /// This is purely a convenience for casting to a `u8` pointer and

    /// using [wrapping_sub][pointer::wrapping_sub] on it. See that method for documentation.

    ///

    /// For non-`Sized` pointees this operation changes only the data pointer,

    /// leaving the metadata untouched.

    #[must_use]

    #[inline(always)]

    #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]

    #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]

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

    pub const fn wrapping_byte_sub(self, count: usize) -> Self {

        self.cast::<u8>().wrapping_sub(count).with_metadata_of(self)

    }

    /// Reads the value from `self` without moving it. This leaves the

    /// memory in `self` unchanged.

    ///

    /// See [`ptr::read`] for safety concerns and examples.

    ///

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

    #[stable(feature = "pointer_methods", since = "1.26.0")]

    #[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")]

    #[inline]

    #[track_caller]

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

    pub const unsafe fn read(self) -> T

    where

        T: Sized,

    {

        // SAFETY: the caller must uphold the safety contract for `read`.

        unsafe { read(self) }

    }

    /// Performs a volatile read of the value from `self` without moving it. This

    /// leaves the memory in `self` unchanged.

    ///

    /// Volatile operations are intended to act on I/O memory, and are guaranteed

    /// to not be elided or reordered by the compiler across other volatile

    /// operations.

    ///

    /// See [`ptr::read_volatile`] for safety concerns and examples.

    ///

    /// [`ptr::read_volatile`]: crate::ptr::read_volatile()

    #[stable(feature = "pointer_methods", since = "1.26.0")]

    #[inline]

    #[track_caller]

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

    pub unsafe fn read_volatile(self) -> T

    where

        T: Sized,

    {

        // SAFETY: the caller must uphold the safety contract for `read_volatile`.

        unsafe { read_volatile(self) }

    }

    /// Reads the value from `self` without moving it. This leaves the

    /// memory in `self` unchanged.

    ///

    /// Unlike `read`, the pointer may be unaligned.

    ///

    /// See [`ptr::read_unaligned`] for safety concerns and examples.

    ///

    /// [`ptr::read_unaligned`]: crate::ptr::read_unaligned()

    #[stable(feature = "pointer_methods", since = "1.26.0")]

    #[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")]

    #[inline]

    #[track_caller]

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

    pub const unsafe fn read_unaligned(self) -> T

    where

        T: Sized,

    {

        // SAFETY: the caller must uphold the safety contract for `read_unaligned`.

        unsafe { read_unaligned(self) }

    }

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

    /// and destination may overlap.

    ///

    /// NOTE: this has the *same* argument order as [`ptr::copy`].

    ///

    /// See [`ptr::copy`] for safety concerns and examples.

    ///

    /// [`ptr::copy`]: crate::ptr::copy()

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

    #[stable(feature = "pointer_methods", since = "1.26.0")]

    #[inline]

    #[track_caller]

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

    pub const unsafe fn copy_to(self, dest: *mut T, count: usize)

    where

        T: Sized,

    {

        // SAFETY: the caller must uphold the safety contract for `copy`.

        unsafe { copy(self, dest, count) }

    }

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

    /// and destination may *not* overlap.

    ///

    /// NOTE: this has the *same* argument order as [`ptr::copy_nonoverlapping`].

    ///

    /// See [`ptr::copy_nonoverlapping`] for safety concerns and examples.

    ///

    /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping()