You need to sign in or sign up before continuing.
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 +4 -4
- data/LICENSE-UNICODE +39 -0
- data/README.md +318 -43
- data/lib/hypercast/3.4/hypercast_native.so +0 -0
- data/lib/hypercast/4.0/hypercast_native.so +0 -0
- data/lib/hypercast/interop.rb +35 -15
- data/lib/hypercast/runtime.rb +62 -9
- data/lib/hypercast.rb +1197 -148
- metadata +3 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: bb326eec4ca49a68216e4a256a20dbae17cdee8915e30525464666914762c6fc
|
|
4
|
+
data.tar.gz: 20d0ea573f4512e5aa6604d75319d7fdbde8c3fb97b03358961fdd2d2e8372c9
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
-
|
|
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}"
|
|
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
|
-
|
|
60
|
-
|
|
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
|
|
74
|
-
16 bytes
|
|
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
|
|
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
|
-
- `
|
|
82
|
-
|
|
83
|
-
|
|
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
|
-
|
|
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,
|
|
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
|
|
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)
|
|
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) (
|
|
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: "٪",
|
|
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
|
|
211
|
-
symbol over 16 bytes
|
|
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
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
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
|
|
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)
|
|
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
|
|
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
|
|
310
|
-
`"l
|
|
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
|
|
318
|
-
|
|
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
|
|
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
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
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
|