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> **NOTE**
234>
235> This API cannot be used in .ets files.
236
237**Atomic service API**: This API can be used in atomic services since API version 12.
238
239**System capability**: SystemCapability.Utils.Lang
240
241**Return value**
242
243| Type| Description|
244| -------- | -------- |
245| IterableIterator&lt;T&gt; | Iterator obtained.|
246
247**Error codes**
248
249For details about the error codes, see [Utils Error Codes](errorcode-utils.md).
250
251| ID| Error Message|
252| -------- | -------- |
253| 10200011 | The Symbol.iterator method cannot be bound. |
254
255**Example**
256```ts
257let queue : Queue<number> = new Queue();
258queue.add(2);
259queue.add(4);
260queue.add(5);
261queue.add(4);
262
263// Method 1:
264while(queue.length) {
265  let item = queue.pop()
266  console.log("value:" + item);
267}
268
269// Method 2:
270let iter = queue[Symbol.iterator]();
271let temp: IteratorResult<number> = iter.next().value;
272while(temp != undefined) {
273  console.log("value:" + temp);
274  temp = iter.next().value;
275}
276```
277