hypercast-wasm 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 292a3d7a2650810b8c764162479aed060b9e05e04a15e12843bbe9d4a1e5f4ec
-  data.tar.gz: '066569a04c5f82dd1ca427c58b0483c3fa0505bd414fe80add69dea5002a9667'
+  metadata.gz: 10c626d762b241c551b0120df1d77ec78d4831a9328c670d2a7bc50c4f3cdf42
+  data.tar.gz: 3fbb217bfe1717648b5a579e034894c2eb55fc797f232b19d2f41aaf950299c2
 SHA512:
-  metadata.gz: 4c654511c4167a2addf7cb4894811c755bd6a9a9a5b7ae9bf3c35b7d24ff36cac233af75d61e7430dc7b08ef84dacf53801bf7853415a0887cbb8a61d9839b6b
-  data.tar.gz: 3e7cefe5d32a2c8f0495eb37a93460499ed2673c7452b12f9eb6b2fa90ff5258607042564460e972027f23ba486b5210d758fa9efb49d4ae98534dc3b9754fa6
+  metadata.gz: 952da6145e72b6d45cda1cb1e56351941cd19f20008a5963ab0452c8c7eec2e6e4204de281d704f2dcf8967d2a8c4a12f0c69984528cd8fdd12e26daded490a2
+  data.tar.gz: e924d2a7f955fd4f748bea86a9e11b8a05343608e4eda4358c9a324aa225088b045a6b569d318fd2b4acc443c847c5809d2ddd91fdbd5fe0aeae19bfcdd56d23

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,15 +39,16 @@ 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` |
 | `excel_serial(text, epoch)` | UTC `Time` | `:y1900` / `:y1904` |
 | `date(text, order = nil)` | `Date` | strict ISO, or `:year_month_day` / `:month_day_year` / `:day_month_year` |
-| `datetime(text, order)` | zone-less `DateTime`, exact `Rational` seconds | a field order, as `date` |
+| `datetime(text, order, am: nil, pm: nil)` | zone-less `DateTime`, exact `Rational` seconds | a field order, as `date`; optionally a culture's own AM/PM words, read beside the English ones — see [`datetime`: a culture's AM/PM](#datetime-a-cultures-ampm) |
 | `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) | — |
@@ -65,9 +66,14 @@ 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
-  characters or not distinct, a currency symbol that is too long or carries an ASCII digit or
-  whitespace.
+- `ArgumentError` from `NumFormat.new`, `NumFormat#override` (and so the `separator:`,
+  `delimiter:` and `unit:` keywords) or `NumFormat.from_i18n` for a malformed format: a
+  separator that is empty, longer than 8 UTF-8 bytes or not distinct from its partner
+  (the pair in force for currency amounts included), any symbol carrying an ASCII digit, a
+  sign, percent or currency symbol carrying ASCII whitespace, a currency symbol longer than
+  16 bytes, or a digit zero that is ASCII or starts no digit block. And from `datetime` for
+  a day-period designator that is empty, longer than 16 bytes, carries an ASCII digit or
+  starts or ends in ASCII whitespace.
 - `KeyError` — `Hash#fetch`'s own, `key not found: …` — for a precision, epoch or date order
   that names nothing: an unknown Symbol, or anything that is not a Symbol (`"seconds"`
   included). `date(text, nil)` is not one of these: an explicit `nil` order is the strict ISO
@@ -132,33 +138,166 @@ value.to_d   # => BigDecimal("-1234.5")
 `to_d` requires the `bigdecimal` gem lazily on first call — a bundled gem since Ruby 3.4,
 deliberately not a dependency of this one, so under Bundler add it to your own Gemfile.
 
-### `NumFormat`: declared separators, and a declared currency
+### `NumFormat`: declared separators, symbols and digits
 
 ```ruby
 HyperCast::NumFormat.new(decimal_sep: ".", group_sep: ",", flags: HyperCast::ALL_STYLES, currency: "$")
 ```
 
 The flags are `GROUPING`, `PARENTHESES`, `EXPONENT`, `RADIX_PREFIXES`, `PERCENT` and
