From cc2a2808d078b0a7d49f7a89fa7d14ead1ebc0df Mon Sep 17 00:00:00 2001 From: Scott McMurray Date: Sat, 1 Jun 2019 17:29:05 -0700 Subject: [PATCH 1/6] Add some Vec <-> VecDeque documentation These are more than just `.into_iter().collect()`, so talk about some of their nuances. --- src/liballoc/collections/vec_deque.rs | 53 +++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/src/liballoc/collections/vec_deque.rs b/src/liballoc/collections/vec_deque.rs index 31e49d06a7b5a..8cda28a5e4023 100644 --- a/src/liballoc/collections/vec_deque.rs +++ b/src/liballoc/collections/vec_deque.rs @@ -2707,6 +2707,33 @@ impl fmt::Debug for VecDeque { } } +/// Turn a `Vec` into a `VecDeque`. +/// +/// This avoids reallocating where possible, but the conditions for that are +/// strict, and subject to change, so shouldn't be relied upon unless the +/// `Vec` came from `From` has hasn't been reallocated. +/// +/// # Examples +/// +/// ``` +/// use std::collections::VecDeque; +/// +/// // Start with a VecDeque +/// let deque: VecDeque<_> = (1..5).collect(); +/// +/// // Turn it into a Vec (no allocation needed) +/// let mut vec = Vec::from(deque); +/// +/// // modify it, being careful to not trigger reallocation +/// vec.pop(); +/// vec.push(100); +/// +/// // Turn it back into a VecDeque (no allocation needed) +/// let ptr = vec.as_ptr(); +/// let deque = VecDeque::from(vec); +/// assert_eq!(deque, [1, 2, 3, 100]); +/// assert_eq!(deque.as_slices().0.as_ptr(), ptr); +/// ``` #[stable(feature = "vecdeque_vec_conversions", since = "1.10.0")] impl From> for VecDeque { fn from(mut other: Vec) -> Self { @@ -2733,6 +2760,32 @@ impl From> for VecDeque { } } +/// Turn a `VecDeque` into a `Vec`. +/// +/// This never needs to re-allocate, but does need to do O(n) data movement if +/// the circular buffer doesn't happen to be at the beginning of the allocation. +/// +/// # Examples +/// +/// ``` +/// use std::collections::VecDeque; +/// +/// // This one is O(1) +/// let deque: VecDeque<_> = (1..5).collect(); +/// let ptr = deque.as_slices().0.as_ptr(); +/// let vec = Vec::from(deque); +/// assert_eq!(vec, [1, 2, 3, 4]); +/// assert_eq!(vec.as_ptr(), ptr); +/// +/// // This one need data rearranging +/// let mut deque: VecDeque<_> = (1..5).collect(); +/// deque.push_front(9); +/// deque.push_front(8); +/// let ptr = deque.as_slices().1.as_ptr(); +/// let vec = Vec::from(deque); +/// assert_eq!(vec, [8, 9, 1, 2, 3, 4]); +/// assert_eq!(vec.as_ptr(), ptr); +/// ``` #[stable(feature = "vecdeque_vec_conversions", since = "1.10.0")] impl From> for Vec { fn from(other: VecDeque) -> Self { From 2da4f9ad5ed80bb1488377711699c5f320ae89db Mon Sep 17 00:00:00 2001 From: scottmcm Date: Sat, 1 Jun 2019 19:47:50 -0700 Subject: [PATCH 2/6] Apply suggestions from code review Co-Authored-By: Mazdak Farrokhzad --- src/liballoc/collections/vec_deque.rs | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/liballoc/collections/vec_deque.rs b/src/liballoc/collections/vec_deque.rs index 8cda28a5e4023..d1c9de7c83cf1 100644 --- a/src/liballoc/collections/vec_deque.rs +++ b/src/liballoc/collections/vec_deque.rs @@ -2707,28 +2707,28 @@ impl fmt::Debug for VecDeque { } } -/// Turn a `Vec` into a `VecDeque`. +/// Turn a `Vec` into a `VecDeque`. /// /// This avoids reallocating where possible, but the conditions for that are -/// strict, and subject to change, so shouldn't be relied upon unless the -/// `Vec` came from `From` has hasn't been reallocated. +/// strict, and subject to change, and so shouldn't be relied upon unless the +/// `Vec` came from `From>` has hasn't been reallocated. /// /// # Examples /// /// ``` /// use std::collections::VecDeque; /// -/// // Start with a VecDeque +/// // Start with a `VecDeque`. /// let deque: VecDeque<_> = (1..5).collect(); /// -/// // Turn it into a Vec (no allocation needed) +/// // Turn it into a `Vec` with no allocation needed. /// let mut vec = Vec::from(deque); /// -/// // modify it, being careful to not trigger reallocation +/// // Modify it, being careful not to trigger reallocation. /// vec.pop(); /// vec.push(100); /// -/// // Turn it back into a VecDeque (no allocation needed) +/// // Turn it back into a `VecDeque` with no allocation needed. /// let ptr = vec.as_ptr(); /// let deque = VecDeque::from(vec); /// assert_eq!(deque, [1, 2, 3, 100]); @@ -2760,7 +2760,7 @@ impl From> for VecDeque { } } -/// Turn a `VecDeque` into a `Vec`. +/// Turn a `VecDeque` into a `Vec`. /// /// This never needs to re-allocate, but does need to do O(n) data movement if /// the circular buffer doesn't happen to be at the beginning of the allocation. @@ -2770,14 +2770,14 @@ impl From> for VecDeque { /// ``` /// use std::collections::VecDeque; /// -/// // This one is O(1) +/// // This one is O(1). /// let deque: VecDeque<_> = (1..5).collect(); /// let ptr = deque.as_slices().0.as_ptr(); /// let vec = Vec::from(deque); /// assert_eq!(vec, [1, 2, 3, 4]); /// assert_eq!(vec.as_ptr(), ptr); /// -/// // This one need data rearranging +/// // This one needs data rearranging. /// let mut deque: VecDeque<_> = (1..5).collect(); /// deque.push_front(9); /// deque.push_front(8); From 1f4a262d85e4a87ebbdded023b2422cd41ce3fef Mon Sep 17 00:00:00 2001 From: Scott McMurray Date: Sat, 1 Jun 2019 19:52:18 -0700 Subject: [PATCH 3/6] Put the docs on the methods instead of the impls Since simulacrum suggested (on Discord) they're better there. --- src/liballoc/collections/vec_deque.rs | 106 +++++++++++++------------- 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/src/liballoc/collections/vec_deque.rs b/src/liballoc/collections/vec_deque.rs index d1c9de7c83cf1..79a36d7248df4 100644 --- a/src/liballoc/collections/vec_deque.rs +++ b/src/liballoc/collections/vec_deque.rs @@ -2707,35 +2707,35 @@ impl fmt::Debug for VecDeque { } } -/// Turn a `Vec` into a `VecDeque`. -/// -/// This avoids reallocating where possible, but the conditions for that are -/// strict, and subject to change, and so shouldn't be relied upon unless the -/// `Vec` came from `From>` has hasn't been reallocated. -/// -/// # Examples -/// -/// ``` -/// use std::collections::VecDeque; -/// -/// // Start with a `VecDeque`. -/// let deque: VecDeque<_> = (1..5).collect(); -/// -/// // Turn it into a `Vec` with no allocation needed. -/// let mut vec = Vec::from(deque); -/// -/// // Modify it, being careful not to trigger reallocation. -/// vec.pop(); -/// vec.push(100); -/// -/// // Turn it back into a `VecDeque` with no allocation needed. -/// let ptr = vec.as_ptr(); -/// let deque = VecDeque::from(vec); -/// assert_eq!(deque, [1, 2, 3, 100]); -/// assert_eq!(deque.as_slices().0.as_ptr(), ptr); -/// ``` #[stable(feature = "vecdeque_vec_conversions", since = "1.10.0")] impl From> for VecDeque { + /// Turn a `Vec` into a `VecDeque`. + /// + /// This avoids reallocating where possible, but the conditions for that are + /// strict, and subject to change, and so shouldn't be relied upon unless the + /// `Vec` came from `From>` has hasn't been reallocated. + /// + /// # Examples + /// + /// ``` + /// use std::collections::VecDeque; + /// + /// // Start with a `VecDeque`. + /// let deque: VecDeque<_> = (1..5).collect(); + /// + /// // Turn it into a `Vec` with no allocation needed. + /// let mut vec = Vec::from(deque); + /// + /// // Modify it, being careful not to trigger reallocation. + /// vec.pop(); + /// vec.push(100); + /// + /// // Turn it back into a `VecDeque` with no allocation needed. + /// let ptr = vec.as_ptr(); + /// let deque = VecDeque::from(vec); + /// assert_eq!(deque, [1, 2, 3, 100]); + /// assert_eq!(deque.as_slices().0.as_ptr(), ptr); + /// ``` fn from(mut other: Vec) -> Self { unsafe { let other_buf = other.as_mut_ptr(); @@ -2760,34 +2760,34 @@ impl From> for VecDeque { } } -/// Turn a `VecDeque` into a `Vec`. -/// -/// This never needs to re-allocate, but does need to do O(n) data movement if -/// the circular buffer doesn't happen to be at the beginning of the allocation. -/// -/// # Examples -/// -/// ``` -/// use std::collections::VecDeque; -/// -/// // This one is O(1). -/// let deque: VecDeque<_> = (1..5).collect(); -/// let ptr = deque.as_slices().0.as_ptr(); -/// let vec = Vec::from(deque); -/// assert_eq!(vec, [1, 2, 3, 4]); -/// assert_eq!(vec.as_ptr(), ptr); -/// -/// // This one needs data rearranging. -/// let mut deque: VecDeque<_> = (1..5).collect(); -/// deque.push_front(9); -/// deque.push_front(8); -/// let ptr = deque.as_slices().1.as_ptr(); -/// let vec = Vec::from(deque); -/// assert_eq!(vec, [8, 9, 1, 2, 3, 4]); -/// assert_eq!(vec.as_ptr(), ptr); -/// ``` #[stable(feature = "vecdeque_vec_conversions", since = "1.10.0")] impl From> for Vec { + /// Turn a `VecDeque` into a `Vec`. + /// + /// This never needs to re-allocate, but does need to do O(n) data movement if + /// the circular buffer doesn't happen to be at the beginning of the allocation. + /// + /// # Examples + /// + /// ``` + /// use std::collections::VecDeque; + /// + /// // This one is O(1). + /// let deque: VecDeque<_> = (1..5).collect(); + /// let ptr = deque.as_slices().0.as_ptr(); + /// let vec = Vec::from(deque); + /// assert_eq!(vec, [1, 2, 3, 4]); + /// assert_eq!(vec.as_ptr(), ptr); + /// + /// // This one needs data rearranging. + /// let mut deque: VecDeque<_> = (1..5).collect(); + /// deque.push_front(9); + /// deque.push_front(8); + /// let ptr = deque.as_slices().1.as_ptr(); + /// let vec = Vec::from(deque); + /// assert_eq!(vec, [8, 9, 1, 2, 3, 4]); + /// assert_eq!(vec.as_ptr(), ptr); + /// ``` fn from(other: VecDeque) -> Self { unsafe { let buf = other.buf.ptr(); From 8da94ef84921213aa42d9da8b48251503e5ad7be Mon Sep 17 00:00:00 2001 From: scottmcm Date: Sun, 2 Jun 2019 12:14:56 -0700 Subject: [PATCH 4/6] Apply suggestions from code review Co-Authored-By: Joe ST --- src/liballoc/collections/vec_deque.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/liballoc/collections/vec_deque.rs b/src/liballoc/collections/vec_deque.rs index 79a36d7248df4..329c1437f29f1 100644 --- a/src/liballoc/collections/vec_deque.rs +++ b/src/liballoc/collections/vec_deque.rs @@ -2713,7 +2713,7 @@ impl From> for VecDeque { /// /// This avoids reallocating where possible, but the conditions for that are /// strict, and subject to change, and so shouldn't be relied upon unless the - /// `Vec` came from `From>` has hasn't been reallocated. + /// `Vec` came from `From>` and hasn't been reallocated. /// /// # Examples /// From 5168f5d220d0b30d322f254f51142931a9054056 Mon Sep 17 00:00:00 2001 From: Scott McMurray Date: Fri, 7 Jun 2019 21:37:52 -0700 Subject: [PATCH 5/6] Add hyperlinks to Vec and VecDeque Let's try the auto-linking instead, since the relative ones don't work. --- src/liballoc/collections/vec_deque.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/liballoc/collections/vec_deque.rs b/src/liballoc/collections/vec_deque.rs index 329c1437f29f1..f01b315552500 100644 --- a/src/liballoc/collections/vec_deque.rs +++ b/src/liballoc/collections/vec_deque.rs @@ -2709,7 +2709,7 @@ impl fmt::Debug for VecDeque { #[stable(feature = "vecdeque_vec_conversions", since = "1.10.0")] impl From> for VecDeque { - /// Turn a `Vec` into a `VecDeque`. + /// Turn a [`Vec`] into a [`VecDeque`]. /// /// This avoids reallocating where possible, but the conditions for that are /// strict, and subject to change, and so shouldn't be relied upon unless the @@ -2762,7 +2762,7 @@ impl From> for VecDeque { #[stable(feature = "vecdeque_vec_conversions", since = "1.10.0")] impl From> for Vec { - /// Turn a `VecDeque` into a `Vec`. + /// Turn a [`VecDeque`] into a [`Vec`]. /// /// This never needs to re-allocate, but does need to do O(n) data movement if /// the circular buffer doesn't happen to be at the beginning of the allocation. From 0150448f1b5474bb0c5fe3297eed0c51dae44dc8 Mon Sep 17 00:00:00 2001 From: Scott McMurray Date: Tue, 11 Jun 2019 21:13:48 -0700 Subject: [PATCH 6/6] Remove the questionably-useful example --- src/liballoc/collections/vec_deque.rs | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/src/liballoc/collections/vec_deque.rs b/src/liballoc/collections/vec_deque.rs index f01b315552500..71faf672962b3 100644 --- a/src/liballoc/collections/vec_deque.rs +++ b/src/liballoc/collections/vec_deque.rs @@ -2714,28 +2714,6 @@ impl From> for VecDeque { /// This avoids reallocating where possible, but the conditions for that are /// strict, and subject to change, and so shouldn't be relied upon unless the /// `Vec` came from `From>` and hasn't been reallocated. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// // Start with a `VecDeque`. - /// let deque: VecDeque<_> = (1..5).collect(); - /// - /// // Turn it into a `Vec` with no allocation needed. - /// let mut vec = Vec::from(deque); - /// - /// // Modify it, being careful not to trigger reallocation. - /// vec.pop(); - /// vec.push(100); - /// - /// // Turn it back into a `VecDeque` with no allocation needed. - /// let ptr = vec.as_ptr(); - /// let deque = VecDeque::from(vec); - /// assert_eq!(deque, [1, 2, 3, 100]); - /// assert_eq!(deque.as_slices().0.as_ptr(), ptr); - /// ``` fn from(mut other: Vec) -> Self { unsafe { let other_buf = other.as_mut_ptr();