Skip to content
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

Add missing documentation examples for BTreeMap. #32135

Merged
merged 2 commits into from
Mar 9, 2016
Merged

Add missing documentation examples for BTreeMap. #32135

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a8df890
Add missing documentation examples for BTreeMap.
nathankleyn Mar 8, 2016
6799895
Add missing "basic usage" sections to docs, fix review comments.
nathankleyn Mar 9, 2016
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
111 changes: 111 additions & 0 deletions src/libcollections/btree/map.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,74 @@ use self::Entry::*;
/// It is a logic error for a key to be modified in such a way that the key's ordering relative to
/// any other key, as determined by the `Ord` trait, changes while it is in the map. This is
/// normally only possible through `Cell`, `RefCell`, global state, I/O, or unsafe code.
///
/// # Examples
///
/// ```
/// use std::collections::BTreeMap;
///
/// // type inference lets us omit an explicit type signature (which
/// // would be `BTreeMap<&str, &str>` in this example).
/// let mut movie_reviews = BTreeMap::new();
///
/// // review some books.
/// movie_reviews.insert("Office Space", "Deals with real issues in the workplace.");
/// movie_reviews.insert("Pulp Fiction", "Masterpiece.");
/// movie_reviews.insert("The Godfather", "Very enjoyable.");
/// movie_reviews.insert("The Blues Brothers", "Eye lyked it alot.");
///
/// // check for a specific one.
/// if !movie_reviews.contains_key("Les Misérables") {
/// println!("We've got {} reviews, but Les Misérables ain't one.",
/// movie_reviews.len());
/// }
///
/// // oops, this review has a lot of spelling mistakes, let's delete it.
/// movie_reviews.remove("The Blues Brothers");
///
/// // look up the values associated with some keys.
/// let to_find = ["Up!", "Office Space"];
/// for book in &to_find {
/// match movie_reviews.get(book) {
/// Some(review) => println!("{}: {}", book, review),
/// None => println!("{} is unreviewed.", book)
/// }
/// }
///
/// // iterate over everything.
/// for (movie, review) in &movie_reviews {
/// println!("{}: \"{}\"", movie, review);
/// }
/// ```
///
/// `BTreeMap` also implements an [`Entry API`](#method.entry), which allows
/// for more complex methods of getting, setting, updating and removing keys and
/// their values:
///
/// ```
/// use std::collections::BTreeMap;
///
/// // type inference lets us omit an explicit type signature (which
/// // would be `BTreeMap<&str, u8>` in this example).
/// let mut player_stats = BTreeMap::new();
///
/// fn random_stat_buff() -> u8 {
/// // could actually return some random value here - let's just return
/// // some fixed value for now
/// 42
/// }
///
/// // insert a key only if it doesn't already exist
/// player_stats.entry("health").or_insert(100);
///
/// // insert a key using a function that provides a new value only if it
/// // doesn't already exist
/// player_stats.entry("defence").or_insert_with(random_stat_buff);
///
/// // update a key, guarding against the key possibly not being set
/// let stat = player_stats.entry("attack").or_insert(100);
/// *stat += random_stat_buff();
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub struct BTreeMap<K, V> {
root: node::Root<K, V>,
Expand Down Expand Up @@ -276,6 +344,19 @@ pub struct OccupiedEntry<'a, K: 'a, V: 'a> {

impl<K: Ord, V> BTreeMap<K, V> {
/// Makes a new empty BTreeMap with a reasonable choice for B.
///
/// # Examples
///
/// Basic usage:
///
/// ```
Copy link
Member

Choose a reason for hiding this comment

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

I've been putting a

/// Basic usage:

line before the first example. Since you're going to be doing a few of these, mind putting this in? If it's too much trouble, I can also do it later.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Not a problem at all - plan to contribute a lot more going forward, so have a whole bunch of PRs to come. Best to learn the right way to do these things now!

Fixed!

Copy link
Member

Choose a reason for hiding this comment

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

Great, I was hoping so 😄

Copy link
Member

Choose a reason for hiding this comment

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

(I think you forgot to push commits, you said it was fixed but there's no new commit)

/// use std::collections::BTreeMap;
///
/// let mut map = BTreeMap::new();
///
/// // entries can now be inserted into the empty map
/// a.insert(1, "a");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn new() -> BTreeMap<K, V> {
BTreeMap {
Expand All @@ -288,6 +369,8 @@ impl<K: Ord, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand All @@ -309,6 +392,8 @@ impl<K: Ord, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand All @@ -332,6 +417,8 @@ impl<K: Ord, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand All @@ -352,6 +439,8 @@ impl<K: Ord, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand Down Expand Up @@ -384,6 +473,8 @@ impl<K: Ord, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand Down Expand Up @@ -414,6 +505,8 @@ impl<K: Ord, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand Down Expand Up @@ -443,6 +536,8 @@ impl<K: Ord, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// #![feature(btree_range, collections_bound)]
///
Expand Down Expand Up @@ -516,6 +611,8 @@ impl<K: Ord, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// #![feature(btree_range, collections_bound)]
///
Expand Down Expand Up @@ -591,6 +688,8 @@ impl<K: Ord, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand Down Expand Up @@ -1199,6 +1298,8 @@ impl<K, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand Down Expand Up @@ -1229,6 +1330,8 @@ impl<K, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand Down Expand Up @@ -1262,6 +1365,8 @@ impl<K, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand All @@ -1281,6 +1386,8 @@ impl<K, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand All @@ -1300,6 +1407,8 @@ impl<K, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand All @@ -1317,6 +1426,8 @@ impl<K, V> BTreeMap<K, V> {
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use std::collections::BTreeMap;
///
Expand Down