mathieu/granite-rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add safety section to NonNull::as_* method docs

Browse source 
This basically adds the safety section of `*mut T::as_{ref,mut}` to the
same methods on `NonNull` with minor modifications to fit the
differences.

Part of #48929.
This commit is contained in:
aticu 2020-08-07 20:58:34 +02:00
parent 4d4342347b
commit c2099b5f28
1 changed files with 36 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
library/core/src/ptr/non_null.rs
View file

@ -117,6 +117,24 @@ impl<T: ?Sized> NonNull<T> {
/// The resulting lifetime is bound to self so this behaves "as if" /// 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 /// it were actually an instance of T that is getting borrowed. If a longer
/// (unbound) lifetime is needed, use `&*my_ptr.as_ptr()`. /// (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")] #[stable(feature = "nonnull", since = "1.25.0")]
#[inline] #[inline]
pub unsafe fn as_ref(&self) -> &T { pub unsafe fn as_ref(&self) -> &T {
@ -130,6 +148,24 @@ impl<T: ?Sized> NonNull<T> {
/// The resulting lifetime is bound to self so this behaves "as if" /// 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 /// it were actually an instance of T that is getting borrowed. If a longer
/// (unbound) lifetime is needed, use `&mut *my_ptr.as_ptr()`. /// (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")] #[stable(feature = "nonnull", since = "1.25.0")]
#[inline] #[inline]
pub unsafe fn as_mut(&mut self) -> &mut T { pub unsafe fn as_mut(&mut self) -> &mut T {