hypercast 0.6.1-x86_64-linux-gnu → 0.8.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96deee8d9c67d0451094f1d85c3219468c5491e3ff2768e52f0d3b8a9326f1bd
-  data.tar.gz: 367b086200228d933395f3cef8c05c42f47a11aedb85eea3a491e3ae9911d3ef
+  metadata.gz: e7dd651d6fbef906514d4873b17dffc7e45fa80e970b6f7636110963c58e6bf1
+  data.tar.gz: a3e8e5b91540b87178fb5c00c6d64f54d2b010fd7ab2a2daf8427727ef33128c
 SHA512:
-  metadata.gz: 94f6b903d7f9e7a79572ce14f89e5e22d763cedb1934cfd2f5d6d0c7b9711415f03d0098d20640ddf31fba00d15e20caa8afa81e8799b433cd7a41885073e363
-  data.tar.gz: 3fb41a394fcd88460a417448560d911687d38a6c020c7bd7875eba64dfd2f9e9fc89e458d27f1549229484d62529b65b4ed422d3fb2d8d974267546a6c308bf7
+  metadata.gz: 526fc92a7b0f0e1f3c8487504aa666a45a988dd39212ecc8652a126d3115b10ca533c0f7fd6604b68e56dd02be5449e4b150f683391de131ab09279d71cb12be
+  data.tar.gz: 6921bb861ac1cc13eab9f3f2a0349dc66827fb4d88eb2b79c514c5ac6f49fb53771a212a3e87e52172e250eabb87f3b06ca602ad0781ca0413e40fa0c671b333

data/README.md

@@ -9,8 +9,8 @@ Symbol plus the exact span that offended. Two backends, one public surface: a Ma
 native extension where a precompiled platform gem covers you, stdlib Fiddle as the last
 resort everywhere else — selected automatically, zero compiles either way.**
 
-Allocation-lean scalar casts — booleans, the full integer family, reals, exact decimals,
-UUIDs, temporals — calling directly into the native `libhypercast` Rust core. Ruby 3.3 is the
+Allocation-lean scalar casts — booleans, characters, the full integer family, reals, exact
+decimals, UUIDs, temporals — calling directly into the native `libhypercast` Rust core. Ruby 3.3 is the
 floor. The fast path links the core straight into a Ruby extension (Magnus): on require it
 redefines the doors in place on the `HyperCast` module — no delegation layer, no second
 surface, which is exactly what keeps the backends provably in agreement.
@@ -39,9 +39,10 @@ midnight, durations come back as exact `Rational` seconds across the core's whol
 | Door | Value | Declares |
 |---|---|---|
 | `bool(text)` | `true`/`false` | — |
