Struct SalvagedEntry 

#[non_exhaustive]
pub struct SalvagedEntry {
    pub scan_position: usize,
    pub offset: u64,
    pub payload_start: u64,
    pub meta: EntryMeta,
    pub status: SalvageStatus,
    pub shadows: Option<usize>,
    pub collides_with: Option<usize>,
    pub marked_deleted: bool,
}

One entry the scan recovered.

#[non_exhaustive] plus SalvagedEntry::new, for the same reason Candidate carries both — see that type’s own doc. This one is built by annotate_candidates in ordinary use, but every per-format scanner crate builds one directly to drive its write_payload seam, so the literal it used to need was an out-of-crate literal all the same.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

scan_position: usize

This entry’s position in SCAN order — not an index any container’s own format assigns, and never renumbered by what list would show. A later task’s CLI surfaces this distinction explicitly (--index on salvage names a scan position, not a list index).

offset: u64

payload_start: u64

Carried forward from Candidate::payload_start — see that field’s doc for why a consumer must use this rather than re-deriving a payload’s location from offset itself.

meta: EntryMeta

status: SalvageStatus

shadows: Option<usize>

Set when this record’s (name, declared_len, verifier) all agree with an EARLIER record’s — a measurement, never inferred from a repeated name alone, and never set for a degenerate zero-length checksum (every empty file and every directory entry shares one). See annotate_candidates for where this is computed.

This is the byte-identical duplicate, and ONLY that. The other, weaker fact — an earlier record under the same name whose content this scan could not prove identical — is Self::collides_with, and the two are mutually exclusive by construction. They were one word (“shadow”) until the final whole-branch review measured what that cost: stuffr list’s own fidelity warning uses “shadowed” for a repeated NAME, so on an archive whose duplicates differ, list said two records were shadowed and salvage --list marked none.

collides_with: Option<usize>

Set when an EARLIER record carries the same meta.name and this one is not that record’s Self::shadows — i.e. the name repeats but the content could not be proven identical.

This is the fact stuffr list’s Fidelity::EntryCountMismatch warning is about: a later record repeating a name is what makes an earlier one unreachable through a central directory’s name index, whatever the bytes under it. It is also the fact that decides anything on the WRITE side, because two records under one name and two different payloads cannot both land on one path.

Deliberately NOT gated on a verifier, a declared length or the degenerate zero-length case the way Self::shadows is: those guards exist because claiming two records are COPIES of each other needs proof, and this annotation claims no such thing. A repeated name is directly observed, and None here means only that no earlier record used this name — never that one did and this could not tell.

marked_deleted: bool

Carried forward unchanged from Candidate::marked_deleted — see that field for the whole ruling. Unlike Self::shadows and Self::collides_with, this is not something this module MEASURES: it is a fact the archive’s own record states, which only the scanner that read that record can know.

Implementations

impl SalvagedEntry

pub fn new( scan_position: usize, offset: u64, payload_start: u64, meta: EntryMeta, status: SalvageStatus, ) -> Self

An entry at scan position scan_position, found at offset, whose payload begins at payload_start, carrying meta and proven to status.

The three fields this does not take default to “nothing was observed”: no shadow, no name collision, not marked deleted. All three are annotations annotate_candidates adds (or, for marked_deleted, carries forward from Candidate), so a caller building one directly — every per-format write_payload test does — wants exactly those defaults.

pub fn with_shadows(self, shadows: Option<usize>) -> Self

Sets Self::shadows — the byte-identical duplicate, and only that. See the field’s own doc for what separates it from Self::collides_with.

pub fn with_collides_with(self, collides_with: Option<usize>) -> Self

Sets Self::collides_with — the weaker, name-only annotation.

pub fn with_marked_deleted(self, marked_deleted: bool) -> Self

Sets Self::marked_deleted, carried forward from Candidate::marked_deleted rather than measured here.

Trait Implementations

impl Debug for SalvagedEntry

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

Formats the value using the given formatter.