| 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 factory Map() = LinkedHashMap<K, V>; | |
| 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 identity map with the default implementation, [LinkedHashMap]. | |
| 55 * | |
| 56 * The returned map allows `null` as a key. | |
| 57 * It iterates in key insertion order. | |
| 58 */ | |
| 59 factory Map.identity() = LinkedHashMap<K, V>.identity; | |
| 60 | |
| 61 /** | |
| 62 * Creates a Map instance in which the keys and values are computed from the | |
| 63 * [iterable]. | |
| 64 * | |
| 65 * The created map is a [LinkedHashMap]. | |
| 66 * A `LinkedHashMap` requires the keys to implement compatible | |
| 67 * `operator==` and `hashCode`, and it allows null as a key. | |
| 68 * It iterates in key insertion order. | |
| 69 * | |
| 70 * For each element of the [iterable] this constructor computes a key-value | |
| 71 * pair, by applying [key] and [value] respectively. | |
| 72 * | |
| 73 * The example below creates a new Map from a List. The keys of `map` are | |
| 74 * `list` values converted to strings, and the values of the `map` are the | |
| 75 * squares of the `list` values: | |
| 76 * | |
| 77 * List<int> list = [1, 2, 3]; | |
| 78 * Map<String, int> map = new Map.fromIterable(list, | |
| 79 * key: (item) => item.toString(), | |
| 80 * value: (item) => item * item)); | |
| 81 * | |
| 82 * map['1'] + map['2']; // 1 + 4 | |
| 83 * map['3'] - map['2']; // 9 - 4 | |
| 84 * | |
| 85 * If no values are specified for [key] and [value] the default is the | |
| 86 * identity function. | |
| 87 * | |
| 88 * In the following example, the keys and corresponding values of `map` | |
| 89 * are `list` values: | |
| 90 * | |
| 91 * map = new Map.fromIterable(list); | |
| 92 * map[1] + map[2]; // 1 + 2 | |
| 93 * map[3] - map[2]; // 3 - 2 | |
| 94 * | |
| 95 * The keys computed by the source [iterable] do not need to be unique. The | |
| 96 * last occurrence of a key will simply overwrite any previous value. | |
| 97 */ | |
| 98 factory Map.fromIterable(Iterable iterable, | |
| 99 {K key(element), V value(element)}) = LinkedHashMap<K, V>.fromIterable; | |
| 100 | |
| 101 /** | |
| 102 * Creates a Map instance associating the given [keys] to [values]. | |
| 103 * | |
| 104 * The created map is a [LinkedHashMap]. | |
| 105 * A `LinkedHashMap` requires the keys to implement compatible | |
| 106 * `operator==` and `hashCode`, and it allows null as a key. | |
| 107 * It iterates in key insertion order. | |
| 108 * | |
| 109 * This constructor iterates over [keys] and [values] and maps each element of | |
| 110 * [keys] to the corresponding element of [values]. | |
| 111 * | |
| 112 * List<String> letters = ['b', 'c']; | |
| 113 * List<String> words = ['bad', 'cat']; | |
| 114 * Map<String, String> map = new Map.fromIterables(letters, words); | |
| 115 * map['b'] + map['c']; // badcat | |
| 116 * | |
| 117 * If [keys] contains the same object multiple times, the last occurrence | |
| 118 * overwrites the previous value. | |
| 119 * | |
| 120 * The two [Iterable]s must have the same length. | |
| 121 */ | |
| 122 factory Map.fromIterables(Iterable<K> keys, Iterable<V> values) | |
| 123 = LinkedHashMap<K, V>.fromIterables; | |
| 124 | |
| 125 /** | |
| 126 * Returns true if this map contains the given [value]. | |
| 127 * | |
| 128 * Returns true if any of the values in the map are equal to `value` | |
| 129 * according to the `==` operator. | |
| 130 */ | |
| 131 bool containsValue(Object value); | |
| 132 | |
| 133 /** | |
| 134 * Returns true if this map contains the given [key]. | |
| 135 * | |
| 136 * Returns true if any of the keys in the map ar equal to `key` | |
| 137 * according to the equality used by the map. | |
| 138 */ | |
| 139 bool containsKey(Object key); | |
| 140 | |
| 141 /** | |
| 142 * Returns the value for the given [key] or null if [key] is not in the map. | |
| 143 * | |
| 144 * Some maps allows keys to have `null` as a value, | |
| 145 * For those maps, a lookup using this operator does cannot be used to | |
| 146 * distinguish between a key not being in the map, and the key having a null | |
| 147 * value. | |
| 148 * Methods like [containsKey] or [putIfAbsent] can be use if the distinction | |
| 149 * is important. | |
| 150 */ | |
| 151 V operator [](Object key); | |
| 152 | |
| 153 /** | |
| 154 * Associates the [key] with the given [value]. | |
| 155 * | |
| 156 * If the key was already in the map, its associated value is changed. | |
| 157 * Otherwise the key-value pair is added to the map. | |
| 158 */ | |
| 159 void operator []=(K key, V value); | |
| 160 | |
| 161 /** | |
| 162 * Look up the value of [key], or add a new value if it isn't there. | |
| 163 * | |
| 164 * Returns the value associated to [key], if there is one. | |
| 165 * Otherwise calls [ifAbsent] to get a new value, associates [key] to | |
| 166 * that value, and then returns the new value. | |
| 167 * | |
| 168 * Map<String, int> scores = {'Bob': 36}; | |
| 169 * for (var key in ['Bob', 'Rohan', 'Sophena']) { | |
| 170 * scores.putIfAbsent(key, () => key.length); | |
| 171 * } | |
| 172 * scores['Bob']; // 36 | |
| 173 * scores['Rohan']; // 5 | |
| 174 * scores['Sophena']; // 7 | |
| 175 * | |
| 176 * Calling [ifAbsent] must not add or remove keys from the map. | |
| 177 */ | |
| 178 V putIfAbsent(K key, V ifAbsent()); | |
| 179 | |
| 180 /** | |
| 181 * Adds all key-value pairs of [other] to this map. | |
| 182 * | |
| 183 * If a key of [other] is already in this map, its value is overwritten. | |
| 184 * | |
| 185 * The operation is equivalent to doing `this[key] = value` for each key | |
| 186 * and associated value in other. It iterates over [other], which must | |
| 187 * therefore not change during the iteration. | |
| 188 */ | |
| 189 void addAll(Map<K, V> other); | |
| 190 | |
| 191 /** | |
| 192 * Removes [key] and its associated value, if present, from the map. | |
| 193 * | |
| 194 * Returns the value associated with `key` before it was removed. | |
| 195 * Returns `null` if `key` was not in the map. | |
| 196 * | |
| 197 * Note that values can be `null` and a returned `null` value doesn't | |
| 198 * always mean that the key was absent. | |
| 199 */ | |
| 200 V remove(Object key); | |
| 201 | |
| 202 /** | |
| 203 * Removes all pairs from the map. | |
| 204 * | |
| 205 * After this, the map is empty. | |
| 206 */ | |
| 207 void clear(); | |
| 208 | |
| 209 /** | |
| 210 * Applies [f] to each key-value pair of the map. | |
| 211 * | |
| 212 * Calling `f` must not add or remove keys from the map. | |
| 213 */ | |
| 214 void forEach(void f(K key, V value)); | |
| 215 | |
| 216 /** | |
| 217 * The keys of [this]. | |
| 218 * | |
| 219 * The returned iterable has efficient `length` and `contains` operations, | |
| 220 * based on [length] and [containsKey] of the map. | |
| 221 * | |
| 222 * The order of iteration is defined by the individual `Map` implementation, | |
| 223 * but must be consistent between changes to the map. | |
| 224 */ | |
| 225 Iterable<K> get keys; | |
| 226 | |
| 227 /** | |
| 228 * The values of [this]. | |
| 229 * | |
| 230 * The values are iterated in the order of their corresponding keys. | |
| 231 * This means that iterating [keys] and [values] in parrallel will | |
| 232 * provided matching pairs of keys and values. | |
| 233 * | |
| 234 * The returned iterable has an efficient `length` method based on the | |
| 235 * [length] of the map. Its [Iterable.contains] method is based on | |
| 236 * `==` comparison. | |
| 237 */ | |
| 238 Iterable<V> get values; | |
| 239 | |
| 240 /** | |
| 241 * The number of key-value pairs in the map. | |
| 242 */ | |
| 243 int get length; | |
| 244 | |
| 245 /** | |
| 246 * Returns true if there is no key-value pair in the map. | |
| 247 */ | |
| 248 bool get isEmpty; | |
| 249 | |
| 250 /** | |
| 251 * Returns true if there is at least one key-value pair in the map. | |
| 252 */ | |
| 253 bool get isNotEmpty; | |
| 254 } | |
| OLD | NEW |