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

@ -31,3 +31,25 @@ after a successful parser call. Errors belong to the calling thread. Copy the
message before making another parser call on that thread, and before the thread
exits; calls on other threads do not invalidate it. Parser panics that unwind
are converted into errors.
For partial reads, call `scan_bytes` with a borrowed GDSII byte buffer to obtain
cell ranges and references without decoding geometry. Pass the desired ranges
to `read_cells_bytes` to load their full contents. Both calls use the same Arrow
outputs and status/error handling as `read_path`:
```c
int scan_bytes(const uint8_t *data, size_t size,
struct ArrowArray *array, struct ArrowSchema *schema);
int read_cells_bytes(const uint8_t *data, size_t size,
const uint64_t *ranges, size_t range_count,
struct ArrowArray *array, struct ArrowSchema *schema);
```
`ranges` contains alternating inclusive start and exclusive end offsets, with
two native-endian `uint64_t` values per cell. Each range must cover one complete
cell. A null `ranges` pointer is accepted when `range_count` is zero. Likewise,
null `data` is accepted for zero bytes and produces an ordinary parse error for
the empty input. Nonempty buffers must be readable for the duration of the call;
range values must be aligned. Exported Arrow data owns its storage independently
of the input. See [Arrow Schema Documentation](ARROW_SCHEMA.md) for the scan
schema, offset definitions, and ID assignment.