-`CURRENCY` (`ALL_STYLES` is all six), plus the `SEPARATOR_DETECT` policy. The currency
-symbol is the one field a culture table would fill in: it is declared, never looked up, and
-honored only while `CURRENCY` is set — once, leading (`$5`, `-$5`, `$ -5`) or trailing
-(`5 €`, `1.234,50 kr.`), with optional ASCII whitespace between symbol and digits, and
-accounting parentheses wrapping symbol and digits together (`($5)`). Declared with the
-flag off, the symbol is a `:malformed` `Fault` at the symbol; the flag with nothing declared
-(`currency: ""`, the default — `INVARIANT` and `DETECT` declare none) matches nothing. A
-symbol longer than 16 UTF-8 bytes, or carrying an ASCII digit or ASCII whitespace, is an
-`ArgumentError` at construction, the same caller-bug treatment equal separators get.
+`CURRENCY` (`ALL_STYLES` is all six), plus `TRAILING_SIGN` — deliberately not in
+`ALL_STYLES`; see below — and the `SEPARATOR_DETECT` policy. A separator is one or two
+characters (`", "`, comma then space, is a separator), up to 8 UTF-8 bytes.
+
+Everything past the separators and the flags is what a culture table would fill in, and
+every such field is declared, never looked up — `from_i18n` fills what Rails' locale data
+offers, and the rest is a keyword on `new` or `Data#with`. The rule for all of them: **a
+declared symbol is read beside its ASCII default, never instead of it.** ASCII `-`, `+`,
+`%` and `0`–`9` are always read, so a format that declares nothing (`""` everywhere, the
+default — `INVARIANT` and `DETECT` declare none) reads exactly as the invariant culture,
+and nothing that parsed before stops parsing when a symbol is declared.
+
+- `currency:` — honored only while `CURRENCY` is set: once, leading (`$5`, `-$5`, `$ -5`)
+  or trailing (`5 €`, `1.234,50 kr.`), with optional ASCII whitespace between symbol and
+  digits, and accounting parentheses wrapping symbol and digits together (`($5)`). Declared
+  with the flag off, the symbol is a `:malformed` `Fault` at the symbol; the flag with
+  nothing declared matches nothing.
+- `currency_decimal_sep:`, `currency_group_sep:` — the separators a currency amount is
+  written with, for a culture whose plain numbers and amounts differ (Swiss German writes
+  `1.234,5` and `CHF 1'234.50`). Read in place of the number separators when `CURRENCY` is
+  set, the symbol is declared, and the symbol is found in the text at either edge; each
+  `""` keeps its number counterpart. Under `SEPARATOR_DETECT`, detection governs the whole
+  token and these are ignored.
+- `minus_sign:`, `plus_sign:` — further spellings of the signs (`"−"`, U+2212, for Estonian
+  and Basque; `"＋"` fullwidth), read wherever ASCII `-`/`+` are: ahead of the digits, before
+  or after a leading currency symbol. Two signs are `:malformed` at the later one.
+- `TRAILING_SIGN` — permits the sign *after* the digits, the way a locale whose negative
+  pattern is `n-` writes it: `5-`, `5 -`, `5+`, `5 €-`, `5- €`, `2.5%-`, ASCII or
+  declared, once, never beside a leading sign nor inside parentheses. It is a flag, not a
+  symbol, and it is not in `ALL_STYLES`: `from_i18n` turns it on from the locale's own
+  `negative_format` rather than assuming it.
+- `percent:` — a further spelling of the percent symbol (`"٪"` in Arabic-script cultures,
+  `"％"` fullwidth), read as a trailing `%` is while `PERCENT` is set, on the real and
+  decimal doors; integer doors never read a percent.
+- `digit_zero:` — the culture's own digits, as their zero: `"٠"` (U+0660) declares the ten
+  Arabic-Indic digits, `"０"` the fullwidth ones. They are read beside ASCII `0`–`9`
+  everywhere digits are — integer part, fraction, exponent — and may be mixed with them;
+  radix-prefixed (`0x`, `0b`) digits stay ASCII.
 
 ```ruby
 dollars = HyperCast::NumFormat.new(decimal_sep: ".", group_sep: ",", flags: HyperCast::ALL_STYLES, currency: "$")
 HyperCast.i32("($1,234)", dollars)        # => Success(value: -1234)
 HyperCast.decimal("$1,234.50", dollars)   # => Success(value: Decimal(magnitude: 12345, scale: 1, negative: false))
 HyperCast.i32("$5", HyperCast::NumFormat::INVARIANT)   # => Fault(reason: :malformed, offset: 0, length: 1)
+
+estonian = HyperCast::NumFormat.new(decimal_sep: ",", group_sep: " ", flags: HyperCast::ALL_STYLES, minus_sign: "−")
+HyperCast.f64("−1 234,5", estonian)       # => Success(value: -1234.5)   (U+2212 minus; ASCII "-" still reads)
+
+francs = HyperCast::NumFormat.new(decimal_sep: ",", group_sep: ".", flags: HyperCast::ALL_STYLES | HyperCast::TRAILING_SIGN,
+                                  currency: "CHF", currency_decimal_sep: ".", currency_group_sep: "'")
+HyperCast.f64("CHF 1'234.50", francs)     # => Success(value: 1234.5)    (the currency separators, the symbol being present)
+HyperCast.f64("1.234,50", francs)         # => Success(value: 1234.5)    (the number separators)
+HyperCast.i32("5 CHF-", francs)           # => Success(value: -5)        (TRAILING_SIGN)
+
+arabic = HyperCast::NumFormat.new(decimal_sep: "٫", group_sep: "٬", flags: HyperCast::ALL_STYLES, percent: "٪", digit_zero: "٠")
+HyperCast.f64("١٬٢٣٤٫٥", arabic)          # => Success(value: 1234.5)
+HyperCast.decimal("٥٠٪", arabic)          # => Success(value: Decimal(magnitude: 5, scale: 1, negative: false))
 ```
 
