lib/deflate/src/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! The decoder expands data compressed with DEFLATE, either bare or inside a zlib or gzip wrapper,
 2 //! from one input buffer into one output buffer that the caller provides.
 3 //!
 4 //! A program that reads a file format or a message with compressed parts, such as the content
 5 //! streams of a PDF file, needs the original bytes back. The program also needs to know that the
 6 //! bytes it got back are whole and correct before it acts on them. Compressed data arrives in three
 7 //! forms: the bare stream, the stream inside the short zlib header and checksum, and the stream
 8 //! inside the longer gzip header, checksum and length.
 9 //!
10 //! The compressed input alone decides how large the expanded data grows, so the program needs a
11 //! bound on the output that the input cannot move. DEFLATE saves space by repeating bytes it has
12 //! already produced, from up to 32768 bytes back, so a decoder has to keep that much recent output
13 //! where it can read it again. A stream can stop short, carry a checksum that disagrees with its
14 //! data, or be followed by more bytes, as when two gzip files are joined end to end, and a caller
15 //! that misses any of these trusts output it should refuse.
16 //!
17 //! [RFC 1950](https://www.rfc-editor.org/rfc/rfc1950), [RFC
18 //! 1951](https://www.rfc-editor.org/rfc/rfc1951) and [RFC
19 //! 1952](https://www.rfc-editor.org/rfc/rfc1952) define the zlib wrapper, the DEFLATE stream and
20 //! the gzip wrapper, and the decoder follows their layouts: the three block types, the length and
21 //! distance tables, the header flags and the trailers.
22 //! [libdeflate](https://github.com/ebiggers/libdeflate) is the C library by Eric Biggers for fast
23 //! DEFLATE compression and decompression of whole buffers. The package takes whole-buffer decoding
24 //! from libdeflate, one call from a complete input to a complete output, and carries the libdeflate
25 //! MIT license. The tests reproduce two cases from libdeflate commit b122c8b: the incomplete
26 //! Huffman codes a stream may use, and code lengths that run past the end of their table.
27 //!
28 //! The decoder allocates nothing: its code tables have fixed sizes and live on the call stack, and
29 //! the caller's output buffer doubles as the history that repeated bytes are copied from. In
30 //! exchange, the caller sizes the output buffer before the call, and a stream that expands past it
31 //! fails with `error.OutputTooSmall`. The zlib and gzip checksums are always checked before a
32 //! success, and a zlib stream that asks for a preset dictionary is refused. A second check, on by
33 //! default, requires the input to end at the last byte of one compressed stream with whatever
34 //! header and trailer its format adds (*frame*), so leftover bytes, including a second gzip member
35 //! joined after the first, fail with `error.TrailingInput`, and where the data ends stays
36 //! unambiguous. A third check, off by default, requires the expanded data to fill the output buffer
37 //! exactly, for a caller that knows the expanded size from elsewhere.
38 
39 const frame = @import("frame.zig");
40 const model = @import("model.zig");
41 
42 /// The full commit hash of the libdeflate source that this package takes as its reference.
43 /// libdeflate is the C library by Eric Biggers at https://github.com/ebiggers/libdeflate for fast
44 /// DEFLATE compression and decompression of whole buffers. The two conformance tests reproduce
45 /// cases from this commit, and their names cite its short form b122c8b. No code reads the value, so
46 /// changing it changes no behavior.
47 pub const upstream_revision = "b122c8be1d78b19f6d0a6efc5bb79bfcbb30dd51";
48 
49 pub const Error = model.Error;
50 pub const Format = model.Format;
51 pub const Options = model.Options;
52 pub const Result = model.Result;
53 pub const decompress = frame.decompress;