• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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&lt;K&gt;
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&lt;K&gt; | 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&lt;V&gt;
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&lt;V&gt; | 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&lt;[K, V]&gt;
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