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.
data/lib/hypercast.rb CHANGED
@@ -9,9 +9,11 @@ require_relative "hypercast/runtime"
9
9
  # platform gems), or the native libhypercast shared library called through Fiddle (the
10
10
  # universal gem bundles one per supported platform). HyperCast::BACKEND names the one that
11
11
  # loaded; the selection logic is at the bottom of this file. Every door returns a verdict: Success or
12
- # Fault (a closed reason plus the offending span), never an exception for bad data — the
13
- # only exceptions here are caller bugs (a malformed NumFormat, an undeclared option, text
14
- # that is not a String), never data, and the same exception on every backend.
12
+ # Fault (a closed reason plus the offending span), and every checked door — the doors that
13
+ # also judge a value by declared Constraints — a Checked, a Fault or a Violation; never an
14
+ # exception for bad data. The only exceptions here are caller bugs (a malformed NumFormat, a
15
+ # refused Constraints, an undeclared option, text that is not a String), never data, and the
16
+ # same exception on every backend.
15
17
  #
16
18
  # Consume with Ruby's own pattern matching over the two Data case types:
17
19
  #
@@ -30,7 +32,7 @@ require_relative "hypercast/runtime"
30
32
  module HyperCast
31
33
  # This gem's own version — kept in lockstep with hypercast.gemspec by the
32
34
  # prepare-release workflow, so the two can never drift apart again.
33
- VERSION = "1.0.0"
35
+ VERSION = "1.1.0"
34
36
 
35
37
  # The success case of a verdict: a cast value.
36
38
  Success = Data.define(:value)
@@ -41,11 +43,127 @@ module HyperCast
41
43
  # byte offsets for a binary (ASCII-8BIT) String, whose characters are its bytes. Either
42
44
  # way `text[offset, length]` is the offending text, with no mapping on your side.
43
45
  # Nothing is captured — slicing it out of the input is the caller's choice.
44
- Fault = Data.define(:reason, :offset, :length)
46
+ #
47
+ # A fault the core reports also carries #detail, what exactly was wrong (a Detail), beside the
48
+ # broad reason. It is not a member: equality, #hash, #to_h, #inspect, the members and the
49
+ # positional and keyword constructors are what they were, so a Fault built by hand with three
50
+ # arguments is #== to the same fault read from a door, and its #detail is nil. A pattern asks
51
+ # for it by name: `in Fault(reason: :malformed, detail: Detail::GROUP_SIZE)`.
52
+ Fault = Data.define(:reason, :offset, :length) do
53
+ # The three members, and optionally the Detail (or nil) the core reported.
54
+ def initialize(reason:, offset:, length:, detail: nil)
55
+ @detail = detail
56
+ super(reason: reason, offset: offset, length: length)
57
+ end
58
+
59
+ # What exactly was wrong, a Detail; nil for a Fault built without one.
60
+ attr_reader :detail
61
+
62
+ # The members, and #detail when a pattern names it.
63
+ def deconstruct_keys(keys)
64
+ return super unless keys&.include?(:detail)
65
+
66
+ super(keys - [:detail]).merge(detail: @detail)
67
+ end
68
+
69
+ # A copy with the given members replaced, keeping #detail unless one is given.
70
+ def with(**changes)
71
+ return self if changes.empty?
72
+
73
+ self.class.new(**to_h, detail: @detail, **changes)
74
+ end
75
+
76
+ # Marshal's form: the members and the detail, so a loaded fault keeps its detail.
77
+ def marshal_dump
78
+ to_h.merge(detail: @detail)
79
+ end
80
+
81
+ # Restores a fault from #marshal_dump's form through #initialize.
82
+ def marshal_load(members)
83
+ initialize(**members)
84
+ end
85
+ end
45
86
 
46
87
  # The native core's failure codes, mapped to the closed reason Symbols a Fault carries.
47
88
  REASONS = { 1 => :empty, 2 => :malformed, 3 => :out_of_range }.freeze
48
89
 
90
+ # What exactly a Fault found wrong: the native core's numeric code and its published name. The
91
+ # codes keep their numbers and meanings, and a later core may add more, so a case over details
92
+ # needs an else branch: a code this gem does not name is kept, its #name :unknown. The reason
93
+ # and span of a fault stay usable either way. The constants (Detail::BLANK ...
94
+ # Detail::NOT_A_SCALAR, one per published code) compare equal to every detail of their code, so
95
+ # `in Fault(detail: Detail::GROUP_SIZE)` matches.
96
+ Detail = Data.define(:code) do
97
+ # The published name as a Symbol (:group_size), or :unknown for a code this gem does not name.
98
+ def name
99
+ self.class::NAMES.fetch(code, :unknown)
100
+ end
101
+
102
+ # True for a code this gem does not name; #code still holds it.
103
+ def unknown?
104
+ !self.class::NAMES.key?(code)
105
+ end
106
+
107
+ # The name, as text ("group_size"; "unknown" for an unknown code).
108
+ def to_s
109
+ name.to_s
110
+ end
111
+
112
+ # The constant that names this detail (HyperCast::Detail::GROUP_SIZE), or the Data form for
113
+ # a code this gem does not name.
114
+ def inspect
115
+ unknown? ? super : "HyperCast::Detail::#{name.to_s.upcase}"
116
+ end
117
+
118
+ # The detail of a core's code: the constant of a published one, a new Detail for any other.
119
+ def self.of(code)
120
+ self::BY_CODE.fetch(code) { new(code: code) }
121
+ end
122
+ end
123
+
124
+ # The published name of each detail, by code.
125
+ Detail::NAMES = {
126
+ 1 => :blank, 2 => :unexpected_character, 3 => :digit_expected, 4 => :delimiter_expected,
127
+ 5 => :trailing_text, 6 => :no_digits, 7 => :sign_misplaced, 8 => :parentheses_unbalanced,
128
+ 9 => :mark_repeated, 10 => :group_misplaced, 11 => :group_size, 12 => :group_in_fraction,
129
+ 13 => :ambiguous_separator, 14 => :fraction_not_allowed, 15 => :field_width, 16 => :wrong_length,
130
+ 17 => :component_missing, 18 => :not_recognized, 19 => :unknown_unit, 20 => :invalid_utf8,
131
+ 21 => :too_long, 22 => :not_finite, 23 => :not_whole, 24 => :negative_not_allowed,
132
+ 25 => :too_large, 26 => :too_small, 27 => :too_precise, 28 => :date_field_out_of_range,
133
+ 29 => :time_field_out_of_range, 30 => :outside_window, 31 => :nonexistent_date, 32 => :not_a_scalar
134
+ }.freeze
135
+
136
+ # Each published detail by code, one frozen constant apiece (Detail::BLANK is code 1, and so
137
+ # on through Detail::NOT_A_SCALAR, code 32): a Fault's #detail is one of these.
138
+ Detail::BY_CODE = Detail::NAMES.to_h do |code, name|
139
+ [code, Detail.const_set(name.to_s.upcase, Detail.new(code: code))]
140
+ end.freeze
141
+
142
+ # The 25 code points of Unicode's White_Space property, the core's one notion of white
143
+ # space: a character class the declaration checks match with (the Magnus backend's designator
144
+ # check reads the core's own predicate). Held to corpus/formats.json by the suite.
145
+ WHITE_SPACE = /[\t\n\v\f\r \u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]/
146
+ private_constant :WHITE_SPACE
147
+
148
+ class << self
149
+ private
150
+
151
+ # A declared symbol's text as the UTF-8 the core reads, transcoded from its own encoding.
152
+ # Text with no UTF-8 form (a lone UTF-16 surrogate, bytes its encoding does not allow, a
153
+ # character with no Unicode counterpart) is data at a door, MALFORMED at that character
154
+ # (#kept); in a declaration it is the caller's bug, refused with the same ArgumentError on
155
+ # every backend, never declared as a stand-in for the character it could not spell.
156
+ def declared_utf8(field, text)
157
+ symbol = text.encode(Encoding::UTF_8)
158
+ return symbol if symbol.valid_encoding?
159
+
160
+ raise ArgumentError, "#{field} #{text.inspect} must be whole characters with a UTF-8 form"
161
+ rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError,
162
+ Encoding::ConverterNotFoundError
163
+ raise ArgumentError, "#{field} #{text.inspect} must be whole characters with a UTF-8 form"
164
+ end
165
+ end
166
+
49
167
  # Caller-declared numeric notation for the integer, real and decimal doors — declared out
50
168
  # loud (INVARIANT, or a literal), never defaulted, the same stance every binding takes.
51
169
  # Past the separators and the flags, every field is one a culture table would fill in,
@@ -63,24 +181,47 @@ module HyperCast
63
181
  # percent symbol while PERCENT is. A separator may be wider than one character (", " —
64
182
  # comma, space — is a separator), up to 8 UTF-8 bytes. A malformed format is a caller bug
65
183
  # (ArgumentError), never a verdict: an empty or over-long separator, equal separators (or
66
- # an equal pair in force for currency amounts), a symbol carrying an ASCII digit, a sign
67
- # or percent symbol carrying ASCII whitespace, a currency symbol longer than 16 bytes or
68
- # carrying a digit or whitespace, or a digit zero that is ASCII or starts no digit block.
184
+ # an equal pair in force for currency amounts), a symbol with no UTF-8 form (a lone UTF-16
185
+ # surrogate, bytes its encoding does not allow), a symbol carrying an ASCII digit, a sign,
186
+ # percent symbol, or a decimal separator, carrying white space (a group separator may be
187
+ # white space), a currency symbol longer than 16 bytes or starting or ending in white
188
+ # space (inside it white space is fine: "F CFA"), or a digit zero that is ASCII or starts
189
+ # no digit block.
190
+ #
191
+ # Grouping is a policy, declared apart from the flags: `grouping:` is :western (the default:
192
+ # once a numeral uses the group separator, groups of exactly three digits counted from the
193
+ # decimal separator, the leftmost one to three and not starting with a zero, so "1,234,567"
194
+ # reads and "12,34" and "0,125" are :malformed Faults with the detail Detail::GROUP_SIZE),
195
+ # or :indian (the group beside the decimal separator three digits, every group to its left two,
196
+ # the leftmost one or two: "12,34,567"), which reads only when declared. An ungrouped
197
+ # numeral reads under every policy, and a policy only judges groups: without the GROUPING flag
198
+ # a group separator is still refused. `flags` is the style mask (GROUPING ... TRAILING_SIGN)
199
+ # and never carries a policy: bits 8 and 9 or any other bit this version does not define is an
200
+ # ArgumentError.
69
201
  NumFormat = Data.define(:decimal_sep, :group_sep, :flags, :currency,
70
202
  :currency_decimal_sep, :currency_group_sep,
71
203
  :minus_sign, :plus_sign, :percent, :digit_zero) do
72
204
  # Validates every declared field up front — the separators (1 to 8 UTF-8 bytes each,
73
205
  # distinct from each other, and so the pair in force for currency amounts), the signs,
74
206
  # the percent and currency symbols (no ASCII digit, since a digit is a digit before it
75
- # is anything else, and no ASCII whitespace, which would collide with the trimming
76
- # around them) and the digit zero (one non-ASCII character whose ten successors share
77
- # its UTF-8 prefix, which every Unicode digit block's zero does) — so a malformed
78
- # format fails loudly as the caller bug it is. Every field is stored transcoded to
79
- # UTF-8, the encoding the core reads — a separator handed over in another encoding (a
80
- # no-break space read from a Latin-1 file, say) is the same code point on every backend
81
- # rather than whatever its bytes happened to spell in the encoding it arrived in.
207
+ # is anything else, and no white space, which would collide with the trimming around
208
+ # them; the decimal separators carry none either, and a currency symbol only at its
209
+ # edges) and the digit zero (one non-ASCII
210
+ # character whose ten successors share its UTF-8 prefix, which every Unicode digit
211
+ # block's zero does) — so a malformed format fails loudly as the caller bug it is. Every
212
+ # field is stored transcoded to UTF-8, the encoding the core reads — a separator handed
213
+ # over in another encoding (a no-break space read from a Latin-1 file, say) is the same
214
+ # code point on every backend rather than whatever its bytes happened to spell in the
215
+ # encoding it arrived in.
82
216
  def initialize(decimal_sep:, group_sep:, flags:, currency: "", currency_decimal_sep: "",
83
- currency_group_sep: "", minus_sign: "", plus_sign: "", percent: "", digit_zero: "")
217
+ currency_group_sep: "", minus_sign: "", plus_sign: "", percent: "", digit_zero: "",
218
+ grouping: :western)
219
+ check_flags(flags)
220
+ raise ArgumentError, "grouping must be one of #{GROUPING_POLICIES.keys.inspect}; got #{grouping.inspect}" unless
221
+ GROUPING_POLICIES.key?(grouping)
222
+
223
+ @grouping = grouping
224
+
84
225
  limit = self.class::SYMBOL_MAX_BYTES
85
226
  decimal_sep = declared("decimal separator", decimal_sep, limit, required: true)
