1# @ohos.util.PlainArray (非线性容器PlainArray)
2
3PlainArray可用于存储具有关联关系的key-value键值对集合,存储元素中key值唯一,key值类型为number类型,每个key对应一个value。
4
5PlainArray依据泛型定义,采用轻量级结构,集合中key值的查找依赖于二分查找算法,然后映射到其他数组中的value值。
6
7PlainArray和[LightWeightMap](js-apis-lightweightmap.md)都是用来存储键值对,且均采用轻量级结构,但PlainArray的key值类型只能为number类型。
8
9**推荐使用场景:** 当需要存储key值为number类型的键值对时,可以使用PlainArray。
10
11文档中存在泛型的使用,涉及以下泛型标记符:<br>
12- T:Type,类
13
14> **说明:**
15>
16> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
17
18
19## 导入模块
20
21```ts
22import { PlainArray } from '@kit.ArkTS';
23```
24
25
26## PlainArray
27
28### 属性
29
30**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
31
32**系统能力:** SystemCapability.Utils.Lang
33
34| 名称 | 类型 | 可读 | 可写 | 说明 |
35| -------- | -------- | -------- | -------- | -------- |
36| length | number | 是 | 否 | PlainArray的元素个数。 |
37
38
39### constructor
40
41constructor()
42
43PlainArray的构造函数。
44
45**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
46
47**系统能力:** SystemCapability.Utils.Lang
48
49**错误码:**
50
51以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。
52
53| 错误码ID | 错误信息 |
54| -------- | -------- |
55| 10200012 | The PlainArray's constructor cannot be directly invoked. |
56
57**示例:**
58
59```ts
60let plainArray: PlainArray<string> = new PlainArray();
61```
62
63
64### isEmpty
65
66isEmpty(): boolean
67
68判断该容器是否为空。
69
70**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
71
72**系统能力:** SystemCapability.Utils.Lang
73
74**返回值:**
75
76| 类型 | 说明 |
77| -------- | -------- |
78| boolean | 为空返回true, 不为空返回false。 |
79
80**错误码:**
81
82以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。
83
84| 错误码ID | 错误信息 |
85| -------- | -------- |
86| 10200011 | The isEmpty method cannot be bound. |
87
88**示例:**
89
90```ts
91const plainArray: PlainArray<string> = new PlainArray();
92let result = plainArray.isEmpty();
93```
94
95
96### has
97
98has(key: number): boolean
99
100判断此容器中是否含有该指定key。
101
102**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
103
104**系统能力:** SystemCapability.Utils.Lang
105
106**参数:**
107
108| 参数名 | 类型 | 必填 | 说明 |
109| -------- | -------- | -------- | -------- |
110| key | number | 是 | 指定key。需要小于等于int32_max即2147483647。 |
111
112**返回值:**
113
114| 类型 | 说明 |
115| -------- | -------- |
116| boolean | 包含指定key返回true,否则返回false。 |
117
118**错误码:**
119
120以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
121
122| 错误码ID | 错误信息 |
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**示例:**
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
140获取指定key所对应的value。
141
142**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
143
144**系统能力:** SystemCapability.Utils.Lang
145
146**参数:**
147
148| 参数名 | 类型 | 必填 | 说明 |
149| -------- | -------- | -------- | -------- |
150| key | number | 是 | 查找的指定key。需要小于等于int32_max即2147483647。 |
151
152**返回值:**
153
154| 类型 | 说明 |
155| -------- | -------- |
156| T | 返回key映射的value值。 |
157
158**错误码:**
159
160以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
161
162| 错误码ID | 错误信息 |
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**示例:**
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
181查找指定key对应的下标值,如果没有找到该key返回-1。
182
183**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
184
185**系统能力:** SystemCapability.Utils.Lang
186
187**参数:**
188
189| 参数名 | 类型 | 必填 | 说明 |
190| -------- | -------- | -------- | -------- |
191| key | number | 是 | 指定key。需要小于等于int32_max即2147483647。 |
192
193**返回值:**
194
195| 类型 | 说明 |
196| -------- | -------- |
197| number | 返回指定key对应的下标值,查找失败返回-1。 |
198
199**错误码:**
200
201以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
202
203| 错误码ID | 错误信息 |
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**示例:**
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
222查找指定value元素第一次出现的下标值,如果没有找到该value元素返回-1。
223
224**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
225
226**系统能力:** SystemCapability.Utils.Lang
227
228**参数:**
229
230| 参数名 | 类型 | 必填 | 说明 |
231| -------- | -------- | -------- | -------- |
232| value | T | 是 | 指定value元素。 |
233
234**返回值:**
235
236| 类型 | 说明 |
237| -------- | -------- |
238| number | 返回指定value元素第一次出现时的下标值,查找失败返回-1。 |
239
240**错误码:**
241
242以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。
243
244| 错误码ID | 错误信息 |
245| -------- | -------- |
246| 10200011 | The getIndexOfValue method cannot be bound. |
247
248**示例:**
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
262查找指定下标元素键值对中的key值。
263
264**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
265
266**系统能力:** SystemCapability.Utils.Lang
267
268**参数:**
269
270| 参数名 | 类型 | 必填 | 说明 |
271| -------- | -------- | -------- | -------- |
272| index | number | 是 | 指定下标。需要小于等于int32_max即2147483647。 |
273
274**返回值:**
275
276| 类型 | 说明 |
277| -------- | -------- |
278| number | 返回该下标元素键值对中的key值,失败返回-1。 |
279
280**错误码:**
281
282以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
283
284| 错误码ID | 错误信息 |
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**示例:**
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
302查找指定下标元素键值对中的Value值,失败返回undefined。
303
304**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
305
306**系统能力:** SystemCapability.Utils.Lang
307
308**参数:**
309
310  | 参数名 | 类型 | 必填 | 说明 |
311  | -------- | -------- | -------- | -------- |
312  | index | number | 是 | 指定下标。需要小于等于int32_max即2147483647。 |
313
314**返回值:**
315
316  | 类型 | 说明 |
317  | -------- | -------- |
318  | T | 返回该下标元素键值对中的value值,失败返回undefined。 |
319
320  **错误码:**
321
322以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
323
324| 错误码ID | 错误信息 |
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**示例:**
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
343克隆一个实例,并返回克隆后的实例。修改克隆后的实例并不会影响原实例。
344
345**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
346
347**系统能力:** SystemCapability.Utils.Lang
348
349**返回值:**
350
351| 类型 | 说明 |
352| -------- | -------- |
353| PlainArray&lt;T&gt; | 返回新的对象实例。 |
354
355**错误码:**
356
357以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。
358
359| 错误码ID | 错误信息 |
360| -------- | -------- |
361| 10200011 | The clone method cannot be bound. |
362
363**示例:**
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
377向容器中添加一组数据。
378
379**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
380
381**系统能力:** SystemCapability.Utils.Lang
382
383**参数:**
384
385| 参数名 | 类型 | 必填 | 说明 |
386| -------- | -------- | -------- | -------- |
387| key | number | 是 | 添加成员数据的键名。需要小于等于int32_max即2147483647。 |
388| value | T | 是 | 添加成员数据的值。 |
389
390**错误码:**
391
392以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
393
394| 错误码ID | 错误信息 |
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**示例:**
400
401```ts
402let plainArray: PlainArray<string> = new PlainArray();
403plainArray.add(1, "squirrel");
404```
405
406
407### remove
408
409remove(key: number): T
410
411删除指定key对应的键值对。
412
413**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
414
415**系统能力:** SystemCapability.Utils.Lang
416
417**参数:**
418
419| 参数名 | 类型 | 必填 | 说明 |
420| -------- | -------- | -------- | -------- |
421| key | number | 是 | 指定key。需要小于等于int32_max即2147483647。 |
422
423**返回值:**
424
425| 类型 | 说明 |
426| -------- | -------- |
427| T | 返回所删除的键值对中的Value值。 |
428
429**错误码:**
430
431以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
432
433| 错误码ID | 错误信息 |
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**示例:**
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
452删除指定下标对应的元素。
453
454**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
455
456**系统能力:** SystemCapability.Utils.Lang
457
458**参数:**
459
460| 参数名 | 类型 | 必填 | 说明 |
461| -------- | -------- | -------- | -------- |
462| index | number | 是 | 指定元素下标。需要小于等于int32_max即2147483647。 |
463
464**返回值:**
465
466| 类型 | 说明 |
467| -------- | -------- |
468| T | 返回删除的元素。 |
469
470**错误码:**
471
472以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
473
474| 错误码ID | 错误信息 |
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**示例:**
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
493删除一定范围内的元素。
494
495**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
496
497**系统能力:** SystemCapability.Utils.Lang
498
499**参数:**
500
501| 参数名 | 类型 | 必填 | 说明 |
502| -------- | -------- | -------- | -------- |
503| index | number | 是 | 删除元素的起始下标。需要小于等于int32_max即2147483647。 |
504| size | number | 是 | 期望删除元素个数。需要小于等于int32_max即2147483647。 |
505
506**返回值:**
507
508| 类型 | 说明 |
509| -------- | -------- |
510| number | 实际删除元素个数。 |
511
512**错误码:**
513
514以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
515
516| 错误码ID | 错误信息 |
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**示例:**
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
536替换容器中指定下标对应键值对中的键值。
537
538**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
539
540**系统能力:** SystemCapability.Utils.Lang
541
542**参数:**
543
544| 参数名 | 类型 | 必填 | 说明 |
545| -------- | -------- | -------- | -------- |
546| index | number | 是 | 指定替换数据下标。需要小于等于int32_max即2147483647。 |
547| value | T | 是 | 替换键值对中的值。 |
548
549**错误码:**
550
551以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
552
553| 错误码ID | 错误信息 |
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**示例:**
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
573获取包含容器中所有键和值的字符串。
574
575**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
576
577**系统能力:** SystemCapability.Utils.Lang
578
579**返回值:**
580
581| 类型 | 说明 |
582| -------- | -------- |
583| String | 返回对应字符串。 |
584
585**错误码:**
586
587以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。
588
589| 错误码ID | 错误信息 |
590| -------- | -------- |
591| 10200011 | The toString method cannot be bound. |
592
593**示例:**
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
607清除容器中的所有元素,并把length置为0。
608
609**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
610
611**系统能力:** SystemCapability.Utils.Lang
612
613**错误码:**
614
615以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。
616
617| 错误码ID | 错误信息 |
618| -------- | -------- |
619| 10200011 | The clear method cannot be bound. |
620
621**示例:**
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
635通过回调函数来遍历实例对象上的元素以及元素对应的下标。
636
637**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
638
639**系统能力:** SystemCapability.Utils.Lang
640
641**参数:**
642
643| 参数名 | 类型 | 必填 | 说明 |
644| -------- | -------- | -------- | -------- |
645| callbackFn | function | 是 | 回调函数。 |
646| thisArg | Object | 否 | callbackfn被调用时用作this值,默认值为当前实例对象。 |
647
648callbackfn的参数说明:
649| 参数名 | 类型 | 必填 | 说明 |
650| -------- | -------- | -------- | -------- |
651| value | T | 是 | 当前遍历到的元素。 |
652| index | number | 否 | 当前遍历到的下标值,默认值为0。 |
653| PlainArray | PlainArray&lt;T&gt;| 否 | 当前调用forEach方法的实例对象,默认值为当前实例对象。 |
654
655**错误码:**
656
657以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
658
659| 错误码ID | 错误信息 |
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**示例:**
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// 不建议在forEach中使用add、remove、removeAt方法,会导致死循环等不可预知的风险,可使用for循环来进行插入和删除。
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
690返回一个包含key-value键值对的迭代器对象,其中key是number类型。
691
692**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
693
694**系统能力:** SystemCapability.Utils.Lang
695
696**返回值:**
697
698| 类型 | 说明 |
699| -------- | -------- |
700| IterableIterator&lt;[number, T]&gt; | 返回一个迭代器。 |
701
702**错误码:**
703
704以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。
705
706| 错误码ID | 错误信息 |
707| -------- | -------- |
708| 10200011 | The Symbol.iterator method cannot be bound. |
709
710**示例:**
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// 不建议在Symbol.iterator中使用add、remove、removeAt方法,会导致死循环等不可预知的风险,可使用for循环来进行插入和删除。
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```