From 451cc7e5c07ec50ff35b9447999cb3e990cef340 Mon Sep 17 00:00:00 2001
From: jbranchaud <jbranchaud@gmail.com>
Date: Tue, 2 Dec 2014 22:59:24 -0600
Subject: [PATCH] Add doctests for union, diff, sym_diff, and intersection.

Add a rustdoc test for union to exhibit how it is used.

There is already a test for union in the test namespace, but this commit
adds a doctest that will appear in the rustdocs.

Add a doctest for the difference function.

Add a doctest for the symmetric_difference function.

Add a doctest for the intersection function.

Update the union et al. doctests based on @Gankro's comments.

Make the union et al. doctests a bit more readable.
---
 src/libcollections/btree/set.rs | 66 +++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs
index 64ae4f6a50867..3973b4774b3ae 100644
--- a/src/libcollections/btree/set.rs
+++ b/src/libcollections/btree/set.rs
@@ -94,12 +94,46 @@ impl<T> BTreeSet<T> {
 
 impl<T: Ord> BTreeSet<T> {
     /// Visits the values representing the difference, in ascending order.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::BTreeSet;
+    ///
+    /// let mut a = BTreeSet::new();
+    /// a.insert(1u);
+    /// a.insert(2u);
+    ///
+    /// let mut b = BTreeSet::new();
+    /// b.insert(2u);
+    /// b.insert(3u);
+    ///
+    /// let diff: Vec<uint> = a.difference(&b).cloned().collect();
+    /// assert_eq!(diff, vec![1u]);
+    /// ```
     #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn difference<'a>(&'a self, other: &'a BTreeSet<T>) -> DifferenceItems<'a, T> {
         DifferenceItems{a: self.iter().peekable(), b: other.iter().peekable()}
     }
 
     /// Visits the values representing the symmetric difference, in ascending order.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::BTreeSet;
+    ///
+    /// let mut a = BTreeSet::new();
+    /// a.insert(1u);
+    /// a.insert(2u);
+    ///
+    /// let mut b = BTreeSet::new();
+    /// b.insert(2u);
+    /// b.insert(3u);
+    ///
+    /// let sym_diff: Vec<uint> = a.symmetric_difference(&b).cloned().collect();
+    /// assert_eq!(sym_diff, vec![1u,3]);
+    /// ```
     #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn symmetric_difference<'a>(&'a self, other: &'a BTreeSet<T>)
         -> SymDifferenceItems<'a, T> {
@@ -107,6 +141,23 @@ impl<T: Ord> BTreeSet<T> {
     }
 
     /// Visits the values representing the intersection, in ascending order.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::BTreeSet;
+    ///
+    /// let mut a = BTreeSet::new();
+    /// a.insert(1u);
+    /// a.insert(2u);
+    ///
+    /// let mut b = BTreeSet::new();
+    /// b.insert(2u);
+    /// b.insert(3u);
+    ///
+    /// let intersection: Vec<uint> = a.intersection(&b).cloned().collect();
+    /// assert_eq!(intersection, vec![2u]);
+    /// ```
     #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn intersection<'a>(&'a self, other: &'a BTreeSet<T>)
         -> IntersectionItems<'a, T> {
@@ -114,6 +165,21 @@ impl<T: Ord> BTreeSet<T> {
     }
 
     /// Visits the values representing the union, in ascending order.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::BTreeSet;
+    ///
+    /// let mut a = BTreeSet::new();
+    /// a.insert(1u);
+    ///
+    /// let mut b = BTreeSet::new();
+    /// b.insert(2u);
+    ///
+    /// let union: Vec<uint> = a.union(&b).cloned().collect();
+    /// assert_eq!(union, vec![1u,2]);
+    /// ```
     #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn union<'a>(&'a self, other: &'a BTreeSet<T>) -> UnionItems<'a, T> {
         UnionItems{a: self.iter().peekable(), b: other.iter().peekable()}