predicator 1.2.1 → 2.0.0

data/lib/predicator/ast.rb

@@ -1,190 +1,77 @@
-module Predicator
-  module AST
-    class Node
-      include Enumerable
-
-      attr_accessor :left
-
-      def initialize left
-        @left = left
-      end
-
-      def each &block
-        Visitors::Each.new(block).accept self
-      end
-
-      def to_dot
-        Visitors::Dot.new.accept self
-      end
-
-      def to_instructions
-        Visitors::Instructions.new.accept self
-      end
-
-      def to_s
-        Visitors::String.new.accept self
-      end
-
-      def type
-        raise NotImplementedError
-      end
-
-      def variable?; false; end
-      def literal?; false; end
-    end
-
-    class Terminal < Node
-      alias :symbol :left
-    end
-
-    class Literal < Terminal
-      def type; :LITERAL; end
-      def literal?; true; end
-    end
-
-    class Variable < Terminal
-      def type; :VARIABLE; end
-      def variable?; true; end
-    end
-
-    %w[ True False Integer String Date Duration Blank Present ].each do |t|
-      class_eval <<-eoruby, __FILE__, __LINE__ + 1
-        class #{t} < Literal;
-          def type; :#{t.upcase}; end
-        end
-      eoruby
-    end
-
-    class Unary < Node
-      def children; [left] end
-    end
-
-    class IntegerArray < Unary
-      def type; :INTARRAY; end
-    end
-
-    class StringArray < Unary
-      def type; :STRARRAY; end
-    end
-
-    class Not < Unary
-      def type; :NOT; end
-    end
-
-    class Group < Unary
-      def type; :GROUP; end
-    end
-
-    class DateFromNow < Unary
-      def type; :DATEFROMNOW; end
-    end
-
-    class DateAgo < Unary
-      def type; :DATEAGO; end
-    end
-
-    class Binary < Node
-      attr_accessor :right
-
-      def initialize left, right
-        super left
-        @right = right
-      end
-
-      def children; [left, right] end
-    end
-
-    class IntegerEqual < Binary
-      def type; :INTEQ; end
-    end
-
-    class StringEqual < Binary
-      def type; :STREQ; end
-    end
-
-    class DateEqual < Binary
-      def type; :DATEQ; end
-    end
-
-    class IntegerGreaterThan < Binary
-      def type; :INTGT; end
-    end
-
-    class StringGreaterThan < Binary
-      def type; :STRGT; end
-    end
-
-    class DateGreaterThan < Binary
-      def type; :DATGT; end
-    end
-
-    class IntegerLessThan < Binary
-      def type; :INTLT; end
-    end
-
-    class StringLessThan < Binary
-      def type; :STRLT; end
-    end
-
-    class DateLessThan < Binary
-      def type; :DATLT; end
-    end
-
-    class IntegerIn < Binary
-      def type; :INTIN; end
-    end
-
-    class StringIn < Binary
-      def type; :STRIN; end
-    end
-
-    class IntegerNotIn < Binary
-      def type; :INTNOTIN; end
-    end
-
-    class StringNotIn < Binary
-      def type; :STRNOTIN; end
-    end
-
-    class StringStartsWith < Binary
-      def type; :STRSTARTSWITH; end
-    end
-
-    class StringEndsWith < Binary
-      def type; :STRENDSWITH; end
-    end
-
-    class And < Binary
-      def type; :AND; end
-    end
-
-    class Or < Binary
-      def type; :OR; end
-    end
-
-    class Ternary < Node
-      attr_accessor :middle, :right
-
-      def initialize left, middle, right
-        super left
-        @middle = middle
-        @right = right
-      end
-
-      def children; [left, middle, right] end
-    end
-
-    class IntegerBetween < Ternary
-      def type; :INTBETWEEN; end
-    end
-
-    class DateBetween < Ternary
-      def type; :DATBETWEEN; end
-    end
-
-    class BooleanVariable < Unary
-      def type; :BOOL; end
-    end
+# frozen_string_literal: true
 
