lzrw 0.1.0

Rust bindings for the LZRW family of lossless data-compression algorithms
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# lzrw

[![Crates.io](https://img.shields.io/crates/v/lzrw.svg)](https://crates.io/crates/lzrw)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Rust bindings for the [LZRW](https://en.wikipedia.org/wiki/LZRW) family of lossless data-compression algorithms.

Originally written in C by [Ross Williams](http://www.ross.net/compression/) in the early 1990s, the algorithms were designed to prioritize speed over compression ratio.
This crate vendors the original C source and exposes all six original algorithms through a safe Rust API.

## Supported Algorithms

| Algorithm | Description                                                                   |
| --------- | ----------------------------------------------------------------------------- |
| LZRW1     | Simplest variant, fast and minimal memory usage                               |
| LZRW1-A   | Optimized version of LZRW1                                                    |
| LZRW2     | Adds adaptive encoding for improved ratios                                    |
| LZRW3     | Uses a hash table for faster matching                                         |
| LZRW3-A   | Optimized version of LZRW3, best compression ratio of the family              |
| LZRW5     | LZW-based (dictionary, not sliding window), different than all other variants |

## Workspace Structure

- **`lzrw`** - the public crate meant to provide a safe Rust API for the LZRW algorithms.
- **`lzrw-sys`** - internal `-sys` crate. Compiles the vendored C code with [`cc`](https://crates.io/crates/cc).

## Usage

Add the crate to your project:

```toml
[dependencies]
lzrw = "0.1.0"
```

### Compress & Decompress

```rust
use lzrw::{self, LzrwAlgorithm};

fn main() {
    let input = b"Hello world! Hello world! Hello world!";

    // compress
    let compressed = lzrw::compress(
        LzrwAlgorithm::Lzrw3a,
        input,
    );

    println!("compressed {} -> {} bytes", input.len(), compressed.len());

    // decompress
    let decompressed = lzrw::decompress(
        LzrwAlgorithm::Lzrw3a,
        &compressed,
    );

    assert_eq!(&decompressed, input);
}
```

### Choosing an Algorithm

All six variants share the same API, just swap the `LzrwAlgorithm` enum value:

```rust
LzrwAlgorithm::Lzrw1
LzrwAlgorithm::Lzrw1a
LzrwAlgorithm::Lzrw2
LzrwAlgorithm::Lzrw3
LzrwAlgorithm::Lzrw3a
LzrwAlgorithm::Lzrw5
```

## Authors

This crate was developed and is maintained by [Brandon "SaturnKai" Gardenhire](https://panka.io).

The original **LZRW** source was released by **Ross Williams** into the public domain.
The source has been slightly modified to be compiled on modern platforms, available in the `lzrw-sys/lzrw/` directory.

## License

MIT License, see [LICENSE](LICENSE) for more details.