timerizer 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e03bc2d5660e629ad3545c610bf09efa55fbe07cec5c364970eabb8001add9fd
-  data.tar.gz: 050b2b058e5c63eda87f973e5adde7c84e34c9c230833c47f84eb7189ef0d774
+  metadata.gz: 02461e09b8beea13b38f2e36aab85ab643fe7975b2f96132aa7bdbe8930ed370
+  data.tar.gz: 9fe1a1573e379256bedf1628ea469ec65c0e68f3a8da842ed77d995b0b70f753
 SHA512:
-  metadata.gz: bcc860c64450e0e1f099dca114205f727410a216846c25a61ce75b5052783e95a7b748df72227b9b1b108d44ca0eb11f4dbb81ac7ddcf715629f3a4d9e3135a1
-  data.tar.gz: a9836b0cb9c429a8ed66fad757cea99f022934af83e7b5757f8bd84fdf805fe102624d6e14b41d6e9711cbb10dbb53fbd315798b86633de18edfb1e560d2b6ed
+  metadata.gz: 1135496242298cd85e09d05d945b156cd592f76f9645a4b4bd3693e8cda1f3b190e8a27130a64337077ae62ab4b47f3205e8fbdeb6178034e358bb7f682dcbc6
+  data.tar.gz: baa46d6fe2ad8cec7bd48199081624dd31f2499235c04f319c0bd27b58417dfbc649f1e41cf207b2156985f56ca6a76148926cbc09ea083e2023dd3963bc2354

