diff --git a/src/libcollections/smallintmap.rs b/src/libcollections/smallintmap.rs index 603d5bb820d49..0b937bb75c23e 100644 --- a/src/libcollections/smallintmap.rs +++ b/src/libcollections/smallintmap.rs @@ -19,7 +19,36 @@ use std::iter::{Enumerate, FilterMap, Rev}; use std::mem::replace; use std::vec; -#[allow(missing_doc)] +/// A map implementation designed for use with small unsigned integer keys. +/// +/// Underneath, it's backed by a simple continuous vector where a key-value pair +/// with the key `n` is stored in the n-th element of the vector. +/// Therefore, its memory usage is proportional to the maximum value of all the +/// keys in the map. +/// +/// # Example +/// +/// ```rust +/// use collections::SmallIntMap; +/// +/// let mut birthdates = SmallIntMap::new(); +/// +/// // Add some key-value pairs. +/// birthdates.insert(1987, ~"John"); +/// birthdates.insert(1955, ~"Alice"); +/// birthdates.insert(1990, ~"Anna"); +/// +/// // Find a single element. +/// match birthdates.get(1955) { +/// Some(v) => println!("{}", v); +/// None => println!("Not found."); +/// } +/// +/// // Iterate over the map. +/// for (year, name) in birthdates { +/// println!("{} => {}", year, name); +/// } +/// ``` pub struct SmallIntMap { priv v: ~[Option], } @@ -112,6 +141,11 @@ impl SmallIntMap { /// Create an empty SmallIntMap pub fn new() -> SmallIntMap { SmallIntMap{v: ~[]} } + /// Return a reference to the value corresponding to the key. + /// + /// # Failure + /// + /// Fails if the key does not exist. pub fn get<'a>(&'a self, key: &uint) -> &'a V { self.find(key).expect("key not present") } @@ -163,6 +197,11 @@ impl SmallIntMap { } impl SmallIntMap { + /// Insert a key-value pair into the map. If the key already exists, uses the function `ff` + /// to resolve the collision. + /// + /// The arguments to the user-provided function are the key, the original value and the new + /// intended value and its return value is used as the final value that is put into the map. pub fn update_with_key(&mut self, key: uint, val: V, @@ -175,6 +214,11 @@ impl SmallIntMap { self.insert(key, new_val) } + /// Insert a key-value pair into the map. If the key already exists, uses the function `ff` + /// to resolve the collision. + /// + /// The arguments to the user-provided function are the original value and the new + /// intended value and its return value is used as the final value that is put into the map. pub fn update(&mut self, key: uint, newval: V, ff: |V, V| -> V) -> bool { self.update_with_key(key, newval, |_k, v, v1| ff(v,v1)) } @@ -233,6 +277,7 @@ macro_rules! double_ended_iterator { } } +/// SmallIntMap iterator pub struct Entries<'a, T> { priv front: uint, priv back: uint, @@ -241,8 +286,10 @@ pub struct Entries<'a, T> { iterator!(impl Entries -> (uint, &'a T), get_ref) double_ended_iterator!(impl Entries -> (uint, &'a T), get_ref) +/// SmallIntMap backwards iterator pub type RevEntries<'a, T> = Rev>; +/// SmallIntMap mutable values iterator pub struct MutEntries<'a, T> { priv front: uint, priv back: uint, @@ -251,6 +298,7 @@ pub struct MutEntries<'a, T> { iterator!(impl MutEntries -> (uint, &'a mut T), get_mut_ref) double_ended_iterator!(impl MutEntries -> (uint, &'a mut T), get_mut_ref) +/// SmallIntMap mutable values backwards iterator pub type RevMutEntries<'a, T> = Rev>; #[cfg(test)] diff --git a/src/libcollections/treemap.rs b/src/libcollections/treemap.rs index 5965417bac71b..83b0b6e196aea 100644 --- a/src/libcollections/treemap.rs +++ b/src/libcollections/treemap.rs @@ -33,7 +33,26 @@ use std::ptr; // * union: | // These would be convenient since the methods work like `each` -#[allow(missing_doc)] +/// An ordered map implementation. +/// +/// # Example +/// +/// ```rust +/// use collections::TreeMap; +/// +/// let mut artists = TreeMap::new::(); +/// +/// // Add some elements to the map. +/// artists.insert(1972, ~"ABBA"); +/// artists.insert(1979, ~"Europe"); +/// artists.insert(1986, ~"Roxette"); +/// artists.insert(1992, ~"The Cardigans"); +/// +/// // Iterate over all values greater than a certain value. +/// for (year, artist) in artists.upper_bound(1980) { +/// println!("{} => {}", year, aritst); +/// } +/// ``` #[deriving(Clone)] pub struct TreeMap { priv root: Option<~TreeNode>, @@ -549,6 +568,33 @@ impl<'a, T> Iterator<&'a T> for RevSetItems<'a, T> { /// A implementation of the `Set` trait on top of the `TreeMap` container. The /// only requirement is that the type of the elements contained ascribes to the /// `TotalOrd` trait. +/// +/// # Example +/// +/// ```rust +/// use collections::TreeSet; +/// +/// let mut vecs = TreeSet::new(); +/// +/// // Add some elements to the set. +/// vecs.insert(vec!(1, 2, 3)); +/// vecs.insert(vec!(4, 5)); +/// vecs.insert(vec!(6, 7, 8, 9)); +/// vecs.insert(vec!(10, 11)); +/// +/// // Remove an element. +/// vecs.remove(vec!(4, 5)); +/// +/// // Intersect with another set. +/// let intersection = vecs.intersection( +/// vec!(vec!(1, 2), vec!(6, 7, 8, 9), vec!(10, 11)).iter().collect() +/// ); +/// +/// // Iterate over all values in the set. +/// for vec in intersection { +/// println!("{:}", vec); +/// } +/// ``` #[deriving(Clone)] pub struct TreeSet { priv map: TreeMap diff --git a/src/libcollections/trie.rs b/src/libcollections/trie.rs index 2232af98eb311..b5f7f9a7c3e64 100644 --- a/src/libcollections/trie.rs +++ b/src/libcollections/trie.rs @@ -28,7 +28,7 @@ enum Child { Nothing } -#[allow(missing_doc)] +/// An ordered map implementation for unsigned integer keys using a radix tree. pub struct TrieMap { priv root: TrieNode, priv length: uint @@ -276,7 +276,7 @@ impl Extendable<(uint, T)> for TrieMap { } } -#[allow(missing_doc)] +/// An ordered set implementation for unsigned integer keys using a radix tree. pub struct TrieSet { priv map: TrieMap<()> }