time_calc 0.0.1

data/lib/time_calc/types.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+class TimeCalc
+  # @private
+  # Tries to encapsulate all the differences between Time, Date, DateTime
+  module Types
+    extend self
+
+    ATTRS = {
+      Time => %i[year month day hour min sec subsec utc_offset],
+      Date => %i[year month day],
+      DateTime => %i[year month day hour min sec sec_fraction zone]
+    }.freeze
+
+    def compatible?(v1, v2)
+      [v1, v2].all?(Date) || [v1, v2].all?(Time)
+    end
+
+    def compare(v1, v2)
+      compatible?(v1, v2) ? v1 <=> v2 : v1.to_time <=> v2.to_time
+    end
+
+    def convert(v, klass)
+      return v if v.class == klass
+
+      v.public_send("to_#{klass.name.downcase}")
+    end
+
+    def merge_time(value, **attrs)
+      _merge(value, **attrs)
+        .tap { |h|
+          h[:sec] += h.delete(:subsec)
+          h[:utc_offset] = value.zone if value.zone.respond_to?(:utc_to_local) # Ruby 2.6 real timezones
+        }
+        .values.then { |components| Time.new(*components) }
+    end
+
+    def merge_date(value, **attrs)
+      _merge(value, **attrs).values.then { |components| Date.new(*components) }
+    end
+
+    def merge_datetime(value, **attrs)
+      # When we truncate, we use :subsec key as a sign to zeroefy second fractions
+      attrs[:sec_fraction] ||= attrs.delete(:subsec) if attrs.key?(:subsec)
+
+      _merge(value, **attrs)
+        .tap { |h| h[:sec] += h.delete(:sec_fraction) }
+        .values.then { |components| DateTime.new(*components) }
+    end
+
+    private
+
+    def _merge(value, attrs)
+      attr_names = ATTRS.fetch(value.class)
+      attr_names.to_h { |u| [u, value.public_send(u)] }.merge(**attrs.slice(*attr_names))
+    end
+  end
+end

data/lib/time_calc/units.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+class TimeCalc
+  # @private
+  # Unit-related constants and utilities for fetching their values
+  module Units
+    ALL = %i[year month week day hour min sec].freeze
+    NATURAL = %i[year month day hour min sec].freeze
+    STRUCTURAL = %i[year month day hour min sec subsec].freeze
+
+    SYNONYMS = {
+      second: :sec,
+      seconds: :sec,
+      minute: :min,
+      minutes: :min,
+      hours: :hour,
+      days: :day,
+      weeks: :week,
+      months: :month,
+      years: :year
+    }.freeze
+
+    DEFAULTS = {
+      month: 1,
+      day: 1,
+      hour: 0,
+      min: 0,
+      sec: 0,
+      subsec: 0
+    }.freeze
+
+    MULTIPLIERS = {
+      sec: 1,
+      min: 60,
+      hour: 60 * 60,
+      day: 24 * 60 * 60
+    }.freeze
+
+    def self.call(unit)
+      SYNONYMS.fetch(unit, unit)
+              .tap { |u| ALL.include?(u) or fail ArgumentError, "Unsupported unit: #{u}" }
+    end
+
+    def self.multiplier_for(klass, unit, precise: false)
+      res = MULTIPLIERS.fetch(unit)
+      d = MULTIPLIERS.fetch(:day)
+      case klass.name
+      when 'Time'
+        res
+      when 'DateTime'
+        res / d.to_f
+      when 'Date'
+        precise ? res / d.to_f : res / d
+      end
+    end
+  end
+end

