Implement low-hanging fruit of collection conventions

src/libcollections/binary_heap.rs

@@ -162,6 +162,8 @@ use core::ptr;
 use slice;
 use vec::Vec;
 
+// FIXME(conventions): implement into_iter
+
 /// A priority queue implemented with a binary heap.
 ///
 /// This will be a max-heap.
@@ -184,6 +186,7 @@ impl<T: Ord> BinaryHeap<T> {
     /// use std::collections::BinaryHeap;
     /// let pq: BinaryHeap<uint> = BinaryHeap::new();
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn new() -> BinaryHeap<T> { BinaryHeap{data: vec!(),} }
 
     /// Creates an empty `BinaryHeap` with a specific capacity.
@@ -197,6 +200,7 @@ impl<T: Ord> BinaryHeap<T> {
     /// use std::collections::BinaryHeap;
     /// let pq: BinaryHeap<uint> = BinaryHeap::with_capacity(10u);
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn with_capacity(capacity: uint) -> BinaryHeap<T> {
         BinaryHeap { data: Vec::with_capacity(capacity) }
     }
@@ -234,6 +238,7 @@ impl<T: Ord> BinaryHeap<T> {
     ///     println!("{}", x);
     /// }
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn iter<'a>(&'a self) -> Items<'a, T> {
         Items { iter: self.data.iter() }
     }
@@ -268,10 +273,19 @@ impl<T: Ord> BinaryHeap<T> {
     /// let pq: BinaryHeap<uint> = BinaryHeap::with_capacity(100u);
     /// assert!(pq.capacity() >= 100u);
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn capacity(&self) -> uint { self.data.capacity() }
 
-    /// Reserves capacity for exactly `n` elements in the `BinaryHeap`.
-    /// Do nothing if the capacity is already sufficient.
+    /// Reserves the minimum capacity for exactly `additional` more elements to be inserted in the
+    /// given `BinaryHeap`. Does nothing if the capacity is already sufficient.
+    ///
+    /// Note that the allocator may give the collection more space than it requests. Therefore
+    /// capacity can not be relied upon to be precisely minimal. Prefer `reserve` if future
+    /// insertions are expected.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the new capacity overflows `uint`.
     ///
     /// # Example
     ///
@@ -280,12 +294,17 @@ impl<T: Ord> BinaryHeap<T> {
     ///
     /// let mut pq: BinaryHeap<uint> = BinaryHeap::new();
     /// pq.reserve_exact(100u);
-    /// assert!(pq.capacity() == 100u);
+    /// assert!(pq.capacity() >= 100u);
     /// ```
-    pub fn reserve_exact(&mut self, n: uint) { self.data.reserve_exact(n) }
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn reserve_exact(&mut self, additional: uint) { self.data.reserve_exact(additional) }
 
-    /// Reserves capacity for at least `n` elements in the `BinaryHeap`.
-    /// Do nothing if the capacity is already sufficient.
+    /// Reserves capacity for at least `additional` more elements to be inserted in the
+    /// `BinaryHeap`. The collection may reserve more space to avoid frequent reallocations.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the new capacity overflows `uint`.
     ///
     /// # Example
     ///
@@ -296,8 +315,15 @@ impl<T: Ord> BinaryHeap<T> {
     /// pq.reserve(100u);
     /// assert!(pq.capacity() >= 100u);
     /// ```
-    pub fn reserve(&mut self, n: uint) {
-        self.data.reserve(n)
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn reserve(&mut self, additional: uint) {
+        self.data.reserve(additional)
+    }
+
+    /// Discards as much additional capacity as possible.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn shrink_to_fit(&mut self) {
+        self.data.shrink_to_fit()
     }
 
     /// Removes the greatest item from a queue and returns it, or `None` if it
@@ -314,6 +340,7 @@ impl<T: Ord> BinaryHeap<T> {
     /// assert_eq!(pq.pop(), Some(1i));
     /// assert_eq!(pq.pop(), None);
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn pop(&mut self) -> Option<T> {
         match self.data.pop() {
             None           => { None }
@@ -342,6 +369,7 @@ impl<T: Ord> BinaryHeap<T> {
     /// assert_eq!(pq.len(), 3);
     /// assert_eq!(pq.top(), Some(&5i));
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn push(&mut self, item: T) {
         self.data.push(item);
         let new_len = self.len() - 1;
@@ -495,12 +523,15 @@ impl<T: Ord> BinaryHeap<T> {
     }
 
     /// Returns the length of the queue.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn len(&self) -> uint { self.data.len() }
 
     /// Returns true if the queue contains no elements
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_empty(&self) -> bool { self.len() == 0 }
 
     /// Drops all items from the queue.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn clear(&mut self) { self.data.truncate(0) }
 }
 
@@ -528,8 +559,7 @@ impl<T: Ord> Extendable<T> for BinaryHeap<T> {
     fn extend<Iter: Iterator<T>>(&mut self, mut iter: Iter) {
         let (lower, _) = iter.size_hint();
 
-        let len = self.capacity();
-        self.reserve(len + lower);
+        self.reserve(lower);
 
         for elem in iter {
             self.push(elem);

src/libcollections/bit.rs

@@ -75,6 +75,8 @@ use std::hash;
 
 use vec::Vec;
 
+// FIXME(conventions): look, we just need to refactor this whole thing. Inside and out.
+
 type MatchWords<'a> = Chain<MaskWords<'a>, Skip<Take<Enumerate<Repeat<u32>>>>>;
 // Take two BitV's, and return iterators of their words, where the shorter one
 // has been padded with 0's
@@ -216,6 +218,7 @@ impl Bitv {
     /// use std::collections::Bitv;
     /// let mut bv = Bitv::new();
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn new() -> Bitv {
         Bitv { storage: Vec::new(), nbits: 0 }
     }
@@ -613,6 +616,7 @@ impl Bitv {
     /// bv.truncate(2);
     /// assert!(bv.eq_vec([false, true]));
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn truncate(&mut self, len: uint) {
         if len < self.len() {
             self.nbits = len;
@@ -760,14 +764,17 @@ impl Bitv {
 
     /// Return the total number of bits in this vector
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn len(&self) -> uint { self.nbits }
 
     /// Returns true if there are no bits in this vector
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_empty(&self) -> bool { self.len() == 0 }
 
     /// Clears all bits in this vector.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn clear(&mut self) {
         for w in self.storage.iter_mut() { *w = 0u32; }
     }
@@ -849,8 +856,7 @@ impl Clone for Bitv {
     #[inline]
     fn clone_from(&mut self, source: &Bitv) {
         self.nbits = source.nbits;
-        self.storage.reserve(source.storage.len());
-        for (i, w) in self.storage.iter_mut().enumerate() { *w = source.storage[i]; }
+        self.storage.clone_from(&source.storage);
     }
 }
 
@@ -1052,6 +1058,7 @@ impl BitvSet {
     /// let mut s = BitvSet::new();
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn new() -> BitvSet {
         BitvSet(Bitv::new())
     }
@@ -1067,6 +1074,7 @@ impl BitvSet {
     /// assert!(s.capacity() >= 100);
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn with_capacity(nbits: uint) -> BitvSet {
         let bitv = Bitv::with_capacity(nbits, false);
         BitvSet::from_bitv(bitv)
@@ -1106,6 +1114,7 @@ impl BitvSet {
     /// assert!(s.capacity() >= 100);
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn capacity(&self) -> uint {
         let &BitvSet(ref bitv) = self;
         bitv.capacity()
@@ -1212,6 +1221,7 @@ impl BitvSet {
     /// println!("new capacity: {}", s.capacity());
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn shrink_to_fit(&mut self) {
         let &BitvSet(ref mut bitv) = self;
         // Obtain original length
@@ -1240,6 +1250,7 @@ impl BitvSet {
     /// }
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn iter<'a>(&'a self) -> BitPositions<'a> {
         BitPositions {set: self, next_idx: 0u}
     }
@@ -1262,6 +1273,7 @@ impl BitvSet {
     /// }
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn union<'a>(&'a self, other: &'a BitvSet) -> TwoBitPositions<'a> {
         TwoBitPositions {
             set: self,
@@ -1290,6 +1302,7 @@ impl BitvSet {
     /// }
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn intersection<'a>(&'a self, other: &'a BitvSet) -> Take<TwoBitPositions<'a>> {
         let min = cmp::min(self.capacity(), other.capacity());
         TwoBitPositions {
@@ -1326,6 +1339,7 @@ impl BitvSet {
     /// }
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn difference<'a>(&'a self, other: &'a BitvSet) -> TwoBitPositions<'a> {
         TwoBitPositions {
             set: self,
@@ -1355,6 +1369,7 @@ impl BitvSet {
     /// }
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn symmetric_difference<'a>(&'a self, other: &'a BitvSet) -> TwoBitPositions<'a> {
         TwoBitPositions {
             set: self,
@@ -1473,27 +1488,31 @@ impl BitvSet {
 
     /// Return the number of set bits in this set.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn len(&self) -> uint  {
         let &BitvSet(ref bitv) = self;
         bitv.storage.iter().fold(0, |acc, &n| acc + n.count_ones())
     }
 
     /// Returns whether there are no bits set in this set
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_empty(&self) -> bool {
         let &BitvSet(ref bitv) = self;
         bitv.storage.iter().all(|&n| n == 0)
     }
 
     /// Clears all bits in this set
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn clear(&mut self) {
         let &BitvSet(ref mut bitv) = self;
         bitv.clear();
     }
 
     /// Returns `true` if this set contains the specified integer.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn contains(&self, value: &uint) -> bool {
         let &BitvSet(ref bitv) = self;
         *value < bitv.nbits && bitv.get(*value)
@@ -1502,12 +1521,14 @@ impl BitvSet {
     /// Returns `true` if the set has no elements in common with `other`.
     /// This is equivalent to checking for an empty intersection.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_disjoint(&self, other: &BitvSet) -> bool {
         self.intersection(other).next().is_none()
     }
 
     /// Returns `true` if the set is a subset of another.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_subset(&self, other: &BitvSet) -> bool {
         let &BitvSet(ref self_bitv) = self;
         let &BitvSet(ref other_bitv) = other;
@@ -1521,12 +1542,14 @@ impl BitvSet {
 
     /// Returns `true` if the set is a superset of another.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_superset(&self, other: &BitvSet) -> bool {
         other.is_subset(self)
     }
 
     /// Adds a value to the set. Returns `true` if the value was not already
     /// present in the set.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn insert(&mut self, value: uint) -> bool {
         if self.contains(&value) {
             return false;
@@ -1545,6 +1568,7 @@ impl BitvSet {
 
     /// Removes a value from the set. Returns `true` if the value was
     /// present in the set.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn remove(&mut self, value: &uint) -> bool {
         if !self.contains(value) {
             return false;