Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

auto merge of #15806 : treeman/rust/std-doc, r=alexcrichton

Used `HashMap` and `HashSet` as the base of most examples. Could change it up with different containers, but I don't think it's a big deal.
  • Loading branch information...
commit 3a37ed4412f571a079e9d365c226af23dfe9d224 2 parents df997e5 + 41729b8
@bors bors authored
View
185 src/libcollections/lib.rs
@@ -73,16 +73,46 @@ mod deque;
/// A trait to represent mutable containers
pub trait Mutable: Collection {
/// Clear the container, removing all values.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// let mut v = vec![1i, 2, 3];
+ /// v.clear();
+ /// assert!(v.is_empty());
+ /// ```
fn clear(&mut self);
}
/// A map is a key-value store where values may be looked up by their keys. This
/// trait provides basic operations to operate on these stores.
pub trait Map<K, V>: Collection {
- /// Return a reference to the value corresponding to the key
+ /// Return a reference to the value corresponding to the key.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashMap;
+ ///
+ /// let mut map = HashMap::new();
+ /// map.insert("a", 1i);
+ /// assert_eq!(map.find(&"a"), Some(&1i));
+ /// assert_eq!(map.find(&"b"), None);
+ /// ```
fn find<'a>(&'a self, key: &K) -> Option<&'a V>;
- /// Return true if the map contains a value for the specified key
+ /// Return true if the map contains a value for the specified key.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashMap;
+ ///
+ /// let mut map = HashMap::new();
+ /// map.insert("a", 1i);
+ /// assert_eq!(map.contains_key(&"a"), true);
+ /// assert_eq!(map.contains_key(&"b"), false);
+ /// ```
#[inline]
fn contains_key(&self, key: &K) -> bool {
self.find(key).is_some()
@@ -94,6 +124,17 @@ pub trait MutableMap<K, V>: Map<K, V> + Mutable {
/// Insert a key-value pair into the map. An existing value for a
/// key is replaced by the new value. Return true if the key did
/// not already exist in the map.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashMap;
+ ///
+ /// let mut map = HashMap::new();
+ /// assert_eq!(map.insert("key", 2i), true);
+ /// assert_eq!(map.insert("key", 9i), false);
+ /// assert_eq!(map.get(&"key"), &9i);
+ /// ```
#[inline]
fn insert(&mut self, key: K, value: V) -> bool {
self.swap(key, value).is_none()
@@ -101,6 +142,17 @@ pub trait MutableMap<K, V>: Map<K, V> + Mutable {
/// Remove a key-value pair from the map. Return true if the key
/// was present in the map, otherwise false.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashMap;
+ ///
+ /// let mut map = HashMap::new();
+ /// assert_eq!(map.remove(&"key"), false);
+ /// map.insert("key", 2i);
+ /// assert_eq!(map.remove(&"key"), true);
+ /// ```
#[inline]
fn remove(&mut self, key: &K) -> bool {
self.pop(key).is_some()
@@ -108,13 +160,52 @@ pub trait MutableMap<K, V>: Map<K, V> + Mutable {
/// Insert a key-value pair from the map. If the key already had a value
/// present in the map, that value is returned. Otherwise None is returned.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashMap;
+ ///
+ /// let mut map = HashMap::new();
+ /// assert_eq!(map.swap("a", 37i), None);
+ /// assert_eq!(map.is_empty(), false);
+ ///
+ /// map.insert("a", 1i);
+ /// assert_eq!(map.swap("a", 37i), Some(1i));
+ /// assert_eq!(map.get(&"a"), &37i);
+ /// ```
fn swap(&mut self, k: K, v: V) -> Option<V>;
/// Removes a key from the map, returning the value at the key if the key
/// was previously in the map.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashMap;
+ ///
+ /// let mut map: HashMap<&str, int> = HashMap::new();
+ /// map.insert("a", 1i);
+ /// assert_eq!(map.pop(&"a"), Some(1i));
+ /// assert_eq!(map.pop(&"a"), None);
+ /// ```
fn pop(&mut self, k: &K) -> Option<V>;
- /// Return a mutable reference to the value corresponding to the key
+ /// Return a mutable reference to the value corresponding to the key.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashMap;
+ ///
+ /// let mut map = HashMap::new();
+ /// map.insert("a", 1i);
+ /// match map.find_mut(&"a") {
+ /// Some(x) => *x = 7i,
+ /// None => (),
+ /// }
+ /// assert_eq!(map.get(&"a"), &7i);
+ /// ```
fn find_mut<'a>(&'a mut self, key: &K) -> Option<&'a mut V>;
}
@@ -122,17 +213,75 @@ pub trait MutableMap<K, V>: Map<K, V> + Mutable {
/// trait represents actions which can be performed on sets to iterate over
/// them.
pub trait Set<T>: Collection {
- /// Return true if the set contains a value
+ /// Return true if the set contains a value.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashSet;
+ ///
+ /// let set: HashSet<int> = [1i, 2, 3].iter().map(|&x| x).collect();
+ /// assert_eq!(set.contains(&1), true);
+ /// assert_eq!(set.contains(&4), false);
+ /// ```
fn contains(&self, value: &T) -> bool;
/// Return true if the set has no elements in common with `other`.
/// This is equivalent to checking for an empty intersection.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashSet;
+ ///
+ /// let a: HashSet<int> = [1i, 2, 3].iter().map(|&x| x).collect();
+ /// let mut b: HashSet<int> = HashSet::new();
+ ///
+ /// assert_eq!(a.is_disjoint(&b), true);
+ /// b.insert(4);
+ /// assert_eq!(a.is_disjoint(&b), true);
+ /// b.insert(1);
+ /// assert_eq!(a.is_disjoint(&b), false);
+ /// ```
fn is_disjoint(&self, other: &Self) -> bool;
- /// Return true if the set is a subset of another
+ /// Return true if the set is a subset of another.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashSet;
+ ///
+ /// let sup: HashSet<int> = [1i, 2, 3].iter().map(|&x| x).collect();
+ /// let mut set: HashSet<int> = HashSet::new();
+ ///
+ /// assert_eq!(set.is_subset(&sup), true);
+ /// set.insert(2);
+ /// assert_eq!(set.is_subset(&sup), true);
+ /// set.insert(4);
+ /// assert_eq!(set.is_subset(&sup), false);
+ /// ```
fn is_subset(&self, other: &Self) -> bool;
- /// Return true if the set is a superset of another
+ /// Return true if the set is a superset of another.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashSet;
+ ///
+ /// let sub: HashSet<int> = [1i, 2].iter().map(|&x| x).collect();
+ /// let mut set: HashSet<int> = HashSet::new();
+ ///
+ /// assert_eq!(set.is_superset(&sub), false);
+ ///
+ /// set.insert(0);
+ /// set.insert(1);
+ /// assert_eq!(set.is_superset(&sub), false);
+ ///
+ /// set.insert(2);
+ /// assert_eq!(set.is_superset(&sub), true);
+ /// ```
fn is_superset(&self, other: &Self) -> bool {
other.is_subset(self)
}
@@ -145,10 +294,34 @@ pub trait Set<T>: Collection {
pub trait MutableSet<T>: Set<T> + Mutable {
/// Add a value to the set. Return true if the value was not already
/// present in the set.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashSet;
+ ///
+ /// let mut set = HashSet::new();
+ ///
+ /// assert_eq!(set.insert(2i), true);
+ /// assert_eq!(set.insert(2i), false);
+ /// assert_eq!(set.len(), 1);
+ /// ```
fn insert(&mut self, value: T) -> bool;
/// Remove a value from the set. Return true if the value was
/// present in the set.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::collections::HashSet;
+ ///
+ /// let mut set = HashSet::new();
+ ///
+ /// set.insert(2i);
+ /// assert_eq!(set.remove(&2), true);
+ /// assert_eq!(set.remove(&2), false);
+ /// ```
fn remove(&mut self, value: &T) -> bool;
}
View
14 src/libcore/collections.rs
@@ -14,9 +14,23 @@
/// knowledge known is the number of elements contained within.
pub trait Collection {
/// Return the number of elements in the container
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// let a = [1i, 2, 3];
+ /// assert_eq!(a.len(), 3);
+ /// ```
fn len(&self) -> uint;
/// Return true if the container contains no elements
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// let s = String::new();
+ /// assert!(s.is_empty());
+ /// ```
#[inline]
fn is_empty(&self) -> bool {
self.len() == 0
View
10 src/libcore/default.rs
@@ -15,6 +15,16 @@
/// A trait that types which have a useful default value should implement.
pub trait Default {
/// Return the "default value" for a type.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::default::Default;
+ ///
+ /// let i: i8 = Default::default();
+ /// let (x, y): (Option<String>, f64) = Default::default();
+ /// let (a, b, (c, d)): (int, uint, (bool, bool)) = Default::default();
+ /// ```
fn default() -> Self;
}
Please sign in to comment.
Something went wrong with that request. Please try again.