86
227
  group_sep = declared("group separator", group_sep, limit, required: true)
@@ -89,20 +230,90 @@ module HyperCast
89
230
 
90
231
  currency_decimal_sep = declared("currency decimal separator", currency_decimal_sep, limit)
91
232
  currency_group_sep = declared("currency group separator", currency_group_sep, limit)
233
+ currency = declared("currency symbol", currency, self.class::CURRENCY_MAX_BYTES)
234
+ minus_sign = declared("minus sign", minus_sign, limit)
235
+ plus_sign = declared("plus sign", plus_sign, limit)
236
+ percent = declared("percent symbol", percent, limit)
92
237
  money_decimal = currency_decimal_sep.empty? ? decimal_sep : currency_decimal_sep
93
238
  money_group = currency_group_sep.empty? ? group_sep : currency_group_sep
94
239
  raise ArgumentError, "currency decimal and group separators must differ; both are #{money_decimal.inspect}" if
95
240
  money_decimal == money_group
96
241
 
242
+ # White space comes last, after every field's length and digit and the equal separators.
243
+ { "decimal separator" => decimal_sep, "currency decimal separator" => currency_decimal_sep,
244
+ "minus sign" => minus_sign, "plus sign" => plus_sign, "percent symbol" => percent }.each do |field, symbol|
245
+ raise ArgumentError, "#{field} #{symbol.inspect} must not contain white space" if
246
+ symbol.match?(WHITE_SPACE)
247
+ end
248
+ # A currency symbol may hold white space inside ("F CFA"), never at an edge.
249
+ raise ArgumentError, "currency symbol #{currency.inspect} must not start or end with white space" if
250
+ currency.match?(/\A#{WHITE_SPACE.source}|#{WHITE_SPACE.source}\z/)
251
+
97
252
  super(decimal_sep: decimal_sep, group_sep: group_sep, flags: flags,
98
- currency: declared("currency symbol", currency, self.class::CURRENCY_MAX_BYTES, flush: true),
99
- currency_decimal_sep: currency_decimal_sep, currency_group_sep: currency_group_sep,
100
- minus_sign: declared("minus sign", minus_sign, limit, flush: true),
101
- plus_sign: declared("plus sign", plus_sign, limit, flush: true),
102
- percent: declared("percent symbol", percent, limit, flush: true),
253
+ currency: currency, currency_decimal_sep: currency_decimal_sep, currency_group_sep: currency_group_sep,
254
+ minus_sign: minus_sign, plus_sign: plus_sign, percent: percent,
103
255
  digit_zero: digit_zero_of(digit_zero))
104
256
  end
105
257
 
258
+ # The grouping policy, :western or :indian. It is not a member, as Fault#detail is
259
+ # not: the ten members, #to_h, #inspect and the positional and keyword constructors are
260
+ # 1.0's, and the policy rides beside them, counting in #==, #eql? and #hash (an :indian and a
261
+ # :western format must never be one memo key). A NumFormat restored from a 1.0 Marshal
262
+ # payload carries no policy and is :western, like everything that records none.
263
+ def grouping
264
+ @grouping || :western
265
+ end
266
+
267
+ # The flags word the native layout carries: #flags with the grouping policy in bits 8 and 9.
268
+ # A 1.0 Marshal payload is restored member by member with no call this class can hook, so a
269
+ # flags word it stored is judged here, on its first use.
270
+ def raw_flags
271
+ check_flags(flags)
272
+ flags | GROUPING_POLICIES.fetch(grouping)
273
+ end
274
+
275
+ # Equal when every member and the grouping policy are.
276
+ def ==(other)
277
+ super && grouping == other.grouping
278
+ end
279
+
280
+ # Eql when every member and the grouping policy are.
281
+ def eql?(other)
282
+ super && grouping.eql?(other.grouping)
283
+ end
284
+
285
+ # A hash over the members and the grouping policy.
286
+ def hash
287
+ [super, grouping].hash
288
+ end
289
+
290
+ # The members, and #grouping when a pattern names it.
291
+ def deconstruct_keys(keys)
292
+ return super unless keys&.include?(:grouping)
293
+
294
+ super(keys - [:grouping]).merge(grouping: grouping)
295
+ end
296
+
297
+ # A copy with the given members (or grouping:) replaced, keeping the policy unless one is
298
+ # given, and validated as NumFormat.new validates. With none given it is the format itself.
299
+ def with(**changes)
300
+ return self if changes.empty?
301
+
302
+ self.class.new(**to_h, grouping: grouping, **changes)
303
+ end
304
+
305
+ # Marshal's form: the members and the policy, so a loaded format keeps its policy and is
306
+ # judged again as a new one is, and a stored policy that isn't one is an ArgumentError here. A
307
+ # 1.0 payload (the struct form) loads without a policy, which #grouping reads as :western.
308
+ def marshal_dump
309
+ to_h.merge(grouping: grouping)
310
+ end
311
+
312
+ # Restores a format from #marshal_dump's form through #initialize.
313
+ def marshal_load(members)
314
+ initialize(**members)
315
+ end
316
+
106
317
  # This format with the fields Ruby's number vocabulary names replaced — the words Rails'
107
318
  # number helpers and I18n's number.format use: separator: (the decimal mark),
108
319
  # delimiter: (grouping) and unit: (the currency symbol). A nil keyword leaves its
@@ -151,7 +362,11 @@ module HyperCast
151
362
  # (U+2212 for Estonian and Basque, for instance) declares it on the result with
152
363
  # Data#with (minus_sign: "−"). Every lenience is on, radix prefixes and percent included;
153
364
  # narrow flags: for anything stricter.
154
- def self.from_i18n(number_format, currency_format: nil, flags: ALL_STYLES)
365
+ #
366
+ # The Hash says nothing about how a locale groups digits, so grouping: declares it — :western,
367
+ # the default, reads groups of three ("1.234.567,89"), and :indian is lakh and crore
368
+ # ("12,34,567").
369
+ def self.from_i18n(number_format, currency_format: nil, flags: ALL_STYLES, grouping: :western)
155
370
  entries = i18n_entries(number_format)
156
371
  separator = entries[:separator] || (entries[:delimiter] == "." ? "," : ".")
157
372
  delimiter = entries[:delimiter]
@@ -176,7 +391,7 @@ module HyperCast
176
391
  flags |= TRAILING_SIGN if trailing_sign?(money[:negative_format])
177
392
  end
178
393
  new(decimal_sep: separator, group_sep: delimiter, flags: flags, currency: currency,
179
- currency_decimal_sep: currency_separator, currency_group_sep: currency_delimiter)
394
+ currency_decimal_sep: currency_separator, currency_group_sep: currency_delimiter, grouping: grouping)
180
395
  end
181
396
 
182
397
  # The I18n Hash's entries under Symbol keys, whatever keys it arrived with.
@@ -199,15 +414,16 @@ module HyperCast
199
414
  end
200
415
  private_class_method :trailing_sign?
201
416
 
202
- # The 92-byte little-endian form of the native ABI's size-tagged NumFormat struct, the
203
- # layout the core reads in place: the size word (92), the flags, the digit zero's code
204
- # point (0 for none), then each symbol as its UTF-8 bytes zero-padded to its field
205
- # followed by its byte length — eight bytes and a length for each of the two number
206
- # separators, the two currency separators, the two signs and the percent symbol, in
207
- # that order; sixteen and a length for the currency symbol. A length of 0 declares
208
- # nothing.
417
+ # The 92-byte little-endian form of the ABI's size-tagged NumFormat struct (what the
418
+ # core's RawNumFormat::from_le_bytes reads, and Python's NumFormat.packed is): the size
419
+ # word (92), the flags with the grouping policy in bits 8 and 9 (#raw_flags), the digit
420
+ # zero's code point (0 for none), each a little-endian u32 on every host, then each symbol
421
+ # as its UTF-8 bytes zero-padded to its field followed by its byte length — eight bytes
422
+ # and a length for each of the two number separators, the two currency separators, the two
423
+ # signs and the percent symbol, in that order; sixteen and a length for the currency
424
+ # symbol. A length of 0 declares nothing.
209
425
  def packed
210
- head = [self.class::PACKED_BYTES, flags, digit_zero.empty? ? 0 : digit_zero.ord].pack("L<L<L<")
426
+ head = [self.class::PACKED_BYTES, raw_flags, digit_zero.empty? ? 0 : digit_zero.ord].pack("L<L<L<")
211
427
  symbols = [decimal_sep, group_sep, currency_decimal_sep, currency_group_sep, minus_sign, plus_sign, percent]
212
428
  head + symbols.map { |symbol| [symbol, symbol.bytesize].pack("a8C") }.join +
213
429
  [currency, currency.bytesize].pack("a16C")
@@ -215,14 +431,25 @@ module HyperCast
215
431
 
216
432
  private
217
433
 
434
+ # The style mask: an Integer of the defined flag bits (0 through 7) and nothing else. The
435
+ # grouping policy has its own keyword, so bits 8 and 9 are refused as a policy in the wrong
436
+ # place, and any bit above them as one this version does not define.
437
+ def check_flags(flags)
438
+ raise ArgumentError, "flags must be an Integer; got #{flags.inspect}" unless flags.is_a?(Integer)
439
+ raise ArgumentError, "flags #{flags} must not carry a grouping policy (bits 8 and 9); declare it with " \
440
+ "grouping:" if flags.anybits?(GROUPING_POLICY)
441
+ raise ArgumentError, "flags #{flags} sets a bit this version does not define (bit 10 and above)" unless
442
+ flags.between?(0, 0xFF)
443
+ end
444
+
218
445
  # The declared text of one field as the UTF-8 the core reads: a String of 1 to `limit`
219
- # UTF-8 bytes with no ASCII digit — nor, for a symbol that sits flush against the
220
- # digits (the signs, the percent and currency symbols), any ASCII whitespace — or ""
221
- # where the field may be left undeclared. Anything else is the caller bug it names.
222
- def declared(field, text, limit, flush: false, required: false)
446
+ # UTF-8 bytes with no ASCII digit, or "" where the field may be left undeclared. Anything
447
+ # else is the caller bug it names. White space is refused by the caller, once every
448
+ # field has passed this and the separators are known to differ.
449
+ def declared(field, text, limit, required: false)
223
450
  raise ArgumentError, "#{field} must be a String; got #{text.inspect}" unless text.is_a?(String)
224
451
 
225
- symbol = text.encode(Encoding::UTF_8)
452
+ symbol = HyperCast.send(:declared_utf8, field, text)
226
453
  if symbol.empty?
227
454
  raise ArgumentError, "#{field} must not be empty" if required
228
455
 
@@ -230,12 +457,8 @@ module HyperCast
230
457
  end
231
458
  raise ArgumentError, "#{field} #{text.inspect} exceeds #{limit} UTF-8 bytes" if symbol.bytesize > limit
232
459
 
233
- if flush
234
- raise ArgumentError, "#{field} #{text.inspect} must not contain an ASCII digit or whitespace" if
235
- symbol.match?(/[0-9\t\n\f\r ]/)
236
- elsif symbol.match?(/[0-9]/)
237
- raise ArgumentError, "#{field} #{text.inspect} must not contain an ASCII digit"
238
- end
460
+ raise ArgumentError, "#{field} #{text.inspect} must not contain an ASCII digit" if symbol.match?(/[0-9]/)
461
+
239
462
  symbol
240
463
  end
241
464
 
@@ -246,7 +469,7 @@ module HyperCast
246
469
  def digit_zero_of(text)
247
470
  raise ArgumentError, "digit zero must be a String; got #{text.inspect}" unless text.is_a?(String)
248
471
 
249
- zero = text.encode(Encoding::UTF_8)
472
+ zero = HyperCast.send(:declared_utf8, "digit zero", text)
250
473
  return zero if zero.empty?
251
474
 
252
475
  raise ArgumentError, "digit zero #{text.inspect} must be one non-ASCII character that starts a digit block" unless
@@ -268,7 +491,8 @@ module HyperCast
268
491
  # The size of NumFormat#packed — the native ABI's size-tagged NumFormat layout — in bytes.
269
492
  NumFormat::PACKED_BYTES = 92
270
493
 
271
- # Permit the group separator between digits (sizes not validated — between digits is the rule).
494
+ # Permit the group separator between digits. The NumFormat's grouping policy judges the sizes
495
+ # (Western by default, :indian when declared).
272
496
  GROUPING = 1
273
497
  # Permit accounting parentheses as negation: (1,234) is -1234.
274
498
  PARENTHESES = 1 << 1
@@ -289,13 +513,13 @@ module HyperCast
289
513
  SEPARATOR_DETECT = 1 << 5
290
514
  # Permit the format's declared currency symbol at either edge of the numeric body —
291
515
  # leading ("$5", "-$5", "$ -5") or trailing ("5 €", "1.234,50 kr."), once, with optional
292
- # ASCII whitespace between symbol and digits; accounting parentheses wrap the symbol
516
+ # white space between symbol and digits; accounting parentheses wrap the symbol
293
517
  # along with the digits ("($5)"). With no symbol declared the flag matches nothing.
