Document Fugit::Cron#next, #prev and #within

jmettraux/rufus-scheduler#325

README.md

@@ -135,6 +135,39 @@ p c.previous_time(Time.parse('2024-06-01')).to_s
     #
     # `Fugit::Cron#next_time` and `#previous_time` accept a "start time"
 
+c = Fugit.parse_cron('0 12 * * mon#2')
+
+  # `#next` and `#prev` return Enumerable instances
+  #
+c.next(Time.parse('2024-02-16 12:00:00'))
+  .take(5)
+  .map(&:to_s)
+    # => [ '2024-03-11 12:00:00',
+    #      '2024-04-08 12:00:00',
+    #      '2024-05-13 12:00:00',
+    #      '2024-06-10 12:00:00',
+    #      '2024-07-08 12:00:00' ]
+c.prev(Time.parse('2024-02-16 12:00:00'))
+  .take(5)
+  .map(&:to_s)
+    # => [ '2024-02-12 12:00:00',
+    #      '2024-01-08 12:00:00',
+    #      '2023-12-11 12:00:00',
+    #      '2023-11-13 12:00:00',
+    #      '2023-10-09 12:00:00' ]
+
+  # `#within` accepts a time range and returns an array of Eo::EoTime
+  # instances that correspond to the occurrences of the cron within
+  # the time range
+  #
+c.within(Time.parse('2024-02-16 12:00')..Time.parse('2024-08-01 12:00'))
+  .map(&:to_s)
+    # => [ '2024-03-11 12:00:00',
+    #      '2024-04-08 12:00:00',
+    #      '2024-05-13 12:00:00',
+    #      '2024-06-10 12:00:00',
+    #      '2024-07-08 12:00:00' ]
+
 p c.brute_frequency  # => [ 604800, 604800, 53 ]
                      #    [ delta min, delta max, occurrence count ]
 p c.rough_frequency  # => 7 * 24 * 3600 (7d rough frequency)

lib/fugit/cron.rb

@@ -335,16 +335,25 @@ def each
       end
     end
 
+    # Returns an ::Enumerable instance that yields each "next time" in
+    # succession
+    #
     def next(from=::EtOrbi::EoTime.now)
 
       CronIterator.new(self, :next_time, from)
     end
 
+    # Returns an ::Enumerable instance that yields each "previous time" in
+    # succession
+    #
     def prev(from=::EtOrbi::EoTime.now)
 
       CronIterator.new(self, :previous_time, from)
     end
 
+    # Returns an array of EtOrbi::EoTime instances that correspond to
+    # the occurrences of the cron within the given time range
+    #
     def within(time_range)
 
       CronIterator