dotiw 5.3.3 → 5.6.0

data/lib/dotiw/methods.rb

@@ -44,6 +44,31 @@ module DOTIW
 
     private
 
+    # How many of each measure is necessary to round up to one of the next-largest measure. Note
+    # that for simplicity of implementation, we only check one measure when seeing if we should
+    # round up. This means that rounding up days to weeks, for instance, cannot draw the line at 3
+    # days and 12 hours, but instead either 3 or 4 (whole) days. Let's not even talk about weeks
+    # rounding up to months.
+    ROUNDING_THRESHOLDS = {
+      seconds: 30,
+      minutes: 30,
+      hours: 12,
+      days: 4,
+      weeks: 2,
+      months: 6,
+      years: Float::INFINITY,
+    }
+
+    ROLLUP_THRESHOLDS = {
+      seconds: 60,
+      minutes: 60,
+      hours: 24,
+      days: 7,
+      weeks: 4, # !!!
+      months: 12,
+      years: Float::INFINITY,
+    }
+
     def normalize_distance_of_time_argument_to_time(value)
       if value.is_a?(Numeric)
         Time.at(value)
@@ -63,47 +88,72 @@ module DOTIW
     end
 
     def _display_time_in_words(hash, options = {})
+      hash = hash.dup
+
       options = options.reverse_merge(
         include_seconds: false
       ).symbolize_keys!
 
+      discarded_hash = {}
+
       include_seconds = options.delete(:include_seconds)
-      hash.delete(:seconds) if !include_seconds && hash[:minutes]
+      discarded_hash[:seconds] = hash.delete(:seconds) if !include_seconds && hash[:minutes]
 
       options[:except] = Array.wrap(options[:except]).map!(&:to_sym) if options[:except]
       options[:only] = Array.wrap(options[:only]).map!(&:to_sym) if options[:only]
 
-      # Remove all the values that are nil or excluded. Keep the required ones.
-      hash.delete_if do |key, value|
-        value.nil? || value.zero? ||
-          options[:except]&.include?(key) ||
-          (options[:only] && !options[:only].include?(key))
+      if options[:except] || options[:only]
+        # Fold excluded fractions into the next smaller fraction instead of discarding their
+        # duration outright, e.g. weeks excluded via only: [:years, :months, :days] are converted
+        # to days and added to the days count, rather than losing those weeks entirely. Larger
+        # fractions are processed first so that a run of consecutive excluded fractions cascades
+        # down to the largest fraction that's still included (or is dropped if none remain).
+        DOTIW::TimeHash::TIME_FRACTIONS.reverse_each do |fraction|
+          next unless hash.key?(fraction)
+          next unless options[:except]&.include?(fraction) || (options[:only] && !options[:only].include?(fraction))
+
+          value = hash.delete(fraction)
+          discarded_hash[fraction] = value
+
+          next_fraction = _next_smaller_fraction(fraction)
+          next unless next_fraction
+
+          hash[next_fraction] = hash.fetch(next_fraction, 0) + (value * ROLLUP_THRESHOLDS[next_fraction])
+        end
       end
 
+      hash.delete_if { |key, value| value.nil? || value.zero? }
+      discarded_hash.delete_if { |key, value| value.nil? || value.zero? }
+
       i18n_scope = options.delete(:scope) || DOTIW::DEFAULT_I18N_SCOPE
       if hash.empty?
         fractions = DOTIW::TimeHash::TIME_FRACTIONS
         fractions &= options[:only] if options[:only]
         fractions -= options[:except] if options[:except]
 
