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