docs/reference/library/2d.udon · urbit.org

git.iko.soy/urbit.org

on c19bc7a help sign in

urbit.org/docs/reference/library/2d.udon

376 lines 6.8 kB history raw

1:- :~ navhome/'/docs/'

2 sort/'7'

3 title/'2d: Bit Logic'

4 ==

6;>

8# 2d: bit logic

10### `++con`

12Binary OR

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

16#### Accepts

18`a` is an atom

20`b` is an atom

22#### Produces

24An atom.

26#### Source

28```

29 ++ con

30 ~/ %con

31 |= [a=@ b=@]

32 =+ [c=0 d=0]

33 |- ^- @

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

35 %= $

36 a (rsh 0 1 a)

37 b (rsh 0 1 b)

38 c +(c)

39 d %+ add d

40 %^ lsh 0 c

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

42 =(0 (end 0 1 b))

43 ==

44 ==

45```

47#### Examples

49```

50 > (con 0b0 0b1)

51 1

53 > (con 0 1)

54 1

56 > (con 0 0)

57 0

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

60 0b1111.0011

62 > (con 4 4)

63 4

65 > (con 10.000 234)

66 10.234

68 > `@ub`534

69 0b10.0001.0110

71 > `@ub`987

72 0b11.1101.1011

74 > `@ub`(con 534 987)

75 0b11.1101.1111

77 > (con 534 987)

78 991

79```

81#### Discussion

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

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

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

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

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

89its samples and its product are stacked.

91```

92 0b1000 :: 8 (sample)

93 0b1100 :: 12 (sample)

94 0b1100 :: 12 (product)

95```

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

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

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

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

101bitwise AND is the logical conjunction.

102

103

104---

105### `++dis`

106

107Binary AND

108

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

111#### Accepts

113`a` is an atom.

115`b` is an atom.

117#### Produces

119An atom.

121#### Source

123```

124 ++ dis

125 ~/ %dis

126 |= [a=@ b=@]

127 =| [c=@ d=@]

128 |- ^- @

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

130 %= $

131 a (rsh 0 1 a)

132 b (rsh 0 1 b)

133 c +(c)

134 d %+ add d

135 %^ lsh 0 c

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

137 =(0 (end 0 1 b))

138 ==

139 ==

140```

141

142#### Examples

143

144```

145 > `@ub`9

146 0b1001

147

148 > `@ub`5

149 0b101

150

151 > `@ub`(dis 9 5)

152 0b1

153

154 > (dis 9 5)

155 1

156

157 > `@ub`534

158 0b10.0001.0110

159

160 > `@ub`987

161 0b11.1101.1011

162

163 > `@ub`(dis 534 987)

164 0b10.0001.0010

165

166 > (dis 534 987)

167 530

168```

169

170#### Discussion

171

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

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

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

175corresponding product bit is set to 0.

176

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

178its samples and its product are stacked.

179

180```

181 0b1000 :: 8 (sample)

182 0b1100 :: 12 (sample)

183 0b1000 :: 8 (product)

184```

185

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

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

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

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

190bitwise AND is the logical conjunction.

191

192---

193### `++mix`

194

195Binary XOR

196

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

199#### Accepts

201`a` is an atom

203`b` is an atom

205#### Produces

207An atom.

209#### Source

211```

212 ++ mix

213 ~/ %mix

214 |= [a=@ b=@]

215 ^- @

216 =+ [c=0 d=0]

217 |-

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

219 %= $

220 a (rsh 0 1 a)

221 b (rsh 0 1 b)

222 c +(c)

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

224 ==

225```

226

227#### Examples

228

229```

230 > `@ub`2

231 0b10

232

233 > `@ub`3

234 0b11

235

236 > `@ub`(mix 2 3)

237 0b1

238

239 > (mix 2 3)

240 1

241

242 > `@ub`(mix 2 2)

243 0b0

244

245 > (mix 2 2)

246 0

247

248 > `@ub`534

249 0b10.0001.0110

250

251 > `@ub`987

252 0b11.1101.1011

253

254 > `@ub`(mix 534 987)

255 0b1.1100.1101

256

257 > (mix 534 987)

258 461

259```

260

261#### Discussion

262

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

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

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

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

267

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

269its samples and its product are stacked.

270

271```

272 0b1000 :: 8 (sample)

273 0b1100 :: 12 (sample)

274 0b100 :: 4 (product)

275```

276

277---

278### `++not`

279

280Binary NOT

281

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

283of `c`.

284

285#### Accepts

286

287`a` is a block size (see [`bloq`](../1c)).

289`b` is an atom.

291`c` is an atom.

293#### Produces

295An atom.

297#### Source

299```

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

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

302```

303

304#### Examples

305

306```

307 > `@ub`24

308 0b1.1000

309

310 > (not 0 5 24)

311 7

312

313 > `@ub`7

314 0b111

315

316 > (not 2 5 24)

317 1.048.551

318

319 > (not 2 5 1.048.551)

320 24

321

322 > (not 1 1 (not 1 1 10))

323 10

324```

325

326#### Discussion

327

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

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

330

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

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

333their [block size](../1c). Decimal `7`, for example, is `0b111` in binary, and

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

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

336

337```

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

339 0b1000

340

341 > `@u`0b1000

342 8

343```

344

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

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

347or `8` in decimal.

348

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

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

351again, treated as `0`.

352

353```

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

355 0b1111.1000

356

357 > `@u`0b1111.1000

358 248

359```

360

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

362

363```

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

365 0b100

366

367 > `@u`0b100

368 4

369```

370

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

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

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

374

375

376---