use super::*;
use crate::cmp::Ordering::{self, Equal, Greater, Less};
use crate::intrinsics;
use crate::mem;
use crate::slice::{self, SliceIndex};

#[lang = "const_ptr"]
impl<T: ?Sized> *const T {
    /// 如果指针为空，则返回 `true`。
    ///
    /// 请注意，未定义大小的类型具有许多可能的空指针，因为仅考虑原始数据指针，而不考虑其长度，vtable 等。
    /// 因此，两个为空的指针可能仍不能相互比较相等。
    ///
    /// ## 常量评估期间的行为
    ///
    /// 在 const 评估期间使用此函数时，对于在运行时结果为空的指针，它可能返回 `false`。
    /// 具体来说，当指向某个内存的指针超出其范围的偏移量 (使结果指针为空) 时，函数仍将返回 `false`。
    ///
    /// CTFE 无法知道该内存的绝对位置，因此我们无法确定指针是否为空。
    ///
    /// # 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_unstable(feature = "const_ptr_is_null", issue = "74939")]
    #[inline]
    pub const fn is_null(self) -> bool {
        // 通过对瘦指针进行强制转换进行比较，因此胖指针仅考虑其 "data" 部分是否为空。
        //
        (self as *const u8).guaranteed_eq(null())
    }

    /// 强制转换为另一种类型的指针。
    #[stable(feature = "ptr_cast", since = "1.38.0")]
    #[rustc_const_stable(feature = "const_ptr_cast", since = "1.38.0")]
    #[inline]
    pub const fn cast<U>(self) -> *const U {
        self as _
    }

    /// 将 (可能是很宽的) 指针分解为地址和元数据组件。
    ///
    /// 以后可以使用 [`from_raw_parts`] 重建指针。
    #[unstable(feature = "ptr_metadata", issue = "81513")]
    #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")]
    #[inline]
    pub const fn to_raw_parts(self) -> (*const (), <T as super::Pointee>::Metadata) {
        (self.cast(), metadata(self))
    }

