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 /** | 7 /** |
8 * A hash-table based implementation of [Map]. | 8 * A hash-table based implementation of [Map]. |
9 * | 9 * |
10 * The insertion order of keys is remembered, | 10 * The insertion order of keys is remembered, |
11 * and keys are iterated in the order they were inserted into the map. | 11 * and keys are iterated in the order they were inserted into the map. |
12 * Values are iterated in their corresponding key's order. | 12 * Values are iterated in their corresponding key's order. |
13 * Changing a key's value, when the key is already in the map, | 13 * Changing a key's value, when the key is already in the map, |
14 * does not change the iteration order, | 14 * does not change the iteration order, |
15 * but removing the key and adding it again | 15 * but removing the key and adding it again |
16 * will make it be last in the iteration order. | 16 * will make it be last in the iteration order. |
17 * | 17 * |
18 * The keys of a `LinkedHashMap` must have consistent [Object.operator==] | 18 * The keys of a `LinkedHashMap` must have consistent [Object.==] |
19 * and [Object.hashCode] implementations. This means that the `==` operator | 19 * and [Object.hashCode] implementations. This means that the `==` operator |
20 * must define a stable equivalence relation on the keys (reflexive, | 20 * must define a stable equivalence relation on the keys (reflexive, |
21 * symmetric, transitive, and consistent over time), and that `hashCode` | 21 * symmetric, transitive, and consistent over time), and that `hashCode` |
22 * must be the same for objects that are considered equal by `==`. | 22 * must be the same for objects that are considered equal by `==`. |
23 * | 23 * |
24 * The map allows `null` as a key. | 24 * The map allows `null` as a key. |
25 */ | 25 */ |
26 abstract class LinkedHashMap<K, V> implements HashMap<K, V> { | 26 abstract class LinkedHashMap<K, V> implements HashMap<K, V> { |
27 /** | 27 /** |
28 * Creates an insertion-ordered hash-table based [Map]. | 28 * Creates an insertion-ordered hash-table based [Map]. |
29 * | 29 * |
30 * If [equals] is provided, it is used to compare the keys in the table with | 30 * If [equals] is provided, it is used to compare the keys in the table with |
31 * new keys. If [equals] is omitted, the key's own [Object.operator==] is used | 31 * new keys. If [equals] is omitted, the key's own [Object.==] is used |
32 * instead. | 32 * instead. |
33 * | 33 * |
34 * Similar, if [hashCode] is provided, it is used to produce a hash value | 34 * Similar, if [hashCode] is provided, it is used to produce a hash value |
35 * for keys in order to place them in the hash table. If it is omitted, the | 35 * for keys in order to place them in the hash table. If it is omitted, the |
36 * key's own [Object.hashCode] is used. | 36 * key's own [Object.hashCode] is used. |
37 * | 37 * |
38 * If using methods like [operator[]], [remove] and [containsKey] together | 38 * If using methods like [[]], [remove] and [containsKey] together |
39 * with a custom equality and hashcode, an extra `isValidKey` function | 39 * with a custom equality and hashcode, an extra `isValidKey` function |
40 * can be supplied. This function is called before calling [equals] or | 40 * can be supplied. This function is called before calling [equals] or |
41 * [hashCode] with an argument that may not be a [K] instance, and if the | 41 * [hashCode] with an argument that may not be a [K] instance, and if the |
42 * call returns false, the key is assumed to not be in the set. | 42 * call returns false, the key is assumed to not be in the set. |
43 * The [isValidKey] function defaults to just testing if the object is a | 43 * The [isValidKey] function defaults to just testing if the object is a |
44 * [K] instance. | 44 * [K] instance. |
45 * | 45 * |
46 * Example: | 46 * Example: |
47 * | 47 * |
48 * new LinkedHashMap<int,int>(equals: (int a, int b) => (b - a) % 5 == 0, | 48 * new LinkedHashMap<int,int>(equals: (int a, int b) => (b - a) % 5 == 0, |
(...skipping 74 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
123 * overwrites the previous value. | 123 * overwrites the previous value. |
124 * | 124 * |
125 * It is an error if the two [Iterable]s don't have the same length. | 125 * It is an error if the two [Iterable]s don't have the same length. |
126 */ | 126 */ |
127 factory LinkedHashMap.fromIterables(Iterable<K> keys, Iterable<V> values) { | 127 factory LinkedHashMap.fromIterables(Iterable<K> keys, Iterable<V> values) { |
128 LinkedHashMap<K, V> map = new LinkedHashMap<K, V>(); | 128 LinkedHashMap<K, V> map = new LinkedHashMap<K, V>(); |
129 Maps._fillMapWithIterables(map, keys, values); | 129 Maps._fillMapWithIterables(map, keys, values); |
130 return map; | 130 return map; |
131 } | 131 } |
132 } | 132 } |
OLD | NEW |