Struct BifIndex 

pub struct BifIndex<R = File> { /* private fields */ }

A lazily-read BIF archive.

Holds both resource tables; payload bytes are read from the backing source on each request.

Compressed archives are supported behind the bzf feature: each entry’s packed extent is derived from offset ordering and decompressed on read, so the owned-bytes contract is identical either way and callers need not care which kind they mounted.

Implementations

impl BifIndex<File>

pub fn open(path: impl AsRef<Path>) -> Result<Self, BifBinaryError>

Opens an archive from disk and indexes it.

Compression is inferred from the path: a .bzf extension (case-insensitive) means LZMA-compressed payloads, anything else means plain. That is the only signal shipping data carries — the file signature is BIFF either way — so it is read here rather than guessed from content.

Errors

The same as Self::open_with_options under the default options.

pub fn open_with_options( path: impl AsRef<Path>, options: BifReadOptions, ) -> Result<Self, BifBinaryError>

Opens an archive from disk with explicit read options.

Compression is inferred from the path as in Self::open.

Errors

BifBinaryError::Io when path will not open or its length cannot be read, and whatever Self::new_with_options reports for the file it opened. A .bzf path with the bzf feature off fails there, as BifBinaryError::BzfFeatureDisabled.

impl<R: Read + Seek> BifIndex<R>

pub fn new(section: SectionReader<R>) -> Result<Self, BifBinaryError>

Indexes an uncompressed archive occupying section.

Errors

The same as Self::new_with_options for a BifContainer::Biff archive under the default options.

pub fn new_with_container( section: SectionReader<R>, container: BifContainer, ) -> Result<Self, BifBinaryError>

Indexes an archive occupying section, stating its container kind.

Windowed constructors take the kind explicitly because a window has no filename to read it from.

Errors

The same as Self::new_with_options under the default options.

pub fn new_with_options( section: SectionReader<R>, container: BifContainer, options: BifReadOptions, ) -> Result<Self, BifBinaryError>

Indexes the archive occupying section with explicit read options.

Reads both resource tables immediately. A table that will not parse fails here, because nothing about the archive is knowable without it. An entry whose declared byte range escapes the archive does not: it is marked with a defect and the rest stays readable.

Errors

BifBinaryError::InvalidHeader when the header or either table escapes the section’s bounds or the two entry counts sum past u32, and BifBinaryError::InvalidMagic or BifBinaryError::InvalidVersion for a signature or version options.input does not accept.

BifBinaryError::BzfFeatureDisabled when container is Bzf and the crate was built without the bzf feature. Indexing does not decompress anything, so this is refused up front rather than at the first read.

BifBinaryError::Io when the backing source fails.

pub fn read_entry(&self, position: usize) -> Result<Vec<u8>, BifBinaryError>

Reads the bytes of the entry at position in table order.

This is the lookup a KEY table drives: its rows carry the resource’s position within the BIF.

Errors

BifBinaryError::InvalidData when position is past the end of the table or the backing read comes up short, and BifBinaryError::InvalidHeader when the entry carries the defect Self::new_with_options leaves on one whose range escapes the archive.

For a BZF archive the payload is decompressed here rather than at index time, so BifBinaryError::InvalidData also covers a declared length beyond addressable memory and an LZMA stream that will not decode. A plain BIFF entry has neither failure.

pub fn container(&self) -> BifContainer

Returns the container kind this archive was opened as.

pub fn resolve_by_id( &self, resource_id: ResourceId, ) -> Result<Option<Vec<u8>>, BifBinaryError>

Reads the bytes of the resource carrying resource_id.

Returns Ok(None) when no entry carries that id.

Errors

Only once the lookup has matched, so an error here means a damaged archive rather than a miss: the terms Self::read_entry gives.

pub fn entry_section(&self, position: usize) -> Option<SectionReader<R>>

Returns a window over the entry’s bytes without reading them.

Returns None when position is out of range or the entry carries a defect.

pub fn iter_resources( &self, ) -> impl Iterator<Item = Result<(&BifIndexEntry, Vec<u8>), BifBinaryError>> + '_

Iterates every resource, pairing its entry with freshly-read bytes.

Each item is read on demand, so a caller that stops early pays only for what it consumed.

impl<R> BifIndex<R>

pub fn entries(&self) -> &[BifIndexEntry]

Returns the indexed entries in table order.

pub fn entry(&self, position: usize) -> Option<&BifIndexEntry>

Returns the entry at position without reading its bytes.

pub fn len(&self) -> usize

Returns the number of indexed resources.

pub fn is_empty(&self) -> bool

Returns whether the archive holds no resources.

pub fn contains_id(&self, resource_id: ResourceId) -> bool

Returns whether the archive holds a resource with resource_id.

True even when the entry is defective: the archive claims the resource exists, it just cannot be read.

pub fn defects( &self, ) -> impl Iterator<Item = (usize, &BifIndexEntry, &EntryDefect)> + '_

Iterates the entries that cannot be read, with their table positions.

Whatever mounts this archive is expected to surface these rather than let a partially-readable archive pass as intact.

pub fn has_defects(&self) -> bool

Returns whether any entry in the archive is unreadable.

Trait Implementations

impl<R: Debug> Debug for BifIndex<R>

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

Formats the value using the given formatter.