libs: make Cow usable, improve documentation

This commit makes `Cow` more usable by allowing it to be applied to
unsized types (as was intended) and providing some basic `ToOwned`
implementations on slice types. It also corrects the documentation for
`Cow` to no longer mention `DerefMut`, and adds an example.

1 files changed, 23 insertions, 7 deletions

diff --git a/src/libcore/borrow.rs b/src/libcore/borrow.rs
index f0a14c02382..f381d70a91b 100644
--- a/src/libcore/borrow.rs
+++ b/src/libcore/borrow.rs
@@ -37,10 +37,10 @@
 //! data lazily when mutation or ownership is required. The type is designed to
 //! work with general borrowed data via the `BorrowFrom` trait.
 //!
-//! `Cow` implements both `Deref` and `DerefMut`, which means that you can call
-//! methods directly on the data it encloses. The first time a mutable reference
-//! is required, the data will be cloned (via `to_owned`) if it is not
-//! already owned.
+//! `Cow` implements both `Deref`, which means that you can call
+//! non-mutating methods directly on the data it encloses. If mutation
+//! is desired, `to_mut` will obtain a mutable references to an owned
+//! value, cloning if necessary.
 
 #![unstable = "recently added as part of collections reform"]
 
@@ -84,7 +84,23 @@ impl<T> ToOwned<T> for T where T: Clone {
 }
 
 /// A clone-on-write smart pointer.
-pub enum Cow<'a, T, B: 'a> where B: ToOwned<T> {
+///
+/// # Example
+///
+/// ```rust
+/// use std::borrow::Cow;
+///
+/// fn abs_all(input: &mut Cow<Vec<int>, [int]>) {
+///     for i in range(0, input.len()) {
+///         let v = input[i];
+///         if v < 0 {
+///             // clones into a vector the first time (if not already owned)
+///             input.to_mut()[i] = -v;
+///         }
+///     }
+/// }
+/// ```
+pub enum Cow<'a, T, Sized? B: 'a> where B: ToOwned<T> {
     /// Borrowed data.
     Borrowed(&'a B),
 
@@ -92,7 +108,7 @@ pub enum Cow<'a, T, B: 'a> where B: ToOwned<T> {
     Owned(T)
 }
 
-impl<'a, T, B> Cow<'a, T, B> where B: ToOwned<T> {
+impl<'a, T, Sized? B> Cow<'a, T, B> where B: ToOwned<T> {
     /// Acquire a mutable reference to the owned form of the data.
     ///
     /// Copies the data if it is not already owned.
@@ -117,7 +133,7 @@ impl<'a, T, B> Cow<'a, T, B> where B: ToOwned<T> {
     }
 }
 
-impl<'a, T, B> Deref<B> for Cow<'a, T, B> where B: ToOwned<T>  {
+impl<'a, T, Sized? B> Deref<B> for Cow<'a, T, B> where B: ToOwned<T>  {
     fn deref(&self) -> &B {
         match *self {
             Borrowed(borrowed) => borrowed,