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<T> 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<T> | 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<T>) => 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<T>| 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<[number, T]> 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<[number, T]> | 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