otf-pixels-compress 0.2.0

Compression and checksum primitives for otf-pixels codecs.
Documentation 
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

//! Compression and checksum primitives for `otf-pixels` codecs.
//!
//! Per ADR-0010 these are written from scratch, and per ADR-0012 they live
//! here rather than inside one codec, because three formats now share them:
//! PNG needs zlib, TIFF needs zlib *and* LZW, GIF needs LZW.
//!
//! # Scope
//!
//! This crate knows about bit streams and byte buffers. It knows nothing about
//! images, pixels or descriptors, and deliberately does not depend on
//! `otf-pixels-core`. That boundary is what lets it be tested directly against
//! reference implementations — the validation ADR-0010 requires — rather than
//! only through a codec.
//!
//! The consequence is a local [`Error`] type. Codecs translate it into their
//! own error at the boundary, which is one small helper per codec and keeps
//! the stable [`ErrorCode`] mapping where it belongs.
//!
//! [`ErrorCode`]: https://docs.rs/otf-pixels-core
//!
//! # Safety
//!
//! Every parser here reads attacker-controlled bytes and returns errors rather
//! than panicking. `unsafe_code = "forbid"` means the classic decompressor
//! failure — an out-of-bounds write through a back-reference — is
//! unrepresentable rather than merely avoided.

mod checksum;
mod deflate;
mod inflate;
mod lzw;

pub use checksum::{Adler32, Crc32};
pub use deflate::{Level, deflate, zlib_compress};
pub use inflate::{Inflater, ZlibStream, inflate_to, zlib_decompress};
pub use lzw::{BitOrder, LzwDecoder, LzwEncoder};

use core::fmt;

/// A compression or checksum failure.
///
/// Always caused by malformed input or by a caller-declared bound being
/// exceeded — never by an internal invariant, which is why there is no
/// "internal error" variant to handle.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Error {
    /// Which format the bytes claimed to be, for the caller's message.
    format: &'static str,
    detail: String,
}

impl Error {
    /// Report bytes that are invalid for `format`.
    #[must_use]
    pub fn malformed(format: &'static str, detail: impl Into<String>) -> Self {
        Self {
            format,
            detail: detail.into(),
        }
    }

    /// The format tag, suitable for a codec's own error type.
    #[must_use]
    pub const fn format(&self) -> &'static str {
        self.format
    }

    /// What went wrong.
    #[must_use]
    pub fn detail(&self) -> &str {
        &self.detail
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "malformed {} data: {}", self.format, self.detail)
    }
}

impl std::error::Error for Error {}

/// The result of a compression operation.
pub type Result<T> = std::result::Result<T, Error>;