    /// 如果指针为空，则返回 `None`，否则返回 `Some` 中包装的值的共享引用。如果该值可能未初始化，则必须改用 [`as_uninit_ref`]。
    ///
    /// [`as_uninit_ref`]: #method.as_uninit_ref
    ///
    /// # Safety
    ///
    /// 调用此方法时，您必须确保要么指针是空的，要么以下所有内容都为真::
    ///
    /// * 指针必须正确对齐。
    ///
    /// * 在 [the module documentation] 中定义的意义上，它必须是 "dereferencable"。
    ///
    /// * 指针必须指向 `T` 的初始化实例。
    ///
    /// * 您必须执行 Rust 的别名规则，因为返回的生命周期 `'a` 是任意选择的，不一定反映数据的实际生命周期。
    ///   特别是，在此生命周期的持续时间内，指针所指向的内存一定不能被可变的 (`UnsafeCell` 内部除外)。
    ///
    /// 即使未使用此方法的结果也是如此!
    /// (关于初始化的部分尚未完全决定，但是直到确定之前，唯一安全的方法是确保它们确实被初始化。)
    ///
    /// [the module documentation]: crate::ptr#safety
    ///
    /// # Examples
    ///
    /// 基本用法:
    ///
    /// ```
    /// let ptr: *const u8 = &10u8 as *const u8;
    ///
    /// unsafe {
    ///     if let Some(val_back) = ptr.as_ref() {
    ///         println!("We got back the value: {}!", val_back);
    ///     }
    /// }
    /// ```
    ///
    /// # 空未经检查的版本
    ///
    /// 如果确定指针永远不会为空，并且正在寻找某种返回 `&T` 而不是 `Option<&T>` 的 `as_ref_unchecked`，请知道您可以直接引用该指针。
    ///
    ///
    /// ```
    /// let ptr: *const u8 = &10u8 as *const u8;
    ///
    /// unsafe {
    ///     let val_back = &*ptr;
    ///     println!("We got back the value: {}!", val_back);
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "ptr_as_ref", since = "1.9.0")]
    #[inline]
    pub unsafe fn as_ref<'a>(self) -> Option<&'a T> {
        // SAFETY: 调用者必须保证 `self` 对于引用有效 (如果它不为 null)。
        //
        if self.is_null() { None } else { unsafe { Some(&*self) } }
    }

    /// 如果指针为空，则返回 `None`，否则返回 `Some` 中包装的值的共享引用。
    /// 与 [`as_ref`] 相比，这不需要将该值初始化。
    ///
    /// [`as_ref`]: #method.as_ref
    ///
    /// # Safety
    ///
    /// 调用此方法时，您必须确保要么指针是空的，要么以下所有内容都为真::
    ///
    /// * 指针必须正确对齐。
    ///
    /// * 在 [the module documentation] 中定义的意义上，它必须是 "dereferencable"。
    ///
    /// * 您必须执行 Rust 的别名规则，因为返回的生命周期 `'a` 是任意选择的，不一定反映数据的实际生命周期。
    ///
    ///   特别是，在此生命周期的持续时间内，指针所指向的内存一定不能被可变的 (`UnsafeCell` 内部除外)。
    ///
    /// 即使未使用此方法的结果也是如此!
    ///
    /// [the module documentation]: crate::ptr#safety
    ///
    /// # Examples
    ///
    /// 基本用法:
    ///
    /// ```
    /// #![feature(ptr_as_uninit)]
    ///
    /// let ptr: *const u8 = &10u8 as *const u8;
    ///
    /// unsafe {
    ///     if let Some(val_back) = ptr.as_uninit_ref() {
    ///         println!("We got back the value: {}!", val_back.assume_init());
    ///     }
    /// }
    /// ```
    ///
    ///
    ///
    #[inline]
    #[unstable(feature = "ptr_as_uninit", issue = "75402")]
    pub unsafe fn as_uninit_ref<'a>(self) -> Option<&'a MaybeUninit<T>>
    where
        T: Sized,
    {
        // SAFETY: 调用者必须保证 `self` 满足引用的所有要求。
        //
        if self.is_null() { None } else { Some(unsafe { &*(self as *const MaybeUninit<T>) }) }
    }

    /// 计算与指针的偏移量。
    ///
    /// `count` 以 T 为单位; 例如，`count` 为 3 表示 `3 * size_of::<T>()` 字节的指针偏移量。
    ///
    /// # Safety
    ///
    /// 如果违反以下任一条件，则结果为未定义行为:
    ///
    /// * 起始指针和结果指针都必须在边界内或在同一个 [allocated object] 的末尾之后一个字节。
    ///
    /// * 计算的偏移量 (以字节为单位 **) 不会使 `isize` 溢出。
    ///
    /// * 偏移量不能依赖 "wrapping around" 地址空间。也就是说，无限精度总和 (以字节为单位) 必须适合于 usize。
    ///
    /// 编译器和标准库通常会尝试确保分配永远不会达到需要考虑偏移量的大小。
    /// 例如，`Vec` 和 `Box` 确保它们分配的字节数永远不会超过 `isize::MAX` 字节，因此 `vec.as_ptr().add(vec.len())` 始终是安全的。
    ///
    /// 从根本上说，大多数平台甚至都无法构造这样的分配。
    /// 例如，由于页表的限制或地址空间的分割，没有已知的 64 位平台可以满足 2 <sup>63</sup> 字节的请求。
    /// 但是，某些 32 位和 16 位平台可能通过物理地址扩展之类的东西成功地为超过 `isize::MAX` 字节的请求提供服务。
    ///
    /// 因此，直接从分配器获取的内存或内存映射文件 *可能* 太大而无法使用此函数进行处理。
    ///
    /// 如果这些约束难以满足，请考虑使用 [`wrapping_offset`]。
    /// 此方法的唯一优点是，它可以实现更积极的编译器优化。
    ///
    /// [`wrapping_offset`]: #method.wrapping_offset
    /// [allocated object]: crate::ptr#allocated-object
    ///
    /// # Examples
    ///
    /// 基本用法:
    ///
    /// ```
    /// let s: &str = "123";
    /// let ptr: *const u8 = s.as_ptr();
    ///
    /// unsafe {
    ///     println!("{}", *ptr.offset(1) as char);
    ///     println!("{}", *ptr.offset(2) as char);
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[must_use = "returns a new pointer rather than modifying its argument"]
    #[rustc_const_unstable(feature = "const_ptr_offset", issue = "71499")]
    #[inline(always)]
    pub const unsafe fn offset(self, count: isize) -> *const T
    where
        T: Sized,
    {
        // SAFETY: 调用者必须坚持 `offset` 的安全保证。
        unsafe { intrinsics::offset(self, count) }
    }

    /// 使用换行算法计算与指针的偏移量。
    ///
    /// `count` 以 T 为单位; 例如，`count` 为 3 表示 `3 * size_of::<T>()` 字节的指针偏移量。
    ///
    /// # Safety
    ///
    /// 此操作本身始终是安全的，但使用结果指针则不安全。
    ///
    /// 结果指针 "remembers" 是 `self` 指向的 [allocated object]; 它不能用于读取或写入其他分配的对象。
    ///
    /// 换句话说，即使我们假设 `T` 的大小为 `1` 并且没有溢出，`let z = x.wrapping_offset((y as isize) - (x as isize))` 不会使 `z` 与 `y` 相同: `z` 仍附加到对象 `x` 所附加的对象，并且解引用它是 Undefined Behavior，除非 `x` 和 `y` 指向同一分配的对象。
    ///
    /// 与 [`offset`] 相比，此方法从根本上延迟了留在同一分配对象内的需求: [`offset`] 是跨越对象边界时的立即未定义行为; `wrapping_offset` 产生一个指针，但如果指针超出其附加对象的范围而被解引用，则仍会导致未定义行为。
    /// [`offset`] 可以更好地进行优化，因此在对性能敏感的代码中更可取。
    ///
    /// 延迟检查仅考虑解引用的指针的值，而不考虑最终结果计算期间使用的中间值。
    /// 例如，`x.wrapping_offset(o).wrapping_offset(o.wrapping_neg())` 始终与 `x` 相同。换句话说，允许离开已分配的对象，然后在以后重新输入它。
    ///
    /// [`offset`]: #method.offset
    /// [allocated object]: crate::ptr#allocated-object
    ///
    /// # Examples
    ///
    /// 基本用法:
    ///
    /// ```
    /// // 使用裸指针以两个元素为增量进行迭代
    /// 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);
    ///
    /// // 此循环打印 "1, 3, 5, "
    /// while ptr != end_rounded_up {
    ///     unsafe {
    ///         print!("{}, ", *ptr);
    ///     }
    ///     ptr = ptr.wrapping_offset(step);
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")]
    #[must_use = "returns a new pointer rather than modifying its argument"]
    #[rustc_const_unstable(feature = "const_ptr_offset", issue = "71499")]
    #[inline(always)]
    pub const fn wrapping_offset(self, count: isize) -> *const T
    where
        T: Sized,
    {
        // SAFETY: `arith_offset` 内联函数没有先决条件。
        unsafe { intrinsics::arith_offset(self, count) }
    }

    /// 计算两个指针之间的距离。返回的值以 T 为单位: 以字节为单位的距离除以 `mem::size_of::<T>()`。
    ///
    /// 该函数是 [`offset`] 的逆函数。
    ///
    /// [`offset`]: #method.offset
    ///
    /// # Safety
    ///
    /// 如果违反以下任一条件，则结果为未定义行为:
    ///
    /// * 起始指针和其他指针都必须在边界内或在同一个 [allocated object] 的末尾之后一个字节。
    ///
    /// * 两个指针必须是指向同一对象的指针的 *derived。
    ///   (请参见下面的示例。)
    ///
    /// * 指针之间的距离 (以字节为单位) 必须是 `T` 大小的精确倍数。
    ///
    /// * 指针之间的距离 (以字节为单位) 不会溢出 `isize`。
    ///
    /// * 该距离不能依赖于 "wrapping around" 地址空间。
    ///
    /// Rust 类型从不大于 `isize::MAX`，并且 Rust 分配从不环绕地址空间，因此，任何 Rust 类型 `T` 的某个值内的两个指针将始终满足最后两个条件。
    ///
    /// 标准库通常还确保分配永远不会达到需要考虑偏移量的大小。
    /// 例如，`Vec` 和 `Box` 确保它们分配的字节数永远不超过 `isize::MAX` 字节，因此 `ptr_into_vec.offset_from(vec.as_ptr())` 始终满足最后两个条件。
    ///
    /// 从根本上说，大多数平台甚至都无法构建如此大的分配。
    /// 例如，由于页表的限制或地址空间的分割，没有已知的 64 位平台可以满足 2 <sup>63</sup> 字节的请求。
    /// 但是，某些 32 位和 16 位平台可能通过物理地址扩展之类的东西成功地为超过 `isize::MAX` 字节的请求提供服务。
    /// 因此，直接从分配器获取的内存或内存映射文件 *可能* 太大而无法使用此函数进行处理。
    /// (请注意，[`offset`] 和 [`add`] 也具有类似的限制，因此也不能在如此大的分配上使用。)
    ///
    /// [`add`]: #method.add
    /// [allocated object]: crate::ptr#allocated-object
    ///
    /// # Panics
    ///
    /// 如果 `T` 是零大小类型 ("ZST")，则此函数 panics。
    ///
    /// # Examples
    ///
    /// 基本用法:
    ///
    /// ```
    /// 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);
    /// }
    /// ```
    ///
    /// *不正确* 用法:
    ///
    /// ```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);
    /// // 将 ptr2_other 设置为 ptr2 的 "alias"，但从 ptr1 派生。
    /// let ptr2_other = (ptr1 as *const u8).wrapping_offset(diff);
    /// assert_eq!(ptr2 as usize, ptr2_other as usize);
    /// // 由于 ptr2_other 和 ptr2 是从指向不同对象的指针派生的，因此即使它们指向相同的地址，计算其偏移量也是未定义的行为!
    /////
    /////
    /// unsafe {
    ///     let zero = ptr2_other.offset_from(ptr2); // 未定义的行为
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "ptr_offset_from", since = "1.47.0")]
    #[rustc_const_unstable(feature = "const_ptr_offset_from", issue = "41079")]
    #[inline]
    pub const unsafe fn offset_from(self, origin: *const T) -> isize
    where
        T: Sized,
    {
        let pointee_size = mem::size_of::<T>();
        assert!(0 < pointee_size && pointee_size <= isize::MAX as usize);
        // SAFETY: 调用者必须坚持 `ptr_offset_from` 的安全保证。
        unsafe { intrinsics::ptr_offset_from(self, origin) }
    }

    /// 返回两个指针是否保证相等。
    ///
    /// 在运行时，此函数的行为类似于 `self == other`。
    /// 但是，在某些情况下 (例如，编译时评估)，并非总是可以确定两个指针是否相等，因此此函数可能会虚假地返回 `false` 来表示后来实际上相等的指针。
    ///
    /// 但是，当它返回 `true` 时，保证指针是相等的。
    ///
    /// 该函数是 [`guaranteed_ne`] 的镜像，但不是其反函数。有两个指针返回 `false` 的指针比较。
    ///
    /// [`guaranteed_ne`]: #method.guaranteed_ne
    ///
    /// 返回值可能会有所不同，具体取决于编译器版本，并且不安全的代码可能不依赖于此函数的结果来确保完整性。
    /// 建议仅将此函数用于性能优化，在这种情况下，此函数的虚假 `false` 返回值不会影响结果，而只会影响性能。
    /// 尚未探讨使用此方法使运行时和编译时代码表现不同的后果。
    /// 不应使用这种方法来引入这种差异，并且在我们对这个问题有更好的理解之前，也不应使其稳定。
    ///
    ///
    ///
    ///
    ///
    ///
    #[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) -> bool
    where
        T: Sized,
    {
        intrinsics::ptr_guaranteed_eq(self, other)
    }

    /// 返回两个指针是否保证不相等。
    ///
    /// 在运行时，此函数的行为类似于 `self != other`。
    /// 但是，在某些情况下 (例如，编译时评估)，并非总是可以确定两个指针的不相等性，因此此函数可能会虚假地返回 `false` 来表示后来实际上不相等的指针。
    ///
    /// 但是，当它返回 `true` 时，保证指针是不相等的。
    ///
    /// 该函数是 [`guaranteed_eq`] 的镜像，但不是其反函数。有两个指针返回 `false` 的指针比较。
    ///
    /// [`guaranteed_eq`]: #method.guaranteed_eq
    ///
    /// 返回值可能会有所不同，具体取决于编译器版本，并且不安全的代码可能不依赖于此函数的结果来确保完整性。
    /// 建议仅将此函数用于性能优化，在这种情况下，此函数的虚假 `false` 返回值不会影响结果，而只会影响性能。
    /// 尚未探讨使用此方法使运行时和编译时代码表现不同的后果。
    /// 不应使用这种方法来引入这种差异，并且在我们对这个问题有更好的理解之前，也不应使其稳定。
    ///
    ///
    ///
    ///
    ///
    ///
    #[unstable(feature = "const_raw_ptr_comparison", issue = "53020")]
    #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")]
    #[inline]
    pub const fn guaranteed_ne(self, other: *const T) -> bool
    where
        T: Sized,
    {
        intrinsics::ptr_guaranteed_ne(self, other)
    }

    /// 计算与指针的偏移量 (`.offset(count as isize)` 的便利性)。
    ///
    /// `count` 以 T 为单位; 例如，`count` 为 3 表示 `3 * size_of::<T>()` 字节的指针偏移量。
    ///
    /// # Safety
    ///
    /// 如果违反以下任一条件，则结果为未定义行为:
    ///
    /// * 起始指针和结果指针都必须在边界内或在同一个 [allocated object] 的末尾之后一个字节。
    ///
    /// * 计算的偏移量 (以字节为单位 **) 不会使 `isize` 溢出。
    ///
    /// * 偏移量不能依赖 "wrapping around" 地址空间。也就是说，无限精度和必须适合 `usize`。
    ///
    /// 编译器和标准库通常会尝试确保分配永远不会达到需要考虑偏移量的大小。
    /// 例如，`Vec` 和 `Box` 确保它们分配的字节数永远不会超过 `isize::MAX` 字节，因此 `vec.as_ptr().add(vec.len())` 始终是安全的。
    ///
    /// 从根本上说，大多数平台甚至都无法构造这样的分配。
    /// 例如，由于页表的限制或地址空间的分割，没有已知的 64 位平台可以满足 2 <sup>63</sup> 字节的请求。
    /// 但是，某些 32 位和 16 位平台可能通过物理地址扩展之类的东西成功地为超过 `isize::MAX` 字节的请求提供服务。
    ///
    /// 因此，直接从分配器获取的内存或内存映射文件 *可能* 太大而无法使用此函数进行处理。
    ///
    /// 如果这些约束难以满足，请考虑使用 [`wrapping_add`]。
    /// 此方法的唯一优点是，它可以实现更积极的编译器优化。
    ///
    /// [`wrapping_add`]: #method.wrapping_add
    /// [allocated object]: crate::ptr#allocated-object
    ///
    /// # Examples
    ///
    /// 基本用法:
    ///
    /// ```
    /// let s: &str = "123";
    /// let ptr: *const u8 = s.as_ptr();
    ///
    /// unsafe {
    ///     println!("{}", *ptr.add(1) as char);
    ///     println!("{}", *ptr.add(2) as char);
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "pointer_methods", since = "1.26.0")]
    #[must_use = "returns a new pointer rather than modifying its argument"]
    #[rustc_const_unstable(feature = "const_ptr_offset", issue = "71499")]
    #[inline(always)]
    pub const unsafe fn add(self, count: usize) -> Self
    where
        T: Sized,
    {
        // SAFETY: 调用者必须坚持 `offset` 的安全保证。
        unsafe { self.offset(count as isize) }
    }

    /// 计算与指针的偏移量 (`.offset((count as isize).wrapping_neg())` 的便利性)。
    ///
    /// `count` 以 T 为单位; 例如，`count` 为 3 表示 `3 * size_of::<T>()` 字节的指针偏移量。
    ///
    /// # Safety
    ///
    /// 如果违反以下任一条件，则结果为未定义行为:
    ///
    /// * 起始指针和结果指针都必须在边界内或在同一个 [allocated object] 的末尾之后一个字节。
    ///
    /// * 计算的偏移量不能超过 `isize::MAX` 个 **字节**。
    ///
    /// * 偏移量不能依赖 "wrapping around" 地址空间。也就是说，无限精度的总和必须适合使用大小。
    ///
    /// 编译器和标准库通常会尝试确保分配永远不会达到需要考虑偏移量的大小。
    /// 例如，`Vec` 和 `Box` 确保它们分配的字节数永远不会超过 `isize::MAX` 字节，因此 `vec.as_ptr().add(vec.len()).sub(vec.len())` 始终是安全的。
    ///
    /// 从根本上说，大多数平台甚至都无法构造这样的分配。
    /// 例如，由于页表的限制或地址空间的分割，没有已知的 64 位平台可以满足 2 <sup>63</sup> 字节的请求。
    /// 但是，某些 32 位和 16 位平台可能通过物理地址扩展之类的东西成功地为超过 `isize::MAX` 字节的请求提供服务。
    ///
    /// 因此，直接从分配器获取的内存或内存映射文件 *可能* 太大而无法使用此函数进行处理。
    ///
    /// 如果这些约束难以满足，请考虑使用 [`wrapping_sub`]。
    /// 此方法的唯一优点是，它可以实现更积极的编译器优化。
    ///
    /// [`wrapping_sub`]: #method.wrapping_sub
    /// [allocated object]: crate::ptr#allocated-object
    ///
    /// # Examples
    ///
    /// 基本用法:
    ///
    /// ```
    /// let s: &str = "123";
    ///
    /// unsafe {
    ///     let end: *const u8 = s.as_ptr().add(3);
    ///     println!("{}", *end.sub(1) as char);
    ///     println!("{}", *end.sub(2) as char);
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "pointer_methods", since = "1.26.0")]
    #[must_use = "returns a new pointer rather than modifying its argument"]
    #[rustc_const_unstable(feature = "const_ptr_offset", issue = "71499")]
    #[inline]
    pub const unsafe fn sub(self, count: usize) -> Self
    where
        T: Sized,
    {
        // SAFETY: 调用者必须坚持 `offset` 的安全保证。
        unsafe { self.offset((count as isize).wrapping_neg()) }
    }

    /// 使用换行算法计算与指针的偏移量。
    /// (为 `.wrapping_offset(count as isize)` 带来的便利)
    ///
    /// `count` 以 T 为单位; 例如，`count` 为 3 表示 `3 * size_of::<T>()` 字节的指针偏移量。
    ///
    /// # Safety
    ///
    /// 此操作本身始终是安全的，但使用结果指针则不安全。
    ///
    /// 结果指针 "remembers" 是 `self` 指向的 [allocated object]; 它不能用于读取或写入其他分配的对象。
    ///
    /// 换句话说，即使我们假设 `T` 的大小为 `1` 并且没有溢出，`let z = x.wrapping_add((y as usize) - (x as usize))` 不会使 `z` 与 `y` 相同: `z` 仍附加到对象 `x` 所附加的对象，并且解引用它是 Undefined Behavior，除非 `x` 和 `y` 指向同一分配的对象。
    ///
    /// 与 [`add`] 相比，此方法从根本上延迟了留在同一分配对象内的需求: [`add`] 是跨越对象边界时的立即未定义行为; `wrapping_add` 产生一个指针，但如果指针超出其附加对象的范围而被解引用，则仍会导致未定义行为。
    /// [`add`] 可以更好地进行优化，因此在对性能敏感的代码中更可取。
    ///
    /// 延迟检查仅考虑解引用的指针的值，而不考虑最终结果计算期间使用的中间值。
    /// 例如，`x.wrapping_add(o).wrapping_sub(o)` 始终与 `x` 相同。换句话说，允许离开已分配的对象，然后在以后重新输入它。
    ///
    /// [`add`]: #method.add
    /// [allocated object]: crate::ptr#allocated-object
    ///
    /// # Examples
    ///
    /// 基本用法:
    ///
    /// ```
    /// // 使用裸指针以两个元素为增量进行迭代
    /// 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);
    ///
    /// // 此循环打印 "1, 3, 5, "
    /// while ptr != end_rounded_up {
    ///     unsafe {
    ///         print!("{}, ", *ptr);
    ///     }
    ///     ptr = ptr.wrapping_add(step);
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "pointer_methods", since = "1.26.0")]
    #[must_use = "returns a new pointer rather than modifying its argument"]
    #[rustc_const_unstable(feature = "const_ptr_offset", issue = "71499")]
    #[inline(always)]
    pub const fn wrapping_add(self, count: usize) -> Self
    where
        T: Sized,
    {
        self.wrapping_offset(count as isize)
    }

    /// 使用换行算法计算与指针的偏移量。
    /// (为 `.wrapping_offset((count as isize).wrapping_neg())` 带来的便利)
    ///
    /// `count` 以 T 为单位; 例如，`count` 为 3 表示 `3 * size_of::<T>()` 字节的指针偏移量。
    ///
    /// # Safety
    ///
    /// 此操作本身始终是安全的，但使用结果指针则不安全。
    ///
    /// 结果指针 "remembers" 是 `self` 指向的 [allocated object]; 它不能用于读取或写入其他分配的对象。
    ///
    /// 换句话说，即使我们假设 `T` 的大小为 `1` 并且没有溢出，`let z = x.wrapping_sub((x as usize) - (y as usize))` 不会使 `z` 与 `y` 相同: `z` 仍附加到对象 `x` 所附加的对象，并且解引用它是 Undefined Behavior，除非 `x` 和 `y` 指向同一分配的对象。
    ///
    /// 与 [`sub`] 相比，此方法从根本上延迟了留在同一分配对象内的需求: [`sub`] 是跨越对象边界时的立即未定义行为; `wrapping_sub` 产生一个指针，但如果指针超出其附加对象的范围而被解引用，则仍会导致未定义行为。
    /// [`sub`] 可以更好地进行优化，因此在对性能敏感的代码中更可取。
    ///
    /// 延迟检查仅考虑解引用的指针的值，而不考虑最终结果计算期间使用的中间值。
    /// 例如，`x.wrapping_add(o).wrapping_sub(o)` 始终与 `x` 相同。换句话说，允许离开已分配的对象，然后在以后重新输入它。
    ///
    /// [`sub`]: #method.sub
    /// [allocated object]: crate::ptr#allocated-object
    ///
    /// # Examples
    ///
    /// 基本用法:
    ///
    /// ```
    /// // 使用裸指针以两个元素 (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;
    /// // 此循环打印 "5, 3, 1, "
    /// while ptr != start_rounded_down {
    ///     unsafe {
    ///         print!("{}, ", *ptr);
    ///     }
    ///     ptr = ptr.wrapping_sub(step);
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "pointer_methods", since = "1.26.0")]
    #[must_use = "returns a new pointer rather than modifying its argument"]
    #[rustc_const_unstable(feature = "const_ptr_offset", issue = "71499")]
    #[inline]
    pub const fn wrapping_sub(self, count: usize) -> Self
    where
        T: Sized,
    {
        self.wrapping_offset((count as isize).wrapping_neg())
    }

    /// 将指针值设置为 `ptr`。
    ///
    /// 如果 `self` 是指向未定义大小类型的 (fat) 指针，则此操作将仅影响指针部分，而对于指向已确定大小类型的 (thin) 指针，其作用与简单分配相同。
    ///
    /// 生成的指针将具有 `val` 的出处，即对于胖指针，此操作在语义上与使用 `val` 的数据指针值但 `self` 的元数据创建新的胖指针相同。
    ///
    ///
    /// # Examples
    ///
    /// 此函数主要用于允许对潜在的胖指针进行按字节指针算术运算:
    ///
    /// ```
    /// #![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 = ptr.set_ptr_value(thin.add(8));
    ///     # assert_eq!(*(ptr as *const i32), 3);
    ///     println!("{:?}", &*ptr); // 将打印 "3"
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[unstable(feature = "set_ptr_value", issue = "75091")]
    #[must_use = "returns a new pointer rather than modifying its argument"]
    #[inline]
    pub fn set_ptr_value(mut self, val: *const u8) -> Self {
        let thin = &mut self as *mut *const T as *mut *const u8;
        // SAFETY: 对于细指针，此操作与简单分配相同。
        // 对于胖指针，在当前胖指针布局实现中，此类指针的第一个字段始终是数据指针，该指针同样被分配。
        //
        //
        unsafe { *thin = val };
        self
    }

    /// 从 `self` 读取值而不移动它。
    /// 这将使 `self` 中的内存保持不变。
    ///
    /// 有关安全性问题和示例，请参见 [`ptr::read`]。
    ///
    /// [`ptr::read`]: crate::ptr::read()
    #[stable(feature = "pointer_methods", since = "1.26.0")]
    #[rustc_const_unstable(feature = "const_ptr_read", issue = "80377")]
    #[inline]
    pub const unsafe fn read(self) -> T
    where
        T: Sized,
    {
        // SAFETY: 调用者必须坚持 `read` 的安全保证。
        unsafe { read(self) }
    }

    /// 对 `self` 的值进行易失性读取，而无需移动它。这将使 `self` 中的内存保持不变。
    ///
    /// 易失性操作旨在作用于 I/O 存储器，并保证编译器不会在其他易失性操作中对易失性操作进行清除或重新排序。
    ///
    ///
    /// 有关安全性问题和示例，请参见 [`ptr::read_volatile`]。
    ///
    /// [`ptr::read_volatile`]: crate::ptr::read_volatile()
    ///
    ///
    #[stable(feature = "pointer_methods", since = "1.26.0")]
    #[inline]
    pub unsafe fn read_volatile(self) -> T
    where
        T: Sized,
    {
        // SAFETY: 调用者必须坚持 `read_volatile` 的安全保证。
        unsafe { read_volatile(self) }
    }

    /// 从 `self` 读取值而不移动它。
    /// 这将使 `self` 中的内存保持不变。
    ///
    /// 与 `read` 不同，指针可能未对齐。
    ///
    /// 有关安全性问题和示例，请参见 [`ptr::read_unaligned`]。
    ///
    /// [`ptr::read_unaligned`]: crate::ptr::read_unaligned()
    #[stable(feature = "pointer_methods", since = "1.26.0")]
    #[rustc_const_unstable(feature = "const_ptr_read", issue = "80377")]
    #[inline]
    pub const unsafe fn read_unaligned(self) -> T
    where
        T: Sized,
    {
        // SAFETY: 调用者必须坚持 `read_unaligned` 的安全保证。
        unsafe { read_unaligned(self) }
    }

    /// 将 `count * size_of<T>` 字节从 `self` 复制到 `dest`。
    /// 源和目标可能会重叠。
    ///
    /// NOTE: 这与 [`ptr::copy`] 具有相同的参数顺序。
    ///
    /// 有关安全性问题和示例，请参见 [`ptr::copy`]。
    ///
    /// [`ptr::copy`]: crate::ptr::copy()
    #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")]
    #[stable(feature = "pointer_methods", since = "1.26.0")]
    #[inline]
    pub const unsafe fn copy_to(self, dest: *mut T, count: usize)
    where
        T: Sized,
    {
        // SAFETY: 调用者必须坚持 `copy` 的安全保证。
        unsafe { copy(self, dest, count) }
    }

    /// 将 `count * size_of<T>` 字节从 `self` 复制到 `dest`。
    /// 源和目标可能 *不* 重叠。
    ///
    /// NOTE: 这与 [`ptr::copy_nonoverlapping`] 具有相同的参数顺序。
    ///
    /// 有关安全性问题和示例，请参见 [`ptr::copy_nonoverlapping`]。
    ///
    /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping()
    #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")]
    #[stable(feature = "pointer_methods", since = "1.26.0")]
    #[inline]
    pub const unsafe fn copy_to_nonoverlapping(self, dest: *mut T, count: usize)
    where
        T: Sized,
    {
        // SAFETY: 调用者必须坚持 `copy_nonoverlapping` 的安全保证。
        unsafe { copy_nonoverlapping(self, dest, count) }
    }

    /// 计算为使其与 `align` 对齐而需要应用到指针的偏移量。
    ///
    /// 如果无法对齐指针，则实现将返回 `usize::MAX`。
    /// 允许实现 *始终* 返回 `usize::MAX`。
    /// 只有算法的性能可以取决于此处是否可获得可用的偏移量，而不取决于其正确性。
    ///
    /// 偏移量以 `T` 元素的数量表示，而不是以字节表示。返回的值可以与 `wrapping_add` 方法一起使用。
    ///
    /// 不能保证偏移指针不会溢出或超出指针所指向的分配范围。
    ///
    /// 调用者应确保返回的偏移量在对齐方式以外的所有方面都是正确的。
    ///
    /// # Panics
    ///
    /// 如果 `align` 不是 2 的幂，则函数 panics。
    ///
    /// # Examples
    ///
    /// 将相邻的 `u8` 作为 `u16` 进行访问
    ///
    /// ```
    /// # fn foo(n: usize) {
    /// # use std::mem::align_of;
    /// # unsafe {
    /// let x = [5u8, 6u8, 7u8, 8u8, 9u8];
    /// let ptr = x.as_ptr().add(n) as *const u8;
    /// let offset = ptr.align_offset(align_of::<u16>());
    /// if offset < x.len() - n - 1 {
    ///     let u16_ptr = ptr.add(offset) as *const u16;
    ///     assert_ne!(*u16_ptr, 500);
    /// } else {
    ///     // 虽然指针可以通过 `offset` 对齐，但它会指向分配之外
    /////
    /// }
    /// # } }
    /// ```
    ///
    ///
    ///
    #[stable(feature = "align_offset", since = "1.36.0")]
    pub fn align_offset(self, align: usize) -> usize
    where
        T: Sized,
    {
        if !align.is_power_of_two() {
            panic!("align_offset: align is not a power-of-two");
        }
        // SAFETY: `align` 已被检查为 2 以上的幂
        unsafe { align_offset(self, align) }
    }
}

