Struct lz_fear::framed::CompressionSettings

pub struct CompressionSettings<'a> { /* private fields */ }

A builder-style struct that configures compression settings. This is how you compress LZ4 frames. (An LZ4 file usually consists of a single frame.)

Create it using Default::default().

Implementations

impl<'a> CompressionSettings<'a>

pub fn independent_blocks(&mut self, v: bool) -> &mut Self

In independent mode, blocks are not allowed to reference data from previous blocks. Hence, using dependent blocks yields slightly better compression. The downside of dependent blocks is that seeking becomes impossible - the entire frame always has to be decompressed from the beginning.

Blocks are independent by default.

pub fn block_checksums(&mut self, v: bool) -> &mut Self

Block checksums can help detect data corruption in storage and transit. They do not offer error correction though.

In most cases, block checksums are not very helpful because you generally want a lower layer to deal with data corruption more comprehensively.

Block checksums are disabled by default.

pub fn content_checksum(&mut self, v: bool) -> &mut Self

The content checksum (also called frame checksum) is calculated over the contents of the entire frame. This makes them cheaper than block checksums as their size overhead is constant as well as marginally more useful, because they can help protect against incorrect decompression.

Note that the content checksum can only be verified after the entire frame has been read (and returned!), which is the downside of content checksums.

Frame checksums are enabled by default.

pub fn block_size(&mut self, v: usize) -> &mut Self

Only valid values are 4MiB, 1MiB, 256KiB, 64KiB (TODO: better interface for this)

The default block size is 4 MiB.

pub fn dictionary(&mut self, id: u32, dict: &'a [u8]) -> &mut Self

A dictionary is essentially a constant slice of bytes shared by the compressing and decompressing party. Using a dictionary can improve compression ratios, because the compressor can reference data from the dictionary.

The dictionary id is an application-specific identifier which can be used during decompression to determine which dictionary to use.

Note that while the size of a dictionary can be arbitrary, dictionaries larger than 64 KiB are not useful as the LZ4 algorithm does not support backreferences by more than 64 KiB, i.e. any dictionary content before the trailing 64 KiB is silently ignored.

By default, no dictionary is used and no id is specified.

pub fn dictionary_id_nonsense_override(&mut self, id: Option<u32>) -> &mut Self

The dictionary id header field is quite obviously intended to tell anyone trying to decompress your frame which dictionary to use. So it is only natural to assume that the absence of a dictionary id indicates that no dictionary was used.

Unfortunately this assumption turns out to be incorrect. The LZ4 CLI simply never writes a dictionary id. The major downside is that you can no longer distinguish corrupted data from a missing dictionary (unless you write block checksums, which the LZ4 CLI also never does).

Hence, this library is opinionated in the sense that we always want you to specify either neither or both of these things (the LZ4 CLI basically just ignores the dictionary id completely and only cares about whether you specify a dictionary parameter or not).

If you think you know better (you probably don’t) you may use this method to break this rule.

pub fn compress<R: Read, W: Write>( &self, reader: R, writer: W ) -> Result<(), CompressionError>

pub fn compress_with_size_unchecked<R: Read, W: Write>( &self, reader: R, writer: W, content_size: u64 ) -> Result<(), CompressionError>

pub fn compress_with_size<R: Read + Seek, W: Write>( &self, reader: R, writer: W ) -> Result<(), CompressionError>

Trait Implementations

impl<'a> Default for CompressionSettings<'a>

fn default() -> Self

Returns the “default value” for a type.