iostreams 2.1.0 → 2.2.0

data/lib/io_streams/utils.rb

@@ -5,6 +5,81 @@ module IOStreams
   module Utils
     MAX_TEMP_FILE_NAME_ATTEMPTS = 5
 
+    # Replaces the value of a sensitive option for display, see .redact_options.
+    FILTERED = "[FILTERED]".freeze
+
+    # Option names whose values are hidden as a precaution, even when they are not declared sensitive.
+    # Matched against the name in lower case without `_` or `-`, see .redact_options.
+    SENSITIVE_NAME = /passphrase|password|secret|token|credential|auth|apikey|privatekey/
+    private_constant :SENSITIVE_NAME
+
+    # Returns [Hash] the options with the value of each sensitive option replaced with FILTERED, so that they can be
+    # displayed, for example by `#inspect`, or in a web interface.
+    #
+    # An option is sensitive when its name is one of the supplied `sensitive_names`, or, as a precaution, contains
+    # `passphrase`, `password`, `secret`, `token`, `credential`, `auth`, `apikey` or `privatekey`. Names are compared in
+    # lower case, ignoring `_` and `-`, so that `:identity_key` matches the ssh option "IdentityKey", and the header
+    # "X-Api-Key" contains `apikey`. The options in a Hash value, such as `ssh_options:` or `client:`, are redacted the
+    # same way, as are those in an Array value, whether its elements are Hashes or `[name, value]` pairs.
+    def self.redact_options(options, sensitive_names = [])
+      redact_hash(options, sensitive_names.map { |name| normalize_option_name(name) })
+    end
+
+    # Returns [Hash] the options of each stream, by its name, such as those supplied to `IOStreams::Stream#stream`, with
+    # the value of each sensitive option replaced with FILTERED, as the extension that the block returns for the name of
+    # the stream decides, see `IOStreams::Extension#redact_options`.
+    #
+    # Every value of a stream is replaced when the block returns nil, since no extension can say which are sensitive,
+    # and options that are not a Hash are replaced whole, since they cannot say which of their values are sensitive.
+    # Options that are nil are kept.
+    def self.redact_streams(streams)
+      streams.to_h do |name, options|
+        next [name, options] if options.nil?
+        next [name, FILTERED] unless options.is_a?(Hash)
+
+        extension = yield(name)
+        [name, extension ? extension.redact_options(options) : options.transform_values { FILTERED }]
+      end
+    end
+
+    def self.redact_hash(options, sensitive)
+      options.to_h { |name, value| [name, redact_option(name, value, sensitive)] }
+    end
+    private_class_method :redact_hash
+
+    # Returns the value of the named option for display, see .redact_options.
+    def self.redact_option(name, value, sensitive)
+      key = normalize_option_name(name)
+      return FILTERED if sensitive.include?(key) || key.match?(SENSITIVE_NAME)
+
+      redact_value(value, sensitive)
+    end
+    private_class_method :redact_option
+
+    # Returns the value with the options within it redacted, when it is a Hash or an Array, see .redact_options.
+    def self.redact_value(value, sensitive)
+      case value
+      when Hash
+        redact_hash(value, sensitive)
+      when Array
+        value.map do |element|
+          if element.is_a?(Array) && element.size == 2 && (element.first.is_a?(String) || element.first.is_a?(Symbol))
+            [element.first, redact_option(element.first, element.last, sensitive)]
+          else
+            redact_value(element, sensitive)
+          end
+        end
+      else
+        value
+      end
+    end
+    private_class_method :redact_value
+
+    def self.normalize_option_name(name)
+      name.to_s.downcase.delete("_-")
+    end
+    private_class_method :normalize_option_name
+
     # Lazy load dependent gem so that it remains a soft dependency.
     def self.load_soft_dependency(gem_name, stream_type, require_name = gem_name)
       require require_name
@@ -12,17 +87,47 @@ module IOStreams
       raise(LoadError, "Please install the gem '#{gem_name}' to support #{stream_type}. #{e.message}")
     end
 
