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_into(&self, name: &str, buffer: &mut [u8]) -> Result<usize>

Reads an entry into a provided buffer, avoiding allocation.

Decompresses if needed and verifies CRC32. Returns the number of bytes read. If the buffer is too small, only reads up to buffer.len() bytes.

Example

use bindle_file::Bindle;

let archive = Bindle::open("data.bndl")?;
let mut buffer = vec![0u8; 1024];
let bytes_read = archive.read_into("file.txt", &mut buffer)?;

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.