@@ -8,27 +8,23 @@ navhome: /docs/
88
99Binary OR
1010
11−Computes the bit-wise logical OR of two [atom]()s, `a` and `b`, producing an
12−atom.
11+Computes the bitwise logical OR of two atoms, `a` and `b`, producing an atom.
1312
14−Accepts
15−-------
13+#### Accepts
1614
1715`a` is an atom
1816
1917`b` is an atom
2018
21−Produces
22−--------
19+#### Produces
2320
2421An atom.
2522
26−Source
27−------
23+#### Source
2824
29− ++ con :: binary or
25+ ++ con
3026 ~/ %con
31− |= {a/@ b/@}
27+ |= [a=@ b=@]
3228 =+ [c=0 d=0]
3329 |- ^- @
3430 ?: ?&(=(0 a) =(0 b)) d
@@ -43,22 +39,58 @@ Source
4339 ==
4440 ==
4541
46−Examples
47−--------
42+#### Examples
4843
4944 > (con 0b0 0b1)
5045 1
46+
5147 > (con 0 1)
5248 1
49+
5350 > (con 0 0)
5451 0
52+
5553 > `@ub`(con 0b1111.0000 0b1.0011)
5654 0b1111.0011
55+
5756 > (con 4 4)
5857 4
58+
5959 > (con 10.000 234)
6060 10.234
6161
62+ > `@ub`534
63+ 0b10.0001.0110
64+
65+ > `@ub`987
66+ 0b11.1101.1011
67+
68+ > `@ub`(con 534 987)
69+ 0b11.1101.1111
70+
71+ > (con 534 987)
72+ 991
73+
74+
75+#### Discussion
76+
77+`con` performs the bitwise operation OR, a concept that's general to computing.
78+It compares each bit of its first sample to the corresponding bit of its second
79+sample. If either bit is 1, the corresponding product bit is set
80+to 1. Otherwise, the corresponding product bit is set to 0.
81+
82+Take the example of `(con 8 12)`. It's easy to see how this operation works when
83+ its samples and its product are stacked.
84+
85+ 0b1000 :: 8 (sample)
86+ 0b1100 :: 12 (sample)
87+ 0b1100 :: 12 (product)
88+
89+Note that the names `con` (conjunction) for OR and `dis` (disjunction) for AND
90+are given to opposite operators in Hoon when compared to other computing
91+contexts. That's because `0` is true in Hoon and `1` is false. Outside of Hoon,
92+where `0` is false and `1` is true, bitwise OR is the logical disjunction and
93+bitwise AND is the logical conjunction.
6294
6395
6496***
@@ -66,28 +98,24 @@ Examples
6698
6799Binary AND
68100
69−Computes the bit-wise logical AND of two atoms `a` and `b`, producing an
70−atom.
101+Computes the bitwise logical AND of two atoms, `a` and `b`, producing an atom.
71102
72−Accepts
73−-------
103+#### Accepts
74104
75105`a` is an atom.
76106
77107`b` is an atom.
78108
79−Produces
80−--------
109+#### Produces
81110
82111An atom.
83112
84−Source
85−------
113+#### Source
86114
87− ++ dis :: binary and
115+ ++ dis
88116 ~/ %dis
89− |= {a/@ b/@}
90− =| {c/@ d/@}
117+ |= [a=@ b=@]
118+ =| [c=@ d=@]
91119 |- ^- @
92120 ?: ?|(=(0 a) =(0 b)) d
93121 %= $
@@ -101,53 +129,75 @@ Source
101129 ==
102130 ==
103131
104−Examples
105−--------
132+#### Examples
106133
107134 > `@ub`9
108135 0b1001
136+
109137 > `@ub`5
110138 0b101
139+
111140 > `@ub`(dis 9 5)
112141 0b1
142+
113143 > (dis 9 5)
114144 1
145+
115146 > `@ub`534
116147 0b10.0001.0110
148+
117149 > `@ub`987
118150 0b11.1101.1011
151+
119152 > `@ub`(dis 534 987)
120153 0b10.0001.0010
154+
121155 > (dis 534 987)
122156 530
123157
124158
159+#### Discussion
160+
161+`dis` performs the bitwise AND, an operation general to computing. It compares
162+each bit of its first sample to the corresponding bit of its second sample. If
163+both bits are 1, the corresponding product bit is set to 1. Otherwise, the
164+corresponding product bit is set to 0.
165+
166+Take the example of `(dis 8 12)`. It's easy to see how this operation works when
167+its samples and its product are stacked.
168+
169+ 0b1000 :: 8 (sample)
170+ 0b1100 :: 12 (sample)
171+ 0b1000 :: 8 (product)
172+
173+Note that the names `dis` (disjunction) for AND and `con` (conjuction) for OR
174+are given to opposite operators in Hoon when compared to other computing
175+contexts. That's because `0` is true in Hoon and `1` is false. Outside of Hoon,
176+where `0` is false and `1` is true, bitwise OR is the logical disjunction and
177+bitwise AND is the logical conjunction.
125178
126179***
127180### `++mix`
128181
129182Binary XOR
130183
131−Produces the bit-wise logical XOR of `a` and `b`, producing an atom.
184+Produces the bitwise logical XOR of two atoms, `a` and `b`, producing an atom.
132185
133−Accepts
134−-------
186+#### Accepts
135187
136188`a` is an atom
137189
138190`b` is an atom
139191
140−Produces
141−--------
192+#### Produces
142193
143194An atom.
144195
145−Source
146−------
196+#### Source
147197
148− ++ mix :: binary xor
198+ ++ mix
149199 ~/ %mix
150− |= {a/@ b/@}
200+ |= [a=@ b=@]
151201 ^- @
152202 =+ [c=0 d=0]
153203 |-
@@ -159,69 +209,140 @@ Source
159209 d (add d (lsh 0 c =((end 0 1 a) (end 0 1 b))))
160210 ==
161211
162−Examples
163−--------
212+#### Examples
164213
165214 > `@ub`2
166215 0b10
216+
167217 > `@ub`3
168218 0b11
219+
169220 > `@ub`(mix 2 3)
170221 0b1
222+
171223 > (mix 2 3)
172224 1
225+
173226 > `@ub`(mix 2 2)
174227 0b0
228+
175229 > (mix 2 2)
176230 0
177231
232+ > `@ub`534
233+ 0b10.0001.0110
234+
235+ > `@ub`987
236+ 0b11.1101.1011
237+
238+ > `@ub`(mix 534 987)
239+ 0b1.1100.1101
178240
241+ > (mix 534 987)
242+ 461
243+
244+#### Discussion
245+
246+`mix` performs the bitwise XOR (exclusive-OR), an operation that's general to
247+computing. compares each bit of its first sample to the corresponding bit of its
248+second sample. If one bit is 0 and the other bit is 1, the corresponding product
249+bit is set to 1. Otherwise, the corresponding product bit is set to 0.
250+
251+Take the example of `(mix 8 12)`. It's easy to see how this operation works when
252+its samples and its product are stacked.
253+
254+ 0b1000 :: 8 (sample)
255+ 0b1100 :: 12 (sample)
256+ 0b100 :: 4 (product)
179257
180258***
181259### `++not`
182260
183261Binary NOT
184262
185−Computes the bit-wise logical NOT of the bottom `b` blocks of size `a`
263+Computes the bitwise logical NOT of the bottom `b` blocks of size `a`
186264of `c`.
187265
188−Accepts
189−-------
266+#### Accepts
190267
191−`a` is a block size (see `++bloq`).
268+`a` is a block size (see [`bloq`](../1c)).
192269
193270`b` is an atom.
194271
195272`c` is an atom.
196273
197−Produces
198−--------
274+#### Produces
199275
200−An atom.
276+An atom.
201277
202−Source
203−------
278+#### Source
204279
205− ++ not |= {a/bloq b/@ c/@} :: binary not (sized)
280+ ++ not |= [a=bloq b=@ c=@]
206281 (mix c (dec (bex (mul b (bex a)))))
207282
208283
209−Examples
210−--------
284+#### Examples
211285
212286 > `@ub`24
213287 0b1.1000
288+
214289 > (not 0 5 24)
215290 7
291+
216292 > `@ub`7
217293 0b111
294+
218295 > (not 2 5 24)
219296 1.048.551
297+
220298 > (not 2 5 1.048.551)
221299 24
300+
222301 > (not 1 1 (not 1 1 10))
223302 10
224303
304+#### Discussion
305+
306+In computing in general, the bitwise operation NOT simply turns a binary
307+number's `0`s into `1`s, and vice versa.
308+
309+In Hoon, we ask for a little more information to use `not`, because binary
310+numbers have a number of implicit leading zeroes differently depending on on
311+their [block size](../1c). Decimal `7`, for example, is `0b111` in binary, and
312+has one implicit zero in the context of a block of size `2`, which has a
313+bitwidth of 4. Let's try `not` on `7` with a single block of size `2`.
314+
315+ > `@ub`(not 2 1 0b111)
316+ 0b1000
317+
318+ > `@u`0b1000
319+ 8
320+
321+This happened because `0b111` is considered as `0b0111` by the `not` operator
322+when dealing with a single block of size `2`. The NOT of `7`, then, is `0b1000`,
323+ or `8` in decimal.
324+
325+When we pass `not` a single block of size `3`, there is a bitwidth of 8 to
326+fill with binary information. So the remaining leading digits of `0b111` are,
327+again, treated as `0`.
328+
329+ > `@ub`(not 3 1 0b111)
330+ 0b1111.1000
331+
332+ > `@u`0b1111.1000
333+ 248
334+
335+This works when going to a smaller block size, too.
336+
337+ > `@ub`(not 1 1 0b1011)
338+ 0b100
339+
340+ > `@u`0b100
341+ 4
342+
343+What's happening here may not be readily apparent. But we're only flipping the
344+last block of size `1` (bitwidth 2) of the binary `0b111`. That is, we leave
345+the "0b1" piece just the same and manipulate the "11" that the number ends with.
225346
226347
227348***