hypercast 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8da896d32dfcc062ba70735385c985f5a99ba957bb33d22c8ad0cda13d7921b4
-  data.tar.gz: 49bbe35c6755ed52f2ba7ef3538e33759e54cda9d92069fc87393a0555763200
+  metadata.gz: eaba9476c698240d6ef0a3ac0a98b11030a016740972914e2f3c13b3aa05d203
+  data.tar.gz: 536c6ba3793ad95387972a08eebaf010ab4bad460a89d3b7f4cdde6252a877c0
 SHA512:
-  metadata.gz: ed56bbe6e07f38e2a358e320dc8c8b1a88cf091e11ba34931b2df087c6ca813be2bd8d42bcc70c26376cfe9e291d5f1632097b16a8d292a23f5ce74930f29c16
-  data.tar.gz: 04bc0358dce246eefb0f3d952eeb8a655ade6eeaf652b929298f5a3acc78b262f6c0d5c2be6e66c2f0eb537db227cbd63ba8ef975610caaedbee4f19c4f2e630
+  metadata.gz: e1188eefa9d4b79d00fa93dbf18c7e0b81377c9e9c5006a0a141c8dcff53b5ab8b7521f1d2411e9474f07b46e563c0f2075db57ad7234a10d3cfdb77e56bd0d6
+  data.tar.gz: 5136f110fd9356546c15174aa5fa667300d7ba29cc34daa4c62132c01e1e60cd1fbb00402cffeb58a30faf9120e568f75c44eafd1315d8d81e4042d6d9bcec7f

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` |
@@ -65,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
@@ -160,6 +162,38 @@ 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:
@@ -347,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

@@ -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

@@ -21,7 +21,7 @@ module HyperCast
     # 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,

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.8.0"
 
   # The success case of a verdict: a cast value.
   Success = Data.define(:value)
@@ -84,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.
@@ -220,6 +264,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, A or A — 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 +280,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 +312,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
 

metadata

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