294
518
  # Integer, real and decimal doors.
295
519
  CURRENCY = 1 << 6
296
520
  # Permit the sign after the digits ("5-", "5 -", "5 €-", "5- €"), the way a locale whose
297
521
  # negative_format is "%n-" writes it: ASCII - and + or the format's declared signs, once,
298
- # with optional ASCII whitespace before it, and never beside a leading sign or inside
522
+ # with optional white space before it, and never beside a leading sign or inside
299
523
  # accounting parentheses. Not part of ALL_STYLES — NumFormat.from_i18n sets it from the
300
524
  # locale's own negative_format rather than assuming it.
301
525
  TRAILING_SIGN = 1 << 7
@@ -304,12 +528,26 @@ module HyperCast
304
528
  # lenience, and is deliberately not included either).
305
529
  ALL_STYLES = GROUPING | PARENTHESES | EXPONENT | RADIX_PREFIXES | PERCENT | CURRENCY
306
530
 
307
- # The invariant profile — '.' decimal, ',' grouping, every lenience on, no currency
308
- # symbol declared.
531
+ # Grouping policy Western, no bits, the default: groups of exactly three digits from the
532
+ # decimal separator, the leftmost one to three.
533
+ GROUPING_WESTERN = 0
534
+ # Grouping policy Indian, bit 9, only when declared: three digits beside the decimal separator,
535
+ # two in each group to its left, the leftmost one or two.
536
+ GROUPING_INDIAN = 2 << 8
537
+ # The two policy bits, 8 and 9, of the native flags word. Bit 8 (256) is retired and never
538
+ # reused, so 256 and 768 name no policy and are refused. A NumFormat declares its policy with
539
+ # grouping:, never in flags.
540
+ GROUPING_POLICY = 3 << 8
541
+
542
+ # The grouping policies a NumFormat's grouping: names, with their bits in the native flags word.
543
+ GROUPING_POLICIES = { western: GROUPING_WESTERN, indian: GROUPING_INDIAN }.freeze
544
+
545
+ # The invariant profile — '.' decimal, ',' grouping, every lenience on, Western
546
+ # grouping, no currency symbol declared.
309
547
  NumFormat::INVARIANT = NumFormat.new(decimal_sep: ".", group_sep: ",", flags: ALL_STYLES)
310
548
 
311
- # The detection profile — every lenience on, ./, roles resolved per input by
312
- # SEPARATOR_DETECT's structural rules.
549
+ # The detection profile — every lenience on, Western grouping, ./, roles resolved per
550
+ # input by SEPARATOR_DETECT's structural rules.
313
551
  NumFormat::DETECT = NumFormat.new(decimal_sep: ".", group_sep: ",",
314
552
  flags: ALL_STYLES | SEPARATOR_DETECT)
315
553
 
@@ -326,6 +564,184 @@ module HyperCast
326
564
  # en-GB order) only because the caller said which.
327
565
  DATE_ORDERS = { year_month_day: 1, month_day_year: 2, day_month_year: 3 }.freeze
328
566
 
