Bit-Twiddling
=============
`(require 'logical)'
The bit-twiddling functions are made available through the use of the
`logical' package. `logical' is loaded by inserting `(require
'logical)' before the code that uses these functions. These functions
behave as though operating on integers in two's-complement
representation.
Bitwise Operations
------------------
- Function: logand n1 n1
Returns the integer which is the bit-wise AND of the two integer
arguments.
Example:
(number->string (logand #b1100 #b1010) 2)
=> "1000"
- Function: logior n1 n2
Returns the integer which is the bit-wise OR of the two integer
arguments.
Example:
(number->string (logior #b1100 #b1010) 2)
=> "1110"
- Function: logxor n1 n2
Returns the integer which is the bit-wise XOR of the two integer
arguments.
Example:
(number->string (logxor #b1100 #b1010) 2)
=> "110"
- Function: lognot n
Returns the integer which is the 2s-complement of the integer
argument.
Example:
(number->string (lognot #b10000000) 2)
=> "-10000001"
(number->string (lognot #b0) 2)
=> "-1"
- Function: bitwise-if mask n0 n1
Returns an integer composed of some bits from integer N0 and some
from integer N1. A bit of the result is taken from N0 if the
corresponding bit of integer MASK is 1 and from N1 if that bit of
MASK is 0.
- Function: logtest j k
(logtest j k) == (not (zero? (logand j k)))
(logtest #b0100 #b1011) => #f
(logtest #b0100 #b0111) => #t
- Function: logcount n
Returns the number of bits in integer N. If integer 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 0, 0 is returned.
Example:
(logcount #b10101010)
=> 4
(logcount 0)
=> 0
(logcount -2)
=> 1
Bit Within Word
---------------
- Function: logbit? index j
(logbit? index j) == (logtest (integer-expt 2 index) j)
(logbit? 0 #b1101) => #t
(logbit? 1 #b1101) => #f
(logbit? 2 #b1101) => #t
(logbit? 3 #b1101) => #t
(logbit? 4 #b1101) => #f
- Function: copy-bit index from bit
Returns an integer the same as FROM except in the INDEXth bit,
which is 1 if BIT is `#t' and 0 if BIT is `#f'.
Example:
(number->string (copy-bit 0 0 #t) 2) => "1"
(number->string (copy-bit 2 0 #t) 2) => "100"
(number->string (copy-bit 2 #b1111 #f) 2) => "1011"
Fields of Bits
--------------
- Function: bit-field n start end
Returns the integer composed of the START (inclusive) through END
(exclusive) bits of N. The STARTth bit becomes the 0-th bit in
the result.
This function was called `bit-extract' in previous versions of
SLIB.
Example:
(number->string (bit-field #b1101101010 0 4) 2)
=> "1010"
(number->string (bit-field #b1101101010 4 9) 2)
=> "10110"
- Function: copy-bit-field to start end from
Returns an integer the same as TO except possibly in the START
(inclusive) through END (exclusive) bits, which are the same as
those of FROM. The 0-th bit of FROM becomes the STARTth bit of
the result.
Example:
(number->string (copy-bit-field #b1101101010 0 4 0) 2)
=> "1101100000"
(number->string (copy-bit-field #b1101101010 0 4 -1) 2)
=> "1101101111"
- Function: ash int count
Returns an integer equivalent to `(inexact->exact (floor (* INT
(expt 2 COUNT))))'.
Example:
(number->string (ash #b1 3) 2)
=> "1000"
(number->string (ash #b1010 -1) 2)
=> "101"
- Function: integer-length n
Returns the number of bits neccessary to represent N.
Example:
(integer-length #b10101010)
=> 8
(integer-length 0)
=> 0
(integer-length #b1111)
=> 4
- Function: integer-expt n k
Returns N raised to the non-negative integer exponent K.
Example:
(integer-expt 2 5)
=> 32
(integer-expt -3 3)
=> -27