#[repr(transparent)]pub struct NonNull<T: ?Sized> { /* private fields */ }
Expand description
*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§
source§impl<T: Sized> NonNull<T>
impl<T: Sized> NonNull<T>
const: unstable · sourcepub unsafe fn as_uninit_ref<'a>(self) -> &'a MaybeUninit<T>
🔬This is a nightly-only experimental API. (ptr_as_uninit
#75402)
pub unsafe fn as_uninit_ref<'a>(self) -> &'a MaybeUninit<T>
ptr_as_uninit
#75402)返回该值的共享引用。与 as_ref
相比,这不需要将该值初始化。
对于可变的对应物,请参见 as_uninit_mut
。
Safety
调用此方法时,必须确保满足以下所有条件:
-
指针必须正确对齐。
-
在 模块的文档 中定义的含义上,它必须是 “dereferenceable”。
-
您必须执行 Rust 的别名规则,因为返回的生命周期
'a
是任意选择的,不一定反映数据的实际生命周期。特别是,当这个引用存在时,指针指向的内存不能发生可变 (
UnsafeCell
内部除外)。
即使未使用此方法的结果也是如此!
const: unstable · sourcepub unsafe fn as_uninit_mut<'a>(self) -> &'a mut MaybeUninit<T>
🔬This is a nightly-only experimental API. (ptr_as_uninit
#75402)
pub unsafe fn as_uninit_mut<'a>(self) -> &'a mut MaybeUninit<T>
ptr_as_uninit
#75402)返回该值的唯一引用。与 as_mut
相比,这不需要将该值初始化。
有关共享副本,请参见 as_uninit_ref
。
Safety
调用此方法时,必须确保满足以下所有条件:
-
指针必须正确对齐。
-
在 模块的文档 中定义的含义上,它必须是 “dereferenceable”。
-
您必须执行 Rust 的别名规则,因为返回的生命周期
'a
是任意选择的,不一定反映数据的实际生命周期。特别是,当这个引用存在时,指针指向的内存不能通过任何其他指针访问 (读取或写入)。
即使未使用此方法的结果也是如此!
source§impl<T: ?Sized> NonNull<T>
impl<T: ?Sized> NonNull<T>
const: 1.25.0 · sourcepub const unsafe fn new_unchecked(ptr: *mut T) -> Self
pub const unsafe fn new_unchecked(ptr: *mut T) -> Self
const: unstable · sourcepub fn from_raw_parts(
data_address: NonNull<()>,
metadata: <T as Pointee>::Metadata
) -> NonNull<T>
🔬This is a nightly-only experimental API. (ptr_metadata
#81513)
pub fn from_raw_parts( data_address: NonNull<()>, metadata: <T as Pointee>::Metadata ) -> NonNull<T>
ptr_metadata
#81513)执行与 std::ptr::from_raw_parts
相同的功能,除了返回 NonNull
指针 (与原始 *const
指针相反)。
有关更多详细信息,请参见 std::ptr::from_raw_parts
的文档。
const: unstable · sourcepub fn to_raw_parts(self) -> (NonNull<()>, <T as Pointee>::Metadata)
🔬This is a nightly-only experimental API. (ptr_metadata
#81513)
pub fn to_raw_parts(self) -> (NonNull<()>, <T as Pointee>::Metadata)
ptr_metadata
#81513)将指针 (可能是宽指针) 分解为其地址和元数据组件。
以后可以使用 NonNull::from_raw_parts
重建指针。
sourcepub fn addr(self) -> NonZeroUsize
🔬This is a nightly-only experimental API. (strict_provenance
#95228)
pub fn addr(self) -> NonZeroUsize
strict_provenance
#95228)获取指针的 “address” 部分。
有关更多详细信息,请参见裸指针上的等效方法 pointer::addr
。
此 API 及其声明的语义是 Strict Provenance 实验的一部分,请参见 ptr
module documentation。
sourcepub fn with_addr(self, addr: NonZeroUsize) -> Self
🔬This is a nightly-only experimental API. (strict_provenance
#95228)
pub fn with_addr(self, addr: NonZeroUsize) -> Self
strict_provenance
#95228)使用给定地址创建一个新指针。
有关更多详细信息,请参见裸指针上的等效方法 pointer::with_addr
。
此 API 及其声明的语义是 Strict Provenance 实验的一部分,请参见 ptr
module documentation。
sourcepub fn map_addr(self, f: impl FnOnce(NonZeroUsize) -> NonZeroUsize) -> Self
🔬This is a nightly-only experimental API. (strict_provenance
#95228)
pub fn map_addr(self, f: impl FnOnce(NonZeroUsize) -> NonZeroUsize) -> Self
strict_provenance
#95228)通过将 self
的地址映射到新地址来创建新指针。
有关更多详细信息,请参见裸指针上的等效方法 pointer::map_addr
。
此 API 及其声明的语义是 Strict Provenance 实验的一部分,请参见 ptr
module documentation。
const: unstable · sourcepub unsafe fn as_ref<'a>(&self) -> &'a T
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}");
Runconst: unstable · sourcepub unsafe fn as_mut<'a>(&mut self) -> &'a mut T
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);
Runsource§impl<T> NonNull<[T]>
impl<T> NonNull<[T]>
1.70.0 (const: unstable) · sourcepub fn slice_from_raw_parts(data: NonNull<T>, len: usize) -> Self
pub fn slice_from_raw_parts(data: NonNull<T>, len: usize) -> Self
根据细指针和长度创建非空的原始切片。
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);
Run(请注意,此示例人为地演示了此方法的用法,但是 let slice = NonNull::from(&x[..]);
是编写这样的代码的更好方法。)
const: unstable · sourcepub fn as_non_null_ptr(self) -> NonNull<T>
🔬This is a nightly-only experimental API. (slice_ptr_get
#74265)
pub fn as_non_null_ptr(self) -> NonNull<T>
slice_ptr_get
#74265)const: unstable · sourcepub fn as_mut_ptr(self) -> *mut T
🔬This is a nightly-only experimental API. (slice_ptr_get
#74265)
pub fn as_mut_ptr(self) -> *mut T
slice_ptr_get
#74265)const: unstable · sourcepub unsafe fn as_uninit_slice<'a>(self) -> &'a [MaybeUninit<T>]
🔬This is a nightly-only experimental API. (ptr_as_uninit
#75402)
pub unsafe fn as_uninit_slice<'a>(self) -> &'a [MaybeUninit<T>]
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
。
const: unstable · sourcepub unsafe fn as_uninit_slice_mut<'a>(self) -> &'a mut [MaybeUninit<T>]
🔬This is a nightly-only experimental API. (ptr_as_uninit
#75402)
pub unsafe fn as_uninit_slice_mut<'a>(self) -> &'a mut [MaybeUninit<T>]
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() };
Runsourcepub unsafe fn get_unchecked_mut<I>(self, index: I) -> NonNull<I::Output>where
I: SliceIndex<[T]>,
🔬This is a nightly-only experimental API. (slice_ptr_get
#74265)
pub unsafe fn get_unchecked_mut<I>(self, index: I) -> NonNull<I::Output>where I: SliceIndex<[T]>,
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));
}
RunTrait Implementations§
source§impl<T: ?Sized> PartialOrd<NonNull<T>> for NonNull<T>
impl<T: ?Sized> PartialOrd<NonNull<T>> for NonNull<T>
impl<T, U: ?Sized> CoerceUnsized<NonNull<U>> for NonNull<T>where T: Unsize<U> + ?Sized,
impl<T: ?Sized> Copy for NonNull<T>
impl<T, U: ?Sized> DispatchFromDyn<NonNull<U>> for NonNull<T>where T: Unsize<U> + ?Sized,
impl<T: ?Sized> Eq for NonNull<T>
impl<T: ?Sized> !Send for NonNull<T>
NonNull
指针不是 Send
,因为它们引用的数据可能是别名。
impl<T: ?Sized> !Sync for NonNull<T>
NonNull
指针不是 Sync
,因为它们引用的数据可能是别名。