-Across the ABI a `NumFormat` is a 32-byte struct — the two separators as code points, the
-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.
+A malformed field is an `ArgumentError` at construction, naming the field — the same
+caller-bug treatment equal separators have always had: an empty or over-long separator, an
+equal pair (the number pair, or the pair in force for currency amounts), a symbol carrying
+an ASCII digit, a sign, percent or currency symbol carrying ASCII whitespace, a currency
+symbol over 16 bytes, a digit zero that is ASCII or does not start a digit block. The
+limits are `NumFormat::SYMBOL_MAX_BYTES` (8) and `NumFormat::CURRENCY_MAX_BYTES` (16).
+
+Across the ABI a `NumFormat` is a 92-byte, size-tagged struct that the core reads in
+place — `NumFormat#packed` is exactly those bytes: the size word, the flags, the digit
+zero's code point, then each symbol's UTF-8 bytes and length held inline. It is packed
+once per format object and memoized by identity on every backend, so declaring a currency
+or a culture's digits costs a cast nothing.
+
+**What stays English: the boolean lexicon.** `bool` reads its twenty lexemes
+(`true`/`false`, `yes`/`no`, `on`/`off`, …) in English only. No platform carries culture
+data for boolean words, so there is no bridge that could fill them; a caller with a
+localized source maps its words before the door.
+
+### 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), `unit` (the currency symbol) and `negative_format` (where
+the sign goes). Every numeric door takes the first three 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)
+
+# A locale whose currency amounts use other separators than its numbers: both Hashes.
+swiss = HyperCast::NumFormat.from_i18n(I18n.t("number.format"), currency_format: I18n.t("number.currency.format"))
+HyperCast.f64("CHF 1'234.50", swiss)                                  # => Success(value: 1234.5)
+HyperCast.f64("1.234,50", swiss)                                      # => Success(value: 1234.5)
+```
+
+The keywords go through `NumFormat#override`, which is public: the result is validated like
+any `NumFormat`, and the flags and every other field 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` passed alone works as well. Missing keys keep the invariant's
+fields. An empty `delimiter` (a locale that writes no grouping) turns `GROUPING` off. A
+`negative_format` that writes the sign after the number (`"%n-"`, `"%n %u-"`) turns
+`TRAILING_SIGN` on; `"-%n"`, the Rails default, leaves it off. `currency_format:` takes
+`number.currency.format` beside `number.format`: its `separator` and `delimiter` become
+`currency_decimal_sep` and `currency_group_sep` (a key it lacks declares nothing, so the
+number separator stands in), its `unit` the currency symbol, and its `negative_format`
+counts the same way. `flags:` defaults to `ALL_STYLES`.
+
+That is everything the Hash offers. Rails carries no minus or plus sign, no percent symbol
+and no digits, so `from_i18n` leaves those undeclared — the core reads ASCII `-`, `+`, `%`
+and `0`–`9` — and a locale that writes them differently declares them on the result:
+`from_i18n(I18n.t("number.format")).with(minus_sign: "−")` for Estonian.
+
+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.
+
+### `datetime`: a culture's AM/PM
+
+The civil date-time door reads a 12-hour clock's `AM`/`PM` ASCII case-insensitively, after
+the clock (`3:04 PM`) or ahead of it (`PM 3:04`). `am:` and `pm:` declare a culture's own
+words beside the English ones — German's `vorm.`/`nachm.`, Korean's `오전`/`오후`
+(written ahead of the clock), Spanish's `a. m.`/`p. m.` (a space inside is fine) — matched
+exactly, with or without a space between word and clock. English is still read whatever is
+declared; `nil`, the default, declares nothing, so a call without the keywords is exactly
+the call it was. Like a `NumFormat`'s symbols the words are declared, never looked up:
+Ruby's stdlib has no day-period data, and `I18n.t("time.am")`/`("time.pm")` are where a
+Rails app finds them.
+
+```ruby
+HyperCast.datetime("1/7/2026 3:04 nachm.", :day_month_year, am: "vorm.", pm: "nachm.")
+# => Success(value: #<DateTime: 2026-07-01T15:04:00+00:00 ...>)
+HyperCast.datetime("2026-01-07 오후 3:04", :year_month_day, am: "오전", pm: "오후")
+# => Success(value: #<DateTime: 2026-01-07T15:04:00+00:00 ...>)
+HyperCast.datetime("1/7/2026 3:04 nachm.", :day_month_year)   # => Fault(reason: :malformed, offset: 13, length: 1)
+```
+
+A designator is 1 to 16 UTF-8 bytes with no ASCII digit and no ASCII whitespace at either
+end; anything else is an `ArgumentError`. Only `datetime` reads them — `date` has no time
+part. Across the ABI they are a 40-byte, size-tagged struct passed beside the order, null
+when nothing is declared. The designators are keywords, so they are read, validated and
+packed per call — the Fiddle backend packs them into its per-thread scratch — and a call
+that declares them costs about twice the plain call on the Magnus backend (the keyword
+scan is the cost: `am: nil, pm: nil` pays the same) and about half again on Fiddle.
+
+[^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
 
@@ -216,6 +355,12 @@ HyperCast::Interop.version(0x000700)                       # => "0.7.0"
    is now identity-matched like `INVARIANT`, and any other format is resolved once per
    thread and memoized by identity — anchored in a thread-variable so the memo's key can
    never be a recycled address — which turned the per-call cost into one pointer compare.
+
+   A declared currency symbol costs text that does not carry one about 6 ns on the Magnus
+   backend: in one run, `1,234,567` took 151 ns under `INVARIANT` and 157 ns under a format
+   declaring `$`. A fault costs more than a success: the same run returned the `Fault` for
+   `12345x7` in 222 ns, against 101 ns for `Integer("12345x7", exception: false)` returning
+   `nil`. The door builds a reason and a span where `Integer()` hands back nothing.
    The three reason Symbols and the option Symbols (`:seconds`, `:month_day_year`, …) are
    cached the same way, so a fault or a declared option is a pointer compare too, never a
    `Symbol#name` materialization.
