From 41729b83bc3bf93cfb9cf727b64f5c3a2b35cefe Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Sat, 19 Jul 2014 12:10:09 +0200 Subject: [PATCH] Document some trait methods. --- src/libcollections/lib.rs | 185 +++++++++++++++++++++++++++++++++++-- src/libcore/collections.rs | 14 +++ src/libcore/default.rs | 10 ++ 3 files changed, 203 insertions(+), 6 deletions(-) diff --git a/src/libcollections/lib.rs b/src/libcollections/lib.rs index 06ec2588ac3..d3c0c8856bd 100644 --- a/src/libcollections/lib.rs +++ b/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: 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: Map + 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: Map + 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: Map + 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; /// 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; - /// 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: Map + Mutable { /// trait represents actions which can be performed on sets to iterate over /// them. pub trait Set: 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 = [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 = [1i, 2, 3].iter().map(|&x| x).collect(); + /// let mut b: HashSet = 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 = [1i, 2, 3].iter().map(|&x| x).collect(); + /// let mut set: HashSet = 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 = [1i, 2].iter().map(|&x| x).collect(); + /// let mut set: HashSet = 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: Collection { pub trait MutableSet: Set + 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; } diff --git a/src/libcore/collections.rs b/src/libcore/collections.rs index 0bb9289397a..7d87e03c134 100644 --- a/src/libcore/collections.rs +++ b/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 diff --git a/src/libcore/default.rs b/src/libcore/default.rs index 0fcc02aae0d..363d8ecf002 100644 --- a/src/libcore/default.rs +++ b/src/libcore/default.rs @@ -13,6 +13,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, f64) = Default::default(); + /// let (a, b, (c, d)): (int, uint, (bool, bool)) = Default::default(); + /// ``` fn default() -> Self; }