time_math2 0.0.3

data/lib/time_math/units/base.rb

@@ -0,0 +1,264 @@
+module TimeMath
+  module Units
+    # It is a main class representing most of TimeMath functionality.
+    # It (or rather its descendants) represents "unit of time" and
+    # connected calculations logic. Typical usage:
+    #
+    # ```ruby
+    # TimeMath.day.advance(tm, 5) # advances tm by 5 days
+    # ```
+    #
+    class Base
+      # Creates unit of time. Typically you don't need it, as it is
+      # easier to do `TimeMath.day` or `TimeMath[:day]` to obtain it.
+      #
+      # @param name [Symbol] one of {TimeMath.units}.
+      def initialize(name)
+        @name = name
+      end
+
+      attr_reader :name
+
+      # Rounds `tm` down to nearest unit (this means, `TimeMath.day.floor(tm)`
+      # will return beginning of `tm`-s day, and so on).
+      #
+      # @param tm [Time,DateTime] time value to floor.
+      # @return [Time,DateTime] floored time value; class and timezone info
+      #   of origin would be preserved.
+      def floor(tm)
+        components = [tm.year,
+                      tm.month,
+                      tm.day,
+                      tm.hour,
+                      tm.min,
+                      tm.sec].first(index + 1)
+
+        new_from_components(tm, *components)
+      end
+
+      # Rounds `tm` up to nearest unit (this means, `TimeMath.day.ceil(tm)`
+      # will return beginning of day next after `tm`, and so on).
+      #
+      # @param tm [Time,DateTime] time value to ceil.
+      # @return [Time,DateTime] ceiled time value; class and timezone info
+      #   of origin would be preserved.
+      def ceil(tm)
+        f = floor(tm)
+
+        f == tm ? f : advance(f)
+      end
+
+      # Rounds `tm` up or down to nearest unit (this means, `TimeMath.day.round(tm)`
+      # will return beginning of `tm` day if `tm` is before noon, and
+      # day next after `tm` if it is after, and so on).
+      #
+      # @param tm [Time,DateTime] time value to round.
+      # @return [Time,DateTime] rounded time value; class and timezone info
+      #   of origin would be preserved.
+      def round(tm)
+        f, c = floor(tm), ceil(tm)
+
+        (tm - f).abs < (tm - c).abs ? f : c
+      end
+
+      # Like {#floor}, but always return value lower than `tm` (e.g. if
+      # `tm` is exactly midnight, then `TimeMath.day.prev(tm)` will return
+      # _previous midnight_).
+      #
+      # @param tm [Time,DateTime] time value to calculate prev on.
+      # @return [Time,DateTime] prev time value; class and timezone info
+      #   of origin would be preserved.
+      def prev(tm)
+        f = floor(tm)
+        f == tm ? decrease(f) : f
+      end
+
+      # Like {#ceil}, but always return value greater than `tm` (e.g. if
+      # `tm` is exactly midnight, then `TimeMath.day.next(tm)` will return
+      # _next midnight_).
+      #
+      # @param tm [Time,DateTime] time value to calculate next on.
+      # @return [Time,DateTime] next time value; class and timezone info
+      #   of origin would be preserved.
+      def next(tm)
+        c = ceil(tm)
+        c == tm ? advance(c) : c
+      end
+
+      # Checks if `tm` is exactly rounded to unit.
+      #
+      # @param tm [Time,DateTime] time value to check.
+      # @return [Boolean] whether `tm` is exactly round to unit.
+      def round?(tm)
+        floor(tm) == tm
+      end
+
+      # Advances `tm` by given amount of unit.
+      #
+      # @param tm [Time,DateTime] time value to advance;
+      # @param amount [Integer] how many units forward to go.
+      #
+      # @return [Time,DateTime] advanced time value; class and timezone info
+      #   of origin would be preserved.
+      def advance(tm, amount = 1)
+        return decrease(tm, -amount) if amount < 0
+        _advance(tm, amount)
+      end
+
+      # Decreases `tm` by given amount of unit.
+      #
+      # @param tm [Time,DateTime] time value to decrease;
+      # @param amount [Integer] how many units forward to go.
+      #
+      # @return [Time,DateTime] decrease time value; class and timezone info
+      #   of origin would be preserved.
+      def decrease(tm, amount = 1)
+        return advance(tm, -amount) if amount < 0
+        _decrease(tm, amount)
+      end
+
+      # Creates range from `tm` to `tm` increased by amount of units.
+      #
+      # ```ruby
+      # tm = Time.parse('2016-05-28 16:30')
+      # TimeMath.day.range(tm, 5)
+      # # => 2016-05-28 16:30:00 +0300...2016-06-02 16:30:00 +0300
+      # ```
+      #
+      # @param tm [Time,DateTime] time value to create range from;
+      # @param amount [Integer] how many units should be between range
+      #   start and end.
+      #
+      # @return [Range]
+      def range(tm, amount = 1)
+        (tm...advance(tm, amount))
+      end
+
+      # Creates range from `tm` decreased by amount of units to `tm`.
+      #
+      # ```ruby
+      # tm = Time.parse('2016-05-28 16:30')
+      # TimeMath.day.range_back(tm, 5)
+      # # => 2016-05-23 16:30:00 +0300...2016-05-28 16:30:00 +0300
+      # ```
+      #
+      # @param tm [Time,DateTime] time value to create range from;
+      # @param amount [Integer] how many units should be between range
+      #   start and end.
+      #
+      # @return [Range]
+      def range_back(tm, amount = 1)
+        (decrease(tm, amount)...tm)
+      end
+
+      # Measures distance between `from` and `to` in units of this class.
+      #
+      # @param from [Time,DateTime] start of period;
+      # @param to [Time,DateTime] end of period.
+      #
+      # @return [Integer] how many full units are inside the period.
+      # :nocov:
+      def measure(from, to) # rubocop:disable Lint/UnusedMethodArgument
+        raise NotImplementedError,
+              '#measure should be implemented in subclasses'
+      end
+      # :nocov:
+
+      # Like {#measure} but also returns "remainder": the time where
+      # it would be **exactly** returned amount of units between `from`
+      # and `to`:
+      #
+      # ```ruby
+      # TimeMath.day.measure(Time.parse('2016-05-01 16:20'), Time.parse('2016-05-28 15:00'))
+      # # => 26
+      # TimeMath.day.measure_rem(Time.parse('2016-05-01 16:20'), Time.parse('2016-05-28 15:00'))
+      # # => [26, 2016-05-27 16:20:00 +0300]
+      # ```
+      #
+      # @param from [Time,DateTime] start of period;
+      # @param to [Time,DateTime] end of period.
+      #
+      # @return [Array<Integer, Time or DateTime>] how many full units
+      #   are inside the period; exact value of `from` + full units.
+      def measure_rem(from, to)
+        m = measure(from, to)
+        [m, advance(from, m)]
+      end
+
+      # Creates {Span} instance representing amount of units.
+      #
+      # Use it like this:
+      #
+      # ```ruby
+      # span = TimeMath.day.span(5) # => #<TimeMath::Span(day): +5>
+      # # now you can save this variable or path it to the methods...
+      # # and then:
+      # span.before(Time.parse('2016-05-01')) # => 2016-04-26 00:00:00 +0300
+      # span.after(Time.parse('2016-05-01')) # => 2016-05-06 00:00:00 +0300
+      # ```
+      #
+      # @param amount [Integer]
+      # @return [Span]
+      def span(amount = 1)
+        TimeMath::Span.new(name, amount)
+      end
+
+      # Creates {Sequence} instance for producing all time units between
+      # from and too. See {Sequence} class documentation for available
+      # options and functionality.
+      #
+      # @param from [Time,DateTime] start of sequence;
+      # @param to [Time,DateTime] upper limit of sequence;
+      # @param options [Hash]
+      # @option options [Boolean] :expand round sequence ends on creation
+      #   (from is floored and to is ceiled);
+      # @option options [Boolean] :floor sequence will be rounding'ing all
+      #   the intermediate values.
+      #
+      # @return [Sequence]
+      def sequence(from, to, options = {})
+        TimeMath::Sequence.new(name, from, to, options)
+      end
+
+      def inspect
+        "#<#{self.class}>"
+      end
+
+      protected
+
+      # all except :week
+      NATURAL_UNITS = [:year, :month, :day, :hour, :min, :sec].freeze
+      EMPTY_VALUES = [nil, 1, 1, 0, 0, 0].freeze
+
+      def index
+        NATURAL_UNITS.index(name) or
+          raise NotImplementedError, "Can not be used for #{name}"
+      end
+
+      def generate(tm, replacements = {})
+        hash_to_tm(tm, tm_to_hash(tm).merge(replacements))
+      end
+
+      def tm_to_hash(tm)
+        Hash[*NATURAL_UNITS.flat_map { |s| [s, tm.send(s)] }]
+      end
+
+      def hash_to_tm(origin, hash)
+        components = NATURAL_UNITS.map { |s| hash[s] || 0 }
+        new_from_components(origin, *components)
+      end
+
+      def new_from_components(origin, *components)
+        components = EMPTY_VALUES.zip(components).map { |d, c| c || d }
+        case origin
+        when Time
+          Time.mktime(*components.reverse, nil, nil, nil, origin.zone)
+        when DateTime
+          DateTime.new(*components, origin.zone)
+        end
+      end
+
+      include TimeMath # now we can use something like #day inside other units
+    end
+  end
+end