-| `i8` `i16` `i32` `i64` `u8` `u16` `u32` `u64` `(text, format)` | `Integer` (unbounded — u64 is the true unsigned value) | a `NumFormat` |
-| `f32` `f64` `(text, format)` | `Float` (f32 widened losslessly) | a `NumFormat` |
-| `decimal(text, format)` | `HyperCast::Decimal` — exact sign, 96-bit magnitude, base-10 scale | a `NumFormat` |
+| `char(text)` | one-character UTF-8 `String` — the text verbatim when it is one character (`" "` is a space), else a declared code point (`65`, `U+0041`, `0x41`, `&H41`, `A`, `A`) | — |
+| `i8` `i16` `i32` `i64` `u8` `u16` `u32` `u64` `(text, format)` [^overrides] | `Integer` (unbounded — u64 is the true unsigned value) | a `NumFormat` |
+| `f32` `f64` `(text, format)` [^overrides] | `Float` (f32 widened losslessly) | a `NumFormat` |
+| `decimal(text, format)` [^overrides] | `HyperCast::Decimal` — exact sign, 96-bit magnitude, base-10 scale | a `NumFormat` |
 | `uuid(text)` | lowercase hyphenated `String` (`SecureRandom.uuid`'s shape) | — |
 | `timestamp(text)` | UTC `Time`, full nanoseconds | — |
 | `unix(text, precision)` | UTC `Time` | `:seconds` / `:milliseconds` / `:microseconds` / `:nanoseconds` |
@@ -50,6 +51,10 @@ midnight, durations come back as exact `Rational` seconds across the core's whol
 | `datetime(text, order)` | zone-less `DateTime`, exact `Rational` seconds | a field order, as `date` |
 | `time(text)` | `Integer` nanoseconds since midnight | — |
 | `duration(text)` | exact `Rational` seconds | — |
+| `decimal_from_float(value)` | `HyperCast::Decimal`, the shortest that names the number (`0.1` is one tenth) | — |
+| `excel_serial_from_float(value, epoch)` | zone-less `DateTime`, as `datetime` | `:y1900` / `:y1904` |
+| `excel_time(value)` | `Integer` nanoseconds since midnight | — |
+| `excel_duration(value)` | exact `Rational` seconds | — |
 
 Every door returns a `Success` or a `Fault`; `HyperCast.optional(verdict)` folds `:empty`
 to `nil`. Beside the doors, `native_version` returns the loaded core's
@@ -61,7 +66,8 @@ to `nil`. Beside the doors, `native_version` returns the loaded core's
 Bad data is never an exception — it is a `Fault`. What raises is a caller bug, and it raises
 the same exception on every backend:
 
-- `ArgumentError` from `NumFormat.new` for a malformed format: separators that are not single
+- `ArgumentError` from `NumFormat.new`, `NumFormat#override` (and so the `separator:`,
+  `delimiter:` and `unit:` keywords) or `NumFormat.from_i18n` for a malformed format: separators that are not single
   characters or not distinct, a currency symbol that is too long or carries an ASCII digit or
   whitespace.
 - `KeyError` — `Hash#fetch`'s own, `key not found: …` — for a precision, epoch or date order
@@ -156,6 +162,70 @@ Across the ABI a `NumFormat` is a 32-byte struct — the two separators as code
 flags, and the symbol's length and UTF-8 bytes held inline — packed once per format object
 and memoized by identity on every backend, so declaring a currency costs a cast nothing.
 
+### Rails' words for a format: `separator:`, `delimiter:`, `unit:`
+
+Ruby's standard library carries no locale number data, so the vocabulary Ruby code already
+speaks is Rails' — the number helpers' and I18n's `number.format`: `separator` (the decimal
+mark), `delimiter` (grouping) and `unit` (the currency symbol). Every numeric door takes
+them as keywords that replace those fields of the format for the call, and
+`NumFormat.from_i18n` builds a format from the Hash I18n hands back:
+
+```ruby
+inv = HyperCast::NumFormat::INVARIANT
+HyperCast.f64("1.234,5", inv, separator: ",", delimiter: ".")         # => Success(value: 1234.5)
+HyperCast.decimal("1.234,50 kr.", inv, separator: ",", delimiter: ".", unit: "kr.")
+
+german = HyperCast::NumFormat.from_i18n(I18n.t("number.format"))      # {separator: ",", delimiter: ".", ...}
+HyperCast.i32("1.234", german)                                        # => Success(value: 1234)
+```
+
+The keywords go through `NumFormat#override`, which is public: the result is validated like
+any `NumFormat`, and the flags are left alone, so a `unit:` on a format without `CURRENCY`
+is declared but not honored, as it would be in the constructor. `from_i18n` reads Symbol or
+String keys and ignores every other key, so `number.currency.format` works as well. Missing
+keys keep the invariant's fields. An empty `delimiter` (a locale that writes no grouping)
+turns `GROUPING` off. `flags:` defaults to `ALL_STYLES`.
+
+A call without the keywords is exactly the call it was, with no extra allocation on either
+backend. A call with them builds a format each time (a few microseconds), so in a loop,
+build it once with `override` or `from_i18n` and pass that instead.
+
+[^overrides]: Plus the optional keywords `separator:`, `delimiter:` and `unit:`, which
+    override those fields of `format` for the call. See
+    [Rails' words for a format](#rails-words-for-a-format-separator-delimiter-unit).
+
+## Interop: building on HyperCast's C ABI
+
+For a gem that carries HyperCast's verdicts across a C ABI of its own, as HyperTabular does:
+it reads the core's out-values out of its own buffers and needs the values the doors would
+have returned. `HyperCast::Interop` is the code the Fiddle backend's doors decode with, so
+the two cannot drift. It is loaded on every backend.
+
+- `SCALARS` — the `String#unpack` directive for one value of each scalar door (`:i32` is
+  `"l<"`; a bool is the byte 0 or 1).
+- `RECORDS` — for each record door (`:decimal`, `:uuid`, `:timestamp`, `:date`, …), the
+  directive that unpacks one value, how many fields that yields, and a lambda
+  `(fields, at)` that builds the Ruby value from them. To decode a column, append `"*"` and
+  step that many fields at a time.
+- `VALUE_BYTES` — the bytes one value of each door takes.
+- `decode(door, bytes)` — one value, from the bytes the core wrote for it.
+- `fault(code, offset, length)` — the `Fault` a nonzero verdict code names; a code that names
+  no reason is a `KeyError`.
+- `characters(bytes, offset, length)` — the core's byte span as the character span
+  `String#[]` slices by.
+- `version(word)` — a packed `*_version` word as `"major.minor.patch"`.
+- `library_path(library, native_dir, repo_root)` — the shared library to `dlopen`: the
+  staged `native/{rid}/` build, else the in-repo cargo build, else `nil`.
+
+`NativePlatform.rid_and_library_name(library: "hypertabular")` gives the `{rid}` directory
+and file name for any SkunkWerkx core; `library:` defaults to `"hypercast"`.
+
+```ruby
+HyperCast::Interop.decode(:i32, [-7].pack("l<"))           # => -7
+HyperCast::Interop.fault(2, 3, 1)                          # => Fault, reason :malformed
+HyperCast::Interop.version(0x000700)                       # => "0.7.0"
+```
+
 ## Why not `Integer()` / `Time.iso8601` / `Float()`?
 
 1. **Verdicts, not exceptions** — bad data is the expected case for untrusted text; a
@@ -169,12 +239,12 @@ and memoized by identity on every backend, so declaring a currency costs a cast
    boundary).
 4. **Faster than the stdlib on the Magnus backend, where the carrier is cheap** —
    benchmark-ips (`ruby benchmark/cast_benchmark.rb`, linux-x64 on an Intel Core
-   i9-11900H, Ruby 4.0.7): timestamp **447 ns vs 2.97 µs `Time.iso8601`** (6.6x) — while
+   i9-11900H, Ruby 4.0.7): timestamp **404 ns vs 2.70 µs `Time.iso8601`** (6.7x) — while
    returning exact `Rational` durations on the duration door. The Fiddle fallback lands at
-   3.25 µs: a little behind `Time.iso8601`, sitting on Fiddle's per-call marshalling floor.
+   2.85 µs: a little behind `Time.iso8601`, sitting on Fiddle's per-call marshalling floor.
 
    Separator detection is nearly free here: `1.234.567,89` under `NumFormat::DETECT` runs
