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`](fn.decompress_size_prepended.html)
18//! and
19//! [`compress_prepend_size`](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. _enabled by default_
65//!
66//! For maximum performance use `no-default-features`.
67//!
68//! For no_std support only the [`block format`](block/index.html) is supported.
69//!
70//!
71#![deny(warnings)]
72#![deny(missing_docs)]
73#![cfg_attr(not(feature = "std"), no_std)]
74#![cfg_attr(docsrs, feature(doc_cfg))]
75#![cfg_attr(nightly, feature(optimize_attribute))]
76
77#[cfg_attr(test, macro_use)]
78extern crate alloc;
79
80#[cfg(test)]
81#[macro_use]
82extern crate more_asserts;
83
84pub mod block;
85#[cfg(feature = "frame")]
86#[cfg_attr(docsrs, doc(cfg(feature = "frame")))]
87pub mod frame;
88
89#[allow(dead_code)]
90mod fastcpy;
91
92#[cfg(not(all(feature = "safe-encode", feature = "safe-decode")))]
93#[allow(dead_code)]
94mod fastcpy_unsafe;
95
96#[deprecated(
97    since = "0.11.0",
98    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"
99)]
100pub use block::{compress, compress_into, compress_prepend_size};
101#[deprecated(
102    since = "0.11.0",
103    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"
104)]
105pub use block::{decompress, decompress_into, decompress_size_prepended};
106
107#[cfg_attr(
108    all(feature = "safe-encode", feature = "safe-decode"),
109    forbid(unsafe_code)
110)]
111pub(crate) mod sink;
lz4_flex/lib.rs

lz4_flex/
lib.rs