+module Predicator
+  # The syntax tree the parser builds: the reference's node kinds, with the
+  # reference's fields, as immutable values.
+  #
+  # Every node carries both of the reference's two kinds of source metadata,
+  # where the reference's parser carries one or the other per parse. The
+  # position is the {Predicator::Position} of the token that defines the
+  # node, which is not always its leftmost token: an operator node points at
+  # its operator, an access node at the property or the key rather than the
+  # punctuation before it, a cast at its type name, a relative date written
+  # after its duration at the word `ago` or `from`. The span is the source
+  # the node covers, a {Lexer::Span} with an exclusive end. A parenthesized
+  # expression keeps its node's position and widens its span to the
+  # parentheses.
+  #
+  # The kinds and their fields follow the reference's syntax tree:
+  #
+  # - {Literal}: a number, a boolean, null, undefined, a date or a datetime;
+  #   its value is the predicator value ({Predicator::UNDEFINED}, nil, an
+  #   Integer, a Float, a {Predicator::Date}, a {Predicator::DateTime}). A
+  #   negative number is a {Unary} minus over a literal, never a negative
+  #   literal.
+  # - {StringLiteral}: a string and the quote it was written with
+  #   (`:double` or `:single`).
+  # - {Identifier}, {Comparison}, {Arithmetic}, {Membership}, {Unary},
+  #   {LogicalAnd}, {LogicalOr}, {LogicalNot}, {ListLiteral},
+  #   {ObjectLiteral} (whose entries are `[ObjectKey, node]` pairs),
+  #   {FunctionCall}, {BracketAccess}, {PropertyAccess}, {Cast},
+  #   {Duration} (whose units are `[amount, suffix]` pairs in the order
+  #   written, a fraction already expanded into whole units) and
+  #   {RelativeDate}.
+  # - The statement kinds a program holds: {Assignment}, {If} (an `else if`
+  #   is an else {Block} holding one {If}, which borrows that `if`'s
+  #   position and span), {While}, {Block} and {Program}. Any expression
+  #   node also stands as a statement.
+  #
+  # The operators are the reference's: comparison `:gt`, `:lt`, `:gte`,
+  # `:lte`, `:equal_equal`, `:ne`, `:strict_eq`, `:strict_ne`; arithmetic
+  # `:add`, `:subtract`, `:multiply`, `:divide`, `:modulo`; membership
+  # `:in`, `:contains`; unary `:minus`, `:bang`; relative-date directions
+  # `:ago`, `:future` (written `from now`), `:next`, `:last`.
+  #
+  # The module is private to the package.
+  module Ast
+    # A node class with the fields given, then a position and a span.
+    def self.node(*fields) = Data.define(*fields, :position, :span)
+    private_class_method :node
+
+    Literal = node(:value)
+    StringLiteral = node(:value, :quote)
+    Identifier = node(:name)
+    Comparison = node(:operator, :left, :right)
+    Arithmetic = node(:operator, :left, :right)
+    Membership = node(:operator, :left, :right)
+    Unary = node(:operator, :operand)
+    LogicalAnd = node(:left, :right)
+    LogicalOr = node(:left, :right)
+    LogicalNot = node(:operand)
+    ListLiteral = node(:elements)
+    ObjectLiteral = node(:entries)
+    ObjectKey = node(:name, :style)
+    FunctionCall = node(:name, :arguments)
+    BracketAccess = node(:object, :key)
+    PropertyAccess = node(:object, :property)
+    Cast = node(:expression, :type_name)
+    Duration = node(:units)
+    RelativeDate = node(:duration, :direction)
+    Assignment = node(:target, :value)
+    Block = node(:statements)
+    If = node(:condition, :then_block, :else_block)
+    While = node(:condition, :body)
+    Program = node(:statements)
   end
+  private_constant :Ast
 end

