1# @ohos.util.ArrayList (Linear Container ArrayList) 2 3> **NOTE** 4> 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. 5 6**ArrayList** is a linear data structure that is implemented based on arrays. **ArrayList** can dynamically adjust the capacity based on project requirements. It increases the capacity by 50% each time. 7 8Similar to **ArrayList**, **[Vector](js-apis-vector.md)** is also implemented based on arrays and can dynamically adjust the capacity. It increases the capability by 100% each time. 9 10When compared with **[LinkedList](js-apis-linkedlist.md)**, **ArrayList** is more efficient in random access but less efficient in the addition or removal operation, because its addition or removal operation affects the position of other elements in the container. 11 12**Recommended use case**: Use **ArrayList** when elements in a container need to be frequently read. 13 14This topic uses the following to identify the use of generics: 15- T: Type 16 17## Modules to Import 18 19```ts 20import ArrayList from '@ohos.util.ArrayList'; 21``` 22 23## ArrayList 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 an array list (called container later).| 32 33 34### constructor 35 36constructor() 37 38A constructor used to create an **ArrayList** instance. 39 40**System capability**: SystemCapability.Utils.Lang 41 42**Error codes** 43 44For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 45 46| ID| Error Message| 47| -------- | -------- | 48| 10200012 | The ArrayList's constructor cannot be directly invoked. | 49 50**Example** 51 52```ts 53let arrayList = new ArrayList(); 54``` 55 56 57### add 58 59add(element: T): boolean 60 61Adds an element at the end of this container. 62 63**System capability**: SystemCapability.Utils.Lang 64 65**Parameters** 66 67| Name| Type| Mandatory| Description| 68| -------- | -------- | -------- | -------- | 69| element | T | Yes| Target element.| 70 71**Return value** 72 73| Type| Description| 74| -------- | -------- | 75| boolean | Returns **true** if the element is added successfully; returns **false** otherwise.| 76 77**Error codes** 78 79For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 80 81| ID| Error Message| 82| -------- | -------- | 83| 10200011 | The add method cannot be bound. | 84 85**Example** 86 87```ts 88let arrayList = new ArrayList(); 89let result = arrayList.add("a"); 90let result1 = arrayList.add(1); 91let b = [1, 2, 3]; 92let result2 = arrayList.add(b); 93let c = {name: "Dylon", age: "13"}; 94let result3 = arrayList.add(c); 95let result4 = arrayList.add(false); 96``` 97 98### insert 99 100insert(element: T, index: number): void 101 102Inserts an element at the specified position in this container. 103 104**System capability**: SystemCapability.Utils.Lang 105 106**Parameters** 107 108| Name| Type| Mandatory| Description| 109| -------- | -------- | -------- | -------- | 110| element | T | Yes| Target element.| 111| index | number | Yes| Index of the position where the element is to be inserted.| 112 113**Error codes** 114 115For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 116 117| ID| Error Message| 118| -------- | -------- | 119| 10200011 | The insert method cannot be bound. | 120| 10200001 | The value of index is out of range. | 121 122**Example** 123 124```ts 125let arrayList = new ArrayList(); 126arrayList.insert("A", 0); 127arrayList.insert(0, 1); 128arrayList.insert(true, 2); 129``` 130 131### has 132 133has(element: T): boolean 134 135Checks whether this container has the specified element. 136 137**System capability**: SystemCapability.Utils.Lang 138 139**Parameters** 140 141| Name| Type| Mandatory| Description| 142| -------- | -------- | -------- | -------- | 143| element | T | Yes| Target element.| 144 145**Return value** 146 147| Type| Description| 148| -------- | -------- | 149| boolean | Returns **true** if the specified element is contained; returns **false** otherwise.| 150 151**Error codes** 152 153For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 154 155| ID| Error Message| 156| -------- | -------- | 157| 10200011 | The has method cannot be bound. | 158 159**Example** 160 161```ts 162let arrayList = new ArrayList(); 163let result = arrayList.has("squirrel"); 164arrayList.add("squirrel"); 165let result1 = arrayList.has("squirrel"); 166``` 167 168### getIndexOf 169 170getIndexOf(element: T): number 171 172Obtains the index of the first occurrence of the specified element in this container. 173 174**System capability**: SystemCapability.Utils.Lang 175 176**Parameters** 177 178| Name| Type| Mandatory| Description| 179| -------- | -------- | -------- | -------- | 180| element | T | Yes| Target element.| 181 182**Return value** 183 184| Type| Description| 185| -------- | -------- | 186| number | Returns the position index if obtained; returns **-1** if the specified element is not found.| 187 188**Error codes** 189 190For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 191 192| ID| Error Message| 193| -------- | -------- | 194| 10200011 | The getIndexOf method cannot be bound. | 195 196**Example** 197 198```ts 199let arrayList = new ArrayList(); 200arrayList.add(2); 201arrayList.add(4); 202arrayList.add(5); 203arrayList.add(2); 204arrayList.add(1); 205arrayList.add(2); 206arrayList.add(4); 207let result = arrayList.getIndexOf(2); 208``` 209 210### getLastIndexOf 211 212getLastIndexOf(element: T): number 213 214Obtains the index of the last occurrence of the specified element in this container. 215 216**System capability**: SystemCapability.Utils.Lang 217 218**Parameters** 219 220| Name| Type| Mandatory| Description| 221| -------- | -------- | -------- | -------- | 222| element | T | Yes| Target element.| 223 224**Return value** 225 226| Type| Description| 227| -------- | -------- | 228| number | Returns the position index if obtained; returns **-1** if the specified element is not found.| 229 230**Error codes** 231 232For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 233 234| ID| Error Message| 235| -------- | -------- | 236| 10200011 | The getLastIndexOf method cannot be bound. | 237 238**Example** 239 240```ts 241let arrayList = new ArrayList(); 242arrayList.add(2); 243arrayList.add(4); 244arrayList.add(5); 245arrayList.add(2); 246arrayList.add(1); 247arrayList.add(2); 248arrayList.add(4); 249let result = arrayList.getLastIndexOf(2); 250``` 251 252### removeByIndex 253 254removeByIndex(index: number): T 255 256Removes an element with the specified position from this container. 257 258**System capability**: SystemCapability.Utils.Lang 259 260**Parameters** 261 262| Name| Type| Mandatory| Description| 263| -------- | -------- | -------- | -------- | 264| index | number | Yes| Position index of the target element.| 265 266**Return value** 267 268| Type| Description| 269| -------- | -------- | 270| T | Element removed.| 271 272**Error codes** 273 274For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 275 276| ID| Error Message| 277| -------- | -------- | 278| 10200011 | The removeByIndex method cannot be bound. | 279| 10200001 | The value of index is out of range. | 280 281**Example** 282 283```ts 284let arrayList = new ArrayList(); 285arrayList.add(2); 286arrayList.add(4); 287arrayList.add(5); 288arrayList.add(2); 289arrayList.add(4); 290let result = arrayList.removeByIndex(2); 291``` 292 293### remove 294 295remove(element: T): boolean 296 297Removes the first occurrence of the specified element from this container. 298 299**System capability**: SystemCapability.Utils.Lang 300 301**Parameters** 302 303| Name| Type| Mandatory| Description| 304| -------- | -------- | -------- | -------- | 305| element | T | Yes| Target element.| 306 307**Return value** 308 309| Type| Description| 310| -------- | -------- | 311| boolean | Returns **true** if the element is removed successfully; returns **false** otherwise.| 312 313**Error codes** 314 315For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 316 317| ID| Error Message| 318| -------- | -------- | 319| 10200011 | The remove method cannot be bound. | 320 321**Example** 322 323```ts 324let arrayList = new ArrayList(); 325arrayList.add(2); 326arrayList.add(4); 327arrayList.add(5); 328arrayList.add(4); 329let result = arrayList.remove(2); 330``` 331 332### removeByRange 333 334removeByRange(fromIndex: number, toIndex: number): void 335 336Removes from this container all of the elements within a range, including the element at the start position but not that at the end position. 337 338**System capability**: SystemCapability.Utils.Lang 339 340**Parameters** 341 342| Name| Type| Mandatory| Description| 343| -------- | -------- | -------- | -------- | 344| fromIndex | number | Yes| Index of the start position.| 345| toIndex | number | Yes| Index of the end position.| 346 347**Error codes** 348 349For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 350 351| ID| Error Message| 352| -------- | -------- | 353| 10200011 | The removeByRange method cannot be bound. | 354| 10200001 | The value of fromIndex or toIndex is out of range. | 355 356**Example** 357 358```ts 359let arrayList = new ArrayList(); 360arrayList.add(2); 361arrayList.add(4); 362arrayList.add(5); 363arrayList.add(4); 364arrayList.removeByRange(2, 4); 365``` 366 367### replaceAllElements 368 369replaceAllElements(callbackFn: (value: T, index?: number, arrlist?: ArrayList<T>) => T, 370thisArg?: Object): void 371 372Replaces all elements in this container with new elements, and returns the new ones. 373 374**System capability**: SystemCapability.Utils.Lang 375 376**Parameters** 377 378| Name| Type| Mandatory| Description| 379| -------- | -------- | -------- | -------- | 380| callbackFn | function | Yes| Callback invoked for the replacement.| 381| thisArg | Object | No| Value to use when the callback is invoked.| 382 383callbackfn 384 385| Name| Type| Mandatory| Description| 386| -------- | -------- | -------- | -------- | 387| value | T | Yes| Value of the element that is currently traversed.| 388| index | number | No| Position index of the element that is currently traversed.| 389| arrlist | ArrayList<T> | No| Instance that invokes the **replaceAllElements** method.| 390 391**Error codes** 392 393For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 394 395| ID| Error Message| 396| -------- | -------- | 397| 10200011 | The replaceAllElements method cannot be bound. | 398 399**Example** 400 401```ts 402let arrayList = new ArrayList(); 403arrayList.add(2); 404arrayList.add(4); 405arrayList.add(5); 406arrayList.add(4); 407arrayList.replaceAllElements((value) => { 408 // Add the user operation logic based on the actual scenario. 409 return value; 410}); 411``` 412 413### forEach 414 415forEach(callbackFn: (value: T, index?: number, arrlist?: ArrayList<T>) => void, 416thisArg?: Object): void 417 418Uses a callback to traverse the elements in this container and obtain their position indexes. 419 420**System capability**: SystemCapability.Utils.Lang 421 422**Parameters** 423 424| Name| Type| Mandatory| Description| 425| -------- | -------- | -------- | -------- | 426| callbackFn | function | Yes| Callback invoked for the replacement.| 427| thisArg | Object | No| Value to use when the callback is invoked.| 428 429callbackfn 430 431| Name| Type| Mandatory| Description| 432| -------- | -------- | -------- | -------- | 433| value | T | Yes| Value of the element that is currently traversed.| 434| index | number | No| Position index of the element that is currently traversed.| 435| arrlist | ArrayList<T> | No| Instance that invokes the **forEach** method.| 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 forEach method cannot be bound. | 444 445**Example** 446 447```ts 448let arrayList = new ArrayList(); 449arrayList.add(2); 450arrayList.add(4); 451arrayList.add(5); 452arrayList.add(4); 453arrayList.forEach((value, index) => { 454 console.log("value:" + value, "index:" + index); 455}); 456``` 457 458### sort 459 460sort(comparator?: (firstValue: T, secondValue: T) => number): void 461 462Sorts elements in this container. 463 464**System capability**: SystemCapability.Utils.Lang 465 466**Parameters** 467 468| Name| Type| Mandatory| Description| 469| -------- | -------- | -------- | -------- | 470| comparator | function | No| Callback invoked for sorting.| 471 472comparator 473 474| Name| Type| Mandatory| Description| 475| -------- | -------- | -------- | -------- | 476| firstValue | T | Yes| Previous element.| 477| secondValue | T | Yes| Next element.| 478 479**Error codes** 480 481For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 482 483| ID| Error Message| 484| -------- | -------- | 485| 10200011 | The sort method cannot be bound. | 486 487**Example** 488 489```ts 490let arrayList = new ArrayList(); 491arrayList.add(2); 492arrayList.add(4); 493arrayList.add(5); 494arrayList.add(4); 495arrayList.sort((a: number, b: number) => a - b); 496arrayList.sort((a: number, b: number) => b - a); 497arrayList.sort(); 498``` 499 500### subArrayList 501 502subArrayList(fromIndex: number, toIndex: number): ArrayList<T> 503 504Obtains elements within a range in this container, including the element at the start position but not that at the end position, and returns these elements as a new **ArrayList** instance. 505 506**System capability**: SystemCapability.Utils.Lang 507 508**Parameters** 509 510| Name| Type| Mandatory| Description| 511| -------- | -------- | -------- | -------- | 512| fromIndex | number | Yes| Index of the start position.| 513| toIndex | number | Yes| Index of the end position.| 514 515**Return value** 516 517| Type| Description| 518| -------- | -------- | 519| ArrayList<T> | New **ArrayList** instance obtained.| 520 521**Error codes** 522 523For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 524 525| ID| Error Message| 526| -------- | -------- | 527| 10200011 | The subArrayList method cannot be bound. | 528| 10200001 | The value of fromIndex or toIndex is out of range. | 529 530**Example** 531 532```ts 533let arrayList = new ArrayList(); 534arrayList.add(2); 535arrayList.add(4); 536arrayList.add(5); 537arrayList.add(4); 538let result1 = arrayList.subArrayList(2, 4); 539let result2 = arrayList.subArrayList(4, 3); 540let result3 = arrayList.subArrayList(2, 6); 541``` 542 543### clear 544 545clear(): void 546 547Clears this container and sets its length to **0**. 548 549**System capability**: SystemCapability.Utils.Lang 550 551**Error codes** 552 553For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 554 555| ID| Error Message| 556| -------- | -------- | 557| 10200011 | The clear method cannot be bound. | 558 559**Example** 560 561```ts 562let arrayList = new ArrayList(); 563arrayList.add(2); 564arrayList.add(4); 565arrayList.add(5); 566arrayList.add(4); 567arrayList.clear(); 568``` 569 570### clone 571 572clone(): ArrayList<T> 573 574Clones this container and returns a copy. The modification to the copy does not affect the original instance. 575 576**System capability**: SystemCapability.Utils.Lang 577 578 579**Return value** 580 581| Type| Description| 582| -------- | -------- | 583| ArrayList<T> | New **ArrayList** instance obtained.| 584 585**Error codes** 586 587For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 588 589| ID| Error Message| 590| -------- | -------- | 591| 10200011 | The clone method cannot be bound. | 592 593**Example** 594 595```ts 596let arrayList = new ArrayList(); 597arrayList.add(2); 598arrayList.add(4); 599arrayList.add(5); 600arrayList.add(4); 601let result = arrayList.clone(); 602``` 603 604### getCapacity 605 606getCapacity(): number 607 608Obtains the capacity of this container. 609 610**System capability**: SystemCapability.Utils.Lang 611 612**Return value** 613 614| Type| Description| 615| -------- | -------- | 616| number | Capacity obtained.| 617 618**Error codes** 619 620For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 621 622| ID| Error Message| 623| -------- | -------- | 624| 10200011 | The getCapacity method cannot be bound. | 625 626**Example** 627 628```ts 629let arrayList = new ArrayList(); 630arrayList.add(2); 631arrayList.add(4); 632arrayList.add(5); 633arrayList.add(4); 634let result = arrayList.getCapacity(); 635``` 636 637### convertToArray 638 639convertToArray(): Array<T> 640 641Converts this container into an array. 642 643**System capability**: SystemCapability.Utils.Lang 644 645**Return value** 646 647| Type| Description| 648| -------- | -------- | 649| Array<T> | Array obtained.| 650 651**Error codes** 652 653For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 654 655| ID| Error Message| 656| -------- | -------- | 657| 10200011 | The convertToArray method cannot be bound. | 658 659**Example** 660 661```ts 662let arrayList = new ArrayList(); 663arrayList.add(2); 664arrayList.add(4); 665arrayList.add(5); 666arrayList.add(4); 667let result = arrayList.convertToArray(); 668``` 669 670### isEmpty 671 672isEmpty(): boolean 673 674Checks whether this container is empty (contains no element). 675 676**System capability**: SystemCapability.Utils.Lang 677 678**Return value** 679 680| Type| Description| 681| -------- | -------- | 682| boolean | Returns **true** if the container is empty; returns **false** otherwise.| 683 684**Error codes** 685 686For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 687 688| ID| Error Message| 689| -------- | -------- | 690| 10200011 | The isEmpty method cannot be bound. | 691 692**Example** 693 694```ts 695let arrayList = new ArrayList(); 696arrayList.add(2); 697arrayList.add(4); 698arrayList.add(5); 699arrayList.add(4); 700let result = arrayList.isEmpty(); 701``` 702 703### increaseCapacityTo 704 705increaseCapacityTo(newCapacity: number): void 706 707Increases the capacity of this container. 708 709**System capability**: SystemCapability.Utils.Lang 710 711**Parameters** 712 713| Name| Type| Mandatory| Description| 714| -------- | -------- | -------- | -------- | 715| newCapacity | number | Yes| New capacity.| 716 717**Error codes** 718 719For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 720 721| ID| Error Message| 722| -------- | -------- | 723| 10200011 | The increaseCapacityTo method cannot be bound. | 724 725**Example** 726 727```ts 728let arrayList = new ArrayList(); 729arrayList.add(2); 730arrayList.add(4); 731arrayList.add(5); 732arrayList.add(4); 733arrayList.increaseCapacityTo(2); 734arrayList.increaseCapacityTo(8); 735``` 736 737### trimToCurrentLength 738 739trimToCurrentLength(): void 740 741Trims the capacity of this container to its current length. 742 743**System capability**: SystemCapability.Utils.Lang 744 745**Error codes** 746 747For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 748 749| ID| Error Message| 750| -------- | -------- | 751| 10200011 | The trimToCurrentLength method cannot be bound. | 752 753**Example** 754 755```ts 756let arrayList = new ArrayList(); 757arrayList.add(2); 758arrayList.add(4); 759arrayList.add(5); 760arrayList.add(4); 761arrayList.trimToCurrentLength(); 762``` 763 764### [Symbol.iterator] 765 766[Symbol.iterator]\(): IterableIterator<T> 767 768Obtains an iterator, each item of which is a JavaScript object. 769 770**System capability**: SystemCapability.Utils.Lang 771 772**Return value** 773 774| Type| Description| 775| -------- | -------- | 776| IterableIterator<T> | Iterator obtained.| 777 778**Error codes** 779 780For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 781 782| ID| Error Message| 783| -------- | -------- | 784| 10200011 | The Symbol.iterator method cannot be bound. | 785 786**Example** 787 788```ts 789let arrayList = new ArrayList(); 790arrayList.add(2); 791arrayList.add(4); 792arrayList.add(5); 793arrayList.add(4); 794 795// Method 1: 796for (let item of arrayList) { 797 console.log(`value:${item}`); 798} 799 800// Method 2: 801let iter = arrayList[Symbol.iterator](); 802let temp = iter.next().value; 803while(temp != undefined) { 804 console.log(`value:${temp}`); 805 temp = iter.next().value; 806} 807``` 808