1# @ohos.util.Queue (Linear Container Queue)
2
3**Queue** follows the principle of First In First Out (FIFO). It supports insertion of elements at the end and removal from the front of the queue. **Queue** is implemented based on the queue data structure.
4
5Unlike **[Deque](js-apis-deque.md)**, which supports insertion and removal at both the ends, **Queue** supports insertion at one end and removal at the other end.
6
7**Recommended use case**: Use **Queue** in FIFO scenarios.
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 { Queue } from '@kit.ArkTS';
21```
22
23
24## Queue
25
26### Attributes
27
28**Atomic service API**: This API can be used in atomic services since API version 12.
29
30**System capability**: SystemCapability.Utils.Lang
31
32| Name| Type| Readable| Writable| Description|
33| -------- | -------- | -------- | -------- | -------- |
34| length | number | Yes| No| Number of elements in a queue (called container later).|
35
36
37### constructor
38
39constructor()
40
41A constructor used to create a **Queue** instance.
42
43**Atomic service API**: This API can be used in atomic services since API version 12.
44
45**System capability**: SystemCapability.Utils.Lang
46
47**Error codes**
48
49For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
50
51| ID| Error Message|
52| -------- | -------- |
53| 10200012 | The Queue's constructor cannot be directly invoked. |
54
55**Example**
56
57```ts
58let queue : Queue<number | string | Object> = new Queue();
59```
60
61
62### add
63
64add(element: T): boolean
65
66Adds an element at the end of this container.
67
68**Atomic service API**: This API can be used in atomic services since API version 12.
69
70**System capability**: SystemCapability.Utils.Lang
71
72**Parameters**
73
74| Name| Type| Mandatory| Description|
75| -------- | -------- | -------- | -------- |
76| element | T | Yes| Target element.|
77
78**Return value**
79
80| Type| Description|
81| -------- | -------- |
82| boolean | Returns **true** if the element is added successfully; returns **false** otherwise.|
83
84**Error codes**
85
86For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
87
88| ID| Error Message|
89| -------- | -------- |
90| 10200011 | The add method cannot be bound. |
91
92**Example**
93
94```ts
95class C1 {
96  name: string = ""
97  age: string = ""
98}
99let queue : Queue<number | string | C1 | number[]> = new Queue();
100let result = queue.add("a");
101let result1 = queue.add(1);
102let b = [1, 2, 3];
103let result2 = queue.add(b);
104let c : C1 = {name : "Dylan", age : "13"};
105let result3 = queue.add(c);
106```
107
108### pop
109
110pop(): T
111
112Removes the first element from this container.
113
114**Atomic service API**: This API can be used in atomic services since API version 12.
115
116**System capability**: SystemCapability.Utils.Lang
117
118**Return value**
119
120| Type| Description|
121| -------- | -------- |
122| T | Element removed.|
123
124**Error codes**
125
126For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
127
128| ID| Error Message|
129| -------- | -------- |
130| 10200011 | The pop method cannot be bound. |
131
132**Example**
133
134```ts
135let queue : Queue<number> = new Queue();
136queue.add(2);
137queue.add(4);
138queue.add(5);
139queue.add(2);
140queue.add(4);
141let result = queue.pop();
142```
143
144### getFirst
145
146getFirst(): T
147
148Obtains the first element of this container.
149
150**Atomic service API**: This API can be used in atomic services since API version 12.
151
152**System capability**: SystemCapability.Utils.Lang
153
154**Return value**
155
156| Type| Description|
157| -------- | -------- |
158| T | The first element obtained.|
159
160**Error codes**
161
162For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
163
164| ID| Error Message|
165| -------- | -------- |
166| 10200011 | The getFirst method cannot be bound. |
167
168**Example**
169
170```ts
171let queue : Queue<number> = new Queue();
172queue.add(2);
173queue.add(4);
174queue.add(5);
175queue.add(2);
176let result = queue.getFirst();
177```
178
179### forEach
180
181forEach(callbackFn: (value: T, index?: number, Queue?: Queue&lt;T&gt;) => void,
182thisArg?: Object): void
183
184Uses a callback to traverse the elements in this container and obtain their position indexes.
185
186**Atomic service API**: This API can be used in atomic services since API version 12.
187
188**System capability**: SystemCapability.Utils.Lang
189
190**Parameters**
191
192| Name| Type| Mandatory| Description|
193| -------- | -------- | -------- | -------- |
194| callbackFn | function | Yes| Callback invoked to traverse the elements in the container.|
195| thisArg | Object | No| Value of **this** to use when **callbackFn** is invoked. The default value is this instance.|
196
197callbackFn
198
199| Name| Type| Mandatory| Description|
200| -------- | -------- | -------- | -------- |
201| value | T | Yes| Value of the element that is currently traversed.|
202| index | number | No| Position index of the element that is currently traversed. The default value is **0**.|
203| Queue | Queue&lt;T&gt; | No| Instance that calls the **forEach** API. The default value is this instance.|
204
205**Error codes**
206
207For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
208
209| ID| Error Message|
210| -------- | -------- |
211| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
212| 10200011 | The forEach method cannot be bound. |
213
214**Example**
215
216```ts
217let queue : Queue<number> = new Queue();
218queue.add(2);
219queue.add(4);
220queue.add(5);
221queue.add(4);
222queue.forEach((value : number, index ?: number) : void => {
223  console.log("value:" + value, "index:" + index);
224});
225```
226
227### [Symbol.iterator]
228
229[Symbol.iterator]\(): IterableIterator&lt;T&gt;
230
231Obtains an iterator, each item of which is a JavaScript object.
232
233**Atomic service API**: This API can be used in atomic services since API version 12.
234
235**System capability**: SystemCapability.Utils.Lang
236
237**Return value**
238
239| Type| Description|
240| -------- | -------- |
241| IterableIterator&lt;T&gt; | Iterator obtained.|
242
243**Error codes**
244
245For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
246
247| ID| Error Message|
248| -------- | -------- |
249| 10200011 | The Symbol.iterator method cannot be bound. |
250
251**Example**
252```ts
253let queue : Queue<number> = new Queue();
254queue.add(2);
255queue.add(4);
256queue.add(5);
257queue.add(4);
258
259// Method 1:
260while(queue.length) {
261  let item = queue.pop()
262  console.log("value:" + item);
263}
264
265// Method 2:
266let iter = queue[Symbol.iterator]();
267let temp: IteratorResult<number> = iter.next().value;
268while(temp != undefined) {
269  console.log("value:" + temp);
270  temp = iter.next().value;
271}
272```
273