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 = 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 = new List(); 90let result1 = list.add("a"); 91let result2 = list.add(1); 92let b = [1, 2, 3]; 93let result3 = list.add(b); 94let c = {name : "Dylon", age : "13"}; 95let result4 = list.add(c); 96let result5 = list.add(false); 97``` 98 99### insert 100 101insert(element: T, index: number): void 102 103Inserts an element at the specified position in this container. 104 105**System capability**: SystemCapability.Utils.Lang 106 107**Parameters** 108 109| Name| Value Type | Mandatory| Description| 110| -------- | -------- | -------- | -------- | 111| element | T | Yes| Target element.| 112| index | number | Yes| Index of the position where the element is to be inserted.| 113 114**Error codes** 115 116For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 117 118| ID| Error Message| 119| -------- | -------- | 120| 10200011 | The insert method cannot be bound. | 121| 10200001 | The value of index is out of range. | 122 123**Example** 124 125```ts 126let list = new List(); 127list.insert("A", 0); 128list.insert(0, 1); 129list.insert(true, 2); 130``` 131 132### has 133 134has(element: T): boolean 135 136Checks whether this container has the specified element. 137 138**System capability**: SystemCapability.Utils.Lang 139 140**Parameters** 141 142| Name| Value Type | Mandatory| Description| 143| -------- | -------- | -------- | -------- | 144| element | T | Yes| Target element.| 145 146**Return value** 147 148| Value Type | Description| 149| -------- | -------- | 150| boolean | Returns **true** if the specified element is contained; returns **false** otherwise.| 151 152**Error codes** 153 154For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 155 156| ID| Error Message| 157| -------- | -------- | 158| 10200011 | The has method cannot be bound. | 159 160**Example** 161 162```ts 163let list = new List(); 164list.add("squirrel"); 165let result = 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); 291let result = list.getIndexOf(2); 292``` 293 294### equal 295 296equal(obj: Object): boolean 297 298Compares whether a specified object is equal to this container. 299 300**System capability**: SystemCapability.Utils.Lang 301 302**Parameters** 303 304| Name| Value Type | Mandatory| Description| 305| -------- | -------- | -------- | -------- | 306| obj | Object | Yes| Object used for comparison.| 307 308**Return value** 309 310| Value Type | Description| 311| -------- | -------- | 312| boolean | Returns **true** if the two are equal; returns **false** otherwise.| 313 314**Error codes** 315 316For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 317 318| ID| Error Message| 319| -------- | -------- | 320| 10200011 | The equal method cannot be bound. | 321 322**Example** 323 324```ts 325let list = new List(); 326list.add(2); 327list.add(4); 328list.add(5); 329let obj = new List(); 330obj.add(2); 331obj.add(4); 332obj.add(5); 333let result = list.equal(obj); 334``` 335 336### removeByIndex 337 338removeByIndex(index: number): T 339 340Removes an element at the specified position from this container. 341 342**System capability**: SystemCapability.Utils.Lang 343 344**Parameters** 345 346| Name| Value Type | Mandatory| Description| 347| -------- | -------- | -------- | -------- | 348| index | number | Yes| Position index of the target element.| 349 350**Return value** 351 352| Value Type | Description| 353| -------- | -------- | 354| T | Element removed.| 355 356**Error codes** 357 358For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 359 360| ID| Error Message| 361| -------- | -------- | 362| 10200011 | The removeByIndex method cannot be bound. | 363| 10200001 | The value of index is out of range. | 364 365**Example** 366 367```ts 368let list = new List(); 369list.add(2); 370list.add(4); 371list.add(5); 372list.add(2); 373list.add(4); 374let result = list.removeByIndex(2); 375``` 376 377### remove 378 379remove(element: T): boolean 380 381Removes the first occurrence of the specified element from this container. 382 383**System capability**: SystemCapability.Utils.Lang 384 385**Parameters** 386 387| Name| Value Type | Mandatory| Description| 388| -------- | -------- | -------- | -------- | 389| element | T | Yes| Target element.| 390 391**Return value** 392 393| Value Type | Description| 394| -------- | -------- | 395| boolean | Returns **true** if the element is removed successfully; returns **false** otherwise.| 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 remove method cannot be bound. | 404 405**Example** 406 407```ts 408let list = new List(); 409list.add(2); 410list.add(4); 411list.add(5); 412list.add(4); 413let result = list.remove(2); 414``` 415 416### replaceAllElements 417 418replaceAllElements(callbackFn: (value: T, index?: number, list?: List<T>) => T, 419thisArg?: Object): void 420 421Replaces all elements in this container with new elements, and returns the new ones. 422 423**System capability**: SystemCapability.Utils.Lang 424 425**Parameters** 426 427| Name| Value Type | Mandatory| Description| 428| -------- | -------- | -------- | -------- | 429| callbackFn | function | Yes| Callback invoked for the replacement.| 430| thisArg | Object | No| Value to use when the callback is invoked.| 431 432callbackfn 433 434| Name| Value Type | Mandatory| Description| 435| -------- | -------- | -------- | -------- | 436| value | T | Yes| Value of the element that is currently traversed.| 437| index | number | No| Position index of the element that is currently traversed.| 438| list | List<T> | No| Instance that invokes the **replaceAllElements** method.| 439 440**Error codes** 441 442For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 443 444| ID| Error Message| 445| -------- | -------- | 446| 10200011 | The replaceAllElements method cannot be bound. | 447 448**Example** 449 450```ts 451let list = new List(); 452list.add(2); 453list.add(4); 454list.add(5); 455list.add(4); 456list.replaceAllElements((value) => { 457 // Add the user operation logic based on the actual scenario. 458 return value; 459}); 460``` 461 462### forEach 463 464forEach(callbackFn: (value: T, index?: number, List?: List<T>) => void, 465thisArg?: Object): void 466 467Uses a callback to traverse the elements in this container and obtain their position indexes. 468 469**System capability**: SystemCapability.Utils.Lang 470 471**Parameters** 472 473| Name| Value Type | Mandatory| Description| 474| -------- | -------- | -------- | -------- | 475| callbackFn | function | Yes| Callback invoked for the replacement.| 476| thisArg | Object | No| Value to use when the callback is invoked.| 477 478callbackfn 479 480| Name| Value Type | Mandatory| Description| 481| -------- | -------- | -------- | -------- | 482| value | T | Yes| Value of the element that is currently traversed.| 483| index | number | No| Position index of the element that is currently traversed.| 484| List | List<T> | No| Instance that invokes the **forEach** method.| 485 486**Error codes** 487 488For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 489 490| ID| Error Message| 491| -------- | -------- | 492| 10200011 | The forEach method cannot be bound. | 493 494**Example** 495 496```ts 497let list = new List(); 498list.add(2); 499list.add(4); 500list.add(5); 501list.add(4); 502list.forEach((value, index) => { 503 console.log("value:" + value, "index:" + index); 504}); 505``` 506 507### sort 508 509sort(comparator: (firstValue: T, secondValue: T) => number): void 510 511Sorts elements in this container. 512 513**System capability**: SystemCapability.Utils.Lang 514 515**Parameters** 516 517| Name| Value Type | Mandatory| Description| 518| -------- | -------- | -------- | -------- | 519| comparator | function | Yes| Callback invoked for sorting.| 520 521comparator 522 523| Name| Value Type | Mandatory| Description| 524| -------- | -------- | -------- | -------- | 525| firstValue | T | Yes| Previous element.| 526| secondValue | T | Yes| Next element.| 527 528**Error codes** 529 530For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 531 532| ID| Error Message| 533| -------- | -------- | 534| 10200011 | The sort method cannot be bound. | 535 536**Example** 537 538```ts 539let list = new List(); 540list.add(2); 541list.add(4); 542list.add(5); 543list.add(4); 544list.sort((a: number, b: number) => a - b); // The elements are sorted in ascending order. 545list.sort((a: number, b: number) => b - a); // The elements are sorted in descending order. 546``` 547 548### getSubList 549 550getSubList(fromIndex: number, toIndex: number): List<T> 551 552Obtains 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. 553 554**System capability**: SystemCapability.Utils.Lang 555 556**Parameters** 557 558| Name| Value Type | Mandatory| Description| 559| -------- | -------- | -------- | -------- | 560| fromIndex | number | Yes| Index of the start position.| 561| toIndex | number | Yes| Index of the end position.| 562 563**Return value** 564 565| Value Type | Description| 566| -------- | -------- | 567| List<T> | New **List** instance obtained.| 568 569**Error codes** 570 571For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 572 573| ID| Error Message| 574| -------- | -------- | 575| 10200011 | The getSubList method cannot be bound. | 576| 10200001 | The value of fromIndex or toIndex is out of range. | 577 578**Example** 579 580```ts 581let list = new List(); 582list.add(2); 583list.add(4); 584list.add(5); 585list.add(4); 586let result = list.getSubList(1, 3); 587``` 588 589### clear 590 591clear(): void 592 593Clears this container and sets its length to **0**. 594 595**System capability**: SystemCapability.Utils.Lang 596 597**Error codes** 598 599For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 600 601| ID| Error Message| 602| -------- | -------- | 603| 10200011 | The clear method cannot be bound. | 604 605**Example** 606 607```ts 608let list = new List(); 609list.add(2); 610list.add(4); 611list.add(5); 612list.add(4); 613list.clear(); 614``` 615 616### set 617 618set(index: number, element: T): T 619 620Replaces an element at the specified position in this container with a given element. 621 622**System capability**: SystemCapability.Utils.Lang 623 624**Parameters** 625 626| Name| Value Type | Mandatory| Description| 627| -------- | -------- | -------- | -------- | 628| index | number | Yes| Position index of the target element.| 629| element | T | Yes| Element to be used for replacement.| 630 631**Return value** 632 633| Value Type | Description| 634| -------- | -------- | 635| T | New element.| 636 637**Error codes** 638 639For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 640 641| ID| Error Message| 642| -------- | -------- | 643| 10200011 | The set method cannot be bound. | 644| 10200001 | The value of index is out of range. | 645 646**Example** 647 648```ts 649let list = new List(); 650list.add(2); 651list.add(4); 652list.add(5); 653list.add(4); 654let result = list.set(2, "b"); 655``` 656 657### convertToArray 658 659convertToArray(): Array<T> 660 661Converts this container into an array. 662 663**System capability**: SystemCapability.Utils.Lang 664 665**Return value** 666 667| Value Type | Description| 668| -------- | -------- | 669| Array<T> | Array obtained.| 670 671**Error codes** 672 673For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 674 675| ID| Error Message| 676| -------- | -------- | 677| 10200011 | The convertToArray method cannot be bound. | 678 679**Example** 680 681```ts 682let list = new List(); 683list.add(2); 684list.add(4); 685list.add(5); 686list.add(4); 687let result = list.convertToArray(); 688``` 689 690### isEmpty 691 692isEmpty(): boolean 693 694Checks whether this container is empty (contains no element). 695 696**System capability**: SystemCapability.Utils.Lang 697 698**Return value** 699 700| Value Type | Description| 701| -------- | -------- | 702| boolean | Returns **true** if the container is empty; returns **false** otherwise.| 703 704**Error codes** 705 706For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 707 708| ID| Error Message| 709| -------- | -------- | 710| 10200011 | The isEmpty method cannot be bound. | 711 712**Example** 713 714```ts 715let list = new List(); 716list.add(2); 717list.add(4); 718list.add(5); 719list.add(4); 720let result = list.isEmpty(); 721``` 722 723### getFirst 724 725getFirst(): T 726 727Obtains the first element in this container. 728 729**System capability**: SystemCapability.Utils.Lang 730 731**Return value** 732 733| Value Type | Description| 734| -------- | -------- | 735| T | The first element obtained.| 736 737**Error codes** 738 739For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 740 741| ID| Error Message| 742| -------- | -------- | 743| 10200011 | The getFirst method cannot be bound. | 744 745**Example** 746 747```ts 748let list = new List(); 749list.add(2); 750list.add(4); 751list.add(5); 752list.add(4); 753let result = list.getFirst(); 754``` 755 756### getLast 757 758getLast(): T 759 760Obtains the last element in this container. 761 762**System capability**: SystemCapability.Utils.Lang 763 764**Return value** 765 766| Value Type | Description| 767| -------- | -------- | 768| T | The last element obtained.| 769 770**Error codes** 771 772For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 773 774| ID| Error Message| 775| -------- | -------- | 776| 10200011 | The getLast method cannot be bound. | 777 778**Example** 779 780```ts 781let list = new List(); 782list.add(2); 783list.add(4); 784list.add(5); 785list.add(4); 786let result = list.getLast(); 787``` 788 789### [Symbol.iterator] 790 791[Symbol.iterator]\(): IterableIterator<T> 792 793Obtains an iterator, each item of which is a JavaScript object. 794 795**System capability**: SystemCapability.Utils.Lang 796 797**Return value** 798 799| Value Type | Description| 800| -------- | -------- | 801| IterableIterator<T> | Iterator obtained.| 802 803**Error codes** 804 805For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 806 807| ID| Error Message| 808| -------- | -------- | 809| 10200011 | The Symbol.iterator method cannot be bound. | 810 811**Example** 812 813```ts 814let list = new List(); 815list.add(2); 816list.add(4); 817list.add(5); 818list.add(4); 819 820// Method 1: 821for (let item of list) { 822 console.log("value: " + item); 823} 824 825// Method 2: 826let iter = list[Symbol.iterator](); 827let temp = iter.next().value; 828while(temp != undefined) { 829 console.log("value: " + temp); 830 temp = iter.next().value; 831} 832``` 833