use crate::cmp::Ordering;
use crate::convert::From;
use crate::fmt;
use crate::hash;
use crate::intrinsics::assert_unsafe_precondition;
use crate::marker::Unsize;
use crate::mem::{self, MaybeUninit};
use crate::num::NonZeroUsize;
use crate::ops::{CoerceUnsized, DispatchFromDyn};
use crate::ptr::Unique;
use crate::slice::{self, SliceIndex};

/// `*mut T` 但非零和 [covariant]。
///
/// 在使用裸指针构建数据结构时，这通常是正确的选择，但由于其额外的属性，最终使用起来更加危险。如果不确定是否应使用 `NonNull<T>`，请使用 `*mut T`!
///
/// 与 `*mut T` 不同，即使从未解引用指针，指针也必须始终为非 null。这样一来，枚举就可以将此禁止值用作判别式 - `Option<NonNull<T>>` 与 `*mut T` 具有相同的大小。
/// 但是，如果指针未解引用，它可能仍会悬垂。
///
/// 与 `*mut T` 不同，选择 `NonNull<T>` 作为 `T` 的协变。这样就可以在构建协变类型时使用 `NonNull<T>`，但是如果在实际上不应该协变的类型中使用，则会带来不健全的风险。
/// (尽管从技术上讲，不健全只能由调用不安全的函数引起，但对于 `*mut T` 却做出了相反的选择。)
///
/// 对于大多数安全抽象，例如 `Box`，`Rc`，`Arc`，`Vec` 和 `LinkedList`，协方差是正确的。之所以如此，是因为它们提供了遵循 Rust 的常规共享 XOR 可变规则的公共 API。
///
/// 如果您的类型不能安全地协变，则必须确保它包含一些附加字段以提供不变性。通常，此字段是 [`PhantomData`] 类型，例如 `PhantomData<Cell<T>>` 或 `PhantomData<&'a mut T>`。
///
/// 请注意，`NonNull<T>` 具有 `&T` 的 `From` 实例。但是，这不会改变以下事实：除非通过 [`UnsafeCell<T>`] 内部发生可变的，否则通过 (从 a 派生的指针) 进行共享引用的可变的是未定义的行为。从共享引用创建变量引用也是如此。
///
/// 当使用不带 `UnsafeCell<T>` 的 `From` 实例时，您有责任确保从不调用 `as_mut`，并且从不使用 `as_ptr` 进行可变的。
///
/// [covariant]: https://doc.rust-lang.org/reference/subtyping.html
/// [`PhantomData`]: crate::marker::PhantomData
/// [`UnsafeCell<T>`]: crate::cell::UnsafeCell
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "nonnull", since = "1.25.0")]
#[repr(transparent)]
#[rustc_layout_scalar_valid_range_start(1)]
#[rustc_nonnull_optimization_guaranteed]
pub struct NonNull<T: ?Sized> {
    pointer: *const T,
}

/// `NonNull` 指针不是 `Send`，因为它们引用的数据可能是别名。
// 注意，此暗示不是必需的，但应提供更好的错误消息。
#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> !Send for NonNull<T> {}

/// `NonNull` 指针不是 `Sync`，因为它们引用的数据可能是别名。
// 注意，此暗示不是必需的，但应提供更好的错误消息。
#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> !Sync for NonNull<T> {}

impl<T: Sized> NonNull<T> {
    /// 创建一个悬垂但对齐良好的新 `NonNull`。
    ///
    /// 与 `Vec::new` 一样，这对于初始化延迟分配的类型很有用。
    ///
    /// 请注意，该指针值可能表示一个指向 `T` 的有效指针，这意味着不得将其用作 "尚未初始化" 标记值。
    /// 延迟分配的类型必须通过其他某种方式来跟踪初始化。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ptr::NonNull;
    ///
    /// let ptr = NonNull::<u32>::dangling();
    /// // 重要提示：不要尝试访问 `ptr` 的值而不先初始化它！ 指针不为空，但也无效！
    /////
    /// ```
    ///
    ///
    ///
    #[stable(feature = "nonnull", since = "1.25.0")]
    #[rustc_const_stable(feature = "const_nonnull_dangling", since = "1.36.0")]
    #[must_use]
    #[inline]
    pub const fn dangling() -> Self {
        // SAFETY: mem::align_of () 返回一个非零的 usize，然后将其强制转换为 *mut T。
        // 因此，`ptr` 不为空，并且遵守了调用 new_unchecked() 的条件。
        //
        unsafe {
            let ptr = crate::ptr::invalid_mut::<T>(mem::align_of::<T>());
            NonNull::new_unchecked(ptr)
        }
    }