-   at 178 ns against 170 ns for the same text under a declared eurozone format. Both cost
+   at 154 ns against 145 ns for the same text under a declared eurozone format. Both cost
    nearly twice that in 0.1.0, for a reason that had nothing to do with parsing: every format other than `INVARIANT` paid three method dispatches and two
    `String` allocations per call to read its separators back out of the `Data`. `DETECT`
    is now identity-matched like `INVARIANT`, and any other format is resolved once per
@@ -213,14 +283,14 @@ both backends:
 
 | Door | Magnus | Fiddle |
 |---|---:|---:|
-| `bool` | 112 ns | 2.35 µs |
-| `i32` | 133 ns | 2.63 µs |
-| `f64` | 166 ns | 2.70 µs |
-| `uuid` | 223 ns | 3.47 µs |
-| `timestamp` | 447 ns | 3.25 µs |
-| `datetime` (`1/7/2026 3:04 PM`) | 904 ns | 3.98 µs |
-| `duration` (ISO) | 632 ns | 2.91 µs |
-| `i32`, a fault | 225 ns | 3.18 µs |
+| `bool` | 109 ns | 2.30 µs |
+| `i32` | 120 ns | 2.30 µs |
+| `f64` | 134 ns | 2.44 µs |
+| `uuid` | 209 ns | 3.28 µs |
+| `timestamp` | 404 ns | 2.85 µs |
+| `datetime` (`1/7/2026 3:04 PM`) | 877 ns | 3.71 µs |
+| `duration` (ISO) | 578 ns | 2.72 µs |
+| `i32`, a fault | 202 ns | 2.88 µs |
 
 A lean door on the Magnus backend is little more than the native call: the extension builds
 the `Success` or `Fault` it returns directly — allocated, its members stored, frozen —
@@ -311,7 +381,7 @@ one at `require` time:
 | 3.3 (the floor, until its EOL 2027-03-31) | Fiddle | universal |
 
 What stands behind each cell: CI replays the whole suite, shared corpus included, through
-each Magnus extension on every push — Ruby 3.4 and 4.0 on all seven platform-gem platforms,
+each Magnus extension — Ruby 4.0 on every pull request and Ruby 3.4 in the weekly and release builds, on all seven platform-gem platforms,
 the two musl ones inside each Ruby's own Alpine image — and the Fiddle suite on Ruby 4.0 on
 every one of them, plus on Ruby 3.3 inside Alpine. Intel macOS has no CI leg: its library is
 cross-built and tested at the core, and Ruby there runs the universal gem's Fiddle backend

data/lib/hypercast/interop.rb

@@ -0,0 +1,119 @@
+module HyperCast
+  # The native core's C ABI values, presented — for a gem that carries HyperCast's verdicts
+  # across a C ABI of its own (HyperTabular does): how each door's out-value unpacks and what
+  # builds the Ruby value from it, the verdict code and span of a fault, the packed version
+  # word, and where a gem's native library is. The Fiddle backend's doors decode with exactly
+  # these, so a value read out of another library's buffer is the value the door would have.
+  #
+  # Every directive below unpacks one value. A gem decoding a whole column appends "*" and
+  # steps +fields+ at a time.
+  module Interop
+    # The doors whose value is one String#unpack directive away: the directive for one value.
+    # A bool is the byte 0 or 1, unpacked as "C" and compared with zero.
+    SCALARS = {
+      bool: "C", i8: "c", i16: "s<", i32: "l<", i64: "q<", u8: "C", u16: "S<", u32: "L<",
+      u64: "Q<", f32: "e", f64: "E", time: "Q<"
+    }.freeze
+
+    # The doors whose value is a record: the directive that unpacks one, how many fields that
+    # yields, and what builds the door's Ruby value from them, starting at field +at+.
+    RECORDS = {
+      char: ["L<", 1, ->(fields, at) { fields[at].chr(Encoding::UTF_8) }],
+      decimal: ["Q<L<CCx2", 4, ->(fields, at) { decimal(fields[at], fields[at + 1], fields[at + 2], fields[at + 3]) }],
+      uuid: ["H8H4H4H4H12", 5, ->(fields, at) { fields[at, 5].join("-") }],
+      timestamp: ["q<l<x4", 2, ->(fields, at) { instant(fields[at], fields[at + 1]) }],
+      date: ["S<CC", 3, ->(fields, at) { Date.new(fields[at], fields[at + 1], fields[at + 2]) }],
+      datetime: ["S<CCx4Q<", 4, ->(fields, at) { civil(fields[at], fields[at + 1], fields[at + 2], fields[at + 3]) }],
+      duration: ["q<l<x4", 2, ->(fields, at) { duration(fields[at], fields[at + 1]) }]
+    }.tap do |records|
+      records[:unix] = records[:excel_serial] = records[:timestamp]
+      records[:date_ordered] = records[:date]
+    end.freeze
+
+    # The bytes one value of each door takes.
+    VALUE_BYTES = {
+      bool: 1, i8: 1, u8: 1, i16: 2, u16: 2, i32: 4, u32: 4, f32: 4, char: 4, date: 4, date_ordered: 4,
+      i64: 8, u64: 8, f64: 8, time: 8,
+      decimal: 16, uuid: 16, timestamp: 16, unix: 16, excel_serial: 16, datetime: 16, duration: 16
+    }.freeze
+
+    # Encodings whose bytes already are the UTF-8 (or byte-identical) form the core reads.
+    BYTE_COMPATIBLE = [Encoding::UTF_8, Encoding::US_ASCII, Encoding::ASCII_8BIT].freeze
+
+    module_function
+
+    # One value of +door+, from the bytes the core wrote for it.
+    def decode(door, bytes)
+      if (directive = SCALARS[door])
+        value = bytes.unpack1(directive)
+        door == :bool ? value != 0 : value
+      else
+        directive, _fields, build = RECORDS.fetch(door)
+        build.call(bytes.unpack(directive), 0)
+      end
+    end
+
+    # A UTC Time from the core's protobuf-shaped {seconds, nanos} pair, exactly — the
+    # timestamp, unix and excel_serial doors' value. (Time.at then #utc is the same Time as
+    # Time.at(..., in: "UTC"), at half the cost: the zone's name is not read each time.)
+    def instant(seconds, nanos)
+      Time.at(seconds, nanos, :nanosecond).utc
+    end
+
+    # The zone-less DateTime a civil date-time names, with exact Rational seconds — the
+    # datetime door's value. Its +00:00 offset is a carrier artifact, not data.
+    def civil(year, month, day, nanos_of_day)
+      second_of_day, frac = nanos_of_day.divmod(1_000_000_000)
+      hour, rest = second_of_day.divmod(3600)
+      minute, second = rest.divmod(60)
+      DateTime.new(year, month, day, hour, minute, second + Rational(frac, 1_000_000_000))
+    end
+
+    # Exact Rational seconds from the core's same-signed {seconds, nanos} pair — the duration
+    # door's value.
+    def duration(seconds, nanos)
+      Rational(seconds * 1_000_000_000 + nanos, 1_000_000_000)
+    end
+
+    # A Decimal from the core's {lo, hi, scale, negative} — the decimal door's value.
+    def decimal(lo, hi, scale, negative)
+      Decimal.new(magnitude: (hi << 64) | lo, scale: scale, negative: negative != 0)
+    end
+
+    # The Fault a nonzero verdict code and its span name. A code that names no reason is a
+    # binding bug, not data: a KeyError.
+    def fault(code, offset, length)
+      Fault.new(reason: REASONS.fetch(code), offset: offset, length: length)
+    end
+
+    # The core's byte span over +bytes+, in the units String#[] slices by: an identity for a
+    # binary String (its characters are its bytes) and for ASCII text (`ascii_only?` reads the
+    # cached coderange — no scan), a byte-to-character remap otherwise. Character counts
+    # survive transcoding, so a span mapped on the UTF-8 form indexes the caller's own String
+    # whatever encoding it arrived in.
+    def characters(bytes, offset, length)
+      return [offset, length] if bytes.encoding == Encoding::ASCII_8BIT || bytes.ascii_only?
+
+      [bytes.byteslice(0, offset).length, bytes.byteslice(offset, length).length]
+    end
+
+    # A native library's packed version word — major << 16 | minor << 8 | patch, as a
+    # *_version export returns it — as "major.minor.patch".
+    def version(word)
+      "#{word >> 16}.#{(word >> 8) & 0xFF}.#{word & 0xFF}"
+    end
+
+    # The shared library to dlopen for +library+ ("hypercast" for libhypercast.so): the
+    # gem's native/{rid}/{file} under +native_dir+, or — the development loop — the cargo
+    # build under +repo_root+/rust/target/release, exactly what the other bindings' local
+    # staging does. Nil when neither exists.
+    def library_path(library, native_dir, repo_root)
+      rid, file = NativePlatform.rid_and_library_name(library: library)
+      path = File.join(native_dir, rid, file)
+      return path if File.exist?(path)
+
+      repo_build = File.join(repo_root, "rust", "target", "release", file)
+      File.exist?(repo_build) ? repo_build : nil
+    end
+  end
+end

data/lib/hypercast/native_platform.rb

@@ -1,27 +1,29 @@
 module HyperCast
   # Maps the running RUBY_PLATFORM to the RID-style directory (matching the other bindings'
-  # runtimes/{rid}/native/ / native/{rid}/ convention) and native library filename to load.
+  # runtimes/{rid}/native/ / native/{rid}/ convention) and file name of a native library.
+  # Every SkunkWerkx core ships the same way, so +library+ names whose: "hypercast" for this
+  # gem's libhypercast, "hypertabular" for HyperTabular's.
   module NativePlatform
     class UnsupportedPlatformError < StandardError; end
 
     # +platform+ is a parameter only so the specs can walk the whole table from one host;
     # every real caller takes the default.
-    def self.rid_and_library_name(platform = RUBY_PLATFORM)
+    def self.rid_and_library_name(platform = RUBY_PLATFORM, library: "hypercast")
       arch = platform.match?(/arm64|aarch64/) ? "arm64" : "x64"
 
       case platform
       when /mingw|mswin|windows/
-        ["win-#{arch}", "hypercast.dll"]
+        ["win-#{arch}", "#{library}.dll"]
       when /darwin/
-        ["osx-#{arch}", "libhypercast.dylib"]
+        ["osx-#{arch}", "lib#{library}.dylib"]
       when /linux/
         # Two C libraries, two builds: a glibc-linked library cannot be relied on to dlopen
         # into a musl process (Alpine), so musl gets RIDs of its own. Ruby names the libc
         # in its platform string there ("x86_64-linux-musl") and leaves it off on glibc.
         os = platform.include?("musl") ? "linux-musl" : "linux"
-        ["#{os}-#{arch}", "libhypercast.so"]
+        ["#{os}-#{arch}", "lib#{library}.so"]
       else
-        raise UnsupportedPlatformError, "hypercast: unsupported platform RUBY_PLATFORM=#{platform}"
+        raise UnsupportedPlatformError, "#{library}: unsupported platform RUBY_PLATFORM=#{platform}"
       end
     end
   end

data/lib/hypercast/runtime.rb

@@ -17,16 +17,20 @@ module HyperCast
     # Each door's C signature, by shape — resolved to Fiddle types only in load_functions,
     # so nothing here touches Fiddle until the Fiddle backend actually runs: plain is
     # (text, len, out, fault), numeric adds the packed NumFormat pointer before out, and
-    # declared a caller-declared u32 (precision, epoch, field order) in the same place.
+    # declared a caller-declared u32 (precision, epoch, field order) in the same place. The
+    # typed doors take a double instead of the text and its length: typed is (value, out,
+    # fault), typed_declared adds the u32 after the value.
     DOORS = {
-      cast_bool: :plain,
+      cast_bool: :plain, cast_char: :plain,
       cast_i8: :numeric, cast_i16: :numeric, cast_i32: :numeric, cast_i64: :numeric,
       cast_u8: :numeric, cast_u16: :numeric, cast_u32: :numeric, cast_u64: :numeric,
       cast_f32: :numeric, cast_f64: :numeric, cast_decimal: :numeric,
       cast_uuid: :plain,
       cast_timestamp: :plain, cast_unix: :declared, cast_excel_serial: :declared,
       cast_date: :plain, cast_date_ordered: :declared, cast_datetime: :declared,
-      cast_time: :plain, cast_duration: :plain
+      cast_time: :plain, cast_duration: :plain,
+      cast_decimal_from_f64: :typed, cast_excel_serial_from_f64: :typed_declared,
+      cast_excel_time: :typed, cast_excel_duration: :typed
     }.freeze
 
     # The one export that is not a door: the zero-argument version probe, returning the
@@ -60,12 +64,7 @@ module HyperCast
       # development loop — the in-repo cargo build, exactly what the other bindings' local
       # staging does. Nil when neither exists.
       def library_path
-        rid, lib_name = NativePlatform.rid_and_library_name
-        path = File.join(NATIVE_DIR, rid, lib_name)
-        return path if File.exist?(path)
-
-        repo_build = File.expand_path(File.join(__dir__, "../../../rust/target/release", lib_name))
-        File.exist?(repo_build) ? repo_build : nil
+        Interop.library_path("hypercast", NATIVE_DIR, File.expand_path("../../..", __dir__))
       end
 
       # Why Fiddle found nothing to load. A precompiled platform gem is the one install where
@@ -114,7 +113,9 @@ module HyperCast
         signatures = {
           plain: plain,
           numeric: plain.dup.insert(2, Fiddle::TYPE_VOIDP),
-          declared: plain.dup.insert(2, Fiddle::TYPE_UINT32_T)
+          declared: plain.dup.insert(2, Fiddle::TYPE_UINT32_T),
+          typed: [Fiddle::TYPE_DOUBLE, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP],
+          typed_declared: [Fiddle::TYPE_DOUBLE, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP]
         }
         functions = DOORS.to_h do |name, shape|
           [name, Fiddle::Function.new(handle[name.to_s], signatures.fetch(shape), Fiddle::TYPE_INT32_T)]

data/lib/hypercast.rb

@@ -1,5 +1,6 @@
 require "date"
 require_relative "hypercast/native_platform"
+require_relative "hypercast/interop"
 require_relative "hypercast/runtime"
 
 # Allocation-lean scalar casts — booleans, numerics, exact decimals, UUIDs, temporals —
@@ -29,7 +30,7 @@ require_relative "hypercast/runtime"
 module HyperCast
   # This gem's own version — kept in lockstep with hypercast.gemspec by the
   # prepare-release workflow, so the two can never drift apart again.
-  VERSION = "0.6.1"
+  VERSION = "0.8.0"
 
   # The success case of a verdict: a cast value.
   Success = Data.define(:value)
@@ -83,6 +84,50 @@ module HyperCast
       super(decimal_sep: decimal_sep, group_sep: group_sep, flags: flags, currency: symbol)
     end
 
+    # This format with the fields Ruby's number vocabulary names replaced — the words Rails'
+    # number helpers and I18n's number.format use: separator: (the decimal mark),
+    # delimiter: (grouping) and unit: (the currency symbol). A nil keyword leaves its
+    # field alone, so with none given this is the format itself, not a copy. The result is
+    # validated like any NumFormat (single, distinct separators; a declarable symbol), and
+    # the flags are untouched: a unit: declared on a format without CURRENCY is a :malformed
+    # Fault at the symbol, exactly as declaring it in the constructor would be. Every
+    # numeric door takes the same three keywords and applies them through this method.
+    def override(separator: nil, delimiter: nil, unit: nil)
+      return self unless separator || delimiter || unit
+
+      with(**{ decimal_sep: separator, group_sep: delimiter, currency: unit }.compact)
+    end
+
+    # A format from a Hash shaped like I18n's number.format (or number.currency.format):
+    # :separator, :delimiter and :unit, Symbol or String keys, every other key (precision,
+    # format, significant, ...) ignored — so `NumFormat.from_i18n(I18n.t("number.format"))`
+    # drops a Rails locale straight in, with no I18n dependency here. A missing or nil key
+    # keeps the invariant's "." / "," / no symbol. An empty delimiter — the locale writes no
+    # grouping — turns GROUPING off rather than declaring a separator, since a NumFormat
+    # always carries one; the placeholder it gets is whichever of "," and "." the decimal
+    # mark is not. flags defaults to every lenience, the same as INVARIANT.
+    #
+    # Only the separators and the unit carry over; the native format has no field for the
+    # rest. The core reads ASCII "+" and "-" only, so a locale that writes negatives with
+    # another sign (U+2212 for Estonian and Basque, for instance) faults on them; currency
+    # amounts in a locale whose number.currency.format separators differ from number.format's
+    # read with whichever Hash is passed, so pass the currency one for currency columns; and
+    # percent is an ASCII "%". Every lenience is on, radix prefixes and percent included;
+    # narrow flags: for anything stricter.
+    def self.from_i18n(number_format, flags: ALL_STYLES)
+      raise ArgumentError, "expected a Hash-like number format; got #{number_format.inspect}" unless
+        number_format.respond_to?(:to_h)
+
+      entries = number_format.to_h.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+      separator = entries[:separator] || "."
+      delimiter = entries[:delimiter] || ","
+      if delimiter == ""
+        flags &= ~GROUPING
+        delimiter = separator == "," ? "." : ","
+      end
+      new(decimal_sep: separator, group_sep: delimiter, flags: flags, currency: entries[:unit] || "")
+    end
+
     # The 32-byte little-endian form the native ABI's NumFormat struct expects: the two
     # separators as code points, the flags, the symbol's byte length, then the symbol's
     # UTF-8 bytes zero-padded to 16.
