Document std::borrow with examples

[steveklabnik]

No description provided.

[rust-highfive]

r? @pcwalton

(rust_highfive has picked a reviewer for you, use r? to override)

[alexcrichton]

With the borrow module I believe the primary use case is actually through generics, not through direct usage for the traits. Perhaps the examples could show off some examples of using Borrow and BorrowMut in generic contexts?

[steveklabnik]

@alexcrichton ahhh yes, i will do that then

[steveklabnik]

So, in the intervening time, I get errors when trying to run rustdoc on libcollections:

$ rustdoc --test src/libcollections/lib.rs 
src/libcollections/btree/map.rs:1392:32: 1392:58 error: slice pattern syntax is experimental
src/libcollections/btree/map.rs:1392                         if let [ref $($mutability)* edge] = slice.edges {
                                                                    ^~~~~~~~~~~~~~~~~~~~~~~~~~
src/libcollections/btree/map.rs:1342:1: 1470:2 note: in expansion of range_impl!
src/libcollections/btree/map.rs:1496:9: 1497:6 note: expansion site
src/libcollections/btree/map.rs:1392:58: 1392:58 help: add #![feature(slice_patterns)] to the crate attributes to enable
src/libcollections/btree/map.rs:1342:1: 1470:2 note: in expansion of range_impl!
src/libcollections/btree/map.rs:1496:9: 1497:6 note: expansion site
src/libcollections/btree/map.rs:1392:32: 1392:58 error: slice pattern syntax is experimental
src/libcollections/btree/map.rs:1392                         if let [ref $($mutability)* edge] = slice.edges {
                                                                    ^~~~~~~~~~~~~~~~~~~~~~~~~~
src/libcollections/btree/map.rs:1342:1: 1470:2 note: in expansion of range_impl!
src/libcollections/btree/map.rs:1523:9: 1525:6 note: expansion site
src/libcollections/btree/map.rs:1392:58: 1392:58 help: add #![feature(slice_patterns)] to the crate attributes to enable
src/libcollections/btree/map.rs:1342:1: 1470:2 note: in expansion of range_impl!
src/libcollections/btree/map.rs:1523:9: 1525:6 note: expansion site
error: aborting due to 2 previous errors
thread '<unnamed>' panicked at 'Box<Any>', /home/rustbuild/src/rust-buildbot/slave/nightly-dist-rustc-linux/build/src/libsyntax/diagnostic.rs:152
thread '<main>' panicked at 'child thread None panicked', /home/rustbuild/src/rust-buildbot/slave/nightly-dist-rustc-linux/build/src/libstd/thread/mod.rs:775

Unsure what's up with that. The build shouldn't be failing now, should it?

[steveklabnik]

Nevermind, i needed to rebase, that's all

[steveklabnik]

@alexcrichton updated, r?

[alexcrichton]

I think that this example may want to be redone a bit, the Owned variant is meant to represent something like String, and you probably don't want to call to_mut on Cow<str> because that will give you the type &mut str which isn't super useful.

Perhaps this could be Cow<[_]> where the owned variant is vec![1, 2, 3] and then you call .to_mut() to modify one of the elements and then assert that the cow is equal to a slice?

[steveklabnik]

Sounds good. This was an awkward one to even write.

[steveklabnik]

@alexcrichton updated, thanks :D

[alexcrichton]

@bors: r+ edc096d

[alexcrichton]

@bors: rollup