Add example for Cow

[kpp]

Add one more example that shows how to keep Cow in a struct.

Link to playground: https://play.rust-lang.org/?gist=a9256bdd034b44bc3cdd0044bbcdbb7c&version=stable&mode=debug&edition=2015

Users ask this question in ruRust chat time to time and it is not obvious to add ToOwned<Owned=Target> to requirements of generic params.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @withoutboats (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[TimNN]

Ping from triage @withoutboats / @rust-lang/docs: This PR requires your review.

[GuillaumeGomez]

Please add an "introduction" sentence explaining what does this new example (otherwise it's strange to just have two examples following each other).

[kpp]

Done

[GuillaumeGomez]

Please remove this empty line.

[frewsxcv]

Thanks for the docs addition @kpp! You mentioned that users in the ruRust chat have been asking how to do this. Do you think the main reason users are struggling with this because of the [X]: ToOwned<Owned=Vec<X> syntax? If so, do you think it would be sufficient to just have a something like this?

/// If you want to have a structure with a generic type that implements `ToOwned`:
///
/// ```rust
/// struct Items<'a, X: 'a>
///     where [X]: ToOwned<Owned=Vec<X>>
/// {
///     values: Cow<'a, [X]>,
/// }
/// ```

[kpp]

struggling with this because of the [X]: ToOwned<Owned=Vec<X>> syntax

It is hard to tell. Maybe because in this example you don't need to specify [i32]: ToOwned<Owned=Vec<i32>>.

Here is how users try to implement it (forgetting to specify ToOwned<Owned=Vec<X>>):

https://play.rust-lang.org/?gist=46d00be1797064d67deeee75383e7a7e&version=stable&mode=debug&edition=2015

struct Items<'a, X> where [X]: 'a {
    values: Cow<'a, [X]>,
}

They got this error:

error[E0277]: the trait bound `[X]: std::borrow::ToOwned` is not satisfied
 --> src/main.rs:5:5
  |
5 |     values: Cow<'a, [X]>,
  |     ^^^^^^^^^^^^^^^^^^^^ the trait `std::borrow::ToOwned` is not implemented for `[X]`
  |
  = help: consider adding a `where [X]: std::borrow::ToOwned` bound
  = note: required by `std::borrow::Cow`

They add [X]: std::borrow::ToOwned (without Owned=Vec<X> as the compiler did not mention it):

struct Items<'a, X> where [X]: 'a + ToOwned {
    values: Cow<'a, [X]>,
}

And they get sad errors like:

error[E0599]: no method named `push` found for type `&mut <[X] as std::borrow::ToOwned>::Owned` in the current scope
  --> src/main.rs:10:30
   |
10 |         self.values.to_mut().push(x);
   |                              ^^^^

If so, do you think it would be sufficient to just have a something like this?

Probably yes. Or shall we change the compiler warning?

[GuillaumeGomez]

Now please add an "empty" line before the example. 😆

[kpp]

Done

[GuillaumeGomez]

All good for me.

[pietroalbini]

Ping from triage @withoutboats! This PR needs your review.
Otherwise, if you're OK with it, @GuillaumeGomez can you approve the changes?

[GuillaumeGomez]

I'll go ahead and r+ it then. Thanks @kpp!

@bors: r+ rollup

[bors]

📌 Commit 5bfb785 has been approved by GuillaumeGomez