@@ -167,6 +167,49 @@ use vec::{self, Vec};
167167/// item's ordering relative to any other item, as determined by the `Ord`
168168/// trait, changes while it is in the heap. This is normally only possible
169169/// through `Cell`, `RefCell`, global state, I/O, or unsafe code.
170+ ///
171+ /// # Examples
172+ ///
173+ /// ```
174+ /// use std::collections::BinaryHeap;
175+ ///
176+ /// // type inference lets us omit an explicit type signature (which
177+ /// // would be `BinaryHeap<i32>` in this example).
178+ /// let mut heap = BinaryHeap::new();
179+ ///
180+ /// // We can use peek to look at the next item in the heap. In this case,
181+ /// // there's no items in there yet so we get None.
182+ /// assert_eq!(heap.peek(), None);
183+ ///
184+ /// // Let's add some scores...
185+ /// heap.push(1);
186+ /// heap.push(5);
187+ /// heap.push(2);
188+ ///
189+ /// // Now peek shows the most important item in the heap.
190+ /// assert_eq!(heap.peek(), Some(&5));
191+ ///
192+ /// // We can check the length of a heap.
193+ /// assert_eq!(heap.len(), 3);
194+ ///
195+ /// // We can iterate over the items in the heap, although they are returned in
196+ /// // a random order.
197+ /// for x in heap.iter() {
198+ /// println!("{}", x);
199+ /// }
200+ ///
201+ /// // If we instead pop these scores, they should come back in order.
202+ /// assert_eq!(heap.pop(), Some(5));
203+ /// assert_eq!(heap.pop(), Some(2));
204+ /// assert_eq!(heap.pop(), Some(1));
205+ /// assert_eq!(heap.pop(), None);
206+ ///
207+ /// // We can clear the heap of any remaining items.
208+ /// heap.clear();
209+ ///
210+ /// // The heap should now be empty.
211+ /// assert!(heap.is_empty())
212+ /// ```
170213#[ stable( feature = "rust1" , since = "1.0.0" ) ]
171214pub struct BinaryHeap < T > {
172215 data : Vec < T > ,
@@ -203,6 +246,8 @@ impl<T: Ord> BinaryHeap<T> {
203246///
204247/// # Examples
205248///
249+ /// Basic usage:
250+ ///
206251/// ```
207252/// use std::collections::BinaryHeap;
208253/// let mut heap = BinaryHeap::new();
@@ -220,6 +265,8 @@ impl<T: Ord> BinaryHeap<T> {
220265///
221266/// # Examples
222267///
268+ /// Basic usage:
269+ ///
223270/// ```
224271/// use std::collections::BinaryHeap;
225272/// let mut heap = BinaryHeap::with_capacity(10);
@@ -235,6 +282,8 @@ impl<T: Ord> BinaryHeap<T> {
235282///
236283/// # Examples
237284///
285+ /// Basic usage:
286+ ///
238287/// ```
239288/// use std::collections::BinaryHeap;
240289/// let heap = BinaryHeap::from(vec![1, 2, 3, 4]);
@@ -253,6 +302,8 @@ impl<T: Ord> BinaryHeap<T> {
253302///
254303/// # Examples
255304///
305+ /// Basic usage:
306+ ///
256307/// ```
257308/// use std::collections::BinaryHeap;
258309/// let mut heap = BinaryHeap::new();
@@ -273,6 +324,8 @@ impl<T: Ord> BinaryHeap<T> {
273324///
274325/// # Examples
275326///
327+ /// Basic usage:
328+ ///
276329/// ```
277330/// use std::collections::BinaryHeap;
278331/// let mut heap = BinaryHeap::with_capacity(100);
@@ -297,6 +350,8 @@ impl<T: Ord> BinaryHeap<T> {
297350///
298351/// # Examples
299352///
353+ /// Basic usage:
354+ ///
300355/// ```
301356/// use std::collections::BinaryHeap;
302357/// let mut heap = BinaryHeap::new();
@@ -318,6 +373,8 @@ impl<T: Ord> BinaryHeap<T> {
318373///
319374/// # Examples
320375///
376+ /// Basic usage:
377+ ///
321378/// ```
322379/// use std::collections::BinaryHeap;
323380/// let mut heap = BinaryHeap::new();
@@ -331,6 +388,19 @@ impl<T: Ord> BinaryHeap<T> {
331388 }
332389
333390 /// Discards as much additional capacity as possible.
391+ ///
392+ /// # Examples
393+ ///
394+ /// Basic usage:
395+ ///
396+ /// ```
397+ /// use std::collections::BinaryHeap;
398+ /// let mut heap: BinaryHeap<i32> = BinaryHeap::with_capacity(100);
399+ ///
400+ /// assert!(heap.capacity() >= 100);
401+ /// heap.shrink_to_fit();
402+ /// assert!(heap.capacity() == 0);
403+ /// ```
334404#[ stable( feature = "rust1" , since = "1.0.0" ) ]
335405 pub fn shrink_to_fit ( & mut self ) {
336406 self . data . shrink_to_fit ( ) ;
@@ -341,6 +411,8 @@ impl<T: Ord> BinaryHeap<T> {
341411///
342412/// # Examples
343413///
414+ /// Basic usage:
415+ ///
344416/// ```
345417/// use std::collections::BinaryHeap;
346418/// let mut heap = BinaryHeap::from(vec![1, 3]);
@@ -364,6 +436,8 @@ impl<T: Ord> BinaryHeap<T> {
364436///
365437/// # Examples
366438///
439+ /// Basic usage:
440+ ///
367441/// ```
368442/// use std::collections::BinaryHeap;
369443/// let mut heap = BinaryHeap::new();
@@ -386,6 +460,8 @@ impl<T: Ord> BinaryHeap<T> {
386460///
387461/// # Examples
388462///
463+ /// Basic usage:
464+ ///
389465/// ```
390466/// #![feature(binary_heap_extras)]
391467///
@@ -424,6 +500,8 @@ impl<T: Ord> BinaryHeap<T> {
424500///
425501/// # Examples
426502///
503+ /// Basic usage:
504+ ///
427505/// ```
428506/// #![feature(binary_heap_extras)]
429507///
@@ -454,6 +532,8 @@ impl<T: Ord> BinaryHeap<T> {
454532///
455533/// # Examples
456534///
535+ /// Basic usage:
536+ ///
457537/// ```
458538/// use std::collections::BinaryHeap;
459539/// let heap = BinaryHeap::from(vec![1, 2, 3, 4, 5, 6, 7]);
@@ -474,6 +554,8 @@ impl<T: Ord> BinaryHeap<T> {
474554///
475555/// # Examples
476556///
557+ /// Basic usage:
558+ ///
477559/// ```
478560/// use std::collections::BinaryHeap;
479561///
@@ -571,12 +653,40 @@ impl<T: Ord> BinaryHeap<T> {
571653 }
572654
573655 /// Returns the length of the binary heap.
656+ ///
657+ /// # Examples
658+ ///
659+ /// Basic usage:
660+ ///
661+ /// ```
662+ /// use std::collections::BinaryHeap;
663+ /// let heap = BinaryHeap::from(vec![1, 3]);
664+ ///
665+ /// assert_eq!(heap.len(), 2);
666+ /// ```
574667#[ stable( feature = "rust1" , since = "1.0.0" ) ]
575668 pub fn len ( & self ) -> usize {
576669 self . data . len ( )
577670 }
578671
579672 /// Checks if the binary heap is empty.
673+ ///
674+ /// # Examples
675+ ///
676+ /// Basic usage:
677+ ///
678+ /// ```
679+ /// use std::collections::BinaryHeap;
680+ /// let mut heap = BinaryHeap::new();
681+ ///
682+ /// assert!(heap.is_empty());
683+ ///
684+ /// heap.push(3);
685+ /// heap.push(5);
686+ /// heap.push(1);
687+ ///
688+ /// assert!(!heap.is_empty());
689+ /// ```
580690#[ stable( feature = "rust1" , since = "1.0.0" ) ]
581691 pub fn is_empty ( & self ) -> bool {
582692 self . len ( ) == 0
@@ -585,13 +695,45 @@ impl<T: Ord> BinaryHeap<T> {
585695 /// Clears the binary heap, returning an iterator over the removed elements.
586696///
587697/// The elements are removed in arbitrary order.
698+ ///
699+ /// # Examples
700+ ///
701+ /// Basic usage:
702+ ///
703+ /// ```
704+ /// use std::collections::BinaryHeap;
705+ /// let mut heap = BinaryHeap::from(vec![1, 3]);
706+ ///
707+ /// assert!(!heap.is_empty());
708+ ///
709+ /// for x in heap.drain() {
710+ /// println!("{}", x);
711+ /// }
712+ ///
713+ /// assert!(heap.is_empty());
714+ /// ```
588715#[ inline]
589716 #[ stable( feature = "drain" , since = "1.6.0" ) ]
590717 pub fn drain ( & mut self ) -> Drain < T > {
591718 Drain { iter : self . data . drain ( ..) }
592719 }
593720
594721 /// Drops all items from the binary heap.
722+ ///
723+ /// # Examples
724+ ///
725+ /// Basic usage:
726+ ///
727+ /// ```
728+ /// use std::collections::BinaryHeap;
729+ /// let mut heap = BinaryHeap::from(vec![1, 3]);
730+ ///
731+ /// assert!(!heap.is_empty());
732+ ///
733+ /// heap.clear();
734+ ///
735+ /// assert!(heap.is_empty());
736+ /// ```
595737#[ stable( feature = "rust1" , since = "1.0.0" ) ]
596738 pub fn clear ( & mut self ) {
597739 self . drain ( ) ;
@@ -809,6 +951,8 @@ impl<T: Ord> IntoIterator for BinaryHeap<T> {
809951///
810952/// # Examples
811953///
954+ /// Basic usage:
955+ ///
812956/// ```
813957/// use std::collections::BinaryHeap;
814958/// let heap = BinaryHeap::from(vec![1, 2, 3, 4]);
0 commit comments