Struct ErfIndex 

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

A lazily-read ERF-family archive.

Holds the archive’s tables and metadata; resource bytes are read from the backing source on each request. Cheap to construct relative to read_erf on any archive whose data dwarfs its tables.

Implementations

impl ErfIndex<File>

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

Opens an archive from disk and indexes it.

Errors

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

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

Opens an archive from disk with explicit read options.

Errors

ErfBinaryError::Io when path will not open or its length cannot be read, and whatever Self::new_with_options reports for the file it opened.

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

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

Indexes the archive occupying section.

Errors

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

pub fn new_with_options( section: SectionReader<R>, options: ErfReadOptions, ) -> Result<Self, ErfBinaryError>

Indexes the archive occupying section with explicit read options.

Reads the header and both entry 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

ErfBinaryError::InvalidHeader when the header or either table escapes the section’s bounds, ErfBinaryError::InvalidMagic and ErfBinaryError::InvalidVersion for a signature or version options.input does not accept, and ErfBinaryError::InvalidData when a key names a resource id past the entry count.

ErfBinaryError::InvalidResRef for an entry name that is not a valid resref, ErfBinaryError::TextDecoding for a localized string that is not valid text in the archive’s encoding, and ErfBinaryError::Io when the backing source fails.

An entry whose declared data range escapes the archive is not one of these. It carries a defect instead, and only reading that entry fails.

pub fn resolve( &self, resref: &ResRef, resource_type: ResourceTypeCode, ) -> Result<Option<Vec<u8>>, ErfBinaryError>

Reads the bytes of the resource named resref with resource_type.

Returns Ok(None) when the archive holds no such resource.

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 read_entry(&self, index: usize) -> Result<Vec<u8>, ErfBinaryError>

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

Errors

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

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

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

This is how a nested archive is opened in place: pass the returned window to ErfIndex::new to index an archive stored as an entry of this one. Returns None when index is out of range or the entry carries a defect.

pub fn resource_section( &self, resref: &ResRef, resource_type: ResourceTypeCode, ) -> Option<SectionReader<R>>

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

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

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> ErfIndex<R>

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

Returns the indexed entries in table order.

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 file_type(&self) -> ErfFileType

Returns the archive’s container signature.

pub fn build_year(&self) -> u32

Returns the archive’s build year field.

pub fn build_day(&self) -> u32

Returns the archive’s build day field.

pub fn description_strref(&self) -> StrRef

Returns the archive’s description string reference.

pub fn localized_strings(&self) -> &[ErfLocalizedString]

Returns the archive’s localized description strings.

These are parsed up front: they are kilobyte-scale at most and are useful metadata for tooling that lists archives.

pub fn position( &self, resref: &ResRef, resource_type: ResourceTypeCode, ) -> Option<usize>

Returns the table position of the named resource, if it is there.

First entry wins on a duplicate name, matching resolve. The position is what rewrite_erf takes to name an entry, since a name is ambiguous in an archive that carries the same one twice.

pub fn contains(&self, resref: &ResRef, resource_type: ResourceTypeCode) -> bool

Returns whether the archive holds the named resource.

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, &ErfIndexEntry, &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 ErfIndex<R>

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

Formats the value using the given formatter.