Struct std::ptr::NonNull1.25.0[−][src]

#[repr(transparent)]
pub struct NonNull<T> where
    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

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

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

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

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

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

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

Safety

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

  • 指针必须正确对齐。

  • 在 the module documentation 中定义的意义上，它必须是 “dereferencable”。

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

    特别是，在此生命周期的持续时间内，指针所指向的内存一定不能被可变的 (UnsafeCell 内部除外)。

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

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

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

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

Safety

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

  • 指针必须正确对齐。

  • 在 the module documentation 中定义的意义上，它必须是 “dereferencable”。

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

    特别是，在此生命周期的持续时间内，指针所指向的内存一定不能通过任何其他指针进行访问 (读取或写入)。

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

创建一个新的 NonNull。

Safety

ptr 必须为非 null。

如果 ptr 不为空，则创建一个新的 NonNull。

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

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

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

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

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

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

获取基础的 *mut 指针。

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

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

Safety

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

  • 指针必须正确对齐。

  • 在 the module documentation 中定义的意义上，它必须是 “dereferencable”。

  • 指针必须指向 T 的初始化实例。

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

    特别是，在此生命周期的持续时间内，指针所指向的内存一定不能被可变的 (UnsafeCell 内部除外)。

即使未使用此方法的结果也是如此! (关于初始化的部分尚未完全决定，但是直到确定之前，唯一安全的方法是确保它们确实被初始化。)

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

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

Safety

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

  • 指针必须正确对齐。

  • 在 the module documentation 中定义的意义上，它必须是 “dereferencable”。

  • 指针必须指向 T 的初始化实例。

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

    特别是，在此生命周期的持续时间内，指针所指向的内存一定不能通过任何其他指针进行访问 (读取或写入)。

即使未使用此方法的结果也是如此! (关于初始化的部分尚未完全决定，但是直到确定之前，唯一安全的方法是确保它们确实被初始化。)

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

🔬 This is a nightly-only experimental API. (nonnull_slice_from_raw_parts #71941)

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

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

(请注意，此示例人为地演示了此方法的用法，但是 let slice = NonNull::from(&x[..]); 是编写这样的代码的更好方法。)

🔬 This is a nightly-only experimental API. (slice_ptr_len #71146)

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

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

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

Examples

#![feature(slice_ptr_len, nonnull_slice_from_raw_parts)]
use std::ptr::NonNull;

let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
assert_eq!(slice.len(), 3);
Run
🔬 This is a nightly-only experimental API. (slice_ptr_get #74265)

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

Examples

#![feature(slice_ptr_get, nonnull_slice_from_raw_parts)]
use std::ptr::NonNull;

let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
assert_eq!(slice.as_non_null_ptr(), NonNull::new(1 as *mut i8).unwrap());
Run
🔬 This is a nightly-only experimental API. (slice_ptr_get #74265)

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

Examples

#![feature(slice_ptr_get, nonnull_slice_from_raw_parts)]
use std::ptr::NonNull;

let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
assert_eq!(slice.as_mut_ptr(), 1 as *mut i8);
Run
🔬 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。

🔬 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() };
Run
🔬 This is a nightly-only experimental API. (slice_ptr_get #74265)

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

即使未使用生成的指针，使用越界索引或无法使用 self 调用此方法也是 [[undefined 行为]。

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

Trait Implementations

返回值的副本。 Read more

从 source 执行复制分配。 Read more

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

执行转换。

执行转换。

执行转换。

将该值输入给定的 Hasher。 Read more

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

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

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

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

将值限制为一定的时间间隔。 Read more

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

此方法测试 !=。

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

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

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

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

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

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

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

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

Auto Trait Implementations

Blanket Implementations

获取 self 的 TypeId。 Read more

从拥有的值中一成不变地借用。 Read more

从拥有的值中借用。 Read more

执行转换。

执行转换。

获得所有权后的结果类型。

通常通过克隆从借用数据中创建拥有的数据。 Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into #41263)

recently added

使用借来的数据来替换拥有的数据，通常是通过克隆。 Read more

发生转换错误时返回的类型。

执行转换。

发生转换错误时返回的类型。

执行转换。