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