Option to include prior occurrences with overlapping duration

Adding an option on schedule methods to include occurrences whose duration intersects a time window. Issue #154

#154

Author: jopotts

README.md

@@ -77,9 +77,10 @@ schedule.last(2) # [now + 1.day, now + 2.days]
 schedule.last    # now + 2.days
 
 # or the next occurrence
-schedule.next_occurrence(from_time)     # defaults to Time.now
-schedule.next_occurrences(3, from_time) # defaults to Time.now
-schedule.remaining_occurrences          # for terminating schedules
+schedule.next_occurrence(from_time)           # defaults to Time.now
+schedule.next_occurrences(3, from_time)       # defaults to Time.now
+schedule.next_occurrences(3, from_time, true) # include prior occurrences with duration overlapping from_time
+schedule.remaining_occurrences                # for terminating schedules
 
 # or the previous occurrence
 schedule.previous_occurrence(from_time)

lib/ice_cube/schedule.rb

@@ -166,15 +166,15 @@ def each_occurrence(&block)
     end
 
     # The next n occurrences after now
-    def next_occurrences(num, from = nil)
+    def next_occurrences(num, from = nil, spans = false)
       from = TimeUtil.match_zone(from, start_time) || TimeUtil.now(start_time)
-      enumerate_occurrences(from + 1, nil).take(num)
+      enumerate_occurrences(from + 1, nil, spans).take(num)
     end
 
     # The next occurrence after now (overridable)
-    def next_occurrence(from = nil)
+    def next_occurrence(from = nil, spans = false)
       from = TimeUtil.match_zone(from, start_time) || TimeUtil.now(start_time)
-      enumerate_occurrences(from + 1, nil).next
+      enumerate_occurrences(from + 1, nil, spans).next
     rescue StopIteration
       nil
     end
@@ -195,26 +195,26 @@ def previous_occurrences(num, from)
     end
 
     # The remaining occurrences (same requirements as all_occurrences)
-    def remaining_occurrences(from = nil)
+    def remaining_occurrences(from = nil, spans = false)
       require_terminating_rules
       from ||= TimeUtil.now(@start_time)
-      enumerate_occurrences(from).to_a
+      enumerate_occurrences(from, nil, spans).to_a
     end
 
     # Returns an enumerator for all remaining occurrences
-    def remaining_occurrences_enumerator(from = nil)
+    def remaining_occurrences_enumerator(from = nil, spans = false)
       from ||= TimeUtil.now(@start_time)
-      enumerate_occurrences(from)
+      enumerate_occurrences(from, nil, spans)
     end
 
     # Occurrences between two times
-    def occurrences_between(begin_time, closing_time)
-      enumerate_occurrences(begin_time, closing_time).to_a
+    def occurrences_between(begin_time, closing_time, spans = false)
+      enumerate_occurrences(begin_time, closing_time, spans).to_a
     end
 
     # Return a boolean indicating if an occurrence falls between two times
-    def occurs_between?(begin_time, closing_time)
-      enumerate_occurrences(begin_time, closing_time).next
+    def occurs_between?(begin_time, closing_time, spans = false)
+      enumerate_occurrences(begin_time, closing_time, spans).next
       true
     rescue StopIteration
       false
@@ -404,25 +404,29 @@ def reset
     # Find all of the occurrences for the schedule between opening_time
     # and closing_time
     # Iteration is unrolled in pairs to skip duplicate times in end of DST
-    def enumerate_occurrences(opening_time, closing_time = nil, &block)
+    def enumerate_occurrences(opening_time, closing_time = nil, spans = false, &block)
       opening_time = TimeUtil.match_zone(opening_time, start_time)
       closing_time = TimeUtil.match_zone(closing_time, start_time)
       opening_time += start_time.subsec - opening_time.subsec rescue 0
       opening_time = start_time if opening_time < start_time
       Enumerator.new do |yielder|
         reset
-        t1 = full_required? ? start_time : realign(opening_time)
+        t1 = full_required? || spans ? start_time : realign(opening_time)
         loop do
           break unless (t0 = next_time(t1, closing_time))
           break if closing_time && t0 > closing_time
