Skip to content

Commit

Permalink
Rollup merge of rust-lang#32137 - nathankleyn:improve-docs-for-binary…
Browse files Browse the repository at this point in the history
…heap, r=steveklabnik

Add missing documentation examples for BinaryHeap.

As part of the ongoing effort to document all methods with examples,
this commit adds the missing examples for the `BinaryHeap` collection
type.

This is part of issue rust-lang#29348.

r? @steveklabnik
  • Loading branch information
steveklabnik committed Mar 10, 2016
2 parents 5926108 + 04436fb commit 92958be
Showing 1 changed file with 144 additions and 0 deletions.
144 changes: 144 additions & 0 deletions src/libcollections/binary_heap.rs
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,49 @@ use vec::{self, Vec};
/// item's ordering relative to any other item, as determined by the `Ord`
/// trait, changes while it is in the heap. This is normally only possible
/// through `Cell`, `RefCell`, global state, I/O, or unsafe code.
///
/// # Examples
///
/// ```
/// use std::collections::BinaryHeap;
///
/// // type inference lets us omit an explicit type signature (which
/// // would be `BinaryHeap<i32>` in this example).
/// let mut heap = BinaryHeap::new();
///
/// // We can use peek to look at the next item in the heap. In this case,
/// // there's no items in there yet so we get None.
/// assert_eq!(heap.peek(), None);
///
/// // Let's add some scores...
/// heap.push(1);
/// heap.push(5);
/// heap.push(2);
///
/// // Now peek shows the most important item in the heap.
/// assert_eq!(heap.peek(), Some(&5));
///
/// // We can check the length of a heap.
/// assert_eq!(heap.len(), 3);
///
/// // We can iterate over the items in the heap, although they are returned in
/// // a random order.
/// for x in heap.iter() {
/// println!("{}", x);
/// }
///
/// // If we instead pop these scores, they should come back in order.
/// assert_eq!(heap.pop(), Some(5));
/// assert_eq!(heap.pop(), Some(2));
/// assert_eq!(heap.pop(), Some(1));
/// assert_eq!(heap.pop(), None);
///
/// // We can clear the heap of any remaining items.
/// heap.clear();
///
/// // The heap should now be empty.
/// assert!(heap.is_empty())
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub struct BinaryHeap<T> {
data: Vec<T>,
Expand Down Expand Up @@ -203,6 +246,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::new();
Expand All @@ -220,6 +265,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::with_capacity(10);
Expand All @@ -235,6 +282,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let heap = BinaryHeap::from(vec![1, 2, 3, 4]);
Expand All @@ -253,6 +302,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::new();
Expand All @@ -273,6 +324,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::with_capacity(100);
Expand All @@ -297,6 +350,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::new();
Expand All @@ -318,6 +373,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::new();
Expand All @@ -331,6 +388,19 @@ impl<T: Ord> BinaryHeap<T> {
}

/// Discards as much additional capacity as possible.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap: BinaryHeap<i32> = BinaryHeap::with_capacity(100);
///
/// assert!(heap.capacity() >= 100);
/// heap.shrink_to_fit();
/// assert!(heap.capacity() == 0);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn shrink_to_fit(&mut self) {
self.data.shrink_to_fit();
Expand All @@ -341,6 +411,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::from(vec![1, 3]);
Expand All @@ -364,6 +436,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::new();
Expand All @@ -386,6 +460,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// #![feature(binary_heap_extras)]
///
Expand Down Expand Up @@ -424,6 +500,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// #![feature(binary_heap_extras)]
///
Expand Down Expand Up @@ -454,6 +532,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let heap = BinaryHeap::from(vec![1, 2, 3, 4, 5, 6, 7]);
Expand All @@ -474,6 +554,8 @@ impl<T: Ord> BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
///
Expand Down Expand Up @@ -571,12 +653,40 @@ impl<T: Ord> BinaryHeap<T> {
}

/// Returns the length of the binary heap.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::from(vec![1, 3]);
///
/// assert_eq!(heap.len(), 2);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn len(&self) -> usize {
self.data.len()
}

/// Checks if the binary heap is empty.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::new();
///
/// assert!(heap.is_empty());
///
/// heap.push(3);
/// heap.push(5);
/// heap.push(1);
///
/// assert!(!heap.is_empty());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_empty(&self) -> bool {
self.len() == 0
Expand All @@ -585,13 +695,45 @@ impl<T: Ord> BinaryHeap<T> {
/// Clears the binary heap, returning an iterator over the removed elements.
///
/// The elements are removed in arbitrary order.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::from(vec![1, 3]);
///
/// assert!(!heap.is_empty());
///
/// for x in heap.drain() {
/// println!("{}", x);
/// }
///
/// assert!(heap.is_empty());
/// ```
#[inline]
#[stable(feature = "drain", since = "1.6.0")]
pub fn drain(&mut self) -> Drain<T> {
Drain { iter: self.data.drain(..) }
}

/// Drops all items from the binary heap.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let mut heap = BinaryHeap::from(vec![1, 3]);
///
/// assert!(!heap.is_empty());
///
/// heap.clear();
///
/// assert!(heap.is_empty());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn clear(&mut self) {
self.drain();
Expand Down Expand Up @@ -809,6 +951,8 @@ impl<T: Ord> IntoIterator for BinaryHeap<T> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BinaryHeap;
/// let heap = BinaryHeap::from(vec![1, 2, 3, 4]);
Expand Down

0 comments on commit 92958be

Please sign in to comment.