Struct BlockIndex 

pub struct BlockIndex { /* private fields */ }

Complete index for a VBINSEQ file

A BlockIndex contains metadata about a VBINSEQ file and all of its blocks, enabling efficient random access and parallel processing. It consists of an IndexHeader and a collection of BlockRange entries, one for each block in the file.

The index can be created by scanning a VBINSEQ file or loaded from a previously created index file. Once loaded, it provides information about block locations, sizes, and record counts.

Examples

use binseq::vbq::{BlockIndex, MmapReader};
use std::path::Path;

// Create an index from a VBINSEQ file
let vbq_path = Path::new("example.vbq");
let index = BlockIndex::from_vbq(vbq_path).unwrap();

// Save the index for future use
let index_path = Path::new("example.vbq.vqi");
index.save_to_path(index_path).unwrap();

// Use the index with a reader for parallel processing
let reader = MmapReader::new(vbq_path).unwrap();
println!("File contains {} blocks", index.n_blocks());

Implementations

impl BlockIndex

pub fn new(header: IndexHeader) -> Self

Creates a new empty block index with the specified header

Parameters

• header - The index header containing metadata about the indexed file

Returns

A new empty BlockIndex instance

pub fn n_blocks(&self) -> usize

Returns the number of blocks in the indexed file

Returns

The number of blocks in the VBINSEQ file described by this index

Examples

use binseq::vbq::BlockIndex;
use std::path::Path;

let index = BlockIndex::from_path(Path::new("example.vbq.vqi")).unwrap();
println!("The file contains {} blocks", index.n_blocks());

pub fn save_to_path<P: AsRef<Path>>(&self, path: P) -> Result<()>

Writes the collection of BlockRange to a file Saves the index to a file

This writes the index header and all block ranges to a file, which can be loaded later to avoid rescanning the VBINSEQ file. The index is compressed to reduce storage space.

Parameters

• path - The path where the index file should be saved

Returns

• Ok(()) - If the index was successfully saved
• Err(_) - If an error occurred during saving

Examples

use binseq::vbq::BlockIndex;
use std::path::Path;

// Create an index from a VBINSEQ file
let index = BlockIndex::from_vbq(Path::new("example.vbq")).unwrap();

// Save it for future use
index.save_to_path(Path::new("example.vbq.vqi")).unwrap();

pub fn write_bytes<W: Write>(&self, writer: &mut W) -> Result<()>

Write the index to an output buffer

pub fn write_range<W: Write>(&self, writer: &mut W) -> Result<()>

Write the collection of BlockRange to an output handle Writes all block ranges to the provided writer

This method is used internally by save_to_path to write the block ranges to an index file. It can also be used to serialize an index to any destination that implements Write.

Parameters

• writer - The destination to write the block ranges to

Returns

• Ok(()) - If all block ranges were successfully written
• Err(_) - If an error occurred during writing

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

Creates a new index by scanning a VBINSEQ file

This method memory-maps the specified VBINSEQ file and scans it block by block to create an index. The index can then be saved to a file for future use, enabling efficient random access without rescanning the file.

Parameters

• path - Path to the VBINSEQ file to index

Returns

• Ok(Self) - A new BlockIndex containing information about all blocks in the file
• Err(_) - If an error occurred during file opening, validation, or scanning

Examples

use binseq::vbq::BlockIndex;
use std::path::Path;

// Create an index from a VBINSEQ file
let index = BlockIndex::from_vbq(Path::new("example.vbq")).unwrap();

// Save the index for future use
index.save_to_path(Path::new("example.vbq.vqi")).unwrap();

// Get statistics about the file
println!("File contains {} blocks", index.n_blocks());

// Analyze the record distribution
if let Some(last_range) = index.ranges().last() {
    println!("Total records: {}", last_range.cumulative_records);
    println!("Average records per block: {}",
             last_range.cumulative_records as f64 / index.n_blocks() as f64);
}

Notes

This method uses memory mapping for efficiency, which allows the operating system to load only the needed portions of the file into memory as they are accessed.

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

Reads an index from a path

Panics

Panics if the path is not a valid UTF-8 string.

pub fn from_bytes(bytes: &[u8]) -> Result<Self>

pub fn ranges(&self) -> &[BlockRange]

Get a reference to the internal ranges Returns a reference to the collection of block ranges

This provides access to the metadata for all blocks in the indexed file, which can be used for operations like parallel processing or random access.

Returns

A slice containing all BlockRange entries in this index

Examples

use binseq::vbq::BlockIndex;
use std::path::Path;

let index = BlockIndex::from_path(Path::new("example.vbq.vqi")).unwrap();

// Examine the ranges to determine which blocks to process
for (i, range) in index.ranges().iter().enumerate() {
    println!("Block {}: {} records at offset {}",
             i, range.block_records, range.start_offset);
}

pub fn pprint(&self)

pub fn num_records(&self) -> usize

Returns the total number of records in the dataset

Trait Implementations

impl Clone for BlockIndex

fn clone(&self) -> BlockIndex

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BlockIndex

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

Formats the value using the given formatter.