@@ -8,27 +8,23 @@ navhome: /docs/
11−Computes the bit-wise logical OR of two [atom]()s, `a` and `b`, producing an
11+Computes the bitwise logical OR of two atoms, `a` and `b`, producing an atom.
14−Accepts
13+#### Accepts
17`a` is an atom
15`a` is an atom
19`b` is an atom
17`b` is an atom
21−Produces
19+#### Produces
29− ++ con :: binary or
25+ ++ con
31− |= {a/@ b/@}
27+ |= [a=@ b=@]
32 =+ [c=0 d=0]
28 =+ [c=0 d=0]
34 ?: ?&(=(0 a) =(0 b)) d
30 ?: ?&(=(0 a) =(0 b)) d
@@ -43,22 +39,58 @@ Source
46−Examples
42+#### Examples
49 > (con 0b0 0b1)
44 > (con 0b0 0b1)
51 > (con 0 1)
47 > (con 0 1)
53 > (con 0 0)
50 > (con 0 0)
55 > `@ub`(con 0b1111.0000 0b1.0011)
53 > `@ub`(con 0b1111.0000 0b1.0011)
56 0b1111.0011
54 0b1111.0011
57 > (con 4 4)
56 > (con 4 4)
59 > (con 10.000 234)
59 > (con 10.000 234)
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.
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.
86+ 0b1100 :: 12 (sample)
87+ 0b1100 :: 12 (product)
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.
@@ -66,28 +98,24 @@ Examples
69−Computes the bit-wise logical AND of two atoms `a` and `b`, producing an
101+Computes the bitwise logical AND of two atoms, `a` and `b`, producing an atom.
72−Accepts
103+#### Accepts
75`a` is an atom.
105`a` is an atom.
77`b` is an atom.
107`b` is an atom.
79−Produces
109+#### Produces
87− ++ dis :: binary and
115+ ++ dis
89− |= {a/@ b/@}
117+ |= [a=@ b=@]
90− =| {c/@ d/@}
118+ =| [c=@ d=@]
92 ?: ?|(=(0 a) =(0 b)) d
120 ?: ?|(=(0 a) =(0 b)) d
@@ -101,53 +129,75 @@ Source
104−Examples
132+#### Examples
111 > `@ub`(dis 9 5)
140 > `@ub`(dis 9 5)
113 > (dis 9 5)
143 > (dis 9 5)
115 > `@ub`534
146 > `@ub`534
116 0b10.0001.0110
147 0b10.0001.0110
117 > `@ub`987
149 > `@ub`987
118 0b11.1101.1011
150 0b11.1101.1011
119 > `@ub`(dis 534 987)
152 > `@ub`(dis 534 987)
120 0b10.0001.0010
153 0b10.0001.0010
121 > (dis 534 987)
155 > (dis 534 987)
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.
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.
169+ 0b1000 :: 8 (sample)
170+ 0b1100 :: 12 (sample)
171+ 0b1000 :: 8 (product)
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.
127### `++mix`
180### `++mix`
129Binary XOR
182Binary XOR
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.
133−Accepts
186+#### Accepts
136`a` is an atom
188`a` is an atom
138`b` is an atom
190`b` is an atom
140−Produces
192+#### Produces
145−Source
196+#### Source
148− ++ mix :: binary xor
198+ ++ mix
150− |= {a/@ b/@}
200+ |= [a=@ b=@]
152 =+ [c=0 d=0]
202 =+ [c=0 d=0]
@@ -159,69 +209,140 @@ Source
159 d (add d (lsh 0 c =((end 0 1 a) (end 0 1 b))))
209 d (add d (lsh 0 c =((end 0 1 a) (end 0 1 b))))
162−Examples
212+#### Examples
169 > `@ub`(mix 2 3)
220 > `@ub`(mix 2 3)
171 > (mix 2 3)
223 > (mix 2 3)
173 > `@ub`(mix 2 2)
226 > `@ub`(mix 2 2)
175 > (mix 2 2)
229 > (mix 2 2)
238+ > `@ub`(mix 534 987)
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.
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.
254+ 0b1000 :: 8 (sample)
255+ 0b1100 :: 12 (sample)
256+ 0b100 :: 4 (product)
181### `++not`
259### `++not`
183Binary NOT
261Binary NOT
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`
188−Accepts
266+#### Accepts
191−`a` is a block size (see `++bloq`).
268+`a` is a block size (see [`bloq`](../1c)).
193`b` is an atom.
270`b` is an atom.
195`c` is an atom.
272`c` is an atom.
197−Produces
274+#### Produces
200−An atom.
276+An atom.
202−Source
278+#### Source
205− ++ not |= {a/bloq b/@ c/@} :: binary not (sized)
280+ ++ not |= [a=bloq b=@ c=@]
206 (mix c (dec (bex (mul b (bex a)))))
281 (mix c (dec (bex (mul b (bex a)))))
209−Examples
284+#### Examples
212 > `@ub`24
286 > `@ub`24
214 > (not 0 5 24)
289 > (not 0 5 24)
218 > (not 2 5 24)
295 > (not 2 5 24)
219 1.048.551
296 1.048.551
220 > (not 2 5 1.048.551)
298 > (not 2 5 1.048.551)
222 > (not 1 1 (not 1 1 10))
301 > (not 1 1 (not 1 1 10))
306+In computing in general, the bitwise operation NOT simply turns a binary
307+number's `0`s into `1`s, and vice versa.
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`.
315+ > `@ub`(not 2 1 0b111)
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`,
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`.
329+ > `@ub`(not 3 1 0b111)
335+This works when going to a smaller block size, too.
337+ > `@ub`(not 1 1 0b1011)
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.