From 118b975c805533bab31f8155ad0af29b3635d3fc Mon Sep 17 00:00:00 2001 From: Nathan Kleyn Date: Tue, 8 Mar 2016 23:27:24 +0000 Subject: [PATCH 1/3] 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 #29348. --- src/libcollections/binary_heap.rs | 106 ++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) diff --git a/src/libcollections/binary_heap.rs b/src/libcollections/binary_heap.rs index bd329949618e5..efd56bdb264f2 100644 --- a/src/libcollections/binary_heap.rs +++ b/src/libcollections/binary_heap.rs @@ -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` 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 { data: Vec, @@ -331,6 +374,17 @@ impl BinaryHeap { } /// Discards as much additional capacity as possible. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BinaryHeap; + /// let mut heap: BinaryHeap = 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(); @@ -571,12 +625,36 @@ impl BinaryHeap { } /// Returns the length of the binary heap. + /// + /// # Examples + /// + /// ``` + /// 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 + /// + /// ``` + /// 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 @@ -585,6 +663,21 @@ impl BinaryHeap { /// Clears the binary heap, returning an iterator over the removed elements. /// /// The elements are removed in arbitrary order. + /// + /// # Examples + /// + /// ``` + /// 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 { @@ -592,6 +685,19 @@ impl BinaryHeap { } /// Drops all items from the binary heap. + /// + /// # Examples + /// + /// ``` + /// 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(); From 04436fb65b7efa81793f0f89cf375d0fadf99f89 Mon Sep 17 00:00:00 2001 From: Nathan Kleyn Date: Wed, 9 Mar 2016 16:18:31 +0000 Subject: [PATCH 2/3] Address review comments to add "basic usage" sections to docs. --- src/libcollections/binary_heap.rs | 38 +++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/src/libcollections/binary_heap.rs b/src/libcollections/binary_heap.rs index efd56bdb264f2..29258180c67ba 100644 --- a/src/libcollections/binary_heap.rs +++ b/src/libcollections/binary_heap.rs @@ -246,6 +246,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::new(); @@ -263,6 +265,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::with_capacity(10); @@ -278,6 +282,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let heap = BinaryHeap::from(vec![1, 2, 3, 4]); @@ -296,6 +302,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::new(); @@ -316,6 +324,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::with_capacity(100); @@ -340,6 +350,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::new(); @@ -361,6 +373,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::new(); @@ -377,6 +391,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap: BinaryHeap = BinaryHeap::with_capacity(100); @@ -395,6 +411,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::from(vec![1, 3]); @@ -418,6 +436,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::new(); @@ -440,6 +460,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// #![feature(binary_heap_extras)] /// @@ -478,6 +500,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// #![feature(binary_heap_extras)] /// @@ -508,6 +532,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let heap = BinaryHeap::from(vec![1, 2, 3, 4, 5, 6, 7]); @@ -528,6 +554,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// @@ -628,6 +656,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::from(vec![1, 3]); @@ -643,6 +673,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::new(); @@ -666,6 +698,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::from(vec![1, 3]); @@ -688,6 +722,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::from(vec![1, 3]); @@ -915,6 +951,8 @@ impl IntoIterator for BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let heap = BinaryHeap::from(vec![1, 2, 3, 4]); From da4fda44e742671c9451b0b0fd811a5626828041 Mon Sep 17 00:00:00 2001 From: Nathan Kleyn Date: Thu, 10 Mar 2016 11:40:31 +0000 Subject: [PATCH 3/3] Remove unnecessary mut in docs causing test failures. --- src/libcollections/binary_heap.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcollections/binary_heap.rs b/src/libcollections/binary_heap.rs index 29258180c67ba..ba317334cfa0b 100644 --- a/src/libcollections/binary_heap.rs +++ b/src/libcollections/binary_heap.rs @@ -660,7 +660,7 @@ impl BinaryHeap { /// /// ``` /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::from(vec![1, 3]); + /// let heap = BinaryHeap::from(vec![1, 3]); /// /// assert_eq!(heap.len(), 2); /// ```