sample/java.util.HashMap.txt

   1 *java.util.HashMap* *HashMap* Hash table based implementation of the Map interfa
   2
   3 public class HashMap
   4   extends    |java.util.AbstractMap|
   5   implements |java.util.Map|
   6              |java.lang.Cloneable|
   7              |java.io.Serializable|
   8
   9 |java.util.HashMap_Description|
  10 |java.util.HashMap_Fields|
  11 |java.util.HashMap_Constructors|
  12 |java.util.HashMap_Methods|
  13
  14 ================================================================================
  15
  16 *java.util.HashMap_Constructors*
  17 |java.util.HashMap()|Constructs an empty HashMap with the default initial capac
  18 |java.util.HashMap(int)|Constructs an empty HashMap with the specified initial
  19 |java.util.HashMap(int,float)|Constructs an empty HashMap with the specified in
  20 |java.util.HashMap(Map)|Constructs a new HashMap with the same mappings as the
  21
  22 *java.util.HashMap_Methods*
  23 |java.util.HashMap.clear()|Removes all mappings from this map.
  24 |java.util.HashMap.clone()|Returns a shallow copy of this HashMap instance: the
  25 |java.util.HashMap.containsKey(Object)|Returns true if this map contains a mapp
  26 |java.util.HashMap.containsValue(Object)|Returns true if this map maps one or m
  27 |java.util.HashMap.entrySet()|Returns a collection view of the mappings contain
  28 |java.util.HashMap.get(Object)|Returns the value to which the specified key is
  29 |java.util.HashMap.isEmpty()|Returns true if this map contains no key-value map
  30 |java.util.HashMap.keySet()|Returns a set view of the keys contained in this ma
  31 |java.util.HashMap.put(K,V)|Associates the specified value with the specified k
  32 |java.util.HashMap.putAll(Map)|Copies all of the mappings from the specified ma
  33 |java.util.HashMap.remove(Object)|Removes the mapping for this key from this ma
  34 |java.util.HashMap.size()|Returns the number of key-value mappings in this map.
  35 |java.util.HashMap.values()|Returns a collection view of the values contained i
  36
  37 *java.util.HashMap_Description*
  38
  39 Hash table based implementation of the Map interface. This implementation
  40 provides all of the optional map operations, and permits null values and the
  41 null key. (The HashMap class is roughly equivalent to Hashtable, except that it
  42 is unsynchronized and permits nulls.) This class makes no guarantees as to the
  43 order of the map; in particular, it does not guarantee that the order will
  44 remain constant over time.
  45
  46 This implementation provides constant-time performance for the basic operations
  47 (get and put), assuming the hash function disperses the elements properly among
  48 the buckets. Iteration over collection views requires time proportional to the
  49 "capacity" of the HashMap instance (the number of buckets) plus its size (the
  50 number of key-value mappings). Thus, it's very important not to set the initial
  51 capacity too high (or the load factor too low) if iteration performance is
  52 important.
  53
  54 An instance of HashMap has two parameters that affect its performance: initial
  55 capacity and load factor. The capacity is the number of buckets in the hash
  56 table, and the initial capacity is simply the capacity at the time the hash
  57 table is created. The load factor is a measure of how full the hash table is
  58 allowed to get before its capacity is automatically increased. When the number
  59 of entries in the hash table exceeds the product of the load factor and the
  60 current capacity, the capacity is roughly doubled by calling the rehash method.
  61
  62 As a general rule, the default load factor (.75) offers a good tradeoff between
  63 time and space costs. Higher values decrease the space overhead but increase
  64 the lookup cost (reflected in most of the operations of the HashMap class,
  65 including get and put). The expected number of entries in the map and its load
  66 factor should be taken into account when setting its initial capacity, so as to
  67 minimize the number of rehash operations. If the initial capacity is greater
  68 than the maximum number of entries divided by the load factor, no rehash
  69 operations will ever occur.
  70
  71 If many mappings are to be stored in a HashMap instance, creating it with a
  72 sufficiently large capacity will allow the mappings to be stored more
  73 efficiently than letting it perform automatic rehashing as needed to grow the
  74 table.
  75
  76 Note that this implementation is not synchronized. If multiple threads access
  77 this map concurrently, and at least one of the threads modifies the map
  78 structurally, it must be synchronized externally. (A structural modification is
  79 any operation that adds or deletes one or more mappings; merely changing the
  80 value associated with a key that an instance already contains is not a
  81 structural modification.) This is typically accomplished by synchronizing on
  82 some object that naturally encapsulates the map. If no such object exists, the
  83 map should be "wrapped" using the Collections.synchronizedMap method. This is
  84 best done at creation time, to prevent accidental unsynchronized access to the
  85 map: Map m = Collections.synchronizedMap(new HashMap(...));
  86
  87 The iterators returned by all of this class's "collection view methods" are
  88 fail-fast: if the map is structurally modified at any time after the iterator
  89 is created, in any way except through the iterator's own remove or add methods,
  90 the iterator will throw a ConcurrentModificationException. Thus, in the face of
  91 concurrent modification, the iterator fails quickly and cleanly, rather than
  92 risking arbitrary, non-deterministic behavior at an undetermined time in the
  93 future.
  94
  95 Note that the fail-fast behavior of an iterator cannot be guaranteed as it is,
  96 generally speaking, impossible to make any hard guarantees in the presence of
  97 unsynchronized concurrent modification. Fail-fast iterators throw
  98 ConcurrentModificationException on a best-effort basis. Therefore, it would be
  99 wrong to write a program that depended on this exception for its correctness:
 100 the fail-fast behavior of iterators should be used only to detect bugs.
 101
 102 This class is a member of the <a href="/../guide/collections/index.html"> Java
 103 Collections Framework.
 104
 105
 106 *java.util.HashMap()*
 107
 108 public HashMap()
 109
 110 Constructs an empty HashMap with the default initial capacity (16) and the
 111 default load factor (0.75).
 112
 113
 114 *java.util.HashMap(int)*
 115
 116 public HashMap(int initialCapacity)
 117
 118 Constructs an empty HashMap with the specified initial capacity and the default
 119 load factor (0.75).
 120
 121     initialCapacity - the initial capacity.
 122
 123 *java.util.HashMap(int,float)*
 124
 125 public HashMap(
 126   int initialCapacity,
 127   float loadFactor)
 128
 129 Constructs an empty HashMap with the specified initial capacity and load
 130 factor.
 131
 132     initialCapacity - The initial capacity.
 133     loadFactor - The load factor.
 134
 135 *java.util.HashMap(Map)*
 136
 137 public HashMap(java.util.Map m)
 138
 139 Constructs a new HashMap with the same mappings as the specified Map. The
 140 HashMap is created with default load factor (0.75) and an initial capacity
 141 sufficient to hold the mappings in the specified Map.
 142
 143     m - the map whose mappings are to be placed in this map.
 144
 145 *java.util.HashMap.clear()*
 146
 147 public void clear()
 148
 149 Removes all mappings from this map.
 150
 151
 152 *java.util.HashMap.clone()*
 153
 154 public |java.lang.Object| clone()
 155
 156 Returns a shallow copy of this HashMap instance: the keys and values themselves
 157 are not cloned.
 158
 159
 160     Returns: a shallow copy of this map.
 161 *java.util.HashMap.containsKey(Object)*
 162
 163 public boolean containsKey(java.lang.Object key)
 164
 165 Returns true if this map contains a mapping for the specified key.
 166
 167     key - The key whose presence in this map is to be tested
 168
 169     Returns: true if this map contains a mapping for the specified key.
 170 *java.util.HashMap.containsValue(Object)*
 171
 172 public boolean containsValue(java.lang.Object value)
 173
 174 Returns true if this map maps one or more keys to the specified value.
 175
 176     value - value whose presence in this map is to be tested.
 177
 178     Returns: true if this map maps one or more keys to the specified value.
 179 *java.util.HashMap.entrySet()*
 180
 181 public |java.util.Set| entrySet()
 182
 183 Returns a collection view of the mappings contained in this map. Each element
 184 in the returned collection is a Map.Entry. The collection is backed by the map,
 185 so changes to the map are reflected in the collection, and vice-versa. The
 186 collection supports element removal, which removes the corresponding mapping
 187 from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll,
 188 and clear operations. It does not support the add or addAll operations.
 189
 190
 191     Returns: a collection view of the mappings contained in this map.
 192 *java.util.HashMap.get(Object)*
 193
 194 public |java.lang.Object| get(java.lang.Object key)
 195
 196 Returns the value to which the specified key is mapped in this identity hash
 197 map, or null if the map contains no mapping for this key. A return value of
 198 null does not necessarily indicate that the map contains no mapping for the
 199 key; it is also possible that the map explicitly maps the key to null. The
 200 containsKey method may be used to distinguish these two cases.
 201
 202     key - the key whose associated value is to be returned.
 203
 204     Returns: the value to which this map maps the specified key, or null if the map contains
 205              no mapping for this key.
 206 *java.util.HashMap.isEmpty()*
 207
 208 public boolean isEmpty()
 209
 210 Returns true if this map contains no key-value mappings.
 211
 212
 213     Returns: true if this map contains no key-value mappings.
 214 *java.util.HashMap.keySet()*
 215
 216 public |java.util.Set| keySet()
 217
 218 Returns a set view of the keys contained in this map. The set is backed by the
 219 map, so changes to the map are reflected in the set, and vice-versa. The set
 220 supports element removal, which removes the corresponding mapping from this
 221 map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear
 222 operations. It does not support the add or addAll operations.
 223
 224
 225     Returns: a set view of the keys contained in this map.
 226 *java.util.HashMap.put(K,V)*
 227
 228 public |java.lang.Object| put(
 229   java.lang.Object key,
 230   java.lang.Object value)
 231
 232 Associates the specified value with the specified key in this map. If the map
 233 previously contained a mapping for this key, the old value is replaced.
 234
 235     key - key with which the specified value is to be associated.
 236     value - value to be associated with the specified key.
 237
 238     Returns: previous value associated with specified key, or null if there was no mapping
 239              for key. A null return can also indicate that the HashMap
 240              previously associated null with the specified key.
 241 *java.util.HashMap.putAll(Map)*
 242
 243 public void putAll(java.util.Map m)
 244
 245 Copies all of the mappings from the specified map to this map These mappings
 246 will replace any mappings that this map had for any of the keys currently in
 247 the specified map.
 248
 249     m - mappings to be stored in this map.
 250
 251 *java.util.HashMap.remove(Object)*
 252
 253 public |java.lang.Object| remove(java.lang.Object key)
 254
 255 Removes the mapping for this key from this map if present.
 256
 257     key - key whose mapping is to be removed from the map.
 258
 259     Returns: previous value associated with specified key, or null if there was no mapping
 260              for key. A null return can also indicate that the map previously
 261              associated null with the specified key.
 262 *java.util.HashMap.size()*
 263
 264 public int size()
 265
 266 Returns the number of key-value mappings in this map.
 267
 268
 269     Returns: the number of key-value mappings in this map.
 270 *java.util.HashMap.values()*
 271
 272 public |java.util.Collection| values()
 273
 274 Returns a collection view of the values contained in this map. The collection
 275 is backed by the map, so changes to the map are reflected in the collection,
 276 and vice-versa. The collection supports element removal, which removes the
 277 corresponding mapping from this map, via the Iterator.remove,
 278 Collection.remove, removeAll, retainAll, and clear operations. It does not
 279 support the add or addAll operations.
 280
 281
 282     Returns: a collection view of the values contained in this map.
 283