From 087b9283a0ed8df68f47ab07a25e60bc6a3ca050 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Fri, 29 Aug 2014 13:20:58 -0700 Subject: [PATCH] collections: Stabilize Vec The following methods, types, and names have become stable: * Vec * Vec::as_mut_slice * Vec::as_slice * Vec::capacity * Vec::clear * Vec::default * Vec::grow * Vec::insert * Vec::len * Vec::new * Vec::pop * Vec::push * Vec::remove * Vec::set_len * Vec::shrink_to_fit * Vec::truncate * Vec::with_capacity The following have become unstable: * Vec::dedup // naming * Vec::from_fn // naming and unboxed closures * Vec::get_mut // will be removed for IndexMut * Vec::grow_fn // unboxed closures and naming * Vec::retain // unboxed closures * Vec::swap_remove // uncertain naming * Vec::from_elem // uncertain semantics * vec::unzip // should be generic for all collections The following have been deprecated * Vec::append - call .extend() * Vec::append_one - call .push() * Vec::from_slice - call .to_vec() * Vec::grow_set - call .grow() and then .push() * Vec::into_vec - move the vector instead * Vec::move_iter - renamed to iter_move() * Vec::to_vec - call .clone() The following methods remain experimental pending conventions * vec::raw * vec::raw::from_buf * Vec:from_raw_parts * Vec::push_all This is a breaking change in terms of the signature of the `Vec::grow` function. The argument used to be taken by reference, but it is now taken by value. Code must update by removing a leading `&` sigil or by calling `.clone()` to create a value. [breaking-change] --- src/libcollections/vec.rs | 61 +++++++++++++++++++++++++++++++++++---- 1 file changed, 56 insertions(+), 5 deletions(-) diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index 4051f682134..dc43dd5e53d 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -99,6 +99,7 @@ use slice::{Items, MutItems}; /// to use `Vec::with_capacity` whenever possible to specify how big the vector /// is expected to get. #[unsafe_no_drop_flag] +#[stable] pub struct Vec { len: uint, cap: uint, @@ -116,6 +117,7 @@ impl Vec { /// let mut vec: Vec = Vec::new(); /// ``` #[inline] + #[stable] pub fn new() -> Vec { // We want ptr to never be NULL so instead we set it to some arbitrary // non-null value which is fine since we never call deallocate on the ptr @@ -152,6 +154,7 @@ impl Vec { /// vec.push(11); /// ``` #[inline] + #[stable] pub fn with_capacity(capacity: uint) -> Vec { if mem::size_of::() == 0 { Vec { len: 0, cap: uint::MAX, ptr: EMPTY as *mut T } @@ -177,6 +180,8 @@ impl Vec { /// assert_eq!(vec, vec![0, 2, 4]); /// ``` #[inline] + #[unstable = "the naming is uncertain as well as this migrating to unboxed \ + closures in the future"] pub fn from_fn(length: uint, op: |uint| -> T) -> Vec { unsafe { let mut xs = Vec::with_capacity(length); @@ -229,6 +234,7 @@ impl Vec { /// } /// } /// ``` + #[experimental] pub unsafe fn from_raw_parts(length: uint, capacity: uint, ptr: *mut T) -> Vec { Vec { len: length, cap: capacity, ptr: ptr } @@ -249,6 +255,7 @@ impl Vec { /// assert_eq!(odd, vec![1, 3]); /// ``` #[inline] + #[experimental] pub fn partition(self, f: |&T| -> bool) -> (Vec, Vec) { let mut lefts = Vec::new(); let mut rights = Vec::new(); @@ -277,6 +284,7 @@ impl Vec { /// assert_eq!(vec, vec![1, 2, 3, 4]); /// ``` #[inline] + #[deprecated = "this function has been deprecated in favor of extend()"] pub fn append(mut self, second: &[T]) -> Vec { self.push_all(second); self @@ -291,6 +299,7 @@ impl Vec { /// let vec = Vec::from_slice(slice); /// ``` #[inline] + #[deprecated = "this function has been deprecated in favor of to_vec()"] pub fn from_slice(values: &[T]) -> Vec { let mut vector = Vec::new(); vector.push_all(values); @@ -307,6 +316,7 @@ impl Vec { /// println!("{}", vec); // prints [hi, hi, hi] /// ``` #[inline] + #[unstable = "this functionality may become more generic over all collections"] pub fn from_elem(length: uint, value: T) -> Vec { unsafe { let mut xs = Vec::with_capacity(length); @@ -333,6 +343,7 @@ impl Vec { /// assert_eq!(vec, vec![1, 2, 3, 4]); /// ``` #[inline] + #[experimental] pub fn push_all(&mut self, other: &[T]) { self.reserve_additional(other.len()); @@ -359,15 +370,16 @@ impl Vec { /// /// ``` /// let mut vec = vec!["hello"]; - /// vec.grow(2, &("world")); + /// vec.grow(2, "world"); /// assert_eq!(vec, vec!["hello", "world", "world"]); /// ``` - pub fn grow(&mut self, n: uint, value: &T) { + #[stable] + pub fn grow(&mut self, n: uint, value: T) { self.reserve_additional(n); let mut i: uint = 0u; while i < n { - self.push((*value).clone()); + self.push(value.clone()); i += 1u; } } @@ -382,15 +394,17 @@ impl Vec { /// # Example /// /// ``` + /// # #![allow(deprecated)] /// let mut vec = vec!["a", "b", "c"]; /// vec.grow_set(1, &("fill"), "d"); /// vec.grow_set(4, &("fill"), "e"); /// assert_eq!(vec, vec!["a", "d", "c", "fill", "e"]); /// ``` + #[deprecated = "call .grow() and .push() manually instead"] pub fn grow_set(&mut self, index: uint, initval: &T, value: T) { let l = self.len(); if index >= l { - self.grow(index - l + 1u, initval); + self.grow(index - l + 1u, initval.clone()); } *self.get_mut(index) = value; } @@ -409,6 +423,7 @@ impl Vec { /// assert_eq!(even, vec![2i, 4]); /// assert_eq!(odd, vec![1i, 3]); /// ``` + #[experimental] pub fn partitioned(&self, f: |&T| -> bool) -> (Vec, Vec) { let mut lefts = Vec::new(); let mut rights = Vec::new(); @@ -449,6 +464,7 @@ impl Clone for Vec { } } +#[experimental = "waiting on Index stability"] impl Index for Vec { #[inline] #[allow(deprecated)] // allow use of get @@ -506,6 +522,8 @@ impl ops::SliceMut for Vec { self.as_mut_slice().slice_mut_(start, end) } } + +#[experimental = "waiting on FromIterator stability"] impl FromIterator for Vec { #[inline] fn from_iter>(mut iterator: I) -> Vec { @@ -518,6 +536,7 @@ impl FromIterator for Vec { } } +#[experimental = "waiting on Extendable stability"] impl Extendable for Vec { #[inline] fn extend>(&mut self, mut iterator: I) { @@ -529,6 +548,7 @@ impl Extendable for Vec { } } +#[unstable = "waiting on PartialEq stability"] impl PartialEq for Vec { #[inline] fn eq(&self, other: &Vec) -> bool { @@ -536,6 +556,7 @@ impl PartialEq for Vec { } } +#[unstable = "waiting on PartialOrd stability"] impl PartialOrd for Vec { #[inline] fn partial_cmp(&self, other: &Vec) -> Option { @@ -543,13 +564,16 @@ impl PartialOrd for Vec { } } +#[unstable = "waiting on Eq stability"] impl Eq for Vec {} +#[experimental] impl> Equiv for Vec { #[inline] fn equiv(&self, other: &V) -> bool { self.as_slice() == other.as_slice() } } +#[unstable = "waiting on Ord stability"] impl Ord for Vec { #[inline] fn cmp(&self, other: &Vec) -> Ordering { @@ -557,15 +581,19 @@ impl Ord for Vec { } } +#[experimental = "waiting on Collection stability"] impl Collection for Vec { #[inline] + #[stable] fn len(&self) -> uint { self.len } } impl CloneableVector for Vec { + #[deprecated = "call .clone() instead"] fn to_vec(&self) -> Vec { self.clone() } + #[deprecated = "move the vector instead"] fn into_vec(self) -> Vec { self } } @@ -600,6 +628,7 @@ impl Vec { /// assert_eq!(vec.capacity(), 10); /// ``` #[inline] + #[stable] pub fn capacity(&self) -> uint { self.cap } @@ -683,6 +712,7 @@ impl Vec { /// let mut vec = vec![1i, 2, 3]; /// vec.shrink_to_fit(); /// ``` + #[stable] pub fn shrink_to_fit(&mut self) { if mem::size_of::() == 0 { return } @@ -717,6 +747,7 @@ impl Vec { /// assert_eq!(vec, vec![1, 2, 3]); /// ``` #[inline] + #[deprecated = "call .push() instead"] pub fn append_one(mut self, x: T) -> Vec { self.push(x); self @@ -734,6 +765,7 @@ impl Vec { /// vec.truncate(2); /// assert_eq!(vec, vec![1, 2]); /// ``` + #[stable] pub fn truncate(&mut self, len: uint) { unsafe { // drop any extra elements @@ -757,6 +789,7 @@ impl Vec { /// foo(vec.as_mut_slice()); /// ``` #[inline] + #[stable] pub fn as_mut_slice<'a>(&'a mut self) -> &'a mut [T] { unsafe { mem::transmute(RawSlice { @@ -796,7 +829,6 @@ impl Vec { } } - /// Sets the length of a vector. /// /// This will explicitly set the size of the vector, without actually @@ -812,6 +844,7 @@ impl Vec { /// } /// ``` #[inline] + #[stable] pub unsafe fn set_len(&mut self, len: uint) { self.len = len; } @@ -850,6 +883,7 @@ impl Vec { /// assert_eq!(vec, vec![1i, 4, 3]); /// ``` #[inline] + #[unstable = "this is likely to be moved to actual indexing"] pub fn get_mut<'a>(&'a mut self, index: uint) -> &'a mut T { &mut self.as_mut_slice()[index] } @@ -1020,6 +1054,7 @@ impl Vec { /// assert_eq!(v.swap_remove(2), None); /// ``` #[inline] + #[unstable = "the naming of this function may be altered"] pub fn swap_remove(&mut self, index: uint) -> Option { let length = self.len(); if length > 0 && index < length - 1 { @@ -1088,6 +1123,7 @@ impl Vec { /// vec.insert(4, 5); /// assert_eq!(vec, vec![1, 4, 2, 3, 5]); /// ``` + #[stable] pub fn insert(&mut self, index: uint, element: T) { let len = self.len(); assert!(index <= len); @@ -1124,6 +1160,7 @@ impl Vec { /// // v is unchanged: /// assert_eq!(v, vec![1, 3]); /// ``` + #[stable] pub fn remove(&mut self, index: uint) -> Option { let len = self.len(); if index < len { @@ -1410,6 +1447,7 @@ impl Vec { /// vec.retain(|x| x%2 == 0); /// assert_eq!(vec, vec![2, 4]); /// ``` + #[unstable = "the closure argument may become an unboxed closure"] pub fn retain(&mut self, f: |&T| -> bool) { let len = self.len(); let mut del = 0u; @@ -1441,6 +1479,7 @@ impl Vec { /// vec.grow_fn(3, |i| i); /// assert_eq!(vec, vec![0, 1, 0, 1, 2]); /// ``` + #[unstable = "this function may be renamed or change to unboxed closures"] pub fn grow_fn(&mut self, n: uint, f: |uint| -> T) { self.reserve_additional(n); for i in range(0u, n) { @@ -1467,8 +1506,10 @@ impl Vec { } } +#[experimental = "waiting on Mutable stability"] impl Mutable for Vec { #[inline] + #[stable] fn clear(&mut self) { self.truncate(0) } @@ -1499,6 +1540,7 @@ impl Vec { /// vec.dedup(); /// assert_eq!(vec, vec![1i, 2, 3, 2]); /// ``` + #[unstable = "this function may be renamed"] pub fn dedup(&mut self) { unsafe { // Although we have a mutable reference to `self`, we cannot make @@ -1596,6 +1638,7 @@ impl Slice for Vec { /// foo(vec.as_slice()); /// ``` #[inline] + #[stable] fn as_slice<'a>(&'a self) -> &'a [T] { unsafe { mem::transmute(RawSlice { data: self.as_ptr(), len: self.len }) } } @@ -1627,18 +1670,21 @@ impl Drop for Vec { } } +#[stable] impl Default for Vec { fn default() -> Vec { Vec::new() } } +#[experimental = "waiting on Show stability"] impl fmt::Show for Vec { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { self.as_slice().fmt(f) } } +#[experimental = "waiting on MutableSeq stability"] impl MutableSeq for Vec { /// Appends an element to the back of a collection. /// @@ -1654,6 +1700,7 @@ impl MutableSeq for Vec { /// assert_eq!(vec, vec!(1, 2, 3)); /// ``` #[inline] + #[stable] fn push(&mut self, value: T) { if mem::size_of::() == 0 { // zero-size types consume no memory, so we can't rely on the address space running out @@ -1680,6 +1727,7 @@ impl MutableSeq for Vec { } #[inline] + #[stable] fn pop(&mut self) -> Option { if self.len == 0 { None @@ -1765,6 +1813,7 @@ impl Drop for MoveItems { /// vector contains the first element of the i-th tuple of the input iterator, /// and the i-th element of the second vector contains the second element /// of the i-th tuple of the input iterator. +#[unstable = "this functionality may become more generic over time"] pub fn unzip>(mut iter: V) -> (Vec, Vec) { let (lo, _) = iter.size_hint(); let mut ts = Vec::with_capacity(lo); @@ -1777,6 +1826,7 @@ pub fn unzip>(mut iter: V) -> (Vec, Vec) { } /// Unsafe vector operations. +#[unstable] pub mod raw { use super::Vec; use core::ptr; @@ -1786,6 +1836,7 @@ pub mod raw { /// The elements of the buffer are copied into the vector without cloning, /// as if `ptr::read()` were called on them. #[inline] + #[unstable] pub unsafe fn from_buf(ptr: *const T, elts: uint) -> Vec { let mut dst = Vec::with_capacity(elts); dst.set_len(elts);