Skip to content

Improve docs & doc examples for HashSet. #43585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Aug 2, 2017
Merged

Improve docs & doc examples for HashSet. #43585

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8810627
Add doc example for HashSet::hasher.
frewsxcv Aug 1, 2017
9e19260
Show that the capacity changed in HashSet::reserve doc example.
frewsxcv Aug 1, 2017
070eb3c
Indicate HashSet is code-like in docs.
frewsxcv Aug 1, 2017
9e2b0c6
Remove unnecessary 'mut' bindings.
frewsxcv Aug 1, 2017
1599fad
Show the capacity in HashSet::with_capacity doc example.
frewsxcv Aug 1, 2017
34c1bfb
Remove unnecessary clones in doc examples.
frewsxcv Aug 1, 2017
d9df296
Add doc example for HashSet::drain.
frewsxcv Aug 1, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 43 additions & 14 deletions src/libstd/collections/hash/set.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,13 +123,13 @@ pub struct HashSet<T, S = RandomState> {
}

impl<T: Hash + Eq> HashSet<T, RandomState> {
/// Creates an empty HashSet.
/// Creates an empty `HashSet`.
///
/// # Examples
///
/// ```
/// use std::collections::HashSet;
/// let mut set: HashSet<i32> = HashSet::new();
/// let set: HashSet<i32> = HashSet::new();
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
Expand All @@ -146,7 +146,8 @@ impl<T: Hash + Eq> HashSet<T, RandomState> {
///
/// ```
/// use std::collections::HashSet;
/// let mut set: HashSet<i32> = HashSet::with_capacity(10);
/// let set: HashSet<i32> = HashSet::with_capacity(10);
/// assert!(set.capacity() >= 10);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't it be more accurate to check if the capacity is equal to 10 instead of >= ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general, the allocator may give you more than you asked for.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hum ok.

/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
Expand Down Expand Up @@ -215,6 +216,17 @@ impl<T, S> HashSet<T, S>
/// Returns a reference to the set's [`BuildHasher`].
///
/// [`BuildHasher`]: ../../std/hash/trait.BuildHasher.html
///
/// # Examples
///
/// ```
/// use std::collections::HashSet;
/// use std::collections::hash_map::RandomState;
///
/// let hasher = RandomState::new();
/// let set: HashSet<i32> = HashSet::with_hasher(hasher);
/// let hasher: &RandomState = set.hasher();
/// ```
#[stable(feature = "hashmap_public_hasher", since = "1.9.0")]
pub fn hasher(&self) -> &S {
self.map.hasher()
Expand Down Expand Up @@ -249,6 +261,7 @@ impl<T, S> HashSet<T, S>
/// use std::collections::HashSet;
/// let mut set: HashSet<i32> = HashSet::new();
/// set.reserve(10);
/// assert!(set.capacity() >= 10);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn reserve(&mut self, additional: usize) {
Expand Down Expand Up @@ -312,13 +325,13 @@ impl<T, S> HashSet<T, S>
/// println!("{}", x); // Print 1
/// }
///
/// let diff: HashSet<_> = a.difference(&b).cloned().collect();
/// assert_eq!(diff, [1].iter().cloned().collect());
/// let diff: HashSet<_> = a.difference(&b).collect();
/// assert_eq!(diff, [1].iter().collect());
///
/// // Note that difference is not symmetric,
/// // and `b - a` means something else:
/// let diff: HashSet<_> = b.difference(&a).cloned().collect();
/// assert_eq!(diff, [4].iter().cloned().collect());
/// let diff: HashSet<_> = b.difference(&a).collect();
/// assert_eq!(diff, [4].iter().collect());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn difference<'a>(&'a self, other: &'a HashSet<T, S>) -> Difference<'a, T, S> {
Expand All @@ -343,11 +356,11 @@ impl<T, S> HashSet<T, S>
/// println!("{}", x);
/// }
///
/// let diff1: HashSet<_> = a.symmetric_difference(&b).cloned().collect();
/// let diff2: HashSet<_> = b.symmetric_difference(&a).cloned().collect();
/// let diff1: HashSet<_> = a.symmetric_difference(&b).collect();
/// let diff2: HashSet<_> = b.symmetric_difference(&a).collect();
///
/// assert_eq!(diff1, diff2);
/// assert_eq!(diff1, [1, 4].iter().cloned().collect());
/// assert_eq!(diff1, [1, 4].iter().collect());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn symmetric_difference<'a>(&'a self,
Expand All @@ -371,8 +384,8 @@ impl<T, S> HashSet<T, S>
/// println!("{}", x);
/// }
///
/// let intersection: HashSet<_> = a.intersection(&b).cloned().collect();
/// assert_eq!(intersection, [2, 3].iter().cloned().collect());
/// let intersection: HashSet<_> = a.intersection(&b).collect();
/// assert_eq!(intersection, [2, 3].iter().collect());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn intersection<'a>(&'a self, other: &'a HashSet<T, S>) -> Intersection<'a, T, S> {
Expand All @@ -397,8 +410,8 @@ impl<T, S> HashSet<T, S>
/// println!("{}", x);
/// }
///
/// let union: HashSet<_> = a.union(&b).cloned().collect();
/// assert_eq!(union, [1, 2, 3, 4].iter().cloned().collect());
/// let union: HashSet<_> = a.union(&b).collect();
/// assert_eq!(union, [1, 2, 3, 4].iter().collect());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn union<'a>(&'a self, other: &'a HashSet<T, S>) -> Union<'a, T, S> {
Expand Down Expand Up @@ -440,6 +453,22 @@ impl<T, S> HashSet<T, S>
}

/// Clears the set, returning all elements in an iterator.
///
/// # Examples
///
/// ```
/// use std::collections::HashSet;
///
/// let mut set: HashSet<_> = [1, 2, 3].iter().cloned().collect();
/// assert!(!set.is_empty());
///
/// // print 1, 2, 3 in an arbitrary order
/// for i in set.drain() {
/// println!("{}", i);
/// }
///
/// assert!(set.is_empty());
/// ```
#[inline]
#[stable(feature = "drain", since = "1.6.0")]
pub fn drain(&mut self) -> Drain<T> {
Expand Down