(index<- ) ./libcore/container.rs
git branch: * master 5200215 auto merge of #14035 : alexcrichton/rust/experimental, r=huonw
modified: Fri May 9 13:02:28 2014
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10
11 //! Traits for generic containers (including `Map` and `Set`)
12
13 use option::Option;
14
15 /// A trait to represent the abstract idea of a container. The only concrete
16 /// knowledge known is the number of elements contained within.
17 pub trait Container {
18 /// Return the number of elements in the container
19 fn len(&self) -> uint;
20
21 /// Return true if the container contains no elements
22 #[inline]
23 fn is_empty(&self) -> bool {
24 self.len() == 0
25 }
26 }
27
28 /// A trait to represent mutable containers
29 pub trait Mutable: Container {
30 /// Clear the container, removing all values.
31 fn clear(&mut self);
32 }
33
34 /// A map is a key-value store where values may be looked up by their keys. This
35 /// trait provides basic operations to operate on these stores.
36 pub trait Map<K, V>: Container {
37 /// Return a reference to the value corresponding to the key
38 fn find<'a>(&'a self, key: &K) -> Option<&'a V>;
39
40 /// Return true if the map contains a value for the specified key
41 #[inline]
42 fn contains_key(&self, key: &K) -> bool {
43 self.find(key).is_some()
44 }
45 }
46
47 /// This trait provides basic operations to modify the contents of a map.
48 pub trait MutableMap<K, V>: Map<K, V> + Mutable {
49 /// Insert a key-value pair into the map. An existing value for a
50 /// key is replaced by the new value. Return true if the key did
51 /// not already exist in the map.
52 #[inline]
53 fn insert(&mut self, key: K, value: V) -> bool {
54 self.swap(key, value).is_none()
55 }
56
57 /// Remove a key-value pair from the map. Return true if the key
58 /// was present in the map, otherwise false.
59 #[inline]
60 fn remove(&mut self, key: &K) -> bool {
61 self.pop(key).is_some()
62 }
63
64 /// Insert a key-value pair from the map. If the key already had a value
65 /// present in the map, that value is returned. Otherwise None is returned.
66 fn swap(&mut self, k: K, v: V) -> Option<V>;
67
68 /// Removes a key from the map, returning the value at the key if the key
69 /// was previously in the map.
70 fn pop(&mut self, k: &K) -> Option<V>;
71
72 /// Return a mutable reference to the value corresponding to the key
73 fn find_mut<'a>(&'a mut self, key: &K) -> Option<&'a mut V>;
74 }
75
76 /// A set is a group of objects which are each distinct from one another. This
77 /// trait represents actions which can be performed on sets to iterate over
78 /// them.
79 pub trait Set<T>: Container {
80 /// Return true if the set contains a value
81 fn contains(&self, value: &T) -> bool;
82
83 /// Return true if the set has no elements in common with `other`.
84 /// This is equivalent to checking for an empty intersection.
85 fn is_disjoint(&self, other: &Self) -> bool;
86
87 /// Return true if the set is a subset of another
88 fn is_subset(&self, other: &Self) -> bool;
89
90 /// Return true if the set is a superset of another
91 fn is_superset(&self, other: &Self) -> bool {
92 other.is_subset(self)
93 }
94
95 // FIXME #8154: Add difference, sym. difference, intersection and union iterators
96 }
97
98 /// This trait represents actions which can be performed on sets to mutate
99 /// them.
100 pub trait MutableSet<T>: Set<T> + Mutable {
101 /// Add a value to the set. Return true if the value was not already
102 /// present in the set.
103 fn insert(&mut self, value: T) -> bool;
104
105 /// Remove a value from the set. Return true if the value was
106 /// present in the set.
107 fn remove(&mut self, value: &T) -> bool;
108 }