diff --git a/library/core/src/ptr/non_null.rs b/library/core/src/ptr/non_null.rs index 5163b2d9d568b..d876ab23653f3 100644 --- a/library/core/src/ptr/non_null.rs +++ b/library/core/src/ptr/non_null.rs @@ -117,6 +117,24 @@ impl NonNull { /// The resulting lifetime is bound to self so this behaves "as if" /// it were actually an instance of T that is getting borrowed. If a longer /// (unbound) lifetime is needed, use `&*my_ptr.as_ptr()`. + /// + /// # Safety + /// + /// When calling this method, you have to ensure that all of the following is true: + /// - `self` is properly aligned + /// - `self` must point to an initialized instance of T; in particular, the pointer must be + /// "dereferencable" in the sense defined [here]. + /// + /// This applies even if the result of this method is unused! + /// (The part about being initialized is not yet fully decided, but until + /// it is, the only safe approach is to ensure that they are indeed initialized.) + /// + /// Additionally, the lifetime of `self` does not necessarily reflect the actual + /// lifetime of the data. *You* must enforce Rust's aliasing rules. In particular, + /// for the duration of this lifetime, the memory the pointer points to must not + /// get mutated (except inside `UnsafeCell`). + /// + /// [here]: crate::ptr#safety #[stable(feature = "nonnull", since = "1.25.0")] #[inline] pub unsafe fn as_ref(&self) -> &T { @@ -130,6 +148,24 @@ impl NonNull { /// The resulting lifetime is bound to self so this behaves "as if" /// it were actually an instance of T that is getting borrowed. If a longer /// (unbound) lifetime is needed, use `&mut *my_ptr.as_ptr()`. + /// + /// # Safety + /// + /// When calling this method, you have to ensure that all of the following is true: + /// - `self` is properly aligned + /// - `self` must point to an initialized instance of T; in particular, the pointer must be + /// "dereferenceable" in the sense defined [here]. + /// + /// This applies even if the result of this method is unused! + /// (The part about being initialized is not yet fully decided, but until + /// it is the only safe approach is to ensure that they are indeed initialized.) + /// + /// Additionally, the lifetime of `self` does not necessarily reflect the actual + /// lifetime of the data. *You* must enforce Rust's aliasing rules. In particular, + /// for the duration of this lifetime, the memory this pointer points to must not + /// get accessed (read or written) through any other pointer. + /// + /// [here]: crate::ptr#safety #[stable(feature = "nonnull", since = "1.25.0")] #[inline] pub unsafe fn as_mut(&mut self) -> &mut T {