git.iko.soy/urbit.org
on 979ae21 help sign in
urbit.org/hoon/reference/stdlib/2k.md
399 lines 5.9 kB history raw
1+++
2title = "2k: Queue Logic"
3weight = 14
4template = "doc.html"
5+++
7### `++to`
10Queue operations
12Container arm for queue operation arms. The contained arms inherit `a`, its
13sample queue.
15#### Accepts
17`a` is a tree.
19#### Source
21```hoon
22 ++ to
23 |_ a=(tree)
24```
26#### Discussion
28`tree` is the generic tree-shape mold. Maps, sets, and queues all share that
29shape, but they put their elements in different places and have different
30interfaces. `to` is the interface core for `qeu`; it's not generic across all
31the different containers that use `tree`.
33---
34### `+-bal:to`
36Balance
38Vertically rebalances queue `a`.
40#### Accepts
42`a` is a queue.
44#### Produces
46A queue.
48#### Source
50```hoon
51 +- bal
52 |- ^+ a
53 ?~ a ~
54 ?. |(?=($~ l.a) (vor n.a n.l.a))
55 $(a [n.l.a l.l.a $(a [n.a r.l.a r.a])])
56 ?. |(?=($~ r.a) (vor n.a n.r.a))
57 $(a [n.r.a $(a [n.a l.a l.r.a]) r.r.a])
58 a
59```
61#### Examples
63```
64 > `(qeu tape)`["a" ~ "b" ~ "c" ~ "d" ~ "e" ~ "f" ~ "g" ~ ~]
65 {"a" "b" "c" "d" "e" "f" "g"}
67 > `*`["a" ~ "b" ~ "c" ~ "d" ~ "e" ~ "f" ~ "g" ~ ~]
68 [[97 0] 0 [98 0] 0 [99 0] 0 [100 0] 0 [101 0] 0 [102 0] 0 [103 0] 0 0]
70 > ~(bal to `(qeu tape)`["a" ~ "b" ~ "c" ~ "d" ~ "e" ~ "f" ~ "g" ~ ~])
71 [n=[i='d' t=""] l={"a" "b" "c"} r={"e" "f" "g"}]
73 > `*`~(bal to `(qeu tape)`["a" ~ "b" ~ "c" ~ "d" ~ "e" ~ "f" ~ "g" ~ ~])
74 [[100 0] [[99 0] [[98 0] [[97 0] 0 0] 0] 0] [101 0] 0 [102 0] 0 [103 0] 0 0]
75```
77---
78### `+-dep:to`
80Maximum Depth
82Produces the maximum depth of leaves (`r.a` and `l.a`) in queue `a`.
84#### Accepts
86`a` is a queue.
88#### Produces
90An atom.
92#### Source
94```hoon
95 +- dep
96 |- ^- @
97 ?~ a 0
98 +((max $(a l.a) $(a r.a)))
99```
101#### Examples
103```
104 > =a (~(gas to `(qeu @)`~) `(list @)`[1 2 3 4 5 6 7 ~])
105 > ~(dep to a)
106 4
108 > =a (~(gas to `(qeu @)`~) `(list @)`[1 2 3 4 ~])
109 > ~(dep to a)
110 3
112 > =a (~(gas to `(qeu @)`~) `(list @)`[1 2 ~])
113 > ~(dep to a)
114 2
116 > ~(dep to `(qeu tape)`["a" ~ "b" ~ "c" ~ "d" ~ "e" ~ "f" ~ "g" ~ ~])
117 7
119 > ~(dep to ~(bal to `(qeu tape)`["a" ~ "b" ~ "c" ~ "d" ~ "e" ~ "f" ~ "g" ~ ~]))
120 4
121```
123---
124### `+-gas:to`
126Push list
128Push all elements of list `b` into the queue `a`.
130#### Accepts
132`a` is a queue.
134`b` is a list.
136#### Produces
138A queue.
140#### Source
142```hoon
143 +- gas
144 |= b=(list _?>(?=(^ a) n.a))
145 |- ^+ a
146 ?~(b a $(b t.b, a (put i.b)))
147```
150#### Examples
152```
153 > `(qeu)`(~(gas to `(qeu @)`~) [1 2 3 ~])
154 {3 2 1}
156 > =a (~(gas to `(qeu @)`~) [1 2 3 ~])
157 > =b [4 5 6 ~]
158 > `(qeu)`(~(gas to a) b)
159 {6 5 4 3 2 1}
160```
161---
162### `+-get:to`
164Head-tail pair
166Produces the head and tail queue of `a`.
168#### Accepts
170`a` is a queue.
172#### Produces
174A cell of the last element in `a` along with the rest of queue `a`.
176#### Source
178```hoon
179 +- get
180 |- ^+ ?>(?=(^ a) [p=n.a q=*(tree _n.a)])
181 ?~ a
182 !!
183 ?~ r.a
184 [n.a l.a]
185 =+ b=$(a r.a)
186 :- p.b
187 ?: |(?=($~ q.b) (vor n.a n.q.b))
188 [n.a l.a q.b]
189 [n.q.b [n.a l.a l.q.b] r.q.b]
190```
192#### Examples
194```
195 > =s (~(gas to *(tree @)) `(list @)`~[1 2 3])
196 > ~(get to s)
197 [n=2 l={3} r={1}]
199 > ~(get to ~)
200 ! exit
201```
203---
204### `+-nap:to`
206Remove head
208Removes the head of queue `a`, producing the resulting queue.
210#### Accepts
212`a` is a queue.
214#### Produces
216A queue.
218#### Source
220```hoon
221 +- nap
222 ?> ?=(^ a)
223 ?~ l.a r.a
224 =+ b=get(a l.a)
225 bal(a ^+(a [p.b q.b r.a]))
226```
228#### Examples
230```
231 > =a (~(gas to `(qeu @)`~) `(list @)`[1 2 3 4 5 6 ~])
232 > -.a
233 n=6
235 > =b ~(nap to a)
236 > -.b
237 n=2
239 > a
240 [n=6 l={} r={5 4 3 2 1}]
242 > b
243 [n=2 l=[n=4 l={5} r={3}] r=[n=1 l={} r={}]]
245 > `(qeu)`b
246 {5 4 3 2 1}
248 > `(qeu)`a
249 {6 5 4 3 2 1}
250```
252---
253### `+-nip:to`
255Removes the root of queue `a`, producing the resulting queue.
257#### Accepts
259`a` is a queue.
261#### Produces
263A queue.
265#### Source
267```hoon
268 +- nip
269 |- ^+ a
270 ?~ a ~
271 ?~ l.a r.a
272 ?~ r.a l.a
273 ?: (vor n.l.a n.r.a)
274 [n.l.a l.l.a $(l.a r.l.a)]
275 [n.r.a $(r.a l.r.a) r.r.a]
276```
278#### Examples
280```
281 > =a (~(gas to `(qeu @)`~) `(list @)`[1 2 3 4 5 6 ~])
282 > a
283 [n=6 l={} r={5 4 3 2 1}]
285 > ~(nip to a)
286 [n=2 l=[n=4 l={5} r={3}] r=[n=1 l={} r={}]]
287```
289---
290### `+-put:to`
292Insert
294Accept any noun `b` and adds to queue `a` as the head, producing the
295resulting queue.
297#### Accepts
299`a` is a queue.
301`b` is any noun.
303#### Produces
305A queue.
307#### Source
309```hoon
310 +- put
311 |* b=*
312 |- ^+ a
313 ?~ a
314 [b ~ ~]
315 bal(a a(l $(a l.a)))
316```
318#### Examples
320```
321 > =a (~(gas to `(qeu @)`~) `(list @)`[3 1 2 4 5 6 ~])
322 > `(qeu)`(~(put to a) 7)
323 {7 6 5 4 2 1 3}
324```
326---
327### `+-tap:to`
329Queue to list
331Produces queue `a` as a list from front to back.
333#### Accepts
335`a` is a queue.
337#### Produces
339A list.
341#### Source
343```hoon
344 +- tap
345 =| b=(list _?>(?=(^ a) n.a))
346 |- ^+ b
347 =+ 0 :: hack for jet match
348 ?~ a
349 b
350 $(a r.a, b [n.a $(a l.a)])
351```
353#### Examples
355```
356 > =a (~(gas to `(qeu @)`~) [3 1 2 4 5 6 ~])
357 > `*`a
358 [6 0 2 [4 [5 0 0] 0] 1 0 3 0 0]
359 > ~(tap to a)
360 ~[3 1 2 4 5 6]
361```
363---
364### `+-top:to`
366Produce head
368Produces the head of queue `a` as a `unit`.
370#### Accepts
372`a` is a queue.
374#### Produces
376A unit.
378#### Source
380```hoon
381 +- top
382 |- ^- (unit _?>(?=(^ a) n.a))
383 ?~ a ~
384 ?~(r.a [~ n.a] $(a r.a))
385```
387#### Examples
389```
390 > =a (~(gas to `(qeu @)`~) `(list @)`[1 2 3 4 5 6 ~])
391 > ~(top to a)
392 [~ u=1]
393```
395#### Discussion
397An empty queue has no head.
399---