# The bit-smasher Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

# The bit-smasher Reference Manual

This is the bit-smasher Reference Manual, version 1.0.2, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 10:49:10 2018 GMT+0.

Next: , Previous: , Up: Top   [Contents][Index]

# 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:

• Common Lisp HyperSpec:
• Successful Lisp: Chapter 18

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
``````

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.

Next: , Previous: , Up: Top   [Contents][Index]

## 2 Systems

The main system appears first, followed by any subsystem dependency.

Previous: , Up: Systems   [Contents][Index]

### 2.1 bit-smasher

Author

"the Phoeron" Colin J.E. Lupton <sysop@thephoeron.com>

MIT

Description

Utility library for handling bit vectors, bit vector arithmetic, and universal integer type conversions between bit-vectors, byte-vectors, octals, decimals, and hexadecimal notation.

Version

1.0.2

Dependencies
• cl-base58
• cl-base64
Source

bit-smasher.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

## 3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

Previous: , Up: Files   [Contents][Index]

### 3.1 Lisp

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.1 bit-smasher.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/bit-smasher-20180228-git/bit-smasher.asd

Systems

bit-smasher (system)

Packages
Exported Definitions

*bit-smasher-version* (special variable)

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.2 bit-smasher/packages.lisp

Parent

bit-smasher (system)

Location

packages.lisp

Packages
Exported Definitions

*bit-smasher-version* (special variable)

#### 3.1.3 bit-smasher/core.lisp

Dependency

packages.lisp (file)

Parent

bit-smasher (system)

Location

core.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

Dependency

core.lisp (file)

Parent

bit-smasher (system)

Location

Internal Definitions

#### 3.1.5 bit-smasher/conversion.lisp

Dependency

Parent

bit-smasher (system)

Location

conversion.lisp

Exported Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.6 bit-smasher/arithmetic.lisp

Dependency

conversion.lisp (file)

Parent

bit-smasher (system)

Location

arithmetic.lisp

Exported Definitions
Internal Definitions

bit-vector-integer-value-and-place (function)

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.7 bit-smasher/aliases.lisp

Dependency

arithmetic.lisp (file)

Parent

bit-smasher (system)

Location

aliases.lisp

Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.8 bit-smasher/utils.lisp

Dependency

aliases.lisp (file)

Parent

bit-smasher (system)

Location

utils.lisp

Exported Definitions

Next: , Previous: , Up: Top   [Contents][Index]

## 4 Packages

Packages are listed by definition order.

Next: , Previous: , Up: Packages   [Contents][Index]

### 4.1 bit-smasher-asd

Source

/home/quickref/quicklisp/dists/quicklisp/software/bit-smasher-20180228-git/bit-smasher.asd

Use List
• asdf/interface
• common-lisp
Exported Definitions

*bit-smasher-version* (special variable)

Previous: , Up: Packages   [Contents][Index]

### 4.2 bit-smasher

Source

packages.lisp (file)

Nickname

bitsmash

Use List
• common-lisp-user
• common-lisp
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

## 5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

Next: , Previous: , Up: Definitions   [Contents][Index]

### 5.1 Exported definitions

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.1 Special variables

Special Variable: *bit-smasher-version*
Package
Source

/home/quickref/quicklisp/dists/quicklisp/software/bit-smasher-20180228-git/bit-smasher.asd

Special Variable: *bit-smasher-version*
Package
Source

packages.lisp (file)

Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.2 Functions

Function: << N COUNT

Return a bit vector of N left-shifted by COUNT. N may be an integer, bit-vector, octet-vector, or hex-string.

Package
Source

arithmetic.lisp (file)

Function: >> N COUNT

Return a bit vector of N right-shifted by COUNT. N may be an integer, bit-vector, octet-vector, or hex-string.

Package
Source

arithmetic.lisp (file)

Function: bit* &rest REST

Multiplication for bit-vectors. Return result PRODUCT forced to absolute ceiling value.

Package
Source

arithmetic.lisp (file)

Function: bit+ &rest REST

Addition for bit-vectors. Return result SUM forced to absolute ceiling value.

Package
Source

arithmetic.lisp (file)

Function: bit- &rest REST

Subtraction for bit-vectors. Return result DIFFERENCE forced to absolute ceiling value.

Package
Source

arithmetic.lisp (file)

Function: bit-ceiling &rest REST

Ceiling division for bit-vectors. Return result CEILING forced to absolute ceiling value.

Package
Source

arithmetic.lisp (file)

Function: bit-difference &rest REST

Subtraction for bit-vectors. Return result DIFFERENCE forced to absolute ceiling value.

Package
Source

arithmetic.lisp (file)

Function: bit-floor &rest REST

Floor division for bit-vectors. Return result FLOOR forced to absolute ceiling value.

Package
Source

arithmetic.lisp (file)

Function: bit-product &rest REST

Multiplication for bit-vectors. Return result PRODUCT forced to absolute ceiling value.

Package
Source

arithmetic.lisp (file)

Function: bit-quotient &rest REST