#[lang = "const_slice_ptr"]
impl<T> *const [T] {
    /// 返回原始切片的长度。
    ///
    /// 返回的值是 **elements** 的数量，而不是字节数。
    ///
    /// 即使原始切片由于指针为空或未对齐而无法转换为切片引用，此函数也是安全的。
    ///
    ///
    /// # Examples
    ///
    /// ```rust
    /// #![feature(slice_ptr_len)]
    ///
    /// use std::ptr;
    ///
    /// let slice: *const [i8] = ptr::slice_from_raw_parts(ptr::null(), 3);
    /// assert_eq!(slice.len(), 3);
    /// ```
    #[inline]
    #[unstable(feature = "slice_ptr_len", issue = "71146")]
    #[rustc_const_unstable(feature = "const_slice_ptr_len", issue = "71146")]
    pub const fn len(self) -> usize {
        metadata(self)
    }

    /// 将裸指针返回到切片的缓冲区。
    ///
    /// 这等效于将 `self` 强制转换为 `*const T`，但类型安全性更高。
    ///
    /// # Examples
    ///
    /// ```rust
    /// #![feature(slice_ptr_get)]
    /// use std::ptr;
    ///
    /// let slice: *const [i8] = ptr::slice_from_raw_parts(ptr::null(), 3);
    /// assert_eq!(slice.as_ptr(), 0 as *const i8);
    /// ```
    #[inline]
    #[unstable(feature = "slice_ptr_get", issue = "74265")]
    #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")]
    pub const fn as_ptr(self) -> *const T {
        self as *const T
    }

