git.iko.soy/urbit.org
on 7fa97bd help sign in
urbit.org/docs/reference/library/2d.umd
348 lines 6.8 kB history raw
1---
2navhome: /docs/
3---
6# 2d: bit logic
7### `++con`
9Binary OR
11Computes the bitwise logical OR of two atoms, `a` and `b`, producing an atom.
13#### Accepts
15`a` is an atom
17`b` is an atom
19#### Produces
21An atom.
23#### Source
25 ++ con
26 ~/ %con
27 |= [a=@ b=@]
28 =+ [c=0 d=0]
29 |- ^- @
30 ?: ?&(=(0 a) =(0 b)) d
31 %= $
32 a (rsh 0 1 a)
33 b (rsh 0 1 b)
34 c +(c)
35 d %+ add d
36 %^ lsh 0 c
37 ?& =(0 (end 0 1 a))
38 =(0 (end 0 1 b))
39 ==
40 ==
42#### Examples
44 > (con 0b0 0b1)
45 1
47 > (con 0 1)
48 1
50 > (con 0 0)
51 0
53 > `@ub`(con 0b1111.0000 0b1.0011)
54 0b1111.0011
56 > (con 4 4)
57 4
59 > (con 10.000 234)
60 10.234
62 > `@ub`534
63 0b10.0001.0110
65 > `@ub`987
66 0b11.1101.1011
68 > `@ub`(con 534 987)
69 0b11.1101.1111
71 > (con 534 987)
72 991
75#### Discussion
77`con` performs the bitwise operation OR, a concept that's general to computing.
78It compares each bit of its first sample to the corresponding bit of its second
79sample. If either bit is 1, the corresponding product bit is set
80to 1. Otherwise, the corresponding product bit is set to 0.
82Take the example of `(con 8 12)`. It's easy to see how this operation works when
83 its samples and its product are stacked.
85 0b1000 :: 8 (sample)
86 0b1100 :: 12 (sample)
87 0b1100 :: 12 (product)
89Note that the names `con` (conjunction) for OR and `dis` (disjunction) for AND
90are given to opposite operators in Hoon when compared to other computing
91contexts. That's because `0` is true in Hoon and `1` is false. Outside of Hoon,
92where `0` is false and `1` is true, bitwise OR is the logical disjunction and
93bitwise AND is the logical conjunction.
96***
97### `++dis`
99Binary AND
101Computes the bitwise logical AND of two atoms, `a` and `b`, producing an atom.
103#### Accepts
105`a` is an atom.
107`b` is an atom.
109#### Produces
111An atom.
113#### Source
115 ++ dis
116 ~/ %dis
117 |= [a=@ b=@]
118 =| [c=@ d=@]
119 |- ^- @
120 ?: ?|(=(0 a) =(0 b)) d
121 %= $
122 a (rsh 0 1 a)
123 b (rsh 0 1 b)
124 c +(c)
125 d %+ add d
126 %^ lsh 0 c
127 ?| =(0 (end 0 1 a))
128 =(0 (end 0 1 b))
129 ==
130 ==
132#### Examples
134 > `@ub`9
135 0b1001
137 > `@ub`5
138 0b101
140 > `@ub`(dis 9 5)
141 0b1
143 > (dis 9 5)
144 1
146 > `@ub`534
147 0b10.0001.0110
149 > `@ub`987
150 0b11.1101.1011
152 > `@ub`(dis 534 987)
153 0b10.0001.0010
155 > (dis 534 987)
156 530
159#### Discussion
161`dis` performs the bitwise AND, an operation general to computing. It compares
162each bit of its first sample to the corresponding bit of its second sample. If
163both bits are 1, the corresponding product bit is set to 1. Otherwise, the
164corresponding product bit is set to 0.
166Take the example of `(dis 8 12)`. It's easy to see how this operation works when
167its samples and its product are stacked.
169 0b1000 :: 8 (sample)
170 0b1100 :: 12 (sample)
171 0b1000 :: 8 (product)
173Note that the names `dis` (disjunction) for AND and `con` (conjuction) for OR
174are given to opposite operators in Hoon when compared to other computing
175contexts. That's because `0` is true in Hoon and `1` is false. Outside of Hoon,
176where `0` is false and `1` is true, bitwise OR is the logical disjunction and
177bitwise AND is the logical conjunction.
179***
180### `++mix`
182Binary XOR
184Produces the bitwise logical XOR of two atoms, `a` and `b`, producing an atom.
186#### Accepts
188`a` is an atom
190`b` is an atom
192#### Produces
194An atom.
196#### Source
198 ++ mix
199 ~/ %mix
200 |= [a=@ b=@]
201 ^- @
202 =+ [c=0 d=0]
203 |-
204 ?: ?&(=(0 a) =(0 b)) d
205 %= $
206 a (rsh 0 1 a)
207 b (rsh 0 1 b)
208 c +(c)
209 d (add d (lsh 0 c =((end 0 1 a) (end 0 1 b))))
210 ==
212#### Examples
214 > `@ub`2
215 0b10
217 > `@ub`3
218 0b11
220 > `@ub`(mix 2 3)
221 0b1
223 > (mix 2 3)
224 1
226 > `@ub`(mix 2 2)
227 0b0
229 > (mix 2 2)
230 0
232 > `@ub`534
233 0b10.0001.0110
235 > `@ub`987
236 0b11.1101.1011
238 > `@ub`(mix 534 987)
239 0b1.1100.1101
241 > (mix 534 987)
242 461
244#### Discussion
246`mix` performs the bitwise XOR (exclusive-OR), an operation that's general to
247computing. compares each bit of its first sample to the corresponding bit of its
248second sample. If one bit is 0 and the other bit is 1, the corresponding product
249bit is set to 1. Otherwise, the corresponding product bit is set to 0.
251Take the example of `(mix 8 12)`. It's easy to see how this operation works when
252its samples and its product are stacked.
254 0b1000 :: 8 (sample)
255 0b1100 :: 12 (sample)
256 0b100 :: 4 (product)
258***
259### `++not`
261Binary NOT
263Computes the bitwise logical NOT of the bottom `b` blocks of size `a`
264of `c`.
266#### Accepts
268`a` is a block size (see [`bloq`](../1c)).
270`b` is an atom.
272`c` is an atom.
274#### Produces
276An atom.
278#### Source
280 ++ not |= [a=bloq b=@ c=@]
281 (mix c (dec (bex (mul b (bex a)))))
284#### Examples
286 > `@ub`24
287 0b1.1000
289 > (not 0 5 24)
290 7
292 > `@ub`7
293 0b111
295 > (not 2 5 24)
296 1.048.551
298 > (not 2 5 1.048.551)
299 24
301 > (not 1 1 (not 1 1 10))
302 10
304#### Discussion
306In computing in general, the bitwise operation NOT simply turns a binary
307number's `0`s into `1`s, and vice versa.
309In Hoon, we ask for a little more information to use `not`, because binary
310numbers have a number of implicit leading zeroes differently depending on on
311their [block size](../1c). Decimal `7`, for example, is `0b111` in binary, and
312has one implicit zero in the context of a block of size `2`, which has a
313bitwidth of 4. Let's try `not` on `7` with a single block of size `2`.
315 > `@ub`(not 2 1 0b111)
316 0b1000
318 > `@u`0b1000
319 8
321This happened because `0b111` is considered as `0b0111` by the `not` operator
322when dealing with a single block of size `2`. The NOT of `7`, then, is `0b1000`,
323 or `8` in decimal.
325When we pass `not` a single block of size `3`, there is a bitwidth of 8 to
326fill with binary information. So the remaining leading digits of `0b111` are,
327again, treated as `0`.
329 > `@ub`(not 3 1 0b111)
330 0b1111.1000
332 > `@u`0b1111.1000
333 248
335This works when going to a smaller block size, too.
337 > `@ub`(not 1 1 0b1011)
338 0b100
340 > `@u`0b100
341 4
343What's happening here may not be readily apparent. But we're only flipping the
344last block of size `1` (bitwidth 2) of the binary `0b111`. That is, we leave
345the "0b1" piece just the same and manipulate the "11" that the number ends with.
348***