-    # Log a warning for options that a stream ignores, until they raise `ArgumentError` in v3.0.
-    def self.warn_unknown_options(unknown, stream, direction, valid)
+    # Log a warning for options that a stream ignores when reading (type: :reader) or writing (:writer): those that the
+    # class of the other direction takes, other_names, which v3.0 also accepts, and ignores, and the others, which v3.0
+    # raises `ArgumentError` for. A path supplies other_names, and the stream as it was set, see
+    # `IOStreams::Builder#taken_options`; without them, as when a class is opened directly, each option is one that
+    # v3.0 raises for, since its class takes only its own options.
+    #
+    # Those of neither direction are deprecated, and report a deprecation warning when they are set, see
+    # `IOStreams::Builder#option`.
+    def self.warn_unknown_options(unknown, stream, type, valid, other_names = [])
       return if unknown.empty?
 
-      names = unknown.keys.map(&:inspect).join(", ")
+      other     = unknown.keys & other_names
+      neither   = unknown.keys - other
+      direction = type == :reader ? "reading" : "writing"
+      unless other.empty?
+        IOStreams.logger&.warn(
+          "Ignoring #{other.map(&:inspect).join(', ')} when #{direction} a #{stream.inspect} stream, since " \
+          "#{other.size == 1 ? 'it only applies' : 'they only apply'} when #{type == :reader ? 'writing' : 'reading'}."
+        )
+      end
+      return if neither.empty?
+
       IOStreams.logger&.warn(
-        "Ignoring unknown #{unknown.size == 1 ? 'option' : 'options'} #{names} when #{direction} a #{stream.inspect} " \
-        "stream. Valid options: #{valid.map(&:inspect).join(', ')}. In v3.0 this will raise ArgumentError."
+        "Ignoring unknown #{neither.size == 1 ? 'option' : 'options'} #{neither.map(&:inspect).join(', ')} when " \
+        "#{direction} a #{stream.inspect} stream. Valid options: #{valid.map(&:inspect).join(', ')}. " \
+        "In v3.0 this will raise ArgumentError."
       )
     end
 
+    # Returns [String] the string as UTF-8 text that can be displayed or logged, such as the name of a file, which is not
+    # always valid UTF-8, since a file system stores the bytes that a program gave it: a binary string is read as UTF-8,
+    # and each byte that is not valid UTF-8 is shown as `\xHH`.
+    #
+    # For example the name of a file in Latin-1, `caf\xE9.csv`, is displayed as "caf\\xE9.csv".
+    def self.display_text(string)
+      text = string.encoding == Encoding::BINARY ? string.dup.force_encoding(Encoding::UTF_8) : string
+      return text if text.valid_encoding?
+
+      text.scrub { |bytes| bytes.unpack("C*").map { |byte| format("\\x%02X", byte) }.join }
+    end
+
     # Helper method: Returns [true|false] if a value is blank?
     def self.blank?(value)
       return true if value.nil?
@@ -31,6 +136,106 @@ module IOStreams
       value.respond_to?(:empty?) ? value.empty? : !value
     end
 
