From fe2f40a142ef8767ad379b11a86d3161a44b3887 Mon Sep 17 00:00:00 2001 From: ch-iv Date: Tue, 8 Nov 2022 09:27:32 -0500 Subject: [PATCH 1/7] Add an example for Pin::new() --- library/core/src/pin.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/library/core/src/pin.rs b/library/core/src/pin.rs index ccef35b45325a..7751dfb4767d1 100644 --- a/library/core/src/pin.rs +++ b/library/core/src/pin.rs @@ -485,6 +485,13 @@ impl> Pin

{ /// /// Unlike `Pin::new_unchecked`, this method is safe because the pointer /// `P` dereferences to an [`Unpin`] type, which cancels the pinning guarantees. + /// + /// # Examples + /// + /// ``` + /// let val: u8 = 5; + /// let pinned: Pin<&u8> = Pin::new(&val); + /// ``` #[inline(always)] #[rustc_const_unstable(feature = "const_pin", issue = "76654")] #[stable(feature = "pin", since = "1.33.0")] From 8b5379e4b5c032271fe0fb29972f15510e911066 Mon Sep 17 00:00:00 2001 From: ch-iv Date: Wed, 9 Nov 2022 09:02:28 -0500 Subject: [PATCH 2/7] Add example for the into_inner() method --- library/core/src/pin.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/library/core/src/pin.rs b/library/core/src/pin.rs index 7751dfb4767d1..1af638a6b8a63 100644 --- a/library/core/src/pin.rs +++ b/library/core/src/pin.rs @@ -489,7 +489,10 @@ impl> Pin

{ /// # Examples /// /// ``` + /// use std::pin::Pin; + /// /// let val: u8 = 5; + /// // Wrap the value in a pin to make sure it doesn't move /// let pinned: Pin<&u8> = Pin::new(&val); /// ``` #[inline(always)] @@ -505,6 +508,17 @@ impl> Pin

{ /// /// This requires that the data inside this `Pin` is [`Unpin`] so that we /// can ignore the pinning invariants when unwrapping it. + /// + /// # Examples + /// + /// ``` + /// use std::pin::Pin; + /// + /// let pinned: Pin<&u8> = Pin::new(&5); + /// // Unwrap the pin to get a reference to the value + /// let r = Pin::into_inner(pinned); + /// assert_eq!(*r, 5); + /// ``` #[inline(always)] #[rustc_const_unstable(feature = "const_pin", issue = "76654")] #[stable(feature = "pin_into_inner", since = "1.39.0")] From dfa90e76b7d24f8b7f5b588df884b93807b64790 Mon Sep 17 00:00:00 2001 From: ch-iv Date: Wed, 9 Nov 2022 09:59:05 -0500 Subject: [PATCH 3/7] fix formatting --- library/core/src/pin.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/library/core/src/pin.rs b/library/core/src/pin.rs index 1af638a6b8a63..421efa7659a84 100644 --- a/library/core/src/pin.rs +++ b/library/core/src/pin.rs @@ -485,12 +485,12 @@ impl> Pin

{ /// /// Unlike `Pin::new_unchecked`, this method is safe because the pointer /// `P` dereferences to an [`Unpin`] type, which cancels the pinning guarantees. - /// + /// /// # Examples - /// + /// /// ``` /// use std::pin::Pin; - /// + /// /// let val: u8 = 5; /// // Wrap the value in a pin to make sure it doesn't move /// let pinned: Pin<&u8> = Pin::new(&val); @@ -508,9 +508,9 @@ impl> Pin

{ /// /// This requires that the data inside this `Pin` is [`Unpin`] so that we /// can ignore the pinning invariants when unwrapping it. - /// + /// /// # Examples - /// + /// /// ``` /// use std::pin::Pin; /// From 6f48b60ace325b4b8f7260012df8a47ef04fdbbf Mon Sep 17 00:00:00 2001 From: ch-iv Date: Wed, 9 Nov 2022 17:02:30 -0500 Subject: [PATCH 4/7] Repace inaccruate comment --- library/core/src/pin.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/pin.rs b/library/core/src/pin.rs index 421efa7659a84..df65fcfe151cd 100644 --- a/library/core/src/pin.rs +++ b/library/core/src/pin.rs @@ -492,7 +492,7 @@ impl> Pin

{ /// use std::pin::Pin; /// /// let val: u8 = 5; - /// // Wrap the value in a pin to make sure it doesn't move + /// // We can pin the value, since it doesn't care about being moved /// let pinned: Pin<&u8> = Pin::new(&val); /// ``` #[inline(always)] From a4ee02b15ce1cf1518b0b2661a6f00d94847755b Mon Sep 17 00:00:00 2001 From: ch-iv Date: Wed, 9 Nov 2022 17:07:58 -0500 Subject: [PATCH 5/7] formatting --- library/core/src/pin.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/pin.rs b/library/core/src/pin.rs index df65fcfe151cd..12cef04d1f9b7 100644 --- a/library/core/src/pin.rs +++ b/library/core/src/pin.rs @@ -492,7 +492,7 @@ impl> Pin

{ /// use std::pin::Pin; /// /// let val: u8 = 5; - /// // We can pin the value, since it doesn't care about being moved + /// // We can pin the value, since it doesn't care about being moved /// let pinned: Pin<&u8> = Pin::new(&val); /// ``` #[inline(always)] From 06c2ce05a4b0d05553858cf1951f75777a7e9406 Mon Sep 17 00:00:00 2001 From: ch-iv <108201575+ch-iv@users.noreply.github.com> Date: Thu, 10 Nov 2022 08:34:13 -0500 Subject: [PATCH 6/7] Update library/core/src/pin.rs Co-authored-by: Vincenzo Palazzo --- library/core/src/pin.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/pin.rs b/library/core/src/pin.rs index 12cef04d1f9b7..eafbc2c781889 100644 --- a/library/core/src/pin.rs +++ b/library/core/src/pin.rs @@ -506,7 +506,7 @@ impl> Pin

{ /// Unwraps this `Pin

` returning the underlying pointer. /// - /// This requires that the data inside this `Pin` is [`Unpin`] so that we + /// This requires that the data inside this `Pin` implements [`Unpin`] so that we /// can ignore the pinning invariants when unwrapping it. /// /// # Examples From 7a47e2c85314ec5c13c5d0bd2992997bb10033d6 Mon Sep 17 00:00:00 2001 From: ch-iv Date: Wed, 23 Nov 2022 16:55:25 -0500 Subject: [PATCH 7/7] Demonstrate with an &mut reference --- library/core/src/pin.rs | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/library/core/src/pin.rs b/library/core/src/pin.rs index f94969d7c1ac9..3f8acc8505ff1 100644 --- a/library/core/src/pin.rs +++ b/library/core/src/pin.rs @@ -491,9 +491,9 @@ impl> Pin

{ /// ``` /// use std::pin::Pin; /// - /// let val: u8 = 5; + /// let mut val: u8 = 5; /// // We can pin the value, since it doesn't care about being moved - /// let pinned: Pin<&u8> = Pin::new(&val); + /// let mut pinned: Pin<&mut u8> = Pin::new(&mut val); /// ``` #[inline(always)] #[rustc_const_unstable(feature = "const_pin", issue = "76654")] @@ -514,7 +514,8 @@ impl> Pin

{ /// ``` /// use std::pin::Pin; /// - /// let pinned: Pin<&u8> = Pin::new(&5); + /// let mut val: u8 = 5; + /// let pinned: Pin<&mut u8> = Pin::new(&mut val); /// // Unwrap the pin to get a reference to the value /// let r = Pin::into_inner(pinned); /// assert_eq!(*r, 5); @@ -728,6 +729,18 @@ impl Pin

{ /// /// This overwrites pinned data, but that is okay: its destructor gets /// run before being overwritten, so no pinning guarantee is violated. + /// + /// # Example + /// + /// ``` + /// use std::pin::Pin; + /// + /// let mut val: u8 = 5; + /// let mut pinned: Pin<&mut u8> = Pin::new(&mut val); + /// println!("{}", pinned); // 5 + /// pinned.as_mut().set(10); + /// println!("{}", pinned); // 10 + /// ``` #[stable(feature = "pin", since = "1.33.0")] #[inline(always)] pub fn set(&mut self, value: P::Target)