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