Enum Error 

#[non_exhaustive]
pub enum Error {
    Io(Error),
    Usage(String),
    FormatNotEnabled(FormatId),
    UnknownFormat {
        seen: String,
    },
    AmbiguousFormat {
        candidates: String,
    },
    NotSeekable {
        format: FormatId,
    },
    SpillLimitExceeded {
        limit: u64,
    },
    ResourceLimit(String),
    Corrupt(String),
    UnsafePath {
        path: String,
        reason: &'static str,
    },
    FidelityDegraded(usize),
    EntryNotFound(String),
    Unsupported(String),
    CapabilityUnavailable {
        format: FormatId,
        available: &'static str,
        requested: &'static str,
    },
    ChainTooDeep {
        depth: usize,
    },
    NotAnArchive {
        chain: String,
    },
}

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Io(Error)

Usage(String)

FormatNotEnabled(FormatId)

UnknownFormat

Fields

seen: String

AmbiguousFormat

Fields

candidates: String

NotSeekable

Fields

format: FormatId

SpillLimitExceeded

Fields

limit: u64

ResourceLimit(String)

Corrupt(String)

UnsafePath

Fields

path: String

reason: &'static str

FidelityDegraded(usize)

EntryNotFound(String)

Unsupported(String)

CapabilityUnavailable

Fields

format: FormatId

available: &'static str

The direction that IS available, e.g. “read”.

requested: &'static str

The direction that was asked for and is not, e.g. “written”.

ChainTooDeep

Nesting exceeded crate::probe::MAX_CHAIN_DEPTH. Names the bound so the message is actionable rather than merely a refusal.

Fields

depth: usize

NotAnArchive

The chain resolved to raw bytes with no container to open — e.g. list/test pointed at a plain codec stream, or at a file whose magic and extension both name none. Names what the input actually resolved to (chain.describe()), so “unpack this .gz” is actionable rather than a bare refusal.

Fields

chain: String

Implementations

impl Error

pub fn entry_index_out_of_range(index: usize, entries: usize) -> Self

“Entry number index does not exist; here is what does.”

One constructor rather than a format! at each raiser, because there are two routes to an out-of-range index and they must report it IDENTICALLY: a container’s own crate::ArchiveRead::by_index finds it immediately (zip, which has a central directory to check against), while a caller counting a forward walk finds it only at the end of the archive (tar, ar, cpio, and anything on a pipe). A script that could tell those apart from the message would be reading an implementation detail of the source it was handed.

Self::EntryNotFound rather than Self::Usage because the variant exists for exactly this — “you named an entry this archive does not have” — and carries the same exit code, 2. The payload is shaped to read inside that variant’s own entry \{0}` not found` wording.

Indices are 0-based throughout, so the valid range is stated explicitly rather than left to be derived from the count: 0-5 is harder to get wrong than “6 entries” is.

pub fn exit_code(&self) -> i32

Maps to the process exit code, per the spec’s table. Lives here rather than in the CLI so it is unit-testable without a process spawn.

pub fn from_decode_io(e: Error) -> Self

Classifies an io error that arose while decoding.

Malformed input becomes Error::Corrupt (exit 5); everything else stays Error::Io (exit 1). InvalidData is the convention every codec’s decoder is expected to normalise onto for malformed input; a codec whose backend disagrees adapts at its own boundary rather than this classification changing. gzip is one such codec: flate2’s pure-Rust backend actually raises InvalidInput and UnexpectedEof, never InvalidData, so gzip’s decoder wraps it in an adapter that folds both onto InvalidData before this function ever sees them.

OutOfMemory becomes Error::ResourceLimit (exit 6), not Corrupt: a codec whose dictionary allocation would exceed DecodeOpts::memory_limit is refusing to allocate, not reporting a damaged file, and exit 5 would actively mislead the caller about which of those happened. A codec that raises this kind is expected to have NOT routed it through the same InvalidData-folding adapter it uses for malformed input, the same way InvalidData above is a convention the codec opts into deliberately.

One rule here rather than a helper each codec calls: putting the decision in nine places means the natural code — a bare ? on an io::Error — silently bypasses it, and a convention whose failure mode is invisible is not a convention. Conformance property 9 enforces the codec half, that malformed input surfaces as InvalidData at all.

Lives in stuffr-core rather than in ops because Phase 2’s containers need the identical classification on their own decode paths.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.