---

yaml
---
r: 153854
b: refs/heads/try2
c: 53c6391
h: refs/heads/master
v: v3

Author: treeman

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: 78a7676898d9f80ab540c6df5d4c9ce35bb50463
 refs/heads/try: 519addf6277dbafccbb4159db4b710c37eaa2ec5
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: 8c34a97b37a2f546490546c5cac97c9add8a2972
+refs/heads/try2: 53c639184cbbdb95d316cb36691a2f9722dfc41a
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/src/libcollections/treemap.rs

@@ -47,6 +47,107 @@ use vec::Vec;
 /// a red-black tree where red (horizontal) nodes can only be added
 /// as a right child. The time complexity is the same, and re-balancing
 /// operations are more frequent but also cheaper.
+///
+/// # Example
+///
+/// ```
+/// use std::collections::TreeMap;
+///
+/// let mut map = TreeMap::new();
+///
+/// map.insert(2i, "bar");
+/// map.insert(1i, "foo");
+/// map.insert(3i, "quux");
+///
+/// // In ascending order by keys
+/// for (key, value) in map.iter() {
+///     println!("{}: {}", key, value);
+/// }
+///
+/// // Print 1, 2, 3
+/// for key in map.keys() {
+///     println!("{}", key);
+/// }
+///
+/// // Print `foo`, `bar`, `quux`
+/// for key in map.values() {
+///     println!("{}", key);
+/// }
+///
+/// map.remove(&1);
+/// assert_eq!(map.len(), 2);
+///
+/// if !map.contains_key(&1) {
+///     println!("1 is no more");
+/// }
+///
+/// for key in range(0, 4) {
+///     match map.find(&key) {
+///         Some(val) => println!("{} has a value: {}", key, val),
+///         None => println!("{} not in map", key),
+///     }
+/// }
+///
+/// map.clear();
+/// assert!(map.is_empty());
+/// ```
+///
+/// The easiest way to use `TreeMap` with a custom type as keys is to implement `Ord`.
+/// We must also implement `PartialEq`, `Eq` and `PartialOrd`.
+///
+/// ```
+/// use std::collections::TreeMap;
+///
+/// // We need `Eq` and `PartialEq`, these can be derived.
+/// #[deriving(Eq, PartialEq)]
+/// struct Troll<'a> {
+///     name: &'a str,
+///     level: uint,
+/// }
+///
+/// // Implement `Ord` and sort trolls by level.
+/// impl<'a> Ord for Troll<'a> {
+///     fn cmp(&self, other: &Troll) -> Ordering {
+///         // If we swap `self` and `other`, we get descended ordering.
+///         self.level.cmp(&other.level)
+///     }
+/// }
+///
+/// // `PartialOrd` needs to be implemented as well.
+/// impl<'a> PartialOrd for Troll<'a> {
+///     fn partial_cmp(&self, other: &Troll) -> Option<Ordering> {
+///         Some(self.cmp(other))
+///     }
+/// }
+///
+/// // Use a map to store trolls, sorted by level, and track a list of
+/// // heroes slain.
+/// let mut trolls = TreeMap::new();
+///
+/// trolls.insert(Troll { name: "Orgarr", level: 2 },
+///               vec!["King Karl"]);
+/// trolls.insert(Troll { name: "Blargarr", level: 3 },
+///               vec!["Odd"]);
+/// trolls.insert(Troll { name: "Kron the Smelly One", level: 4 },
+///               vec!["Omar the Brave", "Peter: Slayer of Trolls"]);
+/// trolls.insert(Troll { name: "Wartilda", level: 1 },
+///               vec![]);
+///
+/// println!("You are facing {} trolls!", trolls.len());
+///
+/// // Print the trolls, ordered by level with smallest level first
+/// for (troll, heroes) in trolls.iter() {
+///     let what = if heroes.len() == 1u { "hero" }
+///                else { "heroes" };
+///
+///     println!("level {}: '{}' has slain {} {}",
+///              troll.level, troll.name, heroes.len(), what);
+/// }
+///
+/// // Kill all trolls
+/// trolls.clear();
+/// assert_eq!(trolls.len(), 0);
+/// ```
 
 // Future improvements: