git.iko.soy/urbit.org
on 140ac0e help sign in
urbit.org/docs/programming/reference/library/2c.md
671 lines 9.1 kB history raw
1# 2c: bit arithmetic
2### `++bex`
4Binary exponent
6Computes the result of `2^a`, producing an atom.
8Accepts
9-------
11`a` is an atom.
13Produces
14--------
16An atom.
18Source
19------
21 ++ bex :: binary exponent
22 ~/ %bex
23 |= a/@
24 ^- @
25 ?: =(0 a) 1
26 (mul 2 $(a (dec a)))
28Examples
29--------
31 > (bex 4)
32 16
33 > (bex (add 19 1))
34 1.048.576
35 > (bex 0)
36 1
40***
42### `++can`
44Assemble
46Produces an atom from a list `b` of length-value pairs `p` and `q`,
47where `p` is the length in bloqs of size `a`, and `q` is an atomic
48value.
50Accepts
51-------
53`a` is a block size (see `++bloq`).
55`b` is a `++list` of length value pairs, `p` and `q`.
57Produces
58--------
60An atom.
62Source
63------
65 ++ can :: assemble
66 ~/ %can
67 |= [a/bloq b/(list [p=@ q=@])]
68 ^- @
69 ?~ b 0
70 (mix (end a p.i.b q.i.b) (lsh a p.i.b $(b t.b)))
72Examples
73--------
75 > `@ub`(can 3 ~[[1 1]])
76 0b1
77 > `@ub`(can 0 ~[[1 255]])
78 0b1
79 > `@ux`(can 3 [3 0xc1] [1 0xa] ~)
80 0xa00.00c1
81 > `@ux`(can 3 [3 0xc1] [1 0xa] [1 0x23] ~)
82 0x23.0a00.00c1
83 > `@ux`(can 4 [3 0xc1] [1 0xa] [1 0x23] ~)
84 0x23.000a.0000.0000.00c1
85 > `@ux`(can 3 ~[[1 'a'] [2 'bc']])
86 0x63.6261
89***
90### `++cat`
92Concatenate
94Concatenates two atoms, `b` and `c`, according to bloq size `a`, producing an
95atom.
97Accepts
98-------
100`a` is a block size (see `++bloq`).
102`b` is an atom.
104`c` is an atom.
106Produces
107--------
109An atom.
111Source
112------
114 ++ cat :: concatenate
115 ~/ %cat
116 |= {a/bloq b/@ c/@}
117 (add (lsh a (met a b) c) b)
120Examples
121--------
123 > `@ub`(cat 3 1 0)
124 0b1
125 > `@ub`(cat 0 1 1)
126 0b11
127 > `@ub`(cat 0 2 1)
128 0b110
129 > `@ub`(cat 2 1 1)
130 0b1.0001
131 > `@ub`256
132 0b1.0000.0000
133 > `@ub`255
134 0b1111.1111
135 > `@ub`(cat 3 256 255)
136 0b1111.1111.0000.0001.0000.0000
137 > `@ub`(cat 2 256 255)
138 0b1111.1111.0001.0000.0000
139 > (cat 3 256 255)
140 16.711.936
144***
145### `++cut`
147Slice
149Slices `c` blocks of size `a` that are `b` blocks from the end of `d`.
151Accepts
152-------
154`a` is a block size (see ++bloq).
156`b` is an atom.
158`c` is an atom.
160Produces
161--------
163An atom.
165Source
166------
168 ++ cut :: slice
169 ~/ %cut
170 |= {a/bloq {b/@u c/@u} d/@}
171 (end a c (rsh a b d))
173Examples
174--------
176 > (cut 0 [1 1] 2)
177 1
178 > (cut 0 [2 1] 4)
179 1
180 > `@t`(cut 3 [0 3] 'abcdefgh')
181 'abc'
182 > `@t`(cut 3 [1 3] 'abcdefgh')
183 'bcd'
184 > `@ub`(cut 0 [0 3] 0b1111.0000.1101)
185 0b101
186 > `@ub`(cut 0 [0 6] 0b1111.0000.1101)
187 0b1101
188 > `@ub`(cut 0 [4 6] 0b1111.0000.1101)
189 0b11.0000
190 > `@ub`(cut 0 [3 6] 0b1111.0000.1101)
191 0b10.0001
195***
196### `++end`
198Tail
200Produces an atom by taking the last `b` blocks of size `a` from `c`.
202Accepts
203-------
205`a` is a block size (see `++bloq`).
207`b` is an atom.
209`c` is an atom.
211Produces
212--------
214An atom.
217Source
218------
220 ++ end :: tail
221 ~/ %end
222 |= {a/bloq b/@u c/@}
223 (mod c (bex (mul (bex a) b)))
226Examples
227--------
229 > `@ub`12
230 0b1100
231 > `@ub`(end 0 3 12)
232 0b100
233 > (end 0 3 12)
234 4
235 > `@ub`(end 1 3 12)
236 0b1100
237 > (end 1 3 12)
238 12
239 > `@ux`'abc'
240 0x63.6261
241 > `@ux`(end 3 2 'abc')
242 0x6261
243 > `@t`(end 3 2 'abc')
244 'ab'
248***
249### `++fil`
251Fill bloqstream
253Produces an atom by repeating `c` for `b` blocks of size `a`.
255Accepts
256-------
258`a` is a block size (see `++bloq`).
260`b` is an atom.
262`c` is an atom.
264Produces
265--------
267An atom.
269Source
270------
272 ++ fil :: fill bloqstream
273 |= {a/bloq b/@u c/@}
274 =+ n=0
275 =+ d=c
276 |- ^- @
277 ?: =(n b)
278 (rsh a 1 d)
279 $(d (add c (lsh a 1 d)), n +(n))
282Examples
283--------
285 > `@t`(fil 3 5 %a)
286 'aaaaa'
287 > `@t`(fil 5 10 %ceeb)
288 'ceebceebceebceebceebceebceebceebceebceeb'
289 > `@t`(fil 4 10 %eced)
290 'ʇʇʇʇʇʇʇʇʇʇed'
291 > `@tas`(fil 4 10 %bf)
292 %bfbfbfbfbfbfbfbfbfbf
296***
297### `++lsh`
299Left-shift
301Produces an atom by left-shifting `c` by `b` blocks of size `a`.
303Accepts
304-------
306`a` is a block size (see `++bloq`).
308`b` is an atom.
310`c` is an atom.
312Produces
313--------
315An atom.
317Source
318------
320 ++ lsh :: left-shift
321 ~/ %lsh
322 |= {a/bloq b/@u c/@}
323 (mul (bex (mul (bex a) b)) c)
326Examples
327--------
329 > `@ub`1
330 0b1
331 > `@ub`(lsh 0 1 1)
332 0b10
333 > (lsh 0 1 1)
334 2
335 > `@ub`255
336 0b1111.1111
337 > `@ub`(lsh 3 1 255)
338 0b1111.1111.0000.0000
339 > (lsh 3 1 255)
340 65.280
344***
345### `++met`
347Measure
349Computes the number of blocks of size `a` in `b`, producing an atom.
351`a` is a block size (see `++bloq`).
353`b` is an atom.
355Source
356------
358 ++ met :: measure
359 ~/ %met
360 |= {a/bloq b/@}
361 ^- @
362 =+ c=0
363 |-
364 ?: =(0 b) c
365 $(b (rsh a 1 b), c +(c))
367Examples
368--------
370 > (met 0 1)
371 1
372 > (met 0 2)
373 2
374 > (met 3 255)
375 1
376 > (met 3 256)
377 2
378 > (met 3 'abcde')
379 5
383***
384### `++rap`
386Assemble non-zero
388Concatenates a list of atoms `b` using blocksize `a`, producing an atom.
390Accepts
391-------
393`a` is a block size (see `++bloq`).
395`b` is a `++list` of atoms.
397Produces
398--------
400An atom.
402Source
403------
405 ++ rap :: assemble nonzero
406 ~/ %rap
407 |= {a/bloq b/(list @)}
408 ^- @
409 ?~ b 0
410 (cat a i.b $(b t.b))
412Examples
413--------
415 > `@ub`(rap 2 (limo [1 2 3 4 ~]))
416 0b100.0011.0010.0001
417 > `@ub`(rap 1 (limo [1 2 3 4 ~]))
418 0b1.0011.1001
419 > (rap 0 (limo [0 0 0 ~]))
420 0
421 > (rap 0 (limo [1 0 1 ~]))
422 3
426***
427### `++rep`
429Assemble single
431Produces an atom by assembling a list of atoms `b` using block size `a`.
433Accepts
434-------
436`a` is a block size (see `++bloq`).
438`b` is a list of atoms.
440Produces
441--------
443An atom.
445Source
446------
448 ++ rep :: assemble single
449 ~/ %rep
450 |= {a/bloq b/(list @)}
451 ^- @
452 =+ c=0
453 |-
454 ?~ b 0
455 (con (lsh a c (end a 1 i.b)) $(c +(c), b t.b))
457Examples
458--------
460 > `@ub`(rep 2 (limo [1 2 3 4 ~]))
461 0b100.0011.0010.0001
462 > (rep 0 (limo [0 0 1 ~]))
463 4
464 > (rep 0 (limo [0 0 0 1 ~]))
465 8
466 > (rep 0 (limo [0 1 0 0 ~]))
467 2
468 > (rep 0 (limo [0 1 0 1 ~]))
469 10
470 > (rep 0 (limo [0 1 0 1 0 1 ~]))
471 42
472 > `@ub`42
473 0b10.1010
477***
478### `++rip`
480Disassemble
482Produces a list of atoms from the bits of `b` using block size `a`.
484Accepts
485-------
487`a` is a block size (see `++bloq`).
489`b` is an atom.
491Produces
492--------
494A list of atoms.
496Source
497------
499 ++ rip :: disassemble
500 ~/ %rip
501 |= {a/bloq b/@}
502 ^- (list @)
503 ?: =(0 b) ~
504 [(end a 1 b) $(b (rsh a 1 b))]
506Examples
507--------
509 > `@ub`155
510 0b1001.1011
511 > (rip 0 155)
512 ~[1 1 0 1 1 0 0 1]
513 > (rip 2 155)
514 ~[11 9]
515 > (rip 1 155)
516 ~[3 2 1 2]
517 > `@ub`256
518 0b1.0000.0000
519 > (rip 0 256)
520 ~[0 0 0 0 0 0 0 0 1]
521 > (rip 2 256)
522 ~[0 0 1]
523 > (rip 3 256)
524 ~[0 1]
528***
529### `++rsh`
531Right-shift
533Right-shifts `c` by `b` blocks of size `a`, producing an atom.
535Accepts
536-------
538`a` is a block size (see `++bloq`).
540`b` is an atom.
542`c` is an atom.
544Produces
545--------
547An atom.
549Source
550------
552 ++ rsh :: right-shift
553 ~/ %rsh
554 |= {a/bloq b/@u c/@}
555 (div c (bex (mul (bex a) b)))
557Examples
558--------
560 > `@ub`145
561 0b1001.0001
562 > `@ub`(rsh 1 1 145)
563 0b10.0100
564 > (rsh 1 1 145)
565 36
566 > `@ub`(rsh 2 1 145)
567 0b1001
568 > (rsh 2 1 145)
569 9
570 > `@ub`10
571 0b1010
572 > `@ub`(rsh 0 1 10)
573 0b101
574 > (rsh 0 1 10)
575 5
576 > `@ux`'abc'
577 0x63.6261
578 > `@t`(rsh 3 1 'abc')
579 'bc'
580 > `@ux`(rsh 3 1 'abc')
581 0x6362
585***
586### `++swp`
588Reverse block order
590Switches little endian to big and vice versa: produces an atom by
591reversing the block order of `b` using block size `a`.
594Accepts
595-------
597`a` is a block size (see `++bloq`).
599`b` is an atom.
601Produces
602--------
604An atom
606Source
607------
609 ++ swap |=({a/bloq b/@} (rep a (flop (rip a b)))) :: reverse bloq order
611Examples
612--------
614 > `@ub`24
615 0b1.1000
616 > (swap 0 24)
617 3
618 > `@ub`3
619 0b11
620 > (swap 0 0)
621 0
622 > (swap 0 128)
623 1
627***
628### `++xeb`
630Binary logarithm
632Computes the base-2 logarithm of `a`, producing an atom.
634Accepts
635-------
637`a` is an atom.
639Produces
640--------
642An atom.
644Source
645------
647 ++ xeb :: binary logarithm
648 ~/ %xeb
649 |= a/@
650 ^- @
651 (met 0 a)
653Examples
654--------
656 > (xeb 31)
657 5
658 > (xeb 32)
659 6
660 > (xeb 49)
661 6
662 > (xeb 0)
663 0
664 > (xeb 1)
665 1
666 > (xeb 2)
667 2
671***