Struct std::ptr::NonNull

#[repr(transparent)]
pub struct NonNull<T>where
    T: ?Sized,{ /* private fields */ }

*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 进行可变的。

Implementations

impl<T> NonNull<T>

pub const fn dangling() -> NonNull<T>

创建一个悬垂但对齐良好的新 NonNull。

与 Vec::new 一样，这对于初始化延迟分配的类型很有用。

请注意，该指针值可能表示一个指向 T 的有效指针，这意味着不得将其用作 “尚未初始化” 标记值。 延迟分配的类型必须通过其他某种方式来跟踪初始化。

Examples

use std::ptr::NonNull;

let ptr = NonNull::<u32>::dangling();
// 重要提示：不要尝试访问 `ptr` 的值而不先初始化它！ 指针不为空，但也无效！

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

🔬This is a nightly-only experimental API. (ptr_as_uninit #75402)

返回该值的共享引用。与 as_ref 相比，这不需要将该值初始化。

对于可变的对应物，请参见 as_uninit_mut。

Safety

调用此方法时，必须确保满足以下所有条件：

• 指针必须正确对齐。

• 在 模块的文档 中定义的含义上，它必须是 “dereferenceable”。

• 您必须执行 Rust 的别名规则，因为返回的生命周期 'a 是任意选择的，不一定反映数据的实际生命周期。

  特别是，当这个引用存在时，指针指向的内存不能发生可变 (UnsafeCell 内部除外)。

即使未使用此方法的结果也是如此！

pub unsafe fn as_uninit_mut<'a>(self) -> &'a mut MaybeUninit<T>

🔬This is a nightly-only experimental API. (ptr_as_uninit #75402)

返回该值的唯一引用。与 as_mut 相比，这不需要将该值初始化。

有关共享副本，请参见 as_uninit_ref。

Safety

调用此方法时，必须确保满足以下所有条件：

• 指针必须正确对齐。

• 在 模块的文档 中定义的含义上，它必须是 “dereferenceable”。

• 您必须执行 Rust 的别名规则，因为返回的生命周期 'a 是任意选择的，不一定反映数据的实际生命周期。

  特别是，当这个引用存在时，指针指向的内存不能通过任何其他指针访问 (读取或写入)。

即使未使用此方法的结果也是如此！

impl<T> NonNull<T>where T: ?Sized,

pub const unsafe fn new_unchecked(ptr: *mut T) -> NonNull<T>

创建一个新的 NonNull。

Safety

ptr 必须不能为空。

Examples

use std::ptr::NonNull;

let mut x = 0u32;
let ptr = unsafe { NonNull::new_unchecked(&mut x as *mut _) };

此函数的不正确用法：

use std::ptr::NonNull;

// 永远不要这样做！! ! 这是未定义的行为。⚠️
let ptr = unsafe { NonNull::<u32>::new_unchecked(std::ptr::null_mut()) };

pub fn new(ptr: *mut T) -> Option<NonNull<T>>

如果 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!();
}

pub fn from_raw_parts( data_address: NonNull<()>, metadata: <T as Pointee>::Metadata ) -> NonNull<T>

🔬This is a nightly-only experimental API. (ptr_metadata #81513)

执行与 std::ptr::from_raw_parts 相同的功能，除了返回 NonNull 指针 (与原始 *const 指针相反)。

有关更多详细信息，请参见 std::ptr::from_raw_parts 的文档。

pub fn to_raw_parts(self) -> (NonNull<()>, <T as Pointee>::Metadata)

🔬This is a nightly-only experimental API. (ptr_metadata #81513)

将指针 (可能是宽指针) 分解为其地址和元数据组件。

以后可以使用 NonNull::from_raw_parts 重建指针。

pub fn addr(self) -> NonZeroUsize

🔬This is a nightly-only experimental API. (strict_provenance #95228)

获取指针的 “address” 部分。

有关更多详细信息，请参见裸指针上的等效方法 pointer::addr。

此 API 及其声明的语义是 Strict Provenance 实验的一部分，请参见 ptr module documentation。

pub fn with_addr(self, addr: NonZeroUsize) -> NonNull<T>

🔬This is a nightly-only experimental API. (strict_provenance #95228)

使用给定地址创建一个新指针。

有关更多详细信息，请参见裸指针上的等效方法 pointer::with_addr。

此 API 及其声明的语义是 Strict Provenance 实验的一部分，请参见 ptr module documentation。

pub fn map_addr( self, f: impl FnOnce(NonZeroUsize) -> NonZeroUsize ) -> NonNull<T>

🔬This is a nightly-only experimental API. (strict_provenance #95228)

通过将 self 的地址映射到新地址来创建新指针。

有关更多详细信息，请参见裸指针上的等效方法 pointer::map_addr。

此 API 及其声明的语义是 Strict Provenance 实验的一部分，请参见 ptr module documentation。

pub const fn as_ptr(self) -> *mut T

获取底层的 *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);

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

返回该值的共享引用。如果该值可能未初始化，则必须改用 as_uninit_ref。

对于可变的对应物，请参见 as_mut。

Safety

调用此方法时，必须确保满足以下所有条件：

• 指针必须正确对齐。

• 在 模块的文档 中定义的含义上，它必须是 “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}");

pub unsafe fn as_mut<'a>(&mut self) -> &'a mut T

返回该值的唯一引用。如果该值可能未初始化，则必须改用 as_uninit_mut。

有关共享副本，请参见 as_ref。

Safety

调用此方法时，必须确保满足以下所有条件：

• 指针必须正确对齐。

• 在 模块的文档 中定义的含义上，它必须是 “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);

pub const fn cast<U>(self) -> NonNull<U>

强制转换为另一种类型的指针。

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();

impl<T> NonNull<[T]>

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

根据细指针和长度创建非空的原始切片。

len 参数是 元素 的数量，而不是字节数。

此函数是安全的，但解引用的返回值不安全。 有关切片的安全要求，请参见 slice::from_raw_parts 的文档。

Examples

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[..]); 是编写这样的代码的更好方法。)

pub const fn len(self) -> usize

返回非空原始切片的长度。

返回的值是 元素 的数量，而不是字节数。

即使由于指针没有有效地址而无法将非空原始切片重新引用到切片时，此函数也是安全的。

Examples

use std::ptr::NonNull;

let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
assert_eq!(slice.len(), 3);

pub fn as_non_null_ptr(self) -> NonNull<T>

🔬This is a nightly-only experimental API. (slice_ptr_get #74265)

返回指向切片缓冲区的非 null 指针。

Examples

#![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());

pub fn as_mut_ptr(self) -> *mut T

🔬This is a nightly-only experimental API. (slice_ptr_get #74265)

将裸指针返回到切片的缓冲区。

Examples

#![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());

pub unsafe fn as_uninit_slice<'a>(self) -> &'a [MaybeUninit<T>]

🔬This is a nightly-only experimental API. (ptr_as_uninit #75402)

返回对可能未初始化的值的切片的共享引用。与 as_ref 相比，这不需要将该值初始化。

对于可变的对应物，请参见 as_uninit_slice_mut。

Safety

调用此方法时，必须确保满足以下所有条件：

• 指针必须为 有效 的，才能读取许多字节的 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。

pub unsafe fn as_uninit_slice_mut<'a>(self) -> &'a mut [MaybeUninit<T>]

🔬This is a nightly-only experimental API. (ptr_as_uninit #75402)

返回可能未初始化值的切片的唯一引用。与 as_mut 相比，这不需要将该值初始化。

有关共享副本，请参见 as_uninit_slice。

Safety

调用此方法时，必须确保满足以下所有条件：

• 指针必须是 有效 的才能进行 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。

Examples

#![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()`，因为内容可能未初始化。
let slice: &mut [MaybeUninit<u8>] = unsafe { memory.as_uninit_slice_mut() };

pub unsafe fn get_unchecked_mut<I>( self, index: I ) -> NonNull<<I as SliceIndex<[T]>>::Output>where I: SliceIndex<[T]>,

🔬This is a nightly-only experimental API. (slice_ptr_get #74265)

将裸指针返回到元素或子切片，而不进行边界检查。

使用越界索引或当 self 不可解引用时调用此方法是 未定义行为，即使未使用结果指针。

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));
}

Trait Implementations

impl<T> Clone for NonNull<T>where T: ?Sized,

fn clone(&self) -> NonNull<T>

返回值的副本。

fn clone_from(&mut self, source: &Self)

从 source 执行复制分配。

impl<T> Debug for NonNull<T>where T: ?Sized,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

使用给定的格式化程序格式化该值。

impl<T> From<&T> for NonNull<T>where T: ?Sized,

fn from(reference: &T) -> NonNull<T>

将 &T 转换为 NonNull<T>。

这种转换是安全且可靠的，因为引用不能为空。

impl<T> From<&mut T> for NonNull<T>where T: ?Sized,

fn from(reference: &mut T) -> NonNull<T>

将 &mut T 转换为 NonNull<T>。

这种转换是安全且可靠的，因为引用不能为空。

impl<T> Hash for NonNull<T>where T: ?Sized,

fn hash<H>(&self, state: &mut H)where H: Hasher,

将该值输入给定的 Hasher。

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

将这种类型的切片送入给定的 Hasher 中。

impl<T> Ord for NonNull<T>where T: ?Sized,

fn cmp(&self, other: &NonNull<T>) -> Ordering

此方法返回 self 和 other 之间的 Ordering。

fn max(self, other: Self) -> Selfwhere Self: Sized,

比较并返回两个值中的最大值。

fn min(self, other: Self) -> Selfwhere Self: Sized,

比较并返回两个值中的最小值。

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

将值限制在某个时间间隔内。

impl<T> PartialEq<NonNull<T>> for NonNull<T>where T: ?Sized,

fn eq(&self, other: &NonNull<T>) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

fn ne(&self, other: &Rhs) -> bool

此方法测试 !=。 默认实现几乎总是足够的，并且不应在没有充分理由的情况下被覆盖。

impl<T> PartialOrd<NonNull<T>> for NonNull<T>where T: ?Sized,

fn partial_cmp(&self, other: &NonNull<T>) -> Option<Ordering>

如果存在，则此方法返回 self 和 other 值之间的顺序。

fn lt(&self, other: &Rhs) -> bool

此方法测试的内容少于 (对于 self 和 other)，并且由 < 操作员使用。

fn le(&self, other: &Rhs) -> bool

此方法测试小于或等于 (对于 self 和 other)，并且由 <= 运算符使用。

fn gt(&self, other: &Rhs) -> bool

此方法测试大于 (对于 self 和 other)，并且由 > 操作员使用。

fn ge(&self, other: &Rhs) -> bool

此方法测试是否大于或等于 (对于 self 和 other)，并且由 >= 运算符使用。

impl<T> Pointer for NonNull<T>where T: ?Sized,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

使用给定的格式化程序格式化该值。

impl<T, U> CoerceUnsized<NonNull<U>> for NonNull<T>where T: Unsize<U> + ?Sized, U: ?Sized,

impl<T> Copy for NonNull<T>where T: ?Sized,

impl<T, U> DispatchFromDyn<NonNull<U>> for NonNull<T>where T: Unsize<U> + ?Sized, U: ?Sized,

impl<T> Eq for NonNull<T>where T: ?Sized,

impl<T> !Send for NonNull<T>where T: ?Sized,

NonNull 指针不是 Send，因为它们引用的数据可能是别名。

impl<T> !Sync for NonNull<T>where T: ?Sized,

NonNull 指针不是 Sync，因为它们引用的数据可能是别名。

impl<T> UnwindSafe for NonNull<T>where T: RefUnwindSafe + ?Sized,