pub struct Snapshot<'view> { /* private fields */ }Expand description
Validated, borrowed handle to a snapshot’s bytes and section table.
A Snapshot is constructed via Snapshot::open (structural, default
ValidationLevel::Layout), Snapshot::open_with, or
Snapshot::open_checked (structural plus table-checksum
verification). The handle itself is Copy and trivially cheap to pass;
cloning it does not re-validate.
For header-only inspection without parsing the section table, use
HeaderOnlySnapshot instead — Snapshot always carries a validated
section table.
§Performance
Open is O(s) for s sections (header + table walk; payload bytes are
never scanned). Subsequent reads are O(1) to O(log s) per call;
checksum verification (Snapshot::verify_all, Section::verify) is
O(covered bytes). No allocation occurs.
Implementations§
Source§impl<'view> Snapshot<'view>
impl<'view> Snapshot<'view>
Sourcepub fn open(bytes: &'view [u8]) -> Result<Self, SnapshotError>
pub fn open(bytes: &'view [u8]) -> Result<Self, SnapshotError>
Opens bytes as a structurally validated snapshot at
ValidationLevel::Layout.
This is a structural open: the header, section table shape, kind
order, and payload bounds are validated, but no payload bytes are
verified and the header’s table_crc32c is not checked — the
container is no_std and carries no checksum implementation, so a
checksum-bearing open must go through Snapshot::open_checked.
Payload integrity is checked on demand via Snapshot::verify_all
or Section::verify.
§Errors
Returns SnapshotError for any header, section table, or layout
invariant violation.
§Performance
O(s) for s section entries (header + table walk only).
Sourcepub fn open_checked(
bytes: &'view [u8],
checksum: Checksum32,
) -> Result<Self, SnapshotError>
pub fn open_checked( bytes: &'view [u8], checksum: Checksum32, ) -> Result<Self, SnapshotError>
Opens bytes structurally and verifies the header’s table_crc32c
against the section-table bytes.
Section payloads are still not verified; use
Snapshot::verify_all for that.
§Errors
Returns SnapshotError::TableChecksumMismatch when the recomputed
table checksum differs from the header’s, or any structural
SnapshotError from Snapshot::open.
§Performance
O(s) for s section entries (table walk plus one checksum fold
over the table bytes).
Sourcepub fn open_with(
bytes: &'view [u8],
level: ValidationLevel,
) -> Result<Self, SnapshotError>
pub fn open_with( bytes: &'view [u8], level: ValidationLevel, ) -> Result<Self, SnapshotError>
Opens bytes as a snapshot validated at the requested level.
level selects between ValidationLevel::SectionTable (per-entry
self-consistency, bounds, and kind order) and
ValidationLevel::Layout (adds non-overlapping monotonic offset
enforcement). Header-only validation is deliberately not selectable
here; callers wanting it should use HeaderOnlySnapshot::open.
§Errors
Returns SnapshotError for any invariant violation visible at
the requested level.
§Performance
O(s) at either level.
Sourcepub fn verify_all(&self, checksum: Checksum32) -> Result<(), SnapshotError>
pub fn verify_all(&self, checksum: Checksum32) -> Result<(), SnapshotError>
Verifies every section payload against its entry’s recorded CRC-32C.
§Errors
Returns SnapshotError::SectionChecksumMismatch naming the first
section whose payload bytes do not hash to the recorded value.
§Performance
This method is O(total payload bytes) (one checksum fold per
section).
Sourcepub const fn format_major(&self) -> u32
pub const fn format_major(&self) -> u32
Sourcepub const fn format_minor(&self) -> u32
pub const fn format_minor(&self) -> u32
Sourcepub const fn section_count(&self) -> usize
pub const fn section_count(&self) -> usize
Sourcepub fn sections(&self) -> SectionIter<'view> ⓘ
pub fn sections(&self) -> SectionIter<'view> ⓘ
Returns an iterator over all validated sections.
§Performance
Constructing the iterator is O(1); advancing it is O(1) per step.
Sourcepub fn section(&self, kind: u32) -> Option<Section<'view>>
pub fn section(&self, kind: u32) -> Option<Section<'view>>
Returns the section with the given kind, when present.
§Performance
This method is O(log s) for s section entries: the v2
strictly-ascending kind mandate makes the table binary-searchable.
Sourcepub fn typed_section<W>(
&self,
kind: u32,
expected_version: u32,
) -> Result<&'view [W::LittleEndianWord], SectionBindError>where
W: SnapshotWidth,
pub fn typed_section<W>(
&self,
kind: u32,
expected_version: u32,
) -> Result<&'view [W::LittleEndianWord], SectionBindError>where
W: SnapshotWidth,
Binds a width-typed section by kind and version in one step.
Looks up the section, checks its version against expected_version, and
borrows the payload as &[W::LittleEndianWord]. This is the single
section-open primitive every layout crate reuses instead of
re-implementing the lookup/version/typed-view sequence with its own error
variants; callers map SectionBindError into their own typed error at
the boundary.
§Errors
Returns SectionBindError::Missing when no section has kind,
SectionBindError::VersionMismatch when the recorded version differs,
and SectionBindError::View when the payload cannot be borrowed as the
requested little-endian word.
§Performance
This method is O(log s) for s section entries plus the typed-view
checks.