567
+ # The date shapes the doors read only when the caller opts in: a flag set (the doors' own
568
+ # shapes stay exactly as they are without it) and a pivot for two-digit years. Passed as
569
+ # `options:` to the doors that read them — COMPACT_DATE at #date, SPACE_SEPARATOR and
570
+ # HOUR_OFFSET at #timestamp, the pivot at #date with an order and at #datetime — and a known
571
+ # option a door does not read is ignored. #flags is an Integer of the defined bits and nothing
572
+ # else (any other bit is an ArgumentError); #pivot is nil for none, or the last year of the
573
+ # 100-year window a two-digit year is read in, 100 through 9999: with a pivot of 2029, "26"
574
+ # is 2026 and "30" is 1930. A pivot of 0 is none, too.
575
+ DateOptions = Data.define(:flags, :pivot) do
576
+ # Validates the flags and the pivot up front, so options a door could not honour are the
577
+ # caller bug they are, never a verdict.
578
+ def initialize(flags: 0, pivot: nil)
579
+ raise ArgumentError, "date option flags must be an Integer; got #{flags.inspect}" unless flags.is_a?(Integer)
580
+ raise ArgumentError, "date option flags #{flags} set a bit this version does not define" unless
581
+ flags.nobits?(~self.class::DEFINED)
582
+ unless pivot.nil? || (pivot.is_a?(Integer) && (pivot.zero? || pivot.between?(100, 9999)))
583
+ raise ArgumentError, "date pivot must be nil, 0, or 100 to 9999; got #{pivot.inspect}"
584
+ end
585
+
586
+ super(flags: flags, pivot: pivot&.zero? ? nil : pivot)
587
+ end
588
+
589
+ # The 12 bytes the native layout carries, in the host's byte order: the size (12), the
590
+ # flags and the pivot (0 for none), as u32s.
591
+ def packed
592
+ [self.class::PACKED_BYTES, flags, pivot || 0].pack("L3")
593
+ end
594
+ end
595
+
596
+ # `cast_date` also reads `yyyyMMdd`, eight ASCII digits.
597
+ DateOptions::COMPACT_DATE = 1
598
+ # `cast_timestamp` also reads a single space where the `T` goes.
599
+ DateOptions::SPACE_SEPARATOR = 2
600
+ # `cast_timestamp` also reads an offset of `±hh`, with no minutes (`+00`, `-05`).
601
+ DateOptions::HOUR_OFFSET = 4
602
+ # Every flag this version defines.
603
+ DateOptions::DEFINED = DateOptions::COMPACT_DATE | DateOptions::SPACE_SEPARATOR | DateOptions::HOUR_OFFSET
604
+ # The size of DateOptions#packed, the native layout, in bytes.
605
+ DateOptions::PACKED_BYTES = 12
606
+ # COMPACT_DATE, SPACE_SEPARATOR and HOUR_OFFSET together: the shapes real feeds mix with
607
+ # RFC 3339. It supplies no pivot and no month names (`COMMON_FORMS.with(pivot: 2029)` adds one).
608
+ DateOptions::COMMON_FORMS = DateOptions.new(flags: DateOptions::DEFINED)
609
+
610
+ # Declared month names for the doors that read a month field (#date with an order, and
611
+ # #datetime): "Jan", "janvier", "janv.". Built by the caller, never looked up for a locale —
612
+ # aliases, abbreviations and grammatical forms are the caller's decisions — from a Hash of
613
+ # name => month, or an Array of [month, name] pairs (the order the native layout packs them in).
614
+ # Passed as `months:` it replaces the numeric month field, in the position the declared field
615
+ # order selects and with the date's own `/`, `-` or `.` separator: "07-Jan-26" reads with a
616
+ # pivot, "7-Jan-2026" without one, and a vocabulary never reorders fields.
617
+ #
618
+ # Names match under simple case folding, the longest name followed by the separator winning;
619
+ # punctuation is part of a name and never stripped, so with "janv." declared and "." as the
620
+ # separator "7.janv..2026" reads and "7.janv.2026" is :malformed unless "janv" is declared too.
621
+ # The vocabulary rules, each an ArgumentError here: every entry a month 1 through 12 and a
622
+ # String with a UTF-8 form of 1 to 64 bytes holding no ASCII digit, "/", "-" or white space ("."
623
+ # is fine anywhere); every month named at least once; no two names equal under case folding,
624
+ # even for one month.
625
+ MonthNames = Data.define(:entries) do
626
+ # Judges the entries against the rules, then has the core judge the vocabulary once more
627
+ # (the one rule Ruby cannot restate is the core's simple case folding), through the date
628
+ # door: on the Fiddle backend that is a native call, so building a vocabulary raises a
629
+ # LoadError, as every door does, when the shared library is missing.
630
+ def initialize(entries:)
631
+ list = self.class.send(:judged, self.class.send(:pairs, entries))
632
+ @packed = self.class.send(:pack, list)
633
+ super(entries: list)
634
+ self.class.send(:core_judges, self)
635
+ end
636
+
637
+ # The vocabulary in the packed layout the native core reads: each entry a month byte, a
638
+ # little-endian u32 byte length and the name's UTF-8 bytes, with no padding.
639
+ def packed
640
+ @packed
641
+ end
642
+
643
+ # Marshal's form: the entries, so a loaded vocabulary is judged again as a new one is.
644
+ def marshal_dump
645
+ entries
646
+ end
647
+
648
+ # Restores a vocabulary from #marshal_dump's entries through #initialize.
649
+ def marshal_load(list)
650
+ initialize(entries: list)
651
+ end
652
+
653
+ # The vocabulary read from its packed layout (what #packed returns), judged by the same rules
654
+ # as one built from entries; an entry cut short or bytes trailing the last one is an
655
+ # ArgumentError, as is a name that is not UTF-8.
656
+ def self.from_packed(bytes)
657
+ raise ArgumentError, "packed month names must be a String; got #{bytes.inspect}" unless bytes.is_a?(String)
658
+
659
+ bytes = bytes.b
660
+ list = []
661
+ at = 0
662
+ while at < bytes.bytesize
663
+ head = bytes.byteslice(at, self::ENTRY_HEAD)
664
+ raise ArgumentError, "month names are cut short, or bytes trail the last entry" if
665
+ head.bytesize < self::ENTRY_HEAD
666
+
667
+ month, length = head.unpack("CL<")
668
+ # Measured before slicing: where a C long is 32 bits (Windows), byteslice raises RangeError
669
+ # for a declared length past 2^31 - 1.
670
+ raise ArgumentError, "month names are cut short, or bytes trail the last entry" if
671
+ length > bytes.bytesize - at - self::ENTRY_HEAD
672
+
673
+ name = bytes.byteslice(at + self::ENTRY_HEAD, length)
674
+ list << [month, name.force_encoding(Encoding::UTF_8)]
675
+ at += self::ENTRY_HEAD + length
676
+ end
677
+ new(entries: list)
678
+ end
679
+
680
+ # Entries as [month, name] pairs: from a Hash of name => month, or any Enumerable of pairs.
681
+ def self.pairs(entries)
682
+ case entries
683
+ when Hash then entries.map { |name, month| [month, name] }
684
+ else
685
+ raise ArgumentError, "month names must be a Hash or an Array of [month, name] pairs; " \
686
+ "got #{entries.inspect}" unless entries.respond_to?(:to_a)
687
+
688
+ entries.to_a.map do |pair|
689
+ raise ArgumentError, "a month name entry must be a [month, name] pair; got #{pair.inspect}" unless
690
+ pair.respond_to?(:to_ary) && pair.to_ary.size == 2
691
+
692
+ pair.to_ary
693
+ end
694
+ end
695
+ end
696
+
697
+ # The entries as frozen [month, UTF-8 name] pairs, once every rule holds, in the order the
698
+ # core meets them: each entry's month, UTF-8 form, length and characters; then each month's
699
+ # entry.
700
+ def self.judged(pairs)
701
+ list = pairs.map do |month, name|
702
+ raise ArgumentError, "month #{month.inspect} must be an Integer from 1 to 12" unless
703
+ month.is_a?(Integer) && month.between?(1, 12)
704
+ raise ArgumentError, "month name must be a String; got #{name.inspect}" unless name.is_a?(String)
705
+
706
+ text = name.encoding == Encoding::BINARY ? name.dup.force_encoding(Encoding::UTF_8) : name
707
+ text = HyperCast.send(:declared_utf8, "month name", text)
708
+ raise ArgumentError, "month name #{name.inspect} must be 1 to 64 UTF-8 bytes" unless
709
+ text.bytesize.between?(1, 64)
710
+ raise ArgumentError, "month name #{name.inspect} must not contain an ASCII digit, a slash, a hyphen " \
711
+ "or white space" if text.match?(%r{[0-9/-]|#{WHITE_SPACE.source}})
712
+
713
+ [month, text.dup.freeze].freeze
714
+ end
715
+ missing = (1..12).reject { |month| list.any? { |entry, _| entry == month } }
716
+ raise ArgumentError, "month names must name every month; none for #{missing.join(', ')}" unless missing.empty?
717
+
718
+ list.freeze
719
+ end
720
+
721
+ # The vocabulary in its packed layout, a frozen binary String.
722
+ def self.pack(list)
723
+ list.map { |month, name| [month, name.bytesize].pack("CL<") + name.b }.join.b.freeze
724
+ end
725
+
726
+ # The core's last word on a vocabulary Ruby accepted, which only a folded duplicate can
727
+ # still fail: the core's simple case folding is not String#downcase(:fold)'s full one.
728
+ def self.core_judges(names)
729
+ HyperCast.date("", :year_month_day, months: names)
730
+ rescue RefusedDeclaration
731
+ raise ArgumentError, "two month names fold to the same spelling"
732
+ end
733
+ private_class_method :pairs, :judged, :pack, :core_judges
734
+ end
735
+
736
+ # A declaration Ruby accepted and the core refused: date options or month names that passed
737
+ # their own checks and still broke a rule only the core judges (a folded duplicate), or that
738
+ # were built without going through their constructors (Data#allocate, Marshal). The
739
+ # constructors turn it into the ArgumentError they document; a door raises it as it is.
740
+ class RefusedDeclaration < ArgumentError; end
741
+
742
+ # The bytes an entry takes before its name in MonthNames#packed: the month byte and the length.
743
+ MonthNames::ENTRY_HEAD = 5
744
+
329
745
  # An exact decimal, the decimal door's value: an unbounded Integer magnitude (the core's
330
746
  # 96-bit unsigned, so at most 2**96 - 1), an Integer base-10 scale (0..28 — the number of
331
747
  # places the magnitude is shifted right), and a negative flag. The value is
@@ -366,6 +782,363 @@ module HyperCast
366
782
  end
367
783
  end
368
784
 
785
+ # The doors a Constraints can be bound to, mapped to the native core's door codes: the
786
+ # integer, real and decimal doors, and :text.
787
+ CHECKED_DOORS = {
788
+ i8: 2, i16: 3, i32: 4, i64: 5, u8: 6, u16: 7, u32: 8, u64: 9, f32: 10, f64: 11, text: 18, decimal: 19
789
+ }.freeze
790
+
791
+ # Every door that reads text, by name, mapped to the native core's door code (the numbering
792
+ # of its detailed exports).
793
+ DETAILED_DOORS = {
794
+ bool: 1, i8: 2, i16: 3, i32: 4, i64: 5, u8: 6, u16: 7, u32: 8, u64: 9, f32: 10, f64: 11, uuid: 12,
795
+ timestamp: 13, unix: 14, date: 15, time: 16, duration: 17, text: 18, decimal: 19, date_ordered: 20,
796
+ datetime: 21, excel_serial: 22, char: 23
797
+ }.freeze
798
+
799
+ # What a value that is not a multiple of a declared multiple_of becomes, mapped to the
800
+ # native core's rounding codes: :strict (a :multiple_of Violation, the default), :midpoint
801
+ # (the nearest multiple, ties to even), :floor (toward negative infinity) and :ceiling
802
+ # (toward positive infinity). An unknown rounding is a caller bug (KeyError).
803
+ ROUNDINGS = { strict: 0, midpoint: 1, floor: 2, ceiling: 3 }.freeze
804
+
805
+ # The success case of a checked door: the value (rounded to multiple_of when the declaration
806
+ # rounds; at the :text door with an enum, the very String the declaration was given),
807
+ # adjusted (true only when rounding changed the value) and, at the :text door with an enum,
808
+ # the index of the entry matched — nil otherwise, a numeric enum included, where the value
809
+ # is the answer.
810
+ Checked = Data.define(:value, :adjusted, :enum_index)
811
+
812
+ # A value that cast and broke a declared rule: the Keyword broken, the value exactly as the
813
+ # door cast it (in the door's own type, as a Checked's value is, and never rounded: a
814
+ # rounding is part of the judgement, not of the value; at :text the judged String, after
815
+ # trim, never an enum entry) and the value's span, in the units a Fault's span is in
816
+ # (characters for text, bytes for a binary String). A number the caller already held has no
817
+ # text, and an empty span. A Fault means the input is not the door's type at all; a
818
+ # Violation means it is, and breaks a rule.
819
+ Violation = Data.define(:keyword, :value, :offset, :length)
820
+
821
+ # The rule a Violation broke: the native core's code, named the OpenAPI way by #name
822
+ # ("exclusiveMinimum"). Open to additions — format and pattern may join in a minor release —
823
+ # so a case over keywords needs an else branch; a code this gem does not name yet is kept,
824
+ # its name "keyword N". The constants (Keyword::MINIMUM ... Keyword::ENUM) compare equal to
825
+ # every keyword of their code, so `in Violation(keyword: Keyword::MINIMUM)` matches.
826
+ Keyword = Data.define(:code) do
827
+ # The OpenAPI spelling: "minimum", "exclusiveMinimum", ... "enum"; "keyword N" for a code
828
+ # this gem does not name.
829
+ def name
830
+ self.class::NAMES.fetch(code) { "keyword #{code}" }
831
+ end
832
+
833
+ alias_method :to_s, :name
834
+
835
+ # The constant that names this keyword (HyperCast::Keyword::MINIMUM), or the Data form
836
+ # for a code this gem does not name.
837
+ def inspect
838
+ constant = self.class::CONSTANTS[code]
839
+ constant ? "HyperCast::Keyword::#{constant}" : super
840
+ end
841
+ end
842
+
843
+ # The OpenAPI spelling of each keyword the core names, by code.
844
+ Keyword::NAMES = {
845
+ 1 => "minimum", 2 => "exclusiveMinimum", 3 => "maximum", 4 => "exclusiveMaximum", 5 => "multipleOf",
846
+ 6 => "minLength", 7 => "maxLength", 8 => "enum"
847
+ }.freeze
848
+
849
+ # The constant each named keyword is published as, by code.
850
+ Keyword::CONSTANTS = {
851
+ 1 => "MINIMUM", 2 => "EXCLUSIVE_MINIMUM", 3 => "MAXIMUM", 4 => "EXCLUSIVE_MAXIMUM", 5 => "MULTIPLE_OF",
852
+ 6 => "MIN_LENGTH", 7 => "MAX_LENGTH", 8 => "ENUM"
853
+ }.freeze
854
+
855
+ # `minimum`, broken by a value below it.
856
+ Keyword::MINIMUM = Keyword.new(code: 1)
857
+ # `exclusiveMinimum`, broken by a value at or below it.
858
+ Keyword::EXCLUSIVE_MINIMUM = Keyword.new(code: 2)
859
+ # `maximum`, broken by a value above it.
860
+ Keyword::MAXIMUM = Keyword.new(code: 3)
861
+ # `exclusiveMaximum`, broken by a value at or above it.
862
+ Keyword::EXCLUSIVE_MAXIMUM = Keyword.new(code: 4)
863
+ # `multipleOf`, broken by a value that is not a multiple of it under :strict rounding.
864
+ Keyword::MULTIPLE_OF = Keyword.new(code: 5)
865
+ # `minLength`, broken by text of fewer code points.
866
+ Keyword::MIN_LENGTH = Keyword.new(code: 6)
867
+ # `maxLength`, broken by text of more code points.
868
+ Keyword::MAX_LENGTH = Keyword.new(code: 7)
869
+ # `enum`, broken by a value that is none of the entries.
870
+ Keyword::ENUM = Keyword.new(code: 8)
871
+
872
+ # Validation constraints — the OpenAPI 3.2 Schema Object's keywords — bound to one door and
873
+ # judged once, by the native core, when built: every declaration OpenAPI allows is accepted,
874
+ # an unsatisfiable one included (crossed bounds, an empty enum: every value then violates
875
+ # it), and a keyword for another type is ignored, as JSON Schema ignores it. What the core
876
+ # refuses is an ArgumentError here, its message the rule it breaks ("Constraints refused
877
+ # (code 5): multipleOf is not positive."), and every checked cast after that judges only
878
+ # data. The door is required: no declaration ever silently means "no rules", and
879
+ # `Constraints.new(door: :f64)` is an explicit, empty one.
880
+ #
881
+ # The numeric doors take minimum, exclusive_minimum, maximum and exclusive_maximum (four
882
+ # independent keywords, all four together if declared so), multiple_of with a rounding (a
883
+ # ROUNDINGS Symbol), and enum, matched exactly against the value; :text min_length,
884
+ # max_length (in code points), enum (matched under simple case folding unless
885
+ # case_sensitive: true, which compares byte for byte), and HyperCast's own extensions trim
886
+ # (of Unicode White_Space) and case_sensitive. Every keyword is accepted at every door; the
887
+ # core alone refuses trim, case_sensitive or a rounding where they mean nothing.
888
+ #
889
+ # A bound, step or numeric enum entry is an Integer, a BigDecimal, a String in invariant
890
+ # notation ("0.000001", "-90", "1e-6") or this gem's own Decimal, and crosses the core's own
891
+ # conversion (HyperCast.declared_decimal): never a Float, since 0.1 has no exact binary form
892
+ # and a Float could only declare a neighbour of the value meant. Bounds are kept as the exact
893
+ # Decimal declared. A text enum entry is a String, kept as the very object given when it is
894
+ # frozen and as a frozen copy when it is not, so a match delivers what the core judged. An
895
+ # enum left nil declares none, while `enum: []` declares one no value matches. With
896
+ # duplicate entries, the first match wins.
897
+ #
898
+ # latitude = HyperCast::Constraints.new(door: :f64, minimum: "-90", maximum: "90")
899
+ # HyperCast.checked("91", HyperCast::NumFormat::INVARIANT, latitude)
900
+ # # => #<data HyperCast::Violation keyword=HyperCast::Keyword::MAXIMUM, value=91.0, offset=0, length=2>
901
+ Constraints = Data.define(:door, :minimum, :exclusive_minimum, :maximum, :exclusive_maximum, :multiple_of,
902
+ :rounding, :min_length, :max_length, :trim, :case_sensitive, :enum) do
903
+ # Validates every keyword's type, converts the bounds, steps and numeric entries through
904
+ # the core, and has the core judge the declaration; a refusal is an ArgumentError worded
905
+ # from its code. A wrong type is an ArgumentError, an unknown door or rounding a KeyError.
906
+ def initialize(door:, minimum: nil, exclusive_minimum: nil, maximum: nil, exclusive_maximum: nil,
907
+ multiple_of: nil, rounding: :strict, min_length: nil, max_length: nil, trim: false,
908
+ case_sensitive: false, enum: nil)
909
+ keywords = { door: door, minimum: minimum, exclusive_minimum: exclusive_minimum, maximum: maximum,
910
+ exclusive_maximum: exclusive_maximum, multiple_of: multiple_of, rounding: rounding,
911
+ min_length: min_length, max_length: max_length, trim: trim, case_sensitive: case_sensitive,
912
+ enum: enum }
913
+ code = HyperCast.constraints_check(**keywords)
914
+ raise ArgumentError, self.class.send(:refusal, code) unless code.zero?
915
+
916
+ super(**self.class.send(:members_of, **keywords))
917
+ end
918
+
919
+ # The 104 bytes this declaration crosses a C ABI as, in the native byte order the core
920
+ # reads in place: the size (104), the flags, the rounding code, min_length, max_length and
921
+ # a reserved zero as u32s, then minimum, maximum, multiple_of, exclusive_minimum and
922
+ # exclusive_maximum as 16-byte decimals (the low 64 and high 32 bits of the magnitude, the
923
+ # scale, the sign, two zero bytes) — for a gem that judges values across a C ABI of its
924
+ # own, with #packed_enum beside it.
925
+ def packed
926
+ self.class.send(:pack_raw, to_h)
927
+ end
928
+
929
+ # The enum list as the core reads it beside #packed, "" for none (read only when the
930
+ # flags in #packed carry HAS_ENUM, 256, set whenever an enum is declared): at a numeric
931
+ # door 16-byte decimals in native byte order, at :text each entry a little-endian u32 byte
932
+ # length followed by its UTF-8.
933
+ def packed_enum
934
+ self.class.send(:pack_enum, to_h)
935
+ end
936
+
937
+ # The message a refused declaration raises with, one per refusal code; a code this gem
938
+ # does not name is worded as every binding words it.
939
+ def self.refusal(code)
940
+ "Constraints refused (code #{code}): #{self::REFUSALS.fetch(code, 'a rule this binding does not name')}."
941
+ end
942
+
943
+ # The declaration as both backends hand it to the core: the door code, #packed and
944
+ # #packed_enum. Judged again here, once per object (each backend remembers the answer),
945
+ # because a Constraints can exist without Constraints.new having judged it: one never
946
+ # built (Data's allocate) has no door, and one restored by Marshal from a payload in the
947
+ # Struct form sets its members directly. Either is the caller's bug, raised as
948
+ # Constraints.new raises it, never a declaration of no rules.
949
+ def declaration
950
+ raise ArgumentError, "this HyperCast::Constraints was never built: declare it with Constraints.new(door: ...)" if
951
+ door.nil?
952
+
953
+ code = HyperCast.constraints_check(**to_h)
954
+ raise ArgumentError, self.class.send(:refusal, code) unless code.zero?
955
+
956
+ [CHECKED_DOORS.fetch(door), packed, packed_enum]
957
+ end
958
+ private :declaration
959
+
960
+ # Marshal's form of a declaration: its members, so loading one builds it through
961
+ # #initialize, judged as Constraints.new judges it.
962
+ def marshal_dump
963
+ to_h
964
+ end
965
+
966
+ # Restores a declaration from #marshal_dump's members through #initialize, so a payload
967
+ # that declares something the core refuses raises its refusal.
968
+ def marshal_load(members)
969
+ initialize(**members)
970
+ end
971
+
972
+ # The declaration HyperCast.constraints_check judges: its door code, packed layout and
973
+ # packed enum, or the code 8 the conversion of a bound, step or entry was refused with.
974
+ def self.layout(**keywords)
975
+ members = members_of(**keywords)
976
+ return members if members.is_a?(Integer)
977
+
978
+ [CHECKED_DOORS.fetch(members[:door]), pack_raw(members), pack_enum(members)]
979
+ end
980
+
981
+ # Every keyword validated and converted — a declaration's members — or the code 8 a
982
+ # conversion was refused with.
983
+ def self.members_of(door:, minimum: nil, exclusive_minimum: nil, maximum: nil, exclusive_maximum: nil,
984
+ multiple_of: nil, rounding: :strict, min_length: nil, max_length: nil, trim: false,
985
+ case_sensitive: false, enum: nil)
986
+ CHECKED_DOORS.fetch(door)
987
+ ROUNDINGS.fetch(rounding)
988
+ raise ArgumentError, "trim must be true or false; got #{trim.inspect}" unless [true, false].include?(trim)
989
+ raise ArgumentError, "case_sensitive must be true or false; got #{case_sensitive.inspect}" unless
990
+ [true, false].include?(case_sensitive)
991
+
992
+ bounds = { minimum: minimum, exclusive_minimum: exclusive_minimum, maximum: maximum,
993
+ exclusive_maximum: exclusive_maximum, multiple_of: multiple_of }
994
+ bounds.each do |name, value|
995
+ next if value.nil?
996
+
997
+ bounds[name] = exact(name, value)
998
+ return bounds[name] if bounds[name].is_a?(Integer)
999
+ end
1000
+ entries = entries_of(door, enum)
1001
+ return entries if entries.is_a?(Integer)
1002
+
1003
+ { door: door, **bounds, rounding: rounding, min_length: length("min_length", min_length),
1004
+ max_length: length("max_length", max_length), trim: trim, case_sensitive: case_sensitive, enum: entries }
1005
+ end
1006
+
1007
+ # A bound, step or numeric enum entry as the core converts it: an Integer, a BigDecimal,
1008
+ # a String or a Decimal, each through its text and HyperCast.declared_decimal — the exact
1009
+ # Decimal, or the code 8 it was refused with. Never a Float, nor true or false.
1010
+ def self.exact(name, value)
1011
+ text =
1012
+ case value
1013
+ when Integer, String, Decimal then value.to_s
1014
+ else
1015
+ raise ArgumentError, "#{name} must be an Integer, a BigDecimal, a String or a HyperCast::Decimal; got " \
1016
+ "#{value.inspect}#{hint(value)}" unless defined?(BigDecimal) && value.is_a?(BigDecimal)
1017
+
1018
+ value.to_s("F")
1019
+ end
1020
+ begin
1021
+ HyperCast.declared_decimal(text)
1022
+ rescue ArgumentError
1023
+ 8
1024
+ end
1025
+ end
1026
+
1027
+ # Why a Float is refused, beside the refusal.
1028
+ def self.hint(value)
1029
+ return "" unless value.is_a?(Float)
1030
+
1031
+ " (a Float holds most decimals only approximately: write it as a String or a BigDecimal)"
1032
+ end
1033
+
1034
+ # A declared length: nil, or an Integer in the 32 unsigned bits the core counts code
1035
+ # points in (never true or false, nor a Float).
1036
+ def self.length(name, value)
1037
+ return nil if value.nil?
1038
+ raise ArgumentError, "#{name} must be an Integer from 0 to #{0xFFFF_FFFF}; got #{value.inspect}" unless
1039
+ value.is_a?(Integer) && value.between?(0, 0xFFFF_FFFF)
1040
+
1041
+ value
1042
+ end
1043
+
1044
+ # The enum entries, frozen, as a declaration keeps them: at :text the caller's own
1045
+ # Strings, elsewhere each entry's exact Decimal (or the code 8 one was refused with); nil
1046
+ # for none. An empty list is declared: one no value matches.
1047
+ def self.entries_of(door, enum)
1048
+ return nil if enum.nil?
1049
+ raise ArgumentError, "enum must be an Array of entries; got #{enum.inspect}" unless
1050
+ enum.respond_to?(:to_a) && !enum.is_a?(String)
1051
+
1052
+ entries = enum.to_a
1053
+ if door == :text
1054
+ entries = entries.each_with_index.map do |entry, index|
1055
+ # A number is a valid entry that no String equals (JSON Schema's enum is exact
1056
+ # equality across types): kept as given, and packed empty by pack_enum.
1057
+ next entry if number_entry?(entry)
1058
+
1059
+ raise ArgumentError, "enum entries at :text must be Strings, or numbers (an Integer, a BigDecimal or a " \
1060
+ "HyperCast::Decimal), which never match; entry #{index} is #{entry.inspect}" unless
1061
+ entry.is_a?(String)
1062
+
1063
+ # A Hash key's rule: a frozen String is kept as itself, a mutable one as a frozen
1064
+ # copy, so what a match delivers is always what the core judged.
1065
+ entry.frozen? ? entry : entry.dup.freeze
1066
+ end
1067
+ else
1068
+ entries = entries.map do |entry|
1069
+ decimal = exact("enum entry", entry)
1070
+ return decimal if decimal.is_a?(Integer)
1071
+
1072
+ decimal
1073
+ end
1074
+ end
1075
+ entries.freeze
1076
+ end
1077
+
1078
+ # A declaration's members as the 104-byte native layout #packed describes: each bound in
1079
+ # a slot of its own.
1080
+ def self.pack_raw(members)
1081
+ flags = self::FLAGS.sum { |member, flag| members[member].nil? ? 0 : flag }
1082
+ flags |= 128 if members[:trim]
1083
+ flags |= 512 if members[:case_sensitive]
1084
+ decimals = members.values_at(:minimum, :maximum, :multiple_of, :exclusive_minimum, :exclusive_maximum)
1085
+ [self::PACKED_BYTES, flags, ROUNDINGS.fetch(members[:rounding]), members[:min_length] || 0,
1086
+ members[:max_length] || 0, 0].pack("L6") + decimals.map { |decimal| pack_decimal(decimal) }.join
1087
+ end
1088
+
1089
+ # One Decimal in the core's native 16-byte layout; zero for nil.
1090
+ def self.pack_decimal(decimal)
1091
+ return [0, 0, 0, 0].pack("QLCCx2") if decimal.nil?
1092
+
1093
+ magnitude = decimal.magnitude
1094
+ [magnitude & 0xFFFF_FFFF_FFFF_FFFF, magnitude >> 64, decimal.scale, decimal.negative ? 1 : 0].pack("QLCCx2")
1095
+ end
1096
+
1097
+ # Whether a text enum entry is a number: valid, and never matched.
1098
+ def self.number_entry?(entry)
1099
+ entry.is_a?(Integer) || entry.is_a?(Decimal) || (defined?(BigDecimal) && entry.is_a?(BigDecimal))
1100
+ end
1101
+
1102
+ # A declaration's enum as #packed_enum describes it, a binary String.
1103
+ def self.pack_enum(members)
1104
+ entries = members[:enum] or return "".b
1105
+ return entries.map { |entry| pack_decimal(entry) }.join.b unless members[:door] == :text
1106
+
1107
+ # Each entry as input text crosses (HyperCast.utf8): one with no UTF-8 form is then
1108
+ # refused as an entry that is not UTF-8 (9), never transcoded with a guess.
1109
+ entries.map do |entry|
1110
+ # A number packs as an empty entry, which no input matches (empty input is the door's
1111
+ # Empty fault), so every other entry keeps its index.
1112
+ next [0].pack("L<") unless entry.is_a?(String)
1113
+
1114
+ text = HyperCast.send(:utf8, entry)
1115
+ [text.bytesize].pack("L<") + text.b
1116
+ end.join.b
1117
+ end
1118
+
1119
+ private_class_method :refusal, :layout, :members_of, :exact, :hint, :length, :entries_of, :number_entry?, :pack_raw,
1120
+ :pack_decimal, :pack_enum
1121
+ end
1122
+
1123
+ # The flag each declared member sets in the packed layout, HAS_ENUM (256) by an enum even
1124
+ # with no entries; TRIM (128) is set by trim and CASE_SENSITIVE (512) by case_sensitive.
1125
+ Constraints::FLAGS = { minimum: 1, exclusive_minimum: 2, maximum: 4, exclusive_maximum: 8, multiple_of: 16,
1126
+ min_length: 32, max_length: 64, enum: 256 }.freeze
1127
+
1128
+ # The size of Constraints#packed, the native RawConstraints layout, in bytes.
1129
+ Constraints::PACKED_BYTES = 104
1130
+
1131
+ # The words a refused declaration's message gives, one per code: the native core's own. The
1132
+ # codes between belonged to refusals of declarations OpenAPI allows; they are retired.
1133
+ Constraints::REFUSALS = {
1134
+ 1 => "a constraint the door does not take",
1135
+ 5 => "multipleOf is not positive",
1136
+ 6 => "a rounding without multipleOf",
1137
+ 8 => "a bound, step or enum entry the door cannot hold",
1138
+ 9 => "an enum entry that is not UTF-8",
1139
+ 11 => "a malformed constraints layout"
1140
+ }.freeze
1141
+
369
1142
  class << self
370
1143
  # Presents a verdict optionally: an :empty fault becomes nil (Ruby's absent),
371
1144
  # everything else flows through untouched.
@@ -391,28 +1164,36 @@ module HyperCast
391
1164
  false
392
1165
  end
393
1166
  end
1167
+ end
394
1168
 
1169
+ # The doors, the Fiddle way. They live in a module HyperCast extends rather than on its
1170
+ # singleton class, so the Magnus extension's define_singleton_method puts its definition on
1171
+ # the singleton class in front of them: an override through the ancestor chain, not a
1172
+ # redefinition, and `ruby -w` has nothing to say about it (1.0.0 defined them on the
1173
+ # singleton class and printed "method redefined" twice per door on every require under -w).
1174
+ # Lookup is unchanged either way: the singleton class first, then this module, so with the
1175
+ # extension loaded no call ever reaches these. Their helpers stay private on HyperCast.
1176
+ module FiddleBackend
395
1177
  # Casts boolean text: true/false plus the conventions untrusted sources actually send
396
1178
  # (t/f, yes/no, y/n, 1/0, on/off, enabled/disabled, active/inactive,
397
1179
  # checked/unchecked, in/out), ASCII case-insensitive.
398
1180
  def bool(text)
399
- plain(:cast_bool, text, 1) { |out| Interop.decode(:bool, out) }
1181
+ crossing(1, 0, text, 1) { |out| Interop.decode(:bool, out) }
400
1182
  end
401
1183
 
402
1184
  # Casts char text to a one-character UTF-8 String: an input of exactly one character is
403
1185
  # that character verbatim (" " is a space), otherwise one declared code point — 65,
404
- # U+0041, 0x41, &H41, &#65; or &#x41; — surrounded by optional ASCII whitespace. A code
1186
+ # U+0041, 0x41, &H41, &#65; or &#x41; — surrounded by optional white space. A code
405
1187
  # point past U+10FFFF, or a surrogate, is :out_of_range.
406
1188
  def char(text)
407
- plain(:cast_char, text, 4) { |out| Interop.decode(:char, out) }
1189
+ crossing(23, 0, text, 4) { |out| Interop.decode(:char, out) }
408
1190
  end
409
1191
 
410
1192
  %i[i8 i16 i32 i64 u8 u16 u32 u64].each do |door|
411
1193
  unpack = Interop::SCALARS.fetch(door)
412
1194
  size = Interop::VALUE_BYTES.fetch(door)
413
- # Resolved once here, not inside the method: interpolating a Symbol per call built a
414
- # String and interned it on every integer cast.
415
- symbol = :"cast_#{door}"
1195
+ # Resolved once here, not inside the method.
1196
+ code = DETAILED_DOORS.fetch(door)
416
1197
  # Integer doors: the target type's own range, declared grouping, accounting parens,
417
1198
  # non-negative exponent, and 0x/&H/0b two's-complement radix prefixes. Ruby Integer
418
1199
  # is unbounded, so u64 comes back as the true unsigned value. separator:, delimiter:
@@ -420,7 +1201,7 @@ module HyperCast
420
1201
  define_method(door) do |text, format, separator: nil, delimiter: nil, unit: nil|
421
1202
  format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
422
1203
  separator || delimiter || unit
423
- numeric(symbol, text, format, size) { |out| out.unpack1(unpack) }
1204
+ crossing(code, 0, text, size, format) { |out| out.unpack1(unpack) }
424
1205
  end
425
1206
  end
426
1207
 
@@ -431,14 +1212,14 @@ module HyperCast
431
1212
  def f32(text, format, separator: nil, delimiter: nil, unit: nil)
432
1213
  format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
433
1214
  separator || delimiter || unit
434
- numeric(:cast_f32, text, format, 4) { |out| Interop.decode(:f32, out) }
1215
+ crossing(10, 0, text, 4, format) { |out| Interop.decode(:f32, out) }
435
1216
  end
436
1217
 
437
1218
  # Casts real text to an IEEE double. Notation rules as f32.
438
1219
  def f64(text, format, separator: nil, delimiter: nil, unit: nil)
439
1220
  format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
440
1221
  separator || delimiter || unit
441
- numeric(:cast_f64, text, format, 8) { |out| Interop.decode(:f64, out) }
1222
+ crossing(11, 0, text, 8, format) { |out| Interop.decode(:f64, out) }
442
1223
  end
443
1224
 
444
1225
  # Casts decimal text to an exact Decimal — the real doors' grammar (declared separators
@@ -450,27 +1231,30 @@ module HyperCast
450
1231
  def decimal(text, format, separator: nil, delimiter: nil, unit: nil)
451
1232
  format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
452
1233
  separator || delimiter || unit
453
- numeric(:cast_decimal, text, format, 16) { |out| Interop.decode(:decimal, out) }
1234
+ crossing(19, 0, text, 16, format) { |out| Interop.decode(:decimal, out) }
454
1235
  end
455
1236
 
456
1237
  # Casts UUID text — all five .NET Guid formats (D/N/B/P/X) plus urn:uuid:/GUID:/UUID:
457
1238
  # prefixes — to Ruby's UUID lingua franca: the lowercase hyphenated String (the same
458
1239
  # shape SecureRandom.uuid returns).
459
1240
  def uuid(text)
460
- plain(:cast_uuid, text, 16) { |out| Interop.decode(:uuid, out) }
1241
+ crossing(12, 0, text, 16) { |out| Interop.decode(:uuid, out) }
461
1242
  end
462
1243
 
463
1244
  # Casts an RFC 3339 instant — zone mandatory — to a UTC Time at full nanosecond
464
- # fidelity across the whole 0001-9999 window.
465
- def timestamp(text)
466
- plain(:cast_timestamp, text, 16) { |out| Interop.decode(:timestamp, out) }
1245
+ # fidelity across the whole 0001-9999 window. options: (a DateOptions) opens the shapes
1246
+ # RFC 3339 itself does not have, each only when asked for: SPACE_SEPARATOR a space where the
1247
+ # T goes, HOUR_OFFSET an offset of ±hh ("+00"); other options are ignored here.
1248
+ def timestamp(text, options: nil)
1249
+ dated(options, nil)
1250
+ crossing(13, 0, text, 16, nil, nil, options) { |out| Interop.decode(:timestamp, out) }
467
1251
  end
468
1252
 
469
1253
  # Casts an integer Unix-epoch value under a caller-declared unit Symbol
470
1254
  # (:seconds/:milliseconds/:microseconds/:nanoseconds) to a UTC Time. An unknown unit
471
1255
  # is a caller bug (KeyError), never a verdict.
472
1256
  def unix(text, precision)
473
- declared(:cast_unix, text, UNIX_PRECISIONS.fetch(precision), 16) { |out| Interop.decode(:unix, out) }
1257
+ crossing(14, UNIX_PRECISIONS.fetch(precision), text, 16) { |out| Interop.decode(:unix, out) }
474
1258
  end
475
1259
 
476
1260
  # Casts an Excel date serial under a caller-declared epoch Symbol (:y1900/:y1904) to a
@@ -484,7 +1268,7 @@ module HyperCast
484
1268
  # the text "1900-02-29" — so every serial above it is shifted one day against a naive
485
1269
  # count. An unknown epoch is a caller bug (KeyError), never a verdict.
486
1270
  def excel_serial(text, epoch)
487
- declared(:cast_excel_serial, text, EXCEL_EPOCHS.fetch(epoch), 16) { |out| Interop.decode(:excel_serial, out) }
1271
+ crossing(22, EXCEL_EPOCHS.fetch(epoch), text, 16) { |out| Interop.decode(:excel_serial, out) }
488
1272
  end
489
1273
 
490
1274
  # Casts a calendar date to a Date. With no order declared: the strict ISO 8601
@@ -492,11 +1276,19 @@ module HyperCast
492
1276
  # :month_day_year, :day_month_year), also the separated forms — "1/7/2026" is
493
1277
  # January 7th or July 1st only because the caller said which; an unknown order is a
494
1278
  # caller bug (KeyError), never a verdict.
495
- def date(text, order = nil)
1279
+ #
1280
+ # options: (a DateOptions) opens shapes only when asked for: COMPACT_DATE, "20260107", at the
1281
+ # ISO form; the pivot, two-digit years ("1/7/26"), with an order. months: (a MonthNames) opens
1282
+ # declared month names in the month field ("7-Jan-2026") with an order. Options a form does
1283
+ # not read are ignored.
1284
+ def date(text, order = nil, options: nil, months: nil)
1285
+ dated(options, months)
496
1286
  if order.nil?
497
- plain(:cast_date, text, 4) { |out| Interop.decode(:date, out) }
1287
+ crossing(15, 0, text, 4, nil, nil, options) { |out| Interop.decode(:date, out) }
498
1288
  else
499
- declared(:cast_date_ordered, text, DATE_ORDERS.fetch(order), 4) { |out| Interop.decode(:date_ordered, out) }
1289
+ crossing(20, DATE_ORDERS.fetch(order), text, 4, nil, nil, options, months) do |out|
1290
+ Interop.decode(:date_ordered, out)
1291
+ end
500
1292
  end
501
1293
  end
502
1294
 
@@ -512,30 +1304,36 @@ module HyperCast
512
1304
  # A 12-hour clock's AM/PM is read, before or after the clock ("3:04 PM", "PM 3:04"),
513
1305
  # ASCII case-insensitively; am: and pm: declare a culture's own designators beside
514
1306
  # them — "vorm."/"nachm.", "오전"/"오후", "a. m."/"p. m." — matched exactly, after the
515
- # clock ("3:04 nachm.") or ahead of it ("오후 3:04"), with or without a space between.
1307
+ # clock ("3:04 nachm.") or ahead of it ("오후 3:04"), with any run of white space or none between.
516
1308
  # Declared, never looked up, like a NumFormat's symbols; nil (the default) declares
517
1309
  # nothing, so a call without them is exactly the call it was. A designator is 1 to 16
518
- # UTF-8 bytes with no ASCII digit and no ASCII whitespace at either end (a space inside
1310
+ # UTF-8 bytes with no ASCII digit and no white space at either end (a space inside
519
1311
  # is fine); anything else is a caller bug (ArgumentError). The designators are read,
520
1312
  # validated and packed per call: a call that declares them costs about twice the plain
521
1313
  # call on the Magnus backend (the keyword scan itself — nil keywords pay the same) and
522
1314
  # about half again here on Fiddle.
523
- def datetime(text, order, am: nil, pm: nil)
1315
+ #
1316
+ # options: (a DateOptions) gives two-digit years a pivot, and months: (a MonthNames) opens
1317
+ # declared month names ("07-Jan-26 3:04 PM"), each only when asked for.
1318
+ def datetime(text, order, am: nil, pm: nil, options: nil, months: nil)
1319
+ dated(options, months)
524
1320
  periods = packed_day_periods(am, pm) if am || pm
525
- civil(:cast_datetime, text, DATE_ORDERS.fetch(order), periods, 16) { |out| Interop.decode(:datetime, out) }
1321
+ crossing(21, DATE_ORDERS.fetch(order), text, 16, nil, periods, options, months) do |out|
1322
+ Interop.decode(:datetime, out)
1323
+ end
526
1324
  end
527
1325
 
528
1326
  # Casts an ISO 24-hour time-of-day to an exact Integer of nanoseconds since midnight
529
1327
  # (Ruby has no time-of-day type; the integer keeps every digit).
530
1328
  def time(text)
531
- plain(:cast_time, text, 8) { |out| Interop.decode(:time, out) }
1329
+ crossing(16, 0, text, 8) { |out| Interop.decode(:time, out) }
532
1330
  end
533
1331
 
534
1332
  # Casts a duration (ISO 8601 fixed components, invariant colon form, or protobuf JSON
535
1333
  # seconds) to exact Rational seconds — full fidelity across the core's ±10,000-year
536
1334
  # window, no wrapping and no truncation.
537
1335
  def duration(text)
538
- plain(:cast_duration, text, 16) { |out| Interop.decode(:duration, out) }
1336
+ crossing(17, 0, text, 16) { |out| Interop.decode(:duration, out) }
539
1337
  end
540
1338
 
541
1339
  # Reads a number a caller already holds — an Integer, Float or Rational, the way Ruby's
@@ -546,7 +1344,7 @@ module HyperCast
546
1344
  # a magnitude past 2**96 - 1 or more than 28 places is :out_of_range. A typed door's
547
1345
  # Fault has no span: offset and length are 0.
548
1346
  def decimal_from_float(value)
549
- typed(:cast_decimal_from_f64, float(value), 16) { |out| Interop.decode(:decimal, out) }
1347
+ typed(19, 0, float(value), 16) { |out| Interop.decode(:decimal, out) }
550
1348
  end
551
1349
 
552
1350
  # Reads an Excel serial number under a declared epoch Symbol (:y1900/:y1904) as the
@@ -555,18 +1353,105 @@ module HyperCast
555
1353
  # is :out_of_range; a negative, NaN or infinite serial is :malformed.
556
1354
  def excel_serial_from_float(value, epoch)
557
1355
  number = float(value)
558
- typed(:cast_excel_serial_from_f64, number, 16, EXCEL_EPOCHS.fetch(epoch)) { |out| Interop.decode(:datetime, out) }
1356
+ typed(22, EXCEL_EPOCHS.fetch(epoch), number, 16) { |out| Interop.decode(:datetime, out) }
559
1357
  end
560
1358
 
561
1359
  # Reads the fraction of an Excel serial number as an exact Integer of nanoseconds since
562
1360
  # midnight, as time does; 0.75 and 45292.75 are both 18:00.
563
1361
  def excel_time(value)
564
- typed(:cast_excel_time, float(value), 8) { |out| Interop.decode(:time, out) }
1362
+ typed(16, 0, float(value), 8) { |out| Interop.decode(:time, out) }
565
1363
  end
566
1364
 
567
1365
  # Reads a number of days as exact Rational seconds, as duration does: 1.5 is 129600.
568
1366
  def excel_duration(value)
569
- typed(:cast_excel_duration, float(value), 16) { |out| Interop.decode(:duration, out) }
1367
+ typed(17, 0, float(value), 16) { |out| Interop.decode(:duration, out) }
1368
+ end
1369
+
1370
+ # Casts text as text: the input itself, as a String, once it is valid UTF-8 — a binary
1371
+ # String's bytes must be, and a UTF-8 String carrying invalid bytes is :malformed at the
1372
+ # first. Empty input is :empty; nothing is trimmed. The value is the String passed when it
1373
+ # is UTF-8 or US-ASCII, else a UTF-8 copy.
1374
+ #
1375
+ # With Constraints for :text it is judged by them, a Checked, a Fault or a Violation:
1376
+ # trimmed of Unicode White_Space when they say so (trimmed to nothing is :empty), lengths
1377
+ # counted in code points, and an enum matched under simple case folding (byte for byte
1378
+ # with case_sensitive), a match delivering the very String declared and its index; a
1379
+ # Violation's value is the judged text. Constraints for another door are an ArgumentError
1380
+ # (they go to checked).
1381
+ def text(text, constraints = nil)
1382
+ if constraints.nil?
1383
+ return crossing(18, 0, text, 8) { |out, bytes| text_value(bytes, *out.unpack("LL")) }
1384
+ end
1385
+
1386
+ bytes = utf8(text)
1387
+ _door, raw, entries = constrained(constraints, :text)
1388
+ rc = checked_call(CHECKED_DOORS.fetch(:text), nil, raw, entries, bytes)
1389
+ checked_verdict(rc, bytes) do |out, check|
1390
+ offset, length = out[0, 8].unpack("LL")
1391
+ index = check && check[8, 4].unpack1("L")
1392
+ index.nil? || index == 0xFFFF_FFFF ? text_value(bytes, offset, length) : constraints.enum.fetch(index)
1393
+ end
1394
+ end
1395
+
1396
+ # Casts numeric text through the door its Constraints are bound to, under the declared
1397
+ # format, then judges the value by them: a Checked, or the door's own Fault, or a
1398
+ # Violation of the first rule it breaks, carrying the value as cast. The value is judged exactly, on the decimal the
1399
+ # door read, never on a float. Spans are in the units a Fault's are. separator:,
1400
+ # delimiter: and unit: override those fields of format for this call
1401
+ # (NumFormat#override). Constraints for :text are an ArgumentError (they go to text).
1402
+ def checked(text, format, constraints, separator: nil, delimiter: nil, unit: nil)
1403
+ format = format.override(separator: separator, delimiter: delimiter, unit: unit) if
1404
+ separator || delimiter || unit
1405
+ bytes = utf8(text)
1406
+ symbol, raw, entries = constrained(constraints, :checked)
1407
+ rc = checked_call(CHECKED_DOORS.fetch(symbol), packed_cache[format], raw, entries, bytes)
1408
+ checked_verdict(rc, bytes) { |out| Interop.decode(symbol, out[0, Interop::VALUE_BYTES.fetch(symbol)]) }
1409
+ end
1410
+
1411
+ # Reads a number the caller already holds — an Integer, Float or Rational, taken as
1412
+ # decimal_from_float takes it — through the door its Constraints are bound to, then judges
1413
+ # it by them on the shortest decimal that names it: 0.1 + 0.2 is 0.30000000000000004,
1414
+ # which breaks multiple_of: "0.1" under :strict and rounds to 0.3 under :midpoint. NaN is
1415
+ # :malformed; an infinity is :out_of_range at a float or decimal door and :malformed at an
1416
+ # integer door. Every fault and violation has an empty span.
1417
+ def checked_from_float(value, constraints)
1418
+ number = float(value)
1419
+ symbol, raw, entries = constrained(constraints, :checked_from_float)
1420
+ out, fault = scratch
1421
+ rc = Runtime.function(:cast_checked_detailed_from_f64).call(CHECKED_DOORS.fetch(symbol), 0, raw,
1422
+ input_ptr(entries), entries.bytesize, number,
1423
+ out, fault, checked_scratch[1])
1424
+ checked_verdict(rc, nil) { |out| Interop.decode(symbol, out[0, Interop::VALUE_BYTES.fetch(symbol)]) }
1425
+ end
1426
+
1427
+ # Judges a declaration without building it, the way Constraints.new does when it is
1428
+ # built, taking the same keywords: 0 when every rule holds, otherwise the code of the first
1429
+ # rule it breaks (Constraints::REFUSALS words each). A wrong argument is still raised, as
1430
+ # Constraints.new raises it.
1431
+ def constraints_check(**keywords)
1432
+ layout = Constraints.send(:layout, **keywords)
1433
+ return layout if layout.is_a?(Integer)
1434
+
1435
+ door, raw, entries = layout
1436
+ pointer, = checked_scratch
1437
+ pointer[0, raw.bytesize] = raw
1438
+ Runtime.function(:cast_constraints_check).call(door, 0, pointer, input_ptr(entries), entries.bytesize)
1439
+ end
1440
+
1441
+ # Converts a bound, step or numeric enum entry written in invariant notation — an
1442
+ # optional sign, digits with an optional "." and fraction, an optional exponent:
1443
+ # "0.000001", "-90", "1e-6" — to the exact Decimal the core declares it as, trailing zeros
1444
+ # dropped: the conversion every bound a Constraints is given crosses. A value past 96 bits
1445
+ # or 28 places, or text in any other notation, is the ArgumentError a refused declaration
1446
+ # raises (code 8).
1447
+ def declared_decimal(text)
1448
+ bytes = utf8(text)
1449
+ out, = scratch
1450
+ rc = Runtime.function(:cast_declared_decimal).call(input_ptr(bytes), bytes.bytesize, out)
1451
+ raise ArgumentError, Constraints.send(:refusal, rc) if rc == 8
1452
+ raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it" unless rc.zero?
1453
+
1454
+ Interop.decode(:decimal, out[0, 16])
570
1455
  end
571
1456
 
572
1457
  # The version of the native core actually loaded, as "major.minor.patch" — read from
@@ -577,13 +1462,23 @@ module HyperCast
577
1462
  def native_version
578
1463
  Interop.version(packed_version)
579
1464
  end
1465
+ end
1466
+
1467
+ extend FiddleBackend
580
1468
 
1469
+ # The byte #kept stands a character with no UTF-8 form in for.
1470
+ NO_UTF8 = "\x80".b.freeze
1471
+ private_constant :NO_UTF8
1472
+
1473
+ class << self
581
1474
  private
582
1475
 
583
1476
  # Presents the input as UTF-8 bytes: already-compatible text crosses as-is (Fiddle
584
1477
  # passes a String's own bytes for void* — no copy of them); only foreign encodings pay
585
- # a transcode, and text that cannot be transcoded raises String#encode's own
586
- # Encoding:: error, the same one the Magnus extension raises through the same call.
1478
+ # a transcode. The Magnus extension calls this same method for a foreign encoding, so
1479
+ # both backends hand the core the same bytes. Text that cannot be transcoded (a lone
1480
+ # UTF-16 surrogate, bytes its encoding does not allow, a character with no Unicode
1481
+ # counterpart) is data, not a caller bug: see #kept.
587
1482
  #
588
1483
  # Text that is not a String is a caller bug, and the same TypeError on every backend:
589
1484
  # the extension takes its argument through Ruby's implicit String conversion (to_str,
@@ -594,7 +1489,69 @@ module HyperCast
594
1489
  raise TypeError, "no implicit conversion of #{text.class} into String"
595
1490
  text = converted
596
1491
  end
597
- Interop::BYTE_COMPATIBLE.include?(text.encoding) ? text : text.encode(Encoding::UTF_8)
1492
+ encoding = text.encoding
1493
+ # A US-ASCII String with a byte past 0x7F is not ASCII: it transcodes, and that byte is
1494
+ # malformed (#kept), never read as the UTF-8 it might spell.
1495
+ return text if Interop::BYTE_COMPATIBLE.include?(encoding) &&
1496
+ (encoding != Encoding::US_ASCII || text.ascii_only?)
1497
+
1498
+ begin
1499
+ text.encode(Encoding::UTF_8)
1500
+ rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError,
1501
+ Encoding::ConverterNotFoundError
1502
+ kept(text)
1503
+ end
1504
+ end
1505
+
1506
+ # Text that has no UTF-8 form, as the core reads it: each character transcoded, and each
1507
+ # one that cannot be (a lone surrogate, an invalid sequence, a character with no Unicode
1508
+ # counterpart) as the lone continuation byte 0x80, which no UTF-8 decoder accepts and the
1509
+ # core always judges as one malformed byte. The text is then MALFORMED at that character,
1510
+ # never a replacement standing for it, as at every binding's doors; and since 0x80 is one
1511
+ # character of the UTF-8 form, as the character it stands for is one of the caller's
1512
+ # String, a span still indexes the caller's own String.
1513
+ #
1514
+ # An encoding Ruby has no converter to UTF-8 for (EUC-TW, Windows-1258) gives no character
1515
+ # past ASCII a UTF-8 form, so each such character is one 0x80 too.
1516
+ #
1517
+ # A dummy encoding (UTF-16 and UTF-32 with their byte-order mark, ISO-2022-JP, UTF-7) has
1518
+ # no characters Ruby can split: each_char yields single bytes, and a String in one counts
1519
+ # bytes. Such text is transcoded whole (#transcoded), each conversion error standing as
1520
+ # one 0x80, so a span counts the characters of its UTF-8 form, the String
1521
+ # text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) spells, one for one.
1522
+ def kept(text)
1523
+ return transcoded(text) if text.encoding.dummy?
1524
+
1525
+ text.each_char.map do |char|
1526
+ char.valid_encoding? ? char.encode(Encoding::UTF_8).b : NO_UTF8
1527
+ rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError,
1528
+ Encoding::ConverterNotFoundError
1529
+ NO_UTF8
1530
+ end.join.force_encoding(Encoding::UTF_8)
1531
+ end
1532
+
1533
+ # Text in a dummy encoding as UTF-8, through one converter: each invalid sequence, each
1534
+ # character with no Unicode counterpart, and an input cut short as one 0x80. A dummy
1535
+ # encoding with no converter at all (UTF-7, ISO-2022-JP-2) is one 0x80 for each byte, the
1536
+ # unit its String counts.
1537
+ def transcoded(text)
1538
+ converter = begin
1539
+ Encoding::Converter.new(text.encoding, Encoding::UTF_8)
1540
+ rescue Encoding::ConverterNotFoundError
1541
+ return (NO_UTF8 * text.bytesize).force_encoding(Encoding::UTF_8)
1542
+ end
1543
+ source = text.b
1544
+ piece = String.new
1545
+ bytes = String.new(encoding: Encoding::BINARY)
1546
+ loop do
1547
+ status = converter.primitive_convert(source, piece)
1548
+ bytes << piece.b
1549
+ piece.clear
1550
+ break if status == :finished
1551
+
1552
+ bytes << NO_UTF8
1553
+ end
1554
+ bytes.force_encoding(Encoding::UTF_8)
598
1555
  end
599
1556
 
600
1557
  # Fiddle spells a null pointer as nil — the core's contract for empty input.
@@ -602,104 +1559,101 @@ module HyperCast
602
1559
  bytes.empty? ? nil : bytes
603
1560
  end
604
1561
 
605
- # One 64-byte scratch allocation per thread, reused by every call: out-value at 0
606
- # (16 bytes covers every door, and malloc's alignment covers the decimal's 8), fault
607
- # span at 16, and the datetime door's packed day periods at 24 (40 bytes, 4-aligned,
608
- # written only by a call that declares them). Two Fiddle::Pointer.malloc(..., RUBY_FREE)
609
- # calls per cast — each registering a GC finalizer — measured as the dominant per-call
610
- # cost by an order of magnitude. The NumFormat does not live here: each format owns
611
- # its own packed pointer (see packed_cache), so a numeric call copies nothing into
612
- # scratch before crossing. Allocated through Runtime.buffer, which loads the library
613
- # first, so a missing one is reported as such before Fiddle is touched.
1562
+ # One 96-byte scratch allocation per thread, reused by every call: out-value at 0 (16 bytes
1563
+ # covers every door, and malloc's alignment covers the decimal's 8), the fault at 16 (a
1564
+ # RawFaultDetail, 16 bytes: its size word written once, here, and never by the core; then the
1565
+ # span and the detail), the datetime door's packed day periods at 32 (40 bytes, 4-aligned,
1566
+ # written only by a call that declares them) and the date options at 72 (12 bytes, 4-aligned,
1567
+ # likewise). Two Fiddle::Pointer.malloc(..., RUBY_FREE) calls per cast — each registering a GC
1568
+ # finalizer — measured as the dominant per-call cost by an order of magnitude. The NumFormat
1569
+ # does not live here: each format owns its own packed pointer (see packed_cache), so a numeric
1570
+ # call copies nothing into scratch before crossing. Allocated through Runtime.buffer, which
1571
+ # loads the library first, so a missing one is reported as such before Fiddle is touched.
614
1572
  def scratch
615
1573
  Thread.current[:hypercast_scratch] ||= begin
616
- base = Runtime.buffer(64)
617
- [base, base + 16, base + 24]
1574
+ base = Runtime.buffer(96)
1575
+ base[16, 4] = [Interop::FAULT_BYTES].pack("L")
1576
+ [base, base + 16, base + 32, base + 72]
618
1577
  end
619
1578
  end
620
1579
 
621
1580
  # Presents a native return code as the verdict union: 0 yields a Success, a failure
622
- # code becomes a Fault over `bytes` (the UTF-8 the core read), and -1 (contract
623
- # violation) is a binding bug that raises.
1581
+ # code becomes a Fault over `bytes` (the UTF-8 the core read) carrying the core's detail, and
1582
+ # -1 (contract violation) is a binding bug that raises.
624
1583
  def verdict(rc, fault, bytes)
625
1584
  if rc.zero?
626
1585
  Success.new(value: yield)
627
1586
  elsif rc == -1
628
1587
  raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it"
629
1588
  else
630
- Interop.fault(rc, *Interop.characters(bytes, *fault[0, 8].unpack("L<L<")))
1589
+ Interop.raw_fault(rc, fault[0, Interop::FAULT_BYTES], bytes)
631
1590
  end
632
1591
  end
633
1592
 
634
- # The shared body of every format-free door: one native call over the scratch buffers.
635
- def plain(symbol, text, out_size)
1593
+ # The shared body of every door that reads text: one detailed native call over the scratch
1594
+ # buffers. door and param are the core's door code and what the door declares (0 for
1595
+ # nothing); format is the numeric doors' NumFormat, periods the datetime door's packed day
1596
+ # periods, options and months the date doors' DateOptions and MonthNames (nil for none), each
1597
+ # crossing only where the door reads it. The block reads the value from the out-bytes and the
1598
+ # UTF-8 the core read.
1599
+ def crossing(door, param, text, out_size, format = nil, periods = nil, options = nil, months = nil)
636
1600
  bytes = utf8(text)
637
- out, fault = scratch
638
- rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, out, fault)
639
- verdict(rc, fault, bytes) { yield(out[0, out_size]) }
640
- end
641
-
642
- # The shared body of the integer/real/decimal doors: plain, plus the format's own
643
- # packed pointer, passed straight through — no per-call copy of the 92 bytes into
644
- # scratch.
645
- def numeric(symbol, text, format, out_size)
646
- bytes = utf8(text)
647
- out, fault = scratch
648
- rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, packed_cache[format], out, fault)
649
- verdict(rc, fault, bytes) { yield(out[0, out_size]) }
650
- end
651
-
652
- # The civil date-time door's body: declared, plus the day periods after the order — the
653
- # 40 packed bytes copied into this thread's scratch and passed from there, or nil
654
- # (Fiddle's null) when none are declared, which the core reads as English AM/PM only.
655
- def civil(symbol, text, code, periods, out_size)
656
- bytes = utf8(text)
657
- out, fault, slot = scratch
1601
+ out, fault, slot, dates = scratch
658
1602
  if periods
