OLD | NEW |
1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 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. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 part of dart.collection; | 5 part of dart.collection; |
6 | 6 |
7 /** Default function for equality comparison in customized HashMaps */ | 7 /** Default function for equality comparison in customized HashMaps */ |
8 bool _defaultEquals(a, b) => a == b; | 8 bool _defaultEquals(a, b) => a == b; |
9 /** Default function for hash-code computation in customized HashMaps */ | 9 /** Default function for hash-code computation in customized HashMaps */ |
10 int _defaultHashCode(a) => a.hashCode; | 10 int _defaultHashCode(a) => a.hashCode; |
11 | 11 |
12 /** Type of custom equality function */ | 12 /** Type of custom equality function */ |
13 typedef bool _Equality<K>(K a, K b); | 13 typedef bool _Equality<K>(K a, K b); |
14 /** Type of custom hash code function. */ | 14 /** Type of custom hash code function. */ |
15 typedef int _Hasher<K>(K object); | 15 typedef int _Hasher<K>(K object); |
16 | 16 |
17 /** | 17 /** |
18 * A hash-table based implementation of [Map]. | 18 * A hash-table based implementation of [Map]. |
19 * | 19 * |
20 * The keys of a `HashMap` must have consistent [Object.operator==] | 20 * The keys of a `HashMap` must have consistent [Object.==] |
21 * and [Object.hashCode] implementations. This means that the `==` operator | 21 * and [Object.hashCode] implementations. This means that the `==` operator |
22 * must define a stable equivalence relation on the keys (reflexive, | 22 * must define a stable equivalence relation on the keys (reflexive, |
23 * symmetric, transitive, and consistent over time), and that `hashCode` | 23 * symmetric, transitive, and consistent over time), and that `hashCode` |
24 * must be the same for objects that are considered equal by `==`. | 24 * must be the same for objects that are considered equal by `==`. |
25 * | 25 * |
26 * The map allows `null` as a key. | 26 * The map allows `null` as a key. |
27 * | 27 * |
28 * Iterating the map's keys, values or entries (through [forEach]) | 28 * Iterating the map's keys, values or entries (through [forEach]) |
29 * may happen in any order. | 29 * may happen in any order. |
30 * The iteration order only changes when the map is modified. | 30 * The iteration order only changes when the map is modified. |
31 * Values are iterated in the same order as their associated keys, | 31 * Values are iterated in the same order as their associated keys, |
32 * so iterating the [keys] and [values] in parallel | 32 * so iterating the [keys] and [values] in parallel |
33 * will give matching key and value pairs. | 33 * will give matching key and value pairs. |
34 */ | 34 */ |
35 abstract class HashMap<K, V> implements Map<K, V> { | 35 abstract class HashMap<K, V> implements Map<K, V> { |
36 /** | 36 /** |
37 * Creates an unordered hash-table based [Map]. | 37 * Creates an unordered hash-table based [Map]. |
38 * | 38 * |
39 * The created map is not ordered in any way. When iterating the keys or | 39 * The created map is not ordered in any way. When iterating the keys or |
40 * values, the iteration order is unspecified except that it will stay the | 40 * values, the iteration order is unspecified except that it will stay the |
41 * same as long as the map isn't changed. | 41 * same as long as the map isn't changed. |
42 * | 42 * |
43 * If [equals] is provided, it is used to compare the keys in the table with | 43 * If [equals] is provided, it is used to compare the keys in the table with |
44 * new keys. If [equals] is omitted, the key's own [Object.operator==] is used | 44 * new keys. If [equals] is omitted, the key's own [Object.==] is used |
45 * instead. | 45 * instead. |
46 * | 46 * |
47 * Similar, if [hashCode] is provided, it is used to produce a hash value | 47 * Similar, if [hashCode] is provided, it is used to produce a hash value |
48 * for keys in order to place them in the hash table. If it is omitted, the | 48 * for keys in order to place them in the hash table. If it is omitted, the |
49 * key's own [Object.hashCode] is used. | 49 * key's own [Object.hashCode] is used. |
50 * | 50 * |
51 * If using methods like [operator[]], [remove] and [containsKey] together | 51 * If using methods like [[]], [remove] and [containsKey] together |
52 * with a custom equality and hashcode, an extra `isValidKey` function | 52 * with a custom equality and hashcode, an extra `isValidKey` function |
53 * can be supplied. This function is called before calling [equals] or | 53 * can be supplied. This function is called before calling [equals] or |
54 * [hashCode] with an argument that may not be a [K] instance, and if the | 54 * [hashCode] with an argument that may not be a [K] instance, and if the |
55 * call returns false, the key is assumed to not be in the set. | 55 * call returns false, the key is assumed to not be in the set. |
56 * The [isValidKey] function defaults to just testing if the object is a | 56 * The [isValidKey] function defaults to just testing if the object is a |
57 * [K] instance. | 57 * [K] instance. |
58 * | 58 * |
59 * Example: | 59 * Example: |
60 * | 60 * |
61 * new HashMap<int,int>(equals: (int a, int b) => (b - a) % 5 == 0, | 61 * new HashMap<int,int>(equals: (int a, int b) => (b - a) % 5 == 0, |
(...skipping 74 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
136 * overwrites the previous value. | 136 * overwrites the previous value. |
137 * | 137 * |
138 * It is an error if the two [Iterable]s don't have the same length. | 138 * It is an error if the two [Iterable]s don't have the same length. |
139 */ | 139 */ |
140 factory HashMap.fromIterables(Iterable<K> keys, Iterable<V> values) { | 140 factory HashMap.fromIterables(Iterable<K> keys, Iterable<V> values) { |
141 HashMap<K, V> map = new HashMap<K, V>(); | 141 HashMap<K, V> map = new HashMap<K, V>(); |
142 Maps._fillMapWithIterables(map, keys, values); | 142 Maps._fillMapWithIterables(map, keys, values); |
143 return map; | 143 return map; |
144 } | 144 } |
145 } | 145 } |
OLD | NEW |