    /// 返回该值的共享引用。与 [`as_ref`] 相比，这不需要将该值初始化。
    ///
    /// 对于可变的对应物，请参见 [`as_uninit_mut`]。
    ///
    /// [`as_ref`]: NonNull::as_ref
    /// [`as_uninit_mut`]: NonNull::as_uninit_mut
    ///
    /// # Safety
    ///
    /// 调用此方法时，必须确保满足以下所有条件：
    ///
    /// * 指针必须正确对齐。
    ///
    /// * 在 [模块的文档][the module documentation] 中定义的含义上，它必须是 "dereferenceable"。
    ///
    /// * 您必须执行 Rust 的别名规则，因为返回的生命周期 `'a` 是任意选择的，不一定反映数据的实际生命周期。
    ///
    ///   特别是，当这个引用存在时，指针指向的内存不能发生可变 (`UnsafeCell` 内部除外)。
    ///
    /// 即使未使用此方法的结果也是如此！
    ///
    /// [the module documentation]: crate::ptr#safety
    ///
    ///
    #[inline]
    #[must_use]
    #[unstable(feature = "ptr_as_uninit", issue = "75402")]
    #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
    pub const unsafe fn as_uninit_ref<'a>(self) -> &'a MaybeUninit<T> {
        // SAFETY: 调用者必须保证 `self` 满足引用的所有要求。
        //
        unsafe { &*self.cast().as_ptr() }
    }

    /// 返回该值的唯一引用。与 [`as_mut`] 相比，这不需要将该值初始化。
    ///
    /// 有关共享副本，请参见 [`as_uninit_ref`]。
    ///
    /// [`as_mut`]: NonNull::as_mut
    /// [`as_uninit_ref`]: NonNull::as_uninit_ref
    ///
    /// # Safety
    ///
    /// 调用此方法时，必须确保满足以下所有条件：
    ///
    /// * 指针必须正确对齐。
    ///
    /// * 在 [模块的文档][the module documentation] 中定义的含义上，它必须是 "dereferenceable"。
    ///
    /// * 您必须执行 Rust 的别名规则，因为返回的生命周期 `'a` 是任意选择的，不一定反映数据的实际生命周期。
    ///
    ///   特别是，当这个引用存在时，指针指向的内存不能通过任何其他指针访问 (读取或写入)。
    ///
    /// 即使未使用此方法的结果也是如此！
    ///
    /// [the module documentation]: crate::ptr#safety
    ///
    ///
    #[inline]
    #[must_use]
    #[unstable(feature = "ptr_as_uninit", issue = "75402")]
    #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
    pub const unsafe fn as_uninit_mut<'a>(self) -> &'a mut MaybeUninit<T> {
        // SAFETY: 调用者必须保证 `self` 满足引用的所有要求。
        //
        unsafe { &mut *self.cast().as_ptr() }
    }
}

impl<T: ?Sized> NonNull<T> {
    /// 创建一个新的 `NonNull`。
    ///
    /// # Safety
    ///
    /// `ptr` 必须不能为空。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ptr::NonNull;
    ///
    /// let mut x = 0u32;
    /// let ptr = unsafe { NonNull::new_unchecked(&mut x as *mut _) };
    /// ```
    ///
    /// 此函数的不正确用法：
    ///
    /// ```rust,no_run
    /// use std::ptr::NonNull;
    ///
    /// // 永远不要这样做！! ! 这是未定义的行为。⚠️
    /// let ptr = unsafe { NonNull::<u32>::new_unchecked(std::ptr::null_mut()) };
    /// ```
    #[stable(feature = "nonnull", since = "1.25.0")]
    #[rustc_const_stable(feature = "const_nonnull_new_unchecked", since = "1.25.0")]
    #[inline]
    pub const unsafe fn new_unchecked(ptr: *mut T) -> Self {
        // SAFETY: 调用者必须保证 `ptr` 不为空。
        unsafe {
            assert_unsafe_precondition!("NonNull::new_unchecked requires that the pointer is non-null", [T: ?Sized](ptr: *mut T) => !ptr.is_null());
            NonNull { pointer: ptr as _ }
        }
    }