+    # Text that is blank, see .blank_text?: empty, or only whitespace, as Rails' `String#blank?` matches it.
+    BLANK_TEXT = /\A[[:space:]]*\z/
+    private_constant :BLANK_TEXT
+
+    # The pattern of BLANK_TEXT in each encoding that it cannot be matched against, such as UTF-16, see .blank_text?.
+    @encoded_blank_texts = {}
+    @encoded_blank_texts_mutex = Mutex.new
+
+    # The rules below of what is blank apply to the rows and records read and written with a schema, see
+    # `IOStreams::Tabular::SchemaMapping`, as IOStreams 3.0 applies them to every file, while a file without a schema
+    # keeps those of .blank?.
+
+    # Returns [true|false] whether the text is blank, by the rules of Rails' `String#blank?`: empty, or only whitespace,
+    # which is any Unicode whitespace, such as a no-break space (U+00A0) or an ideographic space (U+3000), not only a
+    # space, tab, or line ending. Text in an encoding that is not ASCII compatible, such as UTF-16, is matched in its own
+    # encoding, as Rails matches it.
+    #
+    # Raises ArgumentError for text whose bytes are not valid in its encoding, as Rails does.
+    def self.blank_text?(text)
+      text.empty? || BLANK_TEXT.match?(text)
+    rescue Encoding::CompatibilityError
+      encoded_blank_text(text.encoding).match?(text)
+    end
+
+    # Returns [true|false] whether a value within a row or record is blank, so that it holds no data: nil, or text that
+    # is blank, see .blank_text?. Any other value is data, such as false, 0, an empty Array, or text whose bytes are not
+    # valid in its encoding, since it is not text that is known to be blank.
+    def self.blank_value?(value)
+      value.nil? || (value.is_a?(String) && value.valid_encoding? && blank_text?(value))
+    end
+
+    # Returns [true|false] whether a row or record is blank, so that it holds no data: nil, or an Array or Hash without
+    # values, or whose every value is blank, see .blank_value?, such as the row of a line of CSV of only commas, or a
+    # record of JSON whose every value is null.
+    def self.blank_row?(row)
+      case row
+      when nil then true
+      when ::Hash then row.each_value.all? { |value| blank_value?(value) }
+      when ::Array then row.all? { |value| blank_value?(value) }
+      else false
+      end
+    end
+
+    # Returns [Regexp] the pattern of blank text in the supplied encoding, see .blank_text?, created once for each one.
+    def self.encoded_blank_text(encoding)
+      @encoded_blank_texts_mutex.synchronize do
+        @encoded_blank_texts[encoding] ||=
+          Regexp.new(BLANK_TEXT.source.encode(encoding), BLANK_TEXT.options | Regexp::FIXEDENCODING)
+      end
+    end
+    private_class_method :encoded_blank_text
+
+    # Returns [String] the text, taken as UTF-8 when it is binary, as IOStreams 2 reads a file without an encoding,
+    # see `IOStreams::Stream#encoding`, such as a file read with a schema, whose text is UTF-8, see
+    # `IOStreams::Stream#schema`. Text in any other encoding is returned as it is.
+    #
+    # Raises `IOStreams::Errors::InvalidEncoding` when it is not valid UTF-8.
+    def self.utf8(text)
+      return text unless text.encoding == ::Encoding::BINARY
+
+      utf8 = text.dup.force_encoding(::Encoding::UTF_8)
+      return utf8 if utf8.valid_encoding?
+
+      raise(invalid_utf8(utf8))
+    end
+
+    # Returns [IOStreams::Errors::InvalidEncoding] the error for text taken as UTF-8 that is not valid UTF-8, naming
+    # its first invalid character, and the line that it is on when the number of the line that the text starts on is
+    # supplied, counting the line breaks within the text, such as within a quoted CSV value.
+    def self.invalid_utf8(utf8, line_number: nil)
+      invalid = nil
+      utf8.each_char do |char|
+        unless char.valid_encoding?
+          invalid = char.b
+          break
+        end
+        line_number += 1 if line_number && char == "\n"
+      end
+      on_line = line_number ? " on line #{line_number}" : ""
+      IOStreams::Errors::InvalidEncoding.new(
+        "#{invalid.inspect} is not valid UTF-8#{on_line}. Set the encoding of the file with #encoding",
+        line_number:          line_number,
+        error_char:           invalid,
+        source_encoding:      ::Encoding::BINARY,
+        destination_encoding: ::Encoding::UTF_8
+      )
+    end
+
+    # Returns a frozen copy of the value, whose Hashes, Arrays and Strings are frozen copies too, so that holding a
+    # setting, such as a schema, does not freeze the objects that the caller supplied, and the caller changing them
+    # does not change the setting. Any other value, such as a Symbol, is returned as it is.
+    def self.frozen_copy(value)
+      case value
+      when Hash then value.to_h { |key, item| [frozen_copy(key), frozen_copy(item)] }.freeze
+      when Array then value.map { |item| frozen_copy(item) }.freeze
+      when String then value.frozen? ? value : value.dup.freeze
+      else value
+      end
+    end
+
     # Yields the path to a temporary file_name.
     #
     # File is deleted upon completion if present.
