The bit-smasher Reference Manual

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

The bit-smasher Reference Manual

This is the bit-smasher Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 03:16:54 2022 GMT+0.

Table of Contents


1 Introduction

BIT-SMASHER

Quicklisp MIT License

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.common-lisp.dev/bit-smasher/

Supported Platforms

The current release of BIT-SMASHER compiles without warning and passes all tests on 64-bit versions of the following Lisp implementations:

It compiles with warnings on:

It compiles with style-warnings on:

It does not build 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 bit-vector of the absolute ceiling value. 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–2022, "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.


2 Systems

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


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

2.1 bit-smasher

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

Author

"the Phoeron" Colin J.E. Lupton

Contact

thephoeron@protonmail.com

Home Page

https://thephoeron.common-lisp.dev/bit-smasher/

Source Control

(GIT https://gitlab.common-lisp.net/thephoeron/bit-smasher/)

Bug Tracker

https://gitlab.common-lisp.net/thephoeron/bit-smasher/-/issues/

License

MIT

Dependencies
  • cl-base58 (system).
  • cl-base64 (system).
Source

bit-smasher.asd.

Child Components

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   [Contents][Index]

3.1.1 bit-smasher/bit-smasher.asd

Source

bit-smasher.asd.

Parent Component

bit-smasher (system).

ASDF Systems

bit-smasher.

Packages

bit-smasher/asdf.


3.1.2 bit-smasher/packages.lisp

Source

bit-smasher.asd.

Parent Component

bit-smasher (system).

Packages

bit-smasher.


3.1.3 bit-smasher/core.lisp

Dependency

packages.lisp (file).

Source

bit-smasher.asd.

Parent Component

bit-smasher (system).

Internals

3.1.4 bit-smasher/from-ironclad.lisp

Dependency

core.lisp (file).

Source

bit-smasher.asd.

Parent Component

bit-smasher (system).

Internals

3.1.5 bit-smasher/conversion.lisp

Dependency

from-ironclad.lisp (file).

Source

bit-smasher.asd.

Parent Component

bit-smasher (system).

Public Interface

3.1.6 bit-smasher/arithmetic.lisp

Dependency

conversion.lisp (file).

Source

bit-smasher.asd.

Parent Component

bit-smasher (system).

Public Interface
Internals

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


3.1.7 bit-smasher/aliases.lisp

Dependency

arithmetic.lisp (file).

Source

bit-smasher.asd.

Parent Component

bit-smasher (system).


3.1.8 bit-smasher/utils.lisp

Dependency

aliases.lisp (file).

Source

bit-smasher.asd.

Parent Component

bit-smasher (system).

Public Interface

4 Packages

Packages are listed by definition order.


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

4.1 bit-smasher

Source

packages.lisp.

Nickname

bitsmash

Use List
  • common-lisp.
  • common-lisp-user.
Public Interface
Internals

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

4.2 bit-smasher/asdf

Source

bit-smasher.asd.

Use List
  • asdf/interface.
  • common-lisp.
  • uiop/driver.

5 Definitions

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


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

5.1 Public Interface


5.1.1 Ordinary 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.

Alias for

lshift.

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.

Alias for

rshift.

Function: bit* (&rest rest)

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

Package

bit-smasher.

Alias for

bit-product.

Function: bit+ (&rest rest)

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

Package

bit-smasher.

Alias for

bit-sum.

Function: bit- (&rest rest)

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

Package

bit-smasher.

Alias for

bit-difference.

Function: bit-ceiling (&rest rest)

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

Package

bit-smasher.

Source

arithmetic.lisp.

Function: bit-difference (&rest rest)

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

Package

bit-smasher.

Source

arithmetic.lisp.

Function: bit-floor (&rest rest)

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

Package

bit-smasher.

Source

arithmetic.lisp.

Function: bit-product (&rest rest)

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

Package

bit-smasher.

Source

arithmetic.lisp.

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.

Function: bit-sum (&rest rest)

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

Package

bit-smasher.

Source

arithmetic.lisp.

Function: bit/ (&rest rest)

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

Package

bit-smasher.

Alias for

bit-quotient.

Function: bits->hex (data)

Return the hexadecimal string for bit-vector DATA.

Package

bit-smasher.

Source

conversion.lisp.

Function: bits->int (data)

Return the integer value for bit-vector DATA.

Package

bit-smasher.

Source

conversion.lisp.

Function: bits->octets (data)

Return the octet-vector for bit-vector DATA.

Package

bit-smasher.

Source

conversion.lisp.

Function: bits<- (data)
Package

bit-smasher.

Source

conversion.lisp.

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.

Function: hex->bits (x)

Return the bit-vector for hexadecimal string X.

Package

bit-smasher.

Source

conversion.lisp.

Function: hex->int (x)

Return the integer value for hexadecimal string X.

Package

bit-smasher.

Source

conversion.lisp.

Function: hex->octets (x)

Return the octet-vector for hexadecimal string X.

Package

bit-smasher.

Source

conversion.lisp.

Function: hex<- (data)
Package

bit-smasher.

Source

conversion.lisp.

Function: int->bits (n)

Return the bit-vector for integer N.

Package

bit-smasher.

Source

conversion.lisp.

Function: int->hex (n)

Return the hexadecimal string for integer N.

Package

bit-smasher.

Source

conversion.lisp.

Function: int->octets (n)

Return the octet-vector for integer N.

Package

bit-smasher.

Source

conversion.lisp.

Function: int<- (data)
Package

bit-smasher.

Source

conversion.lisp.

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.

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.

Function: octets->bits (o)

Return the bit-vector for octet-vector O.

Package

bit-smasher.

Source

conversion.lisp.

Function: octets->hex (o)

Return the hexadecimal string for octet-vector O.

Package

bit-smasher.

Source

conversion.lisp.

Function: octets->int (o)

Return the integer value for octet-vector O.

Package

bit-smasher.

Source

conversion.lisp.

Function: octets<- (data)
Package

bit-smasher.

Source

conversion.lisp.

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.

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.

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.


5.2 Internals


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

5.2.1 Special variables

Special Variable: *bit-map*
Package

bit-smasher.

Source

core.lisp.


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

5.2.2 Ordinary 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.

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.

Function: hex-string-to-byte-array (string)

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

Package

bit-smasher.

Source

from-ironclad.lisp.

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.

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.

Function: hexchar->int (char)

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

Package

bit-smasher.

Source

core.lisp.

Function: integer-to-octets (bignum)
Package

bit-smasher.

Source

from-ironclad.lisp.

Function: octets-to-integer (octet-vec)
Package

bit-smasher.

Source

from-ironclad.lisp.


5.2.3 Types

Type: hex-char ()
Package

bit-smasher.

Source

core.lisp.


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  
Index Entry  Section

<
<<: Public ordinary functions

>
>>: Public ordinary functions

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

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

H
hex->bits: Public ordinary functions
hex->int: Public ordinary functions
hex->octets: Public ordinary functions
hex-string-to-byte-array: Private ordinary functions
hex-to-bit-lookup: Private ordinary functions
hex-to-bit-lookup/unsafe: Private ordinary functions
hex<-: Public ordinary functions
hexchar->int: Private ordinary functions

I
int->bits: Public ordinary functions
int->hex: Public ordinary functions
int->octets: Public ordinary functions
int<-: Public ordinary functions
integer-to-octets: Private ordinary functions

L
lshift: Public ordinary functions

M
min-bit-length: Public ordinary functions

O
octets->bits: Public ordinary functions
octets->hex: Public ordinary functions
octets->int: Public ordinary functions
octets-to-integer: Private ordinary functions
octets<-: Public ordinary functions

R
rshift: Public ordinary functions

T
twos-complement-p: Public ordinary functions

W
wide-bit-length: Public ordinary 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*: Private special variables

S
Special Variable, *bit-map*: Private special variables

Jump to:   *  
S