From 74bf59ea037e114fc2d586967601faba9fff64f4 Mon Sep 17 00:00:00 2001 From: Lucas Lois Date: Tue, 2 Oct 2018 13:31:40 -0300 Subject: [PATCH 1/2] Documents reference equality by address (#54197) Clarification of the use of `ptr::eq` to test equality of references via address by pointer coercion --- src/libstd/primitive_docs.rs | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs index 8d54728a75f42..11195bb9a2abd 100644 --- a/src/libstd/primitive_docs.rs +++ b/src/libstd/primitive_docs.rs @@ -908,11 +908,36 @@ mod prim_usize { } /// `&mut T` references can be freely coerced into `&T` references with the same referent type, and /// references with longer lifetimes can be freely coerced into references with shorter ones. /// +/// Reference equality by address, instead of comparing the values pointed to, is accomplished via +/// implicit reference-pointer coercion and raw pointer equality via [`ptr::eq`], while +/// [`PartialEq`] compares values. +/// +/// [`ptr::eq`]: ptr/fn.eq.html +/// [`PartialEq`]: cmp/trait.PartialEq.html +/// +/// ``` +/// use std::ptr; +/// +/// let five = 5; +/// let other_five = 5; +/// let five_ref = &five; +/// let same_five_ref = &five; +/// let other_five_ref = &other_five; +/// +/// assert!(five_ref == same_five_ref); +/// assert!(five_ref == other_five_ref); +/// +/// assert!(ptr::eq(five_ref, same_five_ref)); +/// assert!(!ptr::eq(five_ref, other_five_ref)); +/// ``` +/// /// For more information on how to use references, see [the book's section on "References and /// Borrowing"][book-refs]. /// /// [book-refs]: ../book/second-edition/ch04-02-references-and-borrowing.html /// +/// # Trait implementations +/// /// The following traits are implemented for all `&T`, regardless of the type of its referent: /// /// * [`Copy`] From 68236e088d8b5694eb4097c1ad8302b92e36fd4a Mon Sep 17 00:00:00 2001 From: Lucas Lois Date: Tue, 2 Oct 2018 13:59:33 -0300 Subject: [PATCH 2/2] Cleans trailing whitespace --- src/libstd/primitive_docs.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs index 11195bb9a2abd..3b432d0513209 100644 --- a/src/libstd/primitive_docs.rs +++ b/src/libstd/primitive_docs.rs @@ -909,12 +909,12 @@ mod prim_usize { } /// references with longer lifetimes can be freely coerced into references with shorter ones. /// /// Reference equality by address, instead of comparing the values pointed to, is accomplished via -/// implicit reference-pointer coercion and raw pointer equality via [`ptr::eq`], while +/// implicit reference-pointer coercion and raw pointer equality via [`ptr::eq`], while /// [`PartialEq`] compares values. -/// +/// /// [`ptr::eq`]: ptr/fn.eq.html /// [`PartialEq`]: cmp/trait.PartialEq.html -/// +/// /// ``` /// use std::ptr; /// @@ -930,14 +930,14 @@ mod prim_usize { } /// assert!(ptr::eq(five_ref, same_five_ref)); /// assert!(!ptr::eq(five_ref, other_five_ref)); /// ``` -/// +/// /// For more information on how to use references, see [the book's section on "References and /// Borrowing"][book-refs]. /// /// [book-refs]: ../book/second-edition/ch04-02-references-and-borrowing.html /// /// # Trait implementations -/// +/// /// The following traits are implemented for all `&T`, regardless of the type of its referent: /// /// * [`Copy`]