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**Recommended use case**: Use **List** for frequent insertion and removal operations. 8 9This topic uses the following to identify the use of generics: 10- T: Type 11 12> **NOTE** 13> 14> 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. 15 16## Modules to Import 17 18```ts 19import List from '@ohos.util.List'; 20``` 21 22 23## List 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 a list (called container later).| 32 33 34### constructor 35 36constructor() 37 38A constructor used to create a **List** 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 List's constructor cannot be directly invoked. | 49 50**Example** 51 52```ts 53let list = new List(); 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| Value Type | Mandatory| Description| 68| -------- | -------- | -------- | -------- | 69| element | T | Yes| Target element.| 70 71**Return value** 72 73| Value 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 list = new List(); 89let result1 = list.add("a"); 90let result2 = list.add(1); 91let b = [1, 2, 3]; 92let result3 = list.add(b); 93let c = {name : "Dylon", age : "13"}; 94let result4 = list.add(c); 95let result5 = list.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| Value 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 list = new List(); 126list.insert("A", 0); 127list.insert(0, 1); 128list.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| Value Type | Mandatory| Description| 142| -------- | -------- | -------- | -------- | 143| element | T | Yes| Target element.| 144 145**Return value** 146 147| Value 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 list = new List(); 163let result = list.has("squirrel"); 164list.add("squirrel"); 165let result1 = list.has("squirrel"); 166``` 167 168### get 169 170get(index: number): T 171 172Obtains the element at the specified position in this container. 173 174**System capability**: SystemCapability.Utils.Lang 175 176**Parameters** 177 178| Name| Value Type | Mandatory| Description| 179| -------- | -------- | -------- | -------- | 180| index | number | Yes| Position index of the target element.| 181 182**Return value** 183 184| Value Type | Description| 185| -------- | -------- | 186| T | Element obtained.| 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 get method cannot be bound. | 195 196**Example** 197 198```ts 199let list = new List(); 200list.add(2); 201list.add(4); 202list.add(5); 203list.add(2); 204list.add(1); 205list.add(2); 206list.add(4); 207let result = list.get(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| Value Type | Mandatory| Description| 221| -------- | -------- | -------- | -------- | 222| element | T | Yes| Target element.| 223 224**Return value** 225 226| Value Type | Description| 227| -------- | -------- | 228| number | Returns the index if obtained; returns **-1** otherwise.| 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 list = new List(); 242list.add(2); 243list.add(4); 244list.add(5); 245list.add(2); 246list.add(1); 247list.add(2); 248list.add(4); 249let result = list.getLastIndexOf(2); 250``` 251 252### getIndexOf 253 254getIndexOf(element: T): number 255 256Obtains the index of the first occurrence of the specified element in this container. 257 258**System capability**: SystemCapability.Utils.Lang 259 260**Parameters** 261 262| Name| Value Type | Mandatory| Description| 263| -------- | -------- | -------- | -------- | 264| element | T | Yes| Target element.| 265 266**Return value** 267 268| Value Type | Description| 269| -------- | -------- | 270| number | Returns the position index if obtained; returns **-1** otherwise.| 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 getIndexOf method cannot be bound. | 279 280**Example** 281 282```ts 283let list = new List(); 284list.add(2); 285list.add(4); 286list.add(5); 287list.add(2); 288list.add(1); 289list.add(2); 290list.add(4); 291list.getIndexOf(2); 292let result = list.getIndexOf(2); 293``` 294 295### equal 296 297equal(obj: Object): boolean 298 299Compares whether a specified object is equal to this container. 300 301**System capability**: SystemCapability.Utils.Lang 302 303**Parameters** 304 305| Name| Value Type | Mandatory| Description| 306| -------- | -------- | -------- | -------- | 307| obj | Object | Yes| Object used for comparison.| 308 309**Return value** 310 311| Value Type | Description| 312| -------- | -------- | 313| boolean | Returns **true** if the two are equal; returns **false** otherwise.| 314 315**Error codes** 316 317For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 318 319| ID| Error Message| 320| -------- | -------- | 321| 10200011 | The equal method cannot be bound. | 322 323**Example** 324 325```ts 326let list = new List(); 327list.add(2); 328list.add(4); 329list.add(5); 330list.add(2); 331let obj1 = new List(); 332obj1.add(2); 333obj1.add(4); 334obj1.add(5); 335list.equal(obj1); 336let obj2 = {name : "Dylon", age : "13"}; 337let result = list.equal(obj2); 338``` 339 340### removeByIndex 341 342removeByIndex(index: number): T 343 344Removes an element at the specified position from this container. 345 346**System capability**: SystemCapability.Utils.Lang 347 348**Parameters** 349 350| Name| Value Type | Mandatory| Description| 351| -------- | -------- | -------- | -------- | 352| index | number | Yes| Position index of the target element.| 353 354**Return value** 355 356| Value Type | Description| 357| -------- | -------- | 358| T | Element removed.| 359 360**Error codes** 361 362For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 363 364| ID| Error Message| 365| -------- | -------- | 366| 10200011 | The removeByIndex method cannot be bound. | 367| 10200001 | The value of index is out of range. | 368 369**Example** 370 371```ts 372let list = new List(); 373list.add(2); 374list.add(4); 375list.add(5); 376list.add(2); 377list.add(4); 378let result = list.removeByIndex(2); 379``` 380 381### remove 382 383remove(element: T): boolean 384 385Removes the first occurrence of the specified element from this container. 386 387**System capability**: SystemCapability.Utils.Lang 388 389**Parameters** 390 391| Name| Value Type | Mandatory| Description| 392| -------- | -------- | -------- | -------- | 393| element | T | Yes| Target element.| 394 395**Return value** 396 397| Value Type | Description| 398| -------- | -------- | 399| boolean | Returns **true** if the element is removed successfully; returns **false** otherwise.| 400 401**Error codes** 402 403For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 404 405| ID| Error Message| 406| -------- | -------- | 407| 10200011 | The remove method cannot be bound. | 408 409**Example** 410 411```ts 412let list = new List(); 413list.add(2); 414list.add(4); 415list.add(5); 416list.add(4); 417let result = list.remove(2); 418``` 419 420### replaceAllElements 421 422replaceAllElements(callbackFn: (value: T, index?: number, list?: List<T>) => T, 423thisArg?: Object): void 424 425Replaces all elements in this container with new elements, and returns the new ones. 426 427**System capability**: SystemCapability.Utils.Lang 428 429**Parameters** 430 431| Name| Value Type | Mandatory| Description| 432| -------- | -------- | -------- | -------- | 433| callbackFn | function | Yes| Callback invoked for the replacement.| 434| thisArg | Object | No| Value to use when the callback is invoked.| 435 436callbackfn 437 438| Name| Value Type | Mandatory| Description| 439| -------- | -------- | -------- | -------- | 440| value | T | Yes| Value of the element that is currently traversed.| 441| index | number | No| Position index of the element that is currently traversed.| 442| list | List<T> | No| Instance that invokes the **replaceAllElements** method.| 443 444**Error codes** 445 446For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 447 448| ID| Error Message| 449| -------- | -------- | 450| 10200011 | The replaceAllElements method cannot be bound. | 451 452**Example** 453 454```ts 455let list = new List(); 456list.add(2); 457list.add(4); 458list.add(5); 459list.add(4); 460list.replaceAllElements((value: number, index: number) => { 461 return value = 2 * value; 462}); 463list.replaceAllElements((value: number, index: number) => { 464 return value = value - 2; 465}); 466``` 467 468### forEach 469 470forEach(callbackFn: (value: T, index?: number, List?: List<T>) => void, 471thisArg?: Object): void 472 473Uses a callback to traverse the elements in this container and obtain their position indexes. 474 475**System capability**: SystemCapability.Utils.Lang 476 477**Parameters** 478 479| Name| Value Type | Mandatory| Description| 480| -------- | -------- | -------- | -------- | 481| callbackFn | function | Yes| Callback invoked for the replacement.| 482| thisArg | Object | No| Value to use when the callback is invoked.| 483 484callbackfn 485 486| Name| Value Type | Mandatory| Description| 487| -------- | -------- | -------- | -------- | 488| value | T | Yes| Value of the element that is currently traversed.| 489| index | number | No| Position index of the element that is currently traversed.| 490| List | List<T> | No| Instance that invokes the **forEach** method.| 491 492**Error codes** 493 494For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 495 496| ID| Error Message| 497| -------- | -------- | 498| 10200011 | The forEach method cannot be bound. | 499 500**Example** 501 502```ts 503let list = new List(); 504list.add(2); 505list.add(4); 506list.add(5); 507list.add(4); 508list.forEach((value, index) => { 509 console.log("value:" + value, "index:" + index); 510}); 511``` 512 513### sort 514 515sort(comparator: (firstValue: T, secondValue: T) => number): void 516 517Sorts elements in this container. 518 519**System capability**: SystemCapability.Utils.Lang 520 521**Parameters** 522 523| Name| Value Type | Mandatory| Description| 524| -------- | -------- | -------- | -------- | 525| comparator | function | Yes| Callback invoked for sorting.| 526 527comparator 528 529| Name| Value Type | Mandatory| Description| 530| -------- | -------- | -------- | -------- | 531| firstValue | T | Yes| Previous element.| 532| secondValue | T | Yes| Next element.| 533 534**Error codes** 535 536For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 537 538| ID| Error Message| 539| -------- | -------- | 540| 10200011 | The sort method cannot be bound. | 541 542**Example** 543 544```ts 545let list = new List(); 546list.add(2); 547list.add(4); 548list.add(5); 549list.add(4); 550list.sort((a: number, b: number) => a - b); // The elements are sorted in ascending order. 551list.sort((a: number, b: number) => b - a); // The elements are sorted in descending order. 552``` 553 554### getSubList 555 556getSubList(fromIndex: number, toIndex: number): List<T> 557 558Obtains 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. 559 560**System capability**: SystemCapability.Utils.Lang 561 562**Parameters** 563 564| Name| Value Type | Mandatory| Description| 565| -------- | -------- | -------- | -------- | 566| fromIndex | number | Yes| Index of the start position.| 567| toIndex | number | Yes| Index of the end position.| 568 569**Return value** 570 571| Value Type | Description| 572| -------- | -------- | 573| List<T> | New **List** instance obtained.| 574 575**Error codes** 576 577For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 578 579| ID| Error Message| 580| -------- | -------- | 581| 10200011 | The getSubList method cannot be bound. | 582| 10200001 | The value of fromIndex or toIndex is out of range. | 583 584**Example** 585 586```ts 587let list = new List(); 588list.add(2); 589list.add(4); 590list.add(5); 591list.add(4); 592let result = list.getSubList(2, 4); 593let result1 = list.getSubList(4, 3); 594let result2 = list.getSubList(2, 6); 595``` 596 597### clear 598 599clear(): void 600 601Clears this container and sets its length to **0**. 602 603**System capability**: SystemCapability.Utils.Lang 604 605**Error codes** 606 607For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 608 609| ID| Error Message| 610| -------- | -------- | 611| 10200011 | The clear method cannot be bound. | 612 613**Example** 614 615```ts 616let list = new List(); 617list.add(2); 618list.add(4); 619list.add(5); 620list.add(4); 621list.clear(); 622``` 623 624### set 625 626set(index: number, element: T): T 627 628Replaces an element at the specified position in this container with a given element. 629 630**System capability**: SystemCapability.Utils.Lang 631 632**Parameters** 633 634| Name| Value Type | Mandatory| Description| 635| -------- | -------- | -------- | -------- | 636| index | number | Yes| Position index of the target element.| 637| element | T | Yes| Element to be used for replacement.| 638 639**Return value** 640 641| Value Type | Description| 642| -------- | -------- | 643| T | New element.| 644 645**Error codes** 646 647For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 648 649| ID| Error Message| 650| -------- | -------- | 651| 10200011 | The set method cannot be bound. | 652| 10200001 | The value of index is out of range. | 653 654**Example** 655 656```ts 657let list = new List(); 658list.add(2); 659list.add(4); 660list.add(5); 661list.add(4); 662list.set(2, "b"); 663``` 664 665### convertToArray 666 667convertToArray(): Array<T> 668 669Converts this container into an array. 670 671**System capability**: SystemCapability.Utils.Lang 672 673**Return value** 674 675| Value Type | Description| 676| -------- | -------- | 677| Array<T> | Array obtained.| 678 679**Error codes** 680 681For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 682 683| ID| Error Message| 684| -------- | -------- | 685| 10200011 | The convertToArray method cannot be bound. | 686 687**Example** 688 689```ts 690let list = new List(); 691list.add(2); 692list.add(4); 693list.add(5); 694list.add(4); 695let result = list.convertToArray(); 696``` 697 698### isEmpty 699 700isEmpty(): boolean 701 702Checks whether this container is empty (contains no element). 703 704**System capability**: SystemCapability.Utils.Lang 705 706**Return value** 707 708| Value Type | Description| 709| -------- | -------- | 710| boolean | Returns **true** if the container is empty; returns **false** otherwise.| 711 712**Error codes** 713 714For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 715 716| ID| Error Message| 717| -------- | -------- | 718| 10200011 | The isEmpty method cannot be bound. | 719 720**Example** 721 722```ts 723let list = new List(); 724list.add(2); 725list.add(4); 726list.add(5); 727list.add(4); 728let result = list.isEmpty(); 729``` 730 731### getFirst 732 733getFirst(): T 734 735Obtains the first element in this container. 736 737**System capability**: SystemCapability.Utils.Lang 738 739**Return value** 740 741| Value Type | Description| 742| -------- | -------- | 743| T | The first element obtained.| 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 getFirst method cannot be bound. | 752 753**Example** 754 755```ts 756let list = new List(); 757list.add(2); 758list.add(4); 759list.add(5); 760list.add(4); 761let result = list.getFirst(); 762``` 763 764### getLast 765 766getLast(): T 767 768Obtains the last element in this container. 769 770**System capability**: SystemCapability.Utils.Lang 771 772**Return value** 773 774| Value Type | Description| 775| -------- | -------- | 776| T | The last element 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 getLast method cannot be bound. | 785 786**Example** 787 788```ts 789let list = new List(); 790list.add(2); 791list.add(4); 792list.add(5); 793list.add(4); 794let result = list.getLast(); 795``` 796 797### [Symbol.iterator] 798 799[Symbol.iterator]\(): IterableIterator<T> 800 801Obtains an iterator, each item of which is a JavaScript object. 802 803**System capability**: SystemCapability.Utils.Lang 804 805**Return value** 806 807| Value Type | Description| 808| -------- | -------- | 809| IterableIterator<T> | Iterator obtained.| 810 811**Error codes** 812 813For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 814 815| ID| Error Message| 816| -------- | -------- | 817| 10200011 | The Symbol.iterator method cannot be bound. | 818 819**Example** 820 821```ts 822let list = new List(); 823list.add(2); 824list.add(4); 825list.add(5); 826list.add(4); 827 828// Method 1: 829for (let item of list) { 830 console.log("value: " + item); 831} 832 833// Method 2: 834let iter = list[Symbol.iterator](); 835let temp = iter.next().value; 836while(temp != undefined) { 837 console.log("value: " + temp); 838 temp = iter.next().value; 839} 840``` 841