@@ -347,7 +492,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

@@ -18,6 +18,7 @@ module HyperCast
     # 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]) }],
@@ -31,7 +32,7 @@ module HyperCast
 
     # 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, date: 4, date_ordered: 4,
+      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

data/lib/hypercast/runtime.rb

@@ -16,18 +16,19 @@ 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. 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.
+    # (text, len, out, fault), numeric adds the packed NumFormat pointer before out,
+    # declared a caller-declared u32 (precision, epoch, field order) in the same place, and
+    # civil the field order then the packed DayPeriods pointer (null for none). 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_date: :plain, cast_date_ordered: :declared, cast_datetime: :civil,
       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
@@ -114,6 +115,7 @@ module HyperCast
           plain: plain,
           numeric: plain.dup.insert(2, Fiddle::TYPE_VOIDP),
           declared: plain.dup.insert(2, Fiddle::TYPE_UINT32_T),
+          civil: plain.dup.insert(2, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP),
           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]
         }

data/lib/hypercast.rb

@@ -30,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.7.0"
+  VERSION = "0.9.0"
 
   # The success case of a verdict: a cast value.
   Success = Data.define(:value)
@@ -48,47 +48,202 @@ module HyperCast
 
   # Caller-declared numeric notation for the integer, real and decimal doors — declared out
   # loud (INVARIANT, or a literal), never defaulted, the same stance every binding takes.
-  # The currency symbol is the one field a culture table would fill in: it is declared
-  # here, never looked up, and honored only while the CURRENCY flag is set — declared with
-  # the flag off, the symbol is a :malformed Fault at the symbol, and the flag with no
-  # symbol ("" — the default) matches nothing. Equal separators, or a symbol longer than
-  # 16 UTF-8 bytes or carrying an ASCII digit or ASCII whitespace, are a caller bug
-  # (ArgumentError), never a verdict.
-  NumFormat = Data.define(:decimal_sep, :group_sep, :flags, :currency) do
-    # Validates the declared separators up front — single characters, and distinct from
-    # each other — and the currency symbol (a String of at most 16 UTF-8 bytes with no
-    # ASCII digit or ASCII whitespace, since those would collide with the digit scan and
-    # the trimming around the symbol), so a malformed format fails loudly as the caller bug
-    # it is. All three are stored transcoded to UTF-8, the encoding the core reads — a
-    # separator handed over in another encoding (a no-break space read from a Latin-1
-    # file, say) is the same code point on every backend rather than whatever its bytes
-    # happened to spell in the encoding it arrived in.
-    def initialize(decimal_sep:, group_sep:, flags:, currency: "")
-      raise ArgumentError, "separators must be single characters" unless
-        decimal_sep.is_a?(String) && decimal_sep.length == 1 &&
-        group_sep.is_a?(String) && group_sep.length == 1
-
-      decimal_sep = decimal_sep.encode(Encoding::UTF_8)
-      group_sep = group_sep.encode(Encoding::UTF_8)
+  # Past the separators and the flags, every field is one a culture table would fill in,
+  # and each is declared here, never looked up: the currency symbol; the separators a
+  # currency amount is written with (currency_decimal_sep, currency_group_sep — read in
+  # place of the number separators when the symbol is found in the text, each "" keeping
+  # its number counterpart); further spellings of the minus and plus signs and of the
+  # percent symbol; and the culture's own digits (digit_zero — the ten code points from
+  # that zero up, "٠" for the Arabic-Indic digits). A declared symbol is read *beside* its
+  # ASCII default, never instead of it — ASCII "-", "+", "%" and 0-9 are always read — so a
+  # format that declares nothing ("" everywhere; the default) reads exactly as the
+  # invariant culture, and nothing that parsed before stops parsing. The currency symbol is
+  # honored only while the CURRENCY flag is set — declared with the flag off, the symbol is
+  # a :malformed Fault at the symbol, and the flag with no symbol matches nothing — and the
+  # percent symbol while PERCENT is. A separator may be one or two characters (", " —
+  # comma, space — is a separator), up to 8 UTF-8 bytes. A malformed format is a caller bug
+  # (ArgumentError), never a verdict: an empty or over-long separator, equal separators (or
+  # an equal pair in force for currency amounts), a symbol carrying an ASCII digit, a sign
+  # or percent symbol carrying ASCII whitespace, a currency symbol longer than 16 bytes or
+  # carrying a digit or whitespace, or a digit zero that is ASCII or starts no digit block.
+  NumFormat = Data.define(:decimal_sep, :group_sep, :flags, :currency,
+                          :currency_decimal_sep, :currency_group_sep,
+                          :minus_sign, :plus_sign, :percent, :digit_zero) do
+    # Validates every declared field up front — the separators (1 to 8 UTF-8 bytes each,
+    # distinct from each other, and so the pair in force for currency amounts), the signs,
+    # the percent and currency symbols (no ASCII digit, since a digit is a digit before it
+    # is anything else, and no ASCII whitespace, which would collide with the trimming
+    # around them) and the digit zero (one non-ASCII character whose ten successors share
+    # its UTF-8 prefix, which every Unicode digit block's zero does) — so a malformed
+    # format fails loudly as the caller bug it is. Every field is stored transcoded to
+    # UTF-8, the encoding the core reads — a separator handed over in another encoding (a
+    # no-break space read from a Latin-1 file, say) is the same code point on every backend
+    # rather than whatever its bytes happened to spell in the encoding it arrived in.
+    def initialize(decimal_sep:, group_sep:, flags:, currency: "", currency_decimal_sep: "",
+                   currency_group_sep: "", minus_sign: "", plus_sign: "", percent: "", digit_zero: "")
+      limit = self.class::SYMBOL_MAX_BYTES
+      decimal_sep = declared("decimal separator", decimal_sep, limit, required: true)
+      group_sep = declared("group separator", group_sep, limit, required: true)
       raise ArgumentError, "decimal and group separators must differ; both are #{decimal_sep.inspect}" if
         decimal_sep == group_sep
