Changing spans param to options hash

Swapping the new spans parameter for an options hash to make the method calls more specific in their meaning.

Author: jopotts

README.md

@@ -77,15 +77,17 @@ 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.next_occurrences(3, from_time, true) # include prior occurrences with duration overlapping from_time
-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.remaining_occurrences          # for terminating schedules
 
 # or the previous occurrence
 schedule.previous_occurrence(from_time)
 schedule.previous_occurrences(3, from_time)
 
+# or include prior occurrences with a duration overlapping from_time
+schedule.next_occurrences(3, from_time, :spans => true)
+schedule.occurrences_between(from_time, to_time, :spans => true)
 
 # or give the schedule a duration and ask if occurring_at?
 schedule = IceCube::Schedule.new(now, :duration => 3600)

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, spans = false)
+    def next_occurrences(num, from = nil, options = {})
       from = TimeUtil.match_zone(from, start_time) || TimeUtil.now(start_time)
-      enumerate_occurrences(from + 1, nil, spans).take(num)
+      enumerate_occurrences(from + 1, nil, options).take(num)
     end
 
     # The next occurrence after now (overridable)
-    def next_occurrence(from = nil, spans = false)
+    def next_occurrence(from = nil, options = {})
       from = TimeUtil.match_zone(from, start_time) || TimeUtil.now(start_time)
-      enumerate_occurrences(from + 1, nil, spans).next
+      enumerate_occurrences(from + 1, nil, options).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, spans = false)
+    def remaining_occurrences(from = nil, options = {})
       require_terminating_rules
       from ||= TimeUtil.now(@start_time)
-      enumerate_occurrences(from, nil, spans).to_a
+      enumerate_occurrences(from, nil, options).to_a
     end
 
     # Returns an enumerator for all remaining occurrences
-    def remaining_occurrences_enumerator(from = nil, spans = false)
+    def remaining_occurrences_enumerator(from = nil, options = {})
       from ||= TimeUtil.now(@start_time)
-      enumerate_occurrences(from, nil, spans)
+      enumerate_occurrences(from, nil, options)
     end
 
     # Occurrences between two times
-    def occurrences_between(begin_time, closing_time, spans = false)
-      enumerate_occurrences(begin_time, closing_time, spans).to_a
+    def occurrences_between(begin_time, closing_time, options = {})
+      enumerate_occurrences(begin_time, closing_time, options).to_a
     end
 
     # Return a boolean indicating if an occurrence falls between two times
-    def occurs_between?(begin_time, closing_time, spans = false)
-      enumerate_occurrences(begin_time, closing_time, spans).next
+    def occurs_between?(begin_time, closing_time, options = {})
+      enumerate_occurrences(begin_time, closing_time, options).next
       true
     rescue StopIteration
       false
@@ -226,7 +226,7 @@ def occurs_between?(begin_time, closing_time, spans = false)
     # occurrences at the end of the range since none of their duration
     # intersects the range.
     def occurring_between?(opening_time, closing_time)
-      occurs_between?(opening_time, closing_time, true)
+      occurs_between?(opening_time, closing_time, :spans => true)
     end
 
     # Return a boolean indicating if an occurrence falls on a certain date
@@ -402,12 +402,12 @@ 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, spans = false, &block)
+    def enumerate_occurrences(opening_time, closing_time = nil, options = {}, &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
-      spans = false if duration == 0
+      spans = options[:spans] == true && duration != 0
       Enumerator.new do |yielder|
         reset
         t1 = full_required? ? start_time : realign((spans ? opening_time - duration : opening_time))

spec/examples/schedule_spec.rb

@@ -458,52 +458,52 @@
       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 = schedule.next_occurrence(t0 + IceCube::ONE_HOUR, :spans => 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 = schedule.next_occurrences(10, t0 + IceCube::ONE_HOUR, :spans => 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 = schedule.remaining_occurrences(t0 + IceCube::ONE_DAY + IceCube::ONE_HOUR, :spans => 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 = schedule.remaining_occurrences_enumerator(t0 + IceCube::ONE_DAY, :spans => 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 = schedule.occurrences_between(t0 + IceCube::ONE_HOUR + 1, t0 + 3 * IceCube::ONE_HOUR + 1, :spans => 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 = schedule.occurrences_between(t0 + IceCube::ONE_HOUR, t0 + IceCube::ONE_DAY - IceCube::ONE_HOUR, :spans => true)
       occs.should == [t0]
     end
 
     it 'should not find occurrence with duration ending on start time' 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_false
+      schedule.occurs_between?(t0 + IceCube::ONE_HOUR, t0 + 2 * IceCube::ONE_HOUR, :spans => true).should be_false
     end
 
     it 'should quickly fetch a future time from a recurring schedule' do
@@ -513,7 +513,7 @@
       schedule.add_recurrence_rule IceCube::Rule.hourly
       occ = nil
       timing = Benchmark.realtime do
-        occ = schedule.remaining_occurrences_enumerator(t1, true).take(1)
+        occ = schedule.remaining_occurrences_enumerator(t1, :spans => true).take(1)
       end
       timing.should < 0.1
       occ.should == [t1]
@@ -523,7 +523,7 @@
       t0 = Time.utc(2015, 10, 1, 10, 00)
       schedule = IceCube::Schedule.new(t0, :duration => IceCube::ONE_HOUR / 2)
       schedule.add_recurrence_rule IceCube::Rule.minutely(30).count(6)
-      third_occ = schedule.next_occurrence(t0 + IceCube::ONE_HOUR, true)
+      third_occ = schedule.next_occurrence(t0 + IceCube::ONE_HOUR, :spans => true)
       third_occ.should == t0 + IceCube::ONE_HOUR
     end