@@ -162,6 +162,8 @@ use core::ptr;
162162use slice;
163163use vec:: Vec ;
164164
165+ // FIXME(conventions): implement into_iter
166+
165167/// A priority queue implemented with a binary heap.
166168///
167169/// This will be a max-heap.
@@ -184,6 +186,7 @@ impl<T: Ord> BinaryHeap<T> {
184186/// use std::collections::BinaryHeap;
185187/// let pq: BinaryHeap<uint> = BinaryHeap::new();
186188/// ```
189+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
187190 pub fn new ( ) -> BinaryHeap < T > { BinaryHeap { data : vec ! ( ) , } }
188191
189192 /// Creates an empty `BinaryHeap` with a specific capacity.
@@ -197,6 +200,7 @@ impl<T: Ord> BinaryHeap<T> {
197200/// use std::collections::BinaryHeap;
198201/// let pq: BinaryHeap<uint> = BinaryHeap::with_capacity(10u);
199202/// ```
203+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
200204 pub fn with_capacity ( capacity : uint ) -> BinaryHeap < T > {
201205 BinaryHeap { data : Vec :: with_capacity ( capacity) }
202206 }
@@ -234,6 +238,7 @@ impl<T: Ord> BinaryHeap<T> {
234238/// println!("{}", x);
235239/// }
236240/// ```
241+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
237242 pub fn iter < ' a > ( & ' a self ) -> Items < ' a , T > {
238243 Items { iter : self . data . iter ( ) }
239244 }
@@ -268,10 +273,19 @@ impl<T: Ord> BinaryHeap<T> {
268273/// let pq: BinaryHeap<uint> = BinaryHeap::with_capacity(100u);
269274/// assert!(pq.capacity() >= 100u);
270275/// ```
276+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
271277 pub fn capacity ( & self ) -> uint { self . data . capacity ( ) }
272278
273- /// Reserves capacity for exactly `n` elements in the `BinaryHeap`.
274- /// Do nothing if the capacity is already sufficient.
279+ /// Reserves the minimum capacity for exactly `additional` more elements to be inserted in the
280+ /// given `BinaryHeap`. Does nothing if the capacity is already sufficient.
281+ ///
282+ /// Note that the allocator may give the collection more space than it requests. Therefore
283+ /// capacity can not be relied upon to be precisely minimal. Prefer `reserve` if future
284+ /// insertions are expected.
285+ ///
286+ /// # Panics
287+ ///
288+ /// Panics if the new capacity overflows `uint`.
275289///
276290/// # Example
277291///
@@ -280,12 +294,17 @@ impl<T: Ord> BinaryHeap<T> {
280294///
281295/// let mut pq: BinaryHeap<uint> = BinaryHeap::new();
282296/// pq.reserve_exact(100u);
283- /// assert!(pq.capacity() = = 100u);
297+ /// assert!(pq.capacity() > = 100u);
284298/// ```
285- pub fn reserve_exact ( & mut self , n : uint ) { self . data . reserve_exact ( n) }
299+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
300+ pub fn reserve_exact ( & mut self , additional : uint ) { self . data . reserve_exact ( additional) }
286301
287- /// Reserves capacity for at least `n` elements in the `BinaryHeap`.
288- /// Do nothing if the capacity is already sufficient.
302+ /// Reserves capacity for at least `additional` more elements to be inserted in the
303+ /// `BinaryHeap`. The collection may reserve more space to avoid frequent reallocations.
304+ ///
305+ /// # Panics
306+ ///
307+ /// Panics if the new capacity overflows `uint`.
289308///
290309/// # Example
291310///
@@ -296,8 +315,15 @@ impl<T: Ord> BinaryHeap<T> {
296315/// pq.reserve(100u);
297316/// assert!(pq.capacity() >= 100u);
298317/// ```
299- pub fn reserve ( & mut self , n : uint ) {
300- self . data . reserve ( n)
318+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
319+ pub fn reserve ( & mut self , additional : uint ) {
320+ self . data . reserve ( additional)
321+ }
322+
323+ /// Discards as much additional capacity as possible.
324+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
325+ pub fn shrink_to_fit ( & mut self ) {
326+ self . data . shrink_to_fit ( )
301327 }
302328
303329 /// Removes the greatest item from a queue and returns it, or `None` if it
@@ -314,6 +340,7 @@ impl<T: Ord> BinaryHeap<T> {
314340/// assert_eq!(pq.pop(), Some(1i));
315341/// assert_eq!(pq.pop(), None);
316342/// ```
343+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
317344 pub fn pop ( & mut self ) -> Option < T > {
318345 match self . data . pop ( ) {
319346 None => { None }
@@ -342,6 +369,7 @@ impl<T: Ord> BinaryHeap<T> {
342369/// assert_eq!(pq.len(), 3);
343370/// assert_eq!(pq.top(), Some(&5i));
344371/// ```
372+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
345373 pub fn push ( & mut self , item : T ) {
346374 self . data . push ( item) ;
347375 let new_len = self . len ( ) - 1 ;
@@ -495,12 +523,15 @@ impl<T: Ord> BinaryHeap<T> {
495523 }
496524
497525 /// Returns the length of the queue.
526+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
498527 pub fn len ( & self ) -> uint { self . data . len ( ) }
499528
500529 /// Returns true if the queue contains no elements
530+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
501531 pub fn is_empty ( & self ) -> bool { self . len ( ) == 0 }
502532
503533 /// Drops all items from the queue.
534+ #[ unstable = "matches collection reform specification, waiting for dust to settle" ]
504535 pub fn clear ( & mut self ) { self . data . truncate ( 0 ) }
505536}
506537
@@ -528,8 +559,7 @@ impl<T: Ord> Extendable<T> for BinaryHeap<T> {
528559 fn extend < Iter : Iterator < T > > ( & mut self , mut iter : Iter ) {
529560 let ( lower, _) = iter. size_hint ( ) ;
530561
531- let len = self . capacity ( ) ;
532- self . reserve ( len + lower) ;
562+ self . reserve ( lower) ;
533563
534564 for elem in iter {
535565 self . push ( elem) ;
0 commit comments