-      raise ArgumentError, "currency symbol must be a String; got #{currency.inspect}" unless currency.is_a?(String)
 
-      symbol = currency.encode(Encoding::UTF_8)
-      limit = self.class::CURRENCY_MAX_BYTES
-      raise ArgumentError, "currency symbol #{currency.inspect} exceeds #{limit} UTF-8 bytes" if
-        symbol.bytesize > limit
-      raise ArgumentError, "currency symbol #{currency.inspect} must not contain an ASCII digit or whitespace" if
-        symbol.match?(/[0-9\t\n\f\r ]/)
+      currency_decimal_sep = declared("currency decimal separator", currency_decimal_sep, limit)
+      currency_group_sep = declared("currency group separator", currency_group_sep, limit)
+      money_decimal = currency_decimal_sep.empty? ? decimal_sep : currency_decimal_sep
+      money_group = currency_group_sep.empty? ? group_sep : currency_group_sep
+      raise ArgumentError, "currency decimal and group separators must differ; both are #{money_decimal.inspect}" if
+        money_decimal == money_group
+
+      super(decimal_sep: decimal_sep, group_sep: group_sep, flags: flags,
+            currency: declared("currency symbol", currency, self.class::CURRENCY_MAX_BYTES, flush: true),
+            currency_decimal_sep: currency_decimal_sep, currency_group_sep: currency_group_sep,
+            minus_sign: declared("minus sign", minus_sign, limit, flush: true),
+            plus_sign: declared("plus sign", plus_sign, limit, flush: true),
+            percent: declared("percent symbol", percent, limit, flush: true),
+            digit_zero: digit_zero_of(digit_zero))
+    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 (declarable, distinct separators; a declarable symbol),
+    # and the flags and every other field 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; the fields Rails has no word for (the signs, the percent
+    # symbol, the digits, the currency separators) are declared in the constructor or
+    # through Data#with.
+    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, :unit and :negative_format, 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. A negative_format that writes
+    # the sign after the number ("%n-", "%n %u-") turns TRAILING_SIGN on; "-%n", the Rails
+    # default, leaves it off. flags defaults to every lenience, the same as INVARIANT.
+    #
+    # currency_format: takes the locale's number.currency.format Hash beside number.format,
+    # for a column that mixes plain numbers and currency amounts in a locale whose two
+    # differ (the Swiss German franc, say — "1'234.50" beside "1.234,50"): its separator and
+    # delimiter become the currency separators, read in place of the number ones when the
+    # unit is found in the text, and its unit the currency symbol. A missing key there
+    # declares nothing, keeping the number separator it stands in for; an explicitly empty
+    # delimiter gets the same placeholder rule as above; its negative_format turns
+    # TRAILING_SIGN on the same way. Passed alone, number.currency.format reads as the one
+    # number format, as before.
+    #
+    # The rest of the format is what the Hash cannot offer: Rails carries no minus or plus
+    # sign, no percent symbol and no digits, so those stay undeclared here — the core reads
+    # ASCII "-", "+", "%" and 0-9 — and a locale that writes negatives with another sign
+    # (U+2212 for Estonian and Basque, for instance) declares it on the result with
+    # Data#with (minus_sign: "−"). Every lenience is on, radix prefixes and percent included;
+    # narrow flags: for anything stricter.
+    def self.from_i18n(number_format, currency_format: nil, flags: ALL_STYLES)
+      entries = i18n_entries(number_format)
+      separator = entries[:separator] || "."
+      delimiter = entries[:delimiter] || ","
+      if delimiter == ""
+        flags &= ~GROUPING
+        delimiter = separator == "," ? "." : ","
+      end
+      flags |= TRAILING_SIGN if trailing_sign?(entries[:negative_format])
+      currency = entries[:unit] || ""
+      currency_separator = currency_delimiter = ""
+      if currency_format
+        money = i18n_entries(currency_format)
+        currency = money[:unit] || currency
+        currency_separator = money[:separator] || ""
+        currency_delimiter = money[:delimiter] || ""
+        currency_delimiter = (money[:separator] || separator) == "," ? "." : "," if money[:delimiter] == ""
+        flags |= TRAILING_SIGN if trailing_sign?(money[:negative_format])
+      end
+      new(decimal_sep: separator, group_sep: delimiter, flags: flags, currency: currency,
+          currency_decimal_sep: currency_separator, currency_group_sep: currency_delimiter)
+    end
 
