The snappy Reference Manual

Table of Contents

The snappy Reference Manual

This is the snappy Reference Manual, version 0.3, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 06:08:00 2022 GMT+0.

1 Introduction

Snappy

A Common Lisp implementation of Google's Snappy data compression library. The original name for Google's Snappy compression library was Zippy.

The Snappy API

compress buffer index limit

Compresses the contents of BUFFER, a vector of (UNSIGNED-BYTE 8), from position
INDEX to position LIMIT.  Returns two values, a vector of type (UNSIGNED-BYTE 8)
holding the compressed data and an integer indicating the number of
compressed octets in the vector.

maximum-compressed-length uncompressed-length

Returns the maximum size a vector of length UNCOMPRESSED-LENGTH may take up
after it is compressed.

uncompress buffer index limit

Uncompresses BUFFER, a vector of (UNSIGNED-BYTE 8), from position INDEX to
LIMIT.  Returns the uncompressed data as a vector of (UNSIGNED-BYTE 8).

uncompressed-length buffer index limit

Returns the uncompressed length of the compressed data stored in BUFFER from
position INDEX to LIMIT.

For more information, see the documentation strings in snappy.lisp, the example code in snappy-test.lisp, and Google's GitHub Snappy page.

2 Systems

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

2.1 snappy

Author

Robert Brown <robert.brown@gmail.com>

License

New BSD license. See the copyright messages in individual files.

Description

An implementation of Snappy compression.

Long Description

An implementation of Google’s Snappy compression algorithm, which is designed for speed of compression and decompression.

Version

0.3

Defsystem Dependency

com.google.base

Dependencies

• com.google.base
• nibbles
• varint

Source

snappy.asd (file)

Components

• package.lisp (file)
• snappy.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 snappy.asd

Location

snappy.asd

Systems

snappy (system)

3.1.2 snappy/package.lisp

Parent

snappy (system)

Location

package.lisp

Packages

snappy

3.1.3 snappy/snappy.lisp

Dependency

package.lisp (file)

Parent

snappy (system)

Location

snappy.lisp

Exported Definitions

• compress (function)
• maximum-compressed-length (function)
• uncompress (function)
• uncompressed-length (function)

Internal Definitions

• +copy-1-byte-offset+ (constant)
• +copy-2-byte-offset+ (constant)
• +copy-4-byte-offset+ (constant)
• +decompression-table+ (constant)
• +literal+ (constant)
• +maximum-hash-bits+ (constant)
• +maximum-hash-table-size+ (constant)
• +vector-index-bits+ (constant)
• +word-mask+ (constant)
• decompression-entry (type)
• emit-copy (function)
• emit-copy-less-than-64 (function)
• emit-literal (function)
• hash (function)
• hash-result (type)
• postincf (macro)
• raw-compress (function)
• raw-uncompress (function)
• table-size (type)

4 Packages

Packages are listed by definition order.

4.1 snappy

An implementation of Google’s Snappy compression algorithm, which is designed for speed of compression and decompression.

Source

package.lisp (file)

Use List

• com.google.base
• common-lisp

Exported Definitions

• compress (function)
• maximum-compressed-length (function)
• uncompress (function)
• uncompressed-length (function)

Internal Definitions

• +copy-1-byte-offset+ (constant)
• +copy-2-byte-offset+ (constant)
• +copy-4-byte-offset+ (constant)
• +decompression-table+ (constant)
• +literal+ (constant)
• +maximum-hash-bits+ (constant)
• +maximum-hash-table-size+ (constant)
• +vector-index-bits+ (constant)
• +word-mask+ (constant)
• decompression-entry (type)
• emit-copy (function)
• emit-copy-less-than-64 (function)
• emit-literal (function)
• hash (function)
• hash-result (type)
• postincf (macro)
• raw-compress (function)
• raw-uncompress (function)
• table-size (type)

5 Definitions

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

5.1 Exported definitions

5.1.1 Functions

Function: compress BUFFER INDEX LIMIT

Compresses the contents of BUFFER, a vector of (UNSIGNED-BYTE 8), from position INDEX to position LIMIT. Returns two values, a vector of
type (UNSIGNED-BYTE 8) holding the compressed data and an integer indicating the number of compressed octets in the vector.

Package

snappy

Source

snappy.lisp (file)

Function: maximum-compressed-length UNCOMPRESSED-LENGTH

Returns the maximum size a vector of length UNCOMPRESSED-LENGTH may take up after it is compressed.

Package

snappy

Source

snappy.lisp (file)

Function: uncompress BUFFER INDEX LIMIT

Uncompresses BUFFER, a vector of (UNSIGNED-BYTE 8), from position INDEX to LIMIT. Returns the uncompressed data as a vector of (UNSIGNED-BYTE 8).

Package

snappy

Source

snappy.lisp (file)

Function: uncompressed-length BUFFER INDEX LIMIT

Returns the uncompressed length of the compressed data stored in BUFFER from position INDEX to LIMIT.

Package

snappy

Source

snappy.lisp (file)

5.2 Internal definitions

5.2.1 Constants

Constant: +copy-1-byte-offset+

Package

snappy

Source

snappy.lisp (file)

Constant: +copy-2-byte-offset+

Package

snappy

Source

snappy.lisp (file)

Constant: +copy-4-byte-offset+

Package

snappy

Source

snappy.lisp (file)

Constant: +decompression-table+

Data stored per entry in lookup table:
Range Bits-used Description ————————————
1..64 0..7 Literal/copy length encoded in opcode byte 0..7 8..10 Copy offset encoded in opcode byte / 256 0..4 11..13 Extra bytes after opcode

We use eight bits for the length even though 7 would have sufficed because of efficiency reasons:
(1) Extracting a byte is faster than a bit field
(2) It properly aligns copy offset so we do not need a <<8

Package

snappy

Source

snappy.lisp (file)

Constant: +literal+

Package

snappy

Source

snappy.lisp (file)

Constant: +maximum-hash-bits+

Package

snappy

Source

snappy.lisp (file)

Constant: +maximum-hash-table-size+

Package

snappy

Source

snappy.lisp (file)

Constant: +vector-index-bits+

Package

snappy

Source

snappy.lisp (file)

Constant: +word-mask+

Mapping from i in range [0,4] to a mask to extract the bottom 8*i bits.

Package

snappy

Source

snappy.lisp (file)

5.2.2 Macros

Macro: postincf VARIABLE

Package

snappy

Source

snappy.lisp (file)

5.2.3 Functions

Function: emit-copy OUTPUT-BUFFER OUT OFFSET LENGTH

Package

snappy

Source

snappy.lisp (file)

Function: emit-copy-less-than-64 OUTPUT-BUFFER OUT OFFSET LENGTH

Package

snappy

Source

snappy.lisp (file)

Function: emit-literal INPUT-BUFFER LITERAL OUTPUT-BUFFER OUT LENGTH

Package

snappy

Source

snappy.lisp (file)

Function: hash BUFFER INDEX MASK

Package

snappy

Source

snappy.lisp (file)

Function: raw-compress INPUT-BUFFER IN IN-LIMIT OUTPUT-BUFFER OUT OUT-LIMIT

Package

snappy

Source

snappy.lisp (file)

Function: raw-uncompress INPUT-BUFFER IN IN-LIMIT OUTPUT-BUFFER OUT OUT-LIMIT

Package

snappy

Source

snappy.lisp (file)

5.2.4 Types

Type: decompression-entry ()

Package

snappy

Source

snappy.lisp (file)

Type: hash-result ()

Package

snappy

Source

snappy.lisp (file)

Type: table-size ()

Package

snappy

Source

snappy.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types