data/lib/predicator/boundary.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require_relative "values"
+require_relative "errors"
+
+module Predicator
+  # The value boundary: where a value a host hands in (a context, a literal
+  # operand of an instruction list it built, the answer of one of its
+  # functions) is checked against the value domain before an evaluation
+  # holds it, and where an argument handed to a host function is copied.
+  #
+  # The domain is nil, true and false, an Integer, a finite Float, a String
+  # in UTF-8 (or US-ASCII) that is valid in its encoding, an Array of
+  # values, a Hash of keys to values, {Predicator::UNDEFINED}, a
+  # {Predicator::Date}, a {Predicator::DateTime} and a {Predicator::Duration}.
+  # A map key is a String, an Integer, true, false, nil or
+  # {Predicator::UNDEFINED}, the keys a bracket access reads; a key of the
+  # context itself, the name a load reads, is a String.
+  # A value outside it is refused with an {EvaluationError}, never raised,
+  # under one of these reasons:
+  #
+  # - "unsupported_host_value": a value the domain has no member for (a
+  #   Symbol, a Time, any other object), a map key outside the keys above,
+  #   or a String that is not valid UTF-8 text;
+  # - "non_finite_number": a Float that is not finite;
+  # - "cyclic_value": a list or a map that contains itself;
+  # - "depth_limit_exceeded": lists and maps nested past {DEPTH_LIMIT}
+  #   levels along any path, the outermost counting as the first, a list or
+  #   map shared by several paths measured along each.
+  #
+  # The walks are iterative, so a value deeper than the stack is refused
+  # rather than exhausting it, and each list or map is walked once however
+  # many paths reach it. The module holds no state. It is private to the
+  # package.
+  module Boundary
+    # How deep lists and maps may nest in a value that crosses the boundary:
+    # 100 levels, the bound the tagged codec holds a text to.
+    DEPTH_LIMIT = 100
+
+    # The String encodings a String in the domain may carry.
+    TEXT_ENCODINGS = [Encoding::UTF_8, Encoding::US_ASCII].freeze
+
+    # The keys a map may have besides a String and an Integer.
+    MAP_KEY_ATOMS = [true, false, nil, UNDEFINED].freeze
+
+    module_function
+
+    # The refusal of what an evaluation is handed, or nil when all of it is
+    # in the domain: the context's keys, then its values, then every `lit`
+    # operand of the instruction list, in order.
+    #
+    # @param instructions [Array] the instruction list
+    # @param context [Hash] the context
+    # @return [EvaluationError, nil]
+    def input_refusal(instructions, context)
+      root_refusal(context) || refusal(context, "the context") ||
+        instructions.each_with_index.lazy.filter_map do |instruction, at|
+          next unless instruction.is_a?(Array) && instruction.first == "lit" && instruction.size == 2
+
+          refusal(instruction.last, "the literal at index #{at}")
+        end.first
+    end
+
+    # The refusal of a context key that is not a String, or nil.
+    def root_refusal(context)
+      key = context.each_key.find { |name| !name.is_a?(String) }
+      return unless key || context.key?(key)
+
+      EvaluationError.new(reason: "unsupported_host_value",
+                          message: "the context has the key #{key.inspect}, which is not a String")
+    end
+
+    # The refusal of a value, or nil when it is in the domain.
+    #
+    # @param value [Object]
+    # @param subject [String] what the value is, for the message
+    # @return [EvaluationError, nil]
+    def refusal(value, subject)
+      reason, detail = fault(value)
+      EvaluationError.new(reason:, message: "#{subject} #{detail}") if reason
+    end
+
+    # The first fault of a value, as a reason and a phrase, or nil.
+    def fault(value) = Check.new.fault(value)
+
+    # The fault of a value that is not a list or a map, or nil.
+    def leaf_fault(value)
+      case value
+      when nil, true, false, Integer, Predicator::Date, Predicator::DateTime, Duration, Array, Hash then nil
+      when Float then ["non_finite_number", "holds the float #{value}, which is not finite"] unless value.finite?
+      when String then text_fault(value)
+      else ["unsupported_host_value", "holds #{value.inspect}, which is not a predicator value"] \
+        unless UNDEFINED.equal?(value)
+      end
+    end
+
+    def text_fault(text)
+      return if TEXT_ENCODINGS.include?(text.encoding) && text.valid_encoding?
+
+      ["unsupported_host_value", "holds a String that is not valid UTF-8 text"]
+    end
+
+    # The fault of a map's first key outside the keys a map may have, or
+    # nil.
+    def key_fault(map)
+      map.each_key do |key|
+        next if key.is_a?(Integer) || MAP_KEY_ATOMS.any? { |atom| atom.equal?(key) }
+        return ["unsupported_host_value", "has the key #{key.inspect}, which is not a map key"] unless key.is_a?(String)
+
+        found = text_fault(key)
+        return found if found
+      end
+      nil
+    end
+
+    def container?(value) = value.is_a?(Array) || value.is_a?(Hash)
+    def members(container) = container.is_a?(Hash) ? container.values : container
+
+    # A copy of a value in the domain that shares no list, map or String
+    # with it, so that whatever is done to the copy leaves the value as it
+    # was. Every other member of the domain is immutable and is shared. A
+    # list or a map reached by two paths is copied once, and the walk is
+    # iterative.
+    #
+    # @param value [Object] a value in the domain, with no cycle
+    # @return [Object] the copy
+    def copy(value) = container?(value) ? Copy.new.copy(value) : copy_text(value)
+
+    def copy_text(value) = value.is_a?(String) ? value.dup : value
+
+    # One check of one value: a depth-first walk over an explicit stack. A
+    # list or a map is :open, on the path, from when its members are queued
+    # until the marker queued beneath them is reached; meeting an open one
+    # again is a cycle. From then on it holds its height, the levels it
+    # nests including itself, and is not walked again: a path that reaches
+    # it at a depth where depth plus height passes the limit by one is
+    # refused, so the limit holds along every path however much of the value
+    # is shared.
+    class Check
+      def initialize
+        @state = {}.compare_by_identity
+        @work = []
+      end
+
+      def fault(root)
+        @work.push([root, 1])
+        until @work.empty?
+          value, depth = @work.pop
+          next leave(value) if depth == :leave
+
+          found = Boundary.leaf_fault(value) || container_fault(value, depth)
+          return found if found
+        end
+        nil
+      end
+
+      private
+
+      # Marks a container walked, with its height: one more than its
+      # tallest member's, a member that is not a list or a map counting 0.
+      def leave(container)
+        tallest = Boundary.members(container).map { |member| Boundary.container?(member) ? @state[member] : 0 }.max
+        @state[container] = 1 + (tallest || 0)
+      end
+
+      # The fault of a list or a map, or nil having queued its members; nil
+      # for any other value and for one already walked whose height fits.
+      def container_fault(value, depth)
+        return unless Boundary.container?(value)
+
+        state = @state[value]
+        return state_fault(state, depth) if state
+
+        return too_deep if depth > DEPTH_LIMIT
+
+        (value.is_a?(Hash) && Boundary.key_fault(value)) || enter(value, depth)
+      end
+
+      # The fault of meeting a container again: a cycle while it is open,
+      # too deep when its height from this depth passes the limit.
+      def state_fault(state, depth)
+        return ["cyclic_value", "holds a list or a map that contains itself"] if state == :open
+
+        too_deep if depth + state - 1 > DEPTH_LIMIT
+      end
+
+      def too_deep = ["depth_limit_exceeded", "nests past #{DEPTH_LIMIT} levels"]
+
+      def enter(container, depth)
+        @state[container] = :open
+        @work.push([container, :leave])
+        Boundary.members(container).each { |member| @work.push([member, depth + 1]) }
+        nil
+      end
+    end
+    private_constant :Check
+
+    # One copy of one list or map: a depth-first walk over an explicit
+    # stack that builds each container after its members.
+    class Copy
+      def initialize
+        @copies = {}.compare_by_identity
+        @work = []
+      end
+
+      def copy(root)
+        @work.push([root, false])
+        until @work.empty?
+          held, members_built = @work.pop
+          next @copies[held] = build(held) if members_built
+
+          enter(held) unless @copies.key?(held)
+        end
+        @copies[root]
+      end
+
+      private
+
+      def enter(container)
+        @copies[container] = nil
+        @work.push([container, true])
+        Boundary.members(container).each { |member| @work.push([member, false]) if Boundary.container?(member) }
+      end
+
+      # The copy of one list or map, its members' copies already built.
+      def build(container)
+        return container.map { |member| take(member) } if container.is_a?(Array)
+
+        container.to_h { |key, member| [key.dup, take(member)] }
+      end
+
+      def take(member) = @copies.key?(member) ? @copies[member] : Boundary.copy_text(member)
+    end
+    private_constant :Copy
+  end
+  private_constant :Boundary
+end