-        I18n.with_options locale: options[:locale], scope: i18n_scope do |locale|
-          # e.g. try to format 'less than 1 days', fallback to '0 days'
-          return locale.translate :less_than_x,
-                                  distance: locale.translate(fractions.first, count: 1),
-                                  default: locale.translate(fractions.first, count: 0)
-        end
-      end
-
-      output = []
-      I18n.with_options locale: options[:locale], scope: i18n_scope do |locale|
-        output = hash.map { |key, value| locale.t(key, count: value) }
+        locale = options[:locale]
+        # e.g. try to format 'less than 1 days', fallback to '0 days'
+        return I18n.translate :less_than_x,
+                              locale: locale,
+                              scope: i18n_scope,
+                              distance: I18n.translate(fractions.first, locale: locale, scope: i18n_scope, count: 1),
+                              default: I18n.translate(fractions.first, locale: locale, scope: i18n_scope, count: 0)
       end
 
       options.delete(:except)
       options.delete(:only)
-      highest_measures = options.delete(:highest_measures)
-      highest_measures = 1 if options.delete(:highest_measure_only)
-      output = output[0...highest_measures] if highest_measures
+
+      highest_measures = _compute_highest_measures! options
+      if highest_measures
+        high_entries, low_entries = hash.to_a.partition.with_index { |_, index| index < highest_measures[:max] }
+        hash = high_entries.to_h
+        discarded_hash.merge! low_entries.to_h
+
+        _maybe_round! hash, discarded_hash, highest_measures[:remainder]
+      end
+
+      locale = options[:locale]
+      phrases = hash.map { |key, value| I18n.translate(key, locale: locale, scope: i18n_scope, count: value) }
 
       options[:words_connector] ||= I18n.translate :"#{i18n_scope}.words_connector",
                                                    default: :'support.array.words_connector',
@@ -115,7 +165,63 @@ module DOTIW
                                                        default: :'support.array.last_word_connector',
                                                        locale: options[:locale]
 
-      output.to_sentence(options.except(:accumulate_on, :compact))
+      phrases.to_sentence(options.except(:accumulate_on, :max_unit, :compact))
+    end
+
+    def _compute_highest_measures!(options)
+      highest_measures = options.delete(:highest_measures)
+      highest_measures = 1 if options.delete(:highest_measure_only)
+      highest_measures = { max: highest_measures } if highest_measures.is_a?(Integer)
+      highest_measures = highest_measures.reverse_merge(max: 1, remainder: :floor) if highest_measures
+
+      highest_measures
+    end
+
+    def _maybe_round!(hash, discarded_hash, remainder)
+      smallest_measure_index = DOTIW::TimeHash::TIME_FRACTIONS.index hash.to_a.last[0]
+      smallest_measure = DOTIW::TimeHash::TIME_FRACTIONS[smallest_measure_index]
+
+      case remainder
+      when :floor
+        # Nothing to do.
+      when :ceiling
+        # We already filtered out zeroes, so non-empty also means non-zero.
+        if !discarded_hash.empty?
+          hash[smallest_measure] += 1
+          _rollup! hash, smallest_measure_index
+        end
+      when :round
+        # If our smallest measure is already the smallest possible measure, there is no next
+        # smallest measure to inspect to see if we need to round up.
+        return if smallest_measure_index == 0
+
+        next_smallest_measure = DOTIW::TimeHash::TIME_FRACTIONS[smallest_measure_index - 1]
+        if discarded_hash.fetch(next_smallest_measure, 0) >= ROUNDING_THRESHOLDS[next_smallest_measure]
+          hash[smallest_measure] += 1
+          _rollup! hash, smallest_measure_index
+        end
+      else
+        raise ArgumentError, "unrecognized remainder value #{remainder.inspect}"
+      end
+    end
+
+    def _next_smaller_fraction(fraction)
+      index = DOTIW::TimeHash::TIME_FRACTIONS.index(fraction)
+      return nil if index.nil? || index.zero?
+
+      DOTIW::TimeHash::TIME_FRACTIONS[index - 1]
+    end
+
+    def _rollup!(hash, smallest_measure_index)
+      DOTIW::TimeHash::TIME_FRACTIONS[smallest_measure_index..-1].each_with_index do |fraction, index|
+        if hash.fetch(fraction, 0) >= ROLLUP_THRESHOLDS[fraction]
+          hash.delete fraction
+          next_fraction = DOTIW::TimeHash::TIME_FRACTIONS[smallest_measure_index + index + 1]
+          hash[next_fraction] = hash.fetch(next_fraction, 0) + 1
+        else
+          break
+        end
+      end
     end
   end
 end