data/lib/time_math/units/day.rb

@@ -0,0 +1,34 @@
+module TimeMath
+  module Units
+    # @private
+    class Day < Simple
+      def initialize
+        super(:day)
+      end
+
+      protected
+
+      def _advance(tm, steps)
+        fix_dst(super(tm, steps), tm)
+      end
+
+      def _decrease(tm, steps)
+        fix_dst(super(tm, steps), tm)
+      end
+
+      # :nocov: - somehow Travis env thinks other things about DST
+      def fix_dst(res, src)
+        return res unless res.is_a?(Time)
+
+        if res.dst? && !src.dst?
+          hour.decrease(res)
+        elsif !res.dst? && src.dst?
+          hour.advance(res)
+        else
+          res
+        end
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/time_math/units/month.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+module TimeMath
+  module Units
+    # @private
+    class Month < Base
+      def initialize
+        super(:month)
+      end
+
+      def measure(from, to)
+        ydiff = to.year - from.year
+        mdiff = to.month - from.month
+
+        to.day >= from.day ? (ydiff * 12 + mdiff) : (ydiff * 12 + mdiff - 1)
+      end
+
+      protected
+
+      def succ(tm)
+        return generate(tm, year: tm.year + 1, month: 1) if tm.month == 12
+
+        t = generate(tm, month: tm.month + 1)
+        fix_month(t, t.month + 1)
+      end
+
+      def prev(tm)
+        return generate(tm, year: tm.year - 1, month: 12) if tm.month == 1
+
+        t = generate(tm, month: tm.month - 1)
+        fix_month(t, t.month - 1)
+      end
+
+      def _advance(tm, steps)
+        steps.times.inject(tm) { |t| succ(t) }
+      end
+
+      def _decrease(tm, steps)
+        steps.times.inject(tm) { |t| prev(t) }
+      end
+
+      # fix for too far advance/insufficient decrease:
+      #  Time.new(2013,2,31) #=> 2013-03-02 00:00:00 +0200
+      def fix_month(t, expected)
+        t.month == expected ? day.decrease(t, t.day) : t
+      end
+    end
+  end
+end

