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 17## Modules to Import 18 19```ts 20import List from '@ohos.util.List'; 21``` 22 23 24## List 25 26### Attributes 27 28**System capability**: SystemCapability.Utils.Lang 29 30| Name| Type| Readable| Writable| Description| 31| -------- | -------- | -------- | -------- | -------- | 32| length | number | Yes| No| Number of elements in a list (called container later).| 33 34 35### constructor 36 37constructor() 38 39A constructor used to create a **List** instance. 40 41**System capability**: SystemCapability.Utils.Lang 42 43**Error codes** 44 45For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 46 47| ID| Error Message| 48| -------- | -------- | 49| 10200012 | The List's constructor cannot be directly invoked. | 50 51**Example** 52 53```ts 54let list: List<string | number | boolean | object> = new List(); 55``` 56 57 58### add 59 60add(element: T): boolean 61 62Adds an element at the end of this container. 63 64**System capability**: SystemCapability.Utils.Lang 65 66**Parameters** 67 68| Name| Value Type | Mandatory| Description| 69| -------- | -------- | -------- | -------- | 70| element | T | Yes| Target element.| 71 72**Return value** 73 74| Value Type | Description| 75| -------- | -------- | 76| boolean | Returns **true** if the element is added successfully; returns **false** otherwise.| 77 78**Error codes** 79 80For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 81 82| ID| Error Message| 83| -------- | -------- | 84| 10200011 | The add method cannot be bound. | 85 86**Example** 87 88```ts 89let list: List<string | number | boolean | object> = new List(); 90let result1 = list.add("a"); 91let result2 = list.add(1); 92let b = [1, 2, 3]; 93let result3 = list.add(b); 94class C { 95 name: string = '' 96 age: string = '' 97} 98let c: C = {name : "Dylon", age : "13"}; 99let result4 = list.add(c); 100let result5 = list.add(false); 101``` 102 103### insert 104 105insert(element: T, index: number): void 106 107Inserts an element at the specified position in this container. 108 109**System capability**: SystemCapability.Utils.Lang 110 111**Parameters** 112 113| Name| Value Type | Mandatory| Description| 114| -------- | -------- | -------- | -------- | 115| element | T | Yes| Target element.| 116| index | number | Yes| Index of the position where the element is to be inserted.| 117 118**Error codes** 119 120For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 121 122| ID| Error Message| 123| -------- | -------- | 124| 10200011 | The insert method cannot be bound. | 125| 10200001 | The value of index is out of range. | 126 127**Example** 128 129```ts 130let list: List<string | number | boolean> = new List(); 131list.insert("A", 0); 132list.insert(0, 1); 133list.insert(true, 2); 134``` 135 136### has 137 138has(element: T): boolean 139 140Checks whether this container has the specified element. 141 142**System capability**: SystemCapability.Utils.Lang 143 144**Parameters** 145 146| Name| Value Type | Mandatory| Description| 147| -------- | -------- | -------- | -------- | 148| element | T | Yes| Target element.| 149 150**Return value** 151 152| Value Type | Description| 153| -------- | -------- | 154| boolean | Returns **true** if the specified element is contained; returns **false** otherwise.| 155 156**Error codes** 157 158For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 159 160| ID| Error Message| 161| -------- | -------- | 162| 10200011 | The has method cannot be bound. | 163 164**Example** 165 166```ts 167let list: List<string> = new List(); 168list.add("squirrel"); 169let result = list.has("squirrel"); 170``` 171 172### get 173 174get(index: number): T 175 176Obtains the element at the specified position in this container. 177 178**System capability**: SystemCapability.Utils.Lang 179 180**Parameters** 181 182| Name| Value Type | Mandatory| Description| 183| -------- | -------- | -------- | -------- | 184| index | number | Yes| Position index of the target element.| 185 186**Return value** 187 188| Value Type | Description| 189| -------- | -------- | 190| T | Element obtained.| 191 192**Error codes** 193 194For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 195 196| ID| Error Message| 197| -------- | -------- | 198| 10200011 | The get method cannot be bound. | 199 200**Example** 201 202```ts 203let list: List<number> = new List(); 204list.add(2); 205list.add(4); 206list.add(5); 207list.add(2); 208list.add(1); 209list.add(2); 210list.add(4); 211let result = list.get(2); 212``` 213 214### getLastIndexOf 215 216getLastIndexOf(element: T): number 217 218Obtains the index of the last occurrence of the specified element in this container. 219 220**System capability**: SystemCapability.Utils.Lang 221 222**Parameters** 223 224| Name| Value Type | Mandatory| Description| 225| -------- | -------- | -------- | -------- | 226| element | T | Yes| Target element.| 227 228**Return value** 229 230| Value Type | Description| 231| -------- | -------- | 232| number | Returns the index if obtained; returns **-1** otherwise.| 233 234**Error codes** 235 236For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 237 238| ID| Error Message| 239| -------- | -------- | 240| 10200011 | The getLastIndexOf method cannot be bound. | 241 242**Example** 243 244```ts 245let list: List<number> = new List(); 246list.add(2); 247list.add(4); 248list.add(5); 249list.add(2); 250list.add(1); 251list.add(2); 252list.add(4); 253let result = list.getLastIndexOf(2); 254``` 255 256### getIndexOf 257 258getIndexOf(element: T): number 259 260Obtains the index of the first occurrence of the specified element in this container. 261 262**System capability**: SystemCapability.Utils.Lang 263 264**Parameters** 265 266| Name| Value Type | Mandatory| Description| 267| -------- | -------- | -------- | -------- | 268| element | T | Yes| Target element.| 269 270**Return value** 271 272| Value Type | Description| 273| -------- | -------- | 274| number | Returns the position index if obtained; returns **-1** otherwise.| 275 276**Error codes** 277 278For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 279 280| ID| Error Message| 281| -------- | -------- | 282| 10200011 | The getIndexOf method cannot be bound. | 283 284**Example** 285 286```ts 287let list: List<number> = new List(); 288list.add(2); 289list.add(4); 290list.add(5); 291list.add(2); 292list.add(1); 293list.add(2); 294list.add(4); 295let result = list.getIndexOf(2); 296``` 297 298### equal 299 300equal(obj: Object): boolean 301 302Compares whether a specified object is equal to this container. 303 304**System capability**: SystemCapability.Utils.Lang 305 306**Parameters** 307 308| Name| Value Type | Mandatory| Description| 309| -------- | -------- | -------- | -------- | 310| obj | Object | Yes| Object used for comparison.| 311 312**Return value** 313 314| Value Type | Description| 315| -------- | -------- | 316| boolean | Returns **true** if the two are equal; returns **false** otherwise.| 317 318**Error codes** 319 320For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 321 322| ID| Error Message| 323| -------- | -------- | 324| 10200011 | The equal method cannot be bound. | 325 326**Example** 327 328```ts 329let list: List<number> = new List(); 330list.add(2); 331list.add(4); 332list.add(5); 333let obj: List<number> = new List(); 334obj.add(2); 335obj.add(4); 336obj.add(5); 337let result = list.equal(obj); 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: List<number> = 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: List<number> = 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 of **this** to use when **callbackFn** is invoked. The default value is this instance.| 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. The default value is **0**.| 442| list | List<T> | No| Instance that calls the **replaceAllElements** API. The default value is this instance.| 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: List<number> = new List(); 456list.add(2); 457list.add(4); 458list.add(5); 459list.add(4); 460list.replaceAllElements((value: number) => { 461 // Add the user operation logic based on the actual scenario. 462 return value; 463}); 464``` 465 466### forEach 467 468forEach(callbackFn: (value: T, index?: number, List?: List<T>) => void, 469thisArg?: Object): void 470 471Uses a callback to traverse the elements in this container and obtain their position indexes. 472 473**System capability**: SystemCapability.Utils.Lang 474 475**Parameters** 476 477| Name| Value Type | Mandatory| Description| 478| -------- | -------- | -------- | -------- | 479| callbackFn | function | Yes| Callback invoked for the replacement.| 480| thisArg | Object | No| Value of **this** to use when **callbackFn** is invoked. The default value is this instance.| 481 482callbackFn 483 484| Name| Value Type | Mandatory| Description| 485| -------- | -------- | -------- | -------- | 486| value | T | Yes| Value of the element that is currently traversed.| 487| index | number | No| Position index of the element that is currently traversed. The default value is **0**.| 488| List | List<T> | No| Instance that calls the **forEach** API. The default value is this instance.| 489 490**Error codes** 491 492For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 493 494| ID| Error Message| 495| -------- | -------- | 496| 10200011 | The forEach method cannot be bound. | 497 498**Example** 499 500```ts 501let list: List<number> = new List(); 502list.add(2); 503list.add(4); 504list.add(5); 505list.add(4); 506list.forEach((value: number, index?: number) => { 507 console.log("value:" + value, "index:" + index); 508}); 509``` 510 511### sort 512 513sort(comparator: (firstValue: T, secondValue: T) => number): void 514 515Sorts elements in this container. 516 517**System capability**: SystemCapability.Utils.Lang 518 519**Parameters** 520 521| Name| Value Type | Mandatory| Description| 522| -------- | -------- | -------- | -------- | 523| comparator | function | Yes| Callback invoked for sorting.| 524 525comparator 526 527| Name| Value Type | Mandatory| Description| 528| -------- | -------- | -------- | -------- | 529| firstValue | T | Yes| Previous element.| 530| secondValue | T | Yes| Next element.| 531 532**Error codes** 533 534For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 535 536| ID| Error Message| 537| -------- | -------- | 538| 10200011 | The sort method cannot be bound. | 539 540**Example** 541 542```ts 543let list: List<number> = new List(); 544list.add(2); 545list.add(4); 546list.add(5); 547list.add(4); 548list.sort((a: number, b: number) => a - b); // The elements are sorted in ascending order. 549list.sort((a: number, b: number) => b - a); // The elements are sorted in descending order. 550``` 551 552### getSubList 553 554getSubList(fromIndex: number, toIndex: number): List<T> 555 556Obtains 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. 557 558**System capability**: SystemCapability.Utils.Lang 559 560**Parameters** 561 562| Name| Value Type | Mandatory| Description| 563| -------- | -------- | -------- | -------- | 564| fromIndex | number | Yes| Index of the start position.| 565| toIndex | number | Yes| Index of the end position.| 566 567**Return value** 568 569| Value Type | Description| 570| -------- | -------- | 571| List<T> | New **List** instance obtained.| 572 573**Error codes** 574 575For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 576 577| ID| Error Message| 578| -------- | -------- | 579| 10200011 | The getSubList method cannot be bound. | 580| 10200001 | The value of fromIndex or toIndex is out of range. | 581 582**Example** 583 584```ts 585let list: List<number> = new List(); 586list.add(2); 587list.add(4); 588list.add(5); 589list.add(4); 590let result = list.getSubList(1, 3); 591``` 592 593### clear 594 595clear(): void 596 597Clears this container and sets its length to **0**. 598 599**System capability**: SystemCapability.Utils.Lang 600 601**Error codes** 602 603For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 604 605| ID| Error Message| 606| -------- | -------- | 607| 10200011 | The clear method cannot be bound. | 608 609**Example** 610 611```ts 612let list: List<number> = new List(); 613list.add(2); 614list.add(4); 615list.add(5); 616list.add(4); 617list.clear(); 618``` 619 620### set 621 622set(index: number, element: T): T 623 624Replaces an element at the specified position in this container with a given element. 625 626**System capability**: SystemCapability.Utils.Lang 627 628**Parameters** 629 630| Name| Value Type | Mandatory| Description| 631| -------- | -------- | -------- | -------- | 632| index | number | Yes| Position index of the target element.| 633| element | T | Yes| Element to be used for replacement.| 634 635**Return value** 636 637| Value Type | Description| 638| -------- | -------- | 639| T | New element.| 640 641**Error codes** 642 643For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 644 645| ID| Error Message| 646| -------- | -------- | 647| 10200011 | The set method cannot be bound. | 648| 10200001 | The value of index is out of range. | 649 650**Example** 651 652```ts 653let list: List<number | string> = new List(); 654list.add(2); 655list.add(4); 656list.add(5); 657list.add(4); 658let result = list.set(2, "b"); 659``` 660 661### convertToArray 662 663convertToArray(): Array<T> 664 665Converts this container into an array. 666 667**System capability**: SystemCapability.Utils.Lang 668 669**Return value** 670 671| Value Type | Description| 672| -------- | -------- | 673| Array<T> | Array obtained.| 674 675**Error codes** 676 677For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 678 679| ID| Error Message| 680| -------- | -------- | 681| 10200011 | The convertToArray method cannot be bound. | 682 683**Example** 684 685```ts 686let list: List<number> = new List(); 687list.add(2); 688list.add(4); 689list.add(5); 690list.add(4); 691let result = list.convertToArray(); 692``` 693 694### isEmpty 695 696isEmpty(): boolean 697 698Checks whether this container is empty (contains no element). 699 700**System capability**: SystemCapability.Utils.Lang 701 702**Return value** 703 704| Value Type | Description| 705| -------- | -------- | 706| boolean | Returns **true** if the container is empty; returns **false** otherwise.| 707 708**Error codes** 709 710For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 711 712| ID| Error Message| 713| -------- | -------- | 714| 10200011 | The isEmpty method cannot be bound. | 715 716**Example** 717 718```ts 719let list: List<number> = new List(); 720list.add(2); 721list.add(4); 722list.add(5); 723list.add(4); 724let result = list.isEmpty(); 725``` 726 727### getFirst 728 729getFirst(): T 730 731Obtains the first element in this container. 732 733**System capability**: SystemCapability.Utils.Lang 734 735**Return value** 736 737| Value Type | Description| 738| -------- | -------- | 739| T | The first element obtained.| 740 741**Error codes** 742 743For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 744 745| ID| Error Message| 746| -------- | -------- | 747| 10200011 | The getFirst method cannot be bound. | 748 749**Example** 750 751```ts 752let list: List<number> = new List(); 753list.add(2); 754list.add(4); 755list.add(5); 756list.add(4); 757let result = list.getFirst(); 758``` 759 760### getLast 761 762getLast(): T 763 764Obtains the last element in this container. 765 766**System capability**: SystemCapability.Utils.Lang 767 768**Return value** 769 770| Value Type | Description| 771| -------- | -------- | 772| T | The last element obtained.| 773 774**Error codes** 775 776For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 777 778| ID| Error Message| 779| -------- | -------- | 780| 10200011 | The getLast method cannot be bound. | 781 782**Example** 783 784```ts 785let list: List<number> = new List(); 786list.add(2); 787list.add(4); 788list.add(5); 789list.add(4); 790let result = list.getLast(); 791``` 792 793### [Symbol.iterator] 794 795[Symbol.iterator]\(): IterableIterator<T> 796 797Obtains an iterator, each item of which is a JavaScript object. 798 799> **NOTE** 800> 801> This API cannot be used in .ets files. 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: List<number> = new List(); 823list.add(2); 824list.add(4); 825list.add(5); 826list.add(4); 827 828// Method 1: 829let items = Array.from(list) 830for (let item of items) { 831 console.log("value: " + item); 832} 833 834// Method 2: 835let iter = list[Symbol.iterator](); 836let temp: IteratorResult<number> = iter.next(); 837while(!temp.done) { 838 console.log("value: " + temp.value); 839 temp = iter.next(); 840} 841``` 842