deflate/

compression_options.rs

//! This module contains the various options to tweak how compression is performed.
//!
//! Note that due to the nature of the `DEFLATE` format, lower compression levels
//! may for some data compress better than higher compression levels.
//!
//! For applications where a maximum level of compression (irrespective of compression
//! speed) is required, consider using the [`Zopfli`](https://crates.io/crates/zopfli)
//! compressor, which uses a specialised (but slow) algorithm to figure out the maximum
//! of compression for the provided data.
//!
use lz77::MatchingType;
use std::convert::From;

pub const HIGH_MAX_HASH_CHECKS: u16 = 1768;
pub const HIGH_LAZY_IF_LESS_THAN: u16 = 128;
/// The maximum number of hash checks that make sense as this is the length
/// of the hash chain.
pub const MAX_HASH_CHECKS: u16 = 32 * 1024;
pub const DEFAULT_MAX_HASH_CHECKS: u16 = 128;
pub const DEFAULT_LAZY_IF_LESS_THAN: u16 = 32;

/// An enum describing the level of compression to be used by the encoder
///
/// Higher compression ratios will take longer to encode.
///
/// This is a simplified interface to specify a compression level.
///
/// [See also `CompressionOptions`](./struct.CompressionOptions.html) which provides for
/// tweaking the settings more finely.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
pub enum Compression {
    /// Fast minimal compression (`CompressionOptions::fast()`).
    Fast,
    /// Default level (`CompressionOptions::default()`).
    Default,
    /// Higher compression level (`CompressionOptions::high()`).
    ///
    /// Best in this context isn't actually the highest possible level
    /// the encoder can do, but is meant to emulate the `Best` setting in the `Flate2`
    /// library.
    Best,
}

impl Default for Compression {
    fn default() -> Compression {
        Compression::Default
    }
}

/// Enum allowing some special options (not implemented yet)!
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
pub enum SpecialOptions {
    /// Compress normally.
    Normal,
    /// Force fixed huffman tables. (Unimplemented!).
    _ForceFixed,
    /// Force stored (uncompressed) blocks only. (Unimplemented!).
    _ForceStored,
}

impl Default for SpecialOptions {
    fn default() -> SpecialOptions {
        SpecialOptions::Normal
    }
}

pub const DEFAULT_OPTIONS: CompressionOptions = CompressionOptions {
    max_hash_checks: DEFAULT_MAX_HASH_CHECKS,
    lazy_if_less_than: DEFAULT_LAZY_IF_LESS_THAN,
    matching_type: MatchingType::Lazy,
    special: SpecialOptions::Normal,
};

/// A struct describing the options for a compressor or compression function.
///
/// These values are not stable and still subject to change!
#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
pub struct CompressionOptions {
    /// The maximum number of checks to make in the hash table for matches.
    ///
    /// Higher numbers mean slower, but better compression. Very high (say `>1024`) values
    /// will impact compression speed a lot. The maximum match length is 2^15, so values higher than
    /// this won't make any difference, and will be truncated to 2^15 by the compression
    /// function/writer.
    ///
    /// Default value: `128`
    pub max_hash_checks: u16,
    // pub _window_size: u16,
    /// Only lazy match if we have a length less than this value.
    ///
    /// Higher values degrade compression slightly, but improve compression speed.
    ///
    /// * `0`: Never lazy match. (Same effect as setting MatchingType to greedy, but may be slower).
    /// * `1...257`: Only check for a better match if the first match was shorter than this value.
    /// * `258`: Always lazy match.
    ///
    /// As the maximum length of a match is `258`, values higher than this will have
    /// no further effect.
    ///
    /// * Default value: `32`
    pub lazy_if_less_than: u16,

    // pub _decent_match: u16,
    /// Whether to use lazy or greedy matching.
    ///
    /// Lazy matching will provide better compression, at the expense of compression speed.
    ///
    /// As a special case, if max_hash_checks is set to 0, and matching_type is set to lazy,
    /// compression using only run-length encoding (i.e maximum match distance of 1) is performed.
    /// (This may be changed in the future but is defined like this at the moment to avoid API
    /// breakage.
    ///
    /// [See `MatchingType`](./enum.MatchingType.html)
    ///
    /// * Default value: `MatchingType::Lazy`
    pub matching_type: MatchingType,
    /// Force fixed/stored blocks (Not implemented yet).
    /// * Default value: `SpecialOptions::Normal`
    pub special: SpecialOptions,
}

// Some standard profiles for the compression options.
// Ord should be implemented at some point, but won't yet until the struct is stabilised.
impl CompressionOptions {
    /// Returns compression settings rouhgly corresponding to the `HIGH(9)` setting in miniz.
    pub fn high() -> CompressionOptions {
        CompressionOptions {
            max_hash_checks: HIGH_MAX_HASH_CHECKS,
            lazy_if_less_than: HIGH_LAZY_IF_LESS_THAN,
            matching_type: MatchingType::Lazy,
            special: SpecialOptions::Normal,
        }
    }

    /// Returns  a fast set of compression settings
    ///
    /// Ideally this should roughly correspond to the `FAST(1)` setting in miniz.
    /// However, that setting makes miniz use a somewhat different algorhithm,
    /// so currently hte fast level in this library is slower and better compressing
    /// than the corresponding level in miniz.
    pub fn fast() -> CompressionOptions {
        CompressionOptions {
            max_hash_checks: 1,
            lazy_if_less_than: 0,
            matching_type: MatchingType::Greedy,
            special: SpecialOptions::Normal,
        }
    }

    /// Returns a set of compression settings that makes the compressor only compress using
    /// huffman coding. (Ignoring any length/distance matching)
    ///
    /// This will normally have the worst compression ratio (besides only using uncompressed data),
    /// but may be the fastest method in some cases.
    pub fn huffman_only() -> CompressionOptions {
        CompressionOptions {
            max_hash_checks: 0,
            lazy_if_less_than: 0,
            matching_type: MatchingType::Greedy,
            special: SpecialOptions::Normal,
        }
    }

    /// Returns a set of compression settings that makes the compressor compress only using
    /// run-length encoding (i.e only looking for matches one byte back).
    ///
    /// This is very fast, but tends to compress worse than looking for more matches using hash
    /// chains that the slower settings do.
    /// Works best on data that has runs of equivialent bytes, like binary or simple images,
    /// less good for text.
    pub fn rle() -> CompressionOptions {
        CompressionOptions {
            max_hash_checks: 0,
            lazy_if_less_than: 0,
            matching_type: MatchingType::Lazy,
            special: SpecialOptions::Normal,
        }
    }
}

impl Default for CompressionOptions {
    /// Returns the options describing the default compression level.
    fn default() -> CompressionOptions {
        DEFAULT_OPTIONS
    }
}

impl From<Compression> for CompressionOptions {
    fn from(compression: Compression) -> CompressionOptions {
        match compression {
            Compression::Fast => CompressionOptions::fast(),
            Compression::Default => CompressionOptions::default(),
            Compression::Best => CompressionOptions::high(),
        }
    }
}