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)] 78 extern crate alloc; 79 80 #[cfg(test)] 81 #[macro_use] 82 extern crate more_asserts; 83 84 pub mod block; 85 #[cfg(feature = "frame")] 86 #[cfg_attr(docsrs, doc(cfg(feature = "frame")))] 87 pub mod frame; 88 89 #[allow(dead_code)] 90 mod fastcpy; 91 #[allow(dead_code)] 92 mod fastcpy_unsafe; 93 94 #[deprecated( 95 since = "0.11.0", 96 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" 97 )] 98 pub use block::{compress, compress_into, compress_prepend_size}; 99 #[deprecated( 100 since = "0.11.0", 101 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" 102 )] 103 pub use block::{decompress, decompress_into, decompress_size_prepended}; 104 105 #[cfg_attr( 106 all(feature = "safe-encode", feature = "safe-decode"), 107 forbid(unsafe_code) 108 )] 109 pub(crate) mod sink; 110