@@ -64,8 +269,237 @@ module IOStreams
       end
     end
 
+    module PathName
+      # The byte of the separator of the names in a path, `/`, which every encoding that a path can be in, those that are
+      # ASCII-compatible, holds as this byte, see .join.
+      SEPARATOR = "/".ord
+      private_constant :SEPARATOR
+
+      # The byte of the `.` that starts the extension of a name, see .extname.
+      DOT = ".".ord
+      private_constant :DOT
+
+      # Whether `::File.join`, `::File.dirname`, `::File.extname` and `::File.basename` keep the bytes of a name that is
+      # not valid UTF-8, as CRuby does, rather than changing them, as JRuby does, see
+      # https://github.com/jruby/jruby/issues/9880, such as the name of a file in Latin-1 that SFTP lists as bytes, or
+      # that is labelled UTF-8, so that the path no longer names the file. Found by what they do, so that
+      # IOStreams uses them again once JRuby keeps the bytes.
+      FILE_KEEPS_NAMES =
+        begin
+          name  = "a\xE9".b
+          label = name.dup.force_encoding(Encoding::UTF_8)
+          ::File.join(name, name).b == "a\xE9/a\xE9".b && ::File.dirname("#{name}/x").b == name &&
+            ::File.extname("x.".b + name).b == ".a\xE9".b && ::File.basename("x/#{label}").b == name
+        end
+
+      # Returns [String] the supplied names joined into a path, as `::File.join` joins Strings: with one `/` between
+      # each name and the next, whose separators decide which are kept, keeping the bytes and the encoding of each name,
+      # where `::File.join` does, see FILE_KEEPS_NAMES, otherwise by .join_names.
+      def self.join(*names)
+        FILE_KEEPS_NAMES ? ::File.join(*names) : join_names(names)
+      end
+
+      # Returns [String] the directory of the supplied path, as `::File.dirname` returns it, see .join.
+      def self.dirname(path)
+        FILE_KEEPS_NAMES ? ::File.dirname(path) : dirname_of(path)
+      end
+
+      # Returns [String] the extension of the last name of the supplied path, as `::File.extname` returns it, see .join.
+      def self.extname(path)
+        FILE_KEEPS_NAMES ? ::File.extname(path) : extname_of(path)
+      end
+
+      # Returns [String] the last name of the supplied path, as `::File.basename` returns it, without the supplied
+      # suffix when it ends with it, see .join.
+      def self.basename(path, suffix = nil)
+        return basename_of(path, suffix) unless FILE_KEEPS_NAMES
+
+        suffix.nil? ? ::File.basename(path) : ::File.basename(path, suffix)
+      end
+
+      # Returns [String] the supplied Strings joined into a path, as CRuby's `File.join` joins them on POSIX, by their
+      # bytes: each name after the first is joined to the path so far with one `/`, unless the path ends with `/`, when
+      # it is added as it is, or the name starts with `/`, when the path loses its trailing `/` before it. The path starts
+      # in the encoding of the first name, and takes that of a name whose text needs it, as for `String#<<`, which raises
+      # `Encoding::CompatibilityError` for names that have no encoding in common.
+      #
+      # Used where `::File.join` changes names, see .join, and public, so that its tests compare it with CRuby's.
+      def self.join_names(names)
+        joined = String.new(encoding: names.first&.encoding || Encoding::BINARY)
+        names.each_with_index do |name, index|
+          if index.positive?
+            tail = trailing_separators(joined)
+            if name.getbyte(0) == SEPARATOR
+              joined = joined.byteslice(0, tail)
+            elsif tail == joined.bytesize
+              joined << "/"
+            end
+          end
+          joined << name
+        end
+        joined
+      end
+
+      # Returns [String] the directory of the supplied path, as CRuby's `File.dirname` returns it on POSIX, by its bytes:
+      # the path before the separators of its last name, `/` for a path of only separators, or `.` for a single name, in
+      # the encoding of the path.
+      #
+      # Used where `::File.dirname` changes names, see .dirname, and public, so that its tests compare it with CRuby's.
+      def self.dirname_of(path)
+        root   = leading_separators(path)
+        start  = root > 1 ? root - 1 : 0
+        finish = last_separator(path, root) || root
+        return String.new(".", encoding: path.encoding) if finish == start
+
+        path.byteslice(start, finish - start)
+      end
+
+      # Returns [String] the extension of the last name of the supplied path, as CRuby's `File.extname` returns it on
+      # POSIX, by its bytes: from its last `.`, unless only dots start the name, in the encoding of the path, or an
+      # empty String when it has none.
+      #
+      # Used where `::File.extname` changes names, see .extname, and public, so that its tests compare it with CRuby's.
+      def self.extname_of(path)
+        separator = last_separator(path, 0)
+        position  = separator ? separator + 1 : 0
+        position += 1 while position < path.bytesize && path.getbyte(position) == SEPARATOR
+        position += 1 while position < path.bytesize && path.getbyte(position) == DOT
+        dot = nil
+        while position < path.bytesize
+          byte = path.getbyte(position)
+          break if byte == SEPARATOR
+
+          dot = position if byte == DOT
+          position += 1
+        end
+        return "".b if dot.nil?
+
+        path.byteslice(dot, position - dot)
+      end
+
+      # Returns [String] the last name of the supplied path, as CRuby's `File.basename` returns it on POSIX, by its
+      # bytes: the name after its last separators, without the separators at its end, `/` for a path of only
+      # separators, in the encoding of the path. The supplied suffix is removed when the name ends with it, `.*` removes
+      # the extension of the name, see .extname, and a character followed by `*` removes the name from the last of that
+      # character, unless that would leave nothing. A suffix without an encoding in common with the path is not
+      # removed.
+      #
+      # Raises ArgumentError, as CRuby does, when the first character of the suffix, or for a character followed by
+      # `*`, a character of the name, is not valid in the encoding that they have in common.
+      #
+      # Used where `::File.basename` changes names, see .basename, and public, so that its tests compare it with CRuby's.
+      def self.basename_of(path, suffix = nil)
+        return path.dup if path.empty?
+
+        start = leading_separators(path)
+        return path.byteslice(start - 1, 1) if start == path.bytesize
+
+        separator = last_separator(path, start)
+        if separator
+          start = separator
+          start += 1 while path.getbyte(start) == SEPARATOR
+        end
+        length   = trailing_separators(path) - start
+        encoding = suffix && Encoding.compatible?(path, suffix)
+        kept     = encoding ? without_suffix(path, start, length, suffix.dup.force_encoding(encoding)) : 0
+        path.byteslice(start, kept.positive? ? kept : length)
+      end
+
+      # Returns [Integer] the number of bytes of the name of the supplied length, from the supplied position of the
+      # supplied path, that are kept once the supplied suffix is removed, see .basename_of, or 0 when the suffix is not
+      # removed, as CRuby's `rmext` does.
+      def self.without_suffix(path, start, length, suffix)
+        return 0 if suffix.empty?
+
+        first = valid_character(suffix[0])
+        if suffix.bytesize == first.bytesize + 1 && suffix.getbyte(first.bytesize) == "*".ord
+          return stem_length(path, start, length) if first == "."
+
+          name  = valid_character(path.byteslice(start, length).force_encoding(suffix.encoding))
+          index = name.rindex(first)
+          return index ? name[0, index].bytesize : length
+        end
+        return length if length < suffix.bytesize
+
+        from = start + length - suffix.bytesize
+        return 0 unless character_start?(path, from, suffix.encoding)
+
+        path.byteslice(from, suffix.bytesize).b == suffix.b ? length - suffix.bytesize : 0
+      end
+
+      # Returns [String] the supplied text.
+      #
+      # Raises ArgumentError when it is not valid in its encoding, as CRuby does when it reads its characters.
+      def self.valid_character(text)
+        return text if text.valid_encoding?
+
+        raise(ArgumentError, "invalid byte sequence in #{text.encoding}")
+      end
+      private_class_method :valid_character
+      private_class_method :without_suffix
+
+      # Returns [Integer] the number of bytes of the name of the supplied length, from the supplied position of the
+      # supplied path, before its extension, see .extname_of: before its last `.`, unless only dots start the name.
+      def self.stem_length(path, start, length)
+        position = start
+        position += 1 while position - start < length && path.getbyte(position) == DOT
+        dot = nil
+        while position - start < length
+          dot = position if path.getbyte(position) == DOT
+          position += 1
+        end
+        dot ? dot - start : length
+      end
+      private_class_method :stem_length
+
+      # Returns [true|false] whether a character of the supplied path, read in the supplied encoding, starts at the
+      # supplied position: always for a single byte encoding, and for UTF-8 unless its byte continues a character.
+      def self.character_start?(path, position, encoding)
+        return true unless encoding == Encoding::UTF_8
+
+        !(0x80..0xBF).cover?(path.getbyte(position))
+      end
+      private_class_method :character_start?
+
+      # Returns [Integer] the number of bytes of the supplied path before the separators at its end.
+      def self.trailing_separators(path)
+        tail = path.bytesize
+        tail -= 1 while tail.positive? && path.getbyte(tail - 1) == SEPARATOR
+        tail
+      end
+      private_class_method :trailing_separators
+
+      # Returns [Integer] the number of separators at the start of the supplied path.
+      def self.leading_separators(path)
+        count = 0
+        count += 1 while count < path.bytesize && path.getbyte(count) == SEPARATOR
+        count
+      end
+      private_class_method :leading_separators
+
+      # Returns [Integer] the position of the first of the last separators of the supplied path, from the supplied
+      # position on, that a name follows, or nil when it has none, as CRuby's `strrdirsep` finds it.
+      def self.last_separator(path, from)
+        last     = nil
+        position = from
+        while position < path.bytesize
+          if path.getbyte(position) == SEPARATOR
+            separator = position
+            position += 1 while position < path.bytesize && path.getbyte(position) == SEPARATOR
+            break if position >= path.bytesize
+
+            last = separator
+          else
+            position += 1
+          end
+        end
+        last
+      end
+      private_class_method :last_separator
+    end
+
     class URI
