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

git.iko.soy/urbit.org

on 4fdc19d help sign in

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

374 lines 6.6 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 a)

34 b (rsh 0 b)

35 c +(c)

36 d %+ add d

37 %+ lsh [0 c]

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

39 =(0 (end 0 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 a)

129 b (rsh 0 b)

130 c +(c)

131 d %+ add d

132 %+ lsh [0 c]

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

134 =(0 (end 0 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.

189---

191## `++mix`

193Binary XOR

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

197#### Accepts

199`a` is an atom

201`b` is an atom

203#### Produces

205An atom.

207#### Source

209```hoon

210++ mix

211 ~/ %mix

212 |= [a=@ b=@]

213 ^- @

214 =+ [c=0 d=0]

215 |-

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

217 %= $

218 a (rsh 0 a)

219 b (rsh 0 b)

220 c +(c)

221 d (add d (lsh [0 c] =((end 0 a) (end 0 b))))

222 ==

223```

224

225#### Examples

226

227```

228 > `@ub`2

229 0b10

230

231 > `@ub`3

232 0b11

233

234 > `@ub`(mix 2 3)

235 0b1

236

237 > (mix 2 3)

238 1

239

240 > `@ub`(mix 2 2)

241 0b0

242

243 > (mix 2 2)

244 0

245

246 > `@ub`534

247 0b10.0001.0110

248

249 > `@ub`987

250 0b11.1101.1011

251

252 > `@ub`(mix 534 987)

253 0b1.1100.1101

254

255 > (mix 534 987)

256 461

257```

258

259#### Discussion

260

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

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

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

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

265

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

267its samples and its product are stacked.

268

269```

270 0b1000 :: 8 (sample)

271 0b1100 :: 12 (sample)

272 0b100 :: 4 (product)

273```

275---

277## `++not`

279Binary NOT

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

282of `c`.

283

284#### Accepts

285

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

288`b` is an atom.

290`c` is an atom.

292#### Produces

294An atom.

296#### Source

298```hoon

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

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

301```

302

303#### Examples

304

305```

306 > `@ub`24

307 0b1.1000

308

309 > (not 0 5 24)

310 7

311

312 > `@ub`7

313 0b111

314

315 > (not 2 5 24)

316 1.048.551

317

318 > (not 2 5 1.048.551)

319 24

320

321 > (not 1 1 (not 1 1 10))

322 10

323```

324

325#### Discussion

326

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

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

329

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

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

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

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

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

335

336```

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

338 0b1000

339

340 > `@u`0b1000

341 8

342```

343

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

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

346or `8` in decimal.

347

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

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

350again, treated as `0`.

351

352```

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

354 0b1111.1000

355

356 > `@u`0b1111.1000

357 248

358```

359

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

361

362```

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

364 0b100

365

366 > `@u`0b100

367 4

368```

369

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

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

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

373

374---