@@ -216,33 +261,49 @@ module HyperCast
     # (t/f, yes/no, y/n, 1/0, on/off, enabled/disabled, active/inactive,
     # checked/unchecked, in/out), ASCII case-insensitive.
     def bool(text)
-      plain(:cast_bool, text, 1) { |out| out.unpack1("C") != 0 }
+      plain(:cast_bool, text, 1) { |out| Interop.decode(:bool, out) }
     end
 
-    { i8: "c", i16: "s<", i32: "l<", i64: "q<", u8: "C", u16: "S<", u32: "L<", u64: "Q<" }
-      .each do |door, unpack|
-      sizes = { "c" => 1, "C" => 1, "s<" => 2, "S<" => 2, "l<" => 4, "L<" => 4, "q<" => 8, "Q<" => 8 }
-      size = sizes.fetch(unpack)
+    # Casts char text to a one-character UTF-8 String: an input of exactly one character is
+    # that character verbatim (" " is a space), otherwise one declared code point — 65,
+    # U+0041, 0x41, &H41, &#65; or &#x41; — surrounded by optional ASCII whitespace. A code
+    # point past U+10FFFF, or a surrogate, is :out_of_range.
+    def char(text)
+      plain(:cast_char, text, 4) { |out| Interop.decode(:char, out) }
+    end
+
+    %i[i8 i16 i32 i64 u8 u16 u32 u64].each do |door|
+      unpack = Interop::SCALARS.fetch(door)
+      size = Interop::VALUE_BYTES.fetch(door)
       # Resolved once here, not inside the method: interpolating a Symbol per call built a
       # String and interned it on every integer cast.
       symbol = :"cast_#{door}"
       # Integer doors: the target type's own range, declared grouping, accounting parens,
       # non-negative exponent, and 0x/&H/0b two's-complement radix prefixes. Ruby Integer
-      # is unbounded, so u64 comes back as the true unsigned value.
-      define_method(door) do |text, format|
+      # is unbounded, so u64 comes back as the true unsigned value. separator:, delimiter:
+      # and unit: override those fields of format for this call (NumFormat#override).
+      define_method(door) do |text, format, separator: nil, delimiter: nil, unit: nil|
+        format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
+          separator || delimiter || unit
         numeric(symbol, text, format, size) { |out| out.unpack1(unpack) }
       end
     end
 
     # Casts real text to an IEEE single (widened losslessly on the way out): finite values
     # only, declared separators and grouping, parens, exponent, and trailing percent.
-    def f32(text, format)
-      numeric(:cast_f32, text, format, 4) { |out| out.unpack1("e") }
+    # separator:, delimiter: and unit: override those fields of format for this call
+    # (NumFormat#override), on this door and every other numeric one.
+    def f32(text, format, separator: nil, delimiter: nil, unit: nil)
+      format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
+        separator || delimiter || unit
+      numeric(:cast_f32, text, format, 4) { |out| Interop.decode(:f32, out) }
     end
 
     # Casts real text to an IEEE double. Notation rules as f32.
-    def f64(text, format)
-      numeric(:cast_f64, text, format, 8) { |out| out.unpack1("E") }
+    def f64(text, format, separator: nil, delimiter: nil, unit: nil)
+      format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
+        separator || delimiter || unit
+      numeric(:cast_f64, text, format, 8) { |out| Interop.decode(:f64, out) }
     end
 
     # Casts decimal text to an exact Decimal — the real doors' grammar (declared separators
@@ -251,33 +312,30 @@ module HyperCast
     # "1.10" is canonical magnitude 11, scale 1 — exact trailing zeros are always trimmed.
     # A magnitude past 2**96 - 1, or more fractional precision than 28 places can hold, is
     # an :out_of_range Fault — the door never rounds.
-    def decimal(text, format)
-      numeric(:cast_decimal, text, format, 16) do |out|
-        lo, hi, scale, negative = out.unpack("Q<L<CCx2")
-        Decimal.new(magnitude: (hi << 64) | lo, scale: scale, negative: negative != 0)
-      end
+    def decimal(text, format, separator: nil, delimiter: nil, unit: nil)
+      format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
+        separator || delimiter || unit
+      numeric(:cast_decimal, text, format, 16) { |out| Interop.decode(:decimal, out) }
     end
 
     # Casts UUID text — all five .NET Guid formats (D/N/B/P/X) plus urn:uuid:/GUID:/UUID:
     # prefixes — to Ruby's UUID lingua franca: the lowercase hyphenated String (the same
     # shape SecureRandom.uuid returns).
     def uuid(text)
