Add schedule.last(n) method

Fixes #117

README.md

@@ -74,6 +74,10 @@ schedule.occurs_between?(now + 3.days, now + 30.days) # false
 schedule.first(2) # [now, now + 2.days]
 schedule.first # now
 
+# or the last (n) occurrences (if the schedule terminates)
+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

lib/ice_cube/schedule.rb

@@ -268,6 +268,14 @@ def first(n = nil)
       n.nil? ? occurrences.first : occurrences
     end
 
+    # Get the final n occurrences of a terminating schedule
+    # or the final one if no n is given
+    def last(n = nil)
+      require_terminating_rules
+      occurrences = find_occurrences(start_time, nil, nil, n || 1)
+      n.nil? ? occurrences.last : occurrences[-n..-1]
+    end
+
     # String serialization
     def to_s
       pieces = []
@@ -371,7 +379,7 @@ def reset
 
     # Find all of the occurrences for the schedule between opening_time
     # and closing_time
-    def find_occurrences(opening_time, closing_time = nil, limit = nil, &block)
+    def find_occurrences(opening_time, closing_time = nil, limit = nil, tail_limit = nil, &block)
       opening_time = TimeUtil.ensure_time opening_time
       closing_time = TimeUtil.ensure_time closing_time
       opening_time += start_time.subsec - opening_time.subsec rescue 0
@@ -388,6 +396,7 @@ def find_occurrences(opening_time, closing_time = nil, limit = nil, &block)
         break if closing_time && res > closing_time
         if res >= opening_time
           block_given? ? block.call(res) : (answers << res)
+          answers.shift if tail_limit && answers.length > tail_limit
           break if limit && answers.length == limit
         end
         time = res + 1

spec/examples/schedule_spec.rb

@@ -394,6 +394,32 @@
     end
   end
 
+  describe :last do
+
+    it 'returns the last occurrence for a terminating schedule' do
+      t0 = Time.utc(2013, 5, 18, 12, 34)
+      t1 = Time.utc(2013, 5, 31, 12, 34)
+      schedule = IceCube::Schedule.new(t0)
+      schedule.add_recurrence_rule IceCube::Rule.daily.until(t1 + 1)
+      schedule.last.should == t1
+    end
+
+    it 'returns an array of occurrences given a number' do
+      t0 = Time.utc(2013, 5, 18, 12, 34)
+      t1 = Time.utc(2013, 5, 31, 12, 34)
+      schedule = IceCube::Schedule.new(t0)
+      schedule.add_recurrence_rule IceCube::Rule.daily.until(t1 + 1)
+      schedule.last(2).should == [t1 - ONE_DAY, t1]
+    end
+
+    it 'raises an error for a non-terminating schedule' do
+      schedule = IceCube::Schedule.new
+      schedule.add_recurrence_rule IceCube::Rule.daily
+      expect { schedule.last }.to raise_error
+    end
+
+  end
+
   describe :start_date= do
 
     it 'should modify start date in rrule_occurrence_heads when changed' do