data/lib/predicator/civil.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Predicator
+  # Calendar arithmetic on the proleptic Gregorian calendar, written by hand so
+  # that the package needs no date library: a civil date (year, month, day) to
+  # a count of days since 1970-01-01 and back, and the tests built on them.
+  #
+  # Every function but the four that convert a {Predicator::Date} or a
+  # {Predicator::DateTime} takes and answers Integers. The algorithms are the era-based ones published by
+  # Howard Hinnant ("chrono-Compatible Low-Level Date Algorithms"), exact for
+  # every Integer year, so a year before 1 or after 9999 converts as well as
+  # any other.
+  #
+  # The module holds no state. It is private to the package: the value classes
+  # in values.rb, the evaluator and the codec in tagged.rb are its callers.
+  module Civil
+    # Seconds in a civil day; an instant's day is its epoch second divided by
+    # this, rounded toward the past.
+    SECONDS_PER_DAY = 86_400
+
+    # The days in each month of a year that is not a leap year.
+    MONTH_LENGTHS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31].freeze
+
+    module_function
+
+    # The count of days from 1970-01-01 to the civil date year-month-day,
+    # negative before it. month and day are taken as given; a caller wanting
+    # to know they name a date asks civil?.
+    def days_from_civil(year, month, day)
+      shifted = month <= 2 ? year - 1 : year
+      era = shifted.div(400)
+      (era * 146_097) + day_of_era(shifted - (era * 400), day_of_year(month, day)) - 719_468
+    end
+
+    # The civil date days after 1970-01-01, as [year, month, day].
+    def civil_from_days(days)
+      shifted = days + 719_468
+      era = shifted.div(146_097)
+      era_day = shifted - (era * 146_097)
+      era_year = year_of_era(era_day)
+      month, day = month_and_day(era_day - day_of_era(era_year, 0))
+      [era_year + (era * 400) + (month <= 2 ? 1 : 0), month, day]
+    end
+
+    # The day of a year that starts on March 1st.
+    def day_of_year(month, day) = (((153 * (month + (month > 2 ? -3 : 9))) + 2) / 5) + day - 1
+
+    # The day of a 400-year era, from the year of the era and the day of
+    # that (March-based) year.
+    def day_of_era(year_of_era, day_of_year)
+      (year_of_era * 365) + (year_of_era / 4) - (year_of_era / 100) + day_of_year
+    end
+
+    # The year of a 400-year era a day of the era falls in.
+    def year_of_era(day_of_era)
+      (day_of_era - (day_of_era / 1460) + (day_of_era / 36_524) - (day_of_era / 146_096)) / 365
+    end
+
+    # The civil month and day of a day of a March-based year.
+    def month_and_day(day_of_year)
+      month_from_march = ((5 * day_of_year) + 2) / 153
+      day = day_of_year - (((153 * month_from_march) + 2) / 5) + 1
+      [month_from_march + (month_from_march < 10 ? 3 : -9), day]
+    end
+
+    # Whether part is an Integer from 0 to top.
+    def within?(part, top) = part.is_a?(Integer) && part.between?(0, top)
+
+    # Whether year, month and day are Integers naming a date on the calendar:
+    # a month from 1 to 12 and a day that month has in that year. It reads
+    # the month lengths and the leap-year rule, not the day count, so the two
+    # conversions above are checked against it rather than by it.
+    def civil?(year, month, day)
+      return false unless [year, month, day].all?(Integer) && month.between?(1, 12)
+
+      day.between?(1, days_in_month(year, month))
+    end
+
+    # The {Predicator::Date} days after 1970-01-01.
+    def date_of_days(days) = Predicator::Date.new(*civil_from_days(days))
+
+    # The count of days from 1970-01-01 to a {Predicator::Date}, negative
+    # before it.
+    def days_of(date) = days_from_civil(date.year, date.month, date.day)
+
+    # The {Predicator::DateTime} at a {Predicator::Date} and a time of day,
+    # in UTC.
+    def instant_at(date, hour = 0, minute = 0, second = 0, microsecond: 0)
+      clock = [hour, minute, second]
+      unless date.is_a?(Predicator::Date) && clock.zip([23, 59, 59]).all? { |part, top| within?(part, top) }
+        raise ArgumentError, "#{date.inspect} at #{clock.inspect} does not name a time of day on a date"
+      end
+
+      seconds = (days_of(date) * SECONDS_PER_DAY) + (hour * 3600) + (minute * 60) + second
+      Predicator::DateTime.new(epoch_seconds: seconds, microsecond:)
+    end
+
+    # The civil {Predicator::Date} of a {Predicator::DateTime}, in UTC.
+    def date_of(instant) = date_of_days(instant.epoch_seconds.div(SECONDS_PER_DAY))
+
+    # The days in a month of a year.
+    def days_in_month(year, month)
+      return 29 if month == 2 && leap?(year)
+
+      MONTH_LENGTHS[month - 1]
+    end
+
+    # Whether a year is a leap year on the proleptic Gregorian calendar.
+    def leap?(year) = (year % 4).zero? && (!(year % 100).zero? || (year % 400).zero?)
+  end
+  private_constant :Civil
+end

