calcsheet 0.1.0

data/lib/calcsheet/cast.rb

@@ -0,0 +1,578 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+require "set"
+require_relative "decimal_text"
+require_relative "excel_serial"
+require_relative "time_zone"
+
+module Calcsheet
+  # The types a column can declare.
+  TYPES = %i[string integer decimal date datetime boolean].freeze
+
+  # Turns cell text into native or declared Ruby values. Every reader backend goes
+  # through it, so the methods avoid needless allocations: patterns are compiled once,
+  # decimals are built from the text (never through Float) and native strings are
+  # returned without copying. A value that cannot be converted raises Failure.
+  #
+  # The +type+ of each method is a member of TYPES, or nil for the native value; another raises ArgumentError.
+  class Cast
+    # Raised when a cell cannot be converted. Internal and lightweight: the reader turns it
+    # into a Calcsheet::CellError with the position of the cell.
+    class Failure < StandardError
+      # @return [Symbol] :invalid_integer, :not_integral, :invalid_decimal, :invalid_date,
+      #   :invalid_datetime or :invalid_boolean; :cell_error for an error cell, which the ODS and XLSX readers raise
+      #   or record themselves
+      attr_reader :reason
+      # @return [Object] the raw input
+      attr_reader :value
+
+      # @param reason [Symbol] see #reason
+      # @param value [Object] the raw input
+      def initialize(reason, value)
+        super(reason.to_s)
+        @reason = reason
+        @value = value
+      end
+    end
+
+    # The reason of a value that a declared type cannot take.
+    FAILURES = {
+      integer: :invalid_integer, decimal: :invalid_decimal, date: :invalid_date,
+      datetime: :invalid_datetime, boolean: :invalid_boolean
+    }.freeze
+
+    # The longest text of a number, a date, a time or a duration. The patterns below are only ever matched
+    # against text this long or shorter: their backtracking costs memory in proportion to the length of the text.
+    MAX_NUMBER_BYTES = 1_024
+
+    # A number as BigDecimal reads it: a sign, digits with an optional point, an exponent of at most four digits.
+    NUMBER = /\A[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d{1,4})?\z/
+    # An integer: a sign and digits.
+    INTEGER = /\A[+-]?\d+\z/
+    # Digits only.
+    DIGITS = /\A\d+\z/
+    # A date serial, not negative, without exponent: the common text of an XLSX date (see #serial_units).
+    SERIAL = /\A\d+(?:\.\d+)?\z/
+    # An ODS date-value or XLSX t="d" value: date, then optionally the time, its fraction and a "Z" or "+hh:mm" offset.
+    ISO_DATE = /\A(\d{4})-(\d\d)-(\d\d)(?:T(\d\d):(\d\d):(\d\d)(?:\.(\d+))?(?:(Z)|([+-])(\d\d):(\d\d))?)?\z/
+    # A character that is not whitespace: a text without one is blank.
+    NON_BLANK = /[^[:space:]]/
+    # An ODS time-value: an xsd:duration of days, hours, minutes and seconds (with a fraction).
+    DURATION = /\AP(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)(?:\.(\d+))?S)?)?\z/
+
+    # The strptime directives that date_formats and datetime_formats may use, with the text each one reads (the
+    # widths Date._strptime takes). A %Y year has exactly four digits. Date._strptime reads the digits of a numeric
+    # directive greedily and never gives one back, so they are atomic groups: otherwise "%d%m%Y" would match
+    # "0102026" as 01|0|2026, where Date._strptime reads 01|02|026. Date._strptime also reads one digit after a
+    # leading space for %d and %e, %H and %k, %I and %l alike; the patterns accept that space only for %e, %k and %l,
+    # so a %d, %H or %I text with a space before one digit passes only when the year anchor spares it the pattern
+    # (see .date_format).
+    FORMAT_DIRECTIVES = {
+      "Y" => "\\d{4}", "y" => "(?>\\d{1,2})", "m" => "(?>\\d{1,2})", "d" => "(?>\\d{1,2})", "e" => "(?> \\d|\\d{1,2})",
+      "b" => "[[:alpha:]]+", "B" => "[[:alpha:]]+", "h" => "[[:alpha:]]+", "a" => "[[:alpha:]]+", "A" => "[[:alpha:]]+",
+      "H" => "(?>\\d{1,2})", "k" => "(?> \\d|\\d{1,2})", "I" => "(?>\\d{1,2})", "l" => "(?> \\d|\\d{1,2})", "M" => "(?>\\d{1,2})",
+      "S" => "(?>\\d{1,2})", "p" => "(?i:[ap]\\.?m\\.?)", "P" => "(?i:[ap]\\.?m\\.?)",
+      "F" => "\\d{4}-(?>\\d{1,2})-(?>\\d{1,2})", "T" => "(?>\\d{1,2}):(?>\\d{1,2}):(?>\\d{1,2})",
+      "R" => "(?>\\d{1,2}):(?>\\d{1,2})", "%" => "%"
+    }.freeze
+
+    # Excel keeps 15 significant digits; a double printed in full (the shortest text that reads back as the same
+    # double) has up to 17, so 16 or 17 are the binary artifact of a value Excel saw with 15.
+    SIGNIFICANT_DIGITS = 15
+    # The significant digits of the full print of a double that Excel saw with 15.
+    DOUBLE_DIGITS = 16..17
+    # Beyond this a whole number stays a BigDecimal instead of becoming a huge Integer.
+    MAX_INTEGER_EXPONENT = 30
+    # The units of a day for date serials (seconds).
+    SECONDS_PER_DAY = ExcelSerial::SECONDS_PER_DAY
+    # The units of a day for time serials and durations (milliseconds).
+    MILLIS_PER_DAY = SECONDS_PER_DAY * 1000
+
+    # The pieces of a date format: a directive (or a "%" ending it), a run of whitespace, or other text.
+    FORMAT_PIECE = /%(.)|%\z|\s+|[^%\s]+/m
+    # A format with a year that Date._strptime would read at any length: it gets a pattern (see .date_format).
+    YEAR_DIRECTIVES = /%[YF]/
+    # Directives that read digits only (with a space before them for %e and %k), and the literal text that can
+    # anchor a year after them: no digit, letter or whitespace.
+    NUMERIC_DIRECTIVES = %w[%m %d %e %H %k %M %S %y %%].freeze
+    # Literal text that can anchor a year: no digit, letter, whitespace or "%".
+    ANCHOR_TEXT = /\A[^[:alnum:][:space:]%]+\z/
+
+    # A date or datetime format compiled once per Cast, as +[format, pattern, anchor]+. Date._strptime reads a %Y year
+    # of any length and sign, so a format with %Y (or %F) gets a pattern that the text must match: each directive as
+    # FORMAT_DIRECTIVES gives it, whitespace as any whitespace (as Date._strptime reads it), every other character as
+    # itself. Matching it for every date would cost about 3% of a CSV read, so the anchor tells where the year text
+    # starts in a text Date._strptime read: 0 for the start, the byte before a %Y that ends the text, or a character
+    # whose last occurrence precedes it (only numeric directives and other characters before the year, none of that
+    # character after it). A year from 1000 to 9999 whose text starts there with a digit 1-9 has four digits; any
+    # other year, or a format without an anchor, is checked on the pattern (see #parse_fields).
+    #
+    # @api private
+    # @param format [String] a format of the supported directives (OptionValidation checks them)
+    # @return [Array(String, Regexp | nil, Integer | String | nil)]
+    # @raise [ArgumentError] for another directive
+    def self.date_format(format)
+      return [ format, nil, nil ].freeze unless YEAR_DIRECTIVES.match?(format)
+
+      pieces = []
+      format.scan(FORMAT_PIECE) { pieces << Regexp.last_match(0) }
+      source = pieces.map do |piece|
+        if piece.start_with?("%")
+          FORMAT_DIRECTIVES.fetch(piece[1]) { raise ArgumentError, "unsupported directive #{piece} in #{format.inspect}" }
+        elsif piece.match?(/\A\s/) then "\\s*"
+        else Regexp.escape(piece)
+        end
+      end.join
+      [ format, Regexp.new("\\A#{source}\\z"), year_anchor(pieces) ].freeze
+    end
+
+    # @return [Integer, String, nil] 0 when the first piece is %Y or %F; the last byte of the character before a %Y
+    #   that ends the format; the character after whose last occurrence the first %Y or %F starts; nil when another
+    #   directive or whitespace precedes it, or the character follows it. Offsets are in bytes throughout.
+    def self.year_anchor(pieces)
+      year = pieces.index { %w[%Y %F].include?(_1) } or return
+      return 0 if year.zero?
+
+      before = pieces.first(year)
+      return unless before.all? { |piece| NUMERIC_DIRECTIVES.include?(piece) || piece.match?(ANCHOR_TEXT) }
+      return if before.last.start_with?("%")
+
+      char = before.last[-1]
+      after = pieces.drop(year + 1)
+      return if after.any? { |piece| piece.include?(char) || %w[%p %P].include?(piece) }
+
+      # A year that ends the text (a %Y last) starts 4 bytes before the end, after the character.
+      after.empty? && pieces[year] == "%Y" ? char.bytes.last : char
+    end
+    private_class_method :year_anchor
+
+    # @return [Options] the options of the read, for backends that apply format-specific ones themselves
+    attr_reader :options
+
+    # @param options [Options]
+    # @param date1904 [Boolean] the workbook counts days from 1904-01-01
+    def initialize(options, date1904: false)
+      @options = options
+      @date1904 = date1904
+      @zone = TimeZone.wrap(options.time_zone)
+      # Instants (ISO datetimes with "Z" or an offset) are converted into the zone when it can do so; a zone that
+      # only builds times from fields (responds to local alone) leaves them in UTC.
+      @instant_zone = TimeZone.converts?(@zone) ? @zone : TimeZone::UTC
+      @float = options.decimals == :float
+      @decimal_separator = options.decimal_separator
+      @thousands_separator = options.thousands_separator.to_s.empty? ? nil : options.thousands_separator
+      @plain_numbers = @decimal_separator == "." && @thousands_separator.nil?
+      # Digits grouped by three from the decimal separator, which a text with the thousands separator must match.
+      @grouped = @thousands_separator &&
+                 /\A[+-]?\d{1,3}(?:#{Regexp.escape(@thousands_separator)}\d{3})*(?:#{Regexp.escape(@decimal_separator)}\d+)?\z/
+      @date_formats = options.date_formats.map { self.class.date_format(_1) }
+      @datetime_formats = options.datetime_formats.map { self.class.date_format(_1) }
+      @true_words = options.true_words.to_set { _1.downcase }
+      @false_words = options.false_words.to_set { _1.downcase }
+    end
+
+    # A text cell (CSV, XLSX and ODS strings).
+    # @param str [String]
+    # @param type [Symbol, nil] a member of TYPES, or nil for the native value (the string itself)
+    # @return [Object, nil] the value; nil for a whitespace-only text read as any type but :string
+    # @raise [Failure] the text is not a value of the type
+    def text(str, type)
+      case type
+      when nil, :string then str
+      when :integer then text_integer(str)
+      when :decimal then text_decimal(str)
+      when :date then text_date(str)
+      when :datetime then text_datetime(str)
+      when :boolean then boolean_text(str)
+      else reject(type, str)
+      end
+    end
+
+    # A numeric cell.
+    # @param text [String] the cell text
+    # @param kind [Symbol] :general, or :date, :datetime or :time when the number format makes it a serial
+    # @param type [Symbol, nil] a member of TYPES, or nil for the native value
+    # @param pad [Integer, nil] digits of a zero-padding number format, restored for :string
+    # @return [Object] the value: native, an Integer, BigDecimal (or Float with +decimals: :float+), Date or Time;
+    #   seconds for :time
+    # @raise [Failure] the text is no number, is longer than MAX_NUMBER_BYTES, or is not a value of the type (a date
+    #   type for a :general number, for instance)
+    # @raise [ArgumentError] an unknown +kind+
+    def number(text, kind, type, pad: nil)
+      if text.bytesize > MAX_NUMBER_BYTES
+        raise Failure.new(FAILURES[type] || (%i[date datetime].include?(kind) ? :"invalid_#{kind}" : :invalid_decimal), text)
+      end
+
+      case kind
+      when :general then general_number(text, type, pad)
+      when :date, :datetime then date_serial(text, kind, type)
+      when :time then time_serial(text, type)
+      else raise ArgumentError, "unknown number kind: #{kind.inspect}"
+      end
+    end
+
+    # An ODS +date-value+ or XLSX +t="d"+ value: "2026-01-01" or "2026-01-01T10:00:00[.fff]", wall-clock fields
+    # read in the time zone. A datetime with a "Z" or "+hh:mm" suffix is an instant, given in UTC, or in the time zone
+    # when one is configured that can convert instants (see TimeZone.converts?); in UTC otherwise.
+    # @param kind [Symbol, nil] :date or :datetime when the cell's number format decides it (a date drops the time, a
+    #   datetime may be at midnight); otherwise the text decides
+    # @return [Date, Time, String] a Date, a Time, or for :string the ISO text
+    # @raise [Failure] an invalid date, time or offset, a year 0, or a declared :integer, :decimal or :boolean
+    def iso_date(text, type, kind = nil)
+      return invalid_iso_date(text, type) if text.bytesize > MAX_NUMBER_BYTES
+
+      match = ISO_DATE.match(text) or return invalid_iso_date(text, type)
+      year = match[1].to_i
+      month = match[2].to_i
+      day = match[3].to_i
+      # Spreadsheet dates start in the year 1; Ruby's proleptic calendar would take 0000 too.
+      return invalid_iso_date(text, type) unless year.positive? && Date.valid_civil?(year, month, day)
+
+      date = Date.new(year, month, day)
+      return temporal(date, 0, kind == :datetime ? :datetime : :date, type, text) unless match[4]
+
+      hour = match[4].to_i
+      min = match[5].to_i
+      sec = match[6].to_i
+      return invalid_iso_date(text, type) unless hour < 24 && min < 60 && sec < 60
+
+      seconds = hour * 3600 + min * 60 + sec
+      seconds += 1 if match[7] && match[7].getbyte(0) >= 53 # first fractional digit >= "5"
+      if seconds >= SECONDS_PER_DAY
+        date += 1
+        seconds -= SECONDS_PER_DAY
+      end
+      zone = @zone
+      date, seconds, zone = in_zone(date, seconds, match, text, type) if match[8] || match[9]
+      return temporal(date, 0, :date, type, text) if kind == :date
+
+      temporal(date, seconds, :datetime, type, text, zone)
+    end
+
+    # An ODS +time-value+: "PT12H30M05S".
+    # @return [Integer, BigDecimal, Float, String] whole seconds, fractional ones (rounded to the millisecond), or
+    #   for :string the clock text "12:30:05"
+    # @raise [Failure] an invalid duration, or a type that a duration cannot be
+    def duration(text, type)
+      match = DURATION.match(text) unless text.bytesize > MAX_NUMBER_BYTES
+      unless match && (match[1] || match[2] || match[3] || match[4])
+        raise Failure.new(FAILURES[type] || :invalid_decimal, text)
+      end
+
+      seconds = (((match[1].to_i * 24 + match[2].to_i) * 60 + match[3].to_i) * 60) + match[4].to_i
+      millis = seconds * 1000
+      if (fraction = match[5])
+        scale = 10**fraction.size
+        millis += (fraction.to_i * 2000 + scale) / (scale * 2)
+      end
+      seconds_value(millis, type, text)
+    end
+
+    # A boolean cell.
+    # @param value [Boolean]
+    # @return [Boolean, String, Integer, BigDecimal] the value; "true"/"false", 1/0 for the other types
+    # @raise [Failure] for :date and :datetime
+    def boolean(value, type)
+      case type
+      when nil, :boolean then value
+      when :string then value.to_s
+      when :integer then value ? 1 : 0
+      when :decimal then BigDecimal(value ? 1 : 0)
+      else reject(type, value)
+      end
+    end
+
+    private
+
+    def reject(type, value)
+      reason = FAILURES[type] or raise ArgumentError, "unknown type: #{type.inspect}"
+      raise Failure.new(reason, value)
+    end
+
+    # --- text cells ---------------------------------------------------------------------
+
+    # A text with the thousands separator must have its integer digits grouped by three: "12.5" or
+    # "1.2.3,5" is no number when "." groups thousands, rather than 125 or 123.5.
+    # @return [String, nil] the text with "." as decimal point and no grouping; nil when it cannot be a number or is
+    #   longer than MAX_NUMBER_BYTES
+    def normalize(str)
+      string = str.strip
+      return if string.bytesize > MAX_NUMBER_BYTES
+      return string if @plain_numbers
+
+      if @thousands_separator && string.include?(@thousands_separator)
+        return unless @grouped.match?(string)
+
+        string = string.gsub(@thousands_separator, "")
+      end
+      unless @decimal_separator == "."
+        # A dot that is neither the decimal nor the thousands separator is not a number.
+        return nil if string.include?(".")
+
+        string = string.gsub(@decimal_separator, ".")
+      end
+      string
+    end
+
+    def text_integer(str)
+      string = normalize(str)
+      return blank_or_invalid(:invalid_integer, str) unless string
+      return string.to_i if INTEGER.match?(string)
+      return blank_or_invalid(:invalid_integer, str) unless NUMBER.match?(string)
+
+      integral(BigDecimal(string), str)
+    end
+
+    def text_decimal(str)
+      string = normalize(str)
+      return blank_or_invalid(:invalid_decimal, str) unless string && NUMBER.match?(string)
+
+      BigDecimal(string)
+    end
+
+    def text_date(str)
+      string = str.strip
+      fields = parse_fields(string, @date_formats) || parse_fields(string, @datetime_formats)
+      return blank_or_invalid(:invalid_date, str) unless fields
+
+      Date.new(fields[0], fields[1], fields[2])
+    end
+
+    def text_datetime(str)
+      string = str.strip
+      fields = parse_fields(string, @datetime_formats) || parse_fields(string, @date_formats)
+      return blank_or_invalid(:invalid_datetime, str) unless fields
+
+      @zone.local(*fields)
+    end
+
+    # A text of whitespace only is a blank cell for every declared type but :string: nil, which a required column
+    # reports as :required. Checked only once a cast failed, so that a valid text costs nothing more.
+    def blank_or_invalid(reason, str)
+      return unless NON_BLANK.match?(str)
+
+      raise Failure.new(reason, str)
+    end
+
+    # The first format that matches the whole text with a real calendar date and time of day (see .date_format). A
+    # %Y year from 1000 to 9999 had four digits, unless the text has a "+" or leading zeros that leave its value
+    # right; any other year is checked on the pattern.
+    # @return [Array<Integer>, nil] year, month, day, hour, minute, second
+    def parse_fields(string, formats)
+      return if string.bytesize > MAX_NUMBER_BYTES
+
+      formats.each do |format, pattern, anchor|
+        fields = Date._strptime(string, format)
+        next if fields.nil? || fields.key?(:leftover)
+
+        year = fields[:year]
+        month = fields[:mon]
+        day = fields[:mday]
+        next unless year && month && day && Date.valid_civil?(year, month, day)
+
+        hour = fields[:hour] || 0
+        min = fields[:min] || 0
+        sec = fields[:sec] || 0
+        next unless hour < 24 && min < 60 && sec < 60
+        if pattern
+          # Inline, without a method call per date (see .date_format).
+          byte =
+            if anchor == 0 then string.getbyte(0)
+            elsif anchor.is_a?(Integer) then string.getbyte(-5) == anchor && string.getbyte(-4)
+            else anchor && (last = string.byterindex(anchor)) && string.getbyte(last + anchor.bytesize)
+            end
+          # A year text starting with "1".."9" (bytes 49..57) and a value of four digits has four digits.
+          next unless (byte && byte > 48 && byte < 58 && year > 999 && year < 10_000) || pattern.match?(string)
+        end
+        return [ year, month, day, hour, min, sec ]
+      end
+      nil
+    end
+
+    def boolean_text(str)
+      word = str.strip.downcase
+      if @true_words.include?(word) then true
+      elsif @false_words.include?(word) then false
+      else blank_or_invalid(:invalid_boolean, str)
+      end
+    end
+
+    # --- general numbers ----------------------------------------------------------------
+
+    def general_number(text, type, pad)
+      case type
+      when nil then native_number(text)
+      when :decimal then parse_number(text)
+      when :integer then integer_number(text)
+      when :string then number_string(text, pad)
+      when :boolean then boolean_number(text)
+      else reject(type, text)
+      end
+    end
+
+    # BigDecimal from the cell text, rounded half up to 15 significant digits only when the text is the full print
+    # of a double: a fraction or an exponent with 16 or 17 significant digits. Integer text (digits and a sign) is
+    # exact, and so is text with more than 17 significant digits, which no double prints. The explicit mode keeps a
+    # BigDecimal: without it, BigDecimal#round returns an Integer for a negative digit count. BigDecimal#exponent is
+    # the power of ten of 0.ddd... x 10**exponent, so 15 significant digits are 15 - exponent decimals. A text of at
+    # most 15 bytes has at most 15 significant digits: it is never rounded.
+    def parse_number(text)
+      raise Failure.new(:invalid_decimal, text) unless NUMBER.match?(text)
+
+      number = BigDecimal(text)
+      if text.bytesize > SIGNIFICANT_DIGITS && DOUBLE_DIGITS.cover?(number.n_significant_digits) && !INTEGER.match?(text)
+        number = number.round(SIGNIFICANT_DIGITS - number.exponent, BigDecimal::ROUND_HALF_UP)
+      end
+      number
+    end
+
+    # The fast path: integer text of at most 15 bytes reads as String#to_i, the Integer the BigDecimal below would
+    # give (far fewer digits than MAX_INTEGER_EXPONENT), without building it.
+    def native_number(text)
+      return text.to_i if text.bytesize <= SIGNIFICANT_DIGITS && INTEGER.match?(text)
+
+      number = parse_number(text)
+      if number.frac.zero?
+        number.exponent <= MAX_INTEGER_EXPONENT ? number.to_i : number
+      else
+        @float ? number.to_f : number
+      end
+    end
+
+    # Integer text is exact whatever its length (at most MAX_NUMBER_BYTES). A fraction fails with the number as read
+    # (its plain text, rounded like every stored number), not the full print of a double that a file may hold.
+    def integer_number(text)
+      raise Failure.new(:invalid_integer, text) unless NUMBER.match?(text)
+      return text.to_i if INTEGER.match?(text)
+
+      number = parse_number(text)
+      raise Failure.new(:not_integral, DecimalText.plain(number)) unless number.frac.zero?
+
+      integral(number, text)
+    end
+
+    # 1 and 0, whatever the configured words are.
+    def boolean_number(text)
+      raise Failure.new(:invalid_boolean, text) unless NUMBER.match?(text)
+
+      case native_number(text)
+      when 1 then true
+      when 0 then false
+      else raise Failure.new(:invalid_boolean, text)
+      end
+    end
+
+    def integral(number, raw)
+      raise Failure.new(:not_integral, raw) unless number.frac.zero?
+      raise Failure.new(:invalid_integer, raw) if number.exponent > MAX_INTEGER_EXPONENT
+
+      number.to_i
+    end
+
+    # Digits of at most 15 bytes are taken as written, without a BigDecimal; any other number as its plain text.
+    def number_string(text, pad)
+      string =
+        if text.bytesize <= SIGNIFICANT_DIGITS && DIGITS.match?(text)
+          text
+        else
+          DecimalText.plain(parse_number(text))
+        end
+      pad && DIGITS.match?(string) ? string.rjust(pad, "0") : string
+    end
+
+    # --- serials ------------------------------------------------------------------------
+
+    # The serial as a whole number of units (seconds or milliseconds), rounded half up, with
+    # integer arithmetic only.
+    # @return [Integer, nil] nil when the text is not a number
+    def serial_units(text, per_day)
+      if SERIAL.match?(text)
+        dot = text.index(".")
+        return text.to_i * per_day unless dot
+
+        digits = text.bytesize - dot - 1
+        scale = 10**digits
+        text.to_i * per_day + (text[dot + 1, digits].to_i * per_day * 2 + scale) / (scale * 2)
+      elsif NUMBER.match?(text)
+        (Rational(text) * per_day + Rational(1, 2)).floor
+      end
+    end
+
+    def date_serial(text, kind, type)
+      total = serial_units(text, SECONDS_PER_DAY)
+      days, seconds = total.divmod(SECONDS_PER_DAY) if total && total >= 0
+      date = days && ExcelSerial.date(days, date1904: @date1904)
+      raise Failure.new(FAILURES[type] || (kind == :date ? :invalid_date : :invalid_datetime), text) unless date
+
+      temporal(date, kind == :date ? 0 : seconds, kind, type, text)
+    end
+
+    def time_serial(text, type)
+      millis = serial_units(text, MILLIS_PER_DAY)
+      raise Failure.new(FAILURES[type] || :invalid_decimal, text) unless millis && millis >= 0
+
+      seconds_value(millis, type, text)
+    end
+
+    # --- shared conversions -------------------------------------------------------------
+
+    # A date, or a date with a time of day (seconds since midnight), as the requested type.
+    def temporal(date, seconds, kind, type, raw, zone = @zone)
+      case type
+      when nil then kind == :date ? date : time_of(date, seconds, zone)
+      when :date then date
+      when :datetime then time_of(date, seconds, zone)
+      when :string then kind == :date ? date.iso8601 : "#{date.iso8601}T#{clock(seconds)}"
+      else reject(type, raw)
+      end
+    end
+
+    def time_of(date, seconds, zone = @zone)
+      hour, rest = seconds.divmod(3600)
+      min, sec = rest.divmod(60)
+      zone.local(date.year, date.month, date.day, hour, min, sec)
+    end
+
+    # A duration given in milliseconds as the requested type: whole seconds (Integer) when no
+    # fraction remains, BigDecimal (Float with decimals: :float) otherwise.
+    def seconds_value(millis, type, raw)
+      case type
+      when nil then (millis % 1000).zero? ? millis / 1000 : fractional_seconds(millis)
+      when :integer then (millis % 1000).zero? ? millis / 1000 : raise(Failure.new(:not_integral, raw))
+      when :decimal then BigDecimal(millis) / 1000
+      when :string then clock((millis + 500) / 1000)
+      else reject(type, raw)
+      end
+    end
+
+    def fractional_seconds(millis)
+      @float ? millis / 1000.0 : BigDecimal(millis) / 1000
+    end
+
+    def clock(seconds)
+      format("%02d:%02d:%02d", seconds / 3600, seconds % 3600 / 60, seconds % 60)
+    end
+
+    # The wall-clock date and seconds of the instant given by UTC +date+ and +seconds+ shifted by the offset of
+    # +match+ (nil for "Z"), in the zone that converts instants, and that zone.
+    def in_zone(date, seconds, match, text, type)
+      offset = 0
+      if match[9]
+        hours = match[10].to_i
+        minutes = match[11].to_i
+        return invalid_iso_date(text, type) unless hours < 24 && minutes < 60
+
+        offset = (hours * 3600 + minutes * 60) * (match[9] == "-" ? -1 : 1)
+      end
+      instant = Time.utc(date.year, date.month, date.day) + (seconds - offset)
+      year, month, day, hour, min, sec = TimeZone.wall_clock(@instant_zone, instant)
+      [ Date.new(year, month, day), hour * 3600 + min * 60 + sec, @instant_zone ]
+    end
+
+    def invalid_iso_date(text, type)
+      raise Failure.new(FAILURES[type] || (text.include?("T") ? :invalid_datetime : :invalid_date), text)
+    end
+  end
+end