Struct xz2::stream::LzmaOptions
[−]
[src]
pub struct LzmaOptions { /* fields omitted */ }
Options that can be used to configure how LZMA encoding happens.
This builder is consumed by a number of other methods.
Methods
impl LzmaOptions
[src]
fn new_preset(preset: u32) -> Result<LzmaOptions, Error>
Creates a new blank set of options for encoding.
The preset
argument is the compression level to use, typically in the
range of 0-9.
fn dict_size(&mut self, size: u32) -> &mut LzmaOptions
Configures the dictionary size, in bytes
Dictionary size indicates how many bytes of the recently processed uncompressed data is kept in memory.
The minimum dictionary size is 4096 bytes and the default is 223, 8MB.
fn literal_context_bits(&mut self, bits: u32) -> &mut LzmaOptions
Configures the number of literal context bits.
How many of the highest bits of the previous uncompressed eight-bit byte (also known as `literal') are taken into account when predicting the bits of the next literal.
The maximum value to this is 4 and the default is 3. It is not currently
supported if this plus literal_position_bits
is greater than 4.
fn literal_position_bits(&mut self, bits: u32) -> &mut LzmaOptions
Configures the number of literal position bits.
This affects what kind of alignment in the uncompressed data is assumed
when encoding literals. A literal is a single 8-bit byte. See
position_bits
for more information about alignment.
The default for this is 0.
fn position_bits(&mut self, bits: u32) -> &mut LzmaOptions
Configures the number of position bits.
Position bits affects what kind of alignment in the uncompressed data is assumed in general. The default of 2 means four-byte alignment (2^ pb =22=4), which is often a good choice when there's no better guess.
When the aligment is known, setting pb accordingly may reduce the file size a little. E.g. with text files having one-byte alignment (US-ASCII, ISO-8859-*, UTF-8), setting pb=0 can improve compression slightly. For UTF-16 text, pb=1 is a good choice. If the alignment is an odd number like 3 bytes, pb=0 might be the best choice.
Even though the assumed alignment can be adjusted with pb and lp, LZMA1 and LZMA2 still slightly favor 16-byte alignment. It might be worth taking into account when designing file formats that are likely to be often compressed with LZMA1 or LZMA2.
fn mode(&mut self, mode: Mode) -> &mut LzmaOptions
Configures the compression mode.
fn nice_len(&mut self, len: u32) -> &mut LzmaOptions
Configures the nice length of a match.
This determines how many bytes the encoder compares from the match
candidates when looking for the best match. Once a match of at least
nice_len
bytes long is found, the encoder stops looking for better
candidates and encodes the match. (Naturally, if the found match is
actually longer than nice_len
, the actual length is encoded; it's not
truncated to nice_len
.)
Bigger values usually increase the compression ratio and compression time. For most files, 32 to 128 is a good value, which gives very good compression ratio at good speed.
The exact minimum value depends on the match finder. The maximum is 273, which is the maximum length of a match that LZMA1 and LZMA2 can encode.
fn match_finder(&mut self, mf: MatchFinder) -> &mut LzmaOptions
Configures the match finder ID.
fn depth(&mut self, depth: u32) -> &mut LzmaOptions
Maximum search depth in the match finder.
For every input byte, match finder searches through the hash chain or binary tree in a loop, each iteration going one step deeper in the chain or tree. The searching stops if
- a match of at least
nice_len
bytes long is found; - all match candidates from the hash chain or binary tree have been checked; or
- maximum search depth is reached.
Maximum search depth is needed to prevent the match finder from wasting too much time in case there are lots of short match candidates. On the other hand, stopping the search before all candidates have been checked can reduce compression ratio.
Setting depth to zero tells liblzma to use an automatic default value, that depends on the selected match finder and nice_len. The default is in the range [4, 200] or so (it may vary between liblzma versions).
Using a bigger depth value than the default can increase compression ratio in some cases. There is no strict maximum value, but high values (thousands or millions) should be used with care: the encoder could remain fast enough with typical input, but malicious input could cause the match finder to slow down dramatically, possibly creating a denial of service attack.