The bit-smasher Reference Manual

Table of Contents

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.3 "Robert April" on Wed Mar 14 02:58:28 2018 GMT+0.


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

1 Introduction

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:

It does not build on:

It has not been tested on:

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.


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>

License

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
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/quickbuilder/quicklisp/dists/quicklisp/software/bit-smasher-20180228-git/bit-smasher.asd

Systems

bit-smasher (system)

Packages

bit-smasher-asd

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

bit-smasher

Exported Definitions

*bit-smasher-version* (special variable)


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

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]

3.1.4 bit-smasher/from-ironclad.lisp

Dependency

core.lisp (file)

Parent

bit-smasher (system)

Location

from-ironclad.lisp

Internal Definitions

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

3.1.5 bit-smasher/conversion.lisp

Dependency

from-ironclad.lisp (file)

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/quickbuilder/quicklisp/dists/quicklisp/software/bit-smasher-20180228-git/bit-smasher.asd

Use List
Exported Definitions

*bit-smasher-version* (special variable)


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

4.2 bit-smasher

Source

packages.lisp (file)

Nickname

bitsmash

Use List
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

bit-smasher-asd

Source

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

Special Variable: *bit-smasher-version*
Package

bit-smasher

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

bit-smasher

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

bit-smasher

Source

arithmetic.lisp (file)

Function: bit* &rest REST

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

Package

bit-smasher

Source

arithmetic.lisp (file)

Function: bit+ &rest REST

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

Package

bit-smasher

Source

arithmetic.lisp (file)

Function: bit- &rest REST

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

Package

bit-smasher

Source

arithmetic.lisp (file)

Function: bit-ceiling &rest REST

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

Package

bit-smasher

Source

arithmetic.lisp (file)

Function: bit-difference &rest REST

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

Package

bit-smasher

Source

arithmetic.lisp (file)

Function: bit-floor &rest REST

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

Package

bit-smasher

Source

arithmetic.lisp (file)

Function: bit-product &rest REST

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

Package

bit-smasher

Source

arithmetic.lisp (file)

Function: bit-quotient &rest REST

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

Package

bit-smasher

Source

arithmetic.lisp (file)

Function: bit-sum &rest REST

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

Package

bit-smasher

Source

arithmetic.lisp (file)

Function: bit/ &rest REST

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

Package

bit-smasher

Source

arithmetic.lisp (file)

Function: bits->hex DATA

Return the hexadecimal string for bit-vector DATA.

Package

bit-smasher

Source

conversion.lisp (file)

Function: bits->int DATA

Return the integer value for bit-vector DATA.

Package

bit-smasher

Source

conversion.lisp (file)

Function: bits->octets DATA

Return the octet-vector for bit-vector DATA.

Package

bit-smasher

Source

conversion.lisp (file)

Function: bits<- DATA
Package

bit-smasher

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

bit-smasher

Source

utils.lisp (file)

Function: hex->bits X

Return the bit-vector for hexadecimal string X.

Package

bit-smasher

Source

conversion.lisp (file)

Function: hex->int X

Return the integer value for hexadecimal string X.

Package

bit-smasher

Source

conversion.lisp (file)

Function: hex->octets X

Return the octet-vector for hexadecimal string X.

Package

bit-smasher

Source

conversion.lisp (file)

Function: hex<- DATA
Package

bit-smasher

Source

conversion.lisp (file)

Function: int->bits N

Return the bit-vector for integer N.

Package

bit-smasher

Source

conversion.lisp (file)

Function: int->hex N

Return the hexadecimal string for integer N.

Package

bit-smasher

Source

conversion.lisp (file)

Function: int->octets N

Return the octet-vector for integer N.

Package

bit-smasher

Source

conversion.lisp (file)

Function: int<- DATA
Package

bit-smasher

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

bit-smasher

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

bit-smasher

Source

utils.lisp (file)

Function: octets->bits O

Return the bit-vector for octet-vector O.

Package

bit-smasher

Source

conversion.lisp (file)

Function: octets->hex O

Return the hexadecimal string for octet-vector O.

Package

bit-smasher

Source

conversion.lisp (file)

Function: octets->int O

Return the integer value for octet-vector O.

Package

bit-smasher

Source

conversion.lisp (file)

Function: octets<- DATA
Package

bit-smasher

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

bit-smasher

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

bit-smasher

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

bit-smasher

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

bit-smasher

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

bit-smasher

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

bit-smasher

Source

from-ironclad.lisp (file)

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

bit-smasher

Source

from-ironclad.lisp (file)

Function: hex-to-bit-lookup CHAR

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

Package

bit-smasher

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

bit-smasher

Source

core.lisp (file)

Function: hexchar->int CHAR

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

Package

bit-smasher

Source

core.lisp (file)

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

bit-smasher

Source

from-ironclad.lisp (file)

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

bit-smasher

Source

from-ironclad.lisp (file)


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

5.2.3 Types

Type: hex-char ()
Package

bit-smasher

Source

core.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   B   F   L  
Index Entry  Section

B
bit-smasher.asd: The bit-smasher<dot>asd file
bit-smasher/aliases.lisp: The bit-smasher/aliases<dot>lisp file
bit-smasher/arithmetic.lisp: The bit-smasher/arithmetic<dot>lisp file
bit-smasher/conversion.lisp: The bit-smasher/conversion<dot>lisp file
bit-smasher/core.lisp: The bit-smasher/core<dot>lisp file
bit-smasher/from-ironclad.lisp: The bit-smasher/from-ironclad<dot>lisp file
bit-smasher/packages.lisp: The bit-smasher/packages<dot>lisp file
bit-smasher/utils.lisp: The bit-smasher/utils<dot>lisp file

