Common Lisp, Development, LISP

Announcing BIT-SMASHER

BIT-SMASHER is a lean, straightforward and admittedly naive Common Lisp library for handling the oft-overlooked bit-vector type, bit-vector arithmetic, and type conversion between bit-vectors, octet-vectors, hexadecimal strings, and non-negative integers, extending the related functionality in the Common Lisp standard. While of little use to the average Lisp project, it was designed for those cases where working with bit-vectors is either necessary, or would be ideal if it were not for the lack of the functions this library provides.

You can get BIT-SMASHER now at: — or wait for it to come out in the next Quicklisp release.

The most obvious use-case for BIT-SMASHER is when you need to convert universally between bit-vectors, octet-vectors, hexadecimal strings, and non-negative integers. The library provides manual conversion functions for all twelve cases, plus type-checking, type-casting style convenience functions:

  • hex<-, octets<-, int<-, and bits<-
  • hex->bits, hex->octets, and hex->int
  • octets->hex, octets->bits, and octets->int
  • int->hex, int->bits, and int->octets
  • bits->hex, bits->octets, and bits->int

For example:

; 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

The lack of bit-vector arithmetic in the Common Lisp standard was my main motivation to write this library. However, an obvious limitation of the type to values in the set of non-negative integers forced an equal limitation on return results from the bit-vector arithmetic functions. That is to say, when an arithmetic function would normally return a negative integer, float, or fraction as one of its values, it returns the absolute ceiling value (as a bit-vector) instead. For example:

(bit+ #*0100 #*0010) => #*00000110 ; +6, as expected

(bit- #*0000 #*0010) => #*00000010 ; returns +2, not -2

(bit/ #*1010 #*0010 #*0010) => #*00000010 #*00000001 ; returns +2, remainder +1, not 0.5

The library also contains measurement and predicate utility functions, hopefully serving all your bit-vector needs excluded from the standard.

If you encounter any bugs, or have a feature you would like to see, let me know in the comments or create an issue on GitHub.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s