field_struct 0.15.0 → 1.0.0.pre1

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.
Files changed (70) hide show
  1. checksums.yaml +4 -4
  2. data/.claude-plugin/marketplace.json +13 -0
  3. data/.claude-plugin/plugin.json +9 -0
  4. data/AGENTS.md +47 -54
  5. data/CHANGELOG.md +53 -640
  6. data/LICENSE.txt +21 -0
  7. data/README.md +33 -628
  8. data/USAGE.md +771 -715
  9. data/docs/getting_started.md +139 -325
  10. data/lib/field_struct/base.rb +241 -1149
  11. data/lib/field_struct/class_macros.rb +163 -0
  12. data/lib/field_struct/describer.rb +167 -0
  13. data/lib/field_struct/errors.rb +182 -62
  14. data/lib/field_struct/exceptions.rb +40 -0
  15. data/lib/field_struct/field.rb +69 -135
  16. data/lib/field_struct/field_builder.rb +110 -0
  17. data/lib/field_struct/field_checks.rb +50 -0
  18. data/lib/field_struct/introspection.rb +199 -0
  19. data/lib/field_struct/json_codec.rb +240 -0
  20. data/lib/field_struct/metadata.rb +65 -260
  21. data/lib/field_struct/model_name.rb +27 -27
  22. data/lib/field_struct/option_checker.rb +121 -0
  23. data/lib/field_struct/partial.rb +49 -0
  24. data/lib/field_struct/presence.rb +45 -0
  25. data/lib/field_struct/rbs.rb +151 -271
  26. data/lib/field_struct/registered_option.rb +113 -0
  27. data/lib/field_struct/registry.rb +40 -50
  28. data/lib/field_struct/restrictions.rb +90 -0
  29. data/lib/field_struct/scaffold.rb +274 -301
  30. data/lib/field_struct/suggestion.rb +33 -0
  31. data/lib/field_struct/types/array.rb +147 -126
  32. data/lib/field_struct/types/base.rb +113 -124
  33. data/lib/field_struct/types/big_decimal.rb +59 -55
  34. data/lib/field_struct/types/binary.rb +18 -25
  35. data/lib/field_struct/types/boolean.rb +74 -97
  36. data/lib/field_struct/types/builtin.rb +32 -0
  37. data/lib/field_struct/types/date.rb +23 -137
  38. data/lib/field_struct/types/datetime.rb +30 -139
  39. data/lib/field_struct/types/element_options.rb +51 -0
  40. data/lib/field_struct/types/email.rb +27 -38
  41. data/lib/field_struct/types/float.rb +58 -56
  42. data/lib/field_struct/types/format_presets.rb +30 -0
  43. data/lib/field_struct/types/hash.rb +144 -0
  44. data/lib/field_struct/types/immutable_string.rb +16 -9
  45. data/lib/field_struct/types/integer.rb +74 -102
  46. data/lib/field_struct/types/nested.rb +57 -58
  47. data/lib/field_struct/types/preset_resolver.rb +9 -24
  48. data/lib/field_struct/types/rfc3339_format.rb +70 -153
  49. data/lib/field_struct/types/string.rb +48 -46
  50. data/lib/field_struct/types/symbol.rb +23 -20
  51. data/lib/field_struct/types/temporal.rb +232 -0
  52. data/lib/field_struct/types/time.rb +32 -145
  53. data/lib/field_struct/types/union.rb +111 -65
  54. data/lib/field_struct/types/union_pick.rb +139 -0
  55. data/lib/field_struct/types/url.rb +24 -35
  56. data/lib/field_struct/types/uuid.rb +24 -35
  57. data/lib/field_struct/types/value.rb +14 -9
  58. data/lib/field_struct/types/zone.rb +118 -0
  59. data/lib/field_struct/version.rb +3 -3
  60. data/lib/field_struct.rb +102 -122
  61. data/sig/field_struct.rbs +1180 -2300
  62. data/sig/manifest.yaml +6 -0
  63. data/skills/field-struct/SKILL.md +73 -159
  64. metadata +37 -28
  65. data/CODE_OF_CONDUCT.md +0 -132
  66. data/UPGRADING.md +0 -743
  67. data/lib/field_struct/error.rb +0 -48
  68. data/lib/field_struct/types/temporal_parser.rb +0 -93
  69. data/lib/field_struct/types/time_format_resolver.rb +0 -54
  70. data/lib/field_struct/types/zone_option.rb +0 -267