659
1603
  slot[0, periods.bytesize] = periods
660
1604
  else
661
1605
  slot = nil
662
1606
  end
663
- rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, code, slot, out, fault)
664
- verdict(rc, fault, bytes) { yield(out[0, out_size]) }
1607
+ if options
1608
+ dates[0, DateOptions::PACKED_BYTES] = options.packed
1609
+ else
1610
+ dates = nil
1611
+ end
1612
+ vocabulary = months&.packed
1613
+ rc = Runtime.function(:cast_detailed).call(door, param, format && packed_cache[format], slot, dates,
1614
+ vocabulary, vocabulary ? vocabulary.bytesize : 0,
1615
+ input_ptr(bytes), bytes.bytesize, out, fault)
1616
+ raise RefusedDeclaration, "the core refused the date options or month names" if rc == -1 && (options || months)
1617
+
1618
+ verdict(rc, fault, bytes) { yield(out[0, out_size], bytes) }
1619
+ end
1620
+
1621
+ # Date options and month names as a date door takes them: each nil or the right type, a
1622
+ # TypeError otherwise (what the Magnus extension raises for them too).
1623
+ def dated(options, months)
1624
+ raise TypeError, "options must be a HyperCast::DateOptions; got #{options.inspect}" unless
1625
+ options.nil? || options.is_a?(DateOptions)
1626
+ raise TypeError, "months must be a HyperCast::MonthNames; got #{months.inspect}" unless
1627
+ months.nil? || months.is_a?(MonthNames)
665
1628
  end