-          yielder << (block_given? ? block.call(t0) : t0) if t0 >= opening_time
+          if (spans ? t0.end_time : t0) >= opening_time
+            yielder << (block_given? ? block.call(t0) : t0)
+          end
           break unless (t1 = next_time(t0 + 1, closing_time))
           break if closing_time && t1 > closing_time
           if TimeUtil.same_clock?(t0, t1) && recurrence_rules.any?(&:dst_adjust?)
             wind_back_dst
             next (t1 += 1)
           end
-          yielder << (block_given? ? block.call(t1) : t1) if t1 >= opening_time
+          if (spans ? t1.end_time : t1) >= opening_time
+            yielder << (block_given? ? block.call(t1) : t1)
+          end
           next (t1 += 1)
         end
       end

spec/examples/schedule_spec.rb

@@ -451,6 +451,62 @@
 
   end
 
+  describe :spans do
+
+    it 'should find occurrence in past with duration beyond the start time' do
+      t0 = Time.utc(2015, 10, 1, 15, 31)
+      schedule = IceCube::Schedule.new(t0, :duration => 2 * IceCube::ONE_HOUR)
+      schedule.add_recurrence_rule IceCube::Rule.daily
+      next_occ = schedule.next_occurrence(t0 + IceCube::ONE_HOUR, true)
+      next_occ.should == t0
+    end
+
+    it 'should include occurrence in past with duration beyond the start time' do
+      t0 = Time.utc(2015, 10, 1, 15, 31)
+      schedule = IceCube::Schedule.new(t0, :duration => 2 * IceCube::ONE_HOUR)
+      schedule.add_recurrence_rule IceCube::Rule.daily.count(2)
+      occs = schedule.next_occurrences(10, t0 + IceCube::ONE_HOUR, true)
+      occs.should == [t0, t0 + IceCube::ONE_DAY]
+    end
+
+    it 'should allow duration span on remaining_occurrences' do
+      t0 = Time.utc(2015, 10, 1, 00, 00)
+      schedule = IceCube::Schedule.new(t0, :duration => IceCube::ONE_DAY)
+      schedule.add_recurrence_rule IceCube::Rule.daily.count(3)
+      occs = schedule.remaining_occurrences(t0 + IceCube::ONE_DAY + IceCube::ONE_HOUR, true)
+      occs.should == [t0 + IceCube::ONE_DAY, t0 + 2 * IceCube::ONE_DAY]
+    end
+
+    it 'should include occurrences with duration spanning the requested start time' do
+      t0 = Time.utc(2015, 10, 1, 15, 31)
+      schedule = IceCube::Schedule.new(t0, :duration => 30 * IceCube::ONE_DAY)
+      long_event = schedule.remaining_occurrences_enumerator(t0 + IceCube::ONE_DAY, true).take(1)
+      long_event.should == [t0]
+    end
+    
+    it 'should find occurrences between including previous one with duration spanning start' do
+      t0 = Time.utc(2015, 10, 1, 10, 00)
+      schedule = IceCube::Schedule.new(t0, :duration => IceCube::ONE_HOUR)
+      schedule.add_recurrence_rule IceCube::Rule.hourly.count(10)
+      occs = schedule.occurrences_between(t0 + IceCube::ONE_HOUR + 1, t0 + 3 * IceCube::ONE_HOUR + 1, true)
+      occs.length.should == 3
+    end
+
+    it 'should include long occurrences starting before and ending after' do
+      t0 = Time.utc(2015, 10, 1, 00, 00)
+      schedule = IceCube::Schedule.new(t0, :duration => IceCube::ONE_DAY)
+      occs = schedule.occurrences_between(t0 + IceCube::ONE_HOUR, t0 + IceCube::ONE_DAY - IceCube::ONE_HOUR, true)
+      occs.should == [t0]
+    end
+
+    it 'should include long occurrences starting before and ending after' do
+      t0 = Time.utc(2015, 10, 1, 12, 00)
+      schedule = IceCube::Schedule.new(t0, :duration => IceCube::ONE_HOUR)
+      schedule.occurs_between?(t0 + IceCube::ONE_HOUR, t0 + 2 * IceCube::ONE_HOUR, true).should be_true
+    end
+
+  end
+
   describe :previous_occurrence do
 
     it 'returns the previous occurrence for a time in the schedule' do