    /// 如果 `ptr` 不为空，则创建一个新的 `NonNull`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ptr::NonNull;
    ///
    /// let mut x = 0u32;
    /// let ptr = NonNull::<u32>::new(&mut x as *mut _).expect("ptr is null!");
    ///
    /// if let Some(ptr) = NonNull::<u32>::new(std::ptr::null_mut()) {
    ///     unreachable!();
    /// }
    /// ```
    #[stable(feature = "nonnull", since = "1.25.0")]
    #[rustc_const_unstable(feature = "const_nonnull_new", issue = "93235")]
    #[inline]
    pub const fn new(ptr: *mut T) -> Option<Self> {
        if !ptr.is_null() {
            // SAFETY: 指针已被检查并且不为 null
            Some(unsafe { Self::new_unchecked(ptr) })
        } else {
            None
        }
    }

    /// 执行与 [`std::ptr::from_raw_parts`] 相同的功能，除了返回 `NonNull` 指针 (与原始 `*const` 指针相反)。
    ///
    ///
    /// 有关更多详细信息，请参见 [`std::ptr::from_raw_parts`] 的文档。
    ///
    /// [`std::ptr::from_raw_parts`]: crate::ptr::from_raw_parts
    #[unstable(feature = "ptr_metadata", issue = "81513")]
    #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")]
    #[inline]
    pub const fn from_raw_parts(
        data_address: NonNull<()>,
        metadata: <T as super::Pointee>::Metadata,
    ) -> NonNull<T> {
        // SAFETY: `ptr::from::raw_parts_mut` 的结果为非空值，因为 `data_address` 为非。
        unsafe {
            NonNull::new_unchecked(super::from_raw_parts_mut(data_address.as_ptr(), metadata))
        }
    }

    /// 将指针 (可能是宽指针) 分解为其地址和元数据组件。
    ///
    /// 以后可以使用 [`NonNull::from_raw_parts`] 重建指针。
    #[unstable(feature = "ptr_metadata", issue = "81513")]
    #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")]
    #[must_use = "this returns the result of the operation, \
                  without modifying the original"]
    #[inline]
    pub const fn to_raw_parts(self) -> (NonNull<()>, <T as super::Pointee>::Metadata) {
        (self.cast(), super::metadata(self.as_ptr()))
    }

    /// 获取指针的 "address" 部分。
    ///
    /// 有关更多详细信息，请参见裸指针上的等效方法 [`pointer::addr`]。
    ///
    /// 此 API 及其声明的语义是 Strict Provenance 实验的一部分，请参见 [`ptr` module documentation][crate::ptr]。
    ///
    #[must_use]
    #[inline]
    #[unstable(feature = "strict_provenance", issue = "95228")]
    pub fn addr(self) -> NonZeroUsize {
        // SAFETY: 指针由类型保证为非空，这意味着地址将非零。
        //
        unsafe { NonZeroUsize::new_unchecked(self.pointer.addr()) }
    }

    /// 使用给定地址创建一个新指针。
    ///
    /// 有关更多详细信息，请参见裸指针上的等效方法 [`pointer::with_addr`]。
    ///
    /// 此 API 及其声明的语义是 Strict Provenance 实验的一部分，请参见 [`ptr` module documentation][crate::ptr]。
    ///
    #[must_use]
    #[inline]
    #[unstable(feature = "strict_provenance", issue = "95228")]
    pub fn with_addr(self, addr: NonZeroUsize) -> Self {
        // SAFETY: `ptr::from::with_addr` 的结果是非空的，因为 `addr` 保证非零。
        unsafe { NonNull::new_unchecked(self.pointer.with_addr(addr.get()) as *mut _) }
    }

    /// 通过将 `self` 的地址映射到新地址来创建新指针。
    ///
    /// 有关更多详细信息，请参见裸指针上的等效方法 [`pointer::map_addr`]。
    ///
    /// 此 API 及其声明的语义是 Strict Provenance 实验的一部分，请参见 [`ptr` module documentation][crate::ptr]。
    ///
    #[must_use]
    #[inline]
    #[unstable(feature = "strict_provenance", issue = "95228")]
    pub fn map_addr(self, f: impl FnOnce(NonZeroUsize) -> NonZeroUsize) -> Self {
        self.with_addr(f(self.addr()))
    }