data/lib/time_calc/value.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require 'backports/2.6.0/enumerable/to_h'
+require 'backports/2.6.0/array/to_h'
+require 'backports/2.6.0/hash/to_h'
+require 'backports/2.6.0/kernel/then'
+require 'backports/2.5.0/hash/slice'
+require 'backports/2.5.0/enumerable/all'
+
+class TimeCalc
+  # Wrapper (one can say "monad") around date/time value, allowing to perform several TimeCalc
+  # operations in a chain.
+  #
+  # @example
+  #   TimeCalc.wrap(Time.parse('2019-06-01 14:50')).+(1, :year).-(1, :month).round(:week).unwrap
+  #   # => 2020-05-04 00:00:00 +0300
+  #
+  class Value
+    # @private
+    TIMEY = proc { |t| t.respond_to?(:to_time) }
+
+    # @private
+    def self.wrap(value)
+      case value
+      when Time, Date, DateTime
+        new(value)
+      when Value
+        value
+      when TIMEY
+        wrap(value.to_time)
+      else
+        fail ArgumentError, "Unsupported value: #{value}"
+      end
+    end
+
+    # @private
+    attr_reader :internal
+
+    # @note
+    #   Prefer {TimeCalc.wrap} to create a Value.
+    # @param time_or_date [Time, Date, DateTime]
+    def initialize(time_or_date)
+      @internal = time_or_date
+    end
+
+    # @return [Time, Date, DateTime] The value of the original type that was wrapped and processed
+    def unwrap
+      @internal
+    end
+
+    # @private
+    def inspect
+      '#<%s(%s)>' % [self.class, internal]
+    end
+
+    # @return [1, 0, -1]
+    def <=>(other)
+      return unless other.is_a?(self.class)
+
+      Types.compare(internal, other.internal)
+    end
+
+    include Comparable
+
+    Units::ALL.each { |u| define_method(u) { internal.public_send(u) } }
+
+    def dst?
+      return unless internal.respond_to?(:dst?)
+
+      internal.dst?
+    end
+
+    # Produces new value with some components of underlying time/date replaced.
+    #
+    # @example
+    #    TimeCalc.from(Date.parse('2018-06-01')).merge(year: 1983)
+    #    # => #<TimeCalc::Value(1983-06-01)>
+    #
+    # @param attrs [Hash<Symbol => Integer>]
+    # @return [Value]
+    def merge(**attrs)
+      Value.new(Types.public_send("merge_#{internal.class.name.downcase}", internal, **attrs))
+    end
+
+    # Truncates all time components lower than `unit`. In other words, "floors" (rounds down)
+    # underlying date/time to nearest `unit`.
+    #
+    # @example
+    #   TimeCalc.from(Time.parse('2018-06-23 12:30')).floor(:month)
+    #   # => #<TimeCalc::Value(2018-06-01 00:00:00 +0300)>
+    #
+    # @param unit [Symbol]
+    # @return Value
+    def truncate(unit)
+      unit = Units.(unit)
+      return floor_week if unit == :week
+
+      Units::STRUCTURAL
+        .drop_while { |u| u != unit }
+        .drop(1)
+        .then { |keys| Units::DEFAULTS.slice(*keys) }
+        .then(&method(:merge))
+    end
+
+    alias floor truncate
+
+    # Ceils (rounds up) underlying date/time to nearest `unit`.
+    #
+    # @example
+    #   TimeCalc.from(Time.parse('2018-06-23 12:30')).ceil(:month)
+    #   # => #<TimeCalc::Value(2018-07-01 00:00:00 +0300)>
+    #
+    # @param unit [Symbol]
+    # @return [Value]
+    def ceil(unit)
+      floor(unit).then { |res| res == self ? res : res.+(1, unit) }
+    end
+
+    # Rounds up or down underlying date/time to nearest `unit`.
+    #
+    # @example
+    #   TimeCalc.from(Time.parse('2018-06-23 12:30')).round(:month)
+    #   # => #<TimeCalc::Value(2018-07-01 00:00:00 +0300)>
+    #
+    # @param unit [Symbol]
+    # @return Value
+    def round(unit)
+      f, c = floor(unit), ceil(unit)
+
+      (internal - f.internal).abs < (internal - c.internal).abs ? f : c
+    end
+
+    # Add `<span units>` to wrapped value.
+    #
+    # @param span [Integer]
+    # @param unit [Symbol]
+    # @return [Value]
+    def +(span, unit)
+      unit = Units.(unit)
+      case unit
+      when :sec, :min, :hour, :day
+        plus_seconds(span, unit)
+      when :week
+        self.+(span * 7, :day)
+      when :month
+        plus_months(span)
+      when :year
+        merge(year: year + span)
+      end
+    end
+
+    # @overload -(span, unit)
+    #   Subtracts `span units` from wrapped value.
+    #   @param span [Integer]
+    #   @param unit [Symbol]
+    #   @return [Value]
+    # @overload -(date_or_time)
+    #   Produces {Diff}, allowing to calculate structured difference between two points in time.
+    #   @param date_or_time [Date, Time, DateTime]
+    #   @return [Diff]
+    # Subtracts `span units` from wrapped value.
+    def -(span_or_other, unit = nil)
+      unit.nil? ? Diff.new(self, span_or_other) : self.+(-span_or_other, unit)
+    end
+
+    # Produces {Sequence} from this value to `date_or_time`
+    #
+    # @param date_or_time [Date, Time, DateTime]
+    # @return [Sequence]
+    def to(date_or_time)
+      Sequence.new(from: self).to(date_or_time)
+    end
+
+    # Produces endless {Sequence} from this value, with step specified.
+    #
+    # @overload step(unit)
+    #   Shortcut for `step(1, unit)`
+    #   @param unit [Symbol]
+    # @overload step(span, unit)
+    #   @param span [Integer]
+    #   @param unit [Symbol]
+    # @return [Sequence]
+    def step(span, unit = nil)
+      span, unit = 1, span if unit.nil?
+      Sequence.new(from: self).step(span, unit)
+    end
+
+    # Produces {Sequence} from this value to `this + <span units>`
+    #
+    # @param span [Integer]
+    # @param unit [Symbol]
+    # @return [Sequence]
+    def for(span, unit)
+      to(self.+(span, unit))
+    end
+
+    # @private
+    def convert(klass)
+      return dup if internal.class == klass
+
+      Value.new(Types.convert(internal, klass))
+    end
+
+    private
+
+    def floor_week
+      extra_days = (internal.wday.nonzero? || 7) - 1
+      floor(:day).-(extra_days, :days)
+    end
+
+    def plus_months(span)
+      target = month + span.to_i
+      m = (target - 1) % 12 + 1
+      dy = (target - 1) / 12
+      merge(year: year + dy, month: m)
+    end
+
+    def plus_seconds(span, unit)
+      Value.new(internal + span * Units.multiplier_for(internal.class, unit))
+           .then { |res| unit == :day ? DST.fix_value(res, self) : res }
+    end
+  end
+end

data/lib/time_calc/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class TimeCalc
+  # @private
+  VERSION = '0.0.1'
+end

metadata

@@ -0,0 +1,211 @@
+--- !ruby/object:Gem::Specification
+name: time_calc
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Victor Shepelev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-07-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: backports
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.15.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.15.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.72.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.72.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.17.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.17.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: saharspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: tzinfo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubygems-tasks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2
+      TimeCalc is a library for idiomatic time calculations, like "plus N days", "floor to month start",
+      "how many hours between those dates", "sequence of months from this to that". It intends to
+      be small and easy to remember without any patching of core classes.
+email: zverok.offline@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/time_calc.rb
+- lib/time_calc/diff.rb
+- lib/time_calc/dst.rb
+- lib/time_calc/op.rb
+- lib/time_calc/sequence.rb
+- lib/time_calc/types.rb
+- lib/time_calc/units.rb
+- lib/time_calc/value.rb
+- lib/time_calc/version.rb
+homepage: https://github.com/zverok/time_calc
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.14
+signing_key: 
+specification_version: 4
+summary: Easy time math
+test_files: []