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