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