Skip to content

Improve some pointer-related documentation #62822

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jul 26, 2019
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions src/libstd/primitive_docs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -363,10 +363,11 @@ mod prim_unit { }
/// *[See also the `std::ptr` module](ptr/index.html).*
///
/// Working with raw pointers in Rust is uncommon, typically limited to a few patterns.
/// Raw pointers can be unaligned or null when unused. However, when a raw pointer is used to
/// load/store data from/to memory, they must be non-null and aligned.
/// Storing through a raw pointer (`*ptr = data`) calls `drop` on the old value, so
/// [`write`] must be used if memory is not already initialized.
/// Raw pointers can be unaligned or [`null`] when unused. However, when a raw pointer is
/// dereferenced (using the `*` operator), it must be non-null and aligned.
/// Storing through a raw pointer using `*ptr = data` calls `drop` on the old value, so
/// [`write`] must be used if memory is not already initialized---otherwise `drop`
/// would be called on the uninitialized memory.
///
/// Use the [`null`] and [`null_mut`] functions to create null pointers, and the
/// [`is_null`] method of the `*const T` and `*mut T` types to check for null.
Expand Down Expand Up @@ -896,7 +897,8 @@ mod prim_usize { }
/// operators on a value, or by using a `ref` or `ref mut` pattern.
///
/// For those familiar with pointers, a reference is just a pointer that is assumed to be
/// aligned and not null. In fact, `Option<&T>` has the same memory representation as a
/// aligned, not null, and pointing to valid (initialized) memory.
/// In fact, `Option<&T>` has the same memory representation as a
/// nullable but aligned pointer, and can be passed across FFI boundaries as such.
///
/// In most cases, references can be used much like the original value. Field access, method
Expand Down