bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Elaborate on std::ptr::{as_ref,as_mod} and clarify docs

Browse source
This commit is contained in:
CreepySkeleton 2019-11-13 20:43:45 +03:00
parent 695fe96517
commit d411dd27bf
1 changed files with 24 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

38
src/libcore/ptr/mod.rs
View file

@ -1074,17 +1074,22 @@ impl<T: ?Sized> *const T {
/// operation because the returned value could be pointing to invalid /// operation because the returned value could be pointing to invalid
/// memory. /// memory.
/// ///
/// When calling this method, you have to ensure that if the pointer is /// When calling this method, you have to ensure that *either* the pointer is NULL *or*
/// non-NULL, then it is properly aligned, dereferencable (for the whole /// all of the following is true:
/// size of `T`) and points to an initialized instance of `T`. This applies /// - it is properly aligned
/// even if the result of this method is unused! /// - it 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 /// (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.) /// it is, the only safe approach is to ensure that they are indeed initialized.)
/// ///
/// Additionally, the lifetime `'a` returned is arbitrarily chosen and does /// Additionally, the lifetime `'a` returned is arbitrarily chosen and does
/// not necessarily reflect the actual lifetime of the data. It is up to the /// not necessarily reflect the actual lifetime of the data. *You* must enforce
/// caller to ensure that for the duration of this lifetime, the memory this /// Rust's aliasing rules. In particular, for the duration of this lifetime,
/// pointer points to does not get written to outside of `UnsafeCell<U>`. /// the memory the pointer points to must not get mutated (except inside `UnsafeCell`).
///
/// [here]: https://doc.rust-lang.org/std/ptr/index.html#safety
/// ///
/// # Examples /// # Examples
/// ///
@ -1929,18 +1934,23 @@ impl<T: ?Sized> *mut T {
/// of the returned pointer, nor can it ensure that the lifetime `'a` /// of the returned pointer, nor can it ensure that the lifetime `'a`
/// returned is indeed a valid lifetime for the contained data. /// returned is indeed a valid lifetime for the contained data.
/// ///
/// When calling this method, you have to ensure that if the pointer is /// When calling this method, you have to ensure that *either* the pointer is NULL *or*
/// non-NULL, then it is properly aligned, dereferencable (for the whole /// all of the following is true:
/// size of `T`) and points to an initialized instance of `T`. This applies /// - it is properly aligned
/// even if the result of this method is unused! /// - it 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 /// (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.) /// it is the only safe approach is to ensure that they are indeed initialized.)
/// ///
/// Additionally, the lifetime `'a` returned is arbitrarily chosen and does /// Additionally, the lifetime `'a` returned is arbitrarily chosen and does
/// not necessarily reflect the actual lifetime of the data. It is up to the /// not necessarily reflect the actual lifetime of the data. *You* must enforce
/// caller to ensure that for the duration of this lifetime, the memory this /// Rust's aliasing rules. In particular, for the duration of this lifetime,
/// pointer points to does not get accessed through any other pointer. /// the memory this pointer points to must not get accessed (read or written)
/// through any other pointer.
/// ///
/// [here]: https://doc.rust-lang.org/std/ptr/index.html#safety
/// [`as_ref`]: #method.as_ref /// [`as_ref`]: #method.as_ref
/// ///
/// # Examples /// # Examples