hoon/reference/stdlib/2d.md · urbit.org

git.iko.soy/urbit.org

on c19b089 help sign in

urbit.org/hoon/reference/stdlib/2d.md

373 lines 6.8 kB history raw

1+++

2title = "2d: Bit Logic"

3weight = 7

4template = "doc.html"

5+++

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```hoon

26 ++ con

27 ~/ %con

28 |= [a=@ b=@]

29 =+ [c=0 d=0]

30 |- ^- @

31 ?: ?&(=(0 a) =(0 b)) d

32 %= $

33 a (rsh 0 1 a)

34 b (rsh 0 1 b)

35 c +(c)

36 d %+ add d

37 %^ lsh 0 c

38 ?& =(0 (end 0 1 a))

39 =(0 (end 0 1 b))

40 ==

41 ==

42```

44#### Examples

46```

47 > (con 0b0 0b1)

48 1

50 > (con 0 1)

51 1

53 > (con 0 0)

54 0

56 > `@ub`(con 0b1111.0000 0b1.0011)

57 0b1111.0011

59 > (con 4 4)

60 4

62 > (con 10.000 234)

63 10.234

65 > `@ub`534

66 0b10.0001.0110

68 > `@ub`987

69 0b11.1101.1011

71 > `@ub`(con 534 987)

72 0b11.1101.1111

74 > (con 534 987)

75 991

76```

78#### Discussion

80`con` performs the bitwise operation OR, a concept that's general to computing.

81It compares each bit of its first sample to the corresponding bit of its second

82sample. If either bit is 1, the corresponding product bit is set

83to 1. Otherwise, the corresponding product bit is set to 0.

85Take the example of `(con 8 12)`. It's easy to see how this operation works when

86its samples and its product are stacked.

88```

89 0b1000 :: 8 (sample)

90 0b1100 :: 12 (sample)

91 0b1100 :: 12 (product)

92```

94Note that the names `con` (conjunction) for OR and `dis` (disjunction) for AND

95are given to opposite operators in Hoon when compared to other computing

96contexts. That's because `0` is true in Hoon and `1` is false. Outside of Hoon,

97where `0` is false and `1` is true, bitwise OR is the logical disjunction and

98bitwise AND is the logical conjunction.

100

101---

102### `++dis`

103

104Binary AND

105

106Computes the bitwise logical AND of two atoms, `a` and `b`, producing an atom.

108#### Accepts

110`a` is an atom.

112`b` is an atom.

114#### Produces

116An atom.

118#### Source

120```hoon

121 ++ dis

122 ~/ %dis

123 |= [a=@ b=@]

124 =| [c=@ d=@]

125 |- ^- @

126 ?: ?|(=(0 a) =(0 b)) d

127 %= $

128 a (rsh 0 1 a)

129 b (rsh 0 1 b)

130 c +(c)

131 d %+ add d

132 %^ lsh 0 c

133 ?| =(0 (end 0 1 a))

134 =(0 (end 0 1 b))

135 ==

136 ==

137```

138

139#### Examples

140

141```

142 > `@ub`9

143 0b1001

144

145 > `@ub`5

146 0b101

147

148 > `@ub`(dis 9 5)

149 0b1

150

151 > (dis 9 5)

152 1

153

154 > `@ub`534

155 0b10.0001.0110

156

157 > `@ub`987

158 0b11.1101.1011

159

160 > `@ub`(dis 534 987)

161 0b10.0001.0010

162

163 > (dis 534 987)

164 530

165```

166

167#### Discussion

168

169`dis` performs the bitwise AND, an operation general to computing. It compares

170each bit of its first sample to the corresponding bit of its second sample. If

171both bits are 1, the corresponding product bit is set to 1. Otherwise, the

172corresponding product bit is set to 0.

173

174Take the example of `(dis 8 12)`. It's easy to see how this operation works when

175its samples and its product are stacked.

176

177```

178 0b1000 :: 8 (sample)

179 0b1100 :: 12 (sample)

180 0b1000 :: 8 (product)

181```

182

183Note that the names `dis` (disjunction) for AND and `con` (conjuction) for OR

184are given to opposite operators in Hoon when compared to other computing

185contexts. That's because `0` is true in Hoon and `1` is false. Outside of Hoon,

186where `0` is false and `1` is true, bitwise OR is the logical disjunction and

187bitwise AND is the logical conjunction.

188

