Auto merge of #41009 - scottmcm:toowned-clone-into, r=alexcrichton

Add a resource-reusing method to `ToOwned`

`ToOwned::to_owned` generalizes `Clone::clone`, but `ToOwned` doesn't have an equivalent to `Clone::clone_from`.  This PR adds such a method as `clone_into` under a new unstable feature `toowned_clone_into`.

Analogous to `clone_from`, this has the obvious default implementation in terms of `to_owned`.  I've updated the `libcollections` impls: for `T:Clone` it uses `clone_from`, for `[T]` I moved the code from `Vec::clone_from` and implemented that in terms of this, and for `str` it's a predictable implementation in terms of `[u8]`.

Used it in `Cow::clone_from` to reuse resources when both are `Cow::Owned`, and added a test that `Cow<str>` thus keeps capacity in `clone_from` in that situation.

The obvious question: is this the right place for the method?
- It's here so it lives next to `to_owned`, making the default implementation reasonable, and avoiding another trait.  But allowing method syntax forces a name like `clone_into`, rather than something more consistent like `owned_from`.
- Another trait would allow `owned_from` and could support multiple owning types per borrow type.  But it'd be another single-method trait that generalizes `Clone`, and I don't know how to give it a default impl in terms of `ToOwned::to_owned`, since a blanket would mean overlapping impls problems.

I did it this way as it's simpler and many of the `Borrow`s/`AsRef`s don't make sense with `owned_from` anyway (`[T;1]:Borrow<[T]>`, `Arc<T>:Borrow<T>`, `String:AsRef<OsStr>`...).  I'd be happy to re-do it the other way, though, if someone has a good solution for the default handling.

(I can also update with `CStr`, `OsStr`, and `Path` once a direction is decided.)

Author: bors

src/doc/unstable-book/src/SUMMARY.md

@@ -198,6 +198,7 @@
 - [thread_local](thread-local.md)
 - [thread_local_internals](thread-local-internals.md)
 - [thread_local_state](thread-local-state.md)
+- [toowned_clone_into](toowned-clone-into.md)
 - [trace_macros](trace-macros.md)
 - [trusted_len](trusted-len.md)
 - [try_from](try-from.md)

src/doc/unstable-book/src/toowned-clone-into.md

@@ -0,0 +1,7 @@
+# `toowned_clone_into`
+
+The tracking issue for this feature is: [#41263]
+
+[#41263]: https://github.com/rust-lang/rust/issues/41263
+
+------------------------

src/libcollections/borrow.rs

@@ -60,6 +60,29 @@ pub trait ToOwned {
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     fn to_owned(&self) -> Self::Owned;
+
+    /// Uses borrowed data to replace owned data, usually by cloning.
+    ///
+    /// This is borrow-generalized version of `Clone::clone_from`.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// # #![feature(toowned_clone_into)]
+    /// let mut s: String = String::new();
+    /// "hello".clone_into(&mut s);
+    ///
+    /// let mut v: Vec<i32> = Vec::new();
+    /// [1, 2][..].clone_into(&mut v);
+    /// ```
+    #[unstable(feature = "toowned_clone_into",
+               reason = "recently added",
+               issue = "41263")]
+    fn clone_into(&self, target: &mut Self::Owned) {
+        *target = self.to_owned();
+    }
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -70,6 +93,10 @@ impl<T> ToOwned for T
     fn to_owned(&self) -> T {
         self.clone()
     }
+
+    fn clone_into(&self, target: &mut T) {
+        target.clone_from(self);
+    }
 }
 
 /// A clone-on-write smart pointer.
@@ -141,6 +168,17 @@ impl<'a, B: ?Sized> Clone for Cow<'a, B>
             }
         }
     }
+
+    fn clone_from(&mut self, source: &Cow<'a, B>) {
+        if let Owned(ref mut dest) = *self {
+            if let Owned(ref o) = *source {
+                o.borrow().clone_into(dest);
+                return;
+            }
+        }
+
+        *self = source.clone();
+    }
 }
 
 impl<'a, B: ?Sized> Cow<'a, B>

src/libcollections/slice.rs

@@ -1527,6 +1527,19 @@ impl<T: Clone> ToOwned for [T] {
     fn to_owned(&self) -> Vec<T> {
         panic!("not available with cfg(test)")
     }
+
+    fn clone_into(&self, target: &mut Vec<T>) {
+        // drop anything in target that will not be overwritten
+        target.truncate(self.len());
+        let len = target.len();
+
+        // reuse the contained values' allocations/resources.
+        target.clone_from_slice(&self[..len]);
+
+        // target.len <= self.len due to the truncate above, so the
+        // slice here is always in-bounds.
+        target.extend_from_slice(&self[len..]);
+    }
 }
 
 ////////////////////////////////////////////////////////////////////////////////

src/libcollections/str.rs

@@ -199,6 +199,12 @@ impl ToOwned for str {
     fn to_owned(&self) -> String {
         unsafe { String::from_utf8_unchecked(self.as_bytes().to_owned()) }
     }
+
+    fn clone_into(&self, target: &mut String) {
+        let mut b = mem::replace(target, String::new()).into_bytes();
+        self.as_bytes().clone_into(&mut b);
+        *target = unsafe { String::from_utf8_unchecked(b) }
+    }
 }
 
 /// Methods for string slices.

src/libcollections/tests/cow_str.rs

@@ -139,3 +139,13 @@ fn check_cow_add_assign_str() {
     assert_eq!("Hi, World!", owned);
     assert_eq!("Hello, World!", borrowed);
 }
+
+#[test]
+fn check_cow_clone_from() {
+    let mut c1: Cow<str> = Cow::Owned(String::with_capacity(25));
+    let s: String = "hi".to_string();
+    assert!(s.capacity() < 25);
+    let c2: Cow<str> = Cow::Owned(s);
+    c1.clone_from(&c2);
+    assert!(c1.into_owned().capacity() >= 25);
+}

src/libcollections/vec.rs

@@ -1396,16 +1396,7 @@ impl<T: Clone> Clone for Vec<T> {
     }
 
     fn clone_from(&mut self, other: &Vec<T>) {
-        // drop anything in self that will not be overwritten
-        self.truncate(other.len());
-        let len = self.len();
-
-        // reuse the contained values' allocations/resources.
-        self.clone_from_slice(&other[..len]);
-
-        // self.len <= other.len due to the truncate above, so the
-        // slice here is always in-bounds.
-        self.extend_from_slice(&other[len..]);
+        other.as_slice().clone_into(self);
     }
 }