1# @ohos.util.PlainArray (Nonlinear Container PlainArray)
2
3**PlainArray** stores key-value (KV) pairs. Each key must be unique, be of the number type, and have only one value.
4
5**PlainArray** is based on generics and uses a lightweight structure. Keys in the array are searched using binary search and are mapped to values in other arrays.
6
7Both **PlainArray** and **[LightWeightMap](js-apis-lightweightmap.md)** are used to store KV pairs in the lightweight structure. However, the key type of **PlainArray** can only be **number**.
8
9**Recommended use case**: Use **PlainArray** when you need to store KV pairs whose keys are of the **number** type.
10
11This topic uses the following to identify the use of generics:
12- T: Type
13
14> **NOTE**
15>
16> 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.
17
18
19## Modules to Import
20
21```ts
22import { PlainArray } from '@kit.ArkTS';
23```
24
25
26## PlainArray
27
28### Attributes
29
30**Atomic service API**: This API can be used in atomic services since API version 12.
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 plain array (called container later).|
37
38
39### constructor
40
41constructor()
42
43A constructor used to create a **PlainArray** instance.
44
45**Atomic service API**: This API can be used in atomic services since API version 12.
46
47**System capability**: SystemCapability.Utils.Lang
48
49**Error codes**
50
51For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
52
53| ID| Error Message|
54| -------- | -------- |
55| 10200012 | The PlainArray's constructor cannot be directly invoked. |
56
57**Example**
58
59```ts
60let plainArray: PlainArray<string> = new PlainArray();
61```
62
63
64### isEmpty
65
66isEmpty(): boolean
67
68Checks whether this container is empty.
69
70**Atomic service API**: This API can be used in atomic services since API version 12.
71
72**System capability**: SystemCapability.Utils.Lang
73
74**Return value**
75
76| Type| Description|
77| -------- | -------- |
78| boolean | Returns **true** if the container is empty; returns **false** otherwise.|
79
80**Error codes**
81
82For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
83
84| ID| Error Message|
85| -------- | -------- |
86| 10200011 | The isEmpty method cannot be bound. |
87
88**Example**
89
90```ts
91const plainArray: PlainArray<string> = new PlainArray();
92let result = plainArray.isEmpty();
93```
94
95
96### has
97
98has(key: number): boolean
99
100Checks whether this container contains the specified key.
101
102**Atomic service API**: This API can be used in atomic services since API version 12.
103
104**System capability**: SystemCapability.Utils.Lang
105
106**Parameters**
107
108| Name| Type | Mandatory| Description|
109| -------- | -------- | -------- | -------- |
110| key | number | Yes| Target key. The value must be less than or equal to int32_max, that is, 2147483647.|
111
112**Return value**
113
114| Type| Description|
115| -------- | -------- |
116| boolean | Returns **true** if the specified key is contained; returns **false** otherwise.|
117
118**Error codes**
119
120For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
121
122| ID| Error Message|
123| -------- | -------- |
124| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
125| 10200011 | The has method cannot be bound. |
126
127**Example**
128
129```ts
130let plainArray: PlainArray<string> = new PlainArray();
131plainArray.add(1, "squirrel");
132let result = plainArray.has(1);
133```
134
135
136### get
137
138get(key: number): T
139
140Obtains the value of the specified key in this container.
141
142**Atomic service API**: This API can be used in atomic services since API version 12.
143
144**System capability**: SystemCapability.Utils.Lang
145
146**Parameters**
147
148| Name| Type | Mandatory| Description|
149| -------- | -------- | -------- | -------- |
150| key | number | Yes| Target key. The value must be less than or equal to int32_max, that is, 2147483647.|
151
152**Return value**
153
154| Type| Description|
155| -------- | -------- |
156| T | Value of the key.|
157
158**Error codes**
159
160For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
161
162| ID| Error Message|
163| -------- | -------- |
164| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
165| 10200011 | The get method cannot be bound. |
166
167**Example**
168
169```ts
170let plainArray: PlainArray<string> = new PlainArray();
171plainArray.add(1, "squirrel");
172plainArray.add(2, "sparrow");
173let result = plainArray.get(1);
174```
175
176
177### getIndexOfKey
178
179getIndexOfKey(key: number): number
180
181Obtains the index of the element with the specified key in this container.
182
183**Atomic service API**: This API can be used in atomic services since API version 12.
184
185**System capability**: SystemCapability.Utils.Lang
186
187**Parameters**
188
189| Name| Type | Mandatory| Description|
190| -------- | -------- | -------- | -------- |
191| key | number | Yes| Target key. The value must be less than or equal to int32_max, that is, 2147483647.|
192
193**Return value**
194
195| Type| Description|
196| -------- | -------- |
197| number | Returns the position index if obtained; returns **-1** otherwise.|
198
199**Error codes**
200
201For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
202
203| ID| Error Message|
204| -------- | -------- |
205| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
206| 10200011 | The getIndexOfKey method cannot be bound. |
207
208**Example**
209
210```ts
211let plainArray: PlainArray<string> = new PlainArray();
212plainArray.add(1, "squirrel");
213plainArray.add(2, "sparrow");
214let result = plainArray.getIndexOfKey(2);
215```
216
217
218### getIndexOfValue
219
220getIndexOfValue(value: T): number
221
222Obtains the index of the first occurrence of an element with the specified value in this container.
223
224**Atomic service API**: This API can be used in atomic services since API version 12.
225
226**System capability**: SystemCapability.Utils.Lang
227
228**Parameters**
229
230| Name| Type | Mandatory| Description|
231| -------- | -------- | -------- | -------- |
232| value | T | Yes| Value of the target element.|
233
234**Return value**
235
236| Type| Description|
237| -------- | -------- |
238| number | Returns the position index if obtained; returns **-1** otherwise.|
239
240**Error codes**
241
242For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
243
244| ID| Error Message|
245| -------- | -------- |
246| 10200011 | The getIndexOfValue method cannot be bound. |
247
248**Example**
249
250```ts
251let plainArray: PlainArray<string> = new PlainArray();
252plainArray.add(1, "squirrel");
253plainArray.add(2, "sparrow");
254let result = plainArray.getIndexOfValue("squirrel");
255```
256
257
258### getKeyAt
259
260getKeyAt(index: number): number
261
262Obtains the key of the element at the specified position in this container.
263
264**Atomic service API**: This API can be used in atomic services since API version 12.
265
266**System capability**: SystemCapability.Utils.Lang
267
268**Parameters**
269
270| Name| Type | Mandatory| Description|
271| -------- | -------- | -------- | -------- |
272| index | number | Yes| Position index of the target element. The value must be less than or equal to int32_max, that is, 2147483647.|
273
274**Return value**
275
276| Type| Description|
277| -------- | -------- |
278| number | Returns the key of the element if obtained; returns **-1** otherwise.|
279
280**Error codes**
281
282For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
283
284| ID| Error Message|
285| -------- | -------- |
286| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
287| 10200011 | The getKeyAt method cannot be bound. |
288
289**Example**
290
291```ts
292let plainArray: PlainArray<string> = new PlainArray();
293plainArray.add(1, "squirrel");
294plainArray.add(2, "sparrow");
295let result = plainArray.getKeyAt(1);
296```
297
298### getValueAt
299
300getValueAt(index: number): T
301
302Obtains the value of an element at the specified position in this container.
303
304**Atomic service API**: This API can be used in atomic services since API version 12.
305
306**System capability**: SystemCapability.Utils.Lang
307
308**Parameters**
309
310  | Name| Type | Mandatory| Description|
311  | -------- | -------- | -------- | -------- |
312  | index | number | Yes| Position index of the target element. The value must be less than or equal to int32_max, that is, 2147483647.|
313
314**Return value**
315
316  | Type| Description|
317  | -------- | -------- |
318  | T | Returns the value of the element if obtained; returns **undefined** otherwise.|
319
320  **Error codes**
321
322For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
323
324| ID| Error Message|
325| -------- | -------- |
326| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
327| 10200001 | The value of index is out of range. |
328| 10200011 | The getValueAt method cannot be bound. |
329
330**Example**
331
332```ts
333let plainArray: PlainArray<string> = new PlainArray();
334plainArray.add(1, "squirrel");
335plainArray.add(2, "sparrow");
336let result = plainArray.getValueAt(1);
337```
338
339### clone
340
341clone(): PlainArray&lt;T&gt;
342
343Clones this container and returns a copy. The modification to the copy does not affect the original instance.
344
345**Atomic service API**: This API can be used in atomic services since API version 12.
346
347**System capability**: SystemCapability.Utils.Lang
348
349**Return value**
350
351| Type| Description|
352| -------- | -------- |
353| PlainArray&lt;T&gt; | New **PlainArray** instance obtained.|
354
355**Error codes**
356
357For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
358
359| ID| Error Message|
360| -------- | -------- |
361| 10200011 | The clone method cannot be bound. |
362
363**Example**
364
365```ts
366let plainArray: PlainArray<string> = new PlainArray();
367plainArray.add(1, "squirrel");
368plainArray.add(2, "sparrow");
369let newPlainArray = plainArray.clone();
370```
371
372
373### add
374
375add(key: number, value: T): void
376
377Adds an element to this container.
378
379**Atomic service API**: This API can be used in atomic services since API version 12.
380
381**System capability**: SystemCapability.Utils.Lang
382
383**Parameters**
384
385| Name| Type | Mandatory| Description|
386| -------- | -------- | -------- | -------- |
387| key | number | Yes| Key of the target element. The value must be less than or equal to int32_max, that is, 2147483647.|
388| value | T | Yes| Value of the target element.|
389
390**Error codes**
391
392For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
393
394| ID| Error Message|
395| -------- | -------- |
396| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
397| 10200011 | The add method cannot be bound. |
398
399**Example**
400
401```ts
402let plainArray: PlainArray<string> = new PlainArray();
403plainArray.add(1, "squirrel");
404```
405
406
407### remove
408
409remove(key: number): T
410
411Removes a key-value pair with the specified key.
412
413**Atomic service API**: This API can be used in atomic services since API version 12.
414
415**System capability**: SystemCapability.Utils.Lang
416
417**Parameters**
418
419| Name| Type | Mandatory| Description|
420| -------- | -------- | -------- | -------- |
421| key | number | Yes| Target key. The value must be less than or equal to int32_max, that is, 2147483647.|
422
423**Return value**
424
425| Type| Description|
426| -------- | -------- |
427| T | Value in the key-value pair removed.|
428
429**Error codes**
430
431For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
432
433| ID| Error Message|
434| -------- | -------- |
435| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
436| 10200011 | The remove method cannot be bound. |
437
438**Example**
439
440```ts
441let plainArray: PlainArray<string> = new PlainArray();
442plainArray.add(1, "squirrel");
443plainArray.add(2, "sparrow");
444let result = plainArray.remove(2);
445```
446
447
448### removeAt
449
450removeAt(index: number): T
451
452Removes an element at the specified position from this container.
453
454**Atomic service API**: This API can be used in atomic services since API version 12.
455
456**System capability**: SystemCapability.Utils.Lang
457
458**Parameters**
459
460| Name| Type | Mandatory| Description|
461| -------- | -------- | -------- | -------- |
462| index | number | Yes| Position index of the target element. The value must be less than or equal to int32_max, that is, 2147483647.|
463
464**Return value**
465
466| Type| Description|
467| -------- | -------- |
468| T | Element removed.|
469
470**Error codes**
471
472For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
473
474| ID| Error Message|
475| -------- | -------- |
476| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
477| 10200011 | The removeAt method cannot be bound. |
478
479**Example**
480
481```ts
482let plainArray: PlainArray<string> = new PlainArray();
483plainArray.add(1, "squirrel");
484plainArray.add(2, "sparrow");
485let result = plainArray.removeAt(1);
486```
487
488
489### removeRangeFrom
490
491removeRangeFrom(index: number, size: number): number
492
493Removes elements in a specified range from this container.
494
495**Atomic service API**: This API can be used in atomic services since API version 12.
496
497**System capability**: SystemCapability.Utils.Lang
498
499**Parameters**
500
501| Name| Type | Mandatory| Description|
502| -------- | -------- | -------- | -------- |
503| index | number | Yes| Start position of the elements to remove. The value must be less than or equal to int32_max, that is, 2147483647.|
504| size | number | Yes| Number of elements to remove. The value must be less than or equal to int32_max, that is, 2147483647.|
505
506**Return value**
507
508| Type| Description|
509| -------- | -------- |
510| number | Number of elements removed.|
511
512**Error codes**
513
514For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
515
516| ID| Error Message|
517| -------- | -------- |
518| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
519| 10200001 | The value of index is out of range. |
520| 10200011 | The removeRangeFrom method cannot be bound. |
521
522**Example**
523
524```ts
525let plainArray: PlainArray<string> = new PlainArray();
526plainArray.add(1, "squirrel");
527plainArray.add(2, "sparrow");
528let result = plainArray.removeRangeFrom(1, 3);
529```
530
531
532### setValueAt
533
534setValueAt(index: number, value: T): void
535
536Sets a value for an element at the specified position in this container.
537
538**Atomic service API**: This API can be used in atomic services since API version 12.
539
540**System capability**: SystemCapability.Utils.Lang
541
542**Parameters**
543
544| Name| Type | Mandatory| Description|
545| -------- | -------- | -------- | -------- |
546| index | number | Yes| Position index of the target element. The value must be less than or equal to int32_max, that is, 2147483647.|
547| value | T | Yes| Value of the target element.|
548
549**Error codes**
550
551For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
552
553| ID| Error Message|
554| -------- | -------- |
555| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
556| 10200001 | The value of index is out of range. |
557| 10200011 | The setValueAt method cannot be bound. |
558
559**Example**
560
561```ts
562let plainArray: PlainArray<string | number> = new PlainArray();
563plainArray.add(1, "squirrel");
564plainArray.add(2, "sparrow");
565plainArray.setValueAt(1, 3546);
566```
567
568
569### toString
570
571toString(): String
572
573Obtains a string that contains all elements in this container.
574
575**Atomic service API**: This API can be used in atomic services since API version 12.
576
577**System capability**: SystemCapability.Utils.Lang
578
579**Return value**
580
581| Type| Description|
582| -------- | -------- |
583| String | String obtained.|
584
585**Error codes**
586
587For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
588
589| ID| Error Message|
590| -------- | -------- |
591| 10200011 | The toString method cannot be bound. |
592
593**Example**
594
595```ts
596let plainArray: PlainArray<string> = new PlainArray();
597plainArray.add(1, "squirrel");
598plainArray.add(2, "sparrow");
599let result = plainArray.toString();
600```
601
602
603### clear
604
605clear(): void
606
607Clears this container and sets its length to **0**.
608
609**Atomic service API**: This API can be used in atomic services since API version 12.
610
611**System capability**: SystemCapability.Utils.Lang
612
613**Error codes**
614
615For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
616
617| ID| Error Message|
618| -------- | -------- |
619| 10200011 | The clear method cannot be bound. |
620
621**Example**
622
623```ts
624let plainArray: PlainArray<string> = new PlainArray();
625plainArray.add(1, "squirrel");
626plainArray.add(2, "sparrow");
627plainArray.clear();
628```
629
630
631### forEach
632
633forEach(callbackFn: (value: T, index?: number, PlainArray?: PlainArray&lt;T&gt;) => void, thisArg?: Object): void
634
635Uses a callback to traverse the elements in this container and obtain their position indexes.
636
637**Atomic service API**: This API can be used in atomic services since API version 12.
638
639**System capability**: SystemCapability.Utils.Lang
640
641**Parameters**
642
643| Name| Type | Mandatory| Description|
644| -------- | -------- | -------- | -------- |
645| callbackFn | function | Yes| Callback invoked to traverse the elements in the container.|
646| thisArg | Object | No| Value of **this** to use when **callbackFn** is invoked. The default value is this instance.|
647
648callbackFn
649| Name| Type | Mandatory| Description|
650| -------- | -------- | -------- | -------- |
651| value | T | Yes| Value of the element that is currently traversed.|
652| index | number | No| Position index of the element that is currently traversed. The default value is **0**.|
653| PlainArray | PlainArray&lt;T&gt;| No| Instance that calls the **forEach** API. The default value is this instance.|
654
655**Error codes**
656
657For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
658
659| ID| Error Message|
660| -------- | -------- |
661| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
662| 10200011 | The forEach method cannot be bound. |
663
664**Example**
665
666```ts
667let plainArray: PlainArray<string> = new PlainArray();
668plainArray.add(1, "squirrel");
669plainArray.add(2, "sparrow");
670plainArray.forEach((value: string, index?: number) => {
671  console.log("value:" + value, "index:" + index);
672});
673```
674```ts
675// You are not advised to use the add, remove, or removeAt APIs in forEach because they may cause unpredictable risks such as infinite loops. You can use the for loop when inserting or deleting data.
676let plainArray: PlainArray<string> = new PlainArray();
677for(let i = 0;i < 10;i++) {
678  plainArray.add(i,"123");
679}
680
681for(let i = 0;i < 10;i++) {
682  plainArray.remove(i);
683}
684```
685
686### [Symbol.iterator]
687
688[Symbol.iterator]\(): IterableIterator&lt;[number, T]&gt;
689
690Obtains an iterator object that contains key-value pairs, where the key is of the number type.
691
692**Atomic service API**: This API can be used in atomic services since API version 12.
693
694**System capability**: SystemCapability.Utils.Lang
695
696**Return value**
697
698| Type| Description|
699| -------- | -------- |
700| IterableIterator&lt;[number, T]&gt; | Iterator obtained.|
701
702**Error codes**
703
704For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
705
706| ID| Error Message|
707| -------- | -------- |
708| 10200011 | The Symbol.iterator method cannot be bound. |
709
710**Example**
711
712```ts
713let plainArray: PlainArray<string> = new PlainArray();
714plainArray.add(1, "squirrel");
715plainArray.add(2, "sparrow");
716
717let iter = plainArray[Symbol.iterator]();
718let temp: IteratorResult<Object[]> = iter.next();
719while(!temp.done) {
720  console.log("key:" + temp.value[0]);
721  console.log("value:" + temp.value[1]);
722  temp = iter.next();
723}
724```
725```ts
726// You are not advised to use the add, remove, or removeAt APIs in Symbol.iterator because they may cause unpredictable risks such as infinite loops. You can use the for loop when inserting or deleting data.
727let plainArray: PlainArray<string> = new PlainArray();
728for(let i = 0;i < 10;i++) {
729  plainArray.add(i,"123");
730}
731
732for(let i = 0;i < 10;i++) {
733  plainArray.remove(i);
734}
735```
736