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

//! This crate implements [canonical Huffman] functionality for handling [HPACK]
//! format in [HTTP/2]. It exposes a simple API for performing the encoding and
//! decoding of [HTTP/2] header string literals according to the [HPACK] spec.
//! 
//! Header Compression format for [HTTP/2], known as [HPACK], foresees the use
//! of the Huffman algorithm for encoding header literal values. This
//! contributes to the additional decrease in the quantity of data, transferred
//! with each web request and response.
//! 
//! A [Huffman code] is a particular type of optimal prefix code that is
//! commonly used for lossless data compression. The process of finding or using
//! such a code proceeds by means of Huffman coding, an algorithm developed by
//! David A. Huffman. The output from Huffman's algorithm can be viewed as a
//! variable-length code table for encoding a source symbol (such as a character
//! in a file). The algorithm derives this table from the estimated probability
//! or frequency of occurrence (weight) for each possible value of the source
//! symbol. As in other entropy encoding methods, more common symbols are
//! generally represented using fewer bits than less common symbols. Huffman's
//! method can be efficiently implemented, finding a code in time linear to the
//! number of input weights if these weights are sorted.
//! 
//! [HPACK] compression entails a pre-created [canonical Huffman] code table
//! for encoding [ASCII] characters to the Huffman sequence. A
//! [canonical Huffman] code is a particular type of [Huffman code] with unique
//! properties that allow it to be described in a very compact manner. The
//! advantage of a [canonical Huffman] tree is that one can encode data in fewer
//! bits than with a fully described tree. In the aforementioned table are the
//! Huffman codes for each [ASCII] character with a length up to 32 bits (4x by
//! 8 fields with value 0 or 1), in the form of base-2 integer, aligned on the
//! most significant bit (MSB is the bit farthest to the left).
//! 
//! Each module covers this topic in more details so check the rest of the code
//! to learn more.
//! 
//! ## Usage
//!
//! Encoding:
//! 
//! ```rs
//! use httlib_huffman::encode;
//! 
//! let mut sequence = Vec::new();
//! let text = "Hello world!".as_bytes();
//! match encode(&text, &mut sequence)?;
//! ```
//! 
//! Decoding:
//! 
//! ```rs
//! use httlib_huffman::decode;
//!
//! let mut text = Vec::new();
//! let speed = 3;
//! let sequence = vec![168, 209, ...];
//! decode(&sequence, &mut text, speed).unwrap();
//! ```
//! 
//! ## Features
//! 
//! This crate splits functionalities into features so you can manually enable
//! or disable them as needed.
//! 
//! * `encode`: Enables encoding features (default).
//! * `decode1`: Enables decoding features for reading 1 bit at a time.
//! * `decode2`: Enables decoding features for reading 2 bits at a time.
//! * `decode3`: Enables decoding features for reading 3 bits at a time.
//! * `decode4`: Enables decoding features for reading 4 bits at a time (default).
//! * `decode5`: Enables decoding features for reading 5 bits at a time.
//! * `flatten`: Enables features for flattening Huffman table (default).
//! * `parse`: Enables features for parsing Huffman table (default).
//! 
//! ```toml
//! [dependencies.httlib-huffman]
//! default-features = false
//! features = ["encode", "decode4"]
//! ```
//! 
//! [ASCII]: https://en.wikipedia.org/wiki/ASCII
//! [HPACK]: https://tools.ietf.org/html/rfc7541
//! [HTTP/2]: https://tools.ietf.org/html/rfc7540
//! [Huffman code]: https://en.wikipedia.org/wiki/Huffman_coding
//! [canonical Huffman]: https://en.wikipedia.org/wiki/Canonical_Huffman_code

pub mod decode;
#[cfg(feature = "encode")]
pub mod encode;
#[cfg(feature = "flatten")]
pub mod flatten;
#[cfg(feature = "parse")]
pub mod parse;

pub use decode::*;
#[cfg(feature = "encode")]
pub use encode::*;
#[cfg(feature = "flatten")]
pub use flatten::*;
#[cfg(feature = "parse")]
pub use parse::*;