Auto merge of #53832 - pietroalbini:rollup, r=pietroalbini

Rollup of 20 pull requests

Successful merges:

 - #51760 (Add another PartialEq example)
 - #53113 (Add example for Cow)
 - #53129 (remove `let x = baz` which was obscuring the real error)
 - #53389 (document effect of join on memory ordering)
 - #53472 (Use FxHash{Map,Set} instead of the default Hash{Map,Set} everywhere in rustc.)
 - #53476 (Add partialeq implementation for TryFromIntError type)
 - #53513 (Force-inline `shallow_resolve` at its hottest call site.)
 - #53655 (set applicability)
 - #53702 (Fix stabilisation version for macro_vis_matcher.)
 - #53727 (Do not suggest dereferencing in macro)
 - #53732 (save-analysis: Differentiate foreign functions and statics.)
 - #53740 (add llvm-readobj to llvm-tools-preview)
 - #53743 (fix a typo: taget_env -> target_env)
 - #53747 (Rustdoc fixes)
 - #53753 (expand keep-stage --help text)
 - #53756 (Fix typo in comment)
 - #53768 (move file-extension based .gitignore down to src/)
 - #53785 (Fix a comment in src/libcore/slice/mod.rs)
 - #53786 (Replace usages of 'bad_style' with 'nonstandard_style'.)
 - #53806 (Fix UI issues on Implementations on Foreign types)

Failed merges:

r? @ghost

1 files changed, 35 insertions, 0 deletions

diff --git a/src/liballoc/borrow.rs b/src/liballoc/borrow.rs
index c6741ddb822..5ae5339138f 100644
--- a/src/liballoc/borrow.rs
+++ b/src/liballoc/borrow.rs
@@ -141,6 +141,41 @@ impl<T> ToOwned for T
 /// let mut input = Cow::from(vec![-1, 0, 1]);
 /// abs_all(&mut input);
 /// ```
+///
+/// Another example showing how to keep `Cow` in a struct:
+///
+/// ```
+/// use std::borrow::{Cow, ToOwned};
+///
+/// struct Items<'a, X: 'a> where [X]: ToOwned<Owned=Vec<X>> {
+///     values: Cow<'a, [X]>,
+/// }
+///
+/// impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned<Owned=Vec<X>> {
+///     fn new(v: Cow<'a, [X]>) -> Self {
+///         Items { values: v }
+///     }
+/// }
+///
+/// // Creates a container from borrowed values of a slice
+/// let readonly = [1, 2];
+/// let borrowed = Items::new((&readonly[..]).into());
+/// match borrowed {
+///     Items { values: Cow::Borrowed(b) } => println!("borrowed {:?}", b),
+///     _ => panic!("expect borrowed value"),
+/// }
+///
+/// let mut clone_on_write = borrowed;
+/// // Mutates the data from slice into owned vec and pushes a new value on top
+/// clone_on_write.values.to_mut().push(3);
+/// println!("clone_on_write = {:?}", clone_on_write.values);
+///
+/// // The data was mutated. Let check it out.
+/// match clone_on_write {
+///     Items { values: Cow::Owned(_) } => println!("clone_on_write contains owned data"),
+///     _ => panic!("expect owned data"),
+/// }
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub enum Cow<'a, B: ?Sized + 'a>
     where B: ToOwned