hypercast 1.0.0-aarch64-linux-gnu → 1.1.0-aarch64-linux-gnu

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 666f68990de3812651e057a35d44aa42e6ee617ebb20b8504472444f2d409d6f
4
- data.tar.gz: 913752abbe323b82afecd6e914ff8f8db698baadf05b37f9d0dbf1138e8468fd
3
+ metadata.gz: bb326eec4ca49a68216e4a256a20dbae17cdee8915e30525464666914762c6fc
4
+ data.tar.gz: 20d0ea573f4512e5aa6604d75319d7fdbde8c3fb97b03358961fdd2d2e8372c9
5
5
  SHA512:
6
- metadata.gz: 7f0e536d1a06603bc0304f2961f5ac37b78f3f61afb5549052f52d59f779d377a2ec85d85e7746758a0f156cb32ee86b87ad236d492b1a08e2ec928d43f8c0e6
7
- data.tar.gz: 5c112b5d763efba33cb27c17fa9fc9e57cfec7088a11518d6c45f95790ee1cda9ca93db438548e12bdebb4194b07540ed99fc65c2f494ba3296108c986dac840
6
+ metadata.gz: 491a237f766540a5a711e5b39c5321bd3314ffee5700060a6293a15759438e4e14bd8d1ace19599fb90205eb69db4e985ac8c51e4820f21d5597ca8403fcc09e
7
+ data.tar.gz: bb6a412ef9e63ae2143f37fb0a315d86adb591874cb62b8d7e509a3b1c0a8e5dae39fc779cb7f36235e353b0dc3cc215cabdbbb00779337ab0b6bf9f6d44f2cf
data/LICENSE-UNICODE ADDED
@@ -0,0 +1,39 @@
1
+ UNICODE LICENSE V3
2
+
3
+ COPYRIGHT AND PERMISSION NOTICE
4
+
5
+ Copyright © 1991-2026 Unicode, Inc.
6
+
7
+ NOTICE TO USER: Carefully read the following legal agreement. BY
8
+ DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
9
+ SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
10
+ TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
11
+ DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
12
+
13
+ Permission is hereby granted, free of charge, to any person obtaining a
14
+ copy of data files and any associated documentation (the "Data Files") or
15
+ software and any associated documentation (the "Software") to deal in the
16
+ Data Files or Software without restriction, including without limitation
17
+ the rights to use, copy, modify, merge, publish, distribute, and/or sell
18
+ copies of the Data Files or Software, and to permit persons to whom the
19
+ Data Files or Software are furnished to do so, provided that either (a)
20
+ this copyright and permission notice appear with all copies of the Data
21
+ Files or Software, or (b) this copyright and permission notice appear in
22
+ associated Documentation.
23
+
24
+ THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
25
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
26
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
27
+ THIRD PARTY RIGHTS.
28
+
29
+ IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
30
+ BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
31
+ OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
32
+ WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
33
+ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
34
+ FILES OR SOFTWARE.
35
+
36
+ Except as contained in this notice, the name of a copyright holder shall
37
+ not be used in advertising or otherwise to promote the sale, use or other
38
+ dealings in these Data Files or Software without prior written
39
+ authorization of the copyright holder.
data/README.md CHANGED
@@ -12,17 +12,24 @@ resort everywhere else — selected automatically, zero compiles either way.**
12
12
  Allocation-lean scalar casts — booleans, characters, the full integer family, reals, exact
13
13
  decimals, UUIDs, temporals — calling directly into the native `libhypercast` Rust core. Ruby 3.3 is the
14
14
  floor. The fast path links the core straight into a Ruby extension (Magnus): on require it
15
- redefines the doors in place on the `HyperCast` module — no delegation layer, no second
16
- surface, which is exactly what keeps the backends provably in agreement.
15
+ defines the doors on the `HyperCast` module in front of the Fiddle ones — no delegation layer,
16
+ no second surface, which is exactly what keeps the backends provably in agreement.
17
17
  The last-resort fallback, in the universal gem only, calls the native `libhypercast` shared