@@ -1,48 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module FieldStruct
4
- # Base class for every error FieldStruct raises. Catch this to handle
5
- # any library error generically.
6
- class Error < StandardError; end
7
-
8
- # Raised by the setter pipeline when a value cannot be coerced into a
9
- # field's declared type and the class's +coercion_policy+ is +:raise+.
10
- #
11
- # Carries the field name and the original underlying error for callers
12
- # that want to inspect what happened.
13
- class CoercionError < Error
14
- # @return [Symbol, nil] the field whose setter triggered the failure
15
- attr_reader :field_name
16
-
17
- # @return [StandardError, nil] the underlying error from the type's coerce
18
- attr_reader :original
19
-
20
- # @param message [String]
21
- # @param field_name [Symbol, nil]
22
- # @param original [StandardError, nil]
23
- def initialize(message, field_name: nil, original: nil)
24
- super(message)
25
- @field_name = field_name
26
- @original = original
27
- end
28
- end
29
-
30
- # Raised when a field setter on a class marked +immutable!+ is called
31
- # after construction.
32
- class ImmutableError < Error; end
33
-
34
- # Raised by {Base#initialize} / {Base#assign_attributes} when the input
35
- # hash includes a key that is not a declared field on the class and
36
- # the +unknown_attributes+ policy is +:raise+.
37
- class UnknownAttributeError < Error
38
- # @return [Array<Symbol>] the offending keys
39
- attr_reader :keys
40
-
41
- # @param message [String]
42
- # @param keys [Array<Symbol>]
43
- def initialize(message, keys: [])
44
- super(message)
45
- @keys = keys
46
- end
47
- end
48
- end
@@ -1,93 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require 'date'
4
-
5
- module FieldStruct
6
- module Types
7
- # Shared String-parsing rules for {Date}, {Time} and {DateTime}.
8
- #
9
- # Three rules the stdlib parsers leave to their caller. Each of them is a
10
- # case where the stdlib answers a question it was not asked, confidently.
11
- #
12
- # **Anchoring.** +strptime+ matches a PREFIX and discards the rest.
13
- # +Date.strptime('2026-07-031', '%Y-%m-%d')+ returns the 3rd and throws the
14
- # trailing +1+ away; +'2026-07-03T10:30:00+0000-NONSENSE'+ parses clean
15
- # under the +iso8601+ preset. A declared +format:+ is a contract about the
16
- # whole string, so anything left over is refused. (Leading whitespace needs
17
- # no rule — +Date._strptime+ already returns +nil+ for it.)
18
- #
19
- # **Civil validity.** +Date.strptime+ and +DateTime.strptime+ refuse the
20
- # 30th of February. +Time+ does not: +Time.parse+, +Time.strptime+ and
21
- # +Time.new+ all roll it forward to 2 March and say nothing. All three
22
- # types refuse it here.
23
- #
24
- # **Completeness.** With no declared format the stdlib parsers fill in
25
- # whatever the string omits, from *today*: +Time.parse('10:30')+ is today
26
- # at 10:30, +'July'+ is the 1st of July this year, +'12'+ is the 12th of
27
- # this month. A value whose meaning depends on when it was parsed is not a
28
- # value, so a string with no declared format must name a whole day.
29
- #
30
- # Anchoring is trailing-junk rejection and nothing more. Widths, sign and
31
- # case stay strptime-lenient for a hand-written format: +%m+ and +%d+
32
- # accept one or two digits, which is strptime's contract rather than a
33
- # defect. Strictness for the built-in presets is a separate concern.
34
- module TemporalParser
35
- # Validate a String against a declared format.
36
- #
37
- # @param value [::String] the raw string
38
- # @param format [::String] a resolved strftime/strptime format
39
- # @return [::Hash{::Symbol => Object}] the parsed fragments
40
- # @raise [ArgumentError] when the string does not match the format, has
41
- # characters left over, or names a day that does not exist
42
- def self.strptime_parts(value, format)
43
- parts = ::Date._strptime(value, format)
44
- raise ArgumentError, "does not match format #{format.inspect}" if parts.nil?
45
-
46
- if parts.key?(:leftover)
47
- raise ArgumentError,
48
- "does not match format #{format.inspect} — unexpected trailing characters"
49
- end
50
-
51
- ensure_real_day!(parts)
52
- parts
53
- end
54
-
55
- # Validate a String with no declared format.
56
- #
57
- # @param value [::String] the raw string
58
- # @return [::Hash{::Symbol => Object}] the parsed fragments
59
- # @raise [ArgumentError] when the string names only part of a day, or a
60
- # day that does not exist
61
- def self.parse_parts(value)
62
- parts = ::Date._parse(value)
63
- ensure_whole_day!(parts)
64
- ensure_real_day!(parts)
65
- parts
66
- end
67
-
68
- # @param parts [::Hash{::Symbol => Object}] fragments from +Date._parse+
69
- # @return [void]
70
- # @raise [ArgumentError] when year, month or day is missing
71
- def self.ensure_whole_day!(parts)
72
- return if parts[:year] && parts[:mon] && parts[:mday]
73
-
74
- # The value is deliberately not echoed: FieldStruct wraps this as
75
- # "could not be coerced: <message>" and that string reaches API
76
- # responses and audit rows.
77
- raise ArgumentError, 'expected a date with a year, a month and a day'
78
- end
79
-
80
- # @param parts [::Hash{::Symbol => Object}] fragments from +Date._parse+
81
- # or +Date._strptime+
82
- # @return [void]
83
- # @raise [ArgumentError] when the fragments name a day that never existed
84
- def self.ensure_real_day!(parts)
85
- year, month, day = parts.values_at(:year, :mon, :mday)
86
- return if year.nil? || month.nil? || day.nil?
87
- return if ::Date.valid_civil?(year, month, day)
88
-
89
- raise ArgumentError, 'invalid date'
90
- end
91
- end
92
- end
93
- end
@@ -1,54 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module FieldStruct
4
- module Types
5
- # Shared +format:+ option resolution for {Date}/{Time}/{DateTime}.
6
- # Each of those types calls +TimeFormatResolver.call(options, presets)+
7
- # from its +resolve_options+ class method.
8
- #
9
- # A declared +format:+ is VALIDATED at declaration time and kept exactly as
10
- # the user wrote it; it is resolved to a strftime string later, at coerce
11
- # and render time, by {.resolve}.
12
- #
13
- # Keeping the declaration is the point. The Symbol used to be overwritten
14
- # with the strftime String it expands to, which destroyed the only fact a
15
- # documentation generator actually wants — that the field is +:iso8601+,
16
- # not some anonymous String of percent-escapes. Recovering the name by
17
- # reverse-mapping the String worked only while no two presets shared a
18
- # value, which is luck rather than a contract.
19
- module TimeFormatResolver
20
- # Validate a declared +format:+ and return the options unchanged.
21
- #
22
- # @param options [::Hash{::Symbol => Object, nil}] the per-field options as written
23
- # @param presets [::Hash{::Symbol => ::String}] the type's preset table
24
- # @return [::Hash{::Symbol => Object, nil}] +options+, unmodified
25
- # @raise [ArgumentError] when +format:+ is the wrong shape, or names a
26
- # preset the type does not have — at declaration time, not at first use
27
- def self.call(options, presets)
28
- return options unless options.key?(:format)
29
-
30
- fmt = options[:format]
31
- return options if fmt.is_a?(::String) || fmt.is_a?(::Regexp) || fmt.nil?
32
- raise ArgumentError, "format: must be a String, Regexp, or Symbol — got #{fmt.class}" unless fmt.is_a?(::Symbol)
33
-
34
- resolve(fmt, presets) # raises on an unknown name; the result is discarded
35
- options
36
- end
37
-
38
- # Resolve a declared +format:+ to a strftime/strptime String.
39
- #
40
- # @param format [::String, ::Symbol, nil] as declared
41
- # @param presets [::Hash{::Symbol => ::String}] the type's preset table
42
- # @return [::String, nil] +nil+ when no format is declared
43
- # @raise [ArgumentError] when the Symbol names no preset in the table
44
- def self.resolve(format, presets)
45
- return format if format.nil? || format.is_a?(::String)
46
-
47
- presets.fetch(format) do
48
- raise ArgumentError,
49
- "unknown time format preset #{format.inspect}. Available: #{presets.keys.inspect}"
50
- end
51
- end
52
- end
53
- end
54
- end
@@ -1,267 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require 'date'
4
- require 'time'
5
-
6
- module FieldStruct
7
- module Types
8
- # The +zone:+ option shared by {Time} and {DateTime}.
9
- #
10
- # A zone-less string (+"2026-10-22 10:00"+) names a wall-clock time, not an
11
- # instant: by default +:time+ reads it in the *process* zone and +:datetime+
12
- # in UTC, so the same input meant different instants on different servers.
13
- # +zone:+ supplies the missing offset, so it means one instant everywhere.
14
- #
15
- # It only fills in an offset that is MISSING. A string with an offset, a
16
- # +Time+, a +DateTime+ (and ActiveSupport's TimeWithZone) keep theirs; a
17
- # +Date+, which has none, becomes midnight in the zone.
18
- #
19
- # Accepted values are +"UTC"+, fixed offsets +"±HH:MM"+ and IANA
20
- # Area/Location names (+"America/Denver"+). A fixed offset is the same all
21
- # year. A name is read through tzinfo's zone database, so a wall-clock time
22
- # gets the offset in force at that date and an instant (an epoch) the
23
- # offset in force at that instant. tzinfo is required only when a field
24
- # declares a name.
25
- #
26
- # Daylight-saving edges, for a name:
27
- #
28
- # - A wall-clock time the zone skips (02:30 on a spring-forward day) is
29
- # refused, as a 30 February is: it names no instant. ActiveSupport moves
30
- # it an hour forward instead; FieldStruct does not guess.
31
- # - A wall-clock time the zone repeats (01:30 on a fall-back day) is read
32
- # at its daylight-time offset — the earlier instant — which is what
33
- # ActiveSupport's TimeWithZone picks, so a Rails app sees the same answer.
34
- # - A +Date+ whose midnight the zone skips becomes the first moment of that
35
- # day (01:00 in Santiago on its spring-forward day), as
36
- # +Date#in_time_zone+ does.
37
- #
38
- # The value returned is a plain +::Time+ (or +::DateTime+) carrying the
39
- # offset, never a +TZInfo::TimeWithOffset+; it does not carry the zone
40
- # itself, so arithmetic on it keeps that offset rather than following DST.
41
- #
42
- # Refused: abbreviations and legacy aliases with no +/+ (+"MST"+ is a fixed
43
- # -07:00 in the database, not Mountain time with DST) and Rails' friendly
44
- # names (+"Mountain Time (US & Canada)"+), which only exist when
45
- # ActiveSupport is loaded and so would make a declaration valid in one
46
- # process and invalid in another (invariant 7).
47
- module ZoneOption
48
- # A fixed UTC offset, colon required.
49
- # @return [::Regexp]
50
- OFFSET = /\A([+-])(\d{2}):(\d{2})\z/
51
-
52
- # Refuse a +zone:+ value FieldStruct cannot read, at declaration. A
53
- # non-String is left for the option-shape check to report.
54
- #
55
- # @param type_name [::String] the type's short name, for the message
56
- # @param options [::Hash{::Symbol => Object, nil}] the per-field options
57
- # @return [::Hash{::Symbol => Object, nil}] the options, unchanged
58
- # @raise [ArgumentError] when +zone:+ is a String that is not +"UTC"+, a
59
- # valid +±HH:MM+ offset or an IANA name in the zone database, or when
60
- # no zone database can be found
61
- def self.validate!(type_name, options)
62
- zone = options[:zone]
63
- return options unless zone.is_a?(::String)
64
- return options if offset_seconds(zone)
65
-
66
- raise ArgumentError, refusal(type_name, zone) unless zone.include?('/')
67
-
68
- load_timezone(type_name, zone)
69
- options
70
- end
71
-
72
- # @param type_name [::String] the type's short name
73
- # @param zone [::String] the refused +zone:+
74
- # @return [::String] the declaration error, with a hint for the
75
- # shape of +zone+
76
- def self.refusal(type_name, zone)
77
- hint = if zone.match?(/[ ()&]/)
78
- 'Rails zone names are an ActiveSupport alias, not IANA names, and exist only when ' \
79
- 'ActiveSupport is loaded: use the name it maps to (ActiveSupport::TimeZone::MAPPING[name]).'
80
- elsif zone.include?('/')
81
- 'The zone database has no zone by that name.'
82
- else
83
- 'Use an Area/Location name: abbreviations and aliases are refused ("MST" is a fixed ' \
84
- '-07:00 in the zone database, not Mountain time with DST), and an offset needs its colon.'
85
- end
86
- "zone: on #{type_name} expects an IANA name like \"America/Denver\", \"UTC\" or a UTC offset " \
87
- "like \"-06:00\", got #{zone.inspect}. #{hint}"
88
- end
89
-
90
- # Look up (and cache) a zone by name, requiring tzinfo on first use.
91
- #
92
- # @param type_name [::String] the type's short name, for the message
93
- # @param zone [::String] an IANA name
94
- # @return [Object] the +TZInfo::Timezone+
95
- # @raise [ArgumentError] when the name is unknown, or no zone data is
96
- # installed
97
- def self.load_timezone(type_name, zone)
98
- require 'tzinfo'
99
- @timezones ||= {}
100
- @timezones[zone] ||= ::TZInfo::Timezone.get(zone)
101
- rescue ::TZInfo::InvalidTimezoneIdentifier
102
- raise ArgumentError, refusal(type_name, zone)
103
- rescue ::TZInfo::DataSourceNotFound
104
- raise ArgumentError,
105
- "zone: on #{type_name} names #{zone.inspect}, but no time zone data was found on this system. " \
106
- 'Add the tzinfo-data gem to your Gemfile (or install the OS zoneinfo package).'
107
- end
108
-
109
- # @param zone [::String] an IANA name {.validate!} accepted
110
- # @return [Object] the cached +TZInfo::Timezone+
111
- # @raise [ArgumentError] for a name {.validate!} would refuse, when a
112
- # type is called directly with one
113
- def self.timezone(zone)
114
- cached = @timezones && @timezones[zone]
115
- return cached if cached
116
- raise ArgumentError, refusal('the field', zone) unless zone.include?('/')
117
-
118
- load_timezone('the field', zone)
119
- end
120
-
121
- # @param zone [::String] a declared +zone:+
122
- # @return [::Integer, nil] seconds east of UTC, or +nil+ when +zone+ is
123
- # not a value {.validate!} accepts
124
- def self.offset_seconds(zone)
125
- return 0 if zone == 'UTC'
126
-
127
- match = OFFSET.match(zone)
128
- return nil if match.nil?
129
-
130
- hours = Integer(match[2], 10)
131
- minutes = Integer(match[3], 10)
132
- return nil if hours > 23 || minutes > 59
133
-
134
- (match[1] == '-' ? -1 : 1) * ((hours * 3600) + (minutes * 60))
135
- end
136
-
137
- # Whether parsed fragments leave the offset to +zone:+.
138
- #
139
- # @param parts [::Hash{::Symbol => Object}] fragments from +Date._parse+
140
- # or +Date._strptime+
141
- # @return [Boolean] +true+ when the string named no offset at all
142
- # @raise [ArgumentError] when the string names a zone the stdlib cannot
143
- # turn into an offset (+"XYZ"+, +"America/Denver"+): +zone:+ never
144
- # overrides a zone the input stated
145
- def self.zoneless?(parts)
146
- # An epoch (%s / %Q) is an instant already; {.time_at} keeps it and
147
- # only places it at the zone's offset, as it does for any other input.
148
- return false unless parts[:offset].nil?
149
- return true if parts[:zone].nil?
150
-
151
- # The input is not echoed — see Types::Time#coerce.
152
- raise ArgumentError, 'names a time zone with no fixed offset, which zone: does not override'
153
- end
154
-
155
- # Read a zone-less String as a wall-clock time in +zone+.
156
- #
157
- # @param value [::String] a string {.zoneless?} accepted
158
- # @param format [::String, nil] a resolved strptime format, or +nil+ for
159
- # the no-format path (which has already required a whole day)
160
- # @param zone [::String] a declared +zone:+
161
- # @param parts [::Hash{::Symbol => Object}] the fragments the string
162
- # parsed to; an epoch (+%s+ / +%Q+) shows up as +:seconds+
163
- # @return [::Time] at +zone+'s offset (+utc?+ for +"UTC"+)
164
- # @raise [ArgumentError] when +zone+ is a name and the wall-clock time
165
- # falls in a gap the zone skips
166
- def self.time_at(value, format, zone, parts)
167
- offset = offset_seconds(zone)
168
- return named_time_at(value, format, timezone(zone), parts) if offset.nil?
169
-
170
- time = if format
171
- # Appending the offset lets strptime do everything else as usual.
172
- # Given an offset, it also fills a date the format omits from today
173
- # *at that offset*, where plain strptime uses the process zone's
174
- # today, and places an epoch (%s) at that offset.
175
- ::Time.strptime("#{value} #{offset_text(offset)}", "#{format} %z")
176
- else
177
- # DateTime.parse reads the wall clock with no zone involved, so a
178
- # time the process zone skips for DST (02:30 on a spring-forward day)
179
- # is kept rather than moved, as Time.parse would.
180
- wall = ::DateTime.parse(value)
181
- ::Time.new(wall.year, wall.mon, wall.mday, wall.hour, wall.min, wall.sec + wall.sec_fraction, offset)
182
- end
183
- zone == 'UTC' ? time.utc : time
184
- end
185
-
186
- # {.time_at} for an IANA name: the offset depends on the date.
187
- #
188
- # @param value [::String] the zone-less string
189
- # @param format [::String, nil] a resolved strptime format, or +nil+
190
- # @param timezone [Object] a +TZInfo::Timezone+
191
- # @param parts [::Hash{::Symbol => Object}] the parsed fragments
192
- # @return [::Time]
193
- def self.named_time_at(value, format, timezone, parts)
194
- # An epoch is an instant already: keep it, at the offset of that instant.
195
- return in_zone(::Time.strptime(value, format), timezone) if format && parts.key?(:seconds)
196
-
197
- wall = if format
198
- # The offset in force NOW only decides which day "today" is when
199
- # the format omits the date; the wall clock is resolved below.
200
- now = offset_text(timezone.period_for(::Time.now).observed_utc_offset)
201
- ::Time.strptime("#{value} #{now}", "#{format} %z")
202
- else
203
- ::DateTime.parse(value)
204
- end
205
- sec = wall.sec + (wall.is_a?(::DateTime) ? wall.sec_fraction : wall.subsec)
206
- local(timezone, [wall.year, wall.mon, wall.mday, wall.hour, wall.min, sec])
207
- end
208
-
209
- # A wall-clock time in a named zone.
210
- #
211
- # @param timezone [Object] a +TZInfo::Timezone+
212
- # @param civil [::Array<::Numeric>] year, month, day, hour, minute and
213
- # seconds (with any fraction)
214
- # @return [::Time] at the offset in force at that wall-clock time
215
- # @raise [ArgumentError] when the zone skips that wall-clock time
216
- def self.local(timezone, civil)
217
- # tzinfo reads the components and ignores the offset of the Time it is
218
- # given. In an overlap, dst = true and the block pick what
219
- # ActiveSupport's TimeZone#period_for_local picks.
220
- period = timezone.period_for_local(::Time.utc(*civil), true, &:last)
221
- ::Time.new(*civil, period.observed_utc_offset)
222
- rescue ::TZInfo::PeriodNotFound
223
- # The input is not echoed — see Types::Time#coerce. The zone is the
224
- # declaration, not the value.
225
- raise ArgumentError,
226
- "names a local time that does not exist in #{timezone.identifier} (skipped by a daylight-saving change)"
227
- end
228
-
229
- # @param time [::Time] an instant
230
- # @param timezone [Object] a +TZInfo::Timezone+
231
- # @return [::Time] the same instant at the zone's offset at that instant
232
- def self.in_zone(time, timezone)
233
- time.getlocal(timezone.period_for(time).observed_utc_offset)
234
- end
235
-
236
- # @param value [::Date] a plain Date
237
- # @param zone [::String] a declared +zone:+
238
- # @return [::Time] midnight at +zone+'s offset — for a name, the first
239
- # moment of that day
240
- def self.midnight(value, zone)
241
- offset = offset_seconds(zone)
242
- return named_midnight(value, timezone(zone)) if offset.nil?
243
-
244
- time = ::Time.new(value.year, value.mon, value.mday, 0, 0, 0, offset)
245
- zone == 'UTC' ? time.utc : time
246
- end
247
-
248
- # @param value [::Date] a plain Date
249
- # @param timezone [Object] a +TZInfo::Timezone+
250
- # @return [::Time] the first moment of that day in the zone
251
- def self.named_midnight(value, timezone)
252
- local(timezone, [value.year, value.mon, value.mday, 0, 0, 0])
253
- rescue ArgumentError
254
- # The zone skips midnight: the day starts where the gap ends, the
255
- # instant midnight would be at the offset in force just before it.
256
- before = timezone.period_for_local(::Time.utc(value.year, value.mon, value.mday) - 1, true, &:last)
257
- in_zone(::Time.utc(value.year, value.mon, value.mday) - before.observed_utc_offset, timezone)
258
- end
259
-
260
- # @param seconds [::Integer] seconds east of UTC
261
- # @return [::String] +"+HH:MM"+ / +"-HH:MM"+
262
- def self.offset_text(seconds)
263
- format('%s%02d:%02d', seconds.negative? ? '-' : '+', seconds.abs / 3600, (seconds.abs % 3600) / 60)
264
- end
265
- end
266
- end
267
- end