add example for `Rc::would_unwrap`

Part of #29372

r? @steveklabnik

1 files changed, 17 insertions, 0 deletions

diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs
index 2beb652aa01..3a158240c3a 100644
--- a/src/liballoc/rc.rs
+++ b/src/liballoc/rc.rs
@@ -263,6 +263,23 @@ impl<T> Rc<T> {
     }
 
     /// Checks if `Rc::try_unwrap` would return `Ok`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(rc_would_unwrap)]
+    ///
+    /// use std::rc::Rc;
+    ///
+    /// let x = Rc::new(3);
+    /// assert!(Rc::would_unwrap(&x));
+    /// assert_eq!(Rc::try_unwrap(x), Ok(3));
+    ///
+    /// let x = Rc::new(4);
+    /// let _y = x.clone();
+    /// assert!(!Rc::would_unwrap(&x));
+    /// assert_eq!(Rc::try_unwrap(x), Err(Rc::new(4)));
+    /// ```
     #[unstable(feature = "rc_would_unwrap",
                reason = "just added for niche usecase",
                issue = "28356")]