From a8df890437a39a5f790ea7f08cd0e3b205f40353 Mon Sep 17 00:00:00 2001 From: Nathan Kleyn Date: Tue, 8 Mar 2016 22:44:40 +0000 Subject: [PATCH 1/2] Add missing documentation examples for BTreeMap. As part of the ongoing effort to document all methods with examples, this commit adds the missing examples for the `BTreeMap` collection type. This is part of issue #29348. --- src/libcollections/btree/map.rs | 76 +++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs index 2a950ce0ab7..107a9d415a5 100644 --- a/src/libcollections/btree/map.rs +++ b/src/libcollections/btree/map.rs @@ -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 { root: node::Root, @@ -276,6 +344,14 @@ pub struct OccupiedEntry<'a, K: 'a, V: 'a> { impl BTreeMap { /// Makes a new empty BTreeMap with a reasonable choice for B. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// + /// let mut map: BTreeMap<&str, isize> = BTreeMap::new(); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn new() -> BTreeMap { BTreeMap { From 6799895b6d08e2b3be41a13b74b78368e4f08945 Mon Sep 17 00:00:00 2001 From: Nathan Kleyn Date: Wed, 9 Mar 2016 16:39:23 +0000 Subject: [PATCH 2/2] Add missing "basic usage" sections to docs, fix review comments. --- src/libcollections/btree/map.rs | 37 ++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs index 107a9d415a5..47518d8b33d 100644 --- a/src/libcollections/btree/map.rs +++ b/src/libcollections/btree/map.rs @@ -347,10 +347,15 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// - /// let mut map: BTreeMap<&str, isize> = BTreeMap::new(); + /// 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 { @@ -364,6 +369,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -385,6 +392,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -408,6 +417,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -428,6 +439,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -460,6 +473,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -490,6 +505,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -519,6 +536,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// #![feature(btree_range, collections_bound)] /// @@ -592,6 +611,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// #![feature(btree_range, collections_bound)] /// @@ -667,6 +688,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -1275,6 +1298,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -1305,6 +1330,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -1338,6 +1365,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -1357,6 +1386,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -1376,6 +1407,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; /// @@ -1393,6 +1426,8 @@ impl BTreeMap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BTreeMap; ///