    /// 获取底层的 `*mut` 指针。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ptr::NonNull;
    ///
    /// let mut x = 0u32;
    /// let ptr = NonNull::new(&mut x).expect("ptr is null!");
    ///
    /// let x_value = unsafe { *ptr.as_ptr() };
    /// assert_eq!(x_value, 0);
    ///
    /// unsafe { *ptr.as_ptr() += 2; }
    /// let x_value = unsafe { *ptr.as_ptr() };
    /// assert_eq!(x_value, 2);
    /// ```
    #[stable(feature = "nonnull", since = "1.25.0")]
    #[rustc_const_stable(feature = "const_nonnull_as_ptr", since = "1.32.0")]
    #[must_use]
    #[inline(always)]
    pub const fn as_ptr(self) -> *mut T {
        self.pointer as *mut T
    }

    /// 返回该值的共享引用。如果该值可能未初始化，则必须改用 [`as_uninit_ref`]。
    ///
    /// 对于可变的对应物，请参见 [`as_mut`]。
    ///
    /// [`as_uninit_ref`]: NonNull::as_uninit_ref
    /// [`as_mut`]: NonNull::as_mut
    ///
    /// # Safety
    ///
    /// 调用此方法时，必须确保满足以下所有条件：
    ///
    /// * 指针必须正确对齐。
    ///
    /// * 在 [模块的文档][the module documentation] 中定义的含义上，它必须是 "dereferenceable"。
    ///
    /// * 指针必须指向 `T` 的初始化实例。
    ///
    /// * 您必须执行 Rust 的别名规则，因为返回的生命周期 `'a` 是任意选择的，不一定反映数据的实际生命周期。
    ///
    ///   特别是，当这个引用存在时，指针指向的内存不能发生可变 (`UnsafeCell` 内部除外)。
    ///
    /// 即使未使用此方法的结果也是如此！
    /// (关于初始化的部分尚未完全决定，但是直到确定之前，唯一安全的方法是确保它们确实被初始化。)
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ptr::NonNull;
    ///
    /// let mut x = 0u32;
    /// let ptr = NonNull::new(&mut x as *mut _).expect("ptr is null!");
    ///
    /// let ref_x = unsafe { ptr.as_ref() };
    /// println!("{ref_x}");
    /// ```
    ///
    /// [the module documentation]: crate::ptr#safety
    ///
    ///
    ///
    #[stable(feature = "nonnull", since = "1.25.0")]
    #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
    #[must_use]
    #[inline(always)]
    pub const unsafe fn as_ref<'a>(&self) -> &'a T {
        // SAFETY: 调用者必须保证 `self` 满足引用的所有要求。
        //
        unsafe { &*self.as_ptr() }
    }

    /// 返回该值的唯一引用。如果该值可能未初始化，则必须改用 [`as_uninit_mut`]。
    ///
    /// 有关共享副本，请参见 [`as_ref`]。
    ///
    /// [`as_uninit_mut`]: NonNull::as_uninit_mut
    /// [`as_ref`]: NonNull::as_ref
    ///
    /// # Safety
    ///
    /// 调用此方法时，必须确保满足以下所有条件：
    ///
    /// * 指针必须正确对齐。
    ///
    /// * 在 [模块的文档][the module documentation] 中定义的含义上，它必须是 "dereferenceable"。
    ///
    /// * 指针必须指向 `T` 的初始化实例。
    ///
    /// * 您必须执行 Rust 的别名规则，因为返回的生命周期 `'a` 是任意选择的，不一定反映数据的实际生命周期。
    ///
    ///   特别是，当这个引用存在时，指针指向的内存不能通过任何其他指针访问 (读取或写入)。
    ///
    /// 即使未使用此方法的结果也是如此！
    /// (关于初始化的部分尚未完全决定，但是直到确定之前，唯一安全的方法是确保它们确实被初始化。)
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ptr::NonNull;
    ///
    /// let mut x = 0u32;
    /// let mut ptr = NonNull::new(&mut x).expect("null pointer");
    ///
    /// let x_ref = unsafe { ptr.as_mut() };
    /// assert_eq!(*x_ref, 0);
    /// *x_ref += 2;
    /// assert_eq!(*x_ref, 2);
    /// ```
    ///
    /// [the module documentation]: crate::ptr#safety
    ///
    ///
    #[stable(feature = "nonnull", since = "1.25.0")]
    #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
    #[must_use]
    #[inline(always)]
    pub const unsafe fn as_mut<'a>(&mut self) -> &'a mut T {
        // SAFETY: 调用者必须保证 `self` 满足可变引用的所有要求。
        //
        unsafe { &mut *self.as_ptr() }
    }

