Module: RiCal::OccurrenceEnumerator

Includes:
Enumerable
Included in:
Component::Event, Component::Journal, Component::Timezone::TimezonePeriod, Component::Todo
Defined in:
lib/ri_cal/occurrence_enumerator.rb

Overview

OccurrenceEnumerator provides common methods for CalendarComponents that support recurrence i.e. Event, Journal, Todo, and TimezonePeriod

Defined Under Namespace

Classes: EmptyRulesEnumerator, EnumerationInstance, OccurrenceMerger

Instance Method Summary collapse

Instance Method Details

#after_range?(overlap_range) ⇒ Boolean

Returns:

  • (Boolean) 


203
204
205
206
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 203

def after_range?(overlap_range)
  start = start_time
  !start || start > overlap_range.last
end

#before_range?(overlap_range) ⇒ Boolean

Returns:

  • (Boolean) 


198
199
200
201
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 198

def before_range?(overlap_range)
  finish = finish_time
  !finish_time || finish_time < overlap_range.first
end

#bounded? ⇒ Boolean

A predicate which determines whether the component has a bounded set of occurrences

Returns:

  • (Boolean) 


214
215
216
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 214

def bounded?
  enumeration_instance.bounded?
end

#default_duration ⇒ Object

:nodoc:



8
9
10
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 8

def default_duration # :nodoc:
  dtend && dtstart.to_ri_cal_date_time_value.duration_until(dtend.to_ri_cal_date_time_value)
end

#default_start_time ⇒ Object

:nodoc:



12
13
14
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 12

def default_start_time # :nodoc:
  dtstart && dtstart.to_ri_cal_date_time_value
end

#each(&block) ⇒ Object

execute the block for each occurrence



209
210
211
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 209

def each(&block) # :yields: Component
  enumeration_instance.each(&block)
end

#enumeration_instance ⇒ Object

TODO: Thread safe?



194
195
196
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 194

def enumeration_instance #:nodoc:
  EnumerationInstance.new(self)
end

#occurrences(options = {}) ⇒ Object

return an array of occurrences according to the options parameter. If a component is not bounded, and the number of occurrences to be returned is not constrained by either the :before, or :count options an ArgumentError will be raised.

The components returned will be the same type as the receiver, but will have any recurrence properties (rrule, rdate, exrule, exdate) removed since they are single occurrences, and will have the recurrence-id property set to the occurrences dtstart value. (see RFC 2445 sec 4.8.4.4 pp 107-109)

parameter options:

  • :starting

    a Date, Time, or DateTime, no occurrences starting before this argument will be returned

  • :before

    a Date, Time, or DateTime, no occurrences starting on or after this argument will be returned.

  • :count

    an integer which limits the number of occurrences returned.

  • :overlapping

    a two element array of Dates, Times, or DateTimes, assumed to be in chronological order. Only occurrences which are either totally or partially within the range will be returned.



189
190
191
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 189

def occurrences(options={})
  enumeration_instance.to_a(options)
end

#recurrence(occurrence) ⇒ Object

:nodoc:



253
254
255
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 253

def recurrence(occurrence) # :nodoc:
  result = self.dup.set_occurrence_properties!(occurrence)
end

#recurs? ⇒ Boolean

Returns:

  • (Boolean) 


257
258
259
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 257

def recurs?
  @rrule_property && @rrule_property.length > 0 || @rdate_property && @rdate_property.length > 0
end

#set_occurrence_properties!(occurrence) ⇒ Object

:nodoc:



237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 237

def set_occurrence_properties!(occurrence) # :nodoc:
  occurrence_end = occurrence.dtend
  occurrence_start = occurrence.dtstart
  @rrule_property = nil
  @exrule_property = nil
  @rdate_property = nil
  @exdate_property = nil
  @recurrence_id_property = occurrence_start
  if @dtend_property && !occurrence_end
     occurrence_end = occurrence_start + (@dtend_property - @dtstart_property)
  end
  @dtstart_property = @dtstart_property.for_occurrence(occurrence_start)
  @dtend_property = (@dtend_property || @dtstart_property).for_occurrence(occurrence_end) if occurrence_end
  self
end

#zulu_occurrence_range ⇒ Object

Return a array whose first element is a UTC DateTime representing the start of the first occurrence, and whose second element is a UTC DateTime representing the end of the last occurrence. If the receiver is not bounded then the second element will be nil.

The purpose of this method is to provide values which may be used as database attributes so that a query can find all occurence enumerating components which may have occurrences within a range of times.



226
227
228
229
230
231
232
233
234
235
 
# File 'lib/ri_cal/occurrence_enumerator.rb', line 226

def zulu_occurrence_range
  if bounded?
    all = occurrences
    first, last = all.first, all.last
  else
    first = occurrences(:count => 1).first
    last = nil
  end
  [first.zulu_occurrence_range_start_time, last ? last.zulu_occurrence_range_finish_time : nil]
end