| 1 | Educational Decoder |
| 2 | =================== |
| 3 | |
| 4 | `zstd_decompress.c` is a self-contained implementation in C99 of a decoder, |
| 5 | according to the [Zstandard format specification]. |
| 6 | While it does not implement as many features as the reference decoder, |
| 7 | such as the streaming API or content checksums, it is written to be easy to |
| 8 | follow and understand, to help understand how the Zstandard format works. |
| 9 | It's laid out to match the [format specification], |
| 10 | so it can be used to understand how complex segments could be implemented. |
| 11 | It also contains implementations of Huffman and FSE table decoding. |
| 12 | |
| 13 | [Zstandard format specification]: https://github.com/facebook/zstd/blob/dev/doc/zstd_compression_format.md |
| 14 | [format specification]: https://github.com/facebook/zstd/blob/dev/doc/zstd_compression_format.md |
| 15 | |
| 16 | While the library's primary objective is code clarity, |
| 17 | it also happens to compile into a small object file. |
| 18 | The object file can be made even smaller by removing error messages, |
| 19 | using the macro directive `ZDEC_NO_MESSAGE` at compilation time. |
| 20 | This can be reduced even further by foregoing dictionary support, |
| 21 | by defining `ZDEC_NO_DICTIONARY`. |
| 22 | |
| 23 | `harness.c` provides a simple test harness around the decoder: |
| 24 | |
| 25 | harness <input-file> <output-file> [dictionary] |
| 26 | |
| 27 | As an additional resource to be used with this decoder, |
| 28 | see the `decodecorpus` tool in the [tests] directory. |
| 29 | It generates valid Zstandard frames that can be used to verify |
| 30 | a Zstandard decoder implementation. |
| 31 | Note that to use the tool to verify this decoder implementation, |
| 32 | the --content-size flag should be set, |
| 33 | as this decoder does not handle streaming decoding, |
| 34 | and so it must know the decompressed size in advance. |
| 35 | |
| 36 | [tests]: https://github.com/facebook/zstd/blob/dev/tests/ |