Struct StreamIndex2D 

pub struct StreamIndex2D<R> { /* private fields */ }

Available on crate feature stream only.

Streaming reader for a 2D f64 packed spatial index.

Open one over any RangeReader — a local FileReader, an in-memory SliceReader, or a custom remote source — and query it by fetching only the byte ranges a traversal needs, instead of loading the whole serialized index. open validates the header and level bounds and prefetches the upper levels of the tree.

Queries are fallible (a backing read can fail; a corrupt index is reported as StreamError::Format) and otherwise mirror Index2D range search. Results are item insertion indices, in traversal order.

Example

use packed_spatial_index::{Box2D, Index2DBuilder, SliceReader, StreamIndex2D};

// Serialize an index once...
let mut builder = Index2DBuilder::new(2);
builder.add(Box2D::new(0.0, 0.0, 1.0, 1.0));
builder.add(Box2D::new(5.0, 5.0, 6.0, 6.0));
let bytes = builder.finish().unwrap().to_bytes();

// ...then query it through a RangeReader without rebuilding it in memory.
let index = StreamIndex2D::open(SliceReader::new(bytes))?;
assert_eq!(index.search(Box2D::new(0.0, 0.0, 2.0, 2.0))?, vec![0]);

Implementations

impl<R: AsyncRangeReader> StreamIndex2D<R>

Streaming reader for a 2D f64 index over async I/O. Mirrors StreamIndex2D; use it when reads return futures (e.g. browser / edge worker). Behind the async feature.

pub async fn open_async(reader: R) -> Result<Self, StreamError>

Available on crate feature async only.

Open and validate a 2D f64 index from an async reader.

pub async fn open_with_limits_async( reader: R, limits: StreamLimits, ) -> Result<Self, StreamError>

Available on crate feature async only.

Open from an async reader with per-query StreamLimits. See StreamIndex2D::open_with_limits.

pub async fn search_async( &self, query: Box2D, ) -> Result<Vec<usize>, StreamError>

Available on crate feature async only.

Stream the indices of every item whose box intersects query.

pub async fn search_payloads_async( &self, query: Box2D, ) -> Result<Vec<(usize, Vec<u8>)>, StreamError>

Available on crate feature async only.

Stream (item index, payload blob) for every item intersecting query.

pub async fn visit_region_async<Q, F>( &self, query: &Q, visitor: F, ) -> Result<(), StreamError>

where Q: Overlaps2D, F: FnMut(usize),

Available on crate feature async only.

Stream the indices of every item whose box overlaps the region query — any Overlaps2D shape, not just a box.

pub async fn search_region_async<Q: Overlaps2D>( &self, query: &Q, ) -> Result<Vec<usize>, StreamError>

Available on crate feature async only.

Collect the indices of every item whose box overlaps the region query.

pub async fn visit_payloads_region_async<Q, F>( &self, query: &Q, visitor: F, ) -> Result<(), StreamError>

where Q: Overlaps2D, F: FnMut(usize, &[u8]),

Available on crate feature async only.

Visit (item index, payload blob) for every item whose box overlaps the region query.

pub async fn search_payloads_region_async<Q: Overlaps2D>( &self, query: &Q, ) -> Result<Vec<(usize, Vec<u8>)>, StreamError>

Available on crate feature async only.

Collect (item index, payload blob) for every item whose box overlaps the region query.

pub async fn visit_payload_prefixes_async<F: FnMut(PayloadPrefix<'_>)>( &self, query: Box2D, prefix_len: usize, visitor: F, ) -> Result<(), StreamError>

Available on crate feature async only.

Async counterpart of StreamIndex2D::visit_payload_prefixes.

pub async fn visit_payload_prefixes_region_async<Q, F>( &self, query: &Q, prefix_len: usize, visitor: F, ) -> Result<(), StreamError>

where Q: Overlaps2D, F: FnMut(PayloadPrefix<'_>),

Available on crate feature async only.

Async counterpart of StreamIndex2D::visit_payload_prefixes_region.

pub async fn visit_payloads_at_ranks_async<F: FnMut(usize, &[u8])>( &self, leaf_ranks: &[usize], visitor: F, ) -> Result<(), StreamError>

Available on crate feature async only.

Async counterpart of StreamIndex2D::visit_payloads_at_ranks.

pub fn has_payload_async(&self) -> bool

Available on crate feature async only.

Whether this index was written with a payload section.

impl<R> StreamIndex2D<R>

pub fn into_directory(self) -> (StreamDirectory, R)

Split off the reader, keeping the reusable StreamDirectory. No I/O.

pub fn from_directory( dir: &StreamDirectory, reader: R, ) -> Result<Self, StreamError>

Rebuild a 2D f64 index from a cached directory and a fresh reader. No I/O: the directory reads were paid when it was first opened.

pub fn from_directory_with_limits( dir: &StreamDirectory, reader: R, limits: StreamLimits, ) -> Result<Self, StreamError>

from_directory with per-query StreamLimits.

pub fn num_items(&self) -> usize

Number of indexed items.

pub fn is_empty(&self) -> bool

Whether the index has no items.

pub fn node_size(&self) -> usize

Packed node size of the index.

pub fn has_payload(&self) -> bool

Whether this index was written with a payload section.

impl<R: RangeReader> StreamIndex2D<R>

pub fn open(reader: R) -> Result<Self, StreamError>

Open and validate a 2D f64 index from reader.

Reads and validates the header and level bounds and prefetches the upper levels of the tree. Returns StreamError::Format for a corrupt or wrong-variant index and StreamError::Io for a read failure.

pub fn open_with_limits( reader: R, limits: StreamLimits, ) -> Result<Self, StreamError>

Open with per-query cost StreamLimits. Every query then aborts with StreamError::LimitExceeded if it would exceed a limit — use this to bound a broad query’s reads / bytes / results to your environment (e.g. a worker’s subrequest and memory budgets).

pub fn extent(&self) -> Option<Box2D>

Total extent of all indexed items, or None for an empty index.

Read from the cached root box, so this costs no I/O.

pub fn visit<F: FnMut(usize)>( &self, query: Box2D, visitor: F, ) -> Result<(), StreamError>

Stream the indices of every item whose box intersects query, passing each to visitor.

Fallible: a read from the backing RangeReader can fail mid-query, and a corrupt index is reported as StreamError::Format. Items are yielded in tree-traversal order, which is not part of the API.

pub fn search(&self, query: Box2D) -> Result<Vec<usize>, StreamError>

Stream the indices of every item whose box intersects query.

pub fn search_into( &self, query: Box2D, out: &mut Vec<usize>, ) -> Result<(), StreamError>

Like search, but appends into a reused buffer (cleared first) to avoid reallocating across queries.

pub fn visit_payloads<F: FnMut(usize, &[u8])>( &self, query: Box2D, visitor: F, ) -> Result<(), StreamError>

Visit (item index, payload blob) for every item intersecting query.

The payload section is stored in leaf order, so a spatial query fetches its blobs (and their offset table) in coalesced reads — a handful of round trips even over a remote source, instead of one per item. The blob slice is valid only for the duration of each call. Returns StreamError::NoPayload if the index has no payload section.

pub fn search_payloads( &self, query: Box2D, ) -> Result<Vec<(usize, Vec<u8>)>, StreamError>

Collect (item index, payload blob) for every item intersecting query. The owning counterpart of visit_payloads.

pub fn visit_region<Q, F>( &self, query: &Q, visitor: F, ) -> Result<(), StreamError>

where Q: Overlaps2D, F: FnMut(usize),

Stream the indices of every item whose box overlaps the region query — any Overlaps2D shape (a polygon, triangle, …), not just a box.

Subtrees whose node box falls outside query are pruned during the streamed descent, so a region query fetches only the leaves it overlaps — less data than its bounding box. (Pruning can fragment the coalesced runs, so the range-request count is shape-dependent; the bytes always shrink.)

pub fn search_region<Q: Overlaps2D>( &self, query: &Q, ) -> Result<Vec<usize>, StreamError>

Collect the indices of every item whose box overlaps the region query.

pub fn visit_payloads_region<Q, F>( &self, query: &Q, visitor: F, ) -> Result<(), StreamError>

where Q: Overlaps2D, F: FnMut(usize, &[u8]),

Visit (item index, payload blob) for every item whose box overlaps the region query. Like visit_payloads but for a custom Overlaps2D shape; node-box pruning fetches only the leaves the region touches.

pub fn search_payloads_region<Q: Overlaps2D>( &self, query: &Q, ) -> Result<Vec<(usize, Vec<u8>)>, StreamError>

Collect (item index, payload blob) for every item whose box overlaps the region query. The owning counterpart of visit_payloads_region.

pub fn visit_payload_prefixes<F: FnMut(PayloadPrefix<'_>)>( &self, query: Box2D, prefix_len: usize, visitor: F, ) -> Result<(), StreamError>

Visit a PayloadPrefix for every item intersecting query: id, leaf rank, full payload length, and the first prefix_len payload bytes.

Payload bodies past the prefix are not read — lengths come from the offset table (or the fixed stride) — so identity prefixes and size summaries cost a fraction of visit_payloads. Capture leaf_rank values here and feed a page of them to visit_payloads_at_ranks to fetch full payloads later. Returns StreamError::NoPayload if the index has no payload section.

Example

use packed_spatial_index::{Box2D, Index2DBuilder, SliceReader, StreamIndex2D};

let mut builder = Index2DBuilder::new(2);
builder.add(Box2D::new(0.0, 0.0, 1.0, 1.0));
builder.add(Box2D::new(5.0, 5.0, 6.0, 6.0));
let index = builder.finish()?;
let bytes = index.to_bytes_with_payloads(&[
    b"first payload".as_slice(),
    b"second payload".as_slice(),
])?;

let stream = StreamIndex2D::open(SliceReader::new(bytes))?;
let mut headers = Vec::new();
stream.visit_payload_prefixes(Box2D::new(-1.0, -1.0, 7.0, 7.0), 5, |p| {
    headers.push((p.id, p.leaf_rank, p.payload_len, p.prefix.to_vec()));
})?;
assert_eq!(headers.len(), 2);

let page_ranks = [headers[0].1];
let mut page = Vec::new();
stream.visit_payloads_at_ranks(&page_ranks, |rank, blob| {
    page.push((rank, blob.to_vec()));
})?;
assert_eq!(page[0].0, headers[0].1);
assert_eq!(page[0].1.len(), headers[0].2);

pub fn visit_payload_prefixes_region<Q, F>( &self, query: &Q, prefix_len: usize, visitor: F, ) -> Result<(), StreamError>

where Q: Overlaps2D, F: FnMut(PayloadPrefix<'_>),

visit_payload_prefixes for a custom Overlaps2D region; node-box pruning fetches only the leaves the region touches.

pub fn visit_payloads_at_ranks<F: FnMut(usize, &[u8])>( &self, leaf_ranks: &[usize], visitor: F, ) -> Result<(), StreamError>

Visit (leaf rank, payload blob) for an explicit set of leaf ranks — random-access payload reads for ranks captured by a prefix visit. Ranks are sorted and deduplicated internally, read in coalesced ascending runs, and emitted in ascending rank order. A rank at or past the item count fails with StreamError::InvalidRank.