666
1629
 
667
- # The 40-byte little-endian form of the native ABI's size-tagged DayPeriods struct: the
668
- # size word (40), then each designator as its UTF-8 bytes zero-padded to 16 followed by
669
- # its byte length — am, then pm — and two bytes of padding. A nil designator is a
670
- # length of 0: nothing declared beside AM or PM.
1630
+ # The 40-byte native form of the ABI's size-tagged DayPeriods struct, which the core
1631
+ # reads in place: the size word (40, in native byte order), then each designator as its
1632
+ # UTF-8 bytes zero-padded to 16 followed by its byte length — am, then pm — and two bytes
1633
+ # of padding. A nil designator is a length of 0: nothing declared beside AM or PM.
671
1634
  def packed_day_periods(am, pm)
672
1635
  am = designator("am", am)
673
1636
  pm = designator("pm", pm)
674
- [40].pack("L<") + [am, am.bytesize, pm, pm.bytesize].pack("a16Ca16C") + "\0\0"
1637
+ [40].pack("L") + [am, am.bytesize, pm, pm.bytesize].pack("a16Ca16C") + "\0\0"
675
1638
  end
676
1639
 
677
1640
  # A declared day-period designator as the UTF-8 the core reads — 1 to 16 bytes, no
678
- # ASCII digit, no ASCII whitespace at either end (the grammar around it reads that) —
1641
+ # ASCII digit, no white space at either end (the grammar around it reads that) —
679
1642
  # or "" for nil. Anything else is the caller bug it names, the same ArgumentError on