    /// 将裸指针返回到元素或子切片，而不进行边界检查。
    ///
    /// 即使未使用生成的指针，使用越界索引或无法使用 `self` 调用此方法也是 [*[undefined 行为]*。
    ///
    ///
    /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(slice_ptr_get)]
    ///
    /// let x = &[1, 2, 4] as *const [i32];
    ///
    /// unsafe {
    ///     assert_eq!(x.get_unchecked(1), x.as_ptr().add(1));
    /// }
    /// ```
    ///
    #[unstable(feature = "slice_ptr_get", issue = "74265")]
    #[inline]
    pub unsafe fn get_unchecked<I>(self, index: I) -> *const I::Output
    where
        I: SliceIndex<[T]>,
    {
        // SAFETY: 调用方确保 `self` 是可解引用的，并且 `index` 是入站的。
        unsafe { index.get_unchecked(self) }
    }

    /// 如果指针为空，则返回 `None`，否则返回共享切片到 `Some` 中包装的值。
    /// 与 [`as_ref`] 相比，这不需要将该值初始化。
    ///
    /// [`as_ref`]: #method.as_ref
    ///
    /// # Safety
    ///
    /// 调用此方法时，您必须确保要么指针是空的，要么以下所有内容都为真::
    ///
    /// * 指针必须为 [有效][valid] 的，才能读取许多字节的 `ptr.len() * mem::size_of::<T>()`，并且必须正确对齐。这尤其意味着:
    ///
    ///     * 整个内存范围必须包含在单个 [allocated object] 内!
    ///       切片永远不能跨越多个分配的对象。
    ///
    ///     * 即使对于零长度的切片，指针也必须对齐。
    ///     这样做的一个原因是，枚举布局优化可能依赖于对齐的引用 (包括任何长度的切片) 和非空值，以将它们与其他数据区分开。
    ///
    ///     您可以使用 [`NonNull::dangling()`] 获得可用作零长度切片的 `data` 的指针。
    ///
    /// * 切片的总大小 `ptr.len() * mem::size_of::<T>()` 不能大于 `isize::MAX`。
    ///   请参见 [`pointer::offset`] 的安全文档。
    ///
    /// * 您必须执行 Rust 的别名规则，因为返回的生命周期 `'a` 是任意选择的，不一定反映数据的实际生命周期。
    ///   特别是，在此生命周期的持续时间内，指针所指向的内存一定不能被可变的 (`UnsafeCell` 内部除外)。
    ///
    /// 即使未使用此方法的结果也是如此!
    ///
    /// 另请参见 [`slice::from_raw_parts`][]。
    ///
    /// [valid]: crate::ptr#safety
    /// [allocated object]: crate::ptr#allocated-object
    ///
    ///
    ///
    ///
    ///
    ///
    #[inline]
    #[unstable(feature = "ptr_as_uninit", issue = "75402")]
    pub unsafe fn as_uninit_slice<'a>(self) -> Option<&'a [MaybeUninit<T>]> {
        if self.is_null() {
            None
        } else {
            // SAFETY: 调用者必须坚持 `as_uninit_slice` 的安全保证。
            Some(unsafe { slice::from_raw_parts(self as *const MaybeUninit<T>, self.len()) })
        }
    }
}

// 指针相等
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> PartialEq for *const T {
    #[inline]
    fn eq(&self, other: &*const T) -> bool {
        *self == *other
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Eq for *const T {}

// 指针比较
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Ord for *const T {
    #[inline]
    fn cmp(&self, other: &*const T) -> Ordering {
        if self < other {
            Less
        } else if self == other {
            Equal
        } else {
            Greater
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> PartialOrd for *const T {
    #[inline]
    fn partial_cmp(&self, other: &*const T) -> Option<Ordering> {
        Some(self.cmp(other))
    }

    #[inline]
    fn lt(&self, other: &*const T) -> bool {
        *self < *other
    }

    #[inline]
    fn le(&self, other: &*const T) -> bool {
        *self <= *other
    }

    #[inline]
    fn gt(&self, other: &*const T) -> bool {
        *self > *other
    }

    #[inline]
    fn ge(&self, other: &*const T) -> bool {
        *self >= *other
    }
}