      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196

    //! 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(),
            }
        }
    }

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)