-      super(decimal_sep: decimal_sep, group_sep: group_sep, flags: flags, currency: symbol)
+    # The I18n Hash's entries under Symbol keys, whatever keys it arrived with.
+    def self.i18n_entries(number_format)
+      raise ArgumentError, "expected a Hash-like number format; got #{number_format.inspect}" unless
+        number_format.respond_to?(:to_h)
+
+      number_format.to_h.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
     end
+    private_class_method :i18n_entries
+
+    # Whether an I18n negative_format ("-%n", "%n-", "-%u%n", "%n %u-") writes the sign
+    # after the number: a "-" to the right of the "%n" placeholder.
+    def self.trailing_sign?(negative_format)
+      return false unless negative_format.is_a?(String)
 
-    # 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.
+      number = negative_format.index("%n")
+      sign = negative_format.rindex("-")
+      !number.nil? && !sign.nil? && sign > number
+    end
+    private_class_method :trailing_sign?
+
+    # The 92-byte little-endian form of the native ABI's size-tagged NumFormat struct, the
+    # layout the core reads in place: the size word (92), the flags, the digit zero's code
+    # point (0 for none), then each symbol as its UTF-8 bytes zero-padded to its field
+    # followed by its byte length — eight bytes and a length for each of the two number
+    # separators, the two currency separators, the two signs and the percent symbol, in
+    # that order; sixteen and a length for the currency symbol. A length of 0 declares
+    # nothing.
     def packed
-      [decimal_sep.ord, group_sep.ord, flags, currency.bytesize].pack("L<L<L<L<") + [currency].pack("a16")
+      head = [self.class::PACKED_BYTES, flags, digit_zero.empty? ? 0 : digit_zero.ord].pack("L<L<L<")
+      symbols = [decimal_sep, group_sep, currency_decimal_sep, currency_group_sep, minus_sign, plus_sign, percent]
+      head + symbols.map { |symbol| [symbol, symbol.bytesize].pack("a8C") }.join +
+        [currency, currency.bytesize].pack("a16C")
+    end
+
+    private
+
+    # The declared text of one field as the UTF-8 the core reads: a String of 1 to `limit`
+    # UTF-8 bytes with no ASCII digit — nor, for a symbol that sits flush against the
+    # digits (the signs, the percent and currency symbols), any ASCII whitespace — or ""
+    # where the field may be left undeclared. Anything else is the caller bug it names.
+    def declared(field, text, limit, flush: false, required: false)
+      raise ArgumentError, "#{field} must be a String; got #{text.inspect}" unless text.is_a?(String)
+
+      symbol = text.encode(Encoding::UTF_8)
+      if symbol.empty?
+        raise ArgumentError, "#{field} must not be empty" if required
+
+        return symbol
+      end
+      raise ArgumentError, "#{field} #{text.inspect} exceeds #{limit} UTF-8 bytes" if symbol.bytesize > limit
+
+      if flush
+        raise ArgumentError, "#{field} #{text.inspect} must not contain an ASCII digit or whitespace" if
+          symbol.match?(/[0-9\t\n\f\r ]/)
+      elsif symbol.match?(/[0-9]/)
+        raise ArgumentError, "#{field} #{text.inspect} must not contain an ASCII digit"
+      end
+      symbol
+    end
+
+    # The declared digit zero as UTF-8: "" for none, else exactly one character that is not
+    # ASCII and whose code point modulo 64 is at most 54 — true of the zero of every decimal
+    # digit block Unicode defines, and the shape the core recognises a digit by its last
+    # byte from.
+    def digit_zero_of(text)
+      raise ArgumentError, "digit zero must be a String; got #{text.inspect}" unless text.is_a?(String)
+
+      zero = text.encode(Encoding::UTF_8)
+      return zero if zero.empty?
+
+      raise ArgumentError, "digit zero #{text.inspect} must be one non-ASCII character that starts a digit block" unless
+        zero.length == 1 && zero.ord >= 0x80 && zero.ord % 64 <= 54
+
+      zero
     end
   end
 
@@ -97,6 +252,13 @@ module HyperCast
   # is scoped lexically, and landed on HyperCast instead of on NumFormat.
   NumFormat::CURRENCY_MAX_BYTES = 16
 