-      plain(:cast_uuid, text, 16) do |out|
-        out.unpack("H8H4H4H4H12").join("-")
-      end
+      plain(:cast_uuid, text, 16) { |out| Interop.decode(:uuid, out) }
     end
 
     # Casts an RFC 3339 instant — zone mandatory — to a UTC Time at full nanosecond
     # fidelity across the whole 0001-9999 window.
     def timestamp(text)
-      plain(:cast_timestamp, text, 16) { |out| instant(out) }
+      plain(:cast_timestamp, text, 16) { |out| Interop.decode(:timestamp, out) }
     end
 
     # Casts an integer Unix-epoch value under a caller-declared unit Symbol
     # (:seconds/:milliseconds/:microseconds/:nanoseconds) to a UTC Time. An unknown unit
     # is a caller bug (KeyError), never a verdict.
     def unix(text, precision)
-      declared(:cast_unix, text, UNIX_PRECISIONS.fetch(precision), 16) { |out| instant(out) }
+      declared(:cast_unix, text, UNIX_PRECISIONS.fetch(precision), 16) { |out| Interop.decode(:unix, out) }
     end
 
     # Casts an Excel date serial under a caller-declared epoch Symbol (:y1900/:y1904) to a
@@ -291,7 +349,7 @@ module HyperCast
     # the text "1900-02-29" — so every serial above it is shifted one day against a naive
     # count. An unknown epoch is a caller bug (KeyError), never a verdict.
     def excel_serial(text, epoch)
-      declared(:cast_excel_serial, text, EXCEL_EPOCHS.fetch(epoch), 16) { |out| instant(out) }
+      declared(:cast_excel_serial, text, EXCEL_EPOCHS.fetch(epoch), 16) { |out| Interop.decode(:excel_serial, out) }
     end
 
     # Casts a calendar date to a Date. With no order declared: the strict ISO 8601
@@ -301,15 +359,9 @@ module HyperCast
     # caller bug (KeyError), never a verdict.
     def date(text, order = nil)
       if order.nil?
-        plain(:cast_date, text, 4) do |out|
-          year, month, day = out.unpack("S<CC")
-          Date.new(year, month, day)
-        end
+        plain(:cast_date, text, 4) { |out| Interop.decode(:date, out) }
       else
-        declared(:cast_date_ordered, text, DATE_ORDERS.fetch(order), 4) do |out|
-          year, month, day = out.unpack("S<CC")
-          Date.new(year, month, day)
-        end
+        declared(:cast_date_ordered, text, DATE_ORDERS.fetch(order), 4) { |out| Interop.decode(:date_ordered, out) }
       end
     end
 
@@ -322,29 +374,51 @@ module HyperCast
     # fusing a real zone is the caller's job, and timestamp stays the strict RFC 3339
     # instant door. An unknown order is a caller bug (KeyError).
     def datetime(text, order)
-      declared(:cast_datetime, text, DATE_ORDERS.fetch(order), 16) do |out|
-        year, month, day, nanos = out.unpack("S<CCx4Q<")
-        second_of_day, frac = nanos.divmod(1_000_000_000)
-        hour, rest = second_of_day.divmod(3600)
-        minute, second = rest.divmod(60)
-        DateTime.new(year, month, day, hour, minute, second + Rational(frac, 1_000_000_000))
-      end
+      declared(:cast_datetime, text, DATE_ORDERS.fetch(order), 16) { |out| Interop.decode(:datetime, out) }
     end
 
     # Casts an ISO 24-hour time-of-day to an exact Integer of nanoseconds since midnight
     # (Ruby has no time-of-day type; the integer keeps every digit).
     def time(text)
-      plain(:cast_time, text, 8) { |out| out.unpack1("Q<") }
+      plain(:cast_time, text, 8) { |out| Interop.decode(:time, out) }
     end
 
     # Casts a duration (ISO 8601 fixed components, invariant colon form, or protobuf JSON
     # seconds) to exact Rational seconds — full fidelity across the core's ±10,000-year
     # window, no wrapping and no truncation.
     def duration(text)
-      plain(:cast_duration, text, 16) do |out|
-        seconds, nanos = out.unpack("q<l<")
-        Rational(seconds * 1_000_000_000 + nanos, 1_000_000_000)
-      end
+      plain(:cast_duration, text, 16) { |out| Interop.decode(:duration, out) }
+    end
+
+    # Reads a number a caller already holds — an Integer, Float or Rational, the way Ruby's
+    # own Float conversion takes it; anything else, a String included, is a TypeError — as
+    # the exact Decimal it names: the shortest decimal that rounds back to the Float, the
+    # digits a spreadsheet writes for it. 0.1 is magnitude 1, scale 1, not the binary
+    # fraction nearest it; 0.1 + 0.2 is 0.30000000000000004. NaN is :malformed; an infinity,
+    # a magnitude past 2**96 - 1 or more than 28 places is :out_of_range. A typed door's
+    # Fault has no span: offset and length are 0.
+    def decimal_from_float(value)
+      typed(:cast_decimal_from_f64, float(value), 16) { |out| Interop.decode(:decimal, out) }
+    end
+
+    # Reads an Excel serial number under a declared epoch Symbol (:y1900/:y1904) as the
+    # zone-less DateTime it names — the twin of excel_serial for a number a workbook reader
+    # already holds, on the same carrier datetime uses. The 1900 system's phantom serial 60
+    # is :out_of_range; a negative, NaN or infinite serial is :malformed.
+    def excel_serial_from_float(value, epoch)
+      number = float(value)
+      typed(:cast_excel_serial_from_f64, number, 16, EXCEL_EPOCHS.fetch(epoch)) { |out| Interop.decode(:datetime, out) }
+    end
+
+    # Reads the fraction of an Excel serial number as an exact Integer of nanoseconds since
+    # midnight, as time does; 0.75 and 45292.75 are both 18:00.
+    def excel_time(value)
+      typed(:cast_excel_time, float(value), 8) { |out| Interop.decode(:time, out) }
+    end
+
+    # Reads a number of days as exact Rational seconds, as duration does: 1.5 is 129600.
+    def excel_duration(value)
+      typed(:cast_excel_duration, float(value), 16) { |out| Interop.decode(:duration, out) }
     end
 
     # The version of the native core actually loaded, as "major.minor.patch" — read from
