Commit 1e55f584 authored by bors's avatar bors

Auto merge of #73645 - poliorcetics:ref-keyword, r=jyn514

Document the ref keyword

Partial fix for #34601.

This documents the `ref` keyword with two examples, one failing to compile because the `ref` keyword is missing, and the same example fixed with the keyword inserted in the correct place.

It also explains (very *very* rapidly) the differences between `&` and `ref`.

I put a link to the best place I could find in the Reference but there may be something better that I didn't find.
parents 5ef299eb 79f052bd
......@@ -1060,9 +1060,50 @@ 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: it does
/// not affect *whether* a value is matched, only *how* it is matched.
///
/// [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 is now unavailable.
/// println!("Hello again, {}", maybe_name.unwrap_or("world".into()));
/// ```
///
/// Using the `ref` keyword, the value is only borrowed, not moved, making it
/// 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"),
/// }
/// // ... so 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")]
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment