feat(parser): add hierarchy scans and selective cell reads

Reuse library builders and cell traversal for full reads, lightweight hierarchy scans, and exact cell byte ranges. Preserve file offsets across readers and reject malformed ranges and FFI pointer/count inputs without aborting.

Document scan schemas and ID assignment. Add regression coverage for Arrow round trips, transforms, subset ordering, empty selections, and invalid input.
This commit is contained in:
Jan Petykiewicz 2026-11-14 14:27:09 -08:00
commit 9643089f2d

View file

@ -6,7 +6,7 @@ pub mod records;
pub mod elements;
pub mod library;
use crate::library::read_library;
use crate::library::{read_library, read_selected_library, scan_library};
use byteorder::{ByteOrder, BigEndian};
use std::any::Any;
@ -20,6 +20,7 @@ use std::ptr;
use std::os::unix::ffi::OsStringExt;
use std::str;
use std::fs;
use std::slice;
use arrow::ffi::{to_ffi, FFI_ArrowArray, FFI_ArrowSchema};
use arrow::array::{Array, StructArray};
@ -133,6 +134,76 @@ pub unsafe extern "C" fn read_path(
}
unsafe fn input_slice<'a, T>(data: *const T, size: usize, name: &str) -> Result<&'a [T], String> {
if size == 0 {
return Ok(&[]);
}
if data.is_null() {
return Err(format!("{name} pointer was null"));
}
if !data.is_aligned() {
return Err(format!("{name} pointer was misaligned"));
}
if size.checked_mul(size_of::<T>()).is_none_or(|bytes| bytes > isize::MAX as usize) {
return Err(format!("{name} length is too large"));
}
Ok(unsafe { slice::from_raw_parts(data, size) })
}
/// Scan cell ranges and hierarchy references. Return 0 on success or -1 on error.
///
/// # Safety
/// Non-null `data` must point to `size` readable bytes. Null is allowed when
/// `size` is zero. Output pointers have the same requirements as `read_path`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn scan_bytes(
data: *const u8,
size: usize,
arr: *mut FFI_ArrowArray,
schema: *mut FFI_ArrowSchema,
) -> i32 {
export_struct_array("scan_bytes", arr, schema, || {
let input = unsafe { input_slice(data, size, "data") }?;
let (_input, struct_arr) = scan_library(input)
.map_err(|err| format!("scan failed: {err:?}"))?;
Ok(struct_arr)
})
}
/// Read the cells in half-open byte ranges. Return 0 on success or -1 on error.
///
/// # Safety
/// `data` has the same requirements as `scan_bytes`. Non-null `ranges` must
/// point to `range_count * 2` readable, aligned u64 values, alternating start
/// and end offsets. Null is allowed for zero ranges. Output pointers have the
/// same requirements as `read_path`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn read_cells_bytes(
data: *const u8,
size: usize,
ranges: *const u64,
range_count: usize,
arr: *mut FFI_ArrowArray,
schema: *mut FFI_ArrowSchema,
) -> i32 {
export_struct_array("read_cells_bytes", arr, schema, || {
let input = unsafe { input_slice(data, size, "data") }?;
let range_size = range_count.checked_mul(2)
.ok_or_else(|| "range count is too large".to_string())?;
let flat_ranges = unsafe { input_slice(ranges, range_size, "ranges") }?;
let cell_ranges: Vec<(u64, u64)> = flat_ranges
.chunks_exact(2)
.map(|chunk| (chunk[0], chunk[1]))
.collect();
let (_input, struct_arr) = read_selected_library(input, &cell_ranges)
.map_err(|err| format!("selected-cell read failed: {err:?}"))?;
Ok(struct_arr)
})
}
macro_rules! impl_i16be {
( $tt:ty, $arr:ident, $size:ident ) => {
{