18
18
  library via [`Fiddle`](https://docs.ruby-lang.org/en/master/Fiddle.html) — dlopen/dlsym plus
19
19
  raw C-ABI calls, no runtime bridge. `HyperCast::BACKEND` reports which one is live;
20
20
  `HYPERCAST_PURE=1` forces Fiddle for testing — see [Backends](#backends).
21
21
 
22
22
  ```ruby
23
+ require "hypercast"
24
+
23
25
  case HyperCast.i32("(1,234)", HyperCast::NumFormat::INVARIANT)
24
- in HyperCast::Success(value:) then puts "got #{value}" # -1234
25
- in HyperCast::Fault(reason:, offset:) then puts "#{reason} at #{offset}"
26
+ in HyperCast::Success(value:) then puts "got #{value}" # -1234
27
+ in HyperCast::Fault(reason:, offset:) then puts "#{reason} at char #{offset}"
28
+ end
29
+
30
+ case HyperCast.timestamp("2026-01-02T15:04:05.123456789+05:00")
31
+ in HyperCast::Success(value:) then puts "timestamp #{value.inspect}" # a UTC Time, full nanoseconds
32
+ in HyperCast::Fault(reason:, offset:) then puts "#{reason} at char #{offset}"
26
33
  end
27
34
  ```
28
35
 
@@ -44,23 +51,41 @@ midnight, durations come back as exact `Rational` seconds across the core's whol
44
51
  | `f32` `f64` `(text, format)` [^overrides] | `Float` (f32 widened losslessly) | a `NumFormat` |
45
52
  | `decimal(text, format)` [^overrides] | `HyperCast::Decimal` — exact sign, 96-bit magnitude, base-10 scale | a `NumFormat` |
46
53
  | `uuid(text)` | lowercase hyphenated `String` (`SecureRandom.uuid`'s shape) | — |
47
- | `timestamp(text)` | UTC `Time`, full nanoseconds | — |
54
+ | `timestamp(text, options: nil)` | UTC `Time`, full nanoseconds | optionally a `DateOptions` — see [Date shapes](#date-shapes-dateoptions-and-monthnames) |
48
55
  | `unix(text, precision)` | UTC `Time` | `:seconds` / `:milliseconds` / `:microseconds` / `:nanoseconds` |
49
56
  | `excel_serial(text, epoch)` | UTC `Time` | `:y1900` / `:y1904` |
50
- | `date(text, order = nil)` | `Date` | strict ISO, or `:year_month_day` / `:month_day_year` / `:day_month_year` |
51
- | `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) |
57
+ | `date(text, order = nil, options: nil, months: nil)` | `Date` | strict ISO, or `:year_month_day` / `:month_day_year` / `:day_month_year`; optionally a `DateOptions` and `MonthNames` — see [Date shapes](#date-shapes-dateoptions-and-monthnames) |
58
+ | `datetime(text, order, am: nil, pm: nil, options: nil, months: 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) — and a `DateOptions` and `MonthNames` |
52
59
  | `time(text)` | `Integer` nanoseconds since midnight | — |
53
60
  | `duration(text)` | exact `Rational` seconds | — |
54
61
  | `decimal_from_float(value)` | `HyperCast::Decimal`, the shortest that names the number (`0.1` is one tenth) | — |
55
62
  | `excel_serial_from_float(value, epoch)` | zone-less `DateTime`, as `datetime` | `:y1900` / `:y1904` |
56
63
  | `excel_time(value)` | `Integer` nanoseconds since midnight | — |
57
64
  | `excel_duration(value)` | exact `Rational` seconds | — |
58
-
59
- Every door returns a `Success` or a `Fault`; `HyperCast.optional(verdict)` folds `:empty`
60
- to `nil`. Beside the doors, `native_version` returns the loaded core's
65
+ | `text(text)` | the text itself as a `String`, once it is valid UTF-8 (the `String` passed when it is UTF-8, or US-ASCII holding only ASCII, else a UTF-8 copy) | — |
66
+ | `text(text, constraints)` | a checked verdict over the text — see [Validation constraints](#validation-constraints) | a `Constraints` for `:text` |
67
+ | `checked(text, format, constraints)` [^overrides] | a checked verdict over the value the constraints' door reads — see [Validation constraints](#validation-constraints) | a `NumFormat` and a `Constraints` |
68
+ | `checked_from_float(value, constraints)` | a checked verdict over a number already held | a `Constraints` |
69
+
70
+ White space is Unicode's `White_Space`, the 25 code points (ASCII, U+0085, U+00A0, U+2000 to
71
+ U+200A, U+202F, U+3000 among them). Every door but plain `text` ignores it at both ends (`char` given exactly one character keeps it), and the
72
+ numeric doors also after a leading sign, before a trailing sign or a percent symbol, on either
73
+ side of a currency symbol and inside accounting parentheses (`"- 12"`, `"( 12 )"`, `"12,5 %"`,
74
+ `"1 234,56 €"`, the last two under a declared comma decimal separator, the last with a space group separator and `€` declared); between digits it is `:malformed`, unless a space-like group separator is
75
+ declared. An ASCII space, U+00A0 or U+202F declared as the group separator makes the input's
76
+ choice of those three immaterial (Excel writes U+00A0, ICU's `fr` U+202F, an older system a
77
+ space), a space-like separator with no digit after it is just white space, and any other
78
+ separator stays exact. Input of nothing but white space is `:empty`.
79
+
80
+ Every plain door returns a `Success` or a `Fault`, and every checked door a `Checked`, a
81
+ `Fault` or a `Violation`; `HyperCast.optional(verdict)` folds `:empty` to `nil` for
82
+ either, and passes every other rejection, a `Violation` included, through. Beside the doors, `native_version` returns the loaded core's
61
83
  `"major.minor.patch"` and `available?` answers `true`/`false` without ever raising — see
62
84
  [Is the native core there?](#is-the-native-core-there).
63
85
 
86
+ Every `Fault` a door returns carries `detail`, what exactly was wrong, beside the broad
87
+ reason — see [Fault detail](#fault-detail).
88
+
64
89
  ### Errors
65
90
 
66
91
  Bad data is never an exception — it is a `Fault`. What raises is a caller bug, and it raises
@@ -70,17 +95,46 @@ the same exception on every backend:
70
95
  `delimiter:` and `unit:` keywords) or `NumFormat.from_i18n` for a malformed format: a
71
96
  separator that is empty, longer than 8 UTF-8 bytes or not distinct from its partner
72
97
  (the pair in force for currency amounts included), any symbol carrying an ASCII digit, a
73
- sign, percent or currency symbol carrying ASCII whitespace, a currency symbol longer than
74
- 16 bytes, or a digit zero that is ASCII or starts no digit block. And from `datetime` for
98
+ sign, percent symbol or decimal separator carrying white space, a currency symbol longer
99
+ than 16 bytes or starting or ending in white space (inside it white space is fine, as in
100
+ `F CFA`), or a digit zero that is ASCII or starts no digit block, `flags:` that is not an
101
+ `Integer` of bits 0 to 7 (a grouping policy belongs in `grouping:`, not in the mask) and a
102
+ `grouping:` that is not `:western` or `:indian`. And from `DateOptions.new` for
103
+ flags this version does not define or a pivot outside 100 to 9999, and from `MonthNames` for
104
+ a vocabulary that breaks a rule. And from `datetime` for
75
105
  a day-period designator that is empty, longer than 16 bytes, carries an ASCII digit or
76
- starts or ends in ASCII whitespace.
106
+ starts or ends in white space.
77
107
  - `KeyError` — `Hash#fetch`'s own, `key not found: …` — for a precision, epoch or date order
78
108
  that names nothing: an unknown Symbol, or anything that is not a Symbol (`"seconds"`
79
109
  included). `date(text, nil)` is not one of these: an explicit `nil` order is the strict ISO
80
110
  door, exactly as if it were left off.
81
- - `TypeError` for text that is not a `String` (anything with `to_str` is taken as one).
82
- - `String#encode`'s own `Encoding::` error for text in another encoding that cannot be
83
- transcoded to UTF-8.
111
+ - `ArgumentError` from `Constraints.new` (and `Constraints#with`) for a declaration the core
112
+ refuses, worded from its code — `Constraints refused (code 5): multipleOf is not
113
+ positive.` — and for a keyword of the wrong type: a `Float`, `true` or `false` bound, a
114
+ length that is not an `Integer` from 0 to 2³² − 1, a `trim` or `case_sensitive` that is not
115
+ `true` or `false`, an `enum` that is not a list or a text entry that is not a `String`. Also from
116
+ `checked`, `checked_from_float` and `text` for constraints bound to the other kind of door,
117
+ and from `declared_decimal` for text it cannot convert (code 8). `KeyError` for a door or a
118
+ rounding that names nothing.
119
+ - `TypeError` for text that is not a `String` (anything with `to_str` is taken as one), and
120
+ for constraints that are not a `Constraints`.
121
+
122
+ Text in another encoding that cannot be transcoded to UTF-8 (a lone UTF-16 surrogate, bytes
123
+ its encoding does not allow, such as a byte past 0x7F in a US-ASCII `String`, a character
124
+ with no Unicode counterpart, any character past ASCII in an encoding Ruby has no converter to
125
+ UTF-8 for, such as EUC-TW) is data, not an exception: every door, plain or checked, judges
126
+ it `:malformed` at that character, on both backends, never with a replacement standing for it;
127
+ as an `enum` entry it is refused as an entry that is not UTF-8 (code 9); and as a `NumFormat`
128
+ symbol or a day-period designator it is the caller's bug, an `ArgumentError` naming the field
129
+ ("currency symbol ... must be whole characters with a UTF-8 form"), on both backends.
130
+
131
+ A dummy encoding (`UTF-16` and `UTF-32` with their byte-order mark, `ISO-2022-JP`, `UTF-7`)
132
+ is held to the same rule. Ruby cannot split its text into characters (its `String` counts
133
+ bytes), so the text is transcoded whole, each conversion error judged `:malformed` as one
134
+ character, and a span counts the characters of its UTF-8 form:
135
+ `text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)[offset, length]` is the
136
+ offending text. A dummy encoding with no converter to UTF-8 at all (`UTF-7`,
137
+ `ISO-2022-JP-2`) is `:malformed` at its first byte.
84
138
 
85
139
  ### Is the native core there?
86
140
 
@@ -89,7 +143,9 @@ binding was built against — probed once, cached, never raising — for a consu
89
143
  fallback of its own:
90
144
 
91
145
  ```ruby
92
- value = HyperCast.available? ? HyperCast.i32(text, format) : my_own_parse(text)
146
+ def parse(text)
147
+ HyperCast.available? ? HyperCast.i32(text, HyperCast::NumFormat::INVARIANT) : my_own_parse(text)
148
+ end
93
149
  ```
94
150
 
95
151
  `HyperCast.native_version` reads the version out of the loaded core itself (its
@@ -105,8 +161,8 @@ gem, which carries no Fiddle library, that `LoadError` names the universal gem i
105
161
  ### Fault spans index the String you passed
106
162
 
107
163
  A `Fault`'s `offset`/`length` are in the units `String#[]` slices by on your own input:
108
- character offsets for text — in any encoding; the core reads UTF-8, and the span is mapped
109
- back, an identity for ASCII — and byte offsets for a binary (`ASCII-8BIT`) String, whose
164
+ character offsets for text — in any encoding but a dummy one (above); the core reads UTF-8,
165
+ and the span is mapped back, an identity for ASCII — and byte offsets for a binary (`ASCII-8BIT`) String, whose
110
166
  characters are its bytes. Either way `text[offset, length]` is the offending text with no
111
167
  arithmetic on your side:
112
168
 
@@ -144,6 +200,30 @@ deliberately not a dependency of this one, so under Bundler add it to your own G
144
200
  HyperCast::NumFormat.new(decimal_sep: ".", group_sep: ",", flags: HyperCast::ALL_STYLES, currency: "$")
145
201
  ```
146
202
 
203
+ **Grouping is a policy**, declared apart from the flags with `grouping:`. The default,
204
+ `:western`, reads a numeral that uses the group separator as groups of exactly three digits
205
+ counted from the decimal separator (or the numeral's end), the leftmost one to three:
206
+ `1,234,567` reads, and `12,34` is a `:malformed` `Fault` spanning the bad group with its
207
+ separator (`,34`) and the detail `Detail::GROUP_SIZE`. Under every policy a first group
208
+ can't start with a zero: `0,125` is the same fault, spanning `0`. `:indian` reads lakh and crore (`12,34,567`:
209
+ three beside the decimal separator, two in each group to its left, the leftmost one or two),
210
+ and refuses `1,234,567`, where Western refuses `1,23,456`. An ungrouped
211
+ numeral reads under both, grouping never follows the decimal separator or an exponent,
212
+ digits count as digits (native ones included), and a policy only judges groups: without the
213
+ `GROUPING` flag a group separator stays refused. `INVARIANT` and `DETECT` are Western,
214
+ `#with(grouping: …)` and `#override` keep the policy of the format they start from, and
215
+ `from_i18n` takes `grouping:` too (a Rails locale Hash says nothing about it). The policy is
216
+ not a member of `NumFormat`, as `detail` is not of `Fault`: the ten members, `to_h`, `inspect`,
217
+ the constructors, and array and hash patterns leave the policy out, `grouping` is a reader that a pattern
218
+ can name (`in { grouping: :indian }`), and it counts in `==`, `eql?` and `hash`. A `NumFormat`
219
+ loaded from a 1.0 Marshal payload carries none and is `:western`. Marshal restores such a payload with no call this class can hook, so a flags word holding the retired bit 8 (`351`) is refused with `ArgumentError` on its first use. Because it is not a member, `grouping:` is keyword-only: `NumFormat.new` takes the ten
220
+ members positionally or by keyword, but `Data.new` cannot mix positional members with keywords, so the policy is
221
+ never the eleventh positional argument.
222
+ Across the ABI the policy rides in the flags word (`GROUPING_WESTERN` is 0, `GROUPING_INDIAN` is 512; bit 8, 256, is
223
+ retired permanently and never reused, so 256 and 768 are refused), and the Fiddle
224
+ backend refuses a core older than 1.1 as it loads, naming it: a 1.0 core would read `1,23,456` as 123456
225
+ without a word. A shape neither policy reads is a `Fault` under a declared format, `INVARIANT` or a bridge, never misread, while `NumFormat::DETECT` infers by the delimiter rule, so `1,2345` is 1.2345 there: [docs/grouping.md](https://github.com/SkunkWerkx/HyperCast/blob/master/docs/grouping.md#parked).
226
+
147
227
  The flags are `GROUPING`, `PARENTHESES`, `EXPONENT`, `RADIX_PREFIXES`, `PERCENT` and
148
228
  `CURRENCY` (`ALL_STYLES` is all six), plus `TRAILING_SIGN` — deliberately not in
149
229
  `ALL_STYLES`; see below — and the `SEPARATOR_DETECT` policy. A separator is 1 to 8 UTF-8
@@ -158,10 +238,12 @@ default — `INVARIANT` and `DETECT` declare none) reads exactly as the invarian
158
238
  and nothing that parsed before stops parsing when a symbol is declared.
159
239
 
160
240
  - `currency:` — honored only while `CURRENCY` is set: once, leading (`$5`, `-$5`, `$ -5`)
161
- or trailing (`5 €`, `1.234,50 kr.`), with optional ASCII whitespace between symbol and
241
+ or trailing (`5 €`, `1.234,50 kr.`), with optional white space between symbol and
162
242
  digits, and accounting parentheses wrapping symbol and digits together (`($5)`). Declared
163
243
  with the flag off, the symbol is a `:malformed` `Fault` at the symbol; the flag with
164
- nothing declared matches nothing.
244
+ nothing declared matches nothing. White space inside the symbol is
245
+ allowed (`F CFA`, where an ASCII space, U+00A0 and U+202F read as each other); at either
246
+ edge of it, never.
165
247
  - `currency_decimal_sep:`, `currency_group_sep:` — the separators a currency amount is
166
248
  written with, for a culture whose plain numbers and amounts differ (Swiss German writes
167
249
  `1.234,5` and `CHF 1'234.50`). Read in place of the number separators when `CURRENCY` is
@@ -188,18 +270,19 @@ and nothing that parsed before stops parsing when a symbol is declared.
188
270
  dollars = HyperCast::NumFormat.new(decimal_sep: ".", group_sep: ",", flags: HyperCast::ALL_STYLES, currency: "$")
189
271
  HyperCast.i32("($1,234)", dollars) # => Success(value: -1234)
190
272
  HyperCast.decimal("$1,234.50", dollars) # => Success(value: Decimal(magnitude: 12345, scale: 1, negative: false))
191
- HyperCast.i32("$5", HyperCast::NumFormat::INVARIANT) # => Fault(reason: :malformed, offset: 0, length: 1)
273
+ HyperCast.i32("$5", HyperCast::NumFormat::INVARIANT) # => Fault(reason: :malformed, offset: 0, length: 1)
192
274
 
193
275
  estonian = HyperCast::NumFormat.new(decimal_sep: ",", group_sep: " ", flags: HyperCast::ALL_STYLES, minus_sign: "−")
194
276
  HyperCast.f64("−1 234,5", estonian) # => Success(value: -1234.5) (U+2212 minus; ASCII "-" still reads)
195
277
 
196
278
  francs = HyperCast::NumFormat.new(decimal_sep: ",", group_sep: ".", flags: HyperCast::ALL_STYLES | HyperCast::TRAILING_SIGN,
197
279
  currency: "CHF", currency_decimal_sep: ".", currency_group_sep: "'")
198
- HyperCast.f64("CHF 1'234.50", francs) # => Success(value: 1234.5) (the currency separators, the symbol being present)
280
+ HyperCast.f64("CHF 1'234.50", francs) # => Success(value: 1234.5) (currency separators: the symbol is present)
199
281
  HyperCast.f64("1.234,50", francs) # => Success(value: 1234.5) (the number separators)
200
282
  HyperCast.i32("5 CHF-", francs) # => Success(value: -5) (TRAILING_SIGN)
201
283
 
202
- arabic = HyperCast::NumFormat.new(decimal_sep: "٫", group_sep: "٬", flags: HyperCast::ALL_STYLES, percent: "٪", digit_zero: "٠")
284
+ arabic = HyperCast::NumFormat.new(decimal_sep: "٫", group_sep: "٬", flags: HyperCast::ALL_STYLES, percent: "٪",
285
+ digit_zero: "٠")
203
286
  HyperCast.f64("١٬٢٣٤٫٥", arabic) # => Success(value: 1234.5)
204
287
  HyperCast.decimal("٥٠٪", arabic) # => Success(value: Decimal(magnitude: 5, scale: 1, negative: false))
205
288
  ```
@@ -207,15 +290,20 @@ HyperCast.decimal("٥٠٪", arabic) # => Success(value: Decimal(magnitu
207
290
  A malformed field is an `ArgumentError` at construction, naming the field — the same
208
291
  caller-bug treatment equal separators have always had: an empty or over-long separator, an
209
292
  equal pair (the number pair, or the pair in force for currency amounts), a symbol carrying
210
- an ASCII digit, a sign, percent or currency symbol carrying ASCII whitespace, a currency
211
- symbol over 16 bytes, a digit zero that is ASCII or does not start a digit block. The
293
+ an ASCII digit, a sign, percent symbol or decimal separator carrying white space, a
294
+ currency symbol over 16 bytes or starting or ending in white space (inside it white space
295
+ is fine, as in `F CFA`), a digit zero that is ASCII or does not start a digit block. The
212
296
  limits are `NumFormat::SYMBOL_MAX_BYTES` (8) and `NumFormat::CURRENCY_MAX_BYTES` (16).
213
297
 
214
298
  Across the ABI a `NumFormat` is a 92-byte, size-tagged struct that the core reads in
215
- place — `NumFormat#packed` is exactly those bytes: the size word, the flags, the digit
216
- zero's code point, then each symbol's UTF-8 bytes and length held inline. It is packed
217
- once per format object and memoized by identity on every backend, so declaring a currency
218
- or a culture's digits costs a cast nothing.
299
+ place — `NumFormat#packed` is those bytes in little-endian order, as Python's
300
+ `NumFormat.packed` is: the size word, the flags with the grouping policy in bits 8 and 9
301
+ (`NumFormat#raw_flags`), the digit zero's code point, then each
302
+ symbol's UTF-8 bytes and length held inline. On a little-endian host they are exactly the
303
+ struct; on a big-endian one the three words are swapped to native order before they cross,
304
+ which the Fiddle backend does itself. It is packed once per format object and memoized by
305
+ identity on every backend, so declaring a currency or a culture's digits costs a cast
306
+ nothing.
219
307
 
220
308
  **What stays English: the boolean lexicon.** `bool` reads its twenty lexemes
221
309
  (`true`/`false`, `yes`/`no`, `on`/`off`, …) in English only. No platform carries culture
@@ -267,13 +355,65 @@ and `0`–`9` — and a locale that writes them differently declares them on the
267
355
  A call without the keywords allocates nothing extra on either backend. A call with them builds a format each time (a few microseconds), so in a loop,
268
356
  build it once with `override` or `from_i18n` and pass that instead.
269
357
 
358
+ ### Fault detail
359
+
360
+ A `Fault` the core reports carries `detail`, a `HyperCast::Detail`: the core's numeric `code`
361
+ and its published `name` (`:group_size`, `:digit_expected`, `:not_finite`, …, 32 of them, one
362
+ constant each: `Detail::GROUP_SIZE`). The reason stays the broad classification and the span
363
+ stays what it was; the detail says what in that span was wrong. A later core may add codes,
364
+ so a case over details needs an `else`: a code this gem does not name is kept as a `Detail`
365
+ whose `name` is `:unknown` and whose `code` is the number.
366
+
367
+ ```ruby
368
+ case HyperCast.i32("12,34", HyperCast::NumFormat::INVARIANT)
369
+ in HyperCast::Fault(reason: :malformed, detail: HyperCast::Detail::GROUP_SIZE) then "a group of the wrong size"
370
+ in HyperCast::Fault(detail:) then detail.name
371
+ end
372
+ ```
373
+
374
+ `detail` is not a member of `Fault`: `members`, `to_h`, `==`, `hash`, `inspect`, the
375
+ constructors (a hand-built `Fault.new(reason:, offset:, length:)` has `detail` nil and equals
376
+ the one a door returns) and `Fault(reason:, offset:, length:)` patterns are unchanged. A
377
+ `Violation` has no detail. Typed and checked doors carry one too.
378
+
379
+ ### Date shapes: `DateOptions` and `MonthNames`
380
+
381
+ The date doors read the shapes they always read unless the caller opts in. `options:` takes a
382
+ `DateOptions` (`flags:` and `pivot:`): `COMPACT_DATE` reads `20260107` at `date`,
383
+ `SPACE_SEPARATOR` a space where the `T` goes and `HOUR_OFFSET` an offset of `±hh` (`+00`) at
384
+ `timestamp`; `COMMON_FORMS` is all three, and a flag a door does not read is ignored. A
385
+ `pivot` (100 to 9999) is the last year of the 100-year window a two-digit year reads in
386
+ (`DateOptions.new(pivot: 2029)` reads `26` as 2026), at `date` with an order and at
387
+ `datetime`; there is no default. `months:` takes a `MonthNames`, a vocabulary the caller
388
+ builds, from a Hash of name to month or an Array of `[month, name]` pairs, and never looked
389
+ up: `HyperCast::MonthNames.new({ "Jan" => 1, … })` makes the month field of an ordered date read
390
+ `07-Jan-26` (with a pivot) and `7-Jan-2026`, in the position the declared order selects.
391
+ Names match under simple case folding, the longest followed by the separator winning;
392
+ punctuation is part of a name, so with `janv.` declared and `.` as the separator `7.janv..26`
393
+ reads and `7.janv.26` is `:malformed`. Each name is 1 to 64 bytes with no ASCII digit, `/`,
394
+ `-` or white space, every month needs a name, and two names equal under case folding are
395
+ refused (an `ArgumentError`; the core has the last word on the folding, so on the Fiddle backend building a
396
+ vocabulary is one native call and raises the `LoadError` of a missing library, as a door does).
397
+ `MonthNames#packed` is the layout the core reads: each entry a
398
+ month byte, a little-endian `u32` length and the UTF-8 bytes, which `MonthNames.from_packed`
399
+ reads back.
400
+
401
+ ```ruby
402
+ months = HyperCast::MonthNames.new(%w[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec].each_with_index.to_h { |n, i| [n, i + 1] })
403
+ HyperCast.date("07-Jan-26", :day_month_year, options: HyperCast::DateOptions.new(pivot: 2029), months: months)
404
+ # => Success(value: #<Date: 2026-01-07 ...>)
405
+ HyperCast.timestamp("2026-01-07 15:04:05+00", options: HyperCast::DateOptions::COMMON_FORMS)
406
+ # => Success(value: 2026-01-07 15:04:05 UTC)
407
+ ```
408
+
270
409
  ### `datetime`: a culture's AM/PM
271
410
 
272
411
  The civil date-time door reads a 12-hour clock's `AM`/`PM` ASCII case-insensitively, after
273
412
  the clock (`3:04 PM`) or ahead of it (`PM 3:04`). `am:` and `pm:` declare a culture's own
274
413
  words beside the English ones — German's `vorm.`/`nachm.`, Korean's `오전`/`오후`
275
414
  (written ahead of the clock), Spanish's `a. m.`/`p. m.` (a space inside is fine) — matched
276
- exactly, with or without a space between word and clock. English is still read whatever is
415
+ exactly, with any run of white space or none between word and clock (so the `3:04\u202fPM`
416
+ that ICU 72 and later write for `en_US` reads). English is still read whatever is
277
417
  declared; `nil`, the default, declares nothing, so a call without the keywords reads the
278
418
  English pair only. Like a `NumFormat`'s symbols the words are declared, never looked up:
279
419
  Ruby's stdlib has no day-period data, and `I18n.t("time.am")`/`("time.pm")` are where a
@@ -284,10 +424,10 @@ HyperCast.datetime("1/7/2026 3:04 nachm.", :day_month_year, am: "vorm.", pm: "na
284
424
  # => Success(value: #<DateTime: 2026-07-01T15:04:00+00:00 ...>)
285
425
  HyperCast.datetime("2026-01-07 오후 3:04", :year_month_day, am: "오전", pm: "오후")
286
426
  # => Success(value: #<DateTime: 2026-01-07T15:04:00+00:00 ...>)
287
- HyperCast.datetime("1/7/2026 3:04 nachm.", :day_month_year) # => Fault(reason: :malformed, offset: 13, length: 1)
427
+ HyperCast.datetime("1/7/2026 3:04 nachm.", :day_month_year) # => Fault(reason: :malformed, offset: 13, length: 1)
288
428
  ```
289
429
 
290
- A designator is 1 to 16 UTF-8 bytes with no ASCII digit and no ASCII whitespace at either
430
+ A designator is 1 to 16 UTF-8 bytes with no ASCII digit and no white space at either
291
431
  end; anything else is an `ArgumentError`. Only `datetime` reads them — `date` has no time
292
432
  part. Across the ABI they are a 40-byte, size-tagged struct passed beside the order, null
293
433
  when nothing is declared. The designators are keywords, so they are read, validated and
@@ -295,6 +435,119 @@ packed per call — the Fiddle backend packs them into its per-thread scratch
295
435
  that declares them costs about twice the plain call on the Magnus backend (the keyword
296
436
  scan is the cost: `am: nil, pm: nil` pays the same) and about half again on Fiddle.
297
437
 
438
+ ## Validation constraints
439
+
440
+ A value that parsed can still break a business rule. `Constraints` declares the rule with the
441
+ OpenAPI Schema Object's keywords, bound to one door (`:i32`, `:f64`, `:decimal`, `:text`, …),
442
+ and a checked door judges the value by it, in the core and in exact decimal arithmetic:
443
+
444
+ ```ruby
445
+ require "bigdecimal"
446
+
447
+ # Latitude: a multiple of 0.000001 between -90 and 90, finer input rounded half to even.
448
+ latitude = HyperCast::Constraints.new(door: :f64, minimum: "-90", maximum: "90",
449
+ multiple_of: "0.000001", rounding: :midpoint)
450
+ # Euro cash: a multiple of 0.05, and anything else is wrong.
451
+ euro_cash = HyperCast::Constraints.new(door: :decimal, multiple_of: BigDecimal("0.05"))
452
+ # A sex code: one of three, whatever case and padding it arrived in.
453
+ sex = HyperCast::Constraints.new(door: :text, trim: true, enum: %w[Female Male Other])
454
+
455
+ invariant = HyperCast::NumFormat::INVARIANT
456
+ euro = HyperCast::NumFormat.new(decimal_sep: ",", group_sep: ".", flags: HyperCast::ALL_STYLES, currency: "€")
457
+ HyperCast.checked("45.1234567", invariant, latitude)
458
+ # => Checked(value: 45.123457, adjusted: true, enum_index: nil)
459
+ HyperCast.checked("-90.5", invariant, latitude)
460
+ # => Violation(keyword: HyperCast::Keyword::MINIMUM, value: -90.5, offset: 0, length: 5)
461
+ HyperCast.checked_from_float(45.1234567, latitude)
462
+ # => Checked(value: 45.123457, adjusted: true, enum_index: nil)
463
+ HyperCast.checked("€1.234,55", euro, euro_cash)
464
+ # => Checked(value: Decimal(magnitude: 123455, scale: 2, negative: false), adjusted: false, enum_index: nil)
465
+ HyperCast.checked("€12,37", euro, euro_cash)
466
+ # => Violation(keyword: HyperCast::Keyword::MULTIPLE_OF, value: Decimal(magnitude: 1237, scale: 2, negative: false), offset: 0, length: 6)
467
+ HyperCast.checked("12,3x", euro, euro_cash)
468
+ # => Fault(reason: :malformed, offset: 4, length: 1)
469
+
470
+ def describe(verdict)
471
+ case verdict
472
+ in HyperCast::Checked(value:, enum_index:) then "#{value}, entry #{enum_index}" # " MALE " -> Male, entry 1
473
+ in HyperCast::Fault(reason:, offset:) then "#{reason} at character #{offset}" # " " -> empty at character 0
474
+ in HyperCast::Violation(keyword: HyperCast::Keyword::ENUM, value:, offset:)
475
+ "not a sex code: #{value} at character #{offset}" # " Femal" -> Femal at character 1
476
+ in HyperCast::Violation(keyword:) then "breaks #{keyword.name}" # keywords are open
477
+ end
478
+ end
479
+
480
+ describe(HyperCast.text(" MALE ", sex)) # => "Male, entry 1"
481
+ ```
482
+
483
+ A checked door answers `Checked(value, adjusted, enum_index)` — the value, `adjusted` (true
484
+ only when rounding changed it) and, at `:text` with an `enum`, the index of the entry matched
485
+ (`nil` otherwise, a numeric `enum` included, where the value is the answer) — or one of the
486
+ two rejections: the plain doors' own `Fault` (it did not parse: the very type, so a parse
487
+ failure reads the same at either door: the input is not the type) or a
488
+ `Violation(keyword, value, offset, length)` (it is the type, and broke a rule: the keyword,
489
+ the value exactly as the door cast it, in the type a `Checked` would have carried and never
490
+ rounded, since `multiple_of`'s rounding is part of the judgement, at `:text` the judged text
491
+ after `trim` and never an entry, and the value's span, in the units a fault's span is in,
492
+ characters for text and bytes for a binary `String`). All three are `Data`, so they
493
+ pattern-match.
494
+ `Keyword` is a `Data` with constants (`Keyword::MINIMUM` … `Keyword::ENUM`), not a closed set:
495
+ its `name` is the OpenAPI spelling (`"exclusiveMinimum"`), and `format` and `pattern` may join
496
+ in a minor release, a code this gem does not name yet arriving as `Keyword.new(code: 9)`, named
497
+ `"keyword 9"`. So a `case` over keywords needs its catch-all branch (the last `Violation` one
498
+ above). The plain doors and their `Success` or `Fault` are unchanged.
499
+
500
+ The numeric doors take `minimum:`, `exclusive_minimum:`, `maximum:`, `exclusive_maximum:`
501
+ (four independent keywords: all four may be declared together, and each is judged on its
502
+ own), `multiple_of:` with a `rounding:` (`:strict`, the default, then `:midpoint`, half to
503
+ even, `:floor` and `:ceiling`, the keys of `HyperCast::ROUNDINGS`) and `enum:`, whose entries
504
+ are compared exactly to the value; `:text` takes `min_length:`, `max_length:` (in code points)
505
+ and `enum:` (an `Integer`, `BigDecimal` or `Decimal` among its entries is valid and never
506
+ matches), matched under Unicode simple case folding and delivering the `String` declared and
507
+ its index: the very object when it is frozen, and when it is not, the frozen copy the
508
+ declaration took of it (a `Hash` key's rule), so mutating the original afterwards changes
509
+ nothing. Two of HyperCast's own extensions go with them at `:text`: `trim:` (Unicode
510
+ `White_Space`, U+00A0 included) and `case_sensitive:`, which matches `enum:` byte for byte
511
+ instead, for a vocabulary whose case carries meaning (`mm` and `Mm`). The constructor takes
512
+ every keyword at every door; a keyword for another type is ignored, as JSON Schema ignores it.
513
+ The first failure wins: the door parses, the text is trimmed, `multiple_of` rounds or
514
+ refuses (a rounding past what the type holds breaks `multiple_of`), then the bounds
515
+ (`minimum`, `exclusive_minimum`, `maximum`, `exclusive_maximum`), the lengths and `enum` judge
516
+ the result. A float door also judges the float it delivers against each bound read as the door reads
517
+ it: `"1e-400"` at `:f64` reads as `0`, so it breaks `exclusive_minimum: "0"`. Bounds, steps and
518
+ numeric entries are an `Integer`, a `BigDecimal`, a `String` in invariant notation or a
519
+ `HyperCast::Decimal`, all converted exactly by the core (`"1e-6"` is `0.000001`, and `"1e-29"`,
520
+ past the 28 places a core decimal holds, is refused rather than rounded) and kept as the exact
521
+ `HyperCast::Decimal` declared; never a `Float`, so `0.1` cannot be declared inexactly: a `Float`
522
+ bound is an `ArgumentError`. `checked(text, format, constraints)` is every numeric door's checked
523
+ form, with the same `separator:`, `delimiter:` and `unit:` overrides, and
524
+ `checked_from_float(value, constraints)` judges a number a source already decoded on the shortest
525
+ decimal that names it (`0.1 + 0.2` breaks `multiple_of: "0.1"` under `:strict`, and rounds to `0.3`
526
+ under `:midpoint`), with an empty span. `text(text, constraints)` is the text door's.
527
+
528
+ A declaration is judged once, by the core, when it is built. Every declaration OpenAPI 3.2
529
+ allows is accepted, an unsatisfiable one included: crossed or equal bounds, `min_length:` above
530
+ `max_length:`, duplicate `enum:` entries (the first match wins), an empty or untrimmable text
531
+ entry (it never matches), a numeric entry the type cannot hold, and `enum: []`, which every
532
+ value violates (an `enum:` left `nil` is none). What the core refuses is the caller's bug:
533
+ `Constraints.new` raises `ArgumentError`, its message the rule (`Constraints.new(door: :u8,
534
+ multiple_of: "0")` raises "Constraints refused (code 5): multipleOf is not positive."). It
535
+ refuses `trim:` or `case_sensitive:` at a numeric door and `multiple_of:` with a `rounding:` at `:text` (code 1), a
536
+ `multiple_of:` that is not positive (5), a `rounding:` without `multiple_of:` (6), a bound, step
537
+ or entry past the 28 places a core decimal holds or a rounding with a fractional
538
+ `multiple_of:` at an integer door (8), and a text entry that is not UTF-8 (9). The
539
+ door is a required keyword, so no
540
+ `Constraints` means "no rules" by accident; `Constraints.new(door: :f64)` declares none on
541
+ purpose. Handing a declaration to the other kind of door (`:text` constraints to `checked`,
542
+ numeric ones to `text`) is an `ArgumentError` too, and after that a checked cast judges only
543
+ data and raises nothing for it. `HyperCast.constraints_check(door:, **keywords)` answers the
544
+ same refusal as its code, `0` or one of those above (`Constraints::REFUSALS` words each; any other
545
+ reads "Constraints refused (code N): a rule this binding does not name."), without raising,
546
+ and `HyperCast.declared_decimal(text)` is the conversion every bound crosses. A text `enum`
547
+ entry crosses as its bytes, so one that is not UTF-8 (a binary `"\xFF".b`) is the core's
548
+ refusal 9. A `Constraints` is an immutable `Data`: two declaring the same rules are equal, and
549
+ `#with` builds a new one, judged again, as `Marshal.load` does.
550
+
298
551
  [^overrides]: Plus the optional keywords `separator:`, `delimiter:` and `unit:`, which
299
552
  override those fields of `format` for the call. See
300
553
  [Rails' words for a format](#rails-words-for-a-format-separator-delimiter-unit).
@@ -306,27 +559,44 @@ it reads the core's out-values out of its own buffers and needs the values the d
306
559
  have returned. `HyperCast::Interop` is the code the Fiddle backend's doors decode with, so
307
560
  the two cannot drift. It is loaded on every backend.
308
561
 
309
- - `SCALARS` — the `String#unpack` directive for one value of each scalar door (`:i32` is
310
- `"l<"`; a bool is the byte 0 or 1).
562
+ - `SCALARS` — the `String#unpack` directive for one value of each scalar door, in the host's
563
+ native byte order, the order the core writes in (`:i32` is `"l"`; a bool is the byte 0 or
564
+ 1).
311
565
  - `RECORDS` — for each record door (`:decimal`, `:uuid`, `:timestamp`, `:date`, …), the
312
566
  directive that unpacks one value, how many fields that yields, and a lambda
313
567
  `(fields, at)` that builds the Ruby value from them. To decode a column, append `"*"` and
314
568
  step that many fields at a time.
315
569
  - `VALUE_BYTES` — the bytes one value of each door takes.
316
570
  - `decode(door, bytes)` — one value, from the bytes the core wrote for it.
317
- - `fault(code, offset, length)` — the `Fault` a nonzero verdict code names; a code that names
318
- no reason is a `KeyError`.
571
+ - `fault(code, offset, length, detail = nil)` — the `Fault` a nonzero verdict code names, with
572
+ the core's detail code (a code this gem does not name becomes an `:unknown` `Detail`); a
573
+ code that names no reason is a `KeyError`.
574
+ - `raw_fault(code, raw, bytes = nil)` — the same from the 16 bytes of a `RawFaultDetail`
575
+ (`FAULT_BYTES`: the size word, then the span's offset and length and the detail code), the
576
+ span mapped to characters over `bytes` when given.
319
577
  - `characters(bytes, offset, length)` — the core's byte span as the character span
320
578
  `String#[]` slices by.
321
579
  - `version(word)` — a packed `*_version` word as `"major.minor.patch"`.
322
580
  - `library_path(library, native_dir, repo_root)` — the shared library to `dlopen`: the
323
581
  staged `native/{rid}/` build, else the in-repo cargo build, else `nil`.
324
582
 
583
+ A `Constraints` crosses a C ABI as two Strings, the layouts the core reads in place:
584
+ `#packed` is the 104-byte `RawConstraints` (`Constraints::PACKED_BYTES`) in native byte order
585
+ (the size, the flags, the rounding code, `min_length`, `max_length` and a reserved zero as
586
+ `u32`s, then `minimum`, `maximum`, `multiple_of`, `exclusive_minimum` and `exclusive_maximum`
587
+ as 16-byte decimals at 24, 40, 56, 72 and 88: the low 64 and high 32 bits of the magnitude, the
588
+ scale, the sign and two zero bytes), and `#packed_enum` the `enum` list beside it (`""` for
589
+ none): at a numeric door 16-byte decimals in native byte order, at `:text` each entry a
590
+ little-endian `u32` byte length followed by its UTF-8, read only when the flags carry
591
+ `HAS_ENUM` (256), which any declared `enum:` sets (`Constraints::FLAGS`; `trim:` sets 128 and
592
+ `case_sensitive:` 512).
593
+ `HyperCast::CHECKED_DOORS` maps each door to the core's door code.
594
+
325
595
  `NativePlatform.rid_and_library_name(library: "hypertabular")` gives the `{rid}` directory
326
596
  and file name for any SkunkWerkx core; `library:` defaults to `"hypercast"`.
327
597
 
328
598
  ```ruby
329
- HyperCast::Interop.decode(:i32, [-7].pack("l<")) # => -7
599
+ HyperCast::Interop.decode(:i32, [-7].pack("l")) # => -7
330
600
  HyperCast::Interop.fault(2, 3, 1) # => Fault, reason :malformed
331
601
  HyperCast::Interop.version(0x000700) # => "0.7.0"
332
602
  ```
@@ -349,10 +619,13 @@ HyperCast::Interop.version(0x000700) # => "0.7.0"
349
619
  2.85 µs: a little behind `Time.iso8601`, sitting on Fiddle's per-call marshalling floor.
350
620
 
351
621
  Separator detection is nearly free here: `1.234.567,89` under `NumFormat::DETECT` runs
352
- at 154 ns against 145 ns for the same text under a declared eurozone format. Reading a
353
- format costs one pointer compare: `DETECT` is identity-matched like `INVARIANT`, and any
354
- other format is resolved once per thread and memoized by identity — anchored in a
355
- thread-variable so the memo's key can never be a recycled address.
622
+ at 154 ns against 145 ns for the same text under a declared eurozone format. Reading
623
+ `INVARIANT` or `DETECT` costs one pointer compare; any other format is resolved once per
624
+ thread and memoized by its `object_id`, which survives a compacting collection and is never
625
+ reused, so the memo cannot mistake a format built later for the one it remembers. That
626
+ lookup costs about 5 ns more than the address compare it replaced (Apple M6, Ruby 4.0.9,
627
+ 2026-11-02: `1,234,567` under a declared `$` at 82 ns against 77 ns), and a thread
628
+ alternating between two formats now pays 970 ns per pair against 1.13 µs.
356
629
 
357
630
  A declared currency symbol costs text that does not carry one about 6 ns on the Magnus
358
631
  backend: in a run for 0.9.0, separate from the [Benchmarks](#benchmarks) table, `1,234,567`
@@ -412,7 +685,9 @@ rather than through `Data.new`, whose keyword handling alone cost more than the
412
685
  | `:native` | the core linked into a Magnus extension | a precompiled platform gem is installed — every one carries an extension for each Ruby it installs on; see [Install](#install) — or the `hypercast-wasm` gem is linked into a ruby.wasm interpreter; see [Ruby in the browser](#ruby-in-the-browser) |
413
686
  | `:fiddle` | `libhypercast` for this platform, `dlopen`ed through Fiddle | no extension loads: the universal gem, on a Ruby or platform no platform gem covers; also the answer when nothing loads at all |
414
687
 
415
- Selection happens once, at `require`, in that order.
688
+ Selection happens once, at `require`, in that order. Either way the gem has a door for each
689
+ of the core's 36 C ABI exports: Fiddle calls the exports, and the extension the core's Rust
690
+ functions behind them (`date` takes the order `cast_date_ordered` would).
416
691
 
417
692
  `HYPERCAST_PURE` forces `:fiddle`, even where an extension would load. It is a testing and
418
693
  diagnostic switch — CI runs the whole suite through it, and it is how to rule an extension
Binary file
Binary file