F
File, Lisp, bit-smasher.asd: The bit-smasher<dot>asd file
File, Lisp, bit-smasher/aliases.lisp: The bit-smasher/aliases<dot>lisp file
File, Lisp, bit-smasher/arithmetic.lisp: The bit-smasher/arithmetic<dot>lisp file
File, Lisp, bit-smasher/conversion.lisp: The bit-smasher/conversion<dot>lisp file
File, Lisp, bit-smasher/core.lisp: The bit-smasher/core<dot>lisp file
File, Lisp, bit-smasher/from-ironclad.lisp: The bit-smasher/from-ironclad<dot>lisp file
File, Lisp, bit-smasher/packages.lisp: The bit-smasher/packages<dot>lisp file
File, Lisp, bit-smasher/utils.lisp: The bit-smasher/utils<dot>lisp file

L
Lisp File, bit-smasher.asd: The bit-smasher<dot>asd file
Lisp File, bit-smasher/aliases.lisp: The bit-smasher/aliases<dot>lisp file
Lisp File, bit-smasher/arithmetic.lisp: The bit-smasher/arithmetic<dot>lisp file
Lisp File, bit-smasher/conversion.lisp: The bit-smasher/conversion<dot>lisp file
Lisp File, bit-smasher/core.lisp: The bit-smasher/core<dot>lisp file
Lisp File, bit-smasher/from-ironclad.lisp: The bit-smasher/from-ironclad<dot>lisp file
Lisp File, bit-smasher/packages.lisp: The bit-smasher/packages<dot>lisp file
Lisp File, bit-smasher/utils.lisp: The bit-smasher/utils<dot>lisp file

Jump to:   B   F   L  

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

A.2 Functions

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

<
<<: Exported functions

>
>>: Exported functions

B
bit*: Exported functions
bit+: Exported functions
bit-: Exported functions
bit-ceiling: Exported functions
bit-difference: Exported functions
bit-floor: Exported functions
bit-product: Exported functions
bit-quotient: Exported functions
bit-sum: Exported functions
bit-vector-integer-value-and-place: Internal functions
bit/: Exported functions
bits->hex: Exported functions
bits->int: Exported functions
bits->octets: Exported functions
bits<-: Exported functions
byte-array-to-hex-string: Internal functions
byte-length: Exported functions

F
Function, <<: Exported functions
Function, >>: Exported functions
Function, bit*: Exported functions
Function, bit+: Exported functions
Function, bit-: Exported functions
Function, bit-ceiling: Exported functions
Function, bit-difference: Exported functions
Function, bit-floor: Exported functions
Function, bit-product: Exported functions
Function, bit-quotient: Exported functions
Function, bit-sum: Exported functions
Function, bit-vector-integer-value-and-place: Internal functions
Function, bit/: Exported functions
Function, bits->hex: Exported functions
Function, bits->int: Exported functions
Function, bits->octets: Exported functions
Function, bits<-: Exported functions
Function, byte-array-to-hex-string: Internal functions
Function, byte-length: Exported functions
Function, hex->bits: Exported functions
Function, hex->int: Exported functions
Function, hex->octets: Exported functions
Function, hex-string-to-byte-array: Internal functions
Function, hex-to-bit-lookup: Internal functions
Function, hex-to-bit-lookup/unsafe: Internal functions
Function, hex<-: Exported functions
Function, hexchar->int: Internal functions
Function, int->bits: Exported functions
Function, int->hex: Exported functions
Function, int->octets: Exported functions
Function, int<-: Exported functions
Function, integer-to-octets: Internal functions
Function, lshift: Exported functions
Function, min-bit-length: Exported functions
Function, octets->bits: Exported functions
Function, octets->hex: Exported functions
Function, octets->int: Exported functions
Function, octets-to-integer: Internal functions
Function, octets<-: Exported functions
Function, rshift: Exported functions
Function, twos-complement-p: Exported functions
Function, wide-bit-length: Exported functions

H
hex->bits: Exported functions
hex->int: Exported functions
hex->octets: Exported functions
hex-string-to-byte-array: Internal functions
hex-to-bit-lookup: Internal functions
hex-to-bit-lookup/unsafe: Internal functions
hex<-: Exported functions
hexchar->int: Internal functions

I
int->bits: Exported functions
int->hex: Exported functions
int->octets: Exported functions
int<-: Exported functions
integer-to-octets: Internal functions

L
lshift: Exported functions

M
min-bit-length: Exported functions

O
octets->bits: Exported functions
octets->hex: Exported functions
octets->int: Exported functions
octets-to-integer: Internal functions
octets<-: Exported functions

R
rshift: Exported functions

T
twos-complement-p: Exported functions

W
wide-bit-length: Exported functions

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

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*bit-map*: Internal special variables
*bit-smasher-version*: Exported special variables
*bit-smasher-version*: Exported special variables

S
Special Variable, *bit-map*: Internal special variables
Special Variable, *bit-smasher-version*: Exported special variables
Special Variable, *bit-smasher-version*: Exported special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   B   H   P   S   T  
Index Entry  Section

B
bit-smasher: The bit-smasher system
bit-smasher: The bit-smasher package
bit-smasher-asd: The bit-smasher-asd package

H
hex-char: Internal types

P
Package, bit-smasher: The bit-smasher package
Package, bit-smasher-asd: The bit-smasher-asd package

S
System, bit-smasher: The bit-smasher system

T
Type, hex-char: Internal types

Jump to:   B   H   P   S   T