data/lib/time_math/units/simple.rb

@@ -0,0 +1,58 @@
+module TimeMath
+  module Units
+    # @private
+    class Simple < Base
+      def to_seconds(sz = 1)
+        sz * MULTIPLIERS[index..-1].inject(:*)
+      end
+
+      def measure(from, to)
+        ((to.to_time - from.to_time) / to_seconds).to_i
+      end
+
+      protected
+
+      def _advance(tm, steps)
+        _shift(tm, to_seconds(steps))
+      end
+
+      def _decrease(tm, steps)
+        _shift(tm, -to_seconds(steps))
+      end
+
+      def _shift(tm, seconds)
+        case tm
+        when Time
+          tm + seconds
+        when DateTime
+          tm + Rational(seconds, 86_400)
+        else
+          raise ArgumentError, "Expected Time or DateTime, got #{tm.class}"
+        end
+      end
+
+      MULTIPLIERS = [12, 30, 24, 60, 60, 1].freeze
+    end
+
+    # @private
+    class Sec < Simple
+      def initialize
+        super(:sec)
+      end
+    end
+
+    # @private
+    class Min < Simple
+      def initialize
+        super(:min)
+      end
+    end
+
+    # @private
+    class Hour < Simple
+      def initialize
+        super(:hour)
+      end
+    end
+  end
+end

