pheon/docs/native-api.md
Jan Petykiewicz 31afef0529 Reject invalid record sizes and return malformed-input errors
Validate payload sizes before record/header writes and make header packing
return io::Result when the total size overflows the format limit.

Return located parse errors for invalid UTF-8 and timestamp year overflow.
Validate cell timestamps consistently in full reads, selected reads, and
hierarchy scans while retaining scan behavior for skipped text geometry.

Add regression coverage for preserved writer outputs, padded metadata sizes,
malformed strings, timestamp boundaries, bounded errors, and Python bindings.
Document the fallible header packing API.

Validation: all 97 Rust tests pass in debug and release; all 16 Python tests
pass against the rebuilt native library.
2026-11-16 21:28:54 -08:00

4.1 KiB

Rust and C integration

Use the Rust library or C API to read GDSII into Arrow without Python. For the returned data layout, see the Arrow reference.

Rust

Add pheon as a dependency. The library readers accept GDSII byte slices:

use pheon::library::read_library;

let bytes = std::fs::read("chip.gds").expect("read layout");
let (_remainder, layout) = read_library(&bytes).expect("parse layout");
println!("{layout:?}");

read_library reads geometry; scan_library returns metadata, references, and cell ranges. Pass (start, end) ranges from a scan to read_selected_library to load only those cells. Each range must span one complete cell. Readers return (remainder, StructArray) on success. The selected reader returns the original input as its remainder, since selection is random access.

Layout-review APIs live in pheon::review, with layer-name helpers in pheon::review::names and scope/display selectors in pheon::review::selection.

Comparison::between(&old, &new) captures an owned result with revision metadata, changes, and structured diagnostics. Use outcome() for completeness, equality, and exit status. Its text, json_report, and hierarchy renderers work after the source documents and byte buffers are dropped. Standalone hierarchy inspection uses Document::hierarchy. Reference counts are captured with the result; union-graph and ancestor analysis run only when a hierarchy is requested.

The record, records, and basic modules also provide low-level GDSII record writing. There is no high-level writer for the Arrow layout. REAL8 writing is exact for representable in-range f64 values: magnitudes below 2^-260 underflow to zero; magnitudes at least 2^252 and nonfinite values are rejected.

Record writes check payload sizes before emitting bytes. Header packing returns an io::Result, including an error when the total size exceeds the format limit. Arrow readers return parse errors for invalid UTF-8 strings and timestamp years that exceed the Int16 range after conversion from the 1900 epoch.

C API

Build the shared library with cargo build --release --locked. The header defines the functions and Arrow C Data structures. The library is libpheon.so, libpheon.dylib, or pheon.dll on Linux, macOS, or Windows respectively.

Function Input Result
read_path NUL-terminated path Full layout.
read_bytes Byte pointer and size Full layout.
scan_bytes Byte pointer and size Metadata, references, and cell ranges.
read_cells_bytes Bytes and cell ranges Full layout for selected cells.

read_path accepts UTF-8 paths on Windows and filesystem bytes on Unix. It reads uncompressed GDSII; Python's read_path adds gzip handling.

For read_cells_bytes, ranges points to alternating uint64 start/end offsets and range_count is the number of cells, not the number of offsets. Ranges are half-open, from BGNSTR through the end of ENDSTR. Range values must be aligned, native-endian uint64 values. Input buffers must remain readable for the call. Null buffer pointers are allowed only when their corresponding length is zero.

Status and ownership

Each reader returns 0 on success and -1 on failure. Call last_error_message() on the same thread after a failure. It returns a borrowed NUL-terminated message; copy it before the next parser call or thread exit. It returns null after a successful parser call.

Supply valid, writable, initialized ArrowArray and ArrowSchema structures without live allocations to overwrite. A failed call leaves them unchanged. Successful outputs own their storage independently of the input buffer. Transfer ownership to an Arrow importer, or call each non-null release callback exactly once. Do not release structures again after an importer takes ownership.

pheon_abi_version() and pheon_arrow_schema_version() both currently return 1. Check both before using the API. The C calling/ownership contract and Arrow layout have separate versions; neither is the package version or the JSON report schema.