    /// 强制转换为另一种类型的指针。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ptr::NonNull;
    ///
    /// let mut x = 0u32;
    /// let ptr = NonNull::new(&mut x as *mut _).expect("null pointer");
    ///
    /// let casted_ptr = ptr.cast::<i8>();
    /// let raw_ptr: *mut i8 = casted_ptr.as_ptr();
    /// ```
    #[stable(feature = "nonnull_cast", since = "1.27.0")]
    #[rustc_const_stable(feature = "const_nonnull_cast", since = "1.36.0")]
    #[must_use = "this returns the result of the operation, \
                  without modifying the original"]
    #[inline]
    pub const fn cast<U>(self) -> NonNull<U> {
        // SAFETY: `self` 是一个 `NonNull` 指针，该指针必须非空
        unsafe { NonNull::new_unchecked(self.as_ptr() as *mut U) }
    }

    /// 有关语义和安全要求，请参见 [`pointer::add`]。
    #[inline]
    pub(crate) const unsafe fn add(self, delta: usize) -> Self
    where
        T: Sized,
    {
        // SAFETY: 我们要求增量保持在对象的范围内，因此它不能变为空，因为这需要包装地址空间，而合法对象不允许这样做。
        //
        // 调用者承诺 `delta` 可以正常添加。
        //
        unsafe { NonNull { pointer: self.pointer.add(delta) } }
    }
}

impl<T> NonNull<[T]> {
    /// 根据细指针和长度创建非空的原始切片。
    ///
    /// `len` 参数是 **元素** 的数量，而不是字节数。
    ///
    /// 此函数是安全的，但解引用的返回值不安全。
    /// 有关切片的安全要求，请参见 [`slice::from_raw_parts`] 的文档。
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::ptr::NonNull;
    ///
    /// // 从指向第一个元素的指针开始创建切片指针
    /// let mut x = [5, 6, 7];
    /// let nonnull_pointer = NonNull::new(x.as_mut_ptr()).unwrap();
    /// let slice = NonNull::slice_from_raw_parts(nonnull_pointer, 3);
    /// assert_eq!(unsafe { slice.as_ref()[2] }, 7);
    /// ```
    ///
    /// (请注意，此示例人为地演示了此方法的用法，但是 `let slice = NonNull::from(&x[..]);` 是编写这样的代码的更好方法。)
    ///
    #[stable(feature = "nonnull_slice_from_raw_parts", since = "1.70.0")]
    #[rustc_const_unstable(feature = "const_slice_from_raw_parts_mut", issue = "67456")]
    #[must_use]
    #[inline]
    pub const fn slice_from_raw_parts(data: NonNull<T>, len: usize) -> Self {
        // SAFETY: `data` 是一个 `NonNull` 指针，该指针必须非空
        unsafe { Self::new_unchecked(super::slice_from_raw_parts_mut(data.as_ptr(), len)) }
    }

    /// 返回非空原始切片的长度。
    ///
    /// 返回的值是 **元素** 的数量，而不是字节数。
    ///
    /// 即使由于指针没有有效地址而无法将非空原始切片重新引用到切片时，此函数也是安全的。
    ///
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::ptr::NonNull;
    ///
    /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
    /// assert_eq!(slice.len(), 3);
    /// ```
    #[stable(feature = "slice_ptr_len_nonnull", since = "1.63.0")]
    #[rustc_const_stable(feature = "const_slice_ptr_len_nonnull", since = "1.63.0")]
    #[rustc_allow_const_fn_unstable(const_slice_ptr_len)]
    #[must_use]
    #[inline]
    pub const fn len(self) -> usize {
        self.as_ptr().len()
    }