680
1643
  # every backend.
681
1644
  def designator(name, text)
682
1645
  return "" if text.nil?
683
1646
  raise ArgumentError, "#{name} designator must be a String; got #{text.inspect}" unless text.is_a?(String)
684
1647
 
685
- designator = text.encode(Encoding::UTF_8)
686
- unless designator.bytesize.between?(1, 16) && !designator.match?(/[0-9]|\A[\t\n\f\r ]|[\t\n\f\r ]\z/)
1648
+ designator = declared_utf8("#{name} designator", text)
1649
+ unless designator.bytesize.between?(1, 16) &&
1650
+ !designator.match?(/[0-9]|\A#{WHITE_SPACE.source}|#{WHITE_SPACE.source}\z/)
687
1651
  raise ArgumentError, "#{name} designator #{text.inspect} must be 1 to 16 UTF-8 bytes with no ASCII digit " \
688
- "and no ASCII whitespace at either end"
1652
+ "and no white space at either end"
689
1653
  end
690
1654
  designator
691
1655
  end
692
1656
 
693
- # The shared body of the four doors that take a caller-declared u32 — a precision, an
694
- # epoch, or a field order — already resolved from its Symbol by the door. These bodies
695
- # (plain, numeric, declared, and packed_version below) are the whole Fiddle crossing.
696
- def declared(symbol, text, code, out_size)
697
- bytes = utf8(text)
698
- out, fault = scratch
699
- rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, code, out, fault)
700
- verdict(rc, fault, bytes) { yield(out[0, out_size]) }
701
- end
702
-
703
1657
  # A typed door's number, converted the way the extension's argument is (C's
