Base Bits Library¶

The bits library implements bitwise operations on integers, and also interprets a bitstring pseudo-type, which is string of ones and zeros implemented as regular Scheme symbols prefaced by a lowercase ‘b’ character (so that the parser doesn’t interpret them as regular numeric digits). For example:

--> (import (base bits))
--> (bitstring->int 'b1001001001)
-439
--> (bitstring->int 'b01001001001
585
--> (int->bitstring 10)
b01010
--> (int->bitstring -120)
b10001000
--> (bs+ 'b01010 'b01010)
b010100

Notice that bitstrings are interpreted as twos-compliment values, so positive values must have a leading 0, and negative values must have a leading 1.

Bitwise operations on integers behave as expected similar to most other languages:

--> (import (base bits))
--> (>> 1000 2)
250
--> (<< 1000 2)
4000
--> (band 5 3)
1
--> (band 3 2)
2
--> (bor 5 3)
7
--> (bor 2 8)
10
--> (bxor 5 3)
6
--> (bxor 2 10)
8
--> (bnot 7)
-8
--> (> (band 10 1) 0)  ; test for oddness
#false
--> (> (band 11 1) 0)
#true
--> (= (band 11 1) 0)  ; test for evenness
#false
--> (= (band 10 1) 0)
#true

Operands to these procedures may also be supplied as bitstrings. If either of the operands are supplied as a bitstring, the result will be a bitstring:

--> (import (base bits))
--> (<< 'b010 2)
b01000
--> (<< 2 'b01010)
b0100000000000
--> (band 'b01010 'b0101)
b0
--> (bor 'b01010 'b0101)
b01111
--> (bnot 'b01010)
b10101

There are also four procedures exported for performing basic arithmetic on bitstrings:

--> (import (base bits))
--> (bs+ 'b01010 'b01010)
b010100
--> (bs- 'b01010 'b010)
b01000
--> (bs* 'b01010 'b010)
b010100
--> (bs/ 'b01010 'b010)
b0101

Note

The overhead required for conversions make using bitstrings slower in all practical cases. Therefore, practical use-cases should avoid them. They are implemented for purely pedagogical reasons.

Procedures exported by bits¶

>>¶

(>> n1 n2)

Returns the value of n1 right-shifted by n2.

Parameters:

n1 (integer or bitstring.) – The value to right-shift.
n2 (integer or bitstring.) – The amount to right-shift by.

Returns:

The shifted value.

Return type:

integer, if n1 AND n2 are integers, otherwise, a bitstring.

<<¶

(<< n1 n2)

Returns the value of n1 left-shifted by n2.

Parameters:

n1 (integer or bitstring.) – The value to left-shift.
n2 (integer or bitstring.) – The amount to left-shift by.

Returns:

The shifted value.

Return type:

integer, if n1 AND n2 are integers, otherwise, a bitstring.

band¶

(band n1 n2)

Returns the bitwise AND of the two values.

Parameters:

n1 (integer or bitstring.) – The first value to compare.
n2 (integer or bitstring.) – The second value to compare.

Returns:

The bitwise AND result.

Return type:

integer, if n1 AND n2 are integers, otherwise, a bitstring.

bor¶

(bor n1 n2)

Returns the bitwise OR of the two values.

Parameters:

n1 (integer or bitstring.) – The first value to compare.
n2 (integer or bitstring.) – The second value to compare.

Returns:

The bitwise OR result.

Return type:

integer, if n1 AND n2 are integers, otherwise, a bitstring.

bxor¶

(bxor n1 n2)

Returns the bitwise XOR (exclusive OR) of the two values.

Parameters:

n1 (integer or bitstring.) – The first value to compare.
n2 (integer or bitstring.) – The second value to compare.

Returns:

The bitwise XOR result.

Return type:

integer, if n1 AND n2 are integers, otherwise, a bitstring.

bnot¶

(bnot n)

Returns the bitwise NOT of the value.

Parameters:: n (integer or bitstring.) – The value to invert.
Returns:: The bitwise NOT result.
Return type:: integer, if n is an integer, otherwise, a bitstring.

bs+¶

(bs+ bitstring1 bitstring2)

Returns the sum of the two arguments as a bitstring.

Parameters:

bitstring1 (bitstring.) – The first addend.
bitstring2 (bitstring.) – The second addend.

Returns:

The sum as a bitstring.

Return type:

bitstring.

bs-¶

(bs- bitstring1 bitstring2)

Returns the difference of the two arguments as a bitstring.

Parameters:

bitstring1 (bitstring.) – The value to subtract from.
bitstring2 (bitstring.) – The value to subtract.

Returns:

The difference as a bitstring.

Return type:

bitstring.

bs*¶

(bs* bitstring1 bitstring2)

Returns the product of the two arguments as a bitstring.

Parameters:

bitstring1 (bitstring.) – The first factor.
bitstring2 (bitstring.) – The second factor.

Returns:

The product as a bitstring.

Return type:

bitstring.

bs/¶

(bs/ bitstring1 bitstring2)

Returns the integer quotient of the two arguments as a bitstring.

Parameters:

bitstring1 (bitstring.) – The dividend.
bitstring2 (bitstring.) – The divisor.

Returns:

The quotient as a bitstring.

Return type:

bitstring.

int->bitstring¶

(int->bitstring n)

Returns n represented as a two’s-complement bitstring.

Parameters:: n (integer.) – The integer to convert.
Returns:: The bitstring representation.
Return type:: bitstring.

bitstring->int¶

(bitstring->int bitstring)

Returns the value represented by bitstring as an integer.

Parameters:: bitstring (bitstring.) – The bitstring to convert.
Returns:: The integer value.
Return type:: integer.