lz4_flex/
lib.rs

1//! Pure Rust, high performance implementation of LZ4 compression.
2//!
3//! A detailed explanation of the algorithm can be found [here](http://ticki.github.io/blog/how-lz4-works/).
4//!
5//! # Overview
6//!
7//! This crate provides two ways to use lz4. The first way is through the
8//! [`frame::FrameDecoder`](frame/struct.FrameDecoder.html)
9//! and
10//! [`frame::FrameEncoder`](frame/struct.FrameEncoder.html)
11//! types, which implement the `std::io::Read` and `std::io::Write` traits with the
12//! lz4 frame format. Unless you have a specific reason to the contrary, you
13//! should only use the lz4 frame format. Specifically, the lz4 frame format
14//! permits streaming compression or decompression.
15//!
16//! The second way is through the
17//! [`decompress_size_prepended`](block/fn.decompress_size_prepended.html)
18//! and
19//! [`compress_prepend_size`](block/fn.compress_prepend_size.html)
20//! functions. These functions provide access to the lz4 block format, and
21//! don't support a streaming interface directly. You should only use these types
22//! if you know you specifically need the lz4 block format.
23//!
24//! # Example: compress data on `stdin` with frame format
25//! This program reads data from `stdin`, compresses it and emits it to `stdout`.
26//! This example can be found in `examples/compress.rs`:
27//! ```no_run
28//! use std::io;
29//! let stdin = io::stdin();
30//! let stdout = io::stdout();
31//! let mut rdr = stdin.lock();
32//! // Wrap the stdout writer in a LZ4 Frame writer.
33//! let mut wtr = lz4_flex::frame::FrameEncoder::new(stdout.lock());
34//! io::copy(&mut rdr, &mut wtr).expect("I/O operation failed");
35//! wtr.finish().unwrap();
36//! ```
37//! # Example: decompress data on `stdin` with frame format
38//! This program reads data from `stdin`, decompresses it and emits it to `stdout`.
39//! This example can be found in `examples/decompress.rs`:
40//! ```no_run
41//! use std::io;
42//! let stdin = io::stdin();
43//! let stdout = io::stdout();
44//! // Wrap the stdin reader in a LZ4 FrameDecoder.
45//! let mut rdr = lz4_flex::frame::FrameDecoder::new(stdin.lock());
46//! let mut wtr = stdout.lock();
47//! io::copy(&mut rdr, &mut wtr).expect("I/O operation failed");
48//! ```
49//!
50//! # Example: block format roundtrip
51//! ```
52//! use lz4_flex::block::{compress_prepend_size, decompress_size_prepended};
53//! let input: &[u8] = b"Hello people, what's up?";
54//! let compressed = compress_prepend_size(input);
55//! let uncompressed = decompress_size_prepended(&compressed).unwrap();
56//! assert_eq!(input, uncompressed);
57//! ```
58//!
59//! ## Feature Flags
60//!
61//! - `safe-encode` uses only safe rust for encode. _enabled by default_
62//! - `safe-decode` uses only safe rust for encode. _enabled by default_
63//! - `frame` support for LZ4 frame format. _implies `std`, enabled by default_
64//! - `std` enables dependency on the standard library. _implies `alloc`, enabled by default_
65//! - `alloc` enables APIs that allocate, e.g. [`compress`](block/fn.compress.html) returning a
66//!   `Vec`. _enabled by default_
67//!
68//! For maximum performance use `no-default-features`.
69//!
70//! For no_std support only the [`block format`](block/index.html) is supported.
71//!
72//! Without the `alloc` feature only the `_into` variants are available, e.g.
73//! [`compress_into`](block/fn.compress_into.html). Compression then places its hash table
74//! (8-16KB) on the stack. Alternatively
75//! [`compress_into_with_table`](block/fn.compress_into_with_table.html) can be used with a
76//! statically allocated [`CompressTable`](block/enum.CompressTable.html).
77//!
78//!
79#![deny(warnings)]
80#![deny(missing_docs)]
81#![cfg_attr(not(feature = "std"), no_std)]
82#![cfg_attr(docsrs, feature(doc_cfg))]
83#![cfg_attr(feature = "nightly", feature(optimize_attribute))]
84
85#[cfg(feature = "alloc")]
86#[cfg_attr(test, macro_use)]
87extern crate alloc;
88
89#[cfg(test)]
90#[macro_use]
91extern crate more_asserts;
92
93pub mod block;
94#[cfg(feature = "frame")]
95#[cfg_attr(docsrs, doc(cfg(feature = "frame")))]
96pub mod frame;
97
98#[allow(dead_code)]
99mod fastcpy;
100
101#[cfg(not(all(feature = "safe-encode", feature = "safe-decode")))]
102#[allow(dead_code)]
103mod fastcpy_unsafe;
104
105#[deprecated(
106    since = "0.11.0",
107    note = "This re-export is deprecated as it can be confused with the frame API and is not suitable for very large data, use block:: instead"
108)]
109pub use block::compress_into;
110#[deprecated(
111    since = "0.11.0",
112    note = "This re-export is deprecated as it can be confused with the frame API and is not suitable for very large data, use block:: instead"
113)]
114pub use block::decompress_into;
115#[cfg(feature = "alloc")]
116#[deprecated(
117    since = "0.11.0",
118    note = "This re-export is deprecated as it can be confused with the frame API and is not suitable for very large data, use block:: instead"
119)]
120pub use block::{compress, compress_prepend_size};
121#[cfg(feature = "alloc")]
122#[deprecated(
123    since = "0.11.0",
124    note = "This re-export is deprecated as it can be confused with the frame API and is not suitable for very large data, use block:: instead"
125)]
126pub use block::{decompress, decompress_size_prepended};
127
128#[cfg_attr(
129    all(feature = "safe-encode", feature = "safe-decode"),
130    forbid(unsafe_code)
131)]
132pub(crate) mod sink;
lz4_flex/lib.rs

lz4_flex/
lib.rs