data/lib/dotiw/time_hash.rb

@@ -13,15 +13,9 @@ module DOTIW
       @from_time  = from_time || Time.current
       @to_time    = to_time   || (@to_time_not_given = true && @from_time + distance.seconds)
       @smallest, @largest = [@from_time, @to_time].minmax
-      @to_time   += 1.hour if @to_time_not_given && smallest.dst? && !largest.dst?
-      @to_time   -= 1.hour if @to_time_not_given && !smallest.dst? && largest.dst?
+      @to_time += offset_delta(smallest, largest) if @to_time_not_given
       @smallest, @largest = [@from_time, @to_time].minmax
-      @distance ||= begin
-        d = largest - smallest
-        d -= 1.hour if smallest.dst? && !largest.dst?
-        d += 1.hour if !smallest.dst? && largest.dst?
-        d
-      end
+      @distance ||= (largest - smallest) + offset_delta(smallest, largest)
 
       build_time_hash
     end
@@ -40,11 +34,23 @@ module DOTIW
     ONE_WEEK = 7.days.freeze
     FOUR_WEEKS = 28.days.freeze
 
+    # The distance between two Time objects computed via subtraction already
+    # reflects any change in UTC offset between them (whether from a DST
+    # transition or a permanent tzdata rule change, e.g. Pacific/Norfolk's
+    # 2015 UTC offset change), which is what we want when reporting a raw
+    # elapsed duration. However, when we split that distance into calendar
+    # fields (years/months/weeks/days), we want the offset difference
+    # folded away so the leftover hours/minutes/seconds reflect only actual
+    # elapsed wall-clock time, not artifacts of an offset shift.
+    def offset_delta(smallest, largest)
+      largest.utc_offset - smallest.utc_offset
+    end
+
     def build_time_hash
-      if accumulate_on = options[:accumulate_on]
+      if (max_unit = options[:max_unit])
+        build_max_unit(max_unit.to_sym)
+      elsif accumulate_on = options[:accumulate_on]
         accumulate_on = accumulate_on.to_sym
-        return build_time_hash if accumulate_on == :years
-
         TIME_FRACTIONS.index(accumulate_on).downto(0) { |i| send("build_#{TIME_FRACTIONS[i]}") }
       else
         while distance > 0
@@ -88,14 +94,56 @@ module DOTIW
       output[:weeks], @distance = distance.divmod(ONE_WEEK.to_i) unless output[:weeks]
     end
 
+    # Expresses the entire distance as a single number in the given unit, discarding
+    # (flooring) any remainder smaller than that unit, unlike +accumulate_on+ which keeps
+    # showing the smaller units below the target.
+    def build_max_unit(unit)
+      case unit
+      when :seconds
+        output[:seconds] = distance.to_i
+      when :minutes
+        output[:minutes] = (distance / ONE_MINUTE).floor
+      when :hours
+        output[:hours] = (distance / ONE_HOUR).floor
+      when :days
+        output[:days] = (distance / ONE_DAY).floor
+      when :weeks
+        output[:weeks] = (distance / ONE_WEEK).floor
+      when :months
+        output[:months] = whole_months_between(smallest, largest)
+      when :years
+        output[:years] = whole_years_between(smallest, largest)
+      else
+        raise ArgumentError, "unrecognized max_unit #{unit.inspect}"
+      end
+
+      @distance = 0
+    end
+
+    def whole_months_between(from, to)
+      months = (to.year - from.year) * 12 + (to.month - from.month)
+      months -= 1 if to.advance(months: -months) < from
+      months
+    end
+
+    def whole_years_between(from, to)
+      years = to.year - from.year
+      years -= 1 if to.advance(years: -years) < from
+      years
+    end
+
     def build_months
       build_years_months_weeks_days
 
