1# @ohos.util.HashMap (Nonlinear Container HashMap) 2 3**HashMap** is a map implemented based on the array, linked list, and red-black tree. It provides efficient data query, insertion, and removal. The elements in a **HashMap** instance are mappings of key-value pairs. Each key must be unique and have only one value. 4 5**HashMap** is faster in accessing data than **[TreeMap](js-apis-treemap.md)**, because the former accesses the keys based on the hash codes, whereas the latter stores and accesses the keys in sorted order. 6 7**[HashSet](js-apis-hashset.md)** is implemented based on **HashMap**. The input parameter of **HashMap** consists of **key** and **value**. In **HashSet**, only the **value** object is processed. 8 9**Recommended use case**: Use **HashMap** when you need to quickly access, remove, and insert key-value pairs. 10 11This topic uses the following to identify the use of generics: 12- K: Key 13- V: Value 14 15> **NOTE** 16> 17> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 18 19 20## Modules to Import 21 22```ts 23import HashMap from '@ohos.util.HashMap'; 24``` 25 26## HashMap 27 28### Attributes 29 30**System capability**: SystemCapability.Utils.Lang 31 32| Name| Type| Readable| Writable| Description| 33| -------- | -------- | -------- | -------- | -------- | 34| length | number | Yes| No| Number of elements in a hash map (called container later).| 35 36 37### constructor 38 39constructor() 40 41A constructor used to create a **HashMap** instance. 42 43**System capability**: SystemCapability.Utils.Lang 44 45**Error codes** 46 47For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 48 49| ID| Error Message| 50| -------- | -------- | 51| 10200012 | The HashMap's constructor cannot be directly invoked. | 52 53**Example** 54 55```ts 56let hashMap = new HashMap(); 57``` 58 59 60### isEmpty 61 62isEmpty(): boolean 63 64Checks whether this container is empty (contains no element). 65 66**System capability**: SystemCapability.Utils.Lang 67 68**Return value** 69 70| Type| Description| 71| -------- | -------- | 72| boolean | Returns **true** if the container is empty; returns **false** otherwise.| 73 74**Error codes** 75 76For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 77 78| ID| Error Message| 79| -------- | -------- | 80| 10200011 | The isEmpty method cannot be bound. | 81 82**Example** 83 84```ts 85const hashMap = new HashMap(); 86let result = hashMap.isEmpty(); 87``` 88 89 90### hasKey 91 92hasKey(key: K): boolean 93 94Checks whether this container contains the specified key. 95 96**System capability**: SystemCapability.Utils.Lang 97 98**Parameters** 99 100| Name| Type| Mandatory| Description| 101| -------- | -------- | -------- | -------- | 102| key | K | Yes| Target key.| 103 104**Return value** 105 106| Type| Description| 107| -------- | -------- | 108| boolean | Returns **true** if the specified key is contained; returns **false** otherwise.| 109 110**Error codes** 111 112For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 113 114| ID| Error Message| 115| -------- | -------- | 116| 10200011 | The hasKey method cannot be bound. | 117 118**Example** 119 120```ts 121let hashMap = new HashMap(); 122let result = hashMap.hasKey("squirrel"); 123hashMap.set("squirrel", 123); 124let result1 = hashMap.hasKey("squirrel"); 125``` 126 127 128### hasValue 129 130hasValue(value: V): boolean 131 132Checks whether this container contains the specified value. 133 134**System capability**: SystemCapability.Utils.Lang 135 136**Parameters** 137 138| Name| Type| Mandatory| Description| 139| -------- | -------- | -------- | -------- | 140| value | V | Yes| Target value.| 141 142**Return value** 143 144| Type| Description| 145| -------- | -------- | 146| boolean | Returns **true** if the specified value is contained; returns **false** otherwise.| 147 148**Error codes** 149 150For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 151 152| ID| Error Message| 153| -------- | -------- | 154| 10200011 | The hasValue method cannot be bound. | 155 156**Example** 157 158```ts 159let hashMap = new HashMap(); 160let result = hashMap.hasValue(123); 161hashMap.set("squirrel", 123); 162let result1 = hashMap.hasValue(123); 163``` 164 165 166### get 167 168get(key: K): V 169 170Obtains the value of the specified key in this container. 171 172**System capability**: SystemCapability.Utils.Lang 173 174**Parameters** 175 176| Name| Type| Mandatory| Description| 177| -------- | -------- | -------- | -------- | 178| key | K | Yes| Target key.| 179 180**Return value** 181 182| Type| Description| 183| -------- | -------- | 184| V | Value obtained.| 185 186**Error codes** 187 188For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 189 190| ID| Error Message| 191| -------- | -------- | 192| 10200011 | The get method cannot be bound. | 193 194**Example** 195 196```ts 197let hashMap = new HashMap(); 198hashMap.set("squirrel", 123); 199hashMap.set("sparrow", 356); 200let result = hashMap.get("sparrow"); 201``` 202 203 204### setAll 205 206setAll(map: HashMap<K, V>): void 207 208Adds all elements in a **HashMap** instance to this container. 209 210**System capability**: SystemCapability.Utils.Lang 211 212**Parameters** 213 214| Name| Type| Mandatory| Description| 215| -------- | -------- | -------- | -------- | 216| map | HashMap<K, V> | Yes| **HashMap** instance whose elements are to be added to the current container.| 217 218**Error codes** 219 220For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 221 222| ID| Error Message| 223| -------- | -------- | 224| 10200011 | The setAll method cannot be bound. | 225 226**Example** 227 228```ts 229let hashMap = new HashMap(); 230hashMap.set("squirrel", 123); 231hashMap.set("sparrow", 356); 232let newHashMap = new HashMap(); 233hashMap.setAll(newHashMap); 234``` 235 236 237### set 238 239set(key: K, value: V): Object 240 241Adds an element to this container. 242 243**System capability**: SystemCapability.Utils.Lang 244 245**Parameters** 246 247| Name| Type| Mandatory| Description| 248| -------- | -------- | -------- | -------- | 249| key | K | Yes| Key of the target element.| 250| value | V | Yes| Value of the target element.| 251 252**Return value** 253 254| Type| Description| 255| -------- | -------- | 256| Object | Container that contains the new element.| 257 258**Error codes** 259 260For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 261 262| ID| Error Message| 263| -------- | -------- | 264| 10200011 | The set method cannot be bound. | 265 266**Example** 267 268```ts 269let hashMap = new HashMap(); 270let result = hashMap.set("squirrel", 123); 271``` 272 273 274### remove 275 276remove(key: K): V 277 278Removes an element with the specified key from this container. 279 280**System capability**: SystemCapability.Utils.Lang 281 282**Parameters** 283 284| Name| Type| Mandatory| Description| 285| -------- | -------- | -------- | -------- | 286| key | K | Yes| Key of the target element.| 287 288**Return value** 289 290| Type| Description| 291| -------- | -------- | 292| V | Value of the element.| 293 294**Error codes** 295 296For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 297 298| ID| Error Message| 299| -------- | -------- | 300| 10200011 | The remove method cannot be bound. | 301 302**Example** 303 304```ts 305let hashMap = new HashMap(); 306hashMap.set("squirrel", 123); 307hashMap.set("sparrow", 356); 308let result = hashMap.remove("sparrow"); 309``` 310 311 312### clear 313 314clear(): void 315 316Clears this container and sets its length to **0**. 317 318**System capability**: SystemCapability.Utils.Lang 319 320**Error codes** 321 322For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 323 324| ID| Error Message| 325| -------- | -------- | 326| 10200011 | The clear method cannot be bound. | 327 328**Example** 329 330```ts 331let hashMap = new HashMap(); 332hashMap.set("squirrel", 123); 333hashMap.set("sparrow", 356); 334hashMap.clear(); 335``` 336 337 338### keys 339 340keys(): IterableIterator<K> 341 342Obtains an iterator that contains all the elements in this container. 343 344**System capability**: SystemCapability.Utils.Lang 345 346**Return value** 347 348| Type| Description| 349| -------- | -------- | 350| IterableIterator<K> | Iterator obtained.| 351 352**Error codes** 353 354For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 355 356| ID| Error Message| 357| -------- | -------- | 358| 10200011 | The keys method cannot be bound. | 359 360**Example** 361 362```ts 363let hashMap = new HashMap(); 364hashMap.set("squirrel", 123); 365hashMap.set("sparrow", 356); 366let iter = hashMap.keys(); 367let temp = iter.next().value; 368while(temp != undefined) { 369 console.log("value:" + temp); 370 temp = iter.next().value; 371} 372``` 373 374 375### values 376 377values(): IterableIterator<V> 378 379Obtains an iterator that contains all the values in this container. 380 381**System capability**: SystemCapability.Utils.Lang 382 383**Return value** 384 385| Type| Description| 386| -------- | -------- | 387| IterableIterator<V> | Iterator obtained.| 388 389**Error codes** 390 391For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 392 393| ID| Error Message| 394| -------- | -------- | 395| 10200011 | The values method cannot be bound. | 396 397**Example** 398 399```ts 400let hashMap = new HashMap(); 401hashMap.set("squirrel", 123); 402hashMap.set("sparrow", 356); 403let iter = hashMap.values(); 404let temp = iter.next().value; 405while(temp != undefined) { 406 console.log("value:" + temp); 407 temp = iter.next().value; 408} 409``` 410 411 412### replace 413 414replace(key: K, newValue: V): boolean 415 416Replaces an element in this container. 417 418**System capability**: SystemCapability.Utils.Lang 419 420**Parameters** 421 422| Name| Type| Mandatory| Description| 423| -------- | -------- | -------- | -------- | 424| key | K | Yes| Key of the target element.| 425| newValue | V | Yes| New value of the element.| 426 427**Return value** 428 429| Type| Description| 430| -------- | -------- | 431| boolean | Returns **true** if the element is replaced successfully; returns **false** otherwise.| 432 433**Error codes** 434 435For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 436 437| ID| Error Message| 438| -------- | -------- | 439| 10200011 | The replace method cannot be bound. | 440 441**Example** 442 443```ts 444let hashMap = new HashMap(); 445hashMap.set("sparrow", 123); 446let result = hashMap.replace("sparrow", 357); 447``` 448 449 450### forEach 451 452forEach(callbackFn: (value?: V, key?: K, map?: HashMap<K, V>) => void, thisArg?: Object): void 453 454Uses a callback to traverse the elements in this container and obtain their position indexes. 455 456**System capability**: SystemCapability.Utils.Lang 457 458**Parameters** 459 460| Name| Type| Mandatory| Description| 461| -------- | -------- | -------- | -------- | 462| callbackFn | function | Yes| Callback invoked to traverse the elements in the container.| 463| thisArg | Object | No| Value to use when the callback is invoked.| 464 465callbackfn 466| Name| Type| Mandatory| Description| 467| -------- | -------- | -------- | -------- | 468| value | V | No| Value of the element that is currently traversed.| 469| key | K | No| Key of the element that is currently traversed.| 470| map | HashMap<K, V> | No| Instance that invokes the **forEach** method.| 471 472**Error codes** 473 474For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 475 476| ID| Error Message| 477| -------- | -------- | 478| 10200011 | The forEach method cannot be bound. | 479 480**Example** 481 482```ts 483let hashMap = new HashMap(); 484hashMap.set("sparrow", 123); 485hashMap.set("gull", 357); 486hashMap.forEach((value, key) => { 487 console.log("value:" + value, "key:" + key); 488}); 489``` 490 491 492### entries 493 494entries(): IterableIterator<[K, V]> 495 496Obtains an iterator that contains all the elements in this container. 497 498**System capability**: SystemCapability.Utils.Lang 499 500**Return value** 501 502| Type| Description| 503| -------- | -------- | 504| IterableIterator<[K, V]> | Iterator obtained.| 505 506**Error codes** 507 508For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 509 510| ID| Error Message| 511| -------- | -------- | 512| 10200011 | The entries method cannot be bound. | 513 514**Example** 515 516```ts 517let hashMap = new HashMap(); 518hashMap.set("squirrel", 123); 519hashMap.set("sparrow", 356); 520let iter = hashMap.entries(); 521let temp = iter.next().value; 522while(temp != undefined) { 523 console.log("key:" + temp[0]); 524 console.log("value:" + temp[1]); 525 temp = iter.next().value; 526} 527``` 528 529 530### [Symbol.iterator] 531 532[Symbol.iterator]\(): IterableIterator<[K, V]> 533 534Obtains an iterator, each item of which is a JavaScript object. 535 536**System capability**: SystemCapability.Utils.Lang 537 538**Return value** 539 540| Type| Description| 541| -------- | -------- | 542| IterableIterator<[K, V]> | Iterator obtained.| 543 544**Error codes** 545 546For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 547 548| ID| Error Message| 549| -------- | -------- | 550| 10200011 | The Symbol.iterator method cannot be bound. | 551 552**Example** 553```ts 554let hashMap = new HashMap(); 555hashMap.set("squirrel", 123); 556hashMap.set("sparrow", 356); 557 558// Method 1: 559for (let item of hashMap) { 560 console.log("key:" + item[0]); 561 console.log("value:" + item[1]); 562} 563 564// Method 2: 565let iter = hashMap[Symbol.iterator](); 566let temp = iter.next().value; 567while(temp != undefined) { 568 console.log("key:" + temp[0]); 569 console.log("value:" + temp[1]); 570 temp = iter.next().value; 571} 572``` 573