huffman-compress 0.7.0

Huffman compression given a probability distribution over arbitrary symbols
Documentation 
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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

huffman-compress
================

[Huffman compression](https://en.wikipedia.org/wiki/Huffman_coding)
given a probability distribution over arbitrary symbols.

[![crates.io](https://img.shields.io/crates/v/huffman-compress.svg)](https://crates.io/crates/huffman-compress)
[![docs.rs](https://docs.rs/huffman-compress/badge.svg)](https://docs.rs/huffman-compress)
[![No Maintenance Intended](http://unmaintained.tech/badge.svg)](#Alternatives)

Alternatives
------------

This project has limited real-world utility. It may be useful to experiment
with or learn about Huffman coding
(for example, when working on
[bespoke chess game compression for lichess.org](https://github.com/lichess-org/compression)),
but there are better entropy coders (both in terms of compression ratio
and performance) and better implementations.

See [`constriction`](https://crates.io/crates/constriction) for composable
entropy coders, models and streams.

See [`arcode`](https://crates.io/crates/arcode) for a standalone implementation
of arithmetic coding.

Examples
--------

```rust
use std::iter::FromIterator;
use std::collections::HashMap;
use bit_vec::BitVec;
use huffman_compress::{CodeBuilder, Book, Tree};

let mut weights = HashMap::new();
weights.insert("CG", 293);
weights.insert("AG", 34);
weights.insert("AT", 4);
weights.insert("CT", 4);
weights.insert("TG", 1);

// Construct a Huffman code based on the weights (e.g. counts or relative
// frequencies).
let (book, tree) = CodeBuilder::from_iter(weights).finish();

// More frequent symbols will be encoded with fewer bits.
assert!(book.get("CG").map_or(0, |cg| cg.len()) <
        book.get("AG").map_or(0, |ag| ag.len()));

// Encode some symbols using the book.
let mut buffer = BitVec::new();
let example = vec!["AT", "CG", "AT", "TG", "AG", "CT", "CT", "AG", "CG"];
for symbol in &example {
    book.encode(&mut buffer, symbol);
}

// Decode the symbols using the tree.
let decoded: Vec<&str> = tree.decoder(&buffer, example.len()).collect();
assert_eq!(decoded, example);
```

Documentation
-------------

[Read the documentation](https://docs.rs/huffman-compress)

Changelog
---------

* 0.7.0
  - Update to `bit-vec` 0.8.
* 0.6.1
  - Fix deprecation warning and remove `#[deny(warnings)]` (a future
    compatibility hazard in libraries).
* 0.6.0
  - Update to `bit-vec` 0.6.
* 0.5.0
  - Update to `bit-vec` 0.5.
* 0.4.0
  - Renamed `Tree::decoder()` to `Tree::unbounded_decoder()` to avoid
    surprises. A new `Tree::decoder()` takes the maximum number of symbols to
    decode.
  - No longer reexporting `Saturating` from num-traits.
* 0.3.2
  - Preallocate arena space for Huffman tree.
* 0.3.1
  - Update num-traits to 0.2 (semver compatible).
* 0.3.0
  - Introduce `CodeBuilder`.
  - Changes tie breaking order.
* 0.2.0
  - Allow initialization from iterators without creating a `HashMap`. Thanks
    @mernen.
  - Require `K: Ord` instead of `K: Hash + Eq` for symbols and switch `Book`
    internals from `HashMap` to `BTreeMap`.
  - Specify stability guarantees.
* 0.1.1
  - Expose more methods on `Book`.
* 0.1.0
  - Initial release.

License
-------

huffman-compress is dual licensed under the [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0)
and [MIT](http://opensource.org/licenses/MIT) license, at your option.