Download the PHP package skunkwerkx/hypertabular without Composer

HyperTabular

Delimited text — CSV, TSV, any single-byte ASCII separator — and workbooks — XLSX and ODS — read a batch at a time into typed columns, with a HyperCast verdict for every cell. Written once in Rust as a core with no standard library, no allocation and no panic, called directly from C#, Java, Go, Swift, Python, Ruby and PHP, with a shared conformance corpus so every binding agrees byte for byte.

Reading a spreadsheet or a CSV into typed values usually means one of two things: a library that guesses (the separator, the header, whether 1/7/2026 is January or July, whether 12.185 is a thousand or twelve) and throws on the first cell it cannot read, or a string per cell and a parser per cell in the host language. HyperTabular does neither. The dialect and the plan — which source column, through which HyperCast door, in which notation — are declared, and nothing is sniffed. A cell that does not cast is a verdict in its column, Empty, Malformed or OutOfRange with the span of the offending text, and the read goes on. And the work happens in one native call per batch: the binding allocates the column buffers once, the core fills them, and the boundary is crossed once per few thousand rows, not once per cell.

Install

Each brings HyperCast 0.8 with it: the verdict, fault, number-format and declared-option types a batch hands out are HyperCast's own, from its package, not copies.

The shape

• One batch type. read() returns a batch — rows, the line each row came from, a whole column as the core wrote it (a span, a slice, a memoryview, a MemorySegment), a verdict beside each value, one cell as HyperCast's union, and the raw text a cell was cast from — or nothing when the input is done. The same type for delimited text and for a sheet.
• Header first, plan after. A reader or a sheet opens without a plan, reads its header, and is told its plan once it knows where each column is: Header.Ordinal("M49 Code") in C#, header.require("M49 Code") in Rust, the same in every binding — exact and first match, a missing name an error that names it. A plan known by position can still be given up front.
• Rows, when that is the shape you want. A batch read across: foreach (var row in batch) and its equivalent in every binding hand out a row view with the batch's own accessors, and every reader and sheet iterates its rows across batches.
• Streams and async. A workbook opens from a path, bytes or a stream. Where the language has an async idiom — C# (ReadAsync, OpenAsync), Swift (readAsync), Python (asyncio), Rust (the async feature) — a delimited source is read asynchronously and cancellably, and a cancelled read loses nothing.
• Nothing is sniffed. The Dialect states the separator, the quoting, the header and whether blank lines are skipped; SheetOptions states a sheet's header, whether empty rows are skipped and the batch size; the plan states each column's door and, for numbers, its NumFormat (separators, grouping, accounting parens, currency — or HyperCast's structural DETECT, which refuses the ambiguous rather than guess). Dates in text are read under a declared field order.
• HyperCast is the judge. A text cell means exactly what HyperCast's door would say of the same text. A workbook's numeric cell is converted from the stored f64 by HyperCast's typed doors: an exact decimal (the shortest one that names the double, so a stored 0.1 is one tenth), a date or date-time under the workbook's own date system (1900 or 1904), a time of day, a span — each time snapped to the fewest fractional-second digits that store as the same double, so Excel's 9999-12-31 23:59:59 reads on the second.
• A bad value is a verdict; a broken file is an error. A record of the wrong width, input that ends inside a quoted cell, a workbook whose container or parts cannot be read, an encrypted package: each is a structural error, raised only after every intact row before it has been delivered.
• Text is zero-copy. A text cell is a span into the input, or into a workbook's shared strings. Only a cell with "" inside, or a typed workbook cell asked for as text, is written to an arena.
• Streaming where the format allows it. Delimited text is read through a buffer the reader refills, so a file of any size reads in memory bounded by that buffer and the longest row. A workbook is a zip whose directory is at its end, so the package is held in memory; each sheet is inflated through a sliding window as it is read, never whole, so a deflate bomb is only as large as the window.

The core, and what holds it

The crate is two layers. The core (rust/src/kernel) is what the native library libhypertabular is made of and what every binding calls: it reads bytes the caller hands it and writes into buffers the caller hands it. The Rust API over it, behind the default std feature, is one binding among eight. The core's three properties are things a build refuses to get wrong, and rust/check-core.sh checks every one on the code and on the library it becomes, on every pull request:

The design record — why one repository, how the scanner and the workbook reader work, what was studied and borrowed — is in docs/.

Receipts

• The corpus is the contract. corpus/delimited.json (33 cases) and corpus/workbook.json (198 cases) replay through the Rust suite and through every binding's own, byte for byte, fault spans included. The workbook cases read generated files and files written by real applications: Excel for Windows (data, strict OOXML, the 1904 date system, an encrypted and a protected workbook, a macro-enabled one, ZIP64), Excel for the web, LibreOffice and Google Sheets, in both formats. corpus/README.md records each writer and what it does that the others do not.
• Delimited text: every cell located and handed out as text at 1.05 GiB/s, against 978 MiB/s for the csv crate splitting the same records; ten typed columns cast into the caller's buffers at 654 MiB/s; the structural scan alone at 2.18 GiB/s on AVX2. Linux x64, a 26 MB 200 000 × 10 file (docs/delimited.md).

• Workbooks, through every binding. Two real-application files, read whole by each binding's own benchmark harness through one eight-column plan, every verdict looked at and every text cell's bytes, each harness printing the same checksum. Excel's excel-win-300k.xlsx (111 MB of sheet XML in a 16.7 MB package) and LibreOffice's libreoffice-300k.ods (360 MB of content.xml in 13.3 MB); linux-x64, an Intel Core i9-11900H:

  Binding (harness)	xlsx open	xlsx read	ods open	ods read
  Rust (Criterion)	34 ms	601 ms	337 ms	1.20 s
  C# (BenchmarkDotNet)	32 ms	591 ms	334 ms	1.21 s
  Java (JMH)	41 ms	600 ms	346 ms	1.23 s
  Go (go test -bench)	30 ms	590 ms	328 ms	1.20 s
  Swift (package-benchmark)	37 ms	617 ms	336 ms	1.20 s
  Python (pyperf)	39 ms	630 ms	344 ms	1.24 s
  Ruby (benchmark-ips), Magnus	30 ms	1.01 s	330 ms	1.61 s
  Ruby (benchmark-ips), Fiddle	36 ms	1.04 s	343 ms	1.65 s
  PHP (phpbench)	44 ms	776 ms	346 ms	1.34 s

  2026-10-07, every binding on the 0.7.0 core. docs/workbook.md has where the time goes, why Ruby's and PHP's rows decode every value, and how to run each harness.

• AOT on both managed platforms. The C# AOT smoke test publishes under PublishAot with the core linked in from the package's static archive, and runs, on every CI leg. The Java smoke test (java/aot-smoke-test) builds a GraalVM Native Image on the jar's own reachability metadata and reads through every door; it is run by hand, not in CI.

Platform support

.github/workflows/ci.yml builds the core fresh on five real-hardware legs and runs every binding's own suite, corpus replay included, against that leg's library; a second job does the same for the two musl RIDs inside Alpine containers, and Intel macOS is cross-built and tested at the core under Rosetta 2. The pipeline is the shared SkunkWerkx forge, the same one HyperCast and HyperUuid ship from.

• osx-x64 (Intel macOS): built, and tested at the core only. The library is cross-compiled on the Apple silicon runner and the core's own suite runs on it under Rosetta 2; no binding's suite runs on Intel macOS.
• PHP on win-arm64. PHP ships no native Windows ARM64 build, so it runs as an x64 process there and loads the win-x64 library.

Swift and Go link the core into the consumer's executable on every platform, so there is nothing to deploy beside it; C# does for a Native AOT publish. Everything else loads the shared library.

iOS and Mac Catalyst load no libraries at all, so C#, Swift and Go link the core into the app there, from static libraries cross-compiled in the same job as the rest: C# for ios-arm64, iossimulator-arm64, maccatalyst-arm64 and maccatalyst-x64, where a .NET iOS, MAUI or Mac Catalyst app (net11.0-ios, net11.0-maccatalyst) needs nothing but the package reference; Swift for the three arm64 ones, as an XCFramework, from iOS 16 and Mac Catalyst 16; and Go for all four, chosen by build tag, since Go builds every one of them as GOOS=ios. HyperCast's archives link beside them in the same app, and the two share no symbols. CI's test-apple-mobile job builds them on a Mac from that run's archives: C# and Swift run in an iOS simulator and as a Mac Catalyst process, Go's suite runs in the simulator, and each links an iOS device build.

Android, arm64 and x86_64, is reached by the same three bindings, so that a .NET MAUI app has the core on every platform MAUI targets and a Go or Swift Android build links it as on any other platform. C# carries a shared library cross-built with the NDK at API level 21, its segments aligned to the 16 KB pages Android 15 devices may use and Google Play requires: an app on CoreCLR, .NET 11's Android runtime, loads it out of the APK like any Linux library, and a Native AOT publish links it in from a static archive like every other RID. Go links its own pair of archives under GOOS=android with the NDK's clang, and Swift links them from its artifact bundle with the Swift SDK for Android (Swift 6.3+, API 28+). HyperCast reaches Android the same three ways, and its libraries sit beside these in the same app. CI's test-android job builds the C# app both ways for both RIDs from a package packed in that run, cross-builds the Go and Swift suites, runs everything x86_64 in an emulator whose image uses 16 KB pages, and links or inspects the arm64 builds. See swift/README.md.

Runtime floors follow upstream support and match HyperCast's: .NET 11, JDK 25, Go 1.26, Swift 6.2, Python 3.11, Ruby 3.3 and PHP 8.2. The crate's floor is Rust 1.88, HyperCast's own.

WebAssembly

The binding is compiled to WebAssembly and the core is linked into that build by the ecosystem's own toolchain — the same archive as everywhere else, built for wasm32. The core imports nothing (no clock, no entropy, no allocator: the caller's buffers are all the memory it touches), so a page loads one module and needs no shim beyond what the language already brings. Every browser row below runs in headless Chrome in CI: on every pull request, except Ruby's, whose ruby.wasm interpreter build per Ruby minor runs in the weekly and release builds instead. Java goes the other way: the core runs as wasm inside the JVM.

Arguments are kept to twelve integers or fewer on every export, because Mono's interpreter — which runs .NET in the browser — passes no more to a native function; the work buffers travel in one hypertabular_buffers struct instead.

Provenance

Every native library carries a GitHub build-provenance attestation from the forge's build, checked again before it is committed for Go, Swift and PHP (stage-native-binaries.yml) and before it is packed into a gem (release.yml). Packages signed inside this repository's own release.yml — the gem and the published NuGet package — verify with gh attestation verify <file> --repo SkunkWerkx/HyperTabular; everything signed by the forge's reusable workflows — the crate, the jar, the wheels, the pre-push NuGet package and every native library — needs --signer-repo SkunkWerkx/.github as well, or --owner SkunkWerkx in place of both.

Layout

Contributing

Pull requests and issues are welcome. .github/workflows/ci.yml builds and tests every binding on every platform — a PR should stay green there before merging. Locally, rust/check-core.sh is the core's proof and cargo test its suite; each binding's README says how to run its own.

License

MIT