time_calc 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 277cc038ff0318d9b8aacb51c60ae7fda0730e24e913f89fd145dc4abb8420c4
-  data.tar.gz: 233d29d03a7d4be6bf6656ca567b16066096af9c4a47f102dc9aafdd52691759
+  metadata.gz: 3222784ca4e6f520d4402ce84f5ea6f8a9becccb66e3640071d0a29b332297b7
+  data.tar.gz: 9746e03e5a3e560a5f63780e87ea75f87597faa44e594228f075ae5daca3a83b
 SHA512:
-  metadata.gz: 1977f5b4e572a304ef4ccb440c1b7ecc16cfe922d7e34f1163b85507cc4143fcfb8607c1a5f8b66b677986b6926af97cbd548560f0c4c056aabcb6e9faa34de1
-  data.tar.gz: 0f53ed256fa451adb9f30ccf256ac957c5370f0d0cbeba8d8dbe648066051ccbcea3ca45475a0a1234cd092014dd0059a14a21aa088f416b94c4efa341ad9295
+  metadata.gz: a6f3315fe5e4bc9334cbee7f089f50aebf7dfa854a6580f7cc53488afa0c8cb9ef0601f0d47c691b8427cbeea4dcc2842c97022666009e3b01b8e4056883b67c
+  data.tar.gz: d0ccd1540d9010f5c4cec6c3fb4708b75c3fc795cbe8913f7a7e43455caa6bf209f6d39ca828dd83bae8d73f4a7e8b7a0a7a432eaeaaec33442e6ef1afe5716d

data/Changelog.md

@@ -1,9 +1,13 @@
 # TimeCalc changelog
 
+## 0.0.3 / 2019-12-14
+
+* Add `TimeCalc#iterate` to easily operate in "business date/time" contexts.
+
 ## 0.0.2 / 2019-07-08
 
 * Alias `TimeCalc[tm]` for those who disapporve on `TimeCalc.(tm)`;
-* More accurate zone infor preservation when time is in local timezone of current machine.
+* More accurate zone info preservation when time is in local timezone of current machine.
 
 ## 0.0.1 / 2019-07-05
 

data/README.md

@@ -67,6 +67,29 @@ TimeCalc.(t).+(3, :months) # jump over DST: we have +3 in summer and +2 in winte
 ```
 <small>(Random fun fact: it is Kyiv, not Kiev!)</small>
 
+### Math with skipping "non-business time"
+
+[TimeCalc#iterate](https://www.rubydoc.info/gems/time_calc/TimeCalc#iterate-instance_method) allows to advance or decrease time values by skipping some of them (like weekends, holidays, and non-working hours):
+
+```ruby
+# add 10 working days (weekends are not counted)
+TimeCalc.(Time.parse('2019-07-03 23:28:54')).iterate(10, :days) { |t| (1..5).cover?(t.wday) }
+# => 2019-07-17 23:28:54 +0300
+
+# add 12 working hours
+TimeCalc.(Time.parse('2019-07-03 13:28:54')).iterate(12, :hours) { |t| (9...18).cover?(t.hour) }
+# => 2019-07-04 16:28:54 +0300
+
+# negative spans are working, too:
+TimeCalc.(Time.parse('2019-07-03 13:28:54')).iterate(-12, :hours) { |t| (9...18).cover?(t.hour) }
+# => 2019-07-02 10:28:54 +0300
+
+# zero span could be used to robustly enforce value into acceptable range
+# (increasing forward till block is true):
+TimeCalc.(Time.parse('2019-07-03 23:28:54')).iterate(0, :hours) { |t| (9...18).cover?(t.hour) }
+# => 2019-07-04 09:28:54 +0300
+```
+
 ### Difference of two values
 
 ```ruby
@@ -118,7 +141,7 @@ TBH, using the library myself only eventually, I have never been too happy with
 # "Formalized": now - 2 days
 
 # ActiveSupport:
-Time.now + 2.days
+Time.now - 2.days
 # also there is 2.days.ago, but I am not a big fan of "1000 synonyms just for naturality"
 
 # TimeMath:
