OLD | NEW |
| (Empty) |
1 // Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file | |
2 // for details. All rights reserved. Use of this source code is governed by a | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 part of dart.core; | |
6 | |
7 /** | |
8 * An collection of key-value pairs, from which you retrieve a value | |
9 * using its associated key. | |
10 * | |
11 * There is a finite number of keys in the map, | |
12 * and each key has exactly one value associated with it. | |
13 * | |
14 * Maps, and their keys and values, can be iterated. | |
15 * The order of iteration is defined by the individual type of map. | |
16 * Examples: | |
17 * | |
18 * * The plain [HashMap] is unordered (no order is guaranteed), | |
19 * * the [LinkedHashMap] iterates in key insertion order, | |
20 * * and a sorted map like [SplayTreeMap] iterates the keys in sorted order. | |
21 * | |
22 * It is generally not allowed to modify the map (add or remove keys) while | |
23 * an operation is being performed on the map, for example in functions called | |
24 * during a [forEach] or [putIfAbsent] call. | |
25 * Modifying the map while iterating the keys or values | |
26 * may also break the iteration. | |
27 */ | |
28 abstract class Map<K, V> { | |
29 /** | |
30 * Creates a Map instance with the default implementation, [LinkedHashMap]. | |
31 * | |
32 * This constructor is equivalent to the non-const map literal `<K,V>{}`. | |
33 * | |
34 * A `LinkedHashMap` requires the keys to implement compatible | |
35 * `operator==` and `hashCode`, and it allows null as a key. | |
36 * It iterates in key insertion order. | |
37 */ | |
38 external factory Map(); | |
39 | |
40 /** | |
41 * Creates a [LinkedHashMap] instance that contains all key-value pairs of | |
42 * [other]. | |
43 * | |
44 * The keys must all be assignable to [K] and the values to [V]. | |
45 * The [other] map itself can have any type. | |
46 * | |
47 * A `LinkedHashMap` requires the keys to implement compatible | |
48 * `operator==` and `hashCode`, and it allows `null` as a key. | |
49 * It iterates in key insertion order. | |
50 */ | |
51 factory Map.from(Map other) = LinkedHashMap<K, V>.from; | |
52 | |
53 /** | |
54 * Creates an unmodifiable hash based map containing the entries of [other]. | |
55 * | |
56 * The keys must all be assignable to [K] and the values to [V]. | |
57 * The [other] map itself can have any type. | |
58 * | |
59 * The map requires the keys to implement compatible | |
60 * `operator==` and `hashCode`, and it allows `null` as a key. | |
61 * The created map iterates keys in a fixed order, | |
62 * preserving the order provided by [other]. | |
63 * | |
64 * The resulting map behaves like the result of [Map.from], | |
65 * except that the map returned by this constructor is not modifiable. | |
66 */ | |
67 external factory Map.unmodifiable(Map other); | |
68 | |
69 /** | |
70 * Creates an identity map with the default implementation, [LinkedHashMap]. | |
71 * | |
72 * The returned map allows `null` as a key. | |
73 * It iterates in key insertion order. | |
74 */ | |
75 factory Map.identity() = LinkedHashMap<K, V>.identity; | |
76 | |
77 /** | |
78 * Creates a Map instance in which the keys and values are computed from the | |
79 * [iterable]. | |
80 * | |
81 * The created map is a [LinkedHashMap]. | |
82 * A `LinkedHashMap` requires the keys to implement compatible | |
83 * `operator==` and `hashCode`, and it allows null as a key. | |
84 * It iterates in key insertion order. | |
85 * | |
86 * For each element of the [iterable] this constructor computes a key-value | |
87 * pair, by applying [key] and [value] respectively. | |
88 * | |
89 * The example below creates a new Map from a List. The keys of `map` are | |
90 * `list` values converted to strings, and the values of the `map` are the | |
91 * squares of the `list` values: | |
92 * | |
93 * List<int> list = [1, 2, 3]; | |
94 * Map<String, int> map = new Map.fromIterable(list, | |
95 * key: (item) => item.toString(), | |
96 * value: (item) => item * item)); | |
97 * | |
98 * map['1'] + map['2']; // 1 + 4 | |
99 * map['3'] - map['2']; // 9 - 4 | |
100 * | |
101 * If no values are specified for [key] and [value] the default is the | |
102 * identity function. | |
103 * | |
104 * In the following example, the keys and corresponding values of `map` | |
105 * are `list` values: | |
106 * | |
107 * map = new Map.fromIterable(list); | |
108 * map[1] + map[2]; // 1 + 2 | |
109 * map[3] - map[2]; // 3 - 2 | |
110 * | |
111 * The keys computed by the source [iterable] do not need to be unique. The | |
112 * last occurrence of a key will simply overwrite any previous value. | |
113 */ | |
114 factory Map.fromIterable(Iterable iterable, | |
115 {K key(element), V value(element)}) = LinkedHashMap<K, V>.fromIterable; | |
116 | |
117 /** | |
118 * Creates a Map instance associating the given [keys] to [values]. | |
119 * | |
120 * The created map is a [LinkedHashMap]. | |
121 * A `LinkedHashMap` requires the keys to implement compatible | |
122 * `operator==` and `hashCode`, and it allows null as a key. | |
123 * It iterates in key insertion order. | |
124 * | |
125 * This constructor iterates over [keys] and [values] and maps each element of | |
126 * [keys] to the corresponding element of [values]. | |
127 * | |
128 * List<String> letters = ['b', 'c']; | |
129 * List<String> words = ['bad', 'cat']; | |
130 * Map<String, String> map = new Map.fromIterables(letters, words); | |
131 * map['b'] + map['c']; // badcat | |
132 * | |
133 * If [keys] contains the same object multiple times, the last occurrence | |
134 * overwrites the previous value. | |
135 * | |
136 * The two [Iterable]s must have the same length. | |
137 */ | |
138 factory Map.fromIterables(Iterable<K> keys, Iterable<V> values) | |
139 = LinkedHashMap<K, V>.fromIterables; | |
140 | |
141 /** | |
142 * Returns true if this map contains the given [value]. | |
143 * | |
144 * Returns true if any of the values in the map are equal to `value` | |
145 * according to the `==` operator. | |
146 */ | |
147 bool containsValue(Object value); | |
148 | |
149 /** | |
150 * Returns true if this map contains the given [key]. | |
151 * | |
152 * Returns true if any of the keys in the map are equal to `key` | |
153 * according to the equality used by the map. | |
154 */ | |
155 bool containsKey(Object key); | |
156 | |
157 /** | |
158 * Returns the value for the given [key] or null if [key] is not in the map. | |
159 * | |
160 * Some maps allows keys to have `null` as a value, | |
161 * For those maps, a lookup using this operator does cannot be used to | |
162 * distinguish between a key not being in the map, and the key having a null | |
163 * value. | |
164 * Methods like [containsKey] or [putIfAbsent] can be use if the distinction | |
165 * is important. | |
166 */ | |
167 V operator [](Object key); | |
168 | |
169 /** | |
170 * Associates the [key] with the given [value]. | |
171 * | |
172 * If the key was already in the map, its associated value is changed. | |
173 * Otherwise the key-value pair is added to the map. | |
174 */ | |
175 void operator []=(K key, V value); | |
176 | |
177 /** | |
178 * Look up the value of [key], or add a new value if it isn't there. | |
179 * | |
180 * Returns the value associated to [key], if there is one. | |
181 * Otherwise calls [ifAbsent] to get a new value, associates [key] to | |
182 * that value, and then returns the new value. | |
183 * | |
184 * Map<String, int> scores = {'Bob': 36}; | |
185 * for (var key in ['Bob', 'Rohan', 'Sophena']) { | |
186 * scores.putIfAbsent(key, () => key.length); | |
187 * } | |
188 * scores['Bob']; // 36 | |
189 * scores['Rohan']; // 5 | |
190 * scores['Sophena']; // 7 | |
191 * | |
192 * Calling [ifAbsent] must not add or remove keys from the map. | |
193 */ | |
194 V putIfAbsent(K key, V ifAbsent()); | |
195 | |
196 /** | |
197 * Adds all key-value pairs of [other] to this map. | |
198 * | |
199 * If a key of [other] is already in this map, its value is overwritten. | |
200 * | |
201 * The operation is equivalent to doing `this[key] = value` for each key | |
202 * and associated value in other. It iterates over [other], which must | |
203 * therefore not change during the iteration. | |
204 */ | |
205 void addAll(Map<K, V> other); | |
206 | |
207 /** | |
208 * Removes [key] and its associated value, if present, from the map. | |
209 * | |
210 * Returns the value associated with `key` before it was removed. | |
211 * Returns `null` if `key` was not in the map. | |
212 * | |
213 * Note that values can be `null` and a returned `null` value doesn't | |
214 * always mean that the key was absent. | |
215 */ | |
216 V remove(Object key); | |
217 | |
218 /** | |
219 * Removes all pairs from the map. | |
220 * | |
221 * After this, the map is empty. | |
222 */ | |
223 void clear(); | |
224 | |
225 /** | |
226 * Applies [f] to each key-value pair of the map. | |
227 * | |
228 * Calling `f` must not add or remove keys from the map. | |
229 */ | |
230 void forEach(void f(K key, V value)); | |
231 | |
232 /** | |
233 * The keys of [this]. | |
234 * | |
235 * The returned iterable has efficient `length` and `contains` operations, | |
236 * based on [length] and [containsKey] of the map. | |
237 * | |
238 * The order of iteration is defined by the individual `Map` implementation, | |
239 * but must be consistent between changes to the map. | |
240 */ | |
241 Iterable<K> get keys; | |
242 | |
243 /** | |
244 * The values of [this]. | |
245 * | |
246 * The values are iterated in the order of their corresponding keys. | |
247 * This means that iterating [keys] and [values] in parallel will | |
248 * provided matching pairs of keys and values. | |
249 * | |
250 * The returned iterable has an efficient `length` method based on the | |
251 * [length] of the map. Its [Iterable.contains] method is based on | |
252 * `==` comparison. | |
253 */ | |
254 Iterable<V> get values; | |
255 | |
256 /** | |
257 * The number of key-value pairs in the map. | |
258 */ | |
259 int get length; | |
260 | |
261 /** | |
262 * Returns true if there is no key-value pair in the map. | |
263 */ | |
264 bool get isEmpty; | |
265 | |
266 /** | |
267 * Returns true if there is at least one key-value pair in the map. | |
268 */ | |
269 bool get isNotEmpty; | |
270 } | |
OLD | NEW |