vendor/miniz_oxide/src/lib.rs

   1 //! A pure rust replacement for the [miniz](https://github.com/richgel999/miniz)
   2 //! DEFLATE/zlib encoder/decoder.
   3 //! The plan for this crate is to be used as a back-end for the
   4 //! [flate2](https://github.com/alexcrichton/flate2-rs) crate and eventually remove the
   5 //! need to depend on a C library.
   6 //!
   7 //! # Usage
   8 //! ## Simple compression/decompression:
   9 //! ``` rust
  10 //!
  11 //! use miniz_oxide::inflate::decompress_to_vec;
  12 //! use miniz_oxide::deflate::compress_to_vec;
  13 //!
  14 //! fn roundtrip(data: &[u8]) {
  15 //!     let compressed = compress_to_vec(data, 6);
  16 //!     let decompressed = decompress_to_vec(compressed.as_slice()).expect("Failed to decompress!");
  17 //! #   let _ = decompressed;
  18 //! }
  19 //!
  20 //! # roundtrip(b"Test_data test data lalalal blabla");
  21 //!
  22 //! ```
  23
  24 #![forbid(unsafe_code)]
  25 #![no_std]
  26
  27 extern crate alloc;
  28
  29 pub mod deflate;
  30 pub mod inflate;
  31 mod shared;
  32
  33 pub use crate::shared::update_adler32 as mz_adler32_oxide;
  34 pub use crate::shared::{MZ_ADLER32_INIT, MZ_DEFAULT_WINDOW_BITS};
  35
  36 /// A list of flush types.
  37 ///
  38 /// See <http://www.bolet.org/~pornin/deflate-flush.html> for more in-depth info.
  39 #[repr(i32)]
  40 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
  41 pub enum MZFlush {
  42     /// Don't force any flushing.
  43     /// Used when more input data is expected.
  44     None = 0,
  45     /// Zlib partial flush.
  46     /// Currently treated as [`Sync`].
  47     Partial = 1,
  48     /// Finish compressing the currently buffered data, and output an empty raw block.
  49     /// Has no use in decompression.
  50     Sync = 2,
  51     /// Same as [`Sync`], but resets the compression dictionary so that further compressed
  52     /// data does not depend on data compressed before the flush.
  53     ///
  54     /// Has no use in decompression, and is an error to supply in that case.
  55     Full = 3,
  56     /// Attempt to flush the remaining data and end the stream.
  57     Finish = 4,
  58     /// Not implemented.
  59     Block = 5,
  60 }
  61
  62 impl MZFlush {
  63     /// Create an MZFlush value from an integer value.
  64     ///
  65     /// Returns `MZError::Param` on invalid values.
  66     pub fn new(flush: i32) -> Result<Self, MZError> {
  67         match flush {
  68             0 => Ok(MZFlush::None),
  69             1 | 2 => Ok(MZFlush::Sync),
  70             3 => Ok(MZFlush::Full),
  71             4 => Ok(MZFlush::Finish),
  72             _ => Err(MZError::Param),
  73         }
  74     }
  75 }
  76
  77 /// A list of miniz successful status codes.
  78 ///
  79 /// These are emitted as the [`Ok`] side of a [`MZResult`] in the [`StreamResult`] returned from
  80 /// [`deflate::stream::deflate()`] or [`inflate::stream::inflate()`].
  81 #[repr(i32)]
  82 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
  83 pub enum MZStatus {
  84     /// Operation succeeded.
  85     ///
  86     /// Some data was decompressed or compressed; see the byte counters in the [`StreamResult`] for
  87     /// details.
  88     Ok = 0,
  89
  90     /// Operation succeeded and end of deflate stream was found.
  91     ///
  92     /// X-ref [`TINFLStatus::Done`][inflate::TINFLStatus::Done] or
  93     /// [`TDEFLStatus::Done`][deflate::core::TDEFLStatus::Done] for `inflate` or `deflate`
  94     /// respectively.
  95     StreamEnd = 1,
  96
  97     /// Unused
  98     NeedDict = 2,
  99 }
 100
 101 /// A list of miniz failed status codes.
 102 ///
 103 /// These are emitted as the [`Err`] side of a [`MZResult`] in the [`StreamResult`] returned from
 104 /// [`deflate::stream::deflate()`] or [`inflate::stream::inflate()`].
 105 #[repr(i32)]
 106 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 107 pub enum MZError {
 108     /// Unused
 109     ErrNo = -1,
 110
 111     /// General stream error.
 112     ///
 113     /// See [`inflate::stream::inflate()`] docs for details of how it can occur there.
 114     ///
 115     /// See [`deflate::stream::deflate()`] docs for how it can in principle occur there, though it's
 116     /// believed impossible in practice.
 117     Stream = -2,
 118
 119     /// Error in inflation; see [`inflate::stream::inflate()`] for details.
 120     ///
 121     /// Not returned from [`deflate::stream::deflate()`].
 122     Data = -3,
 123
 124     /// Unused
 125     Mem = -4,
 126
 127     /// Buffer-related error.
 128     ///
 129     /// See the docs of [`deflate::stream::deflate()`] or [`inflate::stream::inflate()`] for details
 130     /// of when it would trigger in the one you're using.
 131     Buf = -5,
 132
 133     /// Unused
 134     Version = -6,
 135
 136     /// Bad parameters.
 137     ///
 138     /// This can be returned from [`deflate::stream::deflate()`] in the case of bad parameters.  See
 139     /// [`TDEFLStatus::BadParam`][deflate::core::TDEFLStatus::BadParam].
 140     Param = -10_000,
 141 }
 142
 143 /// How compressed data is wrapped.
 144 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 145 #[non_exhaustive]
 146 pub enum DataFormat {
 147     /// Wrapped using the [zlib](http://www.zlib.org/rfc-zlib.html) format.
 148     Zlib,
 149     /// Zlib wrapped but ignore and don't compute the adler32 checksum.
 150     /// Currently only used for inflate, behaves the same as Zlib for compression.
 151     ZLibIgnoreChecksum,
 152     /// Raw DEFLATE.
 153     Raw,
 154 }
 155
 156 impl DataFormat {
 157     pub(crate) fn from_window_bits(window_bits: i32) -> DataFormat {
 158         if window_bits > 0 {
 159             DataFormat::Zlib
 160         } else {
 161             DataFormat::Raw
 162         }
 163     }
 164
 165     pub(crate) fn to_window_bits(self) -> i32 {
 166         match self {
 167             DataFormat::Zlib | DataFormat::ZLibIgnoreChecksum => shared::MZ_DEFAULT_WINDOW_BITS,
 168             DataFormat::Raw => -shared::MZ_DEFAULT_WINDOW_BITS,
 169         }
 170     }
 171 }
 172
 173 /// `Result` alias for all miniz status codes both successful and failed.
 174 pub type MZResult = Result<MZStatus, MZError>;
 175
 176 /// A structure containg the result of a call to the inflate or deflate streaming functions.
 177 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 178 pub struct StreamResult {
 179     /// The number of bytes consumed from the input slice.
 180     pub bytes_consumed: usize,
 181     /// The number of bytes written to the output slice.
 182     pub bytes_written: usize,
 183     /// The return status of the call.
 184     pub status: MZResult,
 185 }
 186
 187 impl StreamResult {
 188     #[inline]
 189     pub(crate) const fn error(error: MZError) -> StreamResult {
 190         StreamResult {
 191             bytes_consumed: 0,
 192             bytes_written: 0,
 193             status: Err(error),
 194         }
 195     }
 196 }
 197
 198 impl core::convert::From<StreamResult> for MZResult {
 199     fn from(res: StreamResult) -> Self {
 200         res.status
 201     }
 202 }
 203
 204 impl core::convert::From<&StreamResult> for MZResult {
 205     fn from(res: &StreamResult) -> Self {
 206         res.status
 207     }
 208 }