@@ -146,4 +169,4 @@ The rest of the design (see examples above) just followed naturally. There could
 ## Author & license
 
 * [Victor Shepelev](https://zverok.github.io)
-* [MIT](https://github.com/zverok/time_calc/blob/master/LICENSE.txt).
+* [MIT](https://github.com/zverok/time_calc/blob/master/LICENSE.txt).

data/lib/time_calc/diff.rb

@@ -285,7 +285,7 @@ class TimeCalc
     # Will coerce Date to Time or DateTime, with the _zone of the latter_
     def coerce_date(date, other)
       TimeCalc.(other)
-        .merge(Units::DEFAULTS.merge(year: date.year, month: date.month, day: date.day))
+        .merge(**Units::DEFAULTS.merge(year: date.year, month: date.month, day: date.day))
     end
   end
 end

data/lib/time_calc/op.rb

@@ -22,17 +22,21 @@ class TimeCalc
 
     # @private
     def inspect
-      '<%s %s>' % [self.class, @chain.map { |name, *args| "#{name}(#{args.join(' ')})" }.join('.')]
+      '<%s %s>' % [self.class, @chain.map { |name, args, _| "#{name}(#{args.join(' ')})" }.join('.')]
     end
 
     TimeCalc::MATH_OPERATIONS.each do |name|
-      define_method(name) { |*args| Op.new([*@chain, [name, *args]]) }
+      define_method(name) { |*args, &block| Op.new([*@chain, [name, args, block].compact]) }
     end
 
     # @!method +(span, unit)
     #   Adds `+(span, unit)` to method chain
     #   @see TimeCalc#+
     #   @return [Op]
+    # @!method iterate(span, unit, &block)
+    #   Adds `iterate(span, unit, &block)` to method chain
+    #   @see TimeCalc#iterate
+    #   @return [Op]
     # @!method -(span, unit)
     #   Adds `-(span, unit)` to method chain
     #   @see TimeCalc#-
@@ -55,8 +59,8 @@ class TimeCalc
     # @param date_or_time [Date, Time, DateTime]
     # @return [Date, Time, DateTime] Type of the result is always the same as type of the parameter
     def call(date_or_time)
-      @chain.reduce(Value.new(date_or_time)) { |val, (name, *args)|
-        val.public_send(name, *args)
+      @chain.reduce(Value.new(date_or_time)) { |val, (name, args, block)|
+        val.public_send(name, *args, &block)
       }.unwrap
     end
 

data/lib/time_calc/value.rb

@@ -7,6 +7,27 @@ require 'backports/2.6.0/kernel/then'
 require 'backports/2.5.0/hash/slice'
 require 'backports/2.5.0/enumerable/all'
 
+if RUBY_VERSION < '2.7'
+  # @private
+  # TODO: Replace with backports after 2.7 release
+  class Enumerator
+    NOVALUE = Object.new.freeze
+
+    def self.produce(initial = NOVALUE)
+      fail ArgumentError, 'No block given' unless block_given?
+
+      Enumerator.new do |y|
+        val = initial == NOVALUE ? yield() : initial
+
+        loop do
+          y << val
+          val = yield(val)
+        end
+      end
+    end
+  end
+end
+
 class TimeCalc
   # Wrapper (one can say "monad") around date/time value, allowing to perform several TimeCalc
   # operations in a chain.
@@ -99,7 +120,7 @@ class TimeCalc
         .drop_while { |u| u != unit }
         .drop(1)
         .then { |keys| Units::DEFAULTS.slice(*keys) }
-        .then(&method(:merge))
+        .then { |attrs| merge(**attrs) } # can't simplify to &method(:merge) due to 2.7 keyword param problem
     end
 
     alias floor truncate
@@ -163,6 +184,28 @@ class TimeCalc
       unit.nil? ? Diff.new(self, span_or_other) : self.+(-span_or_other, unit)
     end
 
+    # Like {#+}, but allows conditional skipping of some periods. Increases value by `unit`
+    # at least `span` times, on each iteration checking with block provided if this point
+    # matches desired period; if it is not, it is skipped without increasing iterations
+    # counter. Useful for "business date/time" algorithms.
+    #
+    # See {TimeCalc#iterate} for examples.
+    #
+    # @param span [Integer]
+    # @param unit [Symbol]
+    # @return [Value]
+    # @yield [Time/Date/DateTime] Object of wrapped class
+    # @yieldreturn [true, false] If this point in time is "suitable". If the falsey value is returned,
+    #    iteration is skipped without increasing the counter.
+    def iterate(span, unit)
+      block_given? or fail ArgumentError, 'No block given'
+      Integer === span or fail ArgumentError, 'Only integer spans are supported' # rubocop:disable Style/CaseEquality
+
+      Enumerator.produce(self) { |v| v.+((span <=> 0).nonzero? || 1, unit) }
+                .lazy.select { |v| yield(v.internal) }
+                .drop(span.abs).first
+    end
+
     # Produces {Sequence} from this value to `date_or_time`
     #
     # @param date_or_time [Date, Time, DateTime]

data/lib/time_calc/version.rb

@@ -2,5 +2,5 @@
 
 class TimeCalc
   # @private
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

data/lib/time_calc.rb

@@ -190,6 +190,37 @@ class TimeCalc
   #   @param unit [Symbol]
   #   @return [Date, Time, DateTime] value of the same type that was initial wrapped value.
 
+  # @!method iterate(span, unit)
+  #   Like {#+}, but allows conditional skipping of some periods. Increases value by `unit`
+  #   at least `span` times, on each iteration checking with block provided if this point
+  #   matches desired period; if it is not, it is skipped without increasing iterations
+  #   counter. Useful for "business date/time" algorithms.
+  #
+  #   @example
+  #      # add 10 working days.
+  #      TimeCalc.(Time.parse('2019-07-03 23:28:54')).iterate(10, :days) { |t| (1..5).cover?(t.wday) }
+  #      # => 2019-07-17 23:28:54 +0300
+  #
+  #      # add 12 working hours
+  #      TimeCalc.(Time.parse('2019-07-03 13:28:54')).iterate(12, :hours) { |t| (9...18).cover?(t.hour) }
+  #      # => 2019-07-04 16:28:54 +0300
+  #
+  #      # negative spans are working, too:
+  #      TimeCalc.(Time.parse('2019-07-03 13:28:54')).iterate(-12, :hours) { |t| (9...18).cover?(t.hour) }
+  #      # => 2019-07-02 10:28:54 +0300
+  #
+  #      # zero span could be used to robustly enforce value into acceptable range
+  #      # (increasing forward till block is true):
+  #      TimeCalc.(Time.parse('2019-07-03 23:28:54')).iterate(0, :hours) { |t| (9...18).cover?(t.hour) }
+  #      # => 2019-07-04 09:28:54 +0300
+  #
+  #   @param span [Integer] Could be positive or negative
+  #   @param unit [Symbol]
+  #   @return [Date, Time, DateTime] value of the same type that was initial wrapped value.
+  #   @yield [Time/Date/DateTime] Object of wrapped class
+  #   @yieldreturn [true, false] If this point in time is "suitable". If the falsey value is returned,
+  #    iteration is skipped without increasing the counter.
+
   # @!method -(span_or_other, unit=nil)
   #   @overload -(span, unit)
   #     Subtracts `span units` from wrapped value.
@@ -238,25 +269,39 @@ class TimeCalc
   #   @return [Sequence]
 
   # @private
-  MATH_OPERATIONS = %i[merge truncate floor ceil round + -].freeze
+  MATH_OPERATIONS = %i[merge truncate floor ceil round + - iterate].freeze
   # @private
   OPERATIONS = MATH_OPERATIONS.+(%i[to step for]).freeze
 
   OPERATIONS.each do |name|
-    define_method(name) { |*args|
-      @value.public_send(name, *args).then { |res| res.is_a?(Value) ? res.unwrap : res }
-    }
+    # https://bugs.ruby-lang.org/issues/16421 :shrug:
+    # FIXME: In fact, the only kwargs op seem to be merge(...). If the problem is unsolvable,
+    # it is easier to define it separately.
+    if RUBY_VERSION < '2.7'
+      define_method(name) { |*args, &block|
+        @value.public_send(name, *args, &block)
+              .then { |res| res.is_a?(Value) ? res.unwrap : res }
+      }
+    else
+      define_method(name) { |*args, **kwargs, &block|
+        @value.public_send(name, *args, **kwargs, &block)
+              .then { |res| res.is_a?(Value) ? res.unwrap : res }
+      }
+    end
   end
 
   class << self
     MATH_OPERATIONS.each do |name|
-      define_method(name) { |*args| Op.new([[name, *args]]) }
+      define_method(name) { |*args, &block| Op.new([[name, args, block].compact]) }
     end
 
     # @!parse
     #   # Creates operation to perform {#+}`(span, unit)`
     #   # @return [Op]
     #   def TimeCalc.+(span, unit); end
+    #   # Creates operation to perform {#iterate}`(span, unit, &block)`
+    #   # @return [Op]
+    #   def TimeCalc.iterate(span, unit, &block); end
     #   # Creates operation to perform {#-}`(span, unit)`
     #   # @return [Op]
     #   def TimeCalc.-(span, unit); end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: time_calc
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Victor Shepelev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-08 00:00:00.000000000 Z
+date: 2019-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: backports
@@ -30,28 +30,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.72.0
+        version: 0.77.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.72.0
+        version: 0.77.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.17.1
+        version: 1.37.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.17.1
+        version: 1.37.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.0.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.0.6
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -188,7 +188,12 @@ files:
 homepage: https://github.com/zverok/time_calc
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/zverok/time_calc/issues
+  changelog_uri: https://github.com/zverok/time_calc/blob/master/Changelog.md
+  documentation_uri: https://www.rubydoc.info/gems/time_calc/
+  homepage_uri: https://github.com/zverok/time_calc
+  source_code_uri: https://github.com/zverok/time_calc
 post_install_message: 
 rdoc_options: []
 require_paths: