5.11.4 Exact bitwise arithmetic

This section describes the (rnrs arithmetic bitwise (6)) library. The exact bitwise arithmetic provides generic operations on exact integer objects. This section uses ei, ei1, ei2, etc., as parameter names that must be exact integer objects.

Procedure: bitwise-not ei

Returns the exact integer object whose two’s complement representation is the one’s complement of the two’s complement representation of ei.

Procedure: bitwise-and ei1 …

Procedure: bitwise-ior ei1 …

Procedure: bitwise-xor ei1 …

These procedures return the exact integer object that is the bit–wise “and”, “inclusive or”, or “exclusive or” of the two’s complement representations of their arguments. If they are passed only one argument, they return that argument. If they are passed no arguments, they return the integer object (either -1 or 0) that acts as identity for the operation.

Procedure: bitwise-if ei1 ei2 ei3

Return the exact integer object that is the bit–wise “if” of the two’s complement representations of its arguments, i.e. for each bit, if it is 1 in ei1, the corresponding bit in ei2 becomes the value of the corresponding bit in the result, and if it is 0, the corresponding bit in ei3 becomes the corresponding bit in the value of the result. This is the result of the following computation:

(bitwise-ior (bitwise-and ei1 ei2)
             (bitwise-and (bitwise-not ei1) ei3))

Procedure: bitwise-bit-count ei

If ei is non–negative, this procedure returns the number of 1 bits in the two’s complement representation of ei. Otherwise it returns the result of the following computation:

(bitwise-not (bitwise-bit-count (bitwise-not ei)))

Procedure: bitwise-length ei

Return the number of bits needed to represent ei if it is positive, and the number of bits needed to represent (bitwise-not ei) if it is negative, which is the exact integer object that is the result of the following computation:

(do ((result 0 (+ result 1))
     (bits (if (negative? ei)
               (bitwise-not ei)
               ei)
           (bitwise-arithmetic-shift bits -1)))
    ((zero? bits)
     result))

Procedure: bitwise-first-bit-set ei

Returns the index of the least significant 1 bit in the two’s complement representation of ei. If ei is 0, then -1 is returned.

(bitwise-first-bit-set 0)        ⇒ -1
(bitwise-first-bit-set 1)        ⇒ 0
(bitwise-first-bit-set -4)       ⇒ 2

Procedure: bitwise-bit-set? ei1 ei2

ei2 must be non–negative.

The bitwise-bit-set? procedure returns #t if the ei2th bit is 1 in the two’s complement representation of ei1, and #f otherwise. This is the result of the following computation:

(not (zero?
       (bitwise-and
         (bitwise-arithmetic-shift-left 1 ei2)
         ei1)))

Procedure: bitwise-copy-bit ei1 ei2 ei3

ei2 must be non–negative, and ei3 must be either 0 or 1.

The bitwise-copy-bit procedure returns the result of replacing the ei2th bit of ei1 by ei3, which is the result of the following computation:

(let* ((mask (bitwise-arithmetic-shift-left 1 ei2)))
  (bitwise-if mask
            (bitwise-arithmetic-shift-left ei3 ei2)
            ei1))

Procedure: bitwise-bit-field ei1 ei2 ei3

ei2 and ei3 must be non–negative, and ei2 must be less than or equal to ei3.

The bitwise-bit-field procedure returns the number represented by the bits at the positions from ei2 (inclusive) to ei3 (exclusive), which is the result of the following computation:

(let ((mask
       (bitwise-not
        (bitwise-arithmetic-shift-left -1 ei3))))
  (bitwise-arithmetic-shift-right
    (bitwise-and ei1 mask)
    ei2))

Procedure: bitwise-copy-bit-field ei1 ei2 ei3 ei4

ei2 and ei3 must be non–negative, and ei2 must be less than or equal to ei3.

The bitwise-copy-bit-field procedure returns the result of replacing in ei1 the bits at positions from ei2 (inclusive) to ei3 (exclusive) by the bits in ei4 from position 0 (inclusive) to position ei3 - ei2 (exclusive) which is the result of the following computation:

(let* ((to    ei1)
       (start ei2)
       (end   ei3)
       (from  ei4)
       (mask1
         (bitwise-arithmetic-shift-left -1 start))
       (mask2
         (bitwise-not
           (bitwise-arithmetic-shift-left -1 end)))
       (mask (bitwise-and mask1 mask2)))
  (bitwise-if mask
              (bitwise-arithmetic-shift-left from
                                             start)
              to))

Procedure: bitwise-arithmetic-shift ei1 ei2

Return the result of the following computation:

(floor (* ei1 (expt 2 ei2)))

Examples:

(bitwise-arithmetic-shift -6 -1)    ⇒ -3
(bitwise-arithmetic-shift -5 -1)    ⇒ -3
(bitwise-arithmetic-shift -4 -1)    ⇒ -2
(bitwise-arithmetic-shift -3 -1)    ⇒ -2
(bitwise-arithmetic-shift -2 -1)    ⇒ -1
(bitwise-arithmetic-shift -1 -1)    ⇒ -1

Procedure: bitwise-arithmetic-shift-left ei1 ei2

Procedure: bitwise-arithmetic-shift-right ei1 ei2

ei2 must be non–negative.

The bitwise-arithmetic-shift-left procedure returns the same result as bitwise-arithmetic-shift, and:

(bitwise-arithmetic-shift-right ei1 ei2)

returns the same result as:

(bitwise-arithmetic-shift ei1 (- ei2))

Procedure: bitwise-rotate-bit-field ei1 ei2 ei3 ei4

ei2, ei3, ei4 must be non–negative, ei2 must be less than or equal to ei3.

The procedure returns the result of cyclically permuting in ei1 the bits at positions from ei2 (inclusive) to ei3 (exclusive) by ei4 bits towards the more significant bits, which is the result of the following computation:

(let* ((n     ei1)
       (start ei2)
       (end   ei3)
       (count ei4)
       (width (- end start)))
  (if (positive? width)
      (let* ((count (mod count width))
             (field0
               (bitwise-bit-field n start end))
             (field1 (bitwise-arithmetic-shift-left
                       field0 count))
             (field2 (bitwise-arithmetic-shift-right
                       field0
                       (- width count)))
             (field (bitwise-ior field1 field2)))
        (bitwise-copy-bit-field n start end field))
      n))

Procedure: bitwise-reverse-bit-field ei1 ei2 ei3

ei2 and ei3 must be non–negative, and ei2 must be less than or equal to ei3.

The bitwise-reverse-bit-field procedure returns the result obtained from ei1 by reversing the order of the bits at positions from ei2 (inclusive) to ei3 (exclusive).

(bitwise-reverse-bit-field #b1010010 1 4)
⇒  88 ; #b1011000