@@ -353,15 +427,11 @@ module HyperCast
     # not). The cheapest possible probe that the backend resolved at all: takes nothing,
     # cannot fail.
     def native_version
-      word = packed_version
-      "#{word >> 16}.#{(word >> 8) & 0xFF}.#{word & 0xFF}"
+      Interop.version(packed_version)
     end
 
     private
 
-    # Encodings whose bytes already are the UTF-8 (or byte-identical) form the core reads.
-    BYTE_COMPATIBLE = [Encoding::UTF_8, Encoding::US_ASCII, Encoding::ASCII_8BIT].freeze
-
     # Presents the input as UTF-8 bytes: already-compatible text crosses as-is (Fiddle
     # passes a String's own bytes for void* — no copy of them); only foreign encodings pay
     # a transcode, and text that cannot be transcoded raises String#encode's own
@@ -376,7 +446,7 @@ module HyperCast
           raise TypeError, "no implicit conversion of #{text.class} into String"
         text = converted
       end
-      BYTE_COMPATIBLE.include?(text.encoding) ? text : text.encode(Encoding::UTF_8)
+      Interop::BYTE_COMPATIBLE.include?(text.encoding) ? text : text.encode(Encoding::UTF_8)
     end
 
     # Fiddle spells a null pointer as nil — the core's contract for empty input.
@@ -408,22 +478,10 @@ module HyperCast
       elsif rc == -1
         raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it"
       else
-        offset, length = characters(bytes, *fault[0, 8].unpack("L<L<"))
-        Fault.new(reason: REASONS.fetch(rc), offset: offset, length: length)
+        Interop.fault(rc, *Interop.characters(bytes, *fault[0, 8].unpack("L<L<")))
       end
     end
 
-    # The core's byte span in the units String#[] slices by: an identity for a binary
-    # String (its characters are its bytes) and for ASCII text (`ascii_only?` reads the
-    # cached coderange — no scan), a byte-to-character remap otherwise. Character counts
-    # survive transcoding, so a span mapped on the UTF-8 form indexes the caller's own
-    # String whatever encoding it arrived in. Failure path only: a Success never pays.
-    def characters(bytes, offset, length)
-      return [offset, length] if bytes.encoding == Encoding::ASCII_8BIT || bytes.ascii_only?
-
-      [bytes.byteslice(0, offset).length, bytes.byteslice(offset, length).length]
-    end
-
     # The shared body of every format-free door: one native call over the scratch buffers.
     def plain(symbol, text, out_size)
       bytes = utf8(text)
@@ -452,6 +510,34 @@ module HyperCast
       verdict(rc, fault, bytes) { yield(out[0, out_size]) }
     end
 
+    # A typed door's number, converted the way the extension's argument is (C's
+    # rb_num2dbl), with the same exception and message: a Numeric converts (a Complex with an
+    # imaginary part is Complex#to_f's RangeError), anything else is a TypeError — a String
+    # among them, which Kernel#Float would have parsed.
+    def float(value)
+      case value
+      when Float then value
+      when Numeric then Float(value)
+      when String then raise TypeError, "no implicit conversion to float from string"
+      when nil, true, false then raise TypeError, "no implicit conversion to float from #{value.inspect}"
+      else raise TypeError, "can't convert #{value.class} into Float"
+      end
+    end
+
+    # The shared body of the typed doors: a double instead of the text, then the declared
+    # u32 when the door takes one.
+    def typed(symbol, number, out_size, *declared)
+      out, fault = scratch
+      rc = Runtime.function(symbol).call(number, *declared, out, fault)
+      if rc.zero?
+        Success.new(value: yield(out[0, out_size]))
+      elsif rc == -1
+        raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it"
+      else
+        Interop.fault(rc, 0, 0)
+      end
+    end
+
     # The loaded core's version word, major << 16 | minor << 8 | patch, straight from the
     # library's zero-argument hypercast_version export.
     def packed_version
@@ -482,12 +568,6 @@ module HyperCast
         cache[format] = pointer
       end.compare_by_identity
     end
-
-    # Builds a UTC Time from the core's protobuf-shaped {seconds, nanos} pair, exactly.
-    def instant(bytes)
-      seconds, nanos = bytes.unpack("q<l<")
-      Time.at(seconds, nanos, :nanosecond, in: "UTC")
-    end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hypercast
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.8.0
 platform: x86_64-linux-gnu
 authors:
 - Brian Buvinghausen
@@ -53,6 +53,7 @@ files:
 - lib/hypercast.rb
 - lib/hypercast/3.4/hypercast_native.so
 - lib/hypercast/4.0/hypercast_native.so
+- lib/hypercast/interop.rb
 - lib/hypercast/native_platform.rb
 - lib/hypercast/runtime.rb
 homepage: https://github.com/SkunkWerkx/HyperCast