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(); 122hashMap.set("squirrel", 123); 123let result = hashMap.hasKey("squirrel"); 124``` 125 126 127### hasValue 128 129hasValue(value: V): boolean 130 131Checks whether this container contains the specified value. 132 133**System capability**: SystemCapability.Utils.Lang 134 135**Parameters** 136 137| Name| Type| Mandatory| Description| 138| -------- | -------- | -------- | -------- | 139| value | V | Yes| Target value.| 140 141**Return value** 142 143| Type| Description| 144| -------- | -------- | 145| boolean | Returns **true** if the specified value is contained; returns **false** otherwise.| 146 147**Error codes** 148 149For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 150 151| ID| Error Message| 152| -------- | -------- | 153| 10200011 | The hasValue method cannot be bound. | 154 155**Example** 156 157```ts 158let hashMap = new HashMap(); 159hashMap.set("squirrel", 123); 160let result = hashMap.hasValue(123); 161``` 162 163 164### get 165 166get(key: K): V 167 168Obtains the value of the specified key in this container. 169 170**System capability**: SystemCapability.Utils.Lang 171 172**Parameters** 173 174| Name| Type| Mandatory| Description| 175| -------- | -------- | -------- | -------- | 176| key | K | Yes| Target key.| 177 178**Return value** 179 180| Type| Description| 181| -------- | -------- | 182| V | Value obtained.| 183 184**Error codes** 185 186For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 187 188| ID| Error Message| 189| -------- | -------- | 190| 10200011 | The get method cannot be bound. | 191 192**Example** 193 194```ts 195let hashMap = new HashMap(); 196hashMap.set("squirrel", 123); 197hashMap.set("sparrow", 356); 198let result = hashMap.get("sparrow"); 199``` 200 201 202### setAll 203 204setAll(map: HashMap<K, V>): void 205 206Adds all elements in a **HashMap** instance to this container. 207 208**System capability**: SystemCapability.Utils.Lang 209 210**Parameters** 211 212| Name| Type| Mandatory| Description| 213| -------- | -------- | -------- | -------- | 214| map | HashMap<K, V> | Yes| **HashMap** instance whose elements are to be added to the current container.| 215 216**Error codes** 217 218For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 219 220| ID| Error Message| 221| -------- | -------- | 222| 10200011 | The setAll method cannot be bound. | 223 224**Example** 225 226```ts 227let hashMap = new HashMap(); 228hashMap.set("squirrel", 123); 229hashMap.set("sparrow", 356); 230let newHashMap = new HashMap(); 231newHashMap.set("newMap", 99); 232hashMap.setAll(newHashMap); 233``` 234 235 236### set 237 238set(key: K, value: V): Object 239 240Adds an element to this container. 241 242**System capability**: SystemCapability.Utils.Lang 243 244**Parameters** 245 246| Name| Type| Mandatory| Description| 247| -------- | -------- | -------- | -------- | 248| key | K | Yes| Key of the target element.| 249| value | V | Yes| Value of the target element.| 250 251**Return value** 252 253| Type| Description| 254| -------- | -------- | 255| Object | Container that contains the new element.| 256 257**Error codes** 258 259For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 260 261| ID| Error Message| 262| -------- | -------- | 263| 10200011 | The set method cannot be bound. | 264 265**Example** 266 267```ts 268let hashMap = new HashMap(); 269let result = hashMap.set("squirrel", 123); 270``` 271 272 273### remove 274 275remove(key: K): V 276 277Removes an element with the specified key from this container. 278 279**System capability**: SystemCapability.Utils.Lang 280 281**Parameters** 282 283| Name| Type| Mandatory| Description| 284| -------- | -------- | -------- | -------- | 285| key | K | Yes| Key of the target element.| 286 287**Return value** 288 289| Type| Description| 290| -------- | -------- | 291| V | Value of the element.| 292 293**Error codes** 294 295For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 296 297| ID| Error Message| 298| -------- | -------- | 299| 10200011 | The remove method cannot be bound. | 300 301**Example** 302 303```ts 304let hashMap = new HashMap(); 305hashMap.set("squirrel", 123); 306hashMap.set("sparrow", 356); 307let result = hashMap.remove("sparrow"); 308``` 309 310 311### clear 312 313clear(): void 314 315Clears this container and sets its length to **0**. 316 317**System capability**: SystemCapability.Utils.Lang 318 319**Error codes** 320 321For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 322 323| ID| Error Message| 324| -------- | -------- | 325| 10200011 | The clear method cannot be bound. | 326 327**Example** 328 329```ts 330let hashMap = new HashMap(); 331hashMap.set("squirrel", 123); 332hashMap.set("sparrow", 356); 333hashMap.clear(); 334``` 335 336 337### keys 338 339keys(): IterableIterator<K> 340 341Obtains an iterator that contains all the elements in this container. 342 343**System capability**: SystemCapability.Utils.Lang 344 345**Return value** 346 347| Type| Description| 348| -------- | -------- | 349| IterableIterator<K> | Iterator obtained.| 350 351**Error codes** 352 353For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 354 355| ID| Error Message| 356| -------- | -------- | 357| 10200011 | The keys method cannot be bound. | 358 359**Example** 360 361```ts 362let hashMap = new HashMap(); 363hashMap.set("squirrel", 123); 364hashMap.set("sparrow", 356); 365let iter = hashMap.keys(); 366let temp = iter.next().value; 367while(temp != undefined) { 368 console.log("value:" + temp); 369 temp = iter.next().value; 370} 371``` 372 373 374### values 375 376values(): IterableIterator<V> 377 378Obtains an iterator that contains all the values in this container. 379 380**System capability**: SystemCapability.Utils.Lang 381 382**Return value** 383 384| Type| Description| 385| -------- | -------- | 386| IterableIterator<V> | Iterator obtained.| 387 388**Error codes** 389 390For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 391 392| ID| Error Message| 393| -------- | -------- | 394| 10200011 | The values method cannot be bound. | 395 396**Example** 397 398```ts 399let hashMap = new HashMap(); 400hashMap.set("squirrel", 123); 401hashMap.set("sparrow", 356); 402let iter = hashMap.values(); 403let temp = iter.next().value; 404while(temp != undefined) { 405 console.log("value:" + temp); 406 temp = iter.next().value; 407} 408``` 409 410 411### replace 412 413replace(key: K, newValue: V): boolean 414 415Replaces an element in this container. 416 417**System capability**: SystemCapability.Utils.Lang 418 419**Parameters** 420 421| Name| Type| Mandatory| Description| 422| -------- | -------- | -------- | -------- | 423| key | K | Yes| Key of the target element.| 424| newValue | V | Yes| New value of the element.| 425 426**Return value** 427 428| Type| Description| 429| -------- | -------- | 430| boolean | Returns **true** if the element is replaced successfully; returns **false** otherwise.| 431 432**Error codes** 433 434For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 435 436| ID| Error Message| 437| -------- | -------- | 438| 10200011 | The replace method cannot be bound. | 439 440**Example** 441 442```ts 443let hashMap = new HashMap(); 444hashMap.set("sparrow", 123); 445let result = hashMap.replace("sparrow", 357); 446``` 447 448 449### forEach 450 451forEach(callbackFn: (value?: V, key?: K, map?: HashMap<K, V>) => void, thisArg?: Object): void 452 453Uses a callback to traverse the elements in this container and obtain their position indexes. 454 455**System capability**: SystemCapability.Utils.Lang 456 457**Parameters** 458 459| Name| Type| Mandatory| Description| 460| -------- | -------- | -------- | -------- | 461| callbackFn | function | Yes| Callback invoked to traverse the elements in the container.| 462| thisArg | Object | No| Value to use when the callback is invoked.| 463 464callbackfn 465| Name| Type| Mandatory| Description| 466| -------- | -------- | -------- | -------- | 467| value | V | No| Value of the element that is currently traversed.| 468| key | K | No| Key of the element that is currently traversed.| 469| map | HashMap<K, V> | No| Instance that invokes the **forEach** method.| 470 471**Error codes** 472 473For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 474 475| ID| Error Message| 476| -------- | -------- | 477| 10200011 | The forEach method cannot be bound. | 478 479**Example** 480 481```ts 482let hashMap = new HashMap(); 483hashMap.set("sparrow", 123); 484hashMap.set("gull", 357); 485hashMap.forEach((value, key) => { 486 console.log("value:" + value, "key:" + key); 487}); 488``` 489 490 491### entries 492 493entries(): IterableIterator<[K, V]> 494 495Obtains an iterator that contains all the elements in this container. 496 497**System capability**: SystemCapability.Utils.Lang 498 499**Return value** 500 501| Type| Description| 502| -------- | -------- | 503| IterableIterator<[K, V]> | Iterator obtained.| 504 505**Error codes** 506 507For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 508 509| ID| Error Message| 510| -------- | -------- | 511| 10200011 | The entries method cannot be bound. | 512 513**Example** 514 515```ts 516let hashMap = new HashMap(); 517hashMap.set("squirrel", 123); 518hashMap.set("sparrow", 356); 519let iter = hashMap.entries(); 520let temp = iter.next().value; 521while(temp != undefined) { 522 console.log("key:" + temp[0]); 523 console.log("value:" + temp[1]); 524 temp = iter.next().value; 525} 526``` 527 528 529### [Symbol.iterator] 530 531[Symbol.iterator]\(): IterableIterator<[K, V]> 532 533Obtains an iterator, each item of which is a JavaScript object. 534 535**System capability**: SystemCapability.Utils.Lang 536 537**Return value** 538 539| Type| Description| 540| -------- | -------- | 541| IterableIterator<[K, V]> | Iterator obtained.| 542 543**Error codes** 544 545For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 546 547| ID| Error Message| 548| -------- | -------- | 549| 10200011 | The Symbol.iterator method cannot be bound. | 550 551**Example** 552```ts 553let hashMap = new HashMap(); 554hashMap.set("squirrel", 123); 555hashMap.set("sparrow", 356); 556 557// Method 1: 558for (let item of hashMap) { 559 console.log("key:" + item[0]); 560 console.log("value:" + item[1]); 561} 562 563// Method 2: 564let iter = hashMap[Symbol.iterator](); 565let temp = iter.next().value; 566while(temp != undefined) { 567 console.log("key:" + temp[0]); 568 console.log("value:" + temp[1]); 569 temp = iter.next().value; 570} 571``` 572