reference/library/2d.md · urbit.org

git.iko.soy/urbit.org

on 91ef98f help sign in

urbit.org/reference/library/2d.md

372 lines 6.8 kB history raw

1+++

2title = "2d: Bit Logic"

3weight = 7

4template = "doc.html"

5+++

6### `++con`

8Binary OR

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

12#### Accepts

14`a` is an atom

16`b` is an atom

18#### Produces

20An atom.

22#### Source

24```

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 ==

41```

43#### Examples

45```

46 > (con 0b0 0b1)

47 1

49 > (con 0 1)

50 1

52 > (con 0 0)

53 0

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

56 0b1111.0011

58 > (con 4 4)

59 4

61 > (con 10.000 234)

62 10.234

64 > `@ub`534

65 0b10.0001.0110

67 > `@ub`987

68 0b11.1101.1011

70 > `@ub`(con 534 987)

71 0b11.1101.1111

73 > (con 534 987)

74 991

75```

77#### Discussion

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

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

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

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

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

85its samples and its product are stacked.

87```

88 0b1000 :: 8 (sample)

89 0b1100 :: 12 (sample)

90 0b1100 :: 12 (product)

91```

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

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

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

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

97bitwise AND is the logical conjunction.

100---

101### `++dis`

102

103Binary AND

104

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

107#### Accepts

109`a` is an atom.

111`b` is an atom.

113#### Produces

115An atom.

117#### Source

119```

120 ++ dis

121 ~/ %dis

122 |= [a=@ b=@]

123 =| [c=@ d=@]

124 |- ^- @

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

126 %= $

127 a (rsh 0 1 a)

128 b (rsh 0 1 b)

129 c +(c)

130 d %+ add d

131 %^ lsh 0 c

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

133 =(0 (end 0 1 b))

134 ==

135 ==

136```

137

138#### Examples

139

140```

141 > `@ub`9

142 0b1001

143

144 > `@ub`5

145 0b101

146

147 > `@ub`(dis 9 5)

148 0b1

149

150 > (dis 9 5)

151 1

152

153 > `@ub`534

154 0b10.0001.0110

155

156 > `@ub`987

157 0b11.1101.1011

158

159 > `@ub`(dis 534 987)

160 0b10.0001.0010

161

162 > (dis 534 987)

163 530

164```

165

166#### Discussion

167

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

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

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

171corresponding product bit is set to 0.

172

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

174its samples and its product are stacked.

175

176```

177 0b1000 :: 8 (sample)

178 0b1100 :: 12 (sample)

179 0b1000 :: 8 (product)

180```

181

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

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

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

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

186bitwise AND is the logical conjunction.

187

188---

189### `++mix`

190

191Binary XOR

192

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

195#### Accepts

197`a` is an atom

199`b` is an atom

201#### Produces

203An atom.

205#### Source

207```

208 ++ mix

209 ~/ %mix

210 |= [a=@ b=@]

211 ^- @

212 =+ [c=0 d=0]

213 |-

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

215 %= $

216 a (rsh 0 1 a)

217 b (rsh 0 1 b)

218 c +(c)

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

220 ==

221```

222

223#### Examples

224

225```

226 > `@ub`2

227 0b10

228

229 > `@ub`3

230 0b11

231

232 > `@ub`(mix 2 3)

233 0b1

234

235 > (mix 2 3)

236 1

237

238 > `@ub`(mix 2 2)

239 0b0

240

241 > (mix 2 2)

242 0

243

244 > `@ub`534

245 0b10.0001.0110

246

247 > `@ub`987

248 0b11.1101.1011

249

250 > `@ub`(mix 534 987)

251 0b1.1100.1101

252

253 > (mix 534 987)

254 461

255```

256

257#### Discussion

258

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

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

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

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

263

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

265its samples and its product are stacked.

266

267```

268 0b1000 :: 8 (sample)

269 0b1100 :: 12 (sample)

270 0b100 :: 4 (product)

271```

272

273---

274### `++not`

275

276Binary NOT

277

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

279of `c`.

280

281#### Accepts

282

283`a` is a block size (see [`bloq`](@/docs/reference/library/1c.md)).

285`b` is an atom.

287`c` is an atom.

289#### Produces

291An atom.

293#### Source

295```

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

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

298```

299

300#### Examples

301

302```

303 > `@ub`24

304 0b1.1000

305

306 > (not 0 5 24)

307 7

308

309 > `@ub`7

310 0b111

311

312 > (not 2 5 24)

313 1.048.551

314

315 > (not 2 5 1.048.551)

316 24

317

318 > (not 1 1 (not 1 1 10))

319 10

320```

321

322#### Discussion

323

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

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

326

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

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

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

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

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

332

333```

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

335 0b1000

336

337 > `@u`0b1000

338 8

339```

340

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

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

343or `8` in decimal.

344

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

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

347again, treated as `0`.

348

349```

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

351 0b1111.1000

352

353 > `@u`0b1111.1000

354 248

355```

356

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

358

359```

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

361 0b100

362

363 > `@u`0b100

364 4

365```

366

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

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

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

370

371

372---