Skip to content

Document some trait methods. #15806

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 20, 2014
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 179 additions & 6 deletions src/libcollections/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand All @@ -94,45 +124,164 @@ 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()
}

/// 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()
}

/// 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>;
}

/// A set is a group of objects which are each distinct from one another. This
/// 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)
}
Expand All @@ -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;
}

Expand Down
14 changes: 14 additions & 0 deletions src/libcore/collections.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 10 additions & 0 deletions src/libcore/default.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String>, f64) = Default::default();
/// let (a, b, (c, d)): (int, uint, (bool, bool)) = Default::default();
/// ```
fn default() -> Self;
}

Expand Down