data/lib/predicator/duration_text.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Predicator
+  # A duration as text in the language's duration-literal grammar, both
+  # ways, as the reference writes and reads it.
+  #
+  # Written, the units come largest first, each as its amount and its
+  # suffix (`y`, `mo`, `w`, `d`, `h`, `m`, `s`, `ms`); a unit that is not
+  # positive is left out, and a duration with nothing left to write is
+  # `0s`.
+  #
+  # Read, the whole text is one or more components, each digits, an
+  # optional fraction (a point and digits) and a suffix, with no sign, no
+  # space and no empty text; `mo` and `ms` are read before `m`. A repeated
+  # unit adds to what came before. A fraction is exact or refused: it is
+  # worth a whole number of milliseconds (a month 30 days, a year 365) or
+  # the text is not a duration, and that remainder is spent largest first
+  # through days, hours, minutes, seconds and milliseconds only, the whole
+  # part keeping its own unit.
+  #
+  # The module holds no state. It is private to the package.
+  module DurationText
+    # Each unit's suffix and its worth in milliseconds, largest unit first.
+    UNITS = {
+      years: ["y", 31_536_000_000], months: ["mo", 2_592_000_000], weeks: ["w", 604_800_000],
+      days: ["d", 86_400_000], hours: ["h", 3_600_000], minutes: ["m", 60_000], seconds: ["s", 1000],
+      milliseconds: ["ms", 1]
+    }.freeze
+
+    # The unit each suffix names.
+    SUFFIXES = UNITS.to_h { |unit, (suffix, _)| [suffix, unit] }.freeze
+
+    # The units a fraction's remainder is spent into.
+    REMAINDER_UNITS = %i[days hours minutes seconds milliseconds].freeze
+
+    # One component, and the whole text as a run of them.
+    COMPONENT = /([0-9]+)(?:\.([0-9]+))?(mo|ms|y|w|d|h|m|s)/
+    TEXT = /\A(?:[0-9]+(?:\.[0-9]+)?(?:mo|ms|y|w|d|h|m|s))+\z/
+
+    module_function
+
+    # @param duration [Duration]
+    # @return [String]
+    def write(duration)
+      parts = UNITS.filter_map do |unit, (suffix, _)|
+        amount = duration.public_send(unit)
+        "#{amount}#{suffix}" if amount.positive?
+      end
+      parts.empty? ? "0s" : parts.join
+    end
+
+    # @param text [String]
+    # @return [Duration, nil] the duration the text names, or nil when it
+    #   names none
+    def read(text)
+      return unless TEXT.match?(text)
+
+      pairs = text.scan(COMPONENT).map { |whole, fraction, suffix| component(whole, fraction, suffix) }
+      return if pairs.include?(nil)
+
+      units = Hash.new(0)
+      pairs.flatten(1).each { |unit, amount| units[unit] += amount }
+      Duration.new(**units)
+    end
+
+    # The unit pairs one component is worth, or nil when its fraction is not
+    # a whole number of milliseconds.
+    def component(whole, fraction, suffix)
+      whole = Integer(whole, 10)
+      unit = SUFFIXES.fetch(suffix)
+      fraction ? expand(whole, fraction, unit) : [[unit, whole]]
+    end
+
+    # The unit pairs a component with a fraction is worth, or nil when the
+    # fraction is not a whole number of milliseconds.
+    def expand(whole, fraction, unit)
+      worth = Integer(fraction, 10) * UNITS.fetch(unit).last
+      remainder, inexact = worth.divmod(10**fraction.size)
+      return unless inexact.zero?
+
+      [[unit, whole], *spend(remainder)]
+    end
+
+    def spend(milliseconds)
+      REMAINDER_UNITS.filter_map do |unit|
+        amount, milliseconds = milliseconds.divmod(UNITS.fetch(unit).last)
+        [unit, amount] if amount.positive?
+      end
+    end
+  end
+  private_constant :DurationText
+end