Division for bit-vectors. Return results QUOTIENT and REMAINDER forced to absolute ceiling values.

Package
Source

arithmetic.lisp (file)

Function: bit-sum &rest REST

Addition for bit-vectors. Return result SUM forced to absolute ceiling value.

Package
Source

arithmetic.lisp (file)

Function: bit/ &rest REST

Division for bit-vectors. Return results QUOTIENT and REMAINDER forced to absolute ceiling values.

Package
Source

arithmetic.lisp (file)

Function: bits->hex DATA

Return the hexadecimal string for bit-vector DATA.

Package
Source

conversion.lisp (file)

Function: bits->int DATA

Return the integer value for bit-vector DATA.

Package
Source

conversion.lisp (file)

Function: bits->octets DATA

Return the octet-vector for bit-vector DATA.

Package
Source

conversion.lisp (file)

Function: bits<- DATA
Package
Source

conversion.lisp (file)

Function: byte-length N

Return the number of bytes required to represent an integer, bit-vector, or hex-string value; or the actual length of an octet-vector, N.

Package
Source

utils.lisp (file)

Function: hex->bits X

Return the bit-vector for hexadecimal string X.

Package
Source

conversion.lisp (file)

Function: hex->int X

Return the integer value for hexadecimal string X.

Package
Source

conversion.lisp (file)

Function: hex->octets X

Return the octet-vector for hexadecimal string X.

Package
Source

conversion.lisp (file)

Function: hex<- DATA
Package
Source

conversion.lisp (file)

Function: int->bits N

Return the bit-vector for integer N.

Package
Source

conversion.lisp (file)

Function: int->hex N

Return the hexadecimal string for integer N.

Package
Source

conversion.lisp (file)

Function: int->octets N

Return the octet-vector for integer N.

Package
Source

conversion.lisp (file)

Function: int<- DATA
Package
Source

conversion.lisp (file)

Function: lshift N COUNT

Return a bit vector of N left-shifted by COUNT. N may be an integer, bit-vector, octet-vector, or hex-string.

Package
Source

arithmetic.lisp (file)

Function: min-bit-length N

Return the minimum number of bits required to represent an integer, bit-vector, octet-vector, or hex-string value N.

Package
Source

utils.lisp (file)

Function: octets->bits O

Return the bit-vector for octet-vector O.

Package
Source

conversion.lisp (file)

Function: octets->hex O

Return the hexadecimal string for octet-vector O.

Package
Source

conversion.lisp (file)

Function: octets->int O

Return the integer value for octet-vector O.

Package
Source

conversion.lisp (file)

Function: octets<- DATA
Package
Source

conversion.lisp (file)

Function: rshift N COUNT

Return a bit vector of N right-shifted by COUNT. N may be an integer, bit-vector, octet-vector, or hex-string.

Package
Source

arithmetic.lisp (file)

Function: twos-complement-p N

Test a bit-vector, octet-vector, hex-string, or non-negative integer to see if it obeys the two’s complement rule.

Package
Source

utils.lisp (file)

Function: wide-bit-length N

Return the maximum number of bits required to represent an integer, bit-vector, octet-vector, or hex-string value N.

Package
Source

utils.lisp (file)

Previous: , Up: Definitions   [Contents][Index]

### 5.2 Internal definitions

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.1 Special variables

Special Variable: *bit-map*
Package
Source

core.lisp (file)

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.2 Functions

Function: bit-vector-integer-value-and-place BIT-VECTOR

Returns the bits of BIT-VECTOR as an integer as the primary value, number of bits as the secondary value. SLOW!! Consult Hackers-Delight

Package
Source

arithmetic.lisp (file)

Function: byte-array-to-hex-string VECTOR

Return a string containing the hexadecimal representation of the subsequence of VECTOR between START and END. ELEMENT-TYPE controls the element-type of the returned string.

Package
Source

Function: hex-string-to-byte-array STRING &aux START END

Parses a substring of STRING delimited by START and END of hexadecimal digits into a byte array.

Package
Source

Function: hex-to-bit-lookup CHAR

Return the bit vector associated with a hex-value character CHAR from *bit-map*.

Package
Source

core.lisp (file)

Function: hex-to-bit-lookup/unsafe CHAR

Return the bit vector associated with a hex-value character CHAR from *bit-map*.

Package
Source

core.lisp (file)

Function: hexchar->int CHAR

Return the bit vector associated with a hex-value character CHAR from *bit-map*.

Package
Source

core.lisp (file)

Function: integer-to-octets BIGNUM &aux N-BITS
Package
Source

Function: octets-to-integer OCTET-VEC &aux END
Package
Source

Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.3 Types

Type: hex-char ()
Package
Source

core.lisp (file)

Previous: , Up: Top   [Contents][Index]

## Appendix A Indexes

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.1 Concepts

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.2 Functions

Jump to: <   >   B   F   H   I   L   M   O   R   T   W
Jump to: <   >   B   F   H   I   L   M   O   R   T   W

Next: , Previous: , Up: Indexes   [Contents][Index]