704
1658
  # rb_num2dbl), with the same exception and message: a Numeric converts (a Complex with an
705
1659
  # imaginary part is Complex#to_f's RangeError), anything else is a TypeError — a String
@@ -714,26 +1668,120 @@ module HyperCast
714
1668
  end
715
1669
  end
716
1670
 
717
- # The shared body of the typed doors: a double instead of the text, then the declared
718
- # u32 when the door takes one.
719
- def typed(symbol, number, out_size, *declared)
1671
+ # The shared body of the typed doors: a double instead of the text, through the core's
1672
+ # detailed typed export (door and param as #crossing's; a typed door's span is empty).
1673
+ def typed(door, param, number, out_size)
720
1674
  out, fault = scratch
721
- rc = Runtime.function(symbol).call(number, *declared, out, fault)
1675
+ rc = Runtime.function(:cast_detailed_from_f64).call(door, param, number, out, fault)
722
1676
  if rc.zero?
723
1677
  Success.new(value: yield(out[0, out_size]))
724
1678
  elsif rc == -1
725
1679
  raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it"
726
1680
  else
727
- Interop.fault(rc, 0, 0)
1681
+ Interop.raw_fault(rc, fault[0, Interop::FAULT_BYTES])
1682
+ end
1683
+ end
1684
+
1685
+ # The text door's value at the byte span the core judged valid: the String passed when
1686
+ # the span is all of it and it is UTF-8 or US-ASCII, else that span as a new UTF-8 String
1687
+ # (a trimmed span, or a binary String's bytes).
1688
+ def text_value(bytes, offset, length)
1689
+ return bytes if offset.zero? && length == bytes.bytesize && bytes.encoding != Encoding::ASCII_8BIT
1690
+
1691
+ bytes.byteslice(offset, length).force_encoding(Encoding::UTF_8)
1692
+ end
1693
+
1694
+ # A Constraints as a checked door hands it to the core — its door Symbol, its packed
1695
+ # layout in 8-aligned native memory and its packed enum — checked against the door it was
1696
+ # passed to: a non-Constraints is a TypeError, and one bound to another door an
1697
+ # ArgumentError naming the door that judges it.
1698
+ def constrained(constraints, door)
1699
+ raise TypeError, "constraints must be a HyperCast::Constraints; got #{constraints.inspect}" unless
1700
+ constraints.is_a?(Constraints)
1701
+
1702
+ declared = constraints_cache[constraints]
1703
+ text = declared[0] == :text
1704
+ if text != (door == :text)
1705
+ raise ArgumentError,
1706
+ "Constraints for #{declared[0].inspect} are judged by HyperCast.#{text ? 'text' : 'checked'}"
1707
+ end
1708
+
1709
+ declared
1710
+ end
1711
+
1712
+ # How many declarations constraints_cache remembers before it starts forgetting the
1713
+ # oldest: packed_cache's bound, for the same reason.
1714
+ CONSTRAINTS_CACHE_LIMIT = 64
1715
+
1716
+ # Identity-keyed memo of each Constraints as the core reads it: its door, its 104-byte
1717
+ # layout copied once into native memory (which a String's bytes are not guaranteed to be
1718
+ # aligned for) and its packed enum, frozen. Bounded and evicted as packed_cache is.
1719
+ def constraints_cache
1720
+ @constraints_cache ||= Hash.new do |cache, constraints|
1721
+ cache.shift while cache.size >= CONSTRAINTS_CACHE_LIMIT
1722
+ _code, raw, entries = constraints.send(:declaration)
1723
+ pointer = Runtime.buffer(raw.bytesize)
1724
+ pointer[0, raw.bytesize] = raw
1725
+ cache[constraints] = [constraints.door, pointer, entries.freeze].freeze
1726
+ end.compare_by_identity
1727
+ end
1728
+
1729
+ # One 120-byte scratch allocation per thread for the checked doors, beside #scratch: a
1730
+ # packed layout constraints_check judges at 0 (104 bytes, 8-aligned by malloc), and the
1731
+ # check a checked door writes at 104 (12 bytes).
1732
+ def checked_scratch
1733
+ Thread.current[:hypercast_checked_scratch] ||= begin
1734
+ base = Runtime.buffer(Constraints::PACKED_BYTES + 16)
1735
+ [base, base + Constraints::PACKED_BYTES]
728
1736
  end
729
1737
  end
730
1738
 
1739
+ # The shared body of the checked doors that read text: one detailed native call. door is
1740
+ # the core's door code, format the packed NumFormat pointer (nil at :text, which never reads
1741
+ # one), raw the packed constraints pointer and entries the packed enum.
1742
+ def checked_call(door, format, raw, entries, bytes)
1743
+ out, fault = scratch
1744
+ Runtime.function(:cast_checked_detailed).call(door, 0, format, raw, input_ptr(entries), entries.bytesize,
1745
+ input_ptr(bytes), bytes.bytesize, out, fault,
1746
+ checked_scratch[1])
1747
+ end
1748
+
1749
+ # Presents a checked door's return code as its verdict: 0 a Checked of the value the
1750
+ # block reads from the out-value and check, 1 to 3 the door's Fault with its detail, 4 a
1751
+ # Violation of the value the block reads from the out-value (handed no check: the value as
1752
+ # cast, never an enum entry) — each span over `bytes` (the UTF-8 the core read) as a
1753
+ # Fault's is, or as written when there is no text — and -1 a binding bug that raises.
1754
+ def checked_verdict(rc, bytes)
1755
+ out, fault = scratch
1756
+ check = checked_scratch[1]
1757
+ if rc.zero?
1758
+ adjusted, index = check[4, 8].unpack("LL")
1759
+ return Checked.new(value: yield(out, check), adjusted: adjusted != 0,
1760
+ enum_index: index == 0xFFFF_FFFF ? nil : index)
1761
+ end
1762
+ raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it" unless
1763
+ rc.between?(1, 4)
1764
+ return Interop.raw_fault(rc, fault[0, Interop::FAULT_BYTES], bytes) unless rc == 4
1765
+
1766
+ offset, length = fault[4, 8].unpack("LL")
1767
+ offset, length = Interop.characters(bytes, offset, length) if bytes
1768
+ Violation.new(keyword: Keyword.new(code: check[0, 4].unpack1("L")), value: yield(out, nil), offset: offset,
1769
+ length: length)
1770
+ end
1771
+
731
1772
  # The loaded core's version word, major << 16 | minor << 8 | patch, straight from the
732
1773
  # library's zero-argument hypercast_version export.
733
1774
  def packed_version
734
1775
  Runtime.function(:hypercast_version).call
735
1776
  end
736
1777
 
1778
+ # NumFormat#packed as the C ABI reads it in place: its three leading words in the host's
1779
+ # native byte order (on a little-endian host, the very bytes), the symbols as they are.
1780
+ def native_packed(format)
1781
+ packed = format.packed
1782
+ packed[0, 12].unpack("L<3").pack("L3") + packed.byteslice(12, packed.bytesize - 12)
1783
+ end
1784
+
737
1785
  # How many formats packed_cache remembers before it starts forgetting the oldest. Far
738
1786
  # more than a process that reuses its formats ever holds; what it bounds is the one
739
1787
  # that builds a NumFormat per request.
@@ -755,15 +1803,16 @@ module HyperCast
755
1803
  cache.shift while cache.size >= PACKED_CACHE_LIMIT
756
1804
  size = NumFormat::PACKED_BYTES
757
1805
  pointer = Runtime.buffer(size)
758
- pointer[0, size] = format.packed
1806
+ pointer[0, size] = native_packed(format)
759
1807
  cache[format] = pointer
760
1808
  end.compare_by_identity
761
1809
  end
762
1810
  end
763
1811
  end
764
1812
 
765
- # --- backend selection: the Magnus extension, when present, replaces the doors above in
766
- # place on this module (no delegation layer) — Fiddle's measured 1.6 µs per-call floor
1813
+ # --- backend selection: the Magnus extension, when present, defines the doors on this
1814
+ # module's singleton class, in front of the FiddleBackend definitions it extends (no
1815
+ # delegation layer, no redefinition) — Fiddle's measured 1.6 µs per-call floor
767
1816
  # drops to an ordinary extension call. The pure-Fiddle definitions stay the universal
768
1817
  # zero-compile fallback — the last resort, for a Ruby or a platform no platform gem covers;
769
1818
  # precompiled platform gems are how the extension ships without ever making a consumer