-      attr_reader :scheme, :hostname, :path, :user, :password, :port, :query
+      attr_reader :scheme, :hostname, :path, :user, :password, :port, :query, :fragment
 
       def initialize(url)
         url       = url.gsub(" ", "%20")
@@ -76,6 +510,7 @@ module IOStreams
         @user     = uri.user
         @password = uri.password
         @port     = uri.port
+        @fragment = uri.fragment
         return unless uri.query
 
         @query = {}

data/lib/io_streams/version.rb

@@ -1,3 +1,3 @@
 module IOStreams
-  VERSION = "2.1.0".freeze
+  VERSION = "2.2.0".freeze
 end

data/lib/io_streams/writer.rb

@@ -1,5 +1,8 @@
 module IOStreams
   class Writer
+    # Answers the names of the options that this writer takes in IOStreams 3.0, and those that it replaces.
+    extend Deprecation::OptionNames
+
     # Returns [Array<Symbol>] the names of the options this writer accepts,
     # or [nil] when the writer does not declare them.
     #
@@ -9,6 +12,30 @@ module IOStreams
       nil
     end
 
+    # Returns [Array<Symbol>] the names of the options whose values must not be displayed, such as a passphrase,
+    # so that `#inspect` on a path does not display them, see `IOStreams::Extension#redact_options`.
+    def self.sensitive_option_names
+      []
+    end
+
+    # The methods of an IO that write, which every stream that v3.0 supplies to a writer block answers, see
+    # .v3_stream_methods.
+    V3_WRITE_METHODS = %i[write << print puts printf].freeze
+
+    # Returns [Array<Symbol>|nil] the methods that the stream that v3.0 supplies to a writer block, in place of the one
+    # that this writer yields, answers, when it does not answer all of the methods of that one, otherwise nil, for a
+    # writer whose stream answers the same methods in both versions, see `IOStreams::Reader.v3_stream_methods`, whose
+    # parameters and block it takes too.
+    def self.v3_stream_methods(_options)
+      nil
+    end
+
+    # Returns [Hash<Symbol:String>|nil] what the application uses in place of each method of the stream that this writer
+    # yields that v3.0 removes, see `IOStreams::Reader.v3_stream_advice`.
+    def self.v3_stream_advice
+      nil
+    end
+
     # When a Writer does not support streams, we copy the stream to a local temp file
     # and then pass that filename in for this reader.
     def self.stream(output_stream, **args, &block)

