git.iko.soy/urbit.org
on master help sign in
Merge pull request #281 from urbit/rmariani-patch-13
a88de8bJoshua Reagan
docs/hoon/library/2f.md+216−73
compare with master
unifiedsplit
@@ -6,30 +6,25 @@ navhome: /docs/
6# 2f: noun ordering
6# 2f: noun ordering
7### `++aor`
7### `++aor`
8
8
9−Alphabetic order
9+Alphabetical order
10
10
11−Computes whether `a` and `b` are in alphabetical order, producing a
11+Computes whether `a` and `b` are in alphabetical order, producing a flag.
12−boolean.
13
12
14−Accepts
13+#### Accepts
15−-------
16
14
17`a` is a noun.
15`a` is a noun.
18
16
19`b` is a noun.
17`b` is a noun.
20
18
21−Produces
19+#### Produces
22−--------
23
20
24−A boolean atom.
21+A flag.
25
22
23+#### Source
26
24
27−Source
28−------
29−
30− ++ aor :: a-order
25+ ++ aor
31 ~/ %aor
26 ~/ %aor
32− |= {a/* b/*}
27+ |= [a=* b=*]
33 ^- ?
28 ^- ?
34 ?: =(a b) &
29 ?: =(a b) &
35 ?. ?=(@ a)
30 ?. ?=(@ a)
@@ -44,24 +39,32 @@ Source
44 $(a (rsh 3 1 a), b (rsh 3 1 b))
39 $(a (rsh 3 1 a), b (rsh 3 1 b))
45 (lth c d)
40 (lth c d)
46
41
47−
48−Examples
42+#### Examples
49−--------
50
43
51 > (aor 'a' 'b')
44 > (aor 'a' 'b')
52 %.y
45 %.y
46+
53 > (aor 'b' 'a')
47 > (aor 'b' 'a')
54 %.n
48 %.n
49+
50+ > (aor 'a' 'a')
51+ %.y
52+
55 > (aor "foo" "bar")
53 > (aor "foo" "bar")
56 %.n
54 %.n
55+
57 > (aor "bar" "foo")
56 > (aor "bar" "foo")
58 %.y
57 %.y
58+
59 > (aor "abcdefz" "abcdefa")
59 > (aor "abcdefz" "abcdefa")
60 %.n
60 %.n
61+
61 > (aor "abcdefa" "abcdefz")
62 > (aor "abcdefa" "abcdefz")
62 %.y
63 %.y
64+
63 > (aor 10.000 17.000)
65 > (aor 10.000 17.000)
64 %.y
66 %.y
67+
65 > (aor 10 9)
68 > (aor 10 9)
66 %.n
69 %.n
67
70
@@ -72,27 +75,23 @@ Examples
72
75
73Numeric order
76Numeric order
74
77
75−Computes whether `a` and `b` are in ascending numeric order, producing a
78+Computes whether `a` and `b` are in ascending numeric order, producing a flag.
76−boolean.
77
79
78−Accepts
80+#### Accepts
79−-------
80
81
81`a` is a noun.
82`a` is a noun.
82
83
83`b` is a noun.
84`b` is a noun.
84
85
85−Produces
86+#### Produces
86−--------
87
87
88−A boolean atom.
88+A flag.
89
89
90−Source
90+#### Source
91−------
92
91
93− ++ dor :: d-order
92+ ++ dor
94 ~/ %dor
93 ~/ %dor
95− |= {a/* b/*}
94+ |= [a=* b=*]
96 ^- ?
95 ^- ?
97 ?: =(a b) &
96 ?: =(a b) &
98 ?. ?=(@ a)
97 ?. ?=(@ a)
@@ -104,22 +103,34 @@ Source
104 (lth a b)
103 (lth a b)
105
104
106
105
107−Examples
106+#### Examples
108−--------
109
107
110 > (dor 1 2)
108 > (dor 1 2)
111 %.y
109 %.y
110+
112 > (dor 2 1)
111 > (dor 2 1)
113 %.n
112 %.n
113+
114 > (dor ~[1 2 3] ~[1 2 4])
114 > (dor ~[1 2 3] ~[1 2 4])
115 %.y
115 %.y
116+
116 > (dor ~[1 2 4] ~[1 2 3])
117 > (dor ~[1 2 4] ~[1 2 3])
117 %.n
118 %.n
119+
118− > (dor (limo ~[99 100 10.000]) ~[99 101 10.000])
120+ > (dor `(list @)`~[99 100 10.000] ~[99 101 10.000])
119 %.y
121 %.y
122+
120− > (dor ~[99 101 10.999] (limo ~[99 100 10.000]))
123+ > (dor ~[99 101 10.999] `(list @)`~[99 100 10.000])
121 %.n
124 %.n
122
125
126+#### Discussion
127+
128+If `a` and `b` are both atoms, `dor` is equivalent to [`lte`](../1a). If they're
129+cells, `dor` recurses on the heads, and then if the heads are the same it checks
130+the tails.
131+
132+If one sample is a cell and the other is an atom, the cell sample is treated as
133+"greater."
123
134
124
135
125***
136***
@@ -127,26 +138,27 @@ Examples
127
138
128Hash order
139Hash order
129
140
130−XX revisit
141+Computes whether of `(mug a)` and `(mug b)` are in ascending numeric order,
142+producing a flag. If the `mug` hashes are equal, `a` and `b` are compared by
143+`dor` instead.
144+
145+[`mug`](../2e) is the the 31-bit nonzero FNV-1a hash algorithm.
131
146
132−Accepts
147+#### Accepts
133−-------
134
148
135`a` is a noun.
149`a` is a noun.
136
150
137`b` is a noun.
151`b` is a noun.
138
152
139−Produces
153+#### Produces
140−--------
141
154
142−A boolean atom.
155+A flag.
143
156
144−Source
157+#### Source
145−------
146
158
147− ++ gor :: g-order
159+ ++ gor
148 ~/ %gor
160 ~/ %gor
149− |= {a/* b/*}
161+ |= [a=* b=*]
150 ^- ?
162 ^- ?
151 =+ [c=(mug a) d=(mug b)]
163 =+ [c=(mug a) d=(mug b)]
152 ?: =(c d)
164 ?: =(c d)
@@ -154,61 +166,77 @@ Source
154 (lth c d)
166 (lth c d)
155
167
156
168
157−Examples
169+#### Examples
158−--------
159
170
160 > (gor 'd' 'c')
171 > (gor 'd' 'c')
161 %.y
172 %.y
173+
162 > 'd'
174 > 'd'
163 'd'
175 'd'
176+
164 > 'c'
177 > 'c'
178+ 'c'
179+
165 > `@ud`'d'
180 > `@ud`'d'
166 100
181 100
182+
167 > `@ud`'c'
183 > `@ud`'c'
168 99
184 99
185+
169− > (mug 'd')
186+ > (mug 'd')
170 1.628.185.714
187 1.628.185.714
188+
171 > (mug 'c')
189 > (mug 'c')
172 1.712.073.811
190 1.712.073.811
191+
173 > (gor 'd' 'c')
192 > (gor 'd' 'c')
174 %.y
193 %.y
194+
175 > (gor 'c' 'd')
195 > (gor 'c' 'd')
176 %.n
196 %.n
197+
177 > (gor "foo" "bar")
198 > (gor "foo" "bar")
178 %.n
199 %.n
200+
179− > (gor (some 10) (limo [1 2 3 ~]))
201+ > (gor (some 10) `(list @)`[1 2 3 ~])
180 %.n
202 %.n
181
203
204+#### Discussion
182
205
206+`map`s use `gor` on the key for horizontal ordering and `vor` for
207+vertical order. `map`s only look at the keys (the head of the key-value pair
208+elements) for ordering.
183
209
184***
210***
185### `++hor`
211### `++hor`
186
212
187−Hash order
213+Horizontal hash order
214+
215+If `a` and `b` are atoms, they are computed as samples of `gor`, producing a
216+flag.
188
217
189−XX revisit
218+If `a` and `b` are cells, `hor` checks to see if their heads are equal. If their
219+heads are equal, `gor` is computed on their tails, producing a flag. If their
220+heads are not equal, `gor` is computed on their heads, producing a flag.
190
221
191−Recursive hash comparator gate.
222+If `a` is an atom and `b` is not, then `%.y` is produced. If `b` is an atom and
223+`a` is not, `%.n` is produced.
192
224
193−Accepts
225+#### Accepts
194−-------
195
226
196`a` is a noun.
227`a` is a noun.
197
228
198`b` is a noun.
229`b` is a noun.
199
230
200−Produces
231+#### Produces
201−--------
202
232
203−A boolean atom.
233+A flag.
204
234
235+#### Source
205
236
206−Source
207−------
208−
209− ++ hor :: h-order
237+ ++ hor
210 ~/ %hor
238 ~/ %hor
211− |= {a/* b/*}
239+ |= [a=* b=*]
212 ^- ?
240 ^- ?
213 ?: ?=(@ a)
241 ?: ?=(@ a)
214 ?. ?=(@ b) &
242 ?. ?=(@ b) &
@@ -217,46 +245,144 @@ Source
217 ?: =(-.a -.b)
245 ?: =(-.a -.b)
218 (gor +.a +.b)
246 (gor +.a +.b)
219 (gor -.a -.b)
247 (gor -.a -.b)
220− ::
221
248
222
249
223−Examples
250+#### Examples
224−--------
225
251
226 > (hor . 1)
252 > (hor . 1)
227 %.n
253 %.n
254+
228 > (hor 1 2)
255 > (hor 1 2)
229 %.y
256 %.y
257+
230 > (hor "abc" "cba")
258 > (hor "abc" "cba")
231 %.y
259 %.y
260+
232 > (hor 'c' 'd')
261 > (hor 'c' 'd')
233 %.n
262 %.n
234
263
264+ > (hor 100 [1 1])
265+ %.y
266+
267+ > (hor [1 1] 100)
268+ %.n
269+
270+ > (hor 500.000.000 "foo")
271+ %.y
272+
273+ > (hor "foo" 500.000.000)
274+ %.n
275+
276+ > (hor 0 "foo")
277+ %.y
278+
279+ > (gor `(list @)`[0 ~] 1)
280+ %.n
281+
282+ > (hor `(list @)`[50 500 5.000 ~] 1)
283+ %.n
284+
235
285
286+#### Discussion
287+
288+Sets (+set, +in) use `hor` for their horizontal order and `vor` for their
289+vertical order. See [`apt:in`](../2h) to see how a set verifies its correctness.
290+`vor` is used to verify.
291+
292+***
293+### `++lor`
294+
295+Leg order
296+
297+Computes whether the corresponding legs of `a` and `b` are in ascending
298+numeric order, producing a flag.
299+
300+#### Accepts
301+
302+`a` is a noun.
303+
304+`b` is a noun.
305+
306+#### Accepts
307+
308+A flag.
309+
310+#### Source
311+
312+ ++ lor
313+ ~/ %lor
314+ |= [a=* b=*]
315+ ^- ?
316+ ?: =(a b) &
317+ ?@ a
318+ ?^ b &
319+ (lth a b)
320+ ?: =(-.a -.b)
321+ $(a +.a, b +.b)
322+ $(a -.a, b -.b)
323+
324+
325+#### Examples
326+
327+ > (lor 1 2)
328+ %.y
329+
330+ > (lor 2 1)
331+ %.n
332+
333+ > (lor 9 [1 2])
334+ %.y
335+
336+ > (lor `(list @)`[1 2 3 ~] `(list @)`[1 2 3 4 ~])
337+ %.y
338+
339+ > (lor `(list @)`[1 2 3 ~] `(list @)`[1 2 2 ~])
340+ %.n
341+
342+ > (lor `(list @)`[1 2 3 ~] `(list @)`[2 2 ~])
343+ %.y
344+
345+ > (lor [2 2 5] [1 5 9 8])
346+ %.n
347+
348+ > (lor [1 5 8] [1 5 9 8])
349+ %.y
350+
351+ > (lor [1 2 3] [1 2])
352+ !! exit
353+
354+
355+#### Discussion
356+
357+`lor` is no longer used internally.
236
358
237***
359***
238### `++vor`
360### `++vor`
239
361
240−Double hash comparator gate.
362+Vertical order
363+
364+Computes whether the double-hashes `(mug (mug a))` and `(mug (mug b))` are in
365+ascending numeric order, producing a flag. If the double-`mug` hashes are
366+equal, `a` and `b` are compared by `dor` instead.
241
367
242−XX revisit
368+[`mug`](../2e) is the the 31-bit nonzero FNV-1a hash algorithm.
243
369
370+
244−Accepts
371+#### Accepts
245−-------
246
372
247`a` is a noun
373`a` is a noun
248
374
249`b` is a noun
375`b` is a noun
250
376
251−Produces
377+#### Produces
252−-------
378+
379+A flag.
253
380
254−Source
381+#### Source
255−------
256
382
257− ++ vor :: v-order
383+ ++ vor
258 ~/ %vor
384 ~/ %vor
259− |= {a/* b/*}
385+ |= [a=* b=*]
260 ^- ?
386 ^- ?
261 =+ [c=(mug (mug a)) d=(mug (mug b))]
387 =+ [c=(mug (mug a)) d=(mug (mug b))]
262 ?: =(c d)
388 ?: =(c d)
@@ -264,16 +390,33 @@ Source
264 (lth c d)
390 (lth c d)
265
391
266
392
267−Examples
393+#### Examples
268−--------
269
394
270 > (vor 'f' 'g')
395 > (vor 'f' 'g')
271 %.y
396 %.y
397+
398+ > [(mug 'f') (mug 'g')]
399+ [1.661.740.952 1.644.963.335]
400+
401+ > [(mug (mug 'f')) (mug (mug 'g'))]
402+ [261.421.509 1.861.258.547]
403+
272 > (vor 'a' 'z')
404 > (vor 'a' 'z')
273 %.n
405 %.n
406+
274 > (vor 43.326 41.106)
407 > (vor 43.326 41.106)
275 %.n
408 %.n
276
409
277
410
411+#### Discussion
412+
413+Maps, sets, and queues all use `vor` to check for vertical ordering. Maps and
414+sets also use `gor` and `hor` for horizontal order, respectively, but queues use
415+vertical ordering alone.
416+
417+Since hashing removes correlation, double-`mug`ging with `vor` removes
418+correlation with single-`mug`ged `hor`. Vertical order becomes uncorrelated
419+with horizontal order.
420+
278
421
279***
422***