1/*!
2This crate provides an implementation of the
3[Snappy compression format](https://github.com/google/snappy/blob/master/format_description.txt),
4as well as the
5[framing format](https://github.com/google/snappy/blob/master/framing_format.txt).
6The goal of Snappy is to provide reasonable compression at high speed. On a
7modern CPU, Snappy can compress data at about 300 MB/sec or more and can
8decompress data at about 800 MB/sec or more.
9
10# Install
11
12To use this crate with
13[Cargo](https://doc.rust-lang.org/cargo/),
14simply add it as a dependency to your `Cargo.toml`:
15
16```ignore
17[dependencies]
18snap = "1"
19```
20
21# Overview
22
23This crate provides two ways to use Snappy. The first way is through the
24[`read::FrameDecoder`](read/struct.FrameDecoder.html)
25and
26[`write::FrameEncoder`](write/struct.FrameEncoder.html)
27types, which implement the `std::io::Read` and `std::io::Write` traits with the
28Snappy frame format. Unless you have a specific reason to the contrary, you
29should only use the Snappy frame format. Specifically, the Snappy frame format
30permits streaming compression or decompression.
31
32The second way is through the
33[`raw::Decoder`](raw/struct.Decoder.html)
34and
35[`raw::Encoder`](raw/struct.Encoder.html)
36types. These types provide lower level control to the raw Snappy format, and
37don't support a streaming interface directly. You should only use these types
38if you know you specifically need the Snappy raw format.
39
40Finally, the `Error` type in this crate provides an exhaustive list of error
41conditions that are probably useless in most circumstances. Therefore,
42`From<snap::Error> for io::Error` is implemented in this crate, which will let
43you automatically convert a Snappy error to an `std::io::Error` (when using
44`?`) with an appropriate error message to display to an end user.
45
46# Example: compress data on `stdin`
47
48This program reads data from `stdin`, compresses it and emits it to `stdout`.
49This example can be found in `examples/compress.rs`:
50
51```no_run
52use std::io;
53
54fn main() {
55 let stdin = io::stdin();
56 let stdout = io::stdout();
57
58 let mut rdr = stdin.lock();
59 // Wrap the stdout writer in a Snappy writer.
60 let mut wtr = snap::write::FrameEncoder::new(stdout.lock());
61 io::copy(&mut rdr, &mut wtr).expect("I/O operation failed");
62}
63```
64
65# Example: decompress data on `stdin`
66
67This program reads data from `stdin`, decompresses it and emits it to `stdout`.
68This example can be found in `examples/decompress.rs`:
69
70```no_run
71use std::io;
72
73fn main() {
74 let stdin = io::stdin();
75 let stdout = io::stdout();
76
77 // Wrap the stdin reader in a Snappy reader.
78 let mut rdr = snap::read::FrameDecoder::new(stdin.lock());
79 let mut wtr = stdout.lock();
80 io::copy(&mut rdr, &mut wtr).expect("I/O operation failed");
81}
82```
83*/
84
85#![deny(missing_docs)]
86
87#[cfg(test)]
88doc_comment::doctest!("../README.md");
89
90pub use crate::error::{Error, Result};
91
92/// We don't permit compressing a block bigger than what can fit in a u32.
93const MAX_INPUT_SIZE: u64 = std::u32::MAX as u64;
94
95/// The maximum number of bytes that we process at once. A block is the unit
96/// at which we scan for candidates for compression.
97const MAX_BLOCK_SIZE: usize = 1 << 16;
98
99mod bytes;
100mod compress;
101mod crc32;
102mod crc32_table;
103mod decompress;
104mod error;
105mod frame;
106pub mod raw;
107pub mod read;
108mod tag;
109pub mod write;
110