lzss

README

lzss

Lempel–Ziv–Storer–Szymanski (LZSS) compression and decompression in Go - LZSS:8bit variant.
This is not the classic Okumura/Apple LZSS (ring-buffer index); it implements the BI-style variant: backward offset from current output position, 8 flag bits per 8 slots, 12-bit offset + 4-bit length, 4096-byte window, trailing 4-byte checksum. Used in some archive and texture formats.

Install

go get github.com/woozymasta/lzss

Usage

Decompress

default: unsigned checksum, strict verification:

out, err := lzss.Decompress(compressed, expectedLen, nil)

Decompress with signed checksum and lenient verification (no error on checksum mismatch):

out, err := lzss.Decompress(compressed, expectedLen, lzss.SignedLenientOptions())

Compress

default search limit 2048:

out, err := lzss.Compress(data, nil)

with options (search limit, checksum mode):

opts := &lzss.CompressOptions{
    Checksum:    lzss.ChecksumUnsigned,
    SearchLimit: 4096,
}
out, err := lzss.Compress(data, opts)

Format details

• Flag byte: 8 bits; bit = 1 -> literal (1 byte), bit = 0 -> pointer (2 bytes).
• Pointer: 12-bit backward offset, 4-bit length -> 3..18 bytes. Stored little-endian.
• Window: 4096 bytes. When offset refers before start of output, filler byte 0x20 is used.
• Checksum: 4 bytes at end. Either unsigned (sum of bytes as uint8) or signed (sum as int8). Some formats use signed and ignore mismatch - use SignedLenientOptions() for decompress.

Peculiarities

• Back-references can overlap the write position (offset < length). The decoder must copy byte-by-byte in that case, not block-copy.
• Two checksum modes and optional strict/lenient verification; choose options to match the stream format (e.g. archives vs certain texture formats).

Documentation

Overview

Package lzss implements LZSS:8bit compression and decompression.

Format: one flag byte per 8 slots; bit 1 = literal (1 byte), bit 0 = pointer (2 bytes). Pointer: 12-bit backward offset from current output position, 4-bit length → (len&0x0F)+3 (3..18 bytes). Sliding window: 4096 bytes; filler 0x20 when offset refers before start of output. Trailing 4-byte checksum: either unsigned (sum of bytes as uint8) or signed (sum as int8).

Use Decompress(src, outLen, opts) with nil for default (unsigned, strict checksum). Use SignedLenientOptions() for formats that use signed checksum and ignore mismatch.

Index

• Constants
• Variables
• func Compress(src []byte, opts *CompressOptions) ([]byte, error)
• func Decompress(src []byte, outLen int, opts *Options) ([]byte, error)
• type ChecksumMode
• type CompressOptions
  • func DefaultCompressOptions() *CompressOptions
• type Options
  • func DefaultOptions() *Options
  • func SignedLenientOptions() *Options

Constants

const (
	WindowSize = 4096 // Sliding window size (ring buffer).
	MaxMatch   = 18   // Maximum back-reference length (encoded as 3..18).
	Filler     = 0x20 // Fill byte when back-reference offset is before start of output.
	FlagBits   = 8    // Bits per flag byte (one flag byte per 8 slots: literal or pointer).
)

LZSS:8bit format constants.

Variables

var (
	ErrInputTooShort    = errors.New("not enough data for checksum")
	ErrUnexpectedEOF    = errors.New("unexpected end of input while reading flags")
	ErrUnexpectedEOFBit = errors.New("unexpected end of input inside flags block")
	ErrEmptyInput       = errors.New("input is empty")
)

Package errors. Use errors.New for static messages, fmt.Errorf when values are needed.

Functions

func Compress

func Compress(src []byte, opts *CompressOptions) ([]byte, error)

Compress compresses src. Options nil means DefaultCompressOptions().

func Decompress

func Decompress(src []byte, outLen int, opts *Options) ([]byte, error)

Decompress decompresses src into a new buffer of length outLen. Options nil means DefaultOptions (unsigned checksum, strict verification).

Types

type ChecksumMode

type ChecksumMode int

ChecksumMode defines how the 4-byte checksum is computed.

const (
	ChecksumUnsigned ChecksumMode = iota // Sum bytes as uint8 (default for archives).
	ChecksumSigned                       // Sum bytes as int8 (used by some texture formats).
)

Checksum mode constants.

type CompressOptions

type CompressOptions struct {
	Checksum    ChecksumMode
	SearchLimit int // 0 = literals only; otherwise max backward distance for match search (e.g. 64..4096).
}

CompressOptions configures compression (checksum mode and search limit).

func DefaultCompressOptions

func DefaultCompressOptions() *CompressOptions

DefaultCompressOptions returns options for default compression (unsigned checksum, search limit 2048).

type Options

type Options struct {
	// Checksum sets unsigned vs signed checksum.
	Checksum ChecksumMode
	// VerifyChecksum: if true, Decompress returns an error on checksum mismatch.
	// If false, mismatch is ignored (lenient mode for formats with often-bad checksums).
	VerifyChecksum bool
}

Options configures Decompress and Compress behavior.

func DefaultOptions

func DefaultOptions() *Options

DefaultOptions returns options for default behavior: unsigned checksum, strict verification.

func SignedLenientOptions

func SignedLenientOptions() *Options

SignedLenientOptions returns options: signed checksum, do not return error on mismatch.