-      if (years = output.delete(:years)) > 0
+      if options[:accumulate_on]&.to_sym == :months && (years = output.delete(:years)) > 0
         output[:months] += (years * 12)
       end
     end
 
+    def build_years
+      build_years_months_weeks_days
+    end
+
     def build_years_months_weeks_days
       months = (largest.year - smallest.year) * 12 + (largest.month - smallest.month)
       years, months = months.divmod(12)

data/lib/dotiw/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DOTIW
-  VERSION = '5.3.3'
+  VERSION = '5.6.0'
 end

data/lib/dotiw.rb

@@ -1,45 +1,6 @@
 # frozen_string_literal: true
 
-require 'i18n'
-
-require 'active_support'
-require 'active_support/core_ext'
-
-module DOTIW
-  extend ActiveSupport::Autoload
-
-  eager_autoload do
-    autoload :VERSION, 'dotiw/version'
-    autoload :TimeHash, 'dotiw/time_hash'
-    autoload :Methods, 'dotiw/methods'
-  end
-
-  extend self
-
-  DEFAULT_I18N_SCOPE = :'datetime.dotiw'
-  DEFAULT_I18N_SCOPE_COMPACT = :'datetime.dotiw_compact'
-
-  def init_i18n!
-    I18n.load_path.unshift(*locale_files)
-    I18n.reload!
-  end
-
-  def languages
-    @languages ||= (locale_files.map { |path| path.split(%r{[/.]})[-2].to_sym })
-  end
-
-  def locale_files
-    files 'dotiw/locale', '*.yml'
-  end
-
-  protected
-
-  def files(directory, ext)
-    Dir[File.join File.dirname(__FILE__), directory, ext]
-  end
-end
-
-DOTIW.init_i18n!
+require_relative 'dotiw/core'
 
 begin
   require 'action_view'

data/spec/lib/dotiw_module_spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe DOTIW do
+  START_TIME_MODULE = '01-08-2009'.to_time(:utc)
+
+  before do
+    I18n.locale = :en
+  end
+
+  describe '.distance_of_time_in_words' do
+    it 'returns the exact distance' do
+      expect(
+        described_class.distance_of_time_in_words(START_TIME_MODULE, START_TIME_MODULE + 1.hour + 30.minutes)
+      ).to eq('1 hour and 30 minutes')
+    end
+
+    it 'accepts options' do
+      expect(
+        described_class.distance_of_time_in_words(
+          START_TIME_MODULE, START_TIME_MODULE + 1.hour + 30.minutes, highest_measures: 1
+        )
+      ).to eq('1 hour')
+    end
+  end
+
+  describe '.time_ago_in_words' do
+    it 'returns the distance to now' do
+      allow(Time).to receive(:now).and_return(START_TIME_MODULE)
+      allow(Time.zone).to receive(:now).and_return(START_TIME_MODULE)
+
+      expect(
+        described_class.time_ago_in_words(START_TIME_MODULE - 90, include_seconds: true)
+      ).to eq('1 minute and 30 seconds')
+    end
+  end
+
+  describe '.distance_of_time' do
+    it 'returns the distance for a number of seconds' do
+      expect(described_class.distance_of_time(90)).to eq('1 minute and 30 seconds')
+    end
+  end
+
+  describe '.distance_of_time_in_words_hash' do
+    it 'returns the distance as a hash' do
+      expect(
+        described_class.distance_of_time_in_words_hash(START_TIME_MODULE, START_TIME_MODULE + 1.hour + 30.minutes)
+      ).to include(hours: 1, minutes: 30)
+    end
+  end
+end