Add TimeCalc#iterate

Author: zverok

lib/time_calc.rb

@@ -190,6 +190,37 @@ def ==(other)
   #   @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 change 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,28 @@ def ==(other)
   #   @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 }
+    define_method(name) { |*args, &block|
+      @value.public_send(name, *args, &block).then { |res| res.is_a?(Value) ? res.unwrap : res }
     }
   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]]) }
     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

lib/time_calc/op.rb

@@ -22,17 +22,21 @@ def initialize(chain = [])
 
     # @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]]) }
     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 @@ def inspect
     # @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
 

lib/time_calc/value.rb

@@ -7,6 +7,25 @@
 require 'backports/2.5.0/hash/slice'
 require 'backports/2.5.0/enumerable/all'
 
+# @private
+# TODO: It is included in Ruby 2.7. Replace with backports when it will be there.
+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
+
 class TimeCalc
   # Wrapper (one can say "monad") around date/time value, allowing to perform several TimeCalc
   # operations in a chain.
@@ -163,6 +182,28 @@ def -(span_or_other, unit = nil)
       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]

lib/time_calc/version.rb

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

spec/time_calc/value_spec.rb

@@ -132,6 +132,52 @@ def obj.to_time
       }
     end
 
+    describe '#iterate' do
+      context 'without additional conditions' do
+        subject { value.iterate(10, :days) }
+
+        its_block { is_expected.to raise_error ArgumentError, 'No block given' }
+      end
+
+      context 'without trivial condition' do
+        subject { value.iterate(10, :days) { true } }
+
+        it { is_expected.to eq value.+(10, :days) }
+      end
+
+      context 'with condition' do
+        subject { value.iterate(10, :days) { |t| (1..5).cover?(t.wday) } }
+
+        it { is_expected.to eq value.+(14, :days) }
+      end
+
+      context 'with negative span' do
+        subject { value.iterate(-10, :days) { true } }
+
+        it { is_expected.to eq value.-(10, :days) }
+      end
+
+      context 'with zero span' do
+        context 'when no changes necessary' do
+          subject { value.iterate(0, :days) { true } }
+
+          it { is_expected.to eq value }
+        end
+
+        context 'when changes necessary' do
+          subject { value.iterate(0, :days) { |t| t.day < 20 } }
+
+          it { is_expected.to eq vt('2019-07-01 14:28:48.123 +03') }
+        end
+      end
+
+      context 'with non-integer span' do
+        subject { value.iterate(10.5, :days) { true } }
+
+        its_block { is_expected.to raise_error ArgumentError }
+      end
+    end
+
     if RUBY_VERSION >= '2.6'
       require 'tzinfo'
       context 'with real time zones' do

time_calc.gemspec

@@ -34,7 +34,7 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency 'rspec', '>= 3.8'
   s.add_development_dependency 'rspec-its', '~> 1'
-  s.add_development_dependency 'saharspec'
+  s.add_development_dependency 'saharspec', '>= 0.0.6'
   s.add_development_dependency 'simplecov', '~> 0.9'
   s.add_development_dependency 'tzinfo'