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