Struct core::ptr::NonNull 1.25.0[−][src]
#[repr(transparent)]pub struct NonNull<T: ?Sized> { /* fields omitted */ }Expand description
*mut T 但是非零且协变。
在使用裸指针构建数据结构时，这通常是正确的选择，但由于其额外的属性，最终使用起来更加危险。如果不确定是否应使用 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
返回该值的共享引用。与 as_ref 相比，这不需要将该值初始化。
对于可变的对应物，请参见 as_uninit_mut。
Safety
调用此方法时，必须确保满足以下所有条件：
-
指针必须正确对齐。
-
在 模块的文档 中定义的含义上，它必须是 “dereferenceable”。
-
您必须执行 Rust 的别名规则，因为返回的生命周期
'a是任意选择的，不一定反映数据的实际生命周期。特别是，在此生命周期的持续时间内，指针所指向的内存一定不能被可变的 (
UnsafeCell内部除外)。
即使未使用此方法的结果也是如此！
返回该值的唯一引用。与 as_mut 相比，这不需要将该值初始化。
有关共享副本，请参见 as_uninit_ref。
Safety
调用此方法时，必须确保满足以下所有条件：
-
指针必须正确对齐。
-
在 模块的文档 中定义的含义上，它必须是 “dereferenceable”。
-
您必须执行 Rust 的别名规则，因为返回的生命周期
'a是任意选择的，不一定反映数据的实际生命周期。特别是，在此生命周期的持续时间内，指针所指向的内存一定不能通过任何其他指针进行访问 (读取或写入)。
即使未使用此方法的结果也是如此！
执行与 std::ptr::from_raw_parts 相同的功能，除了返回 NonNull 指针 (与原始 *const 指针相反)。
有关更多详细信息，请参见 std::ptr::from_raw_parts 的文档。
将指针 (可能是宽指针) 分解为其地址和元数据组件。
以后可以使用 NonNull::from_raw_parts 重建指针。
返回该值的共享引用。如果该值可能未初始化，则必须改用 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);返回该值的唯一引用。如果该值可能未初始化，则必须改用 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);根据细指针和长度创建非空的原始切片。
len 参数是 元素 的数量，而不是字节数。
此函数是安全的，但解引用的返回值不安全。
有关切片的安全要求，请参见 slice::from_raw_parts 的文档。
Examples
#![feature(nonnull_slice_from_raw_parts)]
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[..]); 是编写这样的代码的更好方法。)
返回对可能未初始化的值的切片的共享引用。与 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。
返回可能未初始化值的切片的唯一引用。与 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::Output> where
I: SliceIndex<[T]>,
pub unsafe fn get_unchecked_mut<I>(self, index: I) -> NonNull<I::Output> where
I: SliceIndex<[T]>,
将裸指针返回到元素或子切片，而不进行边界检查。
使用越界索引或当 self 不可解引用时调用此方法是 未定义行为，即使未使用结果指针。
Examples
#![feature(slice_ptr_get, nonnull_slice_from_raw_parts)]
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
如果存在，则此方法返回 self 和 other 值之间的顺序。 Read more
NonNull 指针不是 Send，因为它们引用的数据可能是别名。
NonNull 指针不是 Sync，因为它们引用的数据可能是别名。