+  # The widest separator, sign or percent symbol the native ABI carries inline, in UTF-8
+  # bytes: one or two characters of any script.
+  NumFormat::SYMBOL_MAX_BYTES = 8
+
+  # The size of NumFormat#packed — the native ABI's size-tagged NumFormat layout — in bytes.
+  NumFormat::PACKED_BYTES = 92
+
   # Permit the group separator between digits (sizes not validated — between digits is the rule).
   GROUPING = 1
   # Permit accounting parentheses as negation: (1,234) is -1234.
@@ -105,7 +267,8 @@ module HyperCast
   EXPONENT = 1 << 2
   # Permit 0x/&H/0b two's-complement radix prefixes (0xFF is -1 for an i8).
   RADIX_PREFIXES = 1 << 3
-  # Permit a trailing %, dividing by 100. Real and decimal doors only.
+  # Permit a trailing % (or the format's declared percent symbol), dividing by 100. Real
+  # and decimal doors only.
   PERCENT = 1 << 4
   # Resolve the ./, roles per input from structure instead of the declared separators
   # (which are ignored while this flag is set). Detection, not sniffing: a repeated
@@ -121,8 +284,15 @@ module HyperCast
   # along with the digits ("($5)"). With no symbol declared the flag matches nothing.
   # Integer, real and decimal doors.
   CURRENCY = 1 << 6
-  # Every lenience on (SEPARATOR_DETECT is a separator policy, not a lenience, and is
-  # deliberately not included).
+  # Permit the sign after the digits ("5-", "5 -", "5 €-", "5- €"), the way a locale whose
+  # negative_format is "%n-" writes it: ASCII - and + or the format's declared signs, once,
+  # with optional ASCII whitespace before it, and never beside a leading sign or inside
+  # accounting parentheses. Not part of ALL_STYLES — NumFormat.from_i18n sets it from the
+  # locale's own negative_format rather than assuming it.
+  TRAILING_SIGN = 1 << 7
+  # Every lenience on — every one there was before TRAILING_SIGN, which is declared from a
+  # locale's pattern rather than assumed (SEPARATOR_DETECT is a separator policy, not a
+  # lenience, and is deliberately not included either).
   ALL_STYLES = GROUPING | PARENTHESES | EXPONENT | RADIX_PREFIXES | PERCENT | CURRENCY
 
   # The invariant profile — '.' decimal, ',' grouping, every lenience on, no currency
@@ -220,6 +390,14 @@ module HyperCast
       plain(:cast_bool, text, 1) { |out| Interop.decode(:bool, out) }
     end
 
+    # 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)
@@ -228,20 +406,29 @@ module HyperCast
       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)
+    # 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)
+    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
 
@@ -251,7 +438,9 @@ 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)
+    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
 
@@ -310,8 +499,21 @@ module HyperCast
     # artifact, not data (the same caveat PHP's UTC-labeled DateTimeImmutable carries);
     # 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) { |out| Interop.decode(:datetime, out) }
+    #
+    # A 12-hour clock's AM/PM is read, before or after the clock ("3:04 PM", "PM 3:04"),
+    # ASCII case-insensitively; am: and pm: declare a culture's own designators beside
+    # them — "vorm."/"nachm.", "오전"/"오후", "a. m."/"p. m." — matched exactly, after the
+    # clock ("3:04 nachm.") or ahead of it ("오후 3:04"), with or without a space between.
+    # Declared, never looked up, like a NumFormat's symbols; nil (the default) declares
+    # nothing, so a call without them is exactly the call it was. A designator is 1 to 16
+    # UTF-8 bytes with no ASCII digit and no ASCII whitespace at either end (a space inside
+    # is fine); anything else is a caller bug (ArgumentError). The designators are read,
+    # validated and packed per call: a call that declares them costs about twice the plain
+    # call on the Magnus backend (the keyword scan itself — nil keywords pay the same) and
+    # about half again here on Fiddle.
+    def datetime(text, order, am: nil, pm: nil)
+      periods = packed_day_periods(am, pm) if am || pm
+      civil(:cast_datetime, text, DATE_ORDERS.fetch(order), periods, 16) { |out| Interop.decode(:datetime, out) }
     end
 
     # Casts an ISO 24-hour time-of-day to an exact Integer of nanoseconds since midnight
@@ -391,18 +593,19 @@ module HyperCast
       bytes.empty? ? nil : bytes
     end
 
-    # One 24-byte scratch allocation per thread, reused by every call: out-value at 0
+    # One 64-byte scratch allocation per thread, reused by every call: out-value at 0
     # (16 bytes covers every door, and malloc's alignment covers the decimal's 8), fault
