git.iko.soy/urbit.org
on f3ca521 help sign in
urbit.org/reference/library/2c.md
1251 lines 16 kB history raw
1+++
2title = "2c: Bit Arithmetic"
3weight = 6
4template = "doc.html"
5aliases = ["/docs/reference/library/2c"]
6+++
7### `++bex`
9Binary exponent
11Computes the result of `2^a`, producing an atom.
13#### Accepts
15`a` is an atom.
17#### Produces
19An atom.
21#### Source
23```hoon
24 ++ bex
25 ~/ %bex
26 |= a=@
27 ^- @
28 ?: =(0 a) 1
29 (mul 2 $(a (dec a)))
30```
32#### Examples
34```
35 > (bex 4)
36 16
38 > (bex (add 19 1))
39 1.048.576
41 > (bex 0)
42 1
43```
45---
46### `++can`
48Assemble
50Produces an atom from a list `b` of length-value pairs `p` and `q`,
51where `p` is the length in blocks of size `a`, and `q` is an atomic
52value.
54#### Accepts
56`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
58`b` is a `list` of length-value pairs, `p` and `q`.
60#### Produces
62An atom.
64#### Source
66```hoon
67 ++ can
68 ~/ %can
69 |= [a=bloq b=(list [p=@ q=@])]
70 ^- @
71 ?~ b 0
72 (add (end a p.i.b q.i.b) (lsh a p.i.b $(b t.b)))
73```
75#### Examples
77```
78 > `@ub`21 :: @ub is the binary aura
79 0b1.0101
81 > `@ub`(can 3 ~[[1 21]])
82 0b1.0101
84 > `@ub`(can 3 ~[[1 1]])
85 0b1
87 > `@ub`(can 0 ~[[1 255]])
88 0b1
90 > `@ux`(can 3 [3 0xc1] [1 0xa] ~) :: @ux is the hexadecimal aura
91 0xa00.00c1
93 > `@ux`(can 3 [3 0xc1] [1 0xa] [1 0x23] ~)
94 0x23.0a00.00c1
96 > `@ux`(can 4 [3 0xc1] [1 0xa] [1 0x23] ~)
97 0x23.000a.0000.0000.00c1
99 > `@ux`(can 3 ~[[1 'a'] [2 'bc']])
100 0x63.6261
101```
103---
104### `++cat`
106Concatenate
108Concatenates two atoms, `b` and `c`, according to block size `a`, producing an
109atom.
111#### Accepts
113`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
115`b` is an atom.
117`c` is an atom.
119#### Produces
121An atom.
123#### Source
125```hoon
126 ++ cat
127 ~/ %cat
128 |= [a=bloq b=@ c=@]
129 (add (lsh a (met a b) c) b)
130```
132#### Examples
134```
135 > `@ub`(cat 3 1 0) :: @ub is the binary aura
136 0b1
138 > `@ub`(cat 0 1 1)
139 0b11
141 > `@ub`(cat 0 2 1)
142 0b110
144 > `@ub`(cat 2 1 1)
145 0b1.0001
147 > `@ub`256
148 0b1.0000.0000
150 > `@ub`255
151 0b1111.1111
153 > `@ub`(cat 3 256 255)
154 0b1111.1111.0000.0001.0000.0000
156 > `@ub`(cat 2 256 255)
157 0b1111.1111.0001.0000.0000
159 > (cat 3 256 255)
160 16.711.936
162 > (cat 2 256 255)
163 1.044.736
164```
166---
167### `++cut`
169Slice
171Slices `c` blocks of size `a` that are positioned `b` blocks from the end of
172`d`. That slice is produced as an atom.
174#### Accepts
176`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
178`b` is an atom.
180`c` is an atom.
182`d` is an atom.
184#### Produces
186An atom.
188#### Source
190```hoon
191 ++ cut
192 ~/ %cut
193 |= [a=bloq [b=@u c=@u] d=@]
194 (end a c (rsh a b d))
195```
197#### Examples
199```
200 > (cut 0 [1 1] 2)
201 1
203 > (cut 0 [2 1] 4)
204 1
206 > `@t`(cut 3 [0 3] 'abcdefgh')
207 'abc'
209 > `@t`(cut 3 [1 3] 'abcdefgh') :: @t is the cord aura
210 'bcd'
212 > `@ub`(cut 0 [0 3] 0b1111.0000.1101) :: @ub is the binary aura
213 0b101
215 > `@ub`(cut 0 [0 6] 0b1111.0000.1101)
216 0b1101
218 > `@ub`(cut 0 [4 6] 0b1111.0000.1101)
219 0b11.0000
221 > `@ub`(cut 0 [3 6] 0b1111.0000.1101)
222 0b10.0001
223```
226---
227### `++end`
229Tail
231Produces an atom by taking the last `b` blocks of size `a` from `c`.
233#### Accepts
235`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
237`b` is an atom.
239`c` is an atom.
241#### Produces
243An atom.
246#### Source
248```hoon
249 ++ end
250 ~/ %end
251 |= [a=bloq b=@u c=@]
252 (mod c (bex (mul (bex a) b)))
253```
255#### Examples
257```
258 > (end 2 2 255)
259 255
261 > (end 3 1 255)
262 255
264 > (end 3 1 256)
265 0
267 > `@ub`12 :: @ub is the binary aura
268 0b1100
270 > `@ub`(end 0 3 12)
271 0b100
273 > (end 0 3 12)
274 4
276 > `@ub`(end 1 3 12)
277 0b1100
279 > (end 1 3 12)
280 12
282 > `@ux`'abc' :: @ux is the hexademical aura
283 0x63.6261
285 > `@ux`(end 3 2 'abc')
286 0x6261
288 > `@t`(end 3 2 'abc') :: @t is the cord aura
289 'ab'
290```
293---
294### `++fil`
296Fill bloqstream
298Produces an atom by repeating `c` for `b` blocks of size `a`.
300#### Accepts
302`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
304`b` is an atom.
306`c` is an atom.
308#### Produces
310An atom.
312#### Source
314```hoon
315 ++ fil
316 |= [a=bloq b=@u c=@]
317 =+ n=0
318 =+ d=c
319 |- ^- @
320 ?: =(n b)
321 (rsh a 1 d)
322 $(d (add c (lsh a 1 d)), n +(n))
323```
325#### Examples
327```
328 > `@t`(fil 3 5 %a) :: @t is the cord (string) aura
329 'aaaaa'
331 > `@t`(fil 5 10 %ceeb)
332 'ceebceebceebceebceebceebceebceebceebceeb'
334 > `@t`(fil 4 10 %eced)
335 'ʇʇʇʇʇʇʇʇʇʇed'
337 > `@tas`(fil 4 10 %bf) :: @tas is the term aura
338 %bfbfbfbfbfbfbfbfbfbf
340 > `@ub`(fil 2 6 1) :: @ub is the binary aura
341 0b1.0001.0001.0001.0001.0001
342```
345---
346### `++lsh`
348Left-shift
350Produces an atom by left-shifting `c` by `b` blocks of size `a`.
352#### Accepts
354`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
356`b` is an atom.
358`c` is an atom.
360#### Produces
362An atom.
364#### Source
366```hoon
367 ++ lsh
368 ~/ %lsh
369 |= [a=bloq b=@u c=@]
370 (mul (bex (mul (bex a) b)) c)
371```
373#### Examples
375```
376 > `@ub`1 :: @ub is the binary aura
377 0b1
379 > `@ub`(lsh 0 1 1)
380 0b10
382 > (lsh 0 1 1)
383 2
385 > `@ub`255
386 0b1111.1111
388 > `@ub`(lsh 3 1 255)
389 0b1111.1111.0000.0000
391 > (lsh 3 1 255)
392 65.280
393```
396---
397### `++met`
399Measure
401Computes the number of blocks of size `a` in `b`, producing an atom.
403#### Accepts
405`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
407`b` is an atom.
409#### Source
411```hoon
412 ++ met
413 ~/ %met
414 |= [a=bloq b=@]
415 ^- @
416 =+ c=0
417 |-
418 ?: =(0 b) c
419 $(b (rsh a 1 b), c +(c))
420```
422#### Examples
424```
425 > (met 0 1)
426 1
428 > (met 0 2)
429 2
431 > (met 3 255)
432 1
434 > (met 3 256)
435 2
437 > (met 3 'abcde')
438 5
439```
442---
443### `++rap`
445Assemble non-zero
447Concatenates a list of atoms `b` using block size `a`, producing an atom.
449#### Accepts
451`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
453`b` is a `list` of atoms.
455#### Produces
457An atom.
459#### Source
461```hoon
462 ++ rap
463 ~/ %rap
464 |= [a=bloq b=(list @)]
465 ^- @
466 =+ ~
467 ?~ b 0
468 (cat a i.b $(b t.b))
469```
471#### Examples
473```
474 > `@ub`(rap 2 [1 2 3 4 ~]) :: @ub is the binary aura
475 0b100.0011.0010.0001
477 > `@ub`(rap 1 [1 2 3 4 ~])
478 0b1.0011.1001
480 > (rap 0 [0 0 0 ~])
481 0
483 > (rap 0 [1 0 1 ~])
484 3
486 > `@ub`3
487 0b11
489 > (rap 0 [0 1 0 0 1 2 ~])
490 11
492 > (rap 0 [1 1 2 ~])
493 11
495 > `@ub`11
496 0b1011
497```
499#### Discussion
501Any element of the value `0` is not included in concatenation.
503---
504### `++rep`
506Assemble single
508Produces an atom by assembling a list of atoms `b` using block size `a`.
510#### Accepts
512`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
514`b` is a list of atoms.
516#### Produces
518An atom.
520#### Source
522```hoon
523 ++ rep
524 ~/ %rep
525 |= [a=bloq b=(list @)]
526 ^- @
527 =+ c=0
528 |-
529 ?~ b 0
530 (add (lsh a c (end a 1 i.b)) $(c +(c), b t.b))
531```
533#### Examples
535```
536 > `@ub`(rep 2 [1 2 3 4 ~]) :: @ub is the binary aura
537 0b100.0011.0010.0001
539 > (rep 0 [0 0 1 ~])
540 4
542 > (rep 0 [0 0 0 1 ~])
543 8
545 > `@ub`(rep 0 [0 0 0 1 ~])
546 0b1000
548 > `@ub`8
549 0b1000
551 > (rep 0 [0 1 0 0 ~])
552 2
554 > (rep 0 [0 1 0 1 ~])
555 10
557 > (rep 0 [1 0 1 0 1 ~])
558 21
560 > `@ub`21
561 0b10.1010
563 > `@ub`(rep 3 [12 166 8 34 ~])
564 0b10.0010.0000.1000.1010.0110.0000.1100
565```
568---
569### `++rip`
571Disassemble
573Produces a list of atoms from the bits of `b` using block size `a`.
575#### Accepts
577`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
579`b` is an atom.
581#### Produces
583A list of atoms.
585#### Source
587```hoon
588 ++ rip
589 ~/ %rip
590 |= [a=bloq b=@]
591 ^- (list @)
592 ?: =(0 b) ~
593 [(end a 1 b) $(b (rsh a 1 b))]
594```
596#### Examples
598```
599 > `@ub`155 :: @ub is the binary aura
600 0b1001.1011
602 > (rip 0 155)
603 ~[1 1 0 1 1 0 0 1]
605 > (rip 2 155)
606 ~[11 9]
608 > (rip 0 11)
609 ~[1 1 0 1]
611 > (rip 1 155)
612 ~[3 2 1 2]
614 > `@ub`256
615 0b1.0000.0000
617 > (rip 0 256)
618 ~[0 0 0 0 0 0 0 0 1]
620 > (rip 2 256)
621 ~[0 0 1]
623 > (rip 3 256)
624 ~[0 1]
625```
628---
629### `++rsh`
631Right-shift
633Right-shifts `c` by `b` blocks of size `a`, producing an atom.
635#### Accepts
637`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
639`b` is an atom.
641`c` is an atom.
643#### Produces
645An atom.
647#### Source
649```hoon
650 ++ rsh
651 ~/ %rsh
652 |= [a=bloq b=@u c=@]
653 (div c (bex (mul (bex a) b)))
654```
656#### Examples
658```
659 > `@ub`145 :: @ub is the binary aura
660 0b1001.0001
662 > `@ub`(rsh 1 1 145)
663 0b10.0100
665 > (rsh 1 1 145)
666 36
668 > `@ub`(rsh 2 1 145)
669 0b1001
671 > (rsh 2 1 145)
672 9
674 > `@ub`10
675 0b1010
677 > `@ub`(rsh 0 1 10)
678 0b101
680 > (rsh 0 1 10)
681 5
683 > `@ux`'abc'
684 0x63.6261
686 > `@t`(rsh 3 1 'abc')
687 'bc'
689 > `@ux`(rsh 3 1 'abc')
690 0x6362
691```
694---
695### `++swp`
697Reverse block order
699Switches little-endian to big-endian and vice versa: produces an atom by
700reversing the block order of `b` using block size `a`.
703#### Accepts
705`a` is a block size (see [`++bloq`](@/docs/hoon/library/1c.md)).
707`b` is an atom.
709#### Produces
711An atom
713#### Source
715```hoon
716 ++ swp |=([a=bloq b=@] (rep a (flop (rip a b))))
717```
719#### Examples
721```
722 > `@ub`24 :: @ub is the binary aura
723 0b1.1000
725 > (swp 0 24)
726 3
728 > `@ub`3
729 0b11
731 > (swp 0 0)
732 0
734 > (swp 0 128)
735 1
736```
739---
740### `++xeb`
742Binary logarithm
744Computes the base-2 logarithm of `a`, producing an atom.
746#### Accepts
748`a` is an atom.
750#### Produces
752An atom.
754#### Source
756```hoon
757 ++ xeb
758 ~/ %xeb
759 |= a=@
760 ^- @
761 (met 0 a)
762```
764#### Examples
766```
767 > (xeb 31)
768 5
770 > (xeb 32)
771 6
773 > (xeb 49)
774 6
776 > (xeb 0)
777 0
779 > (xeb 1)
780 1
782 > (xeb 2)
783 2
784```
787---
788### `++fe`
790Modulo bloq
792Core that contains arms for `bloq` and modular integer operations.
794#### Accepts
796`a` is a `bloq`.
798#### Source
800```hoon
801 |_ a=bloq
802```
804---
805### `++dif:fe`
807Produces the difference between two atoms in the modular basis
808representation.
810#### Accepts
812`a` is a `bloq`.
814`b` is an atom.
816`c` is an atom.
818#### Produces
820A `@s`
822#### Source
824```hoon
825 ++ dif |=([b=@ c=@] (sit (sub (add out (sit b)) (sit c))))
826```
828#### Examples
830```
831 > (~(dif fe 3) 63 64)
832 255
834 > (~(dif fe 3) 5 10)
835 251
837 > (~(dif fe 3) 0 1)
838 255
840 > (~(dif fe 0) 9 10)
841 1
843 > (~(dif fe 0) 9 11)
844 0
846 > (~(dif fe 0) 9 12)
847 1
849 > (~(dif fe 2) 9 12)
850 13
852 > (~(dif fe 2) 63 64)
853 15
854```
856---
857### `++inv:fe`
859Inverse
861Inverts the order of the modular field.
863#### Accepts
865`b` is a `bloq`. (see [`++bloq`](@/docs/hoon/library/1c.md))
867#### Produces
869An atom.
871#### Source
873```hoon
874 ++ inv |=(b=@ (sub (dec out) (sit b)))
875```
877#### Examples
879```
880 > (~(inv fe 3) 255)
881 0
883 > (~(inv fe 3) 256)
884 255
886 > (~(inv fe 3) 0)
887 255
889 > (~(inv fe 3) 1)
890 254
892 > (~(inv fe 3) 2)
893 253
895 > (~(inv fe 3) 55)
896 200
897```
899---
900### `++net:fe`
902Flip endianness
904Reverses bytes within a block.
906#### Accepts
908`b` is a `bloq`. (see [`++bloq`](@/docs/hoon/library/1c.md))
910#### Produces
912An atom.
914#### Source
916```hoon
917 ++ net |= b=@ ^- @
918 => .(b (sit b))
919 ?: (lte a 3)
920 b
921 =+ c=(dec a)
922 %+ con
923 (lsh c 1 $(a c, b (cut c [0 1] b)))
924 $(a c, b (cut c [1 1] b))
925```
927#### Examples
929```
930 > (~(net fe 3) 64)
931 64
933 > (~(net fe 3) 128)
934 128
936 > (~(net fe 3) 255)
937 255
939 > (~(net fe 3) 256)
940 0
942 > (~(net fe 3) 257)
943 1
945 > (~(net fe 3) 500)
946 244
948 > (~(net fe 3) 511)
949 255
951 > (~(net fe 3) 512)
952 0
954 > (~(net fe 3) 513)
955 1
957 > (~(net fe 3) 0)
958 0
960 > (~(net fe 3) 1)
961 1
963 > (~(net fe 0) 1)
964 1
966 > (~(net fe 0) 2)
967 0
969 > (~(net fe 0) 3)
970 1
972 > (~(net fe 6) 1)
973 72.057.594.037.927.936
975 > (~(net fe 6) 2)
976 144.115.188.075.855.872
978 > (~(net fe 6) 3)
979 216.172.782.113.783.808
981 > (~(net fe 6) 4)
982 288.230.376.151.711.744
984 > (~(net fe 6) 5)
985 360.287.970.189.639.680
986```
988---
989### `++out:fe`
991Max integer value
993Produces the maximum integer value that the current block can store; `2^a^a`.
995#### Accepts
997`a` is a `bloq`.
999#### Produces
1001An atom.
1003#### Source
1005```hoon
1006 ++ out (bex (bex a))
1007```
1009#### Examples
1011```
1012 > ~(out fe 0)
1015 > ~(out fe 1)
1018 > ~(out fe 2)
1019 16
1021 > ~(out fe 3)
1022 256
1024 > ~(out fe 4)
1025 65.536
1027 > ~(out fe 10)
1028 \/179.769.313.486.231.590.772.930.519.078.902.473.361.797.697.894.230.657.273\/
1029 .430.081.157.732.675.805.500.963.132.708.477.322.407.536.021.120.113.879.87
1030 1.393.357.658.789.768.814.416.622.492.847.430.639.474.124.377.767.893.424.8
1031 65.485.276.302.219.601.246.094.119.453.082.952.085.005.768.838.150.682.342.
1032 462.881.473.913.110.540.827.237.163.350.510.684.586.298.239.947.245.938.479
1033 .716.304.835.356.329.624.224.137.216
1034 \/ \/
1035```
1037---
1038### `++rol:fe`
1040Roll left
1042Rolls `d` to the left by `c` `b`-sized blocks.
1044#### Accepts
1046`a` is a `bloq`.
1048`b` is a `bloq`.
1050`c` is an atom.
1052`d` is an atom.
1054#### Produces
1056An atom.
1058#### Source
1060```hoon
1061 ++ rol |= [b=bloq c=@ d=@] ^- @
1062 =+ e=(sit d)
1063 =+ f=(bex (sub a b))
1064 =+ g=(mod c f)
1065 (sit (con (lsh b g e) (rsh b (sub f g) e)))
1066```
1068#### Examples
1070```
1071 > `@ux`(~(rol fe 6) 4 3 0xabac.dedf.1213)
1072 0x1213.0000.abac.dedf
1074 > `@ux`(~(rol fe 6) 4 2 0xabac.dedf.1213)
1075 0xdedf.1213.0000.abac
1077 > `@t`(~(rol fe 5) 3 1 'dfgh')
1078 'hdfg'
1080 > `@t`(~(rol fe 5) 3 2 'dfgh')
1081 'ghdf'
1083 > `@t`(~(rol fe 5) 3 0 'dfgh')
1084 'dfgh'
1085```
1087---
1088### `++ror:fe`
1090Roll right
1092Rolls `d` to the right by `c` `b`-sized blocks.
1094#### Accepts
1096`a` is a `bloq`.
1098`b` is a `bloq`.
1100`c` is an atom.
1102`d` is an atom.
1104#### Produces
1106An atom.
1108#### Source
1110```hoon
1111 ++ ror |= [b=bloq c=@ d=@] ^- @
1112 =+ e=(sit d)
1113 =+ f=(bex (sub a b))
1114 =+ g=(mod c f)
1115 (sit (con (rsh b g e) (lsh b (sub f g) e)))
1116```
1118#### Examples
1120```
1121 > `@ux`(~(ror fe 6) 4 1 0xabac.dedf.1213)
1122 0x1213.0000.abac.dedf
1124 > `@ux`(~(ror fe 6) 3 5 0xabac.dedf.1213)
1125 0xacde.df12.1300.00ab
1127 > `@ux`(~(ror fe 6) 3 3 0xabac.dedf.1213)
1128 0xdf12.1300.00ab.acde
1130 > `@t`(~(rol fe 5) 3 0 'hijk')
1131 'hijk'
1133 > `@t`(~(rol fe 5) 3 1 'hijk')
1134 'khij'
1136 > `@t`(~(rol fe 5) 3 2 'hijk')
1137 'jkhi'
1138```
1140---
1141### `++sit:fe`
1143Enforce modulo
1145Produces an atom in the current modular block representation.
1147#### Accepts
1149`a` is a `bloq`.
1151`b` is an atom.
1153#### Produces
1155An atom.
1157#### Source
1159```hoon
1160 ++ sit |=(b=@ (end a 1 b))
1161```
1163#### Examples
1165```
1166 > (~(sit fe 3) 255)
1167 255
1169 > (~(sit fe 3) 256)
1172 > (~(sit fe 3) 257)
1175 > (~(sit fe 2) 257)
1178 > (~(sit fe 2) 10.000)
1181 > (~(sit fe 2) 100)
1184 > (~(sit fe 2) 19)
1187 > (~(sit fe 2) 17)
1190 > (~(sit fe 0) 17)
1193 > (~(sit fe 0) 0)
1196 > (~(sit fe 0) 1)
1198```
1200---
1202### `++sum:fe`
1204Sum
1206Sums two numbers in this modular field.
1208#### Accepts
1210`a` is a `bloq`.
1212`b` is an atom.
1214`c` is an atom.
1216#### Produces
1218An atom.
1220#### Source
1222```hoon
1223 ++ sum |=([b=@ c=@] (sit (add b c)))
1224```
1226#### Examples
1228```
1229 > (~(sum fe 3) 10 250)
1232 > (~(sum fe 0) 0 1)
1235 > (~(sum fe 0) 0 2)
1238 > (~(sum fe 2) 14 2)
1241 > (~(sum fe 2) 14 3)
1244 > (~(sum fe 4) 10.000 256)
1245 10.256
1247 > (~(sum fe 4) 10.000 100.000)
1248 44.464
1249```
1251---