    /// 返回指向切片缓冲区的非 null 指针。
    ///
    /// # Examples
    ///
    /// ```rust
    /// #![feature(slice_ptr_get)]
    /// use std::ptr::NonNull;
    ///
    /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
    /// assert_eq!(slice.as_non_null_ptr(), NonNull::<i8>::dangling());
    /// ```
    #[inline]
    #[must_use]
    #[unstable(feature = "slice_ptr_get", issue = "74265")]
    #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")]
    pub const fn as_non_null_ptr(self) -> NonNull<T> {
        // SAFETY: 我们知道 `self` 不为空。
        unsafe { NonNull::new_unchecked(self.as_ptr().as_mut_ptr()) }
    }

    /// 将裸指针返回到切片的缓冲区。
    ///
    /// # Examples
    ///
    /// ```rust
    /// #![feature(slice_ptr_get)]
    /// use std::ptr::NonNull;
    ///
    /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
    /// assert_eq!(slice.as_mut_ptr(), NonNull::<i8>::dangling().as_ptr());
    /// ```
    #[inline]
    #[must_use]
    #[unstable(feature = "slice_ptr_get", issue = "74265")]
    #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")]
    pub const fn as_mut_ptr(self) -> *mut T {
        self.as_non_null_ptr().as_ptr()
    }

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

    /// 返回可能未初始化值的切片的唯一引用。与 [`as_mut`] 相比，这不需要将该值初始化。
    ///
    /// 有关共享副本，请参见 [`as_uninit_slice`]。
    ///
    /// [`as_mut`]: NonNull::as_mut
    /// [`as_uninit_slice`]: NonNull::as_uninit_slice
    ///
    /// # Safety
    ///
    /// 调用此方法时，必须确保满足以下所有条件：
    ///
    /// * 指针必须是 [有效][valid] 的才能进行 `ptr.len() * mem::size_of::<T>()` 多个字节的读取和写入，并且必须正确对齐。这尤其意味着：
    ///
    ///     * 该切片的整个存储范围必须包含在一个分配的对象中！
    ///       切片永远不能跨越多个分配的对象。
    ///
    ///     * 即使对于零长度的切片，指针也必须对齐。
    ///     这样做的一个原因是，枚举布局优化可能依赖于对齐的引用 (包括任何长度的切片) 和非空值，以将它们与其他数据区分开。
    ///
    ///     您可以使用 [`NonNull::dangling()`] 获得可用作零长度切片的 `data` 的指针。
    ///
    /// * 切片的总大小 `ptr.len() * mem::size_of::<T>()` 不能大于 `isize::MAX`。
    ///   请参见 [`pointer::offset`] 的安全文档。
    ///
    /// * 您必须执行 Rust 的别名规则，因为返回的生命周期 `'a` 是任意选择的，不一定反映数据的实际生命周期。
    ///   特别是，当这个引用存在时，指针指向的内存不能通过任何其他指针访问 (读取或写入)。
    ///
    /// 即使未使用此方法的结果也是如此！
    ///
    /// 另请参见 [`slice::from_raw_parts_mut`]。
    ///
    /// [valid]: crate::ptr#safety
    ///
    /// # Examples
    ///
    /// ```rust
    /// #![feature(allocator_api, ptr_as_uninit)]
    ///
    /// use std::alloc::{Allocator, Layout, Global};
    /// use std::mem::MaybeUninit;
    /// use std::ptr::NonNull;
    ///
    /// let memory: NonNull<[u8]> = Global.allocate(Layout::new::<[u8; 32]>())?;
    /// // 这是安全的，因为 `memory` 对于许多字节的 `memory.len()` 读和写有效。
    /// // 请注意，此处不允许调用 `memory.as_mut()`，因为内容可能未初始化。
    /// # #[allow(unused_variables)]
    /// let slice: &mut [MaybeUninit<u8>] = unsafe { memory.as_uninit_slice_mut() };
    /// # Ok::<_, std::alloc::AllocError>(())
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[inline]
    #[must_use]
    #[unstable(feature = "ptr_as_uninit", issue = "75402")]
    #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
    pub const unsafe fn as_uninit_slice_mut<'a>(self) -> &'a mut [MaybeUninit<T>] {
        // SAFETY: 调用者必须遵守 `as_uninit_slice_mut` 的安全保证。
        unsafe { slice::from_raw_parts_mut(self.cast().as_ptr(), self.len()) }
    }