189---

190### `++mix`

191

192Binary XOR

193

194Produces the bitwise logical XOR of two atoms, `a` and `b`, producing an atom.

196#### Accepts

198`a` is an atom

200`b` is an atom

202#### Produces

204An atom.

206#### Source

208```hoon

209 ++ mix

210 ~/ %mix

211 |= [a=@ b=@]

212 ^- @

213 =+ [c=0 d=0]

214 |-

215 ?: ?&(=(0 a) =(0 b)) d

216 %= $

217 a (rsh 0 1 a)

218 b (rsh 0 1 b)

219 c +(c)

220 d (add d (lsh 0 c =((end 0 1 a) (end 0 1 b))))

221 ==

222```

223

224#### Examples

225

226```

227 > `@ub`2

228 0b10

229

230 > `@ub`3

231 0b11

232

233 > `@ub`(mix 2 3)

234 0b1

235

236 > (mix 2 3)

237 1

238

239 > `@ub`(mix 2 2)

240 0b0

241

242 > (mix 2 2)

243 0

244

245 > `@ub`534

246 0b10.0001.0110

247

248 > `@ub`987

249 0b11.1101.1011

250

251 > `@ub`(mix 534 987)

252 0b1.1100.1101

253

254 > (mix 534 987)

255 461

256```

257

258#### Discussion

259

260`mix` performs the bitwise XOR (exclusive-OR), an operation that's general to

261computing. compares each bit of its first sample to the corresponding bit of its

262second sample. If one bit is 0 and the other bit is 1, the corresponding product

263bit is set to 1. Otherwise, the corresponding product bit is set to 0.

264

265Take the example of `(mix 8 12)`. It's easy to see how this operation works when

266its samples and its product are stacked.

267

268```

269 0b1000 :: 8 (sample)

270 0b1100 :: 12 (sample)

271 0b100 :: 4 (product)

272```

273

274---

275### `++not`

276

277Binary NOT

278

279Computes the bitwise logical NOT of the bottom `b` blocks of size `a`

280of `c`.

281

282#### Accepts

283

284`a` is a block size (see [`bloq`](@/docs/hoon/reference/stdlib/1c.md)).

286`b` is an atom.

288`c` is an atom.

290#### Produces

292An atom.

294#### Source

296```hoon

297 ++ not |= [a=bloq b=@ c=@]

298 (mix c (dec (bex (mul b (bex a)))))

299```

300

301#### Examples

302

303```

304 > `@ub`24

305 0b1.1000

306

307 > (not 0 5 24)

308 7

309

310 > `@ub`7

311 0b111

312

313 > (not 2 5 24)

314 1.048.551

315

316 > (not 2 5 1.048.551)

317 24

318

319 > (not 1 1 (not 1 1 10))

320 10

321```

322

323#### Discussion

324

325In computing in general, the bitwise operation NOT simply turns a binary

326number's `0`s into `1`s, and vice versa.

327

328In Hoon, we ask for a little more information to use `not`, because binary

329numbers have a number of implicit leading zeroes differently depending on on

330their [block size](@/docs/hoon/reference/stdlib/1c.md). Decimal `7`, for example, is `0b111` in binary, and

331has one implicit zero in the context of a block of size `2`, which has a

332bitwidth of 4. Let's try `not` on `7` with a single block of size `2`.

333

334```

335 > `@ub`(not 2 1 0b111)

336 0b1000

337

338 > `@u`0b1000

339 8

340```

341

342This happened because `0b111` is considered as `0b0111` by the `not` operator

343when dealing with a single block of size `2`. The NOT of `7`, then, is `0b1000`,

344or `8` in decimal.

345

346When we pass `not` a single block of size `3`, there is a bitwidth of 8 to

347fill with binary information. So the remaining leading digits of `0b111` are,

348again, treated as `0`.

349

350```

351 > `@ub`(not 3 1 0b111)

352 0b1111.1000

353

354 > `@u`0b1111.1000

355 248

356```

357

358This works when going to a smaller block size, too.

359

360```

361 > `@ub`(not 1 1 0b1011)

362 0b100

363

364 > `@u`0b100

365 4

366```

367

368What's happening here may not be readily apparent. But we're only flipping the

369last block of size `1` (bitwidth 2) of the binary `0b111`. That is, we leave

370the "0b1" piece just the same and manipulate the "11" that the number ends with.

371

372

373---