• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Nonlinear Container PlainArray
2
3> **NOTE**
4>
5> 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.
6
7**PlainArray** stores key-value (KV) pairs. Each key must be unique, be of the number type, and have only one value.
8
9**PlainArray** is based on generics and uses a lightweight structure. Keys in the array are searched using binary search, which map to values in other arrays.
10
11Both **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**.
12
13**Recommended use case**: Use **PlainArray** when you need to store KV pairs whose keys are of the **number** type.
14
15## Modules to Import
16
17```ts
18import PlainArray from '@ohos.util.PlainArray';
19```
20
21
22
23## PlainArray
24
25### Attributes
26
27**System capability**: SystemCapability.Utils.Lang
28
29| Name| Type| Readable| Writable| Description|
30| -------- | -------- | -------- | -------- | -------- |
31| length | number | Yes| No| Number of elements in a plain array (called container later).|
32
33
34### constructor
35
36constructor()
37
38A constructor used to create a **PlainArray** instance.
39
40**System capability**: SystemCapability.Utils.Lang
41
42**Example**
43
44```ts
45let plainArray = new PlainArray();
46```
47
48
49### isEmpty
50
51isEmpty(): boolean
52
53Checks whether this container is empty.
54
55**System capability**: SystemCapability.Utils.Lang
56
57**Return value**
58
59| Type| Description|
60| -------- | -------- |
61| boolean | Returns **true** if the container is empty; returns **false** otherwise.|
62
63**Example**
64
65```ts
66const plainArray = new PlainArray();
67let result = plainArray.isEmpty();
68```
69
70
71### has
72
73has(key: number): boolean
74
75Checks whether this container contains the specified key.
76
77**System capability**: SystemCapability.Utils.Lang
78
79**Parameters**
80
81| Name| Type | Mandatory| Description|
82| -------- | -------- | -------- | -------- |
83| key | number | Yes| Target key.|
84
85**Return value**
86
87| Type| Description|
88| -------- | -------- |
89| boolean | Returns **true** if the specified key is contained; returns **false** otherwise.|
90
91**Example**
92
93```ts
94let plainArray = new PlainArray();
95plainArray.has(1);
96plainArray.add(1, "sddfhf");
97let result1 = plainArray.has(1);
98```
99
100
101### get
102
103get(key: number): T
104
105Obtains the value of the specified key in this container.
106
107**System capability**: SystemCapability.Utils.Lang
108
109**Parameters**
110
111| Name| Type | Mandatory| Description|
112| -------- | -------- | -------- | -------- |
113| key | number | Yes| Target key.|
114
115**Return value**
116
117| Type| Description|
118| -------- | -------- |
119| T | Value of the key.|
120
121**Example**
122
123```ts
124let plainArray = new PlainArray();
125plainArray.add(1, "sddfhf");
126plainArray.add(2, "sffdfhf");
127let result = plainArray.get(1);
128```
129
130
131### getIndexOfKey
132
133getIndexOfKey(key: number): number
134
135Obtains the index of the first occurrence of an element with the specified key in this container.
136
137**System capability**: SystemCapability.Utils.Lang
138
139**Parameters**
140
141| Name| Type | Mandatory| Description|
142| -------- | -------- | -------- | -------- |
143| key | number | Yes| Target key.|
144
145**Return value**
146
147| Type| Description|
148| -------- | -------- |
149| number | Returns the position index if obtained; returns **-1** otherwise.|
150
151**Example**
152
153```ts
154let plainArray = new PlainArray();
155plainArray.add(1, "sddfhf");
156plainArray.add(2, "sffdfhf");
157let result = plainArray.getIndexOfKey(2);
158```
159
160
161### getIndexOfValue
162
163getIndexOfValue(value: T): number
164
165Obtains the index of the first occurrence of an element with the specified value in this container.
166
167**System capability**: SystemCapability.Utils.Lang
168
169**Parameters**
170
171| Name| Type | Mandatory| Description|
172| -------- | -------- | -------- | -------- |
173| value | T | Yes| Value of the target element.|
174
175**Return value**
176
177| Type| Description|
178| -------- | -------- |
179| number | Returns the position index if obtained; returns **-1** otherwise.|
180
181**Example**
182
183```ts
184let plainArray = new PlainArray();
185plainArray.add(1, "sddfhf");
186plainArray.add(2, "sffdfhf");
187let result = plainArray.getIndexOfValue("sddfhf");
188```
189
190
191### getKeyAt
192
193getKeyAt(index: number): number
194
195Obtains the key of the element at the specified position in this container.
196
197**System capability**: SystemCapability.Utils.Lang
198
199**Parameters**
200
201| Name| Type | Mandatory| Description|
202| -------- | -------- | -------- | -------- |
203| index | number | Yes| Position index of the target element.|
204
205**Return value**
206
207| Type| Description|
208| -------- | -------- |
209| number | Returns the key of the element if obtained; returns **-1** otherwise.|
210
211**Example**
212
213```ts
214let plainArray = new PlainArray();
215plainArray.add(1, "sddfhf");
216plainArray.add(2, "sffdfhf");
217let result = plainArray.getKeyAt(1);
218```
219
220### getValueAt
221
222getValueAt(index: number): T
223
224Obtains the value of an element at the specified position in this container.
225
226**System capability**: SystemCapability.Utils.Lang
227
228**Parameters**
229
230| Name| Type | Mandatory| Description|
231| -------- | -------- | -------- | -------- |
232| index | number | Yes| Position index of the target element.|
233
234**Return value**
235
236| Type| Description|
237| -------- | -------- |
238| T | Returns the value of the element if obtained; returns **undefined** otherwise.|
239
240**Example**
241
242  ```ts
243  let plainArray = new PlainArray();
244  plainArray.add(1, "sddfhf");
245  plainArray.add(2, "sffdfhf");
246  let result = plainArray.getKeyAt(1);
247  ```
248
249### clone
250
251clone(): PlainArray<T>
252
253Clones this container and returns a copy. The modification to the copy does not affect the original instance.
254
255**System capability**: SystemCapability.Utils.Lang
256
257**Return value**
258
259| Type| Description|
260| -------- | -------- |
261| PlainArray<T> | New **PlainArray** instance obtained.|
262
263**Example**
264
265```ts
266let plainArray = new PlainArray();
267plainArray.add(1, "sddfhf");
268plainArray.add(2, "sffdfhf");
269let newPlainArray = plainArray.clone();
270```
271
272
273### add
274
275add(key: number, value: T): void
276
277Adds an element to this container.
278
279**System capability**: SystemCapability.Utils.Lang
280
281**Parameters**
282
283| Name| Type | Mandatory| Description|
284| -------- | -------- | -------- | -------- |
285| key | number | Yes| Key of the target element.|
286| value | T | Yes| Value of the target element.|
287
288**Example**
289
290```ts
291let plainArray = new PlainArray();
292plainArray.add(1, "sddfhf");
293```
294
295
296### remove
297
298remove(key: number): T
299
300Removes an element with the specified key from this container.
301
302**System capability**: SystemCapability.Utils.Lang
303
304**Parameters**
305
306| Name| Type | Mandatory| Description|
307| -------- | -------- | -------- | -------- |
308| key | number | Yes| Target key.|
309
310**Return value**
311
312| Type| Description|
313| -------- | -------- |
314| T | Value of the element removed.|
315
316**Example**
317
318```ts
319let plainArray = new PlainArray();
320plainArray.add(1, "sddfhf");
321plainArray.add(2, "sffdfhf");
322plainArray.remove(2);
323let result = plainArray.remove(2);
324```
325
326
327### removeAt
328
329removeAt(index: number): T
330
331Removes an element at the specified position from this container.
332
333**System capability**: SystemCapability.Utils.Lang
334
335**Parameters**
336
337| Name| Type | Mandatory| Description|
338| -------- | -------- | -------- | -------- |
339| index | number | Yes| Position index of the target element.|
340
341**Return value**
342
343| Type| Description|
344| -------- | -------- |
345| T | Element removed.|
346
347**Example**
348
349```ts
350let plainArray = new PlainArray();
351plainArray.add(1, "sddfhf");
352plainArray.add(2, "sffdfhf");
353plainArray.removeAt(1);
354let result = plainArray.removeAt(1);
355```
356
357
358### removeRangeFrom
359
360removeRangeFrom(index: number, size: number): number
361
362Removes elements in a specified range from this container.
363
364**System capability**: SystemCapability.Utils.Lang
365
366**Parameters**
367
368| Name| Type | Mandatory| Description|
369| -------- | -------- | -------- | -------- |
370| index | number | Yes| Start position of the elements to remove.|
371| size | number | Yes| Number of elements to remove.|
372
373**Return value**
374
375| Type| Description|
376| -------- | -------- |
377| number | Number of elements removed.|
378
379**Example**
380
381```ts
382let plainArray = new PlainArray();
383plainArray.add(1, "sddfhf");
384plainArray.add(2, "sffdfhf");
385let result = plainArray.removeRangeFrom(1, 3);
386```
387
388
389### setValueAt
390
391setValueAt(index: number, value: T): void
392
393Sets a value for an element at the specified position in this container.
394
395**System capability**: SystemCapability.Utils.Lang
396
397**Parameters**
398
399| Name| Type | Mandatory| Description|
400| -------- | -------- | -------- | -------- |
401| index | number | Yes| Position index of the target element.|
402| value | T | Yes| Value of the target element.|
403
404**Example**
405
406```ts
407let plainArray = new PlainArray();
408plainArray.add(1, "sddfhf");
409plainArray.add(2, "sffdfhf");
410plainArray.setValueAt(1, 3546);
411```
412
413
414### toString
415
416toString(): String
417
418Obtains a string that contains all elements in this container.
419
420**System capability**: SystemCapability.Utils.Lang
421
422**Return value**
423
424| Type| Description|
425| -------- | -------- |
426| String | String obtained.|
427
428**Example**
429
430```ts
431let plainArray = new PlainArray();
432plainArray.add(1, "sddfhf");
433plainArray.add(2, "sffdfhf");
434let result = plainArray.toString();
435```
436
437
438### clear
439
440clear(): void
441
442Clears this container and sets its length to **0**.
443
444**System capability**: SystemCapability.Utils.Lang
445
446**Example**
447
448```ts
449let plainArray = new PlainArray();
450plainArray.add(1, "sddfhf");
451plainArray.add(2, "sffdfhf");
452plainArray.clear();
453```
454
455
456### forEach
457
458forEach(callbackfn: (value: T, index?: number, PlainArray?: PlainArray<T>) => void, thisArg?: Object): void
459
460Uses a callback to traverse the elements in this container and obtain their position indexes.
461
462**System capability**: SystemCapability.Utils.Lang
463
464**Parameters**
465
466| Name| Type | Mandatory| Description|
467| -------- | -------- | -------- | -------- |
468| callbackfn | function | Yes| Callback invoked to traverse the elements in the container.|
469| thisArg | Object | No| Value to use when the callback is invoked.|
470
471callbackfn
472| Name| Type | Mandatory| Description|
473| -------- | -------- | -------- | -------- |
474| value | T | Yes| Value of the element that is currently traversed.|
475| index | number | No| Key of the element that is currently traversed.|
476| PlainArray | PlainArray<T>| No| Instance that invokes the **forEach** API.|
477
478**Example**
479
480```ts
481let plainArray = new PlainArray();
482plainArray.add(1, "sddfhf");
483plainArray.add(2, "sffdfhf");
484plainArray.forEach((value, index) => {
485    console.log("value:" + value, "index:" + index);
486});
487```
488
489
490### [Symbol.iterator]
491
492[Symbol.iterator]\(): IterableIterator<[number, T]>
493
494Obtains an iterator, each item of which is a JavaScript object.
495
496**System capability**: SystemCapability.Utils.Lang
497
498**Return value**
499
500| Type| Description|
501| -------- | -------- |
502| IterableIterator<[number, T]> | Iterator obtained.|
503
504**Example**
505
506```ts
507let plainArray = new PlainArray();
508plainArray.add(1, "sddfhf");
509plainArray.add(2, "sffdfhf");
510
511// Method 1:
512for (let item of plainArray) {
513  console.log("index:" + item[0]);
514  console.log("value:" + item[1]);
515}
516
517// Method 2:
518let iter = plainArray[Symbol.iterator]();
519let temp = iter.next().value;
520while(temp != undefined) {
521  console.log("index:" + temp[0]);
522  console.log("value:" + temp[1]);
523  temp = iter.next().value;
524}
525```
526