Skip to content
Common Lisp library for handling bit vectors, bit vector arithmetic, and type conversions.
Branch: master
Clone or download
thephoeron Merge pull request #9 from jdz/patch-1
Process bit vector from end instead of reversing
Latest commit c2dcb3b Oct 2, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
src Process bit vector from end instead of reversing Oct 2, 2018
t raise more reasonable error: type-error May 11, 2016
.gitignore gitignore May 11, 2016
.travis.yml Update .travis.yml Feb 6, 2017
LICENSE Update LICENSE May 12, 2015
README.md Update README.md Feb 11, 2017
_config.yml Set theme jekyll-theme-hacker Feb 11, 2017
bit-smasher-test.asd more modernization (remove EOF) May 11, 2016
bit-smasher.asd Remove Ironclad from system def Feb 6, 2017
circle.yml let's try that again Feb 12, 2017

README.md

BIT-SMASHER

CircleCI Travis CI Coverage Status Quicklisp MIT License Join the chat at https://gitter.im/thephoeron/bit-smasher

Common Lisp library for handling bit vectors, bit vector arithmetic, and type conversions.

Available in Quicklisp as of July 2014 release.

Documentation available at: https://thephoeron.github.io/bit-smasher/

Supported Platforms

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:

  • SBCL
  • Clozure CL
  • CLISP
  • ECL
  • ABCL
  • Allegro CL

It does not build on:

  • CMUCL

It has not been tested on:

  • LispWorks
  • Clasp
  • or other available Common Lisp implementations

Usage Notes and Limitations

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.

Examples

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) => #*0000000100000000

Arithmetic 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 -2

The 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) => 9

There 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) => 3

In 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) => T

License

Copyright © 2014–2017, "the Phoeron" Colin J.E. Lupton and the Contributors. This project is released under the MIT License; please see bit-smasher/LICENSE for more information.

You can’t perform that action at this time.