Struct SectionedStorage 

pub struct SectionedStorage { /* private fields */ }

Implementations

impl SectionedStorage

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

Create a new sectioned file

pub fn is_sectioned_file(path: &Path) -> bool

Check if a file is a sectioned file without opening it

This is a lightweight check that only reads the file header to verify the magic number. It doesn’t validate the entire file structure.

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

Open an existing sectioned file

Reads header and section table, validates structure integrity. Returns error if validation fails.

pub fn create_section( &mut self, name: &str, capacity: u64, flags: u32, ) -> Result<()>

Create a new section with IMMEDIATE physical reservation

This method:

1. Validates the name
2. Gets current file length
3. Computes allocation_base = max(next_data_offset, file_len)
4. Allocates from allocation_base
5. Physically extends file to reserve capacity
6. Updates header.next_data_offset

Fails if:

• Name is empty
• Name exceeds 32 UTF-8 bytes
• Section with same name exists
• Addition would overflow
• File extension fails

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

Write data to an existing section

TASK 4 CAPACITY BEHAVIOR: Fails loudly with explicit error on overflow. Never silently loses data.

Fails if:

• Section doesn’t exist
• data.len() > section.capacity (explicit capacity error)

pub fn read_section(&mut self, name: &str) -> Result<Vec<u8>>

Read data from a section

Fails if:

• Section doesn’t exist
• Checksum mismatch

pub fn get_section(&self, name: &str) -> Option<&Section>

Get section metadata without reading data

pub fn list_sections(&self) -> Vec<Section>

List all sections

pub fn section_count(&self) -> usize

Get the number of sections

pub fn path(&self) -> &Path

Get the file path

pub fn header(&self) -> &GeoFileHeader

Get a reference to the header

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

Flush section table to EOF

Phase A behavior:

• Appends a FRESH section table at current EOF
• Updates header.section_table_offset to point to new table
• Old section tables become dead bytes in file
• File size grows with each flush

File layout after flush():

[0..128)                    - header
[128..next_data_offset)      - section payload area
[section_table_offset..EOF)  - current section table

Because create_section() guarantees EOF >= next_data_offset, the section table is always placed after all section payloads.

Compaction (reclaiming dead tables) is deferred to a later phase.

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

Validate file structure integrity

IMPORTANT: If self.dirty == true, returns an error. Unflushed state cannot be validated against disk.

pub fn validate_required_sections(&self, required: &[&str]) -> Result<()>

Validate that required sections exist

pub fn resize_section(&mut self, name: &str, new_capacity: u64) -> Result<()>

Resize a section to a new (larger) capacity

This method:

1. Reads the current section data
2. Creates a new section with the larger capacity at EOF
3. Copies the data to the new location
4. Removes the old section (becomes dead space)
5. Flushes to disk

Fails if:

• Section doesn’t exist
• New capacity is smaller than current data length
• Read/write operations fail

Note: The old section’s space becomes dead space in the file. A future compaction operation could reclaim this space.

Trait Implementations

impl Debug for SectionedStorage

Sectioned file storage container

File layout (Phase A - Append-Only with Dead Tables):

[0..128)                    - header
[various offsets]            - live section payloads (may have gaps)
[header.section_table_offset..) - current live section table
[section_table_offset..file_len) - dead bytes (old tables) may exist

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

Formats the value using the given formatter.