diff --git a/library/alloc/src/boxed.rs b/library/alloc/src/boxed.rs index ed3ad8b39a5..e5d62447eb2 100644 --- a/library/alloc/src/boxed.rs +++ b/library/alloc/src/boxed.rs @@ -2088,11 +2088,29 @@ impl Clone for Box<[T], A> { self.to_vec_in(alloc).into_boxed_slice() } - fn clone_from(&mut self, other: &Self) { - if self.len() == other.len() { - self.clone_from_slice(&other); + /// Copies `source`'s contents into `self` without creating a new allocation, + /// so long as the two are of the same length. + /// + /// # Examples + /// + /// ``` + /// let x = Box::new([5, 6, 7]); + /// let mut y = Box::new([8, 9, 10]); + /// let yp: *const [i32] = &*y; + /// + /// y.clone_from(&x); + /// + /// // The value is the same + /// assert_eq!(x, y); + /// + /// // And no allocation occurred + /// assert_eq!(yp, &*y); + /// ``` + fn clone_from(&mut self, source: &Self) { + if self.len() == source.len() { + self.clone_from_slice(&source); } else { - *self = other.clone(); + *self = source.clone(); } } } diff --git a/library/alloc/src/collections/binary_heap/mod.rs b/library/alloc/src/collections/binary_heap/mod.rs index 83b2678f7f5..c54f0062824 100644 --- a/library/alloc/src/collections/binary_heap/mod.rs +++ b/library/alloc/src/collections/binary_heap/mod.rs @@ -385,6 +385,12 @@ impl Clone for BinaryHeap { BinaryHeap { data: self.data.clone() } } + /// Overwrites the contents of `self` with a clone of the contents of `source`. + /// + /// This method is preferred over simply assigning `source.clone()` to `self`, + /// as it avoids reallocation if possible. + /// + /// See [`Vec::clone_from()`] for more details. fn clone_from(&mut self, source: &Self) { self.data.clone_from(&source.data); } diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs index 7508ae468ae..b0bd6ef2d3c 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -116,8 +116,8 @@ impl Clone for BTreeSet { BTreeSet { map: self.map.clone() } } - fn clone_from(&mut self, other: &Self) { - self.map.clone_from(&other.map); + fn clone_from(&mut self, source: &Self) { + self.map.clone_from(&source.map); } } diff --git a/library/alloc/src/collections/linked_list.rs b/library/alloc/src/collections/linked_list.rs index 6dfb82ac807..1c90c171a15 100644 --- a/library/alloc/src/collections/linked_list.rs +++ b/library/alloc/src/collections/linked_list.rs @@ -2126,16 +2126,22 @@ impl Clone for LinkedList { list } - fn clone_from(&mut self, other: &Self) { - let mut iter_other = other.iter(); - if self.len() > other.len() { - self.split_off(other.len()); + /// Overwrites the contents of `self` with a clone of the contents of `source`. + /// + /// This method is preferred over simply assigning `source.clone()` to `self`, + /// as it avoids reallocation of the nodes of the linked list. Additionally, + /// if the element type `T` overrides `clone_from()`, this will reuse the + /// resources of `self`'s elements as well. + fn clone_from(&mut self, source: &Self) { + let mut source_iter = source.iter(); + if self.len() > source.len() { + self.split_off(source.len()); } - for (elem, elem_other) in self.iter_mut().zip(&mut iter_other) { - elem.clone_from(elem_other); + for (elem, source_elem) in self.iter_mut().zip(&mut source_iter) { + elem.clone_from(source_elem); } - if !iter_other.is_empty() { - self.extend(iter_other.cloned()); + if !source_iter.is_empty() { + self.extend(source_iter.cloned()); } } } diff --git a/library/alloc/src/collections/vec_deque/mod.rs b/library/alloc/src/collections/vec_deque/mod.rs index 693ecb0b6b4..4643a6bbe2e 100644 --- a/library/alloc/src/collections/vec_deque/mod.rs +++ b/library/alloc/src/collections/vec_deque/mod.rs @@ -113,9 +113,13 @@ impl Clone for VecDeque { deq } - fn clone_from(&mut self, other: &Self) { + /// Overwrites the contents of `self` with a clone of the contents of `source`. + /// + /// This method is preferred over simply assigning `source.clone()` to `self`, + /// as it avoids reallocation if possible. + fn clone_from(&mut self, source: &Self) { self.clear(); - self.extend(other.iter().cloned()); + self.extend(source.iter().cloned()); } } diff --git a/library/alloc/src/string.rs b/library/alloc/src/string.rs index 5d552c8f15c..082af1447ec 100644 --- a/library/alloc/src/string.rs +++ b/library/alloc/src/string.rs @@ -2097,6 +2097,10 @@ impl Clone for String { String { vec: self.vec.clone() } } + /// Clones the contents of `source` into `self`. + /// + /// This method is preferred over simply assigning `source.clone()` to `self`, + /// as it avoids reallocation if possible. fn clone_from(&mut self, source: &Self) { self.vec.clone_from(&source.vec); } diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index 465da39f184..1930be65bfb 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -2846,8 +2846,30 @@ impl Clone for Vec { crate::slice::to_vec(&**self, alloc) } - fn clone_from(&mut self, other: &Self) { - crate::slice::SpecCloneIntoVec::clone_into(other.as_slice(), self); + /// Overwrites the contents of `self` with a clone of the contents of `source`. + /// + /// This method is preferred over simply assigning `source.clone()` to `self`, + /// as it avoids reallocation if possible. Additionally, if the element type + /// `T` overrides `clone_from()`, this will reuse the resources of `self`'s + /// elements as well. + /// + /// # Examples + /// + /// ``` + /// let x = vec![5, 6, 7]; + /// let mut y = vec![8, 9, 10]; + /// let yp: *const i32 = y.as_ptr(); + /// + /// y.clone_from(&x); + /// + /// // The value is the same + /// assert_eq!(x, y); + /// + /// // And no reallocation occurred + /// assert_eq!(yp, y.as_ptr()); + /// ``` + fn clone_from(&mut self, source: &Self) { + crate::slice::SpecCloneIntoVec::clone_into(source.as_slice(), self); } } diff --git a/library/core/src/cell.rs b/library/core/src/cell.rs index 58b9ba4accb..ae0436bc520 100644 --- a/library/core/src/cell.rs +++ b/library/core/src/cell.rs @@ -1277,11 +1277,11 @@ impl Clone for RefCell { /// # Panics /// - /// Panics if `other` is currently mutably borrowed. + /// Panics if `source` is currently mutably borrowed. #[inline] #[track_caller] - fn clone_from(&mut self, other: &Self) { - self.get_mut().clone_from(&other.borrow()) + fn clone_from(&mut self, source: &Self) { + self.get_mut().clone_from(&source.borrow()) } } diff --git a/library/core/src/cmp.rs b/library/core/src/cmp.rs index fa218600ed9..2fd9e17c994 100644 --- a/library/core/src/cmp.rs +++ b/library/core/src/cmp.rs @@ -688,8 +688,8 @@ impl Clone for Reverse { } #[inline] - fn clone_from(&mut self, other: &Self) { - self.0.clone_from(&other.0) + fn clone_from(&mut self, source: &Self) { + self.0.clone_from(&source.0) } } diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs index fe39f6c0b56..7691721b91e 100644 --- a/library/core/src/task/wake.rs +++ b/library/core/src/task/wake.rs @@ -576,6 +576,42 @@ impl Clone for Waker { } } + /// Assigns a clone of `source` to `self`, unless [`self.will_wake(source)`][Waker::will_wake] anyway. + /// + /// This method is preferred over simply assigning `source.clone()` to `self`, + /// as it avoids cloning the waker if `self` is already the same waker. + /// + /// # Examples + /// + /// ``` + /// use std::future::Future; + /// use std::pin::Pin; + /// use std::sync::{Arc, Mutex}; + /// use std::task::{Context, Poll, Waker}; + /// + /// struct Waiter { + /// shared: Arc>, + /// } + /// + /// struct Shared { + /// waker: Waker, + /// // ... + /// } + /// + /// impl Future for Waiter { + /// type Output = (); + /// fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> { + /// let mut shared = self.shared.lock().unwrap(); + /// + /// // update the waker + /// shared.waker.clone_from(cx.waker()); + /// + /// // readiness logic ... + /// # Poll::Ready(()) + /// } + /// } + /// + /// ``` #[inline] fn clone_from(&mut self, source: &Self) { if !self.will_wake(source) { diff --git a/library/std/src/collections/hash/map.rs b/library/std/src/collections/hash/map.rs index 2cc9afe9249..5039f0b6bb2 100644 --- a/library/std/src/collections/hash/map.rs +++ b/library/std/src/collections/hash/map.rs @@ -1271,8 +1271,8 @@ where } #[inline] - fn clone_from(&mut self, other: &Self) { - self.base.clone_from(&other.base); + fn clone_from(&mut self, source: &Self) { + self.base.clone_from(&source.base); } } diff --git a/library/std/src/collections/hash/set.rs b/library/std/src/collections/hash/set.rs index 3910100f212..f0a498fc7bb 100644 --- a/library/std/src/collections/hash/set.rs +++ b/library/std/src/collections/hash/set.rs @@ -978,6 +978,10 @@ where Self { base: self.base.clone() } } + /// Overwrites the contents of `self` with a clone of the contents of `source`. + /// + /// This method is preferred over simply assigning `source.clone()` to `self`, + /// as it avoids reallocation if possible. #[inline] fn clone_from(&mut self, other: &Self) { self.base.clone_from(&other.base); diff --git a/library/std/src/ffi/os_str.rs b/library/std/src/ffi/os_str.rs index 8927e9a47fa..20ebe1c4f8a 100644 --- a/library/std/src/ffi/os_str.rs +++ b/library/std/src/ffi/os_str.rs @@ -606,6 +606,10 @@ impl Clone for OsString { OsString { inner: self.inner.clone() } } + /// Clones the contents of `source` into `self`. + /// + /// This method is preferred over simply assigning `source.clone()` to `self`, + /// as it avoids reallocation if possible. #[inline] fn clone_from(&mut self, source: &Self) { self.inner.clone_from(&source.inner) diff --git a/library/std/src/path.rs b/library/std/src/path.rs index 5f43d63bf84..0636f55771e 100644 --- a/library/std/src/path.rs +++ b/library/std/src/path.rs @@ -1628,6 +1628,10 @@ impl Clone for PathBuf { PathBuf { inner: self.inner.clone() } } + /// Clones the contents of `source` into `self`. + /// + /// This method is preferred over simply assigning `source.clone()` to `self`, + /// as it avoids reallocation if possible. #[inline] fn clone_from(&mut self, source: &Self) { self.inner.clone_from(&source.inner)