data/lib/time_math/units/week.rb

@@ -0,0 +1,30 @@
+module TimeMath
+  module Units
+    # @private
+    class Week < Simple
+      def initialize
+        super(:week)
+      end
+
+      def floor(tm)
+        f = day.floor(tm)
+        extra_days = tm.wday == 0 ? 6 : tm.wday - 1
+        day.decrease(f, extra_days)
+      end
+
+      def to_seconds(sz = 1)
+        day.to_seconds(sz * 7)
+      end
+
+      protected
+
+      def _advance(tm, steps)
+        day.advance(tm, steps * 7)
+      end
+
+      def _decrease(tm, steps)
+        day.decrease(tm, steps * 7)
+      end
+    end
+  end
+end

data/lib/time_math/units/year.rb

@@ -0,0 +1,28 @@
+module TimeMath
+  module Units
+    # @private
+    class Year < Base
+      def initialize
+        super(:year)
+      end
+
+      def measure(from, to)
+        if generate(from, year: to.year) < to
+          to.year - from.year
+        else
+          to.year - from.year - 1
+        end
+      end
+
+      protected
+
+      def _advance(tm, steps)
+        generate(tm, year: tm.year + steps)
+      end
+
+      def _decrease(tm, steps)
+        generate(tm, year: tm.year - steps)
+      end
+    end
+  end
+end

data/lib/time_math/units.rb

@@ -0,0 +1,29 @@
+require_relative 'units/base'
+require_relative 'units/simple'
+require_relative 'units/day'
+require_relative 'units/week'
+require_relative 'units/month'
+require_relative 'units/year'
+
+module TimeMath
+  # See {Units::Base} for detailed description of all units functionality.
+  module Units
+    # @private
+    UNITS = {
+      sec: Units::Sec.new, min: Units::Min.new, hour: Units::Hour.new,
+      day: Units::Day.new, week: Units::Week.new, month: Units::Month.new,
+      year: Units::Year.new
+    }.freeze
+
+    # @private
+    def self.names
+      UNITS.keys
+    end
+
+    # @private
+    def self.get(name)
+      UNITS[name] or
+        raise ArgumentError, "Unsupported unit: #{name}"
+    end
+  end
+end

data/lib/time_math/version.rb

@@ -0,0 +1,4 @@
+module TimeMath
+  # @private
+  VERSION = '0.0.3'.freeze
+end

data/lib/time_math.rb

