diff options
Diffstat (limited to 'src/libcollections/vec.rs')
| -rw-r--r-- | src/libcollections/vec.rs | 116 |
1 files changed, 107 insertions, 9 deletions
diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index 7a3c9bc3bb2..8b4fce158de 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -73,6 +73,7 @@ use core::mem; use core::ops::{Index, IndexMut}; use core::ops; use core::ptr; +use core::ptr::Shared; use core::slice; use super::SpecExtend; @@ -342,12 +343,18 @@ impl<T> Vec<T> { /// /// * `ptr` needs to have been previously allocated via `String`/`Vec<T>` /// (at least, it's highly likely to be incorrect if it wasn't). - /// * `length` needs to be the length that less than or equal to `capacity`. + /// * `length` needs to be less than or equal to `capacity`. /// * `capacity` needs to be the capacity that the pointer was allocated with. /// /// Violating these may cause problems like corrupting the allocator's /// internal datastructures. /// + /// The ownership of `ptr` is effectively transferred to the + /// `Vec<T>` which may then deallocate, reallocate or change the + /// contents of memory pointed to by the pointer at will. Ensure + /// that nothing else uses the pointer after calling this + /// function. + /// /// # Examples /// /// ``` @@ -469,6 +476,25 @@ impl<T> Vec<T> { /// Note that this will drop any excess capacity. Calling this and /// converting back to a vector with `into_vec()` is equivalent to calling /// `shrink_to_fit()`. + /// + /// # Examples + /// + /// ``` + /// let v = vec![1, 2, 3]; + /// + /// let slice = v.into_boxed_slice(); + /// ``` + /// + /// Any excess capacity is removed: + /// + /// ``` + /// let mut vec = Vec::with_capacity(10); + /// vec.extend([1, 2, 3].iter().cloned()); + /// + /// assert_eq!(vec.capacity(), 10); + /// let slice = vec.into_boxed_slice(); + /// assert_eq!(slice.into_vec().capacity(), 3); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn into_boxed_slice(mut self) -> Box<[T]> { unsafe { @@ -479,18 +505,45 @@ impl<T> Vec<T> { } } - /// Shorten a vector to be `len` elements long, dropping excess elements. + /// Shortens the vector, keeping the first `len` elements and dropping + /// the rest. /// /// If `len` is greater than the vector's current length, this has no /// effect. /// + /// The [`drain`] method can emulate `truncate`, but causes the excess + /// elements to be returned instead of dropped. + /// /// # Examples /// + /// Truncating a five element vector to two elements: + /// /// ``` /// let mut vec = vec![1, 2, 3, 4, 5]; /// vec.truncate(2); /// assert_eq!(vec, [1, 2]); /// ``` + /// + /// No truncation occurs when `len` is greater than the vector's current + /// length: + /// + /// ``` + /// let mut vec = vec![1, 2, 3]; + /// vec.truncate(8); + /// assert_eq!(vec, [1, 2, 3]); + /// ``` + /// + /// Truncating when `len == 0` is equivalent to calling the [`clear`] + /// method. + /// + /// ``` + /// let mut vec = vec![1, 2, 3]; + /// vec.truncate(0); + /// assert_eq!(vec, []); + /// ``` + /// + /// [`clear`]: #method.clear + /// [`drain`]: #method.drain #[stable(feature = "rust1", since = "1.0.0")] pub fn truncate(&mut self, len: usize) { unsafe { @@ -508,6 +561,14 @@ impl<T> Vec<T> { /// Extracts a slice containing the entire vector. /// /// Equivalent to `&s[..]`. + /// + /// # Examples + /// + /// ``` + /// use std::io::{self, Write}; + /// let buffer = vec![1, 2, 3, 5, 8]; + /// io::sink().write(buffer.as_slice()).unwrap(); + /// ``` #[inline] #[stable(feature = "vec_as_slice", since = "1.7.0")] pub fn as_slice(&self) -> &[T] { @@ -517,6 +578,14 @@ impl<T> Vec<T> { /// Extracts a mutable slice of the entire vector. /// /// Equivalent to `&mut s[..]`. + /// + /// # Examples + /// + /// ``` + /// use std::io::{self, Read}; + /// let mut buffer = vec![0; 3]; + /// io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap(); + /// ``` #[inline] #[stable(feature = "vec_as_slice", since = "1.7.0")] pub fn as_mut_slice(&mut self) -> &mut [T] { @@ -532,9 +601,38 @@ impl<T> Vec<T> { /// # Examples /// /// ``` - /// let mut v = vec![1, 2, 3, 4]; + /// use std::ptr; + /// + /// let mut vec = vec!['r', 'u', 's', 't']; + /// + /// unsafe { + /// ptr::drop_in_place(&mut vec[3]); + /// vec.set_len(3); + /// } + /// assert_eq!(vec, ['r', 'u', 's']); + /// ``` + /// + /// In this example, there is a memory leak since the memory locations + /// owned by the inner vectors were not freed prior to the `set_len` call: + /// + /// ``` + /// let mut vec = vec![vec![1, 0, 0], + /// vec![0, 1, 0], + /// vec![0, 0, 1]]; + /// unsafe { + /// vec.set_len(0); + /// } + /// ``` + /// + /// In this example, the vector gets expanded from zero to four items + /// without any memory allocations occurring, resulting in vector + /// values of unallocated memory: + /// + /// ``` + /// let mut vec: Vec<char> = Vec::new(); + /// /// unsafe { - /// v.set_len(1); + /// vec.set_len(4); /// } /// ``` #[inline] @@ -821,8 +919,8 @@ impl<T> Vec<T> { Drain { tail_start: end, tail_len: len - end, - iter: range_slice.iter_mut(), - vec: self as *mut _, + iter: range_slice.iter(), + vec: Shared::new(self as *mut _), } } } @@ -1728,8 +1826,8 @@ pub struct Drain<'a, T: 'a> { /// Length of tail tail_len: usize, /// Current remaining range to remove - iter: slice::IterMut<'a, T>, - vec: *mut Vec<T>, + iter: slice::Iter<'a, T>, + vec: Shared<Vec<T>>, } #[stable(feature = "drain", since = "1.6.0")] @@ -1767,7 +1865,7 @@ impl<'a, T> Drop for Drain<'a, T> { if self.tail_len > 0 { unsafe { - let source_vec = &mut *self.vec; + let source_vec = &mut **self.vec; // memmove back untouched tail, update to new length let start = source_vec.len(); let tail = self.tail_start; |