    /// 将裸指针返回到元素或子切片，而不进行边界检查。
    ///
    /// 使用越界索引或当 `self` 不可解引用时调用此方法是 *[未定义行为][undefined behavior]*，即使未使用结果指针。
    ///
    ///
    /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(slice_ptr_get)]
    /// use std::ptr::NonNull;
    ///
    /// let x = &mut [1, 2, 4];
    /// let x = NonNull::slice_from_raw_parts(NonNull::new(x.as_mut_ptr()).unwrap(), x.len());
    ///
    /// unsafe {
    ///     assert_eq!(x.get_unchecked_mut(1).as_ptr(), x.as_non_null_ptr().as_ptr().add(1));
    /// }
    /// ```
    ///
    #[unstable(feature = "slice_ptr_get", issue = "74265")]
    #[inline]
    pub unsafe fn get_unchecked_mut<I>(self, index: I) -> NonNull<I::Output>
    where
        I: SliceIndex<[T]>,
    {
        // SAFETY: 调用者确保 `self` 是可解引用的，并且 `index` 在边界内。
        // 因此，得到的指针不能为空。
        unsafe { NonNull::new_unchecked(self.as_ptr().get_unchecked_mut(index)) }
    }
}

#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> Clone for NonNull<T> {
    #[inline(always)]
    fn clone(&self) -> Self {
        *self
    }
}

#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> Copy for NonNull<T> {}

#[unstable(feature = "coerce_unsized", issue = "18598")]
impl<T: ?Sized, U: ?Sized> CoerceUnsized<NonNull<U>> for NonNull<T> where T: Unsize<U> {}

#[unstable(feature = "dispatch_from_dyn", issue = "none")]
impl<T: ?Sized, U: ?Sized> DispatchFromDyn<NonNull<U>> for NonNull<T> where T: Unsize<U> {}

#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> fmt::Debug for NonNull<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Pointer::fmt(&self.as_ptr(), f)
    }
}

#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> fmt::Pointer for NonNull<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Pointer::fmt(&self.as_ptr(), f)
    }
}

#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> Eq for NonNull<T> {}

#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> PartialEq for NonNull<T> {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.as_ptr() == other.as_ptr()
    }
}

#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> Ord for NonNull<T> {
    #[inline]
    fn cmp(&self, other: &Self) -> Ordering {
        self.as_ptr().cmp(&other.as_ptr())
    }
}

#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> PartialOrd for NonNull<T> {
    #[inline]
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        self.as_ptr().partial_cmp(&other.as_ptr())
    }
}

#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> hash::Hash for NonNull<T> {
    #[inline]
    fn hash<H: hash::Hasher>(&self, state: &mut H) {
        self.as_ptr().hash(state)
    }
}

#[unstable(feature = "ptr_internals", issue = "none")]
impl<T: ?Sized> From<Unique<T>> for NonNull<T> {
    #[inline]
    fn from(unique: Unique<T>) -> Self {
        // SAFETY: 唯一指针不能为空，因此必须遵守 new_unchecked() 的条件。
        //
        unsafe { NonNull::new_unchecked(unique.as_ptr()) }
    }
}

#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> From<&mut T> for NonNull<T> {
    /// 将 `&mut T` 转换为 `NonNull<T>`。
    ///
    /// 这种转换是安全且可靠的，因为引用不能为空。
    #[inline]
    fn from(reference: &mut T) -> Self {
        // SAFETY: 可变引用不能为空。
        unsafe { NonNull { pointer: reference as *mut T } }
    }
}

#[stable(feature = "nonnull", since = "1.25.0")]
impl<T: ?Sized> From<&T> for NonNull<T> {
    /// 将 `&T` 转换为 `NonNull<T>`。
    ///
    /// 这种转换是安全且可靠的，因为引用不能为空。
    #[inline]
    fn from(reference: &T) -> Self {
        // SAFETY: 引用不能为空，因此必须遵守 new_unchecked() 的条件。
        //
        unsafe { NonNull { pointer: reference as *const T } }
    }
}