Struct TemplateRecordBuffer 

pub struct TemplateRecordBuffer { /* private fields */ }

Template-coordinate record buffer with inline headers.

Uses inline headers to store full sort keys in the data buffer, allowing minimal refs (16 bytes) while maintaining fast comparison.

Memory layout:

data: [Header0][Record0][Header1][Record1]...
refs: [Ref0][Ref1]...

During sorting, we use a custom comparator that:

1. Compares primary keys from refs (fast, O(1))
2. On ties, fetches full keys from inline headers

Implementations

impl TemplateRecordBuffer

pub fn with_capacity(estimated_records: usize, estimated_bytes: usize) -> Self

Create a new buffer with estimated capacity.

pub fn push(&mut self, record: &[u8], key: TemplateKey)

Push a record with a pre-computed template key.

Panics

Panics if the record length exceeds u32::MAX.

pub fn sort(&mut self)

Sort the index by cached key using stable LSD radix sort.

Uses multi-field radix sort which is stable (preserves relative order of records with equal keys). This ensures deterministic output that matches samtools when records have identical sort keys.

pub fn par_sort(&mut self)

Sort using parallel radix sort with stable k-way merge.

Each chunk is sorted with stable radix sort, then merged with a heap that uses chunk_idx as tie-breaker to preserve input order.

pub fn get_record(&self, r: &TemplateRecordRef) -> &[u8]

Get record bytes by reference.

pub fn iter_sorted(&self) -> impl Iterator<Item = &[u8]>

Iterate over sorted records.

pub fn refs(&self) -> &[TemplateRecordRef]

Get the sorted record references.

pub fn memory_usage(&self) -> usize

Memory usage in bytes (actual data stored, not capacity).

pub fn len(&self) -> usize

Number of records.

pub fn is_empty(&self) -> bool

Check if buffer is empty.

pub fn get_key(&self, r: &TemplateRecordRef) -> TemplateKey

Get the key for a record reference (returns cached key from ref).

pub fn iter_sorted_keyed(&self) -> impl Iterator<Item = (TemplateKey, &[u8])>

Iterate over sorted (key, record) pairs. Used for writing keyed temp chunks that preserve sort keys.

pub fn clear(&mut self)

Clear the buffer for reuse.

pub fn data(&self) -> &[u8]

Get underlying data buffer (for direct access to raw bytes).