From cf56c1f744c3e7c71a1d5a80b8889b9fab8f6de7 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 6 Dec 2016 15:20:51 -1000 Subject: [PATCH 1/4] Indicate `BTreeSet` in docs is code-like. --- src/libcollections/btree/set.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index c57266d9e3b4a..46302db0d5bea 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -74,19 +74,19 @@ pub struct BTreeSet { map: BTreeMap, } -/// An iterator over a BTreeSet's items. +/// An iterator over a `BTreeSet`'s items. #[stable(feature = "rust1", since = "1.0.0")] pub struct Iter<'a, T: 'a> { iter: Keys<'a, T, ()>, } -/// An owning iterator over a BTreeSet's items. +/// An owning iterator over a `BTreeSet`'s items. #[stable(feature = "rust1", since = "1.0.0")] pub struct IntoIter { iter: ::btree_map::IntoIter, } -/// An iterator over a sub-range of BTreeSet's items. +/// An iterator over a sub-range of `BTreeSet`'s items. pub struct Range<'a, T: 'a> { iter: ::btree_map::Range<'a, T, ()>, } @@ -120,7 +120,7 @@ pub struct Union<'a, T: 'a> { } impl BTreeSet { - /// Makes a new BTreeSet with a reasonable choice of B. + /// Makes a new `BTreeSet` with a reasonable choice of B. /// /// # Examples /// @@ -137,7 +137,7 @@ impl BTreeSet { } impl BTreeSet { - /// Gets an iterator over the BTreeSet's contents. + /// Gets an iterator over the `BTreeSet`'s contents. /// /// # Examples /// From ae369340473fc4bb5b30d20d32022f7ae9f8324c Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 6 Dec 2016 15:34:55 -1000 Subject: [PATCH 2/4] Document how `BTreeSet` iterator structures are created. --- src/libcollections/btree/set.rs | 36 +++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index 46302db0d5bea..91da8e8b07951 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -75,23 +75,43 @@ pub struct BTreeSet { } /// An iterator over a `BTreeSet`'s items. +/// +/// This structure is created by the [`iter`] method on [`BTreeSet`]. +/// +/// [`BTreeSet`]: struct.BTreeSet.html +/// [`iter`]: struct.BTreeSet.html#method.iter #[stable(feature = "rust1", since = "1.0.0")] pub struct Iter<'a, T: 'a> { iter: Keys<'a, T, ()>, } /// An owning iterator over a `BTreeSet`'s items. +/// +/// This structure is created by the `into_iter` method on [`BTreeSet`] +/// [`BTreeSet`] (provided by the `IntoIterator` trait). +/// +/// [`BTreeSet`]: struct.BTreeSet.html #[stable(feature = "rust1", since = "1.0.0")] pub struct IntoIter { iter: ::btree_map::IntoIter, } /// An iterator over a sub-range of `BTreeSet`'s items. +/// +/// This structure is created by the [`range`] method on [`BTreeSet`]. +/// +/// [`BTreeSet`]: struct.BTreeSet.html +/// [`range`]: struct.BTreeSet.html#method.range pub struct Range<'a, T: 'a> { iter: ::btree_map::Range<'a, T, ()>, } /// A lazy iterator producing elements in the set difference (in-order). +/// +/// This structure is created by the [`difference`] method on [`BTreeSet`]. +/// +/// [`BTreeSet`]: struct.BTreeSet.html +/// [`difference`]: struct.BTreeSet.html#method.difference #[stable(feature = "rust1", since = "1.0.0")] pub struct Difference<'a, T: 'a> { a: Peekable>, @@ -99,6 +119,12 @@ pub struct Difference<'a, T: 'a> { } /// A lazy iterator producing elements in the set symmetric difference (in-order). +/// +/// This structure is created by the [`symmetric_difference`] method on +/// [`BTreeSet`]. +/// +/// [`BTreeSet`]: struct.BTreeSet.html +/// [`symmetric_difference`]: struct.BTreeSet.html#method.symmetric_difference #[stable(feature = "rust1", since = "1.0.0")] pub struct SymmetricDifference<'a, T: 'a> { a: Peekable>, @@ -106,6 +132,11 @@ pub struct SymmetricDifference<'a, T: 'a> { } /// A lazy iterator producing elements in the set intersection (in-order). +/// +/// This structure is created by the [`intersection`] method on [`BTreeSet`]. +/// +/// [`BTreeSet`]: struct.BTreeSet.html +/// [`intersection`]: struct.BTreeSet.html#method.intersection #[stable(feature = "rust1", since = "1.0.0")] pub struct Intersection<'a, T: 'a> { a: Peekable>, @@ -113,6 +144,11 @@ pub struct Intersection<'a, T: 'a> { } /// A lazy iterator producing elements in the set union (in-order). +/// +/// This structure is created by the [`union`] method on [`BTreeSet`]. +/// +/// [`BTreeSet`]: struct.BTreeSet.html +/// [`union`]: struct.BTreeSet.html#method.union #[stable(feature = "rust1", since = "1.0.0")] pub struct Union<'a, T: 'a> { a: Peekable>, From 4c4e8c4af77edda2d62dc8de3cfbcb8393a30ea9 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 6 Dec 2016 15:44:46 -1000 Subject: [PATCH 3/4] Simplify `BTreeSet::iter` doc example. --- src/libcollections/btree/set.rs | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index 91da8e8b07951..ffd5d7a919271 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -180,14 +180,12 @@ impl BTreeSet { /// ``` /// use std::collections::BTreeSet; /// - /// let set: BTreeSet = [1, 2, 3, 4].iter().cloned().collect(); - /// - /// for x in set.iter() { - /// println!("{}", x); - /// } - /// - /// let v: Vec<_> = set.iter().cloned().collect(); - /// assert_eq!(v, [1, 2, 3, 4]); + /// let set: BTreeSet = [1, 2, 3].iter().cloned().collect(); + /// let mut set_iter = set.iter(); + /// assert_eq!(set_iter.next(), Some(&1)); + /// assert_eq!(set_iter.next(), Some(&2)); + /// assert_eq!(set_iter.next(), Some(&3)); + /// assert_eq!(set_iter.next(), None); /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn iter(&self) -> Iter { From fe0d0927f7c01b491a3f247bf2618b64e201bc43 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 6 Dec 2016 15:47:33 -1000 Subject: [PATCH 4/4] Indicate that `BTreeSet::iter` returns values in ascending order. Fixes https://github.com/rust-lang/rust/issues/38204. --- src/libcollections/btree/set.rs | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index ffd5d7a919271..34674e3a0bd30 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -173,7 +173,7 @@ impl BTreeSet { } impl BTreeSet { - /// Gets an iterator over the `BTreeSet`'s contents. + /// Gets an iterator that visits the values in the `BTreeSet` in ascending order. /// /// # Examples /// @@ -187,6 +187,19 @@ impl BTreeSet { /// assert_eq!(set_iter.next(), Some(&3)); /// assert_eq!(set_iter.next(), None); /// ``` + /// + /// Values returned by the iterator are returned in ascending order: + /// + /// ``` + /// use std::collections::BTreeSet; + /// + /// let set: BTreeSet = [3, 1, 2].iter().cloned().collect(); + /// let mut set_iter = set.iter(); + /// assert_eq!(set_iter.next(), Some(&1)); + /// assert_eq!(set_iter.next(), Some(&2)); + /// assert_eq!(set_iter.next(), Some(&3)); + /// assert_eq!(set_iter.next(), None); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn iter(&self) -> Iter { Iter { iter: self.map.keys() }