https://github.com/thephoeron/bit-smasher.git
git clone 'https://github.com/thephoeron/bit-smasher.git'
(ql:quickload :bit-smasher)
Common Lisp library for handling bit vectors, bit vector arithmetic, and type conversions.
Available in Quicklisp as of July 2014 release.
BIT-SMASHER is known to compile and pass all tests with 100% code coverage on the latest 64-bit versions of the following Lisp implementations:
It does not build on: - CMUCL
It has not been tested on: - LispWorks - Clasp - or other available Common Lisp implementations
This library was designed to complement the set of functions included in the Common Lisp specification for handling bit-vectors, by adding relevant lookup, conversion, arithmetic, measurement, and predicate functions. For documentation and tutorials on the bit-vector functions included in the Common Lisp standard, please refer to:
BIT-SMASHER only handles the set of non-negative integers. As such, arithmetic on bit-vectors may not always produce the results you expect—return values of all arithmetic functions are given as the absolute ceiling value in bit-vector. Manual conversion of negative integers, floats, fractions, or complex numbers will trigger an error.
The conversion functions allow you to convert universally between bit-vectors, octet-vectors, hexadecimal strings, and non-negative integers.
; universal type-casting style functions
(bits<- "F0") => #*11110000
(bits<- 240) => #*11110000
(int<- #*11110000) => 240
; manual conversions without type-checking
(hex->bits "F0") => #*11110000
(int->bits 10) => #*00001010
(octets->bits (int->octets 244)) => #*11110100
; etc., etc...Bit-vectors are returned zero-padded to the next full byte.
(bits<- 255) => #*11111111
(bits<- 256) => #*0000000100000000Arithmetic on bit-vectors can be achieved through the functions bit-sum, bit-difference, bit-product, bit-quotient, bit-floor, bit-ceiling, lshift, and rshift. There are also the shorthand macros, bit+, bit-, bit*, bit/, <<, and >>. As stated above, the bit-vector arithmetic functions return the absolute ceiling value of the operation. So,
(bit- #*0000 #*0010) => #*00000010 ; +2, not -2The measurement functions wide-bit-length and min-bit-length tell you the maximum and minimum number of bits needed to store a value, respectively. They operate on bit-vectors, octet-vectors, hexadecimal strings, and non-negative integers.
(wide-bit-length 256) => 16
(min-bit-length 256) => 9There is also the measurement function byte-length that returns the total number of bytes required to store an integer, bit-vector, or hexadecimal value; or the actual length of byte vector or simple byte array.
(byte-length "A0FF") => 2
(byte-length 65536) => 3In addition to the built-in CL predicate function, bit-vector-p, BIT-SMASHER adds the predicate function twos-complement-p, when you need to test the minimum bit length for the two's complement rule. This is required where padding bit-vectors, octet-vectors, or hex-strings with leading zeros up to a set word-length is expected.
(twos-complement-p 256) => NIL
(twos-complement-p 255) => TCopyright © 2014–2015, “the Phoeron” Colin J.E. Lupton. This project is released under the MIT License; please see bit-smasher/LICENSE for more information.