Skip to main content

zxc/
error.rs

1// SPDX-License-Identifier: BSD-3-Clause
2/*
3 * ZXC - High-performance lossless compression
4 *
5 * Copyright (c) Bertrand Lebonnois and contributors.
6 */
7
8//! Error types and code mapping shared across the crate.
9
10use zxc_sys::{
11    ZXC_ERROR_BAD_BLOCK_SIZE, ZXC_ERROR_BAD_BLOCK_TYPE, ZXC_ERROR_BAD_CHECKSUM,
12    ZXC_ERROR_BAD_HEADER, ZXC_ERROR_BAD_LEVEL, ZXC_ERROR_BAD_MAGIC, ZXC_ERROR_BAD_OFFSET,
13    ZXC_ERROR_BAD_PARAM, ZXC_ERROR_BAD_VERSION, ZXC_ERROR_CORRUPT_DATA, ZXC_ERROR_DICT_MISMATCH,
14    ZXC_ERROR_DICT_REQUIRED, ZXC_ERROR_DICT_TOO_LARGE, ZXC_ERROR_DICT_UNSUPPORTED,
15    ZXC_ERROR_DST_TOO_SMALL, ZXC_ERROR_IO, ZXC_ERROR_MEMORY, ZXC_ERROR_NULL_INPUT,
16    ZXC_ERROR_OVERFLOW, ZXC_ERROR_SRC_TOO_SMALL,
17};
18
19/// Errors that can occur during ZXC operations.
20///
21/// Marked `#[non_exhaustive]`: new variants may be added in minor releases,
22/// so keep a wildcard arm when matching.
23#[derive(Debug, Clone, thiserror::Error)]
24#[non_exhaustive]
25pub enum Error {
26    /// Memory allocation failure
27    #[error("memory allocation failed")]
28    Memory,
29
30    /// Destination buffer too small
31    #[error("destination buffer too small")]
32    DstTooSmall,
33
34    /// Source buffer too small or truncated input
35    #[error("source buffer too small or truncated")]
36    SrcTooSmall,
37
38    /// Invalid magic word in file header
39    #[error("invalid magic word in header")]
40    BadMagic,
41
42    /// Unsupported file format version
43    #[error("unsupported file format version")]
44    BadVersion,
45
46    /// Corrupted or invalid header (checksum mismatch)
47    #[error("corrupted or invalid header")]
48    BadHeader,
49
50    /// A block's decoded bytes fail its checksum, or the archive digest mismatches
51    #[error("checksum verification failed")]
52    BadChecksum,
53
54    /// Corrupted compressed data
55    #[error("corrupted compressed data")]
56    CorruptData,
57
58    /// Invalid match offset during decompression
59    #[error("invalid match offset")]
60    BadOffset,
61
62    /// Buffer overflow detected during processing
63    #[error("buffer overflow detected")]
64    Overflow,
65
66    /// Read/write/seek failure on file
67    #[error("I/O error")]
68    Io,
69
70    /// Required input pointer is NULL
71    #[error("null input pointer")]
72    NullInput,
73
74    /// Unknown or unexpected block type
75    #[error("unknown block type")]
76    BadBlockType,
77
78    /// Invalid block size
79    #[error("invalid block size")]
80    BadBlockSize,
81
82    /// The archive requires a dictionary but none was provided
83    #[error("archive requires a dictionary but none was provided")]
84    DictRequired,
85
86    /// The provided dictionary does not match the archive's dictionary ID
87    #[error("dictionary ID does not match the archive header")]
88    DictMismatch,
89
90    /// The dictionary exceeds the maximum allowed size
91    #[error("dictionary exceeds maximum allowed size")]
92    DictTooLarge,
93
94    /// The compression level is out of range or unsupported by this context
95    #[error("compression level out of range")]
96    BadLevel,
97
98    /// Dictionary not supported by this context's workspace (static contexts)
99    #[error("dictionary not supported by this context's workspace")]
100    DictUnsupported,
101
102    /// A context parameter is unknown or its value out of bounds (e.g. a
103    /// thread count above the library maximum)
104    #[error("context parameter unknown or out of bounds")]
105    BadParam,
106
107    /// Shared literal Huffman table is not `ZXC_HUF_TABLE_SIZE` bytes
108    #[error("shared literal Huffman table must be ZXC_HUF_TABLE_SIZE bytes")]
109    BadHufTable,
110
111    /// The requested options are not supported by this API
112    #[error("unsupported option: {0}")]
113    Unsupported(&'static str),
114
115    /// The compressed data appears to be invalid or truncated
116    #[error("invalid compressed data")]
117    InvalidData,
118
119    /// Unknown error code from C library
120    #[error("unknown error (code: {0})")]
121    Unknown(i32),
122}
123
124/// Convert a negative error code from the C library to a Rust [`Error`].
125pub(crate) fn error_from_code(code: i64) -> Error {
126    match code as i32 {
127        ZXC_ERROR_MEMORY => Error::Memory,
128        ZXC_ERROR_DST_TOO_SMALL => Error::DstTooSmall,
129        ZXC_ERROR_SRC_TOO_SMALL => Error::SrcTooSmall,
130        ZXC_ERROR_BAD_MAGIC => Error::BadMagic,
131        ZXC_ERROR_BAD_VERSION => Error::BadVersion,
132        ZXC_ERROR_BAD_HEADER => Error::BadHeader,
133        ZXC_ERROR_BAD_CHECKSUM => Error::BadChecksum,
134        ZXC_ERROR_CORRUPT_DATA => Error::CorruptData,
135        ZXC_ERROR_BAD_OFFSET => Error::BadOffset,
136        ZXC_ERROR_OVERFLOW => Error::Overflow,
137        ZXC_ERROR_IO => Error::Io,
138        ZXC_ERROR_NULL_INPUT => Error::NullInput,
139        ZXC_ERROR_BAD_BLOCK_TYPE => Error::BadBlockType,
140        ZXC_ERROR_BAD_BLOCK_SIZE => Error::BadBlockSize,
141        ZXC_ERROR_DICT_REQUIRED => Error::DictRequired,
142        ZXC_ERROR_DICT_MISMATCH => Error::DictMismatch,
143        ZXC_ERROR_DICT_TOO_LARGE => Error::DictTooLarge,
144        ZXC_ERROR_BAD_LEVEL => Error::BadLevel,
145        ZXC_ERROR_DICT_UNSUPPORTED => Error::DictUnsupported,
146        ZXC_ERROR_BAD_PARAM => Error::BadParam,
147        _ => Error::Unknown(code as i32),
148    }
149}
150
151/// Result type for ZXC operations.
152pub type Result<T> = std::result::Result<T, Error>;