From 2853448426ce76926baa7e6e6173c15228e4951a Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Tue, 23 Jun 2020 11:42:15 +0200 Subject: [PATCH 1/3] Document the ref keyword --- src/libstd/keyword_docs.rs | 44 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index a4996d9eee8..aca7f880ecd 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -991,9 +991,49 @@ mod pub_keyword {} // /// Bind by reference during pattern matching. /// -/// The documentation for this keyword is [not yet complete]. Pull requests welcome! +/// `ref` annotates pattern bindings to make them borrow rather than move. +/// It is **not** a part of the pattern as far as matching is concerned. /// -/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601 +/// By default, [`match`] statements consume all they can, which can sometimes +/// be a problem, when you don't really need the value to be moved and owned: +/// +/// ```compile_fail,E0382 +/// let maybe_name = Some(String::from("Alice")); +/// // The variable 'maybe_name' is consumed here ... +/// match maybe_name { +/// Some(n) => println!("Hello, {}", n), +/// _ => println!("Hello, world"), +/// } +/// // ... and now unavailable. +/// println!("Hello again, {}", maybe_name.unwrap_or("world".into())); +/// ``` +/// +/// Using the `ref` keyword, the value is only borrowed, not moved, making +/// available for use after the [`match`] statement: +/// +/// ``` +/// let maybe_name = Some(String::from("Alice")); +/// // Using `ref`, the value is borrowed, not moved ... +/// match maybe_name { +/// Some(ref n) => println!("Hello, {}", n), +/// _ => println!("Hello, world"), +/// } +/// // ... and it's available here ! +/// println!("Hello again, {}", maybe_name.unwrap_or("world".into())); +/// ``` +/// +/// # `&` vs `ref` +/// +/// - `&` denotes that your pattern expects a reference to an object. Hence `&` +/// is a part of said pattern: `&Foo` matches different objects than `Foo` does. +/// +/// - `ref` indicates that you want a reference to an unpacked value. It is not +/// matched against: `Foo(ref foo)` matches the same objects as `Foo(foo)`. +/// +/// See also the [Reference] for more information. +/// +/// [`match`]: keyword.match.html +/// [Reference]: ../reference/patterns.html#identifier-patterns mod ref_keyword {} #[doc(keyword = "return")] From b36479fcf8d4694ca29fdcc0c7fb1507a6da21c5 Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Thu, 23 Jul 2020 23:30:16 +0200 Subject: [PATCH 2/3] Fix nit --- src/libstd/keyword_docs.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index aca7f880ecd..f29bd99173a 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -992,7 +992,8 @@ mod pub_keyword {} /// Bind by reference during pattern matching. /// /// `ref` annotates pattern bindings to make them borrow rather than move. -/// It is **not** a part of the pattern as far as matching is concerned. +/// It is **not** a part of the pattern as far as matching is concerned: it does +/// not affect *whether* a value is matched, only *how* it is matched. /// /// By default, [`match`] statements consume all they can, which can sometimes /// be a problem, when you don't really need the value to be moved and owned: From 79f052bd4fa7f695a96515c44c5a72e75cf782ee Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Fri, 24 Jul 2020 19:06:26 +0200 Subject: [PATCH 3/3] Fix nits --- src/libstd/keyword_docs.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index f29bd99173a..ea1b9f3672f 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -1005,11 +1005,11 @@ mod pub_keyword {} /// Some(n) => println!("Hello, {}", n), /// _ => println!("Hello, world"), /// } -/// // ... and now unavailable. +/// // ... and is now unavailable. /// println!("Hello again, {}", maybe_name.unwrap_or("world".into())); /// ``` /// -/// Using the `ref` keyword, the value is only borrowed, not moved, making +/// Using the `ref` keyword, the value is only borrowed, not moved, making it /// available for use after the [`match`] statement: /// /// ``` @@ -1019,7 +1019,7 @@ mod pub_keyword {} /// Some(ref n) => println!("Hello, {}", n), /// _ => println!("Hello, world"), /// } -/// // ... and it's available here ! +/// // ... so it's available here! /// println!("Hello again, {}", maybe_name.unwrap_or("world".into())); /// ``` ///