diff --git a/library/core/src/ptr/mut_ptr.rs b/library/core/src/ptr/mut_ptr.rs index b960a3d86bef0..4b86190d450fe 100644 --- a/library/core/src/ptr/mut_ptr.rs +++ b/library/core/src/ptr/mut_ptr.rs @@ -233,18 +233,22 @@ impl *mut T { } /// Returns `None` if the pointer is null, or else returns a shared reference to - /// the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_ref`] - /// must be used instead. + /// the value wrapped in `Some`. /// /// For the mutable counterpart see [`as_mut`]. /// - /// [`as_uninit_ref`]: pointer#method.as_uninit_ref-1 /// [`as_mut`]: #method.as_mut /// /// # Safety /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * *Either* the pointer is null *or* the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * The value of memory pointed by the ptr must be initialized. If not, [`as_uninit_ref`] must be used instead. + /// + /// * Note that after obtaining the reference, the original pointer must not + /// be mutated until the reference's lifetime ends (except inside `UnsafeCell`). /// /// # Panics during const evaluation /// @@ -252,6 +256,7 @@ impl *mut T { /// determined to be null or not. See [`is_null`] for more information. /// /// [`is_null`]: #method.is_null-1 + /// [`as_uninit_ref`]: pointer#method.as_uninit_ref-1 /// /// # Examples /// @@ -289,18 +294,25 @@ impl *mut T { } /// Returns a shared reference to the value behind the pointer. - /// If the pointer may be null or the value may be uninitialized, [`as_uninit_ref`] must be used instead. - /// If the pointer may be null, but the value is known to have been initialized, [`as_ref`] must be used instead. /// /// For the mutable counterpart see [`as_mut_unchecked`]. /// - /// [`as_ref`]: #method.as_ref - /// [`as_uninit_ref`]: #method.as_uninit_ref /// [`as_mut_unchecked`]: #method.as_mut_unchecked /// /// # Safety /// - /// When calling this method, you have to ensure that the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * If the pointer may be null or the value may be uninitialized, [`as_uninit_ref`] must be used instead. + /// If the pointer may be null, but the value is known to have been initialized, [`as_ref`] must be used instead. + /// + /// * Note that after obtaining the reference, the original pointer must not + /// be mutated until the reference's lifetime ends (except inside `UnsafeCell`). + /// + /// [`as_ref`]: #method.as_ref + /// [`as_uninit_ref`]: #method.as_uninit_ref /// /// # Examples /// @@ -332,10 +344,10 @@ impl *mut T { /// /// # Safety /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). - /// Note that because the created reference is to `MaybeUninit`, the - /// source pointer can point to uninitialized memory. + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * Note that after obtaining the reference, the original pointer must not + /// be mutated until the reference's lifetime ends (except inside `UnsafeCell`). /// /// # Panics during const evaluation /// @@ -593,19 +605,22 @@ impl *mut T { } /// Returns `None` if the pointer is null, or else returns a unique reference to - /// the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_mut`] - /// must be used instead. + /// the value wrapped in `Some`. /// /// For the shared counterpart see [`as_ref`]. /// - /// [`as_uninit_mut`]: #method.as_uninit_mut /// [`as_ref`]: pointer#method.as_ref-1 /// /// # Safety /// - /// When calling this method, you have to ensure that *either* - /// the pointer is null *or* - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * *Either* the pointer is null *or* the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * The value of memory pointed by the ptr must be initialized. If not, [`as_uninit_mut`] must be used instead. + /// + /// * Note that after obtaining the mutable reference, the original pointer + /// must not be used to access the data until the reference's lifetime ends. /// /// # Panics during const evaluation /// @@ -614,6 +629,8 @@ impl *mut T { /// /// [`is_null`]: #method.is_null-1 /// + /// [`as_uninit_mut`]: #method.as_uninit_mut + /// /// # Examples /// /// ``` @@ -649,19 +666,25 @@ impl *mut T { } /// Returns a unique reference to the value behind the pointer. - /// If the pointer may be null or the value may be uninitialized, [`as_uninit_mut`] must be used instead. - /// If the pointer may be null, but the value is known to have been initialized, [`as_mut`] must be used instead. /// /// For the shared counterpart see [`as_ref_unchecked`]. /// - /// [`as_mut`]: #method.as_mut - /// [`as_uninit_mut`]: #method.as_uninit_mut /// [`as_ref_unchecked`]: #method.as_mut_unchecked /// /// # Safety /// - /// When calling this method, you have to ensure that - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * If the pointer may be null or the value may be uninitialized, [`as_uninit_mut`] must be used instead. + /// If the pointer may be null, but the value is known to have been initialized, [`as_mut`] must be used instead. + /// + /// * Note that after obtaining the mutable reference, the original pointer + /// must not be used to access the data until the reference's lifetime ends. + /// + /// [`as_mut`]: #method.as_mut + /// [`as_uninit_mut`]: #method.as_uninit_mut /// /// # Examples /// @@ -694,8 +717,10 @@ impl *mut T { /// /// # Safety /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * Note that after obtaining the mutable reference, the original pointer must not + /// be used to access the data until the reference's lifetime ends. /// /// # Panics during const evaluation /// diff --git a/library/core/src/ptr/non_null.rs b/library/core/src/ptr/non_null.rs index c769ba673c61e..a1c66a65e45ac 100644 --- a/library/core/src/ptr/non_null.rs +++ b/library/core/src/ptr/non_null.rs @@ -152,10 +152,11 @@ impl NonNull { /// /// # Safety /// - /// When calling this method, you have to ensure that - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). - /// Note that because the created reference is to `MaybeUninit`, the - /// source pointer can point to uninitialized memory. + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * Note that after obtaining the reference, the original pointer must not + /// be mutated until the reference's lifetime ends (except inside `UnsafeCell`). + /// #[inline] #[must_use] #[unstable(feature = "ptr_as_uninit", issue = "75402")] @@ -175,10 +176,11 @@ impl NonNull { /// /// # Safety /// - /// When calling this method, you have to ensure that - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). - /// Note that because the created reference is to `MaybeUninit`, the - /// source pointer can point to uninitialized memory. + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * Note that after obtaining the mutable reference, the original pointer must not + /// be used to access the data until the reference's lifetime ends. + /// #[inline] #[must_use] #[unstable(feature = "ptr_as_uninit", issue = "75402")] @@ -391,18 +393,24 @@ impl NonNull { unsafe { mem::transmute::(self) } } - /// Returns a shared reference to the value. If the value may be uninitialized, [`as_uninit_ref`] - /// must be used instead. + /// Returns a shared reference to the value. /// /// For the mutable counterpart see [`as_mut`]. /// - /// [`as_uninit_ref`]: NonNull::as_uninit_ref /// [`as_mut`]: NonNull::as_mut /// /// # Safety /// - /// When calling this method, you have to ensure that - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * The value of memory pointed by the ptr must be initialized. If not, [`as_uninit_ref`] must be used instead. + /// + /// * Note that after obtaining the mutable reference, the original pointer must not + /// be mutated until the reference's lifetime ends (except inside `UnsafeCell`). + /// + /// [`as_uninit_ref`]: NonNull::as_uninit_ref /// /// # Examples /// @@ -428,18 +436,25 @@ impl NonNull { unsafe { &*self.as_ptr().cast_const() } } - /// Returns a unique reference to the value. If the value may be uninitialized, [`as_uninit_mut`] - /// must be used instead. + /// Returns a unique reference to the value. /// /// For the shared counterpart see [`as_ref`]. /// - /// [`as_uninit_mut`]: NonNull::as_uninit_mut /// [`as_ref`]: NonNull::as_ref /// /// # Safety /// - /// When calling this method, you have to ensure that - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * The value of memory pointed by the ptr must be initialized. If not, [`as_uninit_mut`] must be used instead. + /// + /// * Note that after obtaining the mutable reference, the original pointer + /// must not be used to access the data until the reference's lifetime ends. + /// + /// [`as_uninit_mut`]: NonNull::as_uninit_mut + /// /// # Examples /// /// ```