@@ -0,0 +1,99 @@
+require 'time'
+
+require_relative './time_math/units'
+require_relative './time_math/sequence'
+require_relative './time_math/measure'
+require_relative './time_math/span'
+
+# TimeMath is a small library for easy time units arithmetics (like "floor
+# the timestamp to the nearest hour", "advance the time value by 3 days"
+# and so on).
+#
+# It has clean and easy-to-remember API, just like this:
+#
+# ```ruby
+# TimeMath.day.floor(Time.now)
+# # or
+# TimeMath[:day].floor(Time.now)
+# ```
+#
+# `TimeMath[unit]` and `TimeMath.<unit>` give you an instance of
+# time unit, which incapsulates most of the functionality. Refer to
+# {Units::Base} to see what you can get of it.
+#
+module TimeMath
+  # rubocop:disable Style/ModuleFunction
+  extend self
+  # rubocop:enable Style/ModuleFunction
+
+  # List all unit names known.
+  #
+  # @return [Array<Symbol>]
+  def units
+    Units.names
+  end
+
+  # Main method to do something with TimeMath. Returns an object
+  # representing some time measurement unit. See {Units::Base} documentation
+  # to know what you can do with it.
+  #
+  # @return [Units::Base]
+  def [](unit)
+    Units.get(unit)
+  end
+
+  # @!method sec
+  #   Shortcut to get second unit.
+  #   @return [Units::Base]
+  #
+  # @!method min
+  #   Shortcut to get minute unit.
+  #   @return [Units::Base]
+  #
+  # @!method hour
+  #   Shortcut to get hour unit.
+  #   @return [Units::Base]
+  #
+  # @!method day
+  #   Shortcut to get day unit.
+  #   @return [Units::Base]
+  #
+  # @!method week
+  #   Shortcut to get week unit.
+  #   @return [Units::Base]
+  #
+  # @!method month
+  #   Shortcut to get month unit.
+  #   @return [Units::Base]
+  #
+  # @!method year
+  #   Shortcut to get year unit.
+  #   @return [Units::Base]
+  #
+  Units.names.each do |unit|
+    define_method(unit) { Units.get(unit) }
+  end
+
+  # Measures distance between two time values in all units at once.
+  #
+  # Just like this:
+  #
+  # ```ruby
+  # birthday = Time.parse('1983-02-14 13:30')
+  #
+  # TimeMath.measure(birthday, Time.now)
+  # # => {:years=>33, :months=>3, :weeks=>2, :days=>0, :hours=>1, :minutes=>25, :seconds=>52}
+  # ```
+  #
+  # @param from [Time,DateTime]
+  # @param to [Time,DateTime]
+  # @param options [Hash] options
+  # @option options [Boolean] :weeks pass `false` to exclude weeks from calculation;
+  # @option options [Symbol] :upto pass max unit to use (e.g. if you'll
+  #   pass `:day`, period would be measured in days, hours, minutes and seconds).
+  #
+  # @return [Hash]
+  def measure(from, to, options = {})
+    Measure.measure(from, to, options)
+  end
+end

data/time_math2.gemspec

@@ -0,0 +1,39 @@
+require './lib/time_math/version'
+
+Gem::Specification.new do |s|
+  s.name     = 'time_math2'
+  s.version  = TimeMath::VERSION
+  s.authors  = ['Victor Shepelev']
+  s.email    = 'zverok.offline@gmail.com'
+  s.homepage = 'https://github.com/zverok/time_math2'
+
+  s.summary = 'Easy time math'
+  s.description = <<-EOF
+    TimeMath is small, no-dependencies library attemting to make work with
+    time units easier. It provides you with simple, easy remembered API, without
+    any monkey patching of core Ruby classes, so it can be used alongside
+    Rails or without it, for any purpose.
+  EOF
+  s.licenses = ['MIT']
+
+  s.files = `git ls-files`.split($RS).reject do |file|
+    file =~ /^(?:
+    spec\/.*
+    |Gemfile
+    |Rakefile
+    |\.rspec
+    |\.gitignore
+    |\.rubocop.yml
+    |\.travis.yml
+    )$/x
+  end
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rubocop', '>= 0.30'
+  s.add_development_dependency 'rspec', '>= 3'
+  s.add_development_dependency 'rspec-its', '~> 1'
+  s.add_development_dependency 'simplecov', '~> 0.9'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rubygems-tasks'
+  s.add_development_dependency 'yard'
+end