data/lib/io_streams/xlsx/cells.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "date"
+
+module IOStreams
+  module Xlsx
+    # The class of the number format of each cell of a worksheet, from Excel's own number formats, and the text of a cell
+    # of a date or a time, as IOStreams 3.0 types them, so that a spreadsheet read with a schema, see
+    # `IOStreams::Xlsx::SchemaReader`, holds the same dates and times in IOStreams 2.2 and 3.0, rather than as creek
+    # classifies them, which takes every custom format with a letter of a date or a time as a date and time, such as
+    # `yyyy-mm-dd`, or `0.00" days"`:
+    #
+    #   Number format            | Text of the cell
+    #   a date                   | its date in ISO 8601, such as `2026-10-25`
+    #   a date and time          | the time of its clock in UTC, such as `2026-10-25T09:30:00Z`, since Excel has no zone
+    #   a time of day            | the time of its clock, such as `09:30:00`
+    module Cells
+      # The seconds of a day.
+      DAY = 86_400
+
+      # The first day of a time of day, as Active Record holds the value of a `time` column.
+      TIME_OF_DAY = [2000, 1, 1].freeze
+
+      # The number of the day after the last date that Excel holds, 9999-12-31, since 1899-12-30.
+      LAST_DAY = 2_958_466
+
+      # The built-in number formats of Excel of dates, times of day, and dates with times, by their ids.
+      BUILT_IN_FORMATS = {
+        14 => :date, 15 => :date, 16 => :date, 17 => :date, 18 => :time, 19 => :time, 20 => :time, 21 => :time,
+        22 => :date_time, 45 => :time, 46 => :time, 47 => :time
+      }.freeze
+
+      # The parts of a custom format code that are not its tokens: quoted text, an escaped character, and a section in
+      # brackets other than an elapsed time, such as a color or a locale. A section never holds another `[`, so a match
+      # stops there, rather than scan the rest of the code again from each `[` of a workbook's code that never closes.
+      LITERALS = /"[^"]*"|\\.|_.|\*.|\[(?![hms]+\])[^\[\]]*\]/i
+
+      # Returns [Array<Symbol|nil>] the class of the number format of each style of a workbook, by the index of the style,
+      # as a cell names it with its `s` attribute: `:date`, `:time` or `:date_time`, or nil for a number, from Excel's own
+      # number formats, see BUILT_IN_FORMATS and .custom_format, rather than as creek finds them.
+      #
+      # Parameters:
+      #   styles: [Nokogiri::XML::Document|nil]
+      #     The styles of the workbook, `xl/styles.xml`, or nil for a workbook without them.
+      def self.number_formats(styles)
+        return [] if styles.nil?
+
+        custom = styles.css("styleSheet numFmts numFmt").to_h do |format|
+          [format["numFmtId"].to_i, custom_format(format["formatCode"].to_s)]
+        end
+        styles.css("styleSheet cellXfs xf").map do |style|
+          id = style["numFmtId"]&.to_i
+          BUILT_IN_FORMATS.fetch(id) { custom[id] } if id
+        end
+      end
+
+      # Returns [Symbol|nil] the class of a custom format code, by the first of its sections: `:date` with only a year,
+      # month or day, `:time` with only hours, minutes or seconds, `:date_time` with both, otherwise nil, for a number.
+      # An `m` is minutes after hours or before seconds, otherwise the month.
+      def self.custom_format(code)
+        tokens = code.split(";").first.to_s.gsub(LITERALS, "")
+        time   = tokens.match?(%r{[hs]|am/pm|a/p}i)
+        date   = tokens.match?(/[yd]/i) || (!time && tokens.match?(/m/i))
+        if date && time then :date_time
+        elsif date then :date
+        elsif time then :time
+        end
+      end
+
+      # Returns [String|nil] the text of a cell of a number type, the text of its `<v>` element, by the class of its
+      # number format, see .number_formats, with the first day of the workbook, see `Creek::Sheet#converter_options`, as
+      # IOStreams 3.0 types it, so that a field of its type reads it:
+      #   a date                   in ISO 8601, such as "2026-10-25"
+      #   a date and time          its time in UTC, such as "2026-10-25T09:30:00Z", with its milliseconds when it has any
+      #   a time                   the time of its clock, such as "09:30:00", or of a number of a day or more, its date
+      #                            and time, as a date and time
+      #
+      # Returns nil for a number of any other format, or one of a date or time format that is not a date that Excel
+      # holds, such as a negative number, which Excel shows as `####`, which is a number.
+      def self.date_text(text, style, base_date)
+        days = days(text) if style
+        return unless days
+
+        case style
+        when :date then (base_date + days.floor).iso8601
+        when :date_time then Schema::Field.any_text(date_time(days, base_date))
+        when :time then days < 1 ? time_of_day_text(time_of_day(days)) : Schema::Field.any_text(date_time(days, base_date))
+        end
+      rescue ArgumentError, ZeroDivisionError
+        nil
+      end
+
+      # Returns [Rational|nil] the days since the first day of the workbook of the text of a number, or nil for one
+      # outside the dates that Excel holds, from its first day up to 9999-12-31, such as a negative number, or one of a
+      # huge exponent, which is checked as a Float before it becomes a Rational, so that its cost is bounded.
+      def self.days(text)
+        days = Float(text)
+        Rational(text) if days >= 0 && days < LAST_DAY
+      end
+
+      # Returns [String] the time of the clock of a time of day, such as "09:30:00", with the milliseconds that Excel
+      # holds when it has any, such as "09:30:00.500", as a `time` field of IOStreams 3.0 writes it.
+      def self.time_of_day_text(time)
+        time.nsec.zero? ? time.strftime("%H:%M:%S") : time.strftime("%H:%M:%S.%3N")
+      end
+
+      # Returns [Time] the time, in UTC, of the clock of the days since the first day of the workbook, to the millisecond
+      # that Excel holds.
+      def self.date_time(days, base_date)
+        date = base_date + days.floor
+        Time.utc(date.year, date.month, date.day) + seconds(days)
+      end
+
+      # Returns [Time] the time of day of the fraction of a day, on 2000-01-01 in UTC, also when the fraction rounds to
+      # a whole day, which is midnight.
+      def self.time_of_day(days)
+        Time.utc(*TIME_OF_DAY) + (seconds(days) % DAY)
+      end
+
+      # Returns [Rational] the seconds of the fraction of the day, to the millisecond.
+      def self.seconds(days)
+        ((days - days.floor) * DAY).round(3)
+      end
+      private_class_method :days, :time_of_day_text, :date_time, :time_of_day, :seconds
+    end
+  end
+end