-    # span at 16. Two Fiddle::Pointer.malloc(..., RUBY_FREE) calls per cast — each
-    # registering a GC finalizer — measured as the dominant per-call cost by an order of
-    # magnitude. The NumFormat no longer lives here: each format owns its own packed
-    # pointer (see packed_cache), so a numeric call copies nothing into scratch before
-    # crossing. Allocated through Runtime.buffer, which loads the library first, so a
-    # missing one is reported as such before Fiddle is touched.
+    # span at 16, and the datetime door's packed day periods at 24 (40 bytes, 4-aligned,
+    # written only by a call that declares them). Two Fiddle::Pointer.malloc(..., RUBY_FREE)
+    # calls per cast — each registering a GC finalizer — measured as the dominant per-call
+    # cost by an order of magnitude. The NumFormat does not live here: each format owns
+    # its own packed pointer (see packed_cache), so a numeric call copies nothing into
+    # scratch before crossing. Allocated through Runtime.buffer, which loads the library
+    # first, so a missing one is reported as such before Fiddle is touched.
     def scratch
       Thread.current[:hypercast_scratch] ||= begin
-        base = Runtime.buffer(24)
-        [base, base + 16]
+        base = Runtime.buffer(64)
+        [base, base + 16, base + 24]
       end
     end
 
@@ -428,7 +631,7 @@ module HyperCast
     end
 
     # The shared body of the integer/real/decimal doors: plain, plus the format's own
-    # packed pointer, passed straight through — no per-call copy of the 32 bytes into
+    # packed pointer, passed straight through — no per-call copy of the 92 bytes into
     # scratch.
     def numeric(symbol, text, format, out_size)
       bytes = utf8(text)
@@ -437,6 +640,47 @@ module HyperCast
       verdict(rc, fault, bytes) { yield(out[0, out_size]) }
     end
 
+    # The civil date-time door's body: declared, plus the day periods after the order — the
+    # 40 packed bytes copied into this thread's scratch and passed from there, or nil
+    # (Fiddle's null) when none are declared, which the core reads as English AM/PM only.
+    def civil(symbol, text, code, periods, out_size)
+      bytes = utf8(text)
+      out, fault, slot = scratch
+      if periods
+        slot[0, periods.bytesize] = periods
+      else
+        slot = nil
+      end
+      rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, code, slot, out, fault)
+      verdict(rc, fault, bytes) { yield(out[0, out_size]) }
+    end
+
+    # The 40-byte little-endian form of the native ABI's size-tagged DayPeriods struct: the
+    # size word (40), then each designator as its UTF-8 bytes zero-padded to 16 followed by
+    # its byte length — am, then pm — and two bytes of padding. A nil designator is a
+    # length of 0: nothing declared beside AM or PM.
+    def packed_day_periods(am, pm)
+      am = designator("am", am)
+      pm = designator("pm", pm)
+      [40].pack("L<") + [am, am.bytesize, pm, pm.bytesize].pack("a16Ca16C") + "\0\0"
+    end
+
+    # A declared day-period designator as the UTF-8 the core reads — 1 to 16 bytes, no
+    # ASCII digit, no ASCII whitespace at either end (the grammar around it reads that) —
+    # or "" for nil. Anything else is the caller bug it names, the same ArgumentError on
+    # every backend.
+    def designator(name, text)
+      return "" if text.nil?
+      raise ArgumentError, "#{name} designator must be a String; got #{text.inspect}" unless text.is_a?(String)
+
+      designator = text.encode(Encoding::UTF_8)
+      unless designator.bytesize.between?(1, 16) && !designator.match?(/[0-9]|\A[\t\n\f\r ]|[\t\n\f\r ]\z/)
+        raise ArgumentError, "#{name} designator #{text.inspect} must be 1 to 16 UTF-8 bytes with no ASCII digit " \
+                             "and no ASCII whitespace at either end"
+      end
+      designator
+    end
+
     # The shared body of the four doors that take a caller-declared u32 — a precision, an
     # epoch, or a field order — already resolved from its Symbol by the door. These bodies
     # (plain, numeric, declared, and packed_version below) are the whole Fiddle crossing.
@@ -487,21 +731,22 @@ module HyperCast
     PACKED_CACHE_LIMIT = 64
 
     # Identity-keyed memo (compare_by_identity — a pointer hash, not Data's structural
-    # #hash over three Strings and an Integer) of a native 32-byte RawNumFormat per format
+    # #hash over nine Strings and an Integer) of a native 92-byte RawNumFormat per format
     # object, filled once from NumFormat#packed. Formats are reused constants in practice,
     # so the common call finds its pointer in one lookup and packs nothing. The Hash holds
     # the format, so a key can never be a recycled address; the race is benign (idempotent).
     #
     # Bounded, oldest entry out first (a Hash keeps insertion order): unbounded, it held
-    # every format ever cast with and its 32-byte allocation for the life of the process,
+    # every format ever cast with and its 92-byte allocation for the life of the process,
     # which a consumer building a format per request experienced as a leak. A format
     # evicted and then used again is simply packed again, and an evicted pointer stays
     # alive for any call already holding it — the caller's own reference outlives the cache's.
     def packed_cache
       @packed_cache ||= Hash.new do |cache, format|
         cache.shift while cache.size >= PACKED_CACHE_LIMIT
-        pointer = Runtime.buffer(32)
-        pointer[0, 32] = format.packed
+        size = NumFormat::PACKED_BYTES
+        pointer = Runtime.buffer(size)
+        pointer[0, size] = format.packed
         cache[format] = pointer
       end.compare_by_identity
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hypercast-wasm
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Brian Buvinghausen