Struct BlockPostingList 

pub struct BlockPostingList { /* private fields */ }

Implementations

impl BlockPostingList

pub fn from_posting_list(list: &PostingList) -> Result<Self>

Build from a posting list.

Block format (8-byte header + packed arrays):

[count: u16][first_doc: u32][doc_id_bits: u8][tf_bits: u8]
[packed doc_id deltas: (count-1) × bytes_per_value(doc_id_bits)]
[packed tfs: count × bytes_per_value(tf_bits)]

pub fn from_posting_list_with_codec( list: &PostingList, codec: PostingCodec, ) -> Result<Self>

Build a list using an explicit per-block codec.

pub fn from_posting_list_with_positions(list: &PostingList) -> Result<Self>

Like Self::from_posting_list, for a term whose positions are stored as a v2 stream: every block records how many positions precede it (the cumulative term frequency), so a reader can address the stream from the doc postings alone.

pub fn from_posting_list_with( list: &PostingList, with_positions: bool, length_of: Option<&dyn Fn(DocId) -> u32>, ) -> Result<Self>

Build with position cursors on demand and, when length_of is given, the minimum scoring-unit length per block (and over the list) so MaxScore bounds use real length normalisation. Without lengths the minimum is 1, which any real unit satisfies.

pub fn from_posting_list_with_options( list: &PostingList, with_positions: bool, length_of: Option<&dyn Fn(DocId) -> u32>, codec: PostingCodec, ) -> Result<Self>

Build with the complete physical layout policy used by index writers.

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

Serialize the block posting list (footer-based: stream first).

Format:

[stream: block data]
[L0 entries: l0_count × 16 bytes (first_doc, last_doc, offset, max_weight)]
[L1 entries: l1_count × 4 bytes (last_doc)]
[L1 bounds: l1_count × 4 bytes (packed max_tf, min_len), FLAG_L1_BOUNDS]
[position cursors: l0_count × 8 bytes, only with positions]
[footer: stream_len(8) + l0_count(4) + l1_count(4) + doc_count(4) + max_tf(4)
         + total_positions(8) + flags(4) + min_len(4) + magic(4) = 44 bytes]

pub fn deserialize(raw: &[u8]) -> Result<Self>

Deserialize from a byte slice (either footer format).

pub fn deserialize_zero_copy(raw: OwnedBytes) -> Result<Self>

Zero-copy deserialization from OwnedBytes. Stream, L0 and cursors are sliced from the source without copying. L1 is extracted into a Vec<u32> for SIMD-friendly access (tiny: ≤ N/8 entries).

pub fn min_len(&self) -> Option<u32>

Minimum scoring-unit length over the list, when the list stores length bounds (None for legacy lists).

pub fn block_bounds(&self, block_idx: usize) -> Option<(u32, Option<u32>)>

(max_tf, min_len) of a block; min_len is None for legacy lists.

pub fn group_bounds(&self, block_idx: usize) -> Option<(u32, u32)>

(max_tf, min_len) over the L1 group (L1_INTERVAL blocks) that contains block_idx; None for legacy lists without group bounds.

pub fn group_last_doc(&self, block_idx: usize) -> Option<DocId>

Last doc of the L1 group containing block_idx.

pub fn is_group_start(&self, block_idx: usize) -> bool

Whether block_idx opens an L1 group.

pub fn next_group_block(&self, block_idx: usize) -> usize

Index of the first block after the L1 group containing block_idx (clamped to the block count).

pub fn has_cursors_bytes(raw: &[u8]) -> bool

Whether serialized bytes carry position cursors (cheap footer check).

pub fn has_position_cursors(&self) -> bool

Whether this list carries a position cursor per block.

pub fn total_positions(&self) -> u64

Number of values in the term’s position stream (0 without cursors).

pub fn pos_cursor(&self, block_idx: usize) -> Option<u64>

Values in the term’s position stream before block block_idx.

pub fn doc_count(&self) -> u32

pub fn max_tf(&self) -> u32

Get maximum term frequency (for MaxScore upper bound computation)

pub fn num_blocks(&self) -> usize

Get number of blocks

pub fn block_max_tf(&self, block_idx: usize) -> Option<u32>

Get block’s max term frequency for block-max pruning

pub fn concatenate_blocks(sources: &[(BlockPostingList, u32)]) -> Result<Self>

Concatenate blocks from multiple posting lists with doc_id remapping. This is O(num_blocks) instead of O(num_postings).

pub fn concatenate_streaming<W: Write>( sources: &[(&[u8], u32)], writer: &mut W, ) -> Result<(u32, usize)>

Streaming merge: write blocks directly to output writer (bounded memory).

Zero-materializing: reads L0 entries directly from source bytes (mmap or &u8) without parsing into Vecs. Block sizes come from the L0 offsets, so blocks of any codec are copied verbatim.

Output L0 + L1 are buffered (bounded O(total_blocks × 16 + total_blocks/8 × 4)). Block data flows source → output writer without intermediate buffering.

Returns (doc_count, bytes_written).

Returns Error::Corruption if any source is shorter than its footer: metas are paired with sources positionally, so a short/corrupt source must fail loudly instead of misassigning every subsequent source.

pub fn decode_block_into( &self, block_idx: usize, doc_ids: &mut Vec<u32>, tfs: &mut Vec<u32>, ) -> bool

Decode a specific block into caller-provided buffers.

Returns true if the block was decoded, false if block_idx is out of range. Reuses doc_ids and tfs buffers (cleared before filling).

Uses SIMD-accelerated unpack for 8/16/32-bit packed arrays.

pub fn decode_block_doc_ids_only( &self, block_idx: usize, doc_ids: &mut Vec<u32>, ) -> Option<(usize, usize, usize)>

Decode only doc IDs from a block (no TF decoding).

Returns (block_data_offset, tf_start_within_block, count) for deferred TF decode, or None if block_idx is out of range.

pub fn decode_block_tfs_deferred( &self, block_offset: usize, tf_start: usize, count: usize, tfs: &mut Vec<u32>, )

Decode TFs from a previously loaded block (deferred decode).

block_offset and tf_start are returned by decode_block_doc_ids_only.

pub fn block_codec(&self, block_idx: usize) -> Option<PostingCodec>

Codec of block block_idx (diagnostics).

pub fn block_first_doc(&self, block_idx: usize) -> Option<DocId>

First doc_id of a block (from L0 skip entry). Returns None if out of range.

pub fn block_last_doc(&self, block_idx: usize) -> Option<DocId>

Last doc_id of a block (from L0 skip entry). Returns None if out of range.

pub fn seek_block(&self, target: DocId, from_block: usize) -> Option<usize>

Find the first block whose last_doc >= target, starting from from_block.

Uses SIMD-accelerated linear scan:

1. find_first_ge_u32 on the contiguous L1 last_doc array
2. Extract ≤L1_INTERVAL L0 last_doc values into a stack buffer → find_first_ge_u32

Returns None if no block contains target.

pub fn iterator(&self) -> BlockPostingIterator<'_>

Create an iterator with skip support

pub fn into_iterator(self) -> BlockPostingIterator<'static>

Create an owned iterator that doesn’t borrow self

Trait Implementations

impl Clone for BlockPostingList

fn clone(&self) -> BlockPostingList

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BlockPostingList

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

Formats the value using the given formatter.