Struct BbfBuilder 

pub struct BbfBuilder { /* private fields */ }

a BBF file builder

provides methods for making a bound book format (BBF) file with assets, pages, sections, and metadata. this builder handles deduplication of assets, string pooling, alignment, and integrity hashing.

Implementations

impl BbfBuilder

pub fn new<P: AsRef<Path>>( output_path: P, alignment: u8, ream_size: u8, flags: u32, ) -> Result<Self>

makes a new BBF builder with custom alignment and ream size

initializes a new BBF file at the specified path and writes the header. validates that alignment and ream size exponents are within acceptable bounds. prompts user for confirmation if alignment exponent exceeds 16 to prevent excessive fragmentation.

Arguments

• output_path - path where the BBF file will be made
• alignment - alignment exp for asset data (actual alignment = 1 << alignment bytes)
• ream_size - ream size exp for small asset threshold (actual size = 1 << ream_size bytes)
• flags - header flags for config opts

Returns

a new BbfBuilder instance ready to accept assets, pages, sections, and metadata

Errors

returns an error if:

• user declines the confirmation prompt for alignment > 16
• alignment exponent exceeds 16 (64kb) without user confirmation
• ream size exponent exceeds 16 (64kb)
• file creation fails
• writing the initial header fails

pub fn with_defaults<P: AsRef<Path>>(output_path: P) -> Result<Self>

creates a new BBF builder with default settings

initializes a builder with standard alignment (12, or 4kb) and ream size (16, or 64kb), and enables variable ream size flag for optimizing small assets

Arguments

• output_path - path where the BBF file will be created

Returns

a new BbfBuilder instance configured with default values

Errors

returns an error if:

• file creation fails
• writing the initial header fails

pub fn calculate_hash_128(data: &[u8]) -> u128

calculates the 128-bit xxh3 hash of the given data

computes a 128-bit hash using the xxh3 algo, used for asset deduplication and integrity verification.

Arguments

• data - the byte slice to hash

Returns

the 128-bit hash value as a u128

pub fn calculate_hash_64(data: &[u8]) -> u64

calculates the 64-bit xxh3 hash of the given data

computes a 64-bit hash using the xxh3 algorithm, used for footer integrity verification.

Arguments

• data - the byte slice to hash

Returns

the 64-bit hash value as a u64

pub fn add_page<P: AsRef<Path>>( &mut self, image_path: P, page_flags: u32, asset_flags: u32, ) -> Result<()>

adds a page (image) to the book

reads the image file, calculates its hash, and either reuses an existing asset (deduplication) or adds a new asset entry. applies appropriate alignment based on file size and configuration. creates a page entry that references the asset.

Arguments

• image_path - path to the image file to add
• page_flags - flags for page-specific configuration
• asset_flags - flags for asset-specific configuration

Returns

unit type on success, indicating the page was added

Errors

returns an error if:

• reading the image file fails
• arithmetic operations overflow (protected by macroni_n_cheese::mathinator2000)
• writing image data to the buffer fails
• aligning padding fails

pub fn add_section( &mut self, title: &str, start_index: u64, parent: Option<&str>, )

adds a section (chapter/part) to the book

creates a section entry with a title, starting page index, and optional parent section. sections organize pages into hierarchical structures like chapters and sub-chapters.

Arguments

• title - the section title (stored in string pool)
• start_index - the first page index in this section
• parent - optional parent section title for hierarchical organization

Returns

unit type on success (sections are stored internally)

pub fn add_metadata(&mut self, key: &str, val: &str, parent: Option<&str>)

adds a metadata key-val pair to the book

stores arbitrary metadata like author, title, publisher, or isbn. metadata can optionally be associated with a parent section.

Arguments

• key - the metadata key (stored in string pool)
• val - the metadata val (stored in string pool)
• parent - optional parent section for section-specific metadata

Returns

unit type on success (metadata is stored internally)

pub fn finalize(self) -> Result<()>

finalizes the book file and writes all indices

writes all asset, page, section, and metadata tables to the file, followed by the string pool. calculates an integrity hash over all index data, writes the footer with all offsets and counts, then seeks back to the beginning to update the header with final values. flushes and syncs all data to disk.

Returns

unit type on success, indicating the BBF file is complete and ready for use

Errors

returns an error if:

• writing any table data fails
• arithmetic operations overflow (protected by macroni_n_cheese::mathinator2000)
• writing the footer fails
• flushing the buffer fails
• syncing to disk fails
• extracting the inner file from bufwriter fails
• seeking to the start of the file fails
• writing the updated header fails

pub const fn asset_count(&self) -> usize

returns the current number of assets

Returns

count of unique assets added (after deduplication)

pub const fn page_count(&self) -> usize

returns the current number of pages

Returns

count of pages added to the book

pub const fn section_count(&self) -> usize

returns the current number of sections

Returns

count of sections added to the book

pub const fn metadata_count(&self) -> usize

returns the current number of metadata entries

Returns

count of metadata key-value pairs added