# 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](arrow-schema.md). ## Rust Add `pheon` as a dependency. The library readers accept GDSII byte slices: ```rust 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 renderers work after the source documents and byte buffers are dropped. `json_report` returns a JSON value, and `write_json_report` writes object evidence incrementally to a writer. `Document::hierarchy` inspects a single revision. A comparison captures reference counts and analyzes the union graph and ancestors when a hierarchy is requested. `TextComparison::between` captures the data needed for text and hierarchy reports. Layered objects in added and removed cells contribute to the cell's object count. Use `RevisionPair::parse(&old_bytes, &new_bytes)` for an unscoped comparison that can reuse matching cells. Its `compare` and `compare_text` methods return the corresponding owned comparison. 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](https://mpxd.net/code/jan/pheon/src/branch/master/pheon/_ffi.h) 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](diff-reports.md).