1# @ohos.util.LightWeightMap (Nonlinear Container LightWeightMap) 2 3**LightWeightMap** stores key-value (KV) pairs. Each key must be unique and have only one value. 4 5**LightWeightMap** is based on generics and uses a lightweight structure. Its default initial capacity is 8, and it has the capacity doubled in each expansion. 6 7The keys in such a set are searched using hash values, which are stored in an array. 8 9Compared with **[HashMap](js-apis-hashmap.md)**, which can also store KV pairs, **LightWeightMap** occupies less memory. 10 11**Recommended use case**: Use LightWeightMap when you need to store and access **KV pairs**. 12 13This topic uses the following to identify the use of generics: 14- K: Key 15- V: Value 16 17> **NOTE** 18> 19> 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. 20 21 22## Modules to Import 23 24```ts 25import LightWeightMap from '@ohos.util.LightWeightMap'; 26``` 27 28## LightWeightMap 29 30### Attributes 31 32**System capability**: SystemCapability.Utils.Lang 33 34| Name| Type| Readable| Writable| Description| 35| -------- | -------- | -------- | -------- | -------- | 36| length | number | Yes| No| Number of elements in a lightweight map (called container later).| 37 38 39### constructor 40 41constructor() 42 43A constructor used to create a **LightWeightMap** instance. 44 45**System capability**: SystemCapability.Utils.Lang 46 47 48**Error codes** 49 50For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 51 52| ID| Error Message| 53| -------- | -------- | 54| 10200012 | The LightWeightMap's constructor cannot be directly invoked. | 55 56**Example** 57 58```ts 59let lightWeightMap = new LightWeightMap(); 60``` 61 62 63### isEmpty 64 65isEmpty(): boolean 66 67Checks whether this container is empty (contains no element). 68 69**System capability**: SystemCapability.Utils.Lang 70 71**Return value** 72 73| Type| Description| 74| -------- | -------- | 75| boolean | Returns **true** if the container is empty; returns **false** otherwise.| 76 77**Error codes** 78 79For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 80 81| ID| Error Message| 82| -------- | -------- | 83| 10200011 | The isEmpty method cannot be bound. | 84 85**Example** 86 87```ts 88const lightWeightMap = new LightWeightMap(); 89let result = lightWeightMap.isEmpty(); 90``` 91 92 93### hasAll 94 95hasAll(map: LightWeightMap<K, V>): boolean 96 97Checks whether this container contains all elements of the specified **LightWeightMap** instance. 98 99**System capability**: SystemCapability.Utils.Lang 100 101**Parameters** 102 103| Name| Type| Mandatory| Description| 104| -------- | -------- | -------- | -------- | 105| map | LightWeightMap<K, V> | Yes| **LightWeightMap** instance to be used for comparison.| 106 107**Return value** 108 109| Type| Description| 110| -------- | -------- | 111| boolean | Returns **true** if all the elements in the specified **LightWeightMap** instance are contained; returns **false** otherwise.| 112 113**Error codes** 114 115For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 116 117| ID| Error Message| 118| -------- | -------- | 119| 10200011 | The hasAll method cannot be bound. | 120 121**Example** 122 123```ts 124let lightWeightMap = new LightWeightMap(); 125lightWeightMap.set("squirrel", 123); 126lightWeightMap.set("sparrow", 356); 127let map = new LightWeightMap(); 128map.set("sparrow", 356); 129let result = lightWeightMap.hasAll(map); 130``` 131 132 133### hasKey 134 135hasKey(key: K): boolean; 136 137Checks whether this container contains the specified key. 138 139**System capability**: SystemCapability.Utils.Lang 140 141**Parameters** 142 143| Name| Type| Mandatory| Description| 144| -------- | -------- | -------- | -------- | 145| key | K | Yes| Target key.| 146 147**Return value** 148 149| Type| Description| 150| -------- | -------- | 151| boolean | Returns **true** if the specified key is contained; returns **false** otherwise.| 152 153**Error codes** 154 155For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 156 157| ID| Error Message| 158| -------- | -------- | 159| 10200011 | The hasKey method cannot be bound. | 160 161**Example** 162 163```ts 164let lightWeightMap = new LightWeightMap(); 165lightWeightMap.set("squirrel", 123); 166let result = lightWeightMap.hasKey("squirrel"); 167``` 168 169 170### hasValue 171 172hasValue(value: V): boolean 173 174Checks whether this container contains the specified value. 175 176**System capability**: SystemCapability.Utils.Lang 177 178**Parameters** 179 180| Name| Type| Mandatory| Description| 181| -------- | -------- | -------- | -------- | 182| value | V | Yes| Target value.| 183 184**Return value** 185 186| Type| Description| 187| -------- | -------- | 188| boolean | Returns **true** if the specified value is contained; returns **false** otherwise.| 189 190**Error codes** 191 192For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 193 194| ID| Error Message| 195| -------- | -------- | 196| 10200011 | The hasValue method cannot be bound. | 197 198**Example** 199 200```ts 201let lightWeightMap = new LightWeightMap(); 202lightWeightMap.set("squirrel", 123); 203let result = lightWeightMap.hasValue(123); 204``` 205 206 207### increaseCapacityTo 208 209increaseCapacityTo(minimumCapacity: number): void 210 211Increases the capacity of this container. 212 213**System capability**: SystemCapability.Utils.Lang 214 215**Error codes** 216 217For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 218 219| ID| Error Message| 220| -------- | -------- | 221| 10200011 | The increaseCapacityTo method cannot be bound. | 222 223**Parameters** 224 225| Name| Type| Mandatory| Description| 226| -------- | -------- | -------- | -------- | 227| minimumCapacity | number | Yes| Minimum number of elements to accommodate in this container.| 228 229**Example** 230 231```ts 232let lightWeightMap = new LightWeightMap(); 233lightWeightMap.increaseCapacityTo(10); 234``` 235 236 237### get 238 239get(key: K): V 240 241Obtains the value of the specified key in this container. 242 243**System capability**: SystemCapability.Utils.Lang 244 245**Parameters** 246 247| Name| Type| Mandatory| Description| 248| -------- | -------- | -------- | -------- | 249| key | K | Yes| Target key.| 250 251**Return value** 252 253| Type| Description| 254| -------- | -------- | 255| V | Value of the key.| 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 get method cannot be bound. | 264 265**Example** 266 267```ts 268let lightWeightMap = new LightWeightMap(); 269lightWeightMap.set("squirrel", 123); 270lightWeightMap.set("sparrow", 356); 271let result = lightWeightMap.get("sparrow"); 272``` 273 274 275### getIndexOfKey 276 277getIndexOfKey(key: K): number 278 279Obtains the index of the first occurrence of an element with the specified key in this container. 280 281**System capability**: SystemCapability.Utils.Lang 282 283**Parameters** 284 285| Name| Type| Mandatory| Description| 286| -------- | -------- | -------- | -------- | 287| key | K | Yes| Key of the element.| 288 289**Return value** 290 291| Type| Description| 292| -------- | -------- | 293| number | Returns the position index if obtained; returns **-1** otherwise.| 294 295**Error codes** 296 297For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 298 299| ID| Error Message| 300| -------- | -------- | 301| 10200011 | The getIndexOfKey method cannot be bound. | 302 303**Example** 304 305```ts 306let lightWeightMap = new LightWeightMap(); 307lightWeightMap.set("squirrel", 123); 308lightWeightMap.set("sparrow", 356); 309let result = lightWeightMap.getIndexOfKey("sparrow"); 310``` 311 312 313### getIndexOfValue 314 315getIndexOfValue(value: V): number 316 317Obtains the index of the first occurrence of an element with the specified value in this container. 318 319**System capability**: SystemCapability.Utils.Lang 320 321**Parameters** 322 323| Name| Type| Mandatory| Description| 324| -------- | -------- | -------- | -------- | 325| value | V | Yes| Key of the element.| 326 327**Return value** 328 329| Type| Description| 330| -------- | -------- | 331| number | Returns the position index if obtained; returns **-1** otherwise.| 332 333**Error codes** 334 335For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 336 337| ID| Error Message| 338| -------- | -------- | 339| 10200011 | The getIndexOfValue method cannot be bound. | 340 341**Example** 342 343```ts 344let lightWeightMap = new LightWeightMap(); 345lightWeightMap.set("squirrel", 123); 346lightWeightMap.set("sparrow", 356); 347let result = lightWeightMap.getIndexOfValue(123); 348``` 349 350 351### getKeyAt 352 353getKeyAt(index: number): K 354 355Obtains the key of an element at the specified position in this container. 356 357**System capability**: SystemCapability.Utils.Lang 358 359**Parameters** 360 361| Name| Type| Mandatory| Description| 362| -------- | -------- | -------- | -------- | 363| index | number | Yes| Position index of the element.| 364 365**Return value** 366 367| Type| Description| 368| -------- | -------- | 369| K | Returns the key if obtained; returns **undefined** otherwise.| 370 371**Error codes** 372 373For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 374 375| ID| Error Message| 376| -------- | -------- | 377| 10200011 | The getKeyAt method cannot be bound. | 378| 10200001 | The value of index is out of range. | 379 380**Example** 381 382```ts 383let lightWeightMap = new LightWeightMap(); 384lightWeightMap.set("squirrel", 123); 385lightWeightMap.set("sparrow", 356); 386let result = lightWeightMap.getKeyAt(1); 387``` 388 389 390### setAll 391 392setAll(map: LightWeightMap<K, V>): void 393 394Adds all elements in a **LightWeightMap** instance to this container. 395 396**System capability**: SystemCapability.Utils.Lang 397 398**Parameters** 399 400| Name| Type| Mandatory| Description| 401| -------- | -------- | -------- | -------- | 402| map | LightWeightMap<K, V> | Yes| **LightWeightMap** instance whose elements are to be added to the current container.| 403 404**Error codes** 405 406For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 407 408| ID| Error Message| 409| -------- | -------- | 410| 10200011 | The setAll method cannot be bound. | 411 412**Example** 413 414```ts 415let lightWeightMap = new LightWeightMap(); 416lightWeightMap.set("squirrel", 123); 417lightWeightMap.set("sparrow", 356); 418let map = new LightWeightMap(); 419map.setAll(lightWeightMap); // Add all elements in lightWeightMap to the map. 420``` 421 422 423### set 424set(key: K, value: V): Object 425 426Adds an element to this container. 427 428**System capability**: SystemCapability.Utils.Lang 429 430**Parameters** 431 432| Name| Type| Mandatory| Description| 433| -------- | -------- | -------- | -------- | 434| key | K | Yes| Key of the target element.| 435| value | V | Yes| Value of the target element.| 436 437**Return value** 438 439| Type| Description| 440| -------- | -------- | 441| Object | Container that contains the new element.| 442 443**Error codes** 444 445For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 446 447| ID| Error Message| 448| -------- | -------- | 449| 10200011 | The set method cannot be bound. | 450 451**Example** 452 453```ts 454let lightWeightMap = new LightWeightMap(); 455let result = lightWeightMap.set("squirrel", 123); 456``` 457 458 459### remove 460 461remove(key: K): V 462 463Removes an element with the specified key from this container. 464 465**System capability**: SystemCapability.Utils.Lang 466 467**Parameters** 468 469| Name| Type| Mandatory| Description| 470| -------- | -------- | -------- | -------- | 471| key | K | Yes| Target key.| 472 473**Return value** 474 475| Type| Description| 476| -------- | -------- | 477| V | Value of the element removed.| 478 479**Error codes** 480 481For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 482 483| ID| Error Message| 484| -------- | -------- | 485| 10200011 | The remove method cannot be bound. | 486 487**Example** 488 489```ts 490let lightWeightMap = new LightWeightMap(); 491lightWeightMap.set("squirrel", 123); 492lightWeightMap.set("sparrow", 356); 493lightWeightMap.remove("sparrow"); 494``` 495 496 497### removeAt 498 499removeAt(index: number): boolean 500 501Removes an element at the specified position from this container. 502 503**System capability**: SystemCapability.Utils.Lang 504 505**Parameters** 506 507| Name| Type| Mandatory| Description| 508| -------- | -------- | -------- | -------- | 509| index | number | Yes| Position index of the element.| 510 511**Return value** 512 513| Type| Description| 514| -------- | -------- | 515| boolean | Returns **true** if the element is removed successfully; returns **false** otherwise.| 516 517**Error codes** 518 519For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 520 521| ID| Error Message| 522| -------- | -------- | 523| 10200011 | The removeAt method cannot be bound. | 524 525**Example** 526 527```ts 528let lightWeightMap = new LightWeightMap(); 529lightWeightMap.set("squirrel", 123); 530lightWeightMap.set("sparrow", 356); 531let result = lightWeightMap.removeAt(1); 532``` 533 534 535### setValueAt 536 537setValueAt(index: number, newValue: V): boolean 538 539Sets a value for an element at the specified position in this container. 540 541**System capability**: SystemCapability.Utils.Lang 542 543**Parameters** 544 545| Name| Type| Mandatory| Description| 546| -------- | -------- | -------- | -------- | 547| index | number | Yes| Position index of the target element.| 548| newValue | V | Yes| Value of the target element to set.| 549 550**Return value** 551 552| Type| Description| 553| -------- | -------- | 554| boolean | Returns **true** if the value is set successfully; returns **false** otherwise.| 555 556**Error codes** 557 558For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 559 560| ID| Error Message| 561| -------- | -------- | 562| 10200011 | The setValueAt method cannot be bound. | 563| 10200001 | The value of index is out of range. | 564 565**Example** 566 567```ts 568let lightWeightMap = new LightWeightMap(); 569lightWeightMap.set("squirrel", 123); 570lightWeightMap.set("sparrow", 356); 571lightWeightMap.setValueAt(1, 3546); 572``` 573 574 575### getValueAt 576 577getValueAt(index: number): V 578 579Obtains the value of an element at the specified position in this container. 580 581**System capability**: SystemCapability.Utils.Lang 582 583**Parameters** 584 585| Name| Type| Mandatory| Description| 586| -------- | -------- | -------- | -------- | 587| index | number | Yes| Position index of the element.| 588 589**Return value** 590 591| Type| Description| 592| -------- | -------- | 593| V | Value obtained.| 594 595**Error codes** 596 597For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 598 599| ID| Error Message| 600| -------- | -------- | 601| 10200011 | The getValueAt method cannot be bound. | 602| 10200001 | The value of index is out of range. | 603 604**Example** 605 606```ts 607let lightWeightMap = new LightWeightMap(); 608lightWeightMap.set("squirrel", 123); 609lightWeightMap.set("sparrow", 356); 610let result = lightWeightMap.getValueAt(1); 611``` 612 613 614### clear 615 616clear(): void 617 618Clears this container and sets its length to **0**. 619 620**System capability**: SystemCapability.Utils.Lang 621 622**Error codes** 623 624For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 625 626| ID| Error Message| 627| -------- | -------- | 628| 10200011 | The clear method cannot be bound. | 629 630**Example** 631 632```ts 633let lightWeightMap = new LightWeightMap(); 634lightWeightMap.set("squirrel", 123); 635lightWeightMap.set("sparrow", 356); 636lightWeightMap.clear(); 637``` 638 639 640### keys 641 642keys(): IterableIterator<K> 643 644Obtains an iterator that contains all the keys in this container. 645 646**System capability**: SystemCapability.Utils.Lang 647 648**Return value** 649 650| Type| Description| 651| -------- | -------- | 652| IterableIterator<K> | Iterator obtained.| 653 654**Error codes** 655 656For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 657 658| ID| Error Message| 659| -------- | -------- | 660| 10200011 | The keys method cannot be bound. | 661 662**Example** 663 664```ts 665let lightWeightMap = new LightWeightMap(); 666lightWeightMap.set("squirrel", 123); 667lightWeightMap.set("sparrow", 356); 668let iter = lightWeightMap.keys(); 669let temp = iter.next().value; 670while(temp != undefined) { 671 console.log("value:" + temp); 672 temp = iter.next().value; 673} 674``` 675 676 677### values 678 679values(): IterableIterator<V> 680 681Obtains an iterator that contains all the values in this container. 682 683**System capability**: SystemCapability.Utils.Lang 684 685**Return value** 686 687| Type| Description| 688| -------- | -------- | 689| IterableIterator<V> | Iterator obtained.| 690 691**Error codes** 692 693For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 694 695| ID| Error Message| 696| -------- | -------- | 697| 10200011 | The values method cannot be bound. | 698 699**Example** 700 701```ts 702let lightWeightMap = new LightWeightMap(); 703lightWeightMap.set("squirrel", 123); 704lightWeightMap.set("sparrow", 356); 705let iter = lightWeightMap.values(); 706let temp = iter.next().value; 707while(temp != undefined) { 708 console.log("value:" + temp); 709 temp = iter.next().value; 710} 711``` 712 713 714### forEach 715 716forEach(callbackFn: (value?: V, key?: K, map?: LightWeightMap<K, V>) => void, thisArg?: Object): void 717 718Uses a callback to traverse the elements in this container and obtain their position indexes. 719 720**System capability**: SystemCapability.Utils.Lang 721 722**Parameters** 723 724| Name| Type| Mandatory| Description| 725| -------- | -------- | -------- | -------- | 726| callbackFn | function | Yes| Callback invoked to traverse the elements in the container.| 727| thisArg | Object | No| Value to use when the callback is invoked.| 728 729callbackfn 730| Name| Type| Mandatory| Description| 731| -------- | -------- | -------- | -------- | 732| value | V | No| Value of the element that is currently traversed.| 733| key | K | No| Key of the element that is currently traversed.| 734| map | LightWeightMap<K, V> | No| Instance that invokes the **forEach** method.| 735 736**Error codes** 737 738For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 739 740| ID| Error Message| 741| -------- | -------- | 742| 10200011 | The forEach method cannot be bound. | 743 744**Example** 745 746```ts 747let lightWeightMap = new LightWeightMap(); 748lightWeightMap.set("sparrow", 123); 749lightWeightMap.set("gull", 357); 750lightWeightMap.forEach((value, key) => { 751 console.log("value:" + value, "key:" + key); 752}); 753``` 754 755 756### entries 757 758entries(): IterableIterator<[K, V]> 759 760Obtains an iterator that contains all the elements in this container. 761 762**System capability**: SystemCapability.Utils.Lang 763 764**Return value** 765 766| Type| Description| 767| -------- | -------- | 768| IterableIterator<[K, V]> | Iterator obtained.| 769 770**Error codes** 771 772For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 773 774| ID| Error Message| 775| -------- | -------- | 776| 10200011 | The entries method cannot be bound. | 777 778**Example** 779 780```ts 781let lightWeightMap = new LightWeightMap(); 782lightWeightMap.set("squirrel", 123); 783lightWeightMap.set("sparrow", 356); 784let iter = lightWeightMap.entries(); 785let temp = iter.next().value; 786while(temp != undefined) { 787 console.log("key:" + temp[0]); 788 console.log("value:" + temp[1]); 789 temp = iter.next().value; 790} 791``` 792 793### toString 794 795toString(): String 796 797Concatenates the elements in this container into a string and returns the string. 798 799**System capability**: SystemCapability.Utils.Lang 800 801**Return value** 802 803 | Type| Description| 804 | -------- | -------- | 805 | String | String obtained.| 806 807**Error codes** 808 809For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 810 811| ID| Error Message| 812| -------- | -------- | 813| 10200011 | The toString method cannot be bound. | 814 815**Example** 816 817```ts 818let lightWeightMap = new LightWeightMap(); 819lightWeightMap.set("squirrel", 123); 820lightWeightMap.set("sparrow", 356); 821let result = lightWeightMap.toString(); 822``` 823 824### [Symbol.iterator] 825 826[Symbol.iterator]\(): IterableIterator<[K, V]> 827 828Obtains an iterator, each item of which is a JavaScript object. 829 830**System capability**: SystemCapability.Utils.Lang 831 832**Return value** 833 834| Type| Description| 835| -------- | -------- | 836| IterableIterator<[K, V]> | Iterator obtained.| 837 838**Error codes** 839 840For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 841 842| ID| Error Message| 843| -------- | -------- | 844| 10200011 | The Symbol.iterator method cannot be bound. | 845 846**Example** 847 848```ts 849let lightWeightMap = new LightWeightMap(); 850lightWeightMap.set("squirrel", 123); 851lightWeightMap.set("sparrow", 356); 852 853// Method 1: 854for (let item of lightWeightMap) { 855 console.log("key:" + item[0]); 856 console.log("value:" + item[1]); 857} 858 859// Method 2: 860let iter = lightWeightMap[Symbol.iterator](); 861let temp = iter.next().value; 862while(temp != undefined) { 863 console.log("key:" + temp[0]); 864 console.log("value:" + temp[1]); 865 temp = iter.next().value; 866} 867``` 868