From 31c2aa26323111849426a682f71b6cd8df36e72c Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Fri, 26 Mar 2021 12:57:55 -0700 Subject: [PATCH 1/2] One sentence is one line: Pointer types --- src/types/pointer.md | 51 +++++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 27 deletions(-) diff --git a/src/types/pointer.md b/src/types/pointer.md index 7cbb1f173..b1f9da327 100644 --- a/src/types/pointer.md +++ b/src/types/pointer.md @@ -1,7 +1,7 @@ # Pointer types -All pointers in Rust are explicit first-class values. They can be moved or -copied, stored into data structs, and returned from functions. +All pointers in Rust are explicit first-class values. +They can be moved or copied, stored into data structs, and returned from functions. ## References (`&` and `&mut`) @@ -11,21 +11,20 @@ copied, stored into data structs, and returned from functions. ### Shared references (`&`) -These point to memory _owned by some other value_. When a shared reference to -a value is created it prevents direct mutation of the value. [Interior -mutability] provides an exception for this in certain circumstances. As the -name suggests, any number of shared references to a value may exist. A shared -reference type is written `&type`, or `&'a type` when you need to specify an -explicit lifetime. Copying a reference is a "shallow" operation: it involves -only copying the pointer itself, that is, pointers are `Copy`. Releasing a -reference has no effect on the value it points to, but referencing of a -[temporary value] will keep it alive during the scope of the reference itself. +These point to memory _owned by some other value_. +When a shared reference to a value is created it prevents direct mutation of the value. +[Interior mutability] provides an exception for this in certain circumstances. +As the name suggests, any number of shared references to a value may exist. +A shared reference type is written `&type`, or `&'a type` when you need to specify an explicit lifetime. +Copying a reference is a "shallow" operation: +it involves only copying the pointer itself, that is, pointers are `Copy`. +Releasing a reference has no effect on the value it points to, but referencing of a [temporary value] will keep it alive during the scope of the reference itself. ### Mutable references (`&mut`) -These also point to memory owned by some other value. A mutable reference type -is written `&mut type` or `&'a mut type`. A mutable reference (that hasn't been -borrowed) is the only way to access the value it points to, so is not `Copy`. +These also point to memory owned by some other value. +A mutable reference type is written `&mut type` or `&'a mut type`. +A mutable reference (that hasn't been borrowed) is the only way to access the value it points to, so is not `Copy`. ## Raw pointers (`*const` and `*mut`) @@ -33,23 +32,21 @@ borrowed) is the only way to access the value it points to, so is not `Copy`. > _RawPointerType_ :\ >    `*` ( `mut` | `const` ) [_TypeNoBounds_] -Raw pointers are pointers without safety or liveness guarantees. Raw pointers -are written as `*const T` or `*mut T`, for example `*const i32` means a raw -pointer to a 32-bit integer. Copying or dropping a raw pointer has no effect -on the lifecycle of any other value. Dereferencing a raw pointer is an -[`unsafe` operation], this can also be used to convert a raw pointer to a -reference by reborrowing it (`&*` or `&mut *`). Raw pointers are generally -discouraged in Rust code; they exist to support interoperability with foreign -code, and writing performance-critical or low-level functions. +Raw pointers are pointers without safety or liveness guarantees. +Raw pointers are written as `*const T` or `*mut T`. +For example `*const i32` means a raw pointer to a 32-bit integer. +Copying or dropping a raw pointer has no effect on the lifecycle of any other value. +Dereferencing a raw pointer is an [`unsafe` operation]. +This can also be used to convert a raw pointer to a reference by reborrowing it (`&*` or `&mut *`). +Raw pointers are generally discouraged in Rust code; +they exist to support interoperability with foreign code, and writing performance-critical or low-level functions. -When comparing raw pointers they are compared by their address, rather than by -what they point to. When comparing raw pointers to [dynamically sized types] they -also have their additional data compared. +When comparing raw pointers they are compared by their address, rather than by what they point to. +When comparing raw pointers to [dynamically sized types] they also have their additional data compared. ## Smart Pointers -The standard library contains additional 'smart pointer' types beyond references -and raw pointers. +The standard library contains additional 'smart pointer' types beyond references and raw pointers. [Interior mutability]: ../interior-mutability.md [_Lifetime_]: ../trait-bounds.md From 4664361ba2f7bcc568f6bef4d119b53971fdf8ad Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Fri, 26 Mar 2021 13:07:22 -0700 Subject: [PATCH 2/2] Mention ptr::addr_of(_mut) on raw pointers section --- src/types/pointer.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/types/pointer.md b/src/types/pointer.md index b1f9da327..47bda4f82 100644 --- a/src/types/pointer.md +++ b/src/types/pointer.md @@ -44,10 +44,14 @@ they exist to support interoperability with foreign code, and writing performanc When comparing raw pointers they are compared by their address, rather than by what they point to. When comparing raw pointers to [dynamically sized types] they also have their additional data compared. +Raw pointers can be created directly using [`core::ptr::addr_of!`] for `*const` pointers and [`core::ptr::addr_of_mut!`] for `*mut` pointers. + ## Smart Pointers The standard library contains additional 'smart pointer' types beyond references and raw pointers. +[`core::ptr::addr_of!`]: ../../core/ptr/macro.addr_of.html +[`core::ptr::addr_of_mut!`]: ../../core/ptr/macro.addr_of_mut.html [Interior mutability]: ../interior-mutability.md [_Lifetime_]: ../trait-bounds.md [_TypeNoBounds_]: ../types.md#type-expressions