Warning: This is the manual of the legacy Guile 2.0 series. You may want to read the manual of the current stable series instead.

6.6.2.13 Bitwise Operations

For the following bitwise functions, negative numbers are treated as infinite precision twos-complements. For instance -6 is bits …111010, with infinitely many ones on the left. It can be seen that adding 6 (binary 110) to such a bit pattern gives all zeros.

Scheme Procedure: logand n1 n2 …

C Function: scm_logand (n1, n2)

Return the bitwise AND of the integer arguments.

(logand) ⇒ -1
(logand 7) ⇒ 7
(logand #b111 #b011 #b001) ⇒ 1

Scheme Procedure: logior n1 n2 …

C Function: scm_logior (n1, n2)

Return the bitwise OR of the integer arguments.

(logior) ⇒ 0
(logior 7) ⇒ 7
(logior #b000 #b001 #b011) ⇒ 3

Scheme Procedure: logxor n1 n2 …

C Function: scm_loxor (n1, n2)

Return the bitwise XOR of the integer arguments. A bit is set in the result if it is set in an odd number of arguments.

(logxor) ⇒ 0
(logxor 7) ⇒ 7
(logxor #b000 #b001 #b011) ⇒ 2
(logxor #b000 #b001 #b011 #b011) ⇒ 1

Scheme Procedure: lognot n

C Function: scm_lognot (n)

Return the integer which is the ones-complement of the integer argument, ie. each 0 bit is changed to 1 and each 1 bit to 0.

(number->string (lognot #b10000000) 2)
   ⇒ "-10000001"
(number->string (lognot #b0) 2)
   ⇒ "-1"

Scheme Procedure: logtest j k

C Function: scm_logtest (j, k)

Test whether j and k have any 1 bits in common. This is equivalent to (not (zero? (logand j k))), but without actually calculating the logand, just testing for non-zero.

(logtest #b0100 #b1011) ⇒ #f
(logtest #b0100 #b0111) ⇒ #t

Scheme Procedure: logbit? index j

C Function: scm_logbit_p (index, j)

Test whether bit number index in j is set. index starts from 0 for the least significant bit.

(logbit? 0 #b1101) ⇒ #t
(logbit? 1 #b1101) ⇒ #f
(logbit? 2 #b1101) ⇒ #t
(logbit? 3 #b1101) ⇒ #t
(logbit? 4 #b1101) ⇒ #f

Scheme Procedure: ash n count

C Function: scm_ash (n, count)

Return floor(n * 2^{count}). n and count must be exact integers.

With n viewed as an infinite-precision twos-complement integer, ash means a left shift introducing zero bits when count is positive, or a right shift dropping bits when count is negative. This is an “arithmetic” shift.

(number->string (ash #b1 3) 2)     ⇒ "1000"
(number->string (ash #b1010 -1) 2) ⇒ "101"

;; -23 is bits ...11101001, -6 is bits ...111010
(ash -23 -2) ⇒ -6

Scheme Procedure: round-ash n count

C Function: scm_round_ash (n, count)

Return round(n * 2^count). n and count must be exact integers.

With n viewed as an infinite-precision twos-complement integer, round-ash means a left shift introducing zero bits when count is positive, or a right shift rounding to the nearest integer (with ties going to the nearest even integer) when count is negative. This is a rounded “arithmetic” shift.

(number->string (round-ash #b1 3) 2)     ⇒ \"1000\"
(number->string (round-ash #b1010 -1) 2) ⇒ \"101\"
(number->string (round-ash #b1010 -2) 2) ⇒ \"10\"
(number->string (round-ash #b1011 -2) 2) ⇒ \"11\"
(number->string (round-ash #b1101 -2) 2) ⇒ \"11\"
(number->string (round-ash #b1110 -2) 2) ⇒ \"100\"

Scheme Procedure: logcount n

C Function: scm_logcount (n)

Return the number of bits in integer n. If n is positive, the 1-bits in its binary representation are counted. If negative, the 0-bits in its two’s-complement binary representation are counted. If zero, 0 is returned.

(logcount #b10101010)
   ⇒ 4
(logcount 0)
   ⇒ 0
(logcount -2)
   ⇒ 1

Scheme Procedure: integer-length n

C Function: scm_integer_length (n)

Return the number of bits necessary to represent n.

For positive n this is how many bits to the most significant one bit. For negative n it’s how many bits to the most significant zero bit in twos complement form.

(integer-length #b10101010) ⇒ 8
(integer-length #b1111)     ⇒ 4
(integer-length 0)          ⇒ 0
(integer-length -1)         ⇒ 0
(integer-length -256)       ⇒ 8
(integer-length -257)       ⇒ 9

Scheme Procedure: integer-expt n k

C Function: scm_integer_expt (n, k)

Return n raised to the power k. k must be an exact integer, n can be any number.

Negative k is supported, and results in 1/n^abs(k) in the usual way. n^0 is 1, as usual, and that includes 0^0 is 1.

(integer-expt 2 5)   ⇒ 32
(integer-expt -3 3)  ⇒ -27
(integer-expt 5 -3)  ⇒ 1/125
(integer-expt 0 0)   ⇒ 1

Scheme Procedure: bit-extract n start end

C Function: scm_bit_extract (n, start, end)

Return the integer composed of the start (inclusive) through end (exclusive) bits of n. The startth bit becomes the 0-th bit in the result.

(number->string (bit-extract #b1101101010 0 4) 2)
   ⇒ "1010"
(number->string (bit-extract #b1101101010 4 9) 2)
   ⇒ "10110"