data/lib/timerizer/duration/rounded_time.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+require 'forwardable'
+
+module Timerizer
+  class Duration
+    # Wraps rounding a {Timerizer::Duration} to the nearest value by the number
+    # of "places", which are customary time units (seconds, minutes, hours,
+    # days, months, years, etc; decades and weeks are not included).
+    #
+    # @private
+    class RoundedTime
+      extend Forwardable
+
+      # @!method remainder_times
+      #   @return (see TermTimes#remainder_times)
+      # @!method target_unit
+      #   @return (see TermTimes#target_unit)
+      # @!method times
+      #   @return (see TermTimes#times)
+      def_delegators :@tt, :remainder_times, :target_unit, :times
+
+      # Default "places" (units, e.g., hours/minutes) to use for rounding.
+      DEFAULT_PLACES = 2
+      # Default {Timerizer::Duration::UNITS} *not* to include in rounded value.
+      OMITTED_KEYS = [:decades, :weeks]
+
+      # Given an original {Timerizer::Duration} instance, return a new instance
+      # that "rounds" the duration to the closest value expressed in a certain
+      # number of units (default 2).
+      #
+      # @param [{Timerizer::Duration}] duration Object encapsulating a duration
+      #                     (in hours, minutes, etc) to "round" to a number of
+      #                     units specified by `places`.
+      # @param [Integer] places Number of units to include in rounded value.
+      #                     Default is 2.
+      # @param [Array<Symbol>] omitted_keys Units to omit from calculation or
+      #                     return value. Default is `[:decades, :weeks]`
+      # @return {Timerizer::Duration}
+      # @example
+      #   t = (12.hours 16.minutes 47.seconds).ago
+      #   d = Time.since(t)
+      #   d2 = RoundedTime.call(d)
+      #   d.to_s  # => "12 hours, 16 minutes, 47 seconds"
+      #   d2.to_s # => "12 hours, 17 minutes"
+      #
+      def self.call(duration, places = DEFAULT_PLACES,
+                    omitted_keys = OMITTED_KEYS)
+        new(duration, places, omitted_keys).call
+      end
+
+      # High-level method to do calculations on component durations.
+      #
+      # @return {Timerizer::Duration}
+      #
+      def call
+        remainder = sum_of(remainder_times)
+        sum_of(times) + offset_from(remainder)
+      end
+
+      private
+
+      # Initial value for adding a collection of Duration instances.
+      # (see #sum_of)
+      ZERO_TIME = Timerizer::Duration.new(seconds: 0)
+      private_constant :ZERO_TIME
+
+      # Private initialiser to prevent direct instantiation by client code.
+      #
+      # @param [{Timerizer::Duration}] duration Object encapsulating a duration
+      #                     (in hours, minutes, etc) to "round" to a number of
+      #                     units specified by `places`.
+      # @param [Integer] places Number of units to include in rounded value.
+      #                     Default is 2.
+      # @param [Array<Symbol>] omitted_keys Units to omit from calculation or
+      #                     return value. Default is `[:decades, :weeks]`
+      #
+      def initialize(duration, places = DEFAULT_PLACES,
+                     omitted_keys = OMITTED_KEYS)
+        @tt = TermTimes.new(duration, omitted_keys).call(places).freeze
+      end
+
+      # Determine whether returned {Timerizer::Duration} value should be rounded
+      # up or down based on a remainder value.
+      #
+      # If the remainder value is more than half of the {#target_unit}, then
+      # this will return a duration of 1 times the target unit, else a duration
+      # of {ZERO_TIME}.
+      #
+      # @return [{Timerizer::Duration}] Either zero or 1 times the `target_unit`
+      # @param [{Timerizer::Duration}] remainder Value of input duration less
+      #                     than one `target_unit`
+      def offset_from(remainder)
+        Timerizer::Duration.new((remainder * 2).to_units(target_unit))
+      end
+
+      # Add all time (Duration) values in an Array (or other Enumerable).
+      #
+      # @return [{Timerizer::Duration}] Sum total of input values.
+      # @param [Array<{Timerizer::Duration}>] Unit values to add together
+      #
+      def sum_of(time_values)
+        time_values.inject(ZERO_TIME, :+)
+      end
+
+      # Convert a single {Timerizer::Duration} instance into an enumeration of
+      # per-unit Duration instances (hours, minutes, etc).
+      #
+      # @private
+      class TermTimes
+        # Least-significant time unit (e.g., ``:days`) used for rounding.
+        # @return [Symbol] Least-significant time unit in the resulting value.
+        attr_reader :target_unit
+        # Time units to be included in "rounded" result, before rounding.
+        # @return [Array<{Timerizer::Duration}>] Base result time-unit values.
+        attr_reader :times
+        # Time units to be "rounded" to adjust resulting Duration value.
+        # @return [Array<{Timerizer::Duration}>] Remaining time-unit values.
+        attr_reader :remainder_times
+
+        # Build array of time-part values based on input {Timerizer::Duration}.
+        #
+        # @param [{Timerizer::Duration}] duration Time differential used as
+        #                     input.
+        # @param [Array<Symbol>] omitted_keys {Timerizer::Duration::UNITS}
+        #                     values to exclude from resulting value.
+        #
+        def initialize(duration, omitted_keys)
+          @part_values = filter_units(duration, omitted_keys)
+        end
+
+        # Compute per-unit {Timerizer::Duration} values, split based on unit
+        # count
+        #
+        # @param [Integer] places Number of time units to include in main Array.
+        def call(places)
+          # Note that `places` may exceed the number of actual units in the
+          # value. For example, with a duration of `(10.days)` and a `places`
+          # value of 2. Adjust as needed.
+          places = @part_values.count - 1 if @part_values.count < places
+          # If a zero-time `duration` is passed in, then @part_values will be
+          # empty, and the key arithmetic will return `nil`. Adjust as needed.
+          @target_unit = @part_values.keys[places - 1] || :seconds
+          term_times = unit_times
+          @times = term_times[0..places - 1]
+          @remainder_times = term_times[@times.count..-1]
+          self
+        end
+
+        private
+
+        def filter_units(duration, omitted_keys)
+          unit_keys = Timerizer::Duration::UNITS.keys - omitted_keys
+          duration.to_units(*unit_keys).reject { |_, v| v.zero? }
+        end
+
+        def unit_times
+          @part_values.map { |unit, val| Timerizer::Duration.new(unit => val) }
+        end
+      end # class RoundedTime::TermTimes
+      private_constant :TermTimes
+    end # class RoundedTime
+  end
+end

data/lib/timerizer/version.rb

@@ -1,3 +1,3 @@
 module Timerizer
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timerizer
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Kyle Lacy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-27 00:00:00.000000000 Z
+date: 2018-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -76,6 +76,7 @@ files:
 - lib/timerizer.rb
 - lib/timerizer/core.rb
 - lib/timerizer/duration.rb
+- lib/timerizer/duration/rounded_time.rb
 - lib/timerizer/version.rb
 - lib/timerizer/wall_clock.rb
 homepage: http://github.com/kylewlacy/timerizer