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