Struct Bindle 

pub struct Bindle { /* private fields */ }

A binary archive for collecting files.

Uses memory-mapped I/O for fast reads, supports optional zstd compression, and handles updates via shadowing. Files can be added incrementally without rewriting the entire archive.

Example

use bindle_file::{Bindle, Compress};

let mut archive = Bindle::open("data.bndl")?;
archive.add("file.txt", b"data", Compress::None)?;
archive.save()?;

Implementations

impl Bindle

pub fn create<P: AsRef<Path>>(path: P) -> Result<Self>

Creates a new archive, overwriting any existing file at the path.

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self>

Opens an existing archive or creates a new one if it doesn’t exist.

pub fn load<P: AsRef<Path>>(path: P) -> Result<Self>

Opens an existing archive. Returns an error if the file doesn’t exist.

pub fn new(path: PathBuf, opts: OpenOptions) -> Result<Self>

Create a new Bindle from a path and file, the path must match the file

pub fn add(&mut self, name: &str, data: &[u8], compress: Compress) -> Result<()>

Adds data to the archive with the given name.

If an entry with the same name exists, it will be shadowed. Call save() to commit changes.

pub fn add_file( &mut self, name: &str, path: impl AsRef<Path>, compress: Compress, ) -> Result<()>

Adds a file from the filesystem to the archive.

Reads the file at path and stores it with the given name. Call save() to commit changes.

pub fn save(&mut self) -> Result<()>

Commits all pending changes by writing the index and footer to disk.

Must be called after add/remove operations to make changes persistent.

pub fn vacuum(&mut self) -> Result<()>

Reclaims space by removing shadowed data.

Rebuilds the archive with only live entries, removing old versions of updated files.

pub fn read<'a>(&'a self, name: &str) -> Option<Cow<'a, [u8]>>

Reads an entry from the archive, decompressing if needed.

Returns None if the entry doesn’t exist or if CRC32 verification fails.

pub fn read_to<W: Write>(&self, name: &str, w: W) -> Result<u64>

Reads an entry and writes it to the given writer.

Returns the number of bytes written. Verifies CRC32 after reading.

pub fn reader<'a>(&'a self, name: &str) -> Result<Reader<'a>>

Returns a streaming reader for an entry.

Automatically decompresses if the entry is compressed. Call Reader::verify_crc32() after reading to verify integrity.

pub fn len(&self) -> usize

Returns the number of entries in the archive.

pub fn is_empty(&self) -> bool

Returns true if the archive contains no entries.

pub fn index(&self) -> &BTreeMap<String, Entry>

Returns a reference to the archive index.

The index maps entry names to their metadata.

pub fn clear(&mut self)

Removes all entries from the index.

Call save() to commit. Data remains in the file until vacuum() is called.

pub fn exists(&self, name: &str) -> bool

Returns true if an entry with the given name exists.

pub fn remove(&mut self, name: &str) -> bool

Removes an entry from the index.

Returns true if the entry existed. Data remains in the file until vacuum() is called.

pub fn pack<P: AsRef<Path>>( &mut self, src_dir: P, compress: Compress, ) -> Result<()>

Recursively adds all files from a directory to the archive.

File paths are stored relative to the source directory. Call save() to commit.

pub fn unpack<P: AsRef<Path>>(&self, dest: P) -> Result<()>

Extracts all entries to a destination directory.

Creates subdirectories as needed to match the stored paths.

pub fn writer<'a>( &'a mut self, name: &str, compress: Compress, ) -> Result<Writer<'a>>

Creates a streaming writer for adding an entry.

The writer must be closed and then save() must be called to commit the entry.

Trait Implementations

impl Drop for Bindle

fn drop(&mut self)

Executes the destructor for this type.