git.iko.soy/urbit.org
on 91ef98f help sign in
urbit.org/reference/library/2c.md
1250 lines 16 kB history raw
1+++
2title = "2c: Bit Arithmetic"
3weight = 6
4template = "doc.html"
5+++
6### `++bex`
8Binary exponent
10Computes the result of `2^a`, producing an atom.
12#### Accepts
14`a` is an atom.
16#### Produces
18An atom.
20#### Source
22```
23 ++ bex
24 ~/ %bex
25 |= a=@
26 ^- @
27 ?: =(0 a) 1
28 (mul 2 $(a (dec a)))
29```
31#### Examples
33```
34 > (bex 4)
35 16
37 > (bex (add 19 1))
38 1.048.576
40 > (bex 0)
41 1
42```
44---
45### `++can`
47Assemble
49Produces an atom from a list `b` of length-value pairs `p` and `q`,
50where `p` is the length in blocks of size `a`, and `q` is an atomic
51value.
53#### Accepts
55`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
57`b` is a `list` of length-value pairs, `p` and `q`.
59#### Produces
61An atom.
63#### Source
65```
66 ++ can
67 ~/ %can
68 |= [a=bloq b=(list [p=@ q=@])]
69 ^- @
70 ?~ b 0
71 (add (end a p.i.b q.i.b) (lsh a p.i.b $(b t.b)))
72```
74#### Examples
76```
77 > `@ub`21 :: @ub is the binary aura
78 0b1.0101
80 > `@ub`(can 3 ~[[1 21]])
81 0b1.0101
83 > `@ub`(can 3 ~[[1 1]])
84 0b1
86 > `@ub`(can 0 ~[[1 255]])
87 0b1
89 > `@ux`(can 3 [3 0xc1] [1 0xa] ~) :: @ux is the hexadecimal aura
90 0xa00.00c1
92 > `@ux`(can 3 [3 0xc1] [1 0xa] [1 0x23] ~)
93 0x23.0a00.00c1
95 > `@ux`(can 4 [3 0xc1] [1 0xa] [1 0x23] ~)
96 0x23.000a.0000.0000.00c1
98 > `@ux`(can 3 ~[[1 'a'] [2 'bc']])
99 0x63.6261
100```
102---
103### `++cat`
105Concatenate
107Concatenates two atoms, `b` and `c`, according to block size `a`, producing an
108atom.
110#### Accepts
112`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
114`b` is an atom.
116`c` is an atom.
118#### Produces
120An atom.
122#### Source
124```
125 ++ cat
126 ~/ %cat
127 |= [a=bloq b=@ c=@]
128 (add (lsh a (met a b) c) b)
129```
131#### Examples
133```
134 > `@ub`(cat 3 1 0) :: @ub is the binary aura
135 0b1
137 > `@ub`(cat 0 1 1)
138 0b11
140 > `@ub`(cat 0 2 1)
141 0b110
143 > `@ub`(cat 2 1 1)
144 0b1.0001
146 > `@ub`256
147 0b1.0000.0000
149 > `@ub`255
150 0b1111.1111
152 > `@ub`(cat 3 256 255)
153 0b1111.1111.0000.0001.0000.0000
155 > `@ub`(cat 2 256 255)
156 0b1111.1111.0001.0000.0000
158 > (cat 3 256 255)
159 16.711.936
161 > (cat 2 256 255)
162 1.044.736
163```
165---
166### `++cut`
168Slice
170Slices `c` blocks of size `a` that are positioned `b` blocks from the end of
171`d`. That slice is produced as an atom.
173#### Accepts
175`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
177`b` is an atom.
179`c` is an atom.
181`d` is an atom.
183#### Produces
185An atom.
187#### Source
189```
190 ++ cut
191 ~/ %cut
192 |= [a=bloq [b=@u c=@u] d=@]
193 (end a c (rsh a b d))
194```
196#### Examples
198```
199 > (cut 0 [1 1] 2)
200 1
202 > (cut 0 [2 1] 4)
203 1
205 > `@t`(cut 3 [0 3] 'abcdefgh')
206 'abc'
208 > `@t`(cut 3 [1 3] 'abcdefgh') :: @t is the cord aura
209 'bcd'
211 > `@ub`(cut 0 [0 3] 0b1111.0000.1101) :: @ub is the binary aura
212 0b101
214 > `@ub`(cut 0 [0 6] 0b1111.0000.1101)
215 0b1101
217 > `@ub`(cut 0 [4 6] 0b1111.0000.1101)
218 0b11.0000
220 > `@ub`(cut 0 [3 6] 0b1111.0000.1101)
221 0b10.0001
222```
225---
226### `++end`
228Tail
230Produces an atom by taking the last `b` blocks of size `a` from `c`.
232#### Accepts
234`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
236`b` is an atom.
238`c` is an atom.
240#### Produces
242An atom.
245#### Source
247```
248 ++ end
249 ~/ %end
250 |= [a=bloq b=@u c=@]
251 (mod c (bex (mul (bex a) b)))
252```
254#### Examples
256```
257 > (end 2 2 255)
258 255
260 > (end 3 1 255)
261 255
263 > (end 3 1 256)
264 0
266 > `@ub`12 :: @ub is the binary aura
267 0b1100
269 > `@ub`(end 0 3 12)
270 0b100
272 > (end 0 3 12)
273 4
275 > `@ub`(end 1 3 12)
276 0b1100
278 > (end 1 3 12)
279 12
281 > `@ux`'abc' :: @ux is the hexademical aura
282 0x63.6261
284 > `@ux`(end 3 2 'abc')
285 0x6261
287 > `@t`(end 3 2 'abc') :: @t is the cord aura
288 'ab'
289```
292---
293### `++fil`
295Fill bloqstream
297Produces an atom by repeating `c` for `b` blocks of size `a`.
299#### Accepts
301`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
303`b` is an atom.
305`c` is an atom.
307#### Produces
309An atom.
311#### Source
313```
314 ++ fil
315 |= [a=bloq b=@u c=@]
316 =+ n=0
317 =+ d=c
318 |- ^- @
319 ?: =(n b)
320 (rsh a 1 d)
321 $(d (add c (lsh a 1 d)), n +(n))
322```
324#### Examples
326```
327 > `@t`(fil 3 5 %a) :: @t is the cord (string) aura
328 'aaaaa'
330 > `@t`(fil 5 10 %ceeb)
331 'ceebceebceebceebceebceebceebceebceebceeb'
333 > `@t`(fil 4 10 %eced)
334 'ʇʇʇʇʇʇʇʇʇʇed'
336 > `@tas`(fil 4 10 %bf) :: @tas is the term aura
337 %bfbfbfbfbfbfbfbfbfbf
339 > `@ub`(fil 2 6 1) :: @ub is the binary aura
340 0b1.0001.0001.0001.0001.0001
341```
344---
345### `++lsh`
347Left-shift
349Produces an atom by left-shifting `c` by `b` blocks of size `a`.
351#### Accepts
353`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
355`b` is an atom.
357`c` is an atom.
359#### Produces
361An atom.
363#### Source
365```
366 ++ lsh
367 ~/ %lsh
368 |= [a=bloq b=@u c=@]
369 (mul (bex (mul (bex a) b)) c)
370```
372#### Examples
374```
375 > `@ub`1 :: @ub is the binary aura
376 0b1
378 > `@ub`(lsh 0 1 1)
379 0b10
381 > (lsh 0 1 1)
382 2
384 > `@ub`255
385 0b1111.1111
387 > `@ub`(lsh 3 1 255)
388 0b1111.1111.0000.0000
390 > (lsh 3 1 255)
391 65.280
392```
395---
396### `++met`
398Measure
400Computes the number of blocks of size `a` in `b`, producing an atom.
402#### Accepts
404`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
406`b` is an atom.
408#### Source
410```
411 ++ met
412 ~/ %met
413 |= [a=bloq b=@]
414 ^- @
415 =+ c=0
416 |-
417 ?: =(0 b) c
418 $(b (rsh a 1 b), c +(c))
419```
421#### Examples
423```
424 > (met 0 1)
425 1
427 > (met 0 2)
428 2
430 > (met 3 255)
431 1
433 > (met 3 256)
434 2
436 > (met 3 'abcde')
437 5
438```
441---
442### `++rap`
444Assemble non-zero
446Concatenates a list of atoms `b` using block size `a`, producing an atom.
448#### Accepts
450`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
452`b` is a `list` of atoms.
454#### Produces
456An atom.
458#### Source
460```
461 ++ rap
462 ~/ %rap
463 |= [a=bloq b=(list @)]
464 ^- @
465 =+ ~
466 ?~ b 0
467 (cat a i.b $(b t.b))
468```
470#### Examples
472```
473 > `@ub`(rap 2 [1 2 3 4 ~]) :: @ub is the binary aura
474 0b100.0011.0010.0001
476 > `@ub`(rap 1 [1 2 3 4 ~])
477 0b1.0011.1001
479 > (rap 0 [0 0 0 ~])
480 0
482 > (rap 0 [1 0 1 ~])
483 3
485 > `@ub`3
486 0b11
488 > (rap 0 [0 1 0 0 1 2 ~])
489 11
491 > (rap 0 [1 1 2 ~])
492 11
494 > `@ub`11
495 0b1011
496```
498#### Discussion
500Any element of the value `0` is not included in concatenation.
502---
503### `++rep`
505Assemble single
507Produces an atom by assembling a list of atoms `b` using block size `a`.
509#### Accepts
511`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
513`b` is a list of atoms.
515#### Produces
517An atom.
519#### Source
521```
522 ++ rep
523 ~/ %rep
524 |= [a=bloq b=(list @)]
525 ^- @
526 =+ c=0
527 |-
528 ?~ b 0
529 (add (lsh a c (end a 1 i.b)) $(c +(c), b t.b))
530```
532#### Examples
534```
535 > `@ub`(rep 2 [1 2 3 4 ~]) :: @ub is the binary aura
536 0b100.0011.0010.0001
538 > (rep 0 [0 0 1 ~])
539 4
541 > (rep 0 [0 0 0 1 ~])
542 8
544 > `@ub`(rep 0 [0 0 0 1 ~])
545 0b1000
547 > `@ub`8
548 0b1000
550 > (rep 0 [0 1 0 0 ~])
551 2
553 > (rep 0 [0 1 0 1 ~])
554 10
556 > (rep 0 [1 0 1 0 1 ~])
557 21
559 > `@ub`21
560 0b10.1010
562 > `@ub`(rep 3 [12 166 8 34 ~])
563 0b10.0010.0000.1000.1010.0110.0000.1100
564```
567---
568### `++rip`
570Disassemble
572Produces a list of atoms from the bits of `b` using block size `a`.
574#### Accepts
576`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
578`b` is an atom.
580#### Produces
582A list of atoms.
584#### Source
586```
587 ++ rip
588 ~/ %rip
589 |= [a=bloq b=@]
590 ^- (list @)
591 ?: =(0 b) ~
592 [(end a 1 b) $(b (rsh a 1 b))]
593```
595#### Examples
597```
598 > `@ub`155 :: @ub is the binary aura
599 0b1001.1011
601 > (rip 0 155)
602 ~[1 1 0 1 1 0 0 1]
604 > (rip 2 155)
605 ~[11 9]
607 > (rip 0 11)
608 ~[1 1 0 1]
610 > (rip 1 155)
611 ~[3 2 1 2]
613 > `@ub`256
614 0b1.0000.0000
616 > (rip 0 256)
617 ~[0 0 0 0 0 0 0 0 1]
619 > (rip 2 256)
620 ~[0 0 1]
622 > (rip 3 256)
623 ~[0 1]
624```
627---
628### `++rsh`
630Right-shift
632Right-shifts `c` by `b` blocks of size `a`, producing an atom.
634#### Accepts
636`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
638`b` is an atom.
640`c` is an atom.
642#### Produces
644An atom.
646#### Source
648```
649 ++ rsh
650 ~/ %rsh
651 |= [a=bloq b=@u c=@]
652 (div c (bex (mul (bex a) b)))
653```
655#### Examples
657```
658 > `@ub`145 :: @ub is the binary aura
659 0b1001.0001
661 > `@ub`(rsh 1 1 145)
662 0b10.0100
664 > (rsh 1 1 145)
665 36
667 > `@ub`(rsh 2 1 145)
668 0b1001
670 > (rsh 2 1 145)
671 9
673 > `@ub`10
674 0b1010
676 > `@ub`(rsh 0 1 10)
677 0b101
679 > (rsh 0 1 10)
680 5
682 > `@ux`'abc'
683 0x63.6261
685 > `@t`(rsh 3 1 'abc')
686 'bc'
688 > `@ux`(rsh 3 1 'abc')
689 0x6362
690```
693---
694### `++swp`
696Reverse block order
698Switches little-endian to big-endian and vice versa: produces an atom by
699reversing the block order of `b` using block size `a`.
702#### Accepts
704`a` is a block size (see [`++bloq`](@/docs/reference/library/1c.md)).
706`b` is an atom.
708#### Produces
710An atom
712#### Source
714```
715 ++ swp |=([a=bloq b=@] (rep a (flop (rip a b))))
716```
718#### Examples
720```
721 > `@ub`24 :: @ub is the binary aura
722 0b1.1000
724 > (swp 0 24)
725 3
727 > `@ub`3
728 0b11
730 > (swp 0 0)
731 0
733 > (swp 0 128)
734 1
735```
738---
739### `++xeb`
741Binary logarithm
743Computes the base-2 logarithm of `a`, producing an atom.
745#### Accepts
747`a` is an atom.
749#### Produces
751An atom.
753#### Source
755```
756 ++ xeb
757 ~/ %xeb
758 |= a=@
759 ^- @
760 (met 0 a)
761```
763#### Examples
765```
766 > (xeb 31)
767 5
769 > (xeb 32)
770 6
772 > (xeb 49)
773 6
775 > (xeb 0)
776 0
778 > (xeb 1)
779 1
781 > (xeb 2)
782 2
783```
786---
787### `++fe`
789Modulo bloq
791Core that contains arms for `bloq` and modular integer operations.
793#### Accepts
795`a` is a `bloq`.
797#### Source
799```
800 |_ a=bloq
801```
803---
804### `++dif:fe`
806Produces the difference between two atoms in the modular basis
807representation.
809#### Accepts
811`a` is a `bloq`.
813`b` is an atom.
815`c` is an atom.
817#### Produces
819A `@s`
821#### Source
823```
824 ++ dif |=([b=@ c=@] (sit (sub (add out (sit b)) (sit c))))
825```
827#### Examples
829```
830 > (~(dif fe 3) 63 64)
831 255
833 > (~(dif fe 3) 5 10)
834 251
836 > (~(dif fe 3) 0 1)
837 255
839 > (~(dif fe 0) 9 10)
840 1
842 > (~(dif fe 0) 9 11)
843 0
845 > (~(dif fe 0) 9 12)
846 1
848 > (~(dif fe 2) 9 12)
849 13
851 > (~(dif fe 2) 63 64)
852 15
853```
855---
856### `++inv:fe`
858Inverse
860Inverts the order of the modular field.
862#### Accepts
864`b` is a `bloq`. (see [`++bloq`](@/docs/reference/library/1c.md))
866#### Produces
868An atom.
870#### Source
872```
873 ++ inv |=(b=@ (sub (dec out) (sit b)))
874```
876#### Examples
878```
879 > (~(inv fe 3) 255)
880 0
882 > (~(inv fe 3) 256)
883 255
885 > (~(inv fe 3) 0)
886 255
888 > (~(inv fe 3) 1)
889 254
891 > (~(inv fe 3) 2)
892 253
894 > (~(inv fe 3) 55)
895 200
896```
898---
899### `++net:fe`
901Flip endianness
903Reverses bytes within a block.
905#### Accepts
907`b` is a `bloq`. (see [`++bloq`](@/docs/reference/library/1c.md))
909#### Produces
911An atom.
913#### Source
915```
916 ++ net |= b=@ ^- @
917 => .(b (sit b))
918 ?: (lte a 3)
919 b
920 =+ c=(dec a)
921 %+ con
922 (lsh c 1 $(a c, b (cut c [0 1] b)))
923 $(a c, b (cut c [1 1] b))
924```
926#### Examples
928```
929 > (~(net fe 3) 64)
930 64
932 > (~(net fe 3) 128)
933 128
935 > (~(net fe 3) 255)
936 255
938 > (~(net fe 3) 256)
939 0
941 > (~(net fe 3) 257)
942 1
944 > (~(net fe 3) 500)
945 244
947 > (~(net fe 3) 511)
948 255
950 > (~(net fe 3) 512)
951 0
953 > (~(net fe 3) 513)
954 1
956 > (~(net fe 3) 0)
957 0
959 > (~(net fe 3) 1)
960 1
962 > (~(net fe 0) 1)
963 1
965 > (~(net fe 0) 2)
966 0
968 > (~(net fe 0) 3)
969 1
971 > (~(net fe 6) 1)
972 72.057.594.037.927.936
974 > (~(net fe 6) 2)
975 144.115.188.075.855.872
977 > (~(net fe 6) 3)
978 216.172.782.113.783.808
980 > (~(net fe 6) 4)
981 288.230.376.151.711.744
983 > (~(net fe 6) 5)
984 360.287.970.189.639.680
985```
987---
988### `++out:fe`
990Max integer value
992Produces the maximum integer value that the current block can store; `2^a^a`.
994#### Accepts
996`a` is a `bloq`.
998#### Produces
1000An atom.
1002#### Source
1004```
1005 ++ out (bex (bex a))
1006```
1008#### Examples
1010```
1011 > ~(out fe 0)
1014 > ~(out fe 1)
1017 > ~(out fe 2)
1018 16
1020 > ~(out fe 3)
1021 256
1023 > ~(out fe 4)
1024 65.536
1026 > ~(out fe 10)
1027 \/179.769.313.486.231.590.772.930.519.078.902.473.361.797.697.894.230.657.273\/
1028 .430.081.157.732.675.805.500.963.132.708.477.322.407.536.021.120.113.879.87
1029 1.393.357.658.789.768.814.416.622.492.847.430.639.474.124.377.767.893.424.8
1030 65.485.276.302.219.601.246.094.119.453.082.952.085.005.768.838.150.682.342.
1031 462.881.473.913.110.540.827.237.163.350.510.684.586.298.239.947.245.938.479
1032 .716.304.835.356.329.624.224.137.216
1033 \/ \/
1034```
1036---
1037### `++rol:fe`
1039Roll left
1041Rolls `d` to the left by `c` `b`-sized blocks.
1043#### Accepts
1045`a` is a `bloq`.
1047`b` is a `bloq`.
1049`c` is an atom.
1051`d` is an atom.
1053#### Produces
1055An atom.
1057#### Source
1059```
1060 ++ rol |= [b=bloq c=@ d=@] ^- @
1061 =+ e=(sit d)
1062 =+ f=(bex (sub a b))
1063 =+ g=(mod c f)
1064 (sit (con (lsh b g e) (rsh b (sub f g) e)))
1065```
1067#### Examples
1069```
1070 > `@ux`(~(rol fe 6) 4 3 0xabac.dedf.1213)
1071 0x1213.0000.abac.dedf
1073 > `@ux`(~(rol fe 6) 4 2 0xabac.dedf.1213)
1074 0xdedf.1213.0000.abac
1076 > `@t`(~(rol fe 5) 3 1 'dfgh')
1077 'hdfg'
1079 > `@t`(~(rol fe 5) 3 2 'dfgh')
1080 'ghdf'
1082 > `@t`(~(rol fe 5) 3 0 'dfgh')
1083 'dfgh'
1084```
1086---
1087### `++ror:fe`
1089Roll right
1091Rolls `d` to the right by `c` `b`-sized blocks.
1093#### Accepts
1095`a` is a `bloq`.
1097`b` is a `bloq`.
1099`c` is an atom.
1101`d` is an atom.
1103#### Produces
1105An atom.
1107#### Source
1109```
1110 ++ ror |= [b=bloq c=@ d=@] ^- @
1111 =+ e=(sit d)
1112 =+ f=(bex (sub a b))
1113 =+ g=(mod c f)
1114 (sit (con (rsh b g e) (lsh b (sub f g) e)))
1115```
1117#### Examples
1119```
1120 > `@ux`(~(ror fe 6) 4 1 0xabac.dedf.1213)
1121 0x1213.0000.abac.dedf
1123 > `@ux`(~(ror fe 6) 3 5 0xabac.dedf.1213)
1124 0xacde.df12.1300.00ab
1126 > `@ux`(~(ror fe 6) 3 3 0xabac.dedf.1213)
1127 0xdf12.1300.00ab.acde
1129 > `@t`(~(rol fe 5) 3 0 'hijk')
1130 'hijk'
1132 > `@t`(~(rol fe 5) 3 1 'hijk')
1133 'khij'
1135 > `@t`(~(rol fe 5) 3 2 'hijk')
1136 'jkhi'
1137```
1139---
1140### `++sit:fe`
1142Enforce modulo
1144Produces an atom in the current modular block representation.
1146#### Accepts
1148`a` is a `bloq`.
1150`b` is an atom.
1152#### Produces
1154An atom.
1156#### Source
1158```
1159 ++ sit |=(b=@ (end a 1 b))
1160```
1162#### Examples
1164```
1165 > (~(sit fe 3) 255)
1166 255
1168 > (~(sit fe 3) 256)
1171 > (~(sit fe 3) 257)
1174 > (~(sit fe 2) 257)
1177 > (~(sit fe 2) 10.000)
1180 > (~(sit fe 2) 100)
1183 > (~(sit fe 2) 19)
1186 > (~(sit fe 2) 17)
1189 > (~(sit fe 0) 17)
1192 > (~(sit fe 0) 0)
1195 > (~(sit fe 0) 1)
1197```
1199---
1201### `++sum:fe`
1203Sum
1205Sums two numbers in this modular field.
1207#### Accepts
1209`a` is a `bloq`.
1211`b` is an atom.
1213`c` is an atom.
1215#### Produces
1217An atom.
1219#### Source
1221```
1222 ++ sum |=([b=@ c=@] (sit (add b c)))
1223```
1225#### Examples
1227```
1228 > (~(sum fe 3) 10 250)
1231 > (~(sum fe 0) 0 1)
1234 > (~(sum fe 0) 0 2)
1237 > (~(sum fe 2) 14 2)
1240 > (~(sum fe 2) 14 3)
1243 > (~(sum fe 4) 10.000 256)
1244 10.256
1246 > (~(sum fe 4) 10.000 100.000)
1247 44.464
1248```
1250---