Class: RiCal::PropertyValue::DateTime

Inherits:
RiCal::PropertyValue show all
Includes:
Comparable, AdditiveMethods, TimeMachine, TimezoneSupport
Defined in:
lib/ri_cal/property_value/date_time.rb,
lib/ri_cal/property_value/date_time/time_machine.rb,
lib/ri_cal/property_value/date_time/additive_methods.rb,
lib/ri_cal/property_value/date_time/timezone_support.rb

Overview

  • ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license

RiCal::PropertyValue::CalAddress represents an icalendar CalAddress property value which is defined in RFC 2445 section 4.3.5 pp 35-37

Direct Known Subclasses

ZuluDateTime

Defined Under Namespace

Modules: AdditiveMethods, TimeMachine, TimezoneSupport

Instance Attribute Summary

Attributes inherited from RiCal::PropertyValue

#timezone_finder

Class Method Summary collapse

Instance Method Summary collapse

Methods included from TimeMachine

#advance, #at_end_of_iso_year, #at_start_of_iso_year, #at_start_of_next_iso_year, #at_start_of_week_with_wkst, #change, #change_day, #change_hour, #change_min, #change_month, #change_sec, #change_year, #end_of_day, #end_of_hour, #end_of_iso_year, #end_of_minute, #end_of_month, #end_of_week_with_wkst, #end_of_year, #in_month, #in_week_starting?, #start_of_day, #start_of_hour, #start_of_minute, #start_of_month, #start_of_week_with_wkst, #start_of_year

Methods included from TimezoneSupport

#find_timezone, #floating?, #has_local_timezone?, #has_valid_tzinfo_tzid?, #in_time_zone, #rational_tz_offset, #reset_cached_values, #timezone, #tzid, #tzid=, #utc, #utc?, #with_floating_timezone

Methods included from AdditiveMethods

#+, #-, #add_to_date_time_value, #duration_until, #subtract_from_date_time_value

Methods inherited from RiCal::PropertyValue

date_or_date_time, date_or_date_time_or_period, #default_tzid, #enumerator, #equality_value, #find_timezone, if_valid_string, #initialize, #parms_string, #to_options_hash, #to_ri_cal_property_value, #to_s, #tz_info_source?, #validate_value

Constructor Details

This class inherits a constructor from RiCal::PropertyValue

Class Method Details

.civil(year, month, day, hour, min, sec, offset, start, params) ⇒ Object

:nodoc:



215
216
217
218
219
220
 
# File 'lib/ri_cal/property_value/date_time.rb', line 215

def self.civil(year, month, day, hour, min, sec, offset, start, params) #:nodoc:
  PropertyValue::DateTime.new(
     :value => ::DateTime.civil(year, month, day, hour, min, sec, offset, start),
     :params =>(params ? params.dup : nil)
  )
end

.convert(timezone_finder, ruby_object) ⇒ Object

:nodoc:



131
132
133
 
# File 'lib/ri_cal/property_value/date_time.rb', line 131

def self.convert(timezone_finder, ruby_object) # :nodoc:
    ruby_object.to_ri_cal_date_or_date_time_value(timezone_finder)
end

.default_tzid ⇒ Object

:nodoc:



31
32
33
 
# File 'lib/ri_cal/property_value/date_time.rb', line 31

def self.default_tzid # :nodoc:
  @default_tzid ||= "UTC"
end

.default_tzid=(tzid) ⇒ Object

Set the default tzid to be used when instantiating an instance from a ruby object see RiCal::PropertyValue::DateTime.from_time

The parameter tzid is a string value to be used for the default tzid, a value of :floating will cause values with NO timezone to be produced, which will be interpreted by iCalendar as floating times i.e. they are interpreted in the timezone of each client. Floating times are typically used to represent events which are ‘repeated’ in the various time zones, like the first hour of the year.



50
51
52
 
# File 'lib/ri_cal/property_value/date_time.rb', line 50

def self.default_tzid=(tzid)
  @default_tzid = tzid
end

.default_tzid_hash ⇒ Object

:nodoc:



54
55
56
57
58
59
60
 
# File 'lib/ri_cal/property_value/date_time.rb', line 54

def self.default_tzid_hash # :nodoc:
  if default_tzid.to_s == 'none'
    {}
  else
    {'TZID' => default_tzid}
  end
end

.from_string(string) ⇒ Object

:nodoc:



135
136
137
138
139
140
141
 
# File 'lib/ri_cal/property_value/date_time.rb', line 135

def self.from_string(string) # :nodoc:
  if string.match(/Z$/)
    new(nil, :value => string, :tzid => 'UTC')
  else
    new(nil, :value => string)
  end
end

.or_date(parent, line) ⇒ Object

:nodoc:



19
20
21
22
23
24
25
 
# File 'lib/ri_cal/property_value/date_time.rb', line 19

def self.or_date(parent, line) # :nodoc:
  if /T/.match(line[:value] || "")
    new(parent, line)
  else
    PropertyValue::Date.new(parent, line)
  end
end

.params_for_tzid(tzid) ⇒ Object

:nodoc:



35
36
37
38
39
40
41
 
# File 'lib/ri_cal/property_value/date_time.rb', line 35

def self.params_for_tzid(tzid) #:nodoc:
  if tzid == :floating
    {}
  else
    {'TZID' => tzid}
  end
end

.time_and_parameters(object) ⇒ Object

Extract the time and timezone identifier from an object used to set the value of a DATETIME property.

If the object is a string it should be of the form [TZID=identifier:]

Otherwise determine if the object acts like an activesupport enhanced time, and extract its timezone idenfifier if it has one.



119
120
121
122
123
124
125
126
127
128
 
# File 'lib/ri_cal/property_value/date_time.rb', line 119

def self.time_and_parameters(object)
  parameters = {}
  if ::String === object
    object, parameters = self.time_and_parameters_from_string(object)
  else
    identifier = object.tzid rescue nil
    parameters["TZID"] = identifier if identifier
  end
  [object, parameters]
end

.valid_string?(string) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


27
28
29
 
# File 'lib/ri_cal/property_value/date_time.rb', line 27

def self.valid_string?(string) #:nodoc:
  string =~ /^\d{8}T\d{6}Z?$/
end

Instance Method Details

#<=>(other) ⇒ Object

Compare the receiver with another object which must respond to the to_datetime message The comparison is done using the Ruby DateTime representations of the two objects



185
186
187
 
# File 'lib/ri_cal/property_value/date_time.rb', line 185

def <=>(other)
 other.cmp_fast_date_time_value(@date_time_value)
end

#==(other) ⇒ Object

Determine if the receiver and another object are equivalent RiCal::PropertyValue::DateTime instances



228
229
230
231
232
233
234
 
# File 'lib/ri_cal/property_value/date_time.rb', line 228

def ==(other)
  if self.class === other
    self.value == other.value && self.visible_params == other.visible_params && self.tzid == other.tzid
  else
    super
  end
end

#add_date_times_to(required_timezones) ⇒ Object

:nodoc:



346
347
348
 
# File 'lib/ri_cal/property_value/date_time.rb', line 346

def add_date_times_to(required_timezones) #:nodoc:
  required_timezones.add_datetime(self, tzid) if has_local_timezone?
end

#cmp_fast_date_time_value(other) ⇒ Object 



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

def cmp_fast_date_time_value(other)
  other <=> @date_time_value
end

#day ⇒ Object Also known as: mday

Return the day of the month



252
253
254
 
# File 'lib/ri_cal/property_value/date_time.rb', line 252

def day
  @date_time_value.day
end

#days_in_month ⇒ Object

Return the number of days in the month containing the receiver



223
224
225
 
# File 'lib/ri_cal/property_value/date_time.rb', line 223

def days_in_month
  @date_time_value.days_in_month
end

#fast_date_tme ⇒ Object

:nodoc:



79
80
81
 
# File 'lib/ri_cal/property_value/date_time.rb', line 79

def fast_date_tme # :nodoc:
  @date_time_value
end

#for_occurrence(occurrence) ⇒ Object 



354
355
356
 
# File 'lib/ri_cal/property_value/date_time.rb', line 354

def for_occurrence(occurrence)
  occurrence.to_ri_cal_date_time_value(timezone_finder)
end

#for_parent(parent) ⇒ Object

:nodoc:



143
144
145
146
147
148
149
150
151
152
 
# File 'lib/ri_cal/property_value/date_time.rb', line 143

def for_parent(parent) #:nodoc:
  if timezone_finder.nil?
    @timezone_finder = parent
    self
  elsif parent == timezone_finder
    self
  else
    DateTime.new(parent, :value => @date_time_value, :params => params, :tzid => tzid)
  end
end

#hour ⇒ Object

Return the hour



264
265
266
 
# File 'lib/ri_cal/property_value/date_time.rb', line 264

def hour
  @date_time_value.hour
end

#in_same_month_as?(other) ⇒ Boolean

Determine if the receiver and other are in the same month

Returns:

  • (Boolean) 


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

def in_same_month_as?(other)
  [other.year, other.month] == [year, month]
end

#inspect ⇒ Object

:nodoc:



62
63
64
 
# File 'lib/ri_cal/property_value/date_time.rb', line 62

def inspect # :nodoc:
  "#{@date_time_value}:#{tzid}"
end

#iso_weeks_in_year(wkst) ⇒ Object

:nodoc:



288
289
290
 
# File 'lib/ri_cal/property_value/date_time.rb', line 288

def iso_weeks_in_year(wkst) #:nodoc:
  @date_time_value.iso_weeks_in_year(wkst) #:nodoc:
end

#iso_year_and_week_one_start(wkst) ⇒ Object

:nodoc:



284
285
286
 
# File 'lib/ri_cal/property_value/date_time.rb', line 284

def iso_year_and_week_one_start(wkst) #:nodoc:
  @date_time_value.iso_year_and_week_one_start(wkst)
end

#min ⇒ Object

Return the minute



269
270
271
 
# File 'lib/ri_cal/property_value/date_time.rb', line 269

def min
  @date_time_value.min
end

#month ⇒ Object

Return the month of the year (1..12)



247
248
249
 
# File 'lib/ri_cal/property_value/date_time.rb', line 247

def month
  @date_time_value.month
end

#nth_wday_in_month(n, which_wday) ⇒ Object

:nodoc:



207
208
209
 
# File 'lib/ri_cal/property_value/date_time.rb', line 207

def nth_wday_in_month(n, which_wday) #:nodoc:
  with_date_time_value(@date_time_value.nth_wday_in_month(n, which_wday))
end

#nth_wday_in_year(n, which_wday) ⇒ Object

:nodoc:



211
212
213
 
# File 'lib/ri_cal/property_value/date_time.rb', line 211

def nth_wday_in_year(n, which_wday) #:nodoc:
  with_date_time_value(@date_time_value.nth_wday_in_year(n, which_wday))
end

#occurrence_period(default_duration) ⇒ Object

TODO: consider if this should be a period rather than a hash



237
238
239
 
# File 'lib/ri_cal/property_value/date_time.rb', line 237

def occurrence_period(default_duration) # :nodoc:
  RiCal::OccurrencePeriod.new(self, (default_duration ? self + default_duration : nil))
end

#params ⇒ Object

Return a Hash representing this properties parameters



172
173
174
175
176
177
178
179
180
181
 
# File 'lib/ri_cal/property_value/date_time.rb', line 172

def params
  result = @params.dup
  case tzid
  when :floating, nil, "UTC"
    result.delete('TZID')
  else
    result['TZID'] = tzid
  end
  result
end

#params=(value) ⇒ Object

:nodoc:



164
165
166
167
168
169
 
# File 'lib/ri_cal/property_value/date_time.rb', line 164

def params=(value) #:nodoc:
  @params = value.dup
  if params_timezone = @params['TZID']
    self.tzid =  @params['TZID']
  end
end

#ruby_value ⇒ Object Also known as: to_finish_time

Returns a ruby DateTime object representing the receiver.



308
309
310
311
312
313
314
 
# File 'lib/ri_cal/property_value/date_time.rb', line 308

def ruby_value
  if has_valid_tzinfo_tzid? && RiCal::TimeWithZone && tz_info_source?
    RiCal::TimeWithZone.new(utc.to_datetime, ::Time.__send__(:get_zone, @tzid))
  else
    ::DateTime.civil(year, month, day, hour, min, sec, rational_tz_offset).set_tzid(@tzid)
  end
end

#sec ⇒ Object

Return the second



274
275
276
 
# File 'lib/ri_cal/property_value/date_time.rb', line 274

def sec
  @date_time_value.sec
end

#start_of_day? ⇒ Boolean

Returns:

  • (Boolean) 


350
351
352
 
# File 'lib/ri_cal/property_value/date_time.rb', line 350

def start_of_day?
  [hour, min, sec] == [0,0,0]
end

#to_datetime ⇒ Object Also known as: to_ri_cal_ruby_value

Return the Ruby DateTime representation of the receiver



303
304
305
 
# File 'lib/ri_cal/property_value/date_time.rb', line 303

def to_datetime #:nodoc:
  @date_time_value.to_datetime
end

#to_ri_cal_date_or_date_time_value(timezone_finder = nil) ⇒ Object

Return the “Natural’ property value for the receover, in this case the receiver itself.”



293
294
295
 
# File 'lib/ri_cal/property_value/date_time.rb', line 293

def to_ri_cal_date_or_date_time_value(timezone_finder = nil) #:nodoc:
  self.for_parent(timezone_finder)
end

#to_ri_cal_date_time_value(timezone = nil) ⇒ Object

Return an RiCal::PropertyValue::DateTime representing the receiver.



280
281
282
 
# File 'lib/ri_cal/property_value/date_time.rb', line 280

def to_ri_cal_date_time_value(timezone=nil)
  for_parent(timezone)
end

#to_ri_cal_date_value(timezone_finder = nil) ⇒ Object

Return a Date property for this DateTime



298
299
300
 
# File 'lib/ri_cal/property_value/date_time.rb', line 298

def to_ri_cal_date_value(timezone_finder=nil)
  PropertyValue::Date.new(timezone_finder, :value => @date_time_value.ical_date_str)
end

#to_ri_cal_zulu_date_time ⇒ Object 



75
76
77
 
# File 'lib/ri_cal/property_value/date_time.rb', line 75

def to_ri_cal_zulu_date_time
  ZuluDateTime.new(nil, :value => self.utc.fast_date_tme)
end

#to_zulu_occurrence_range_finish_time ⇒ Object

If a time is floating, then the utc of it’s start time may actually be as early as 12 hours later if the occurrence is being viewed in a time zone just east of the International Date Line



338
339
340
341
342
343
344
 
# File 'lib/ri_cal/property_value/date_time.rb', line 338

def to_zulu_occurrence_range_finish_time
  if floating?
    utc.advance(:hours => 12).to_datetime
  else
    to_zulu_time
  end
end

#to_zulu_occurrence_range_start_time ⇒ Object

If a time is floating, then the utc of it’s start time may actually be as early as 12 hours earlier if the occurrence is being viewed in a time zone just west of the International Date Line



326
327
328
329
330
331
332
 
# File 'lib/ri_cal/property_value/date_time.rb', line 326

def to_zulu_occurrence_range_start_time
  if floating?
    @date_time_value.advance(:hours => -12, :offset => 0).to_datetime
  else
    to_zulu_time
  end
end

#to_zulu_time ⇒ Object 



319
320
321
 
# File 'lib/ri_cal/property_value/date_time.rb', line 319

def to_zulu_time
  utc.to_datetime
end

#value ⇒ Object

Returns the value of the receiver as an RFC 2445 iCalendar string



67
68
69
70
71
72
73
 
# File 'lib/ri_cal/property_value/date_time.rb', line 67

def value
  if @date_time_value
    "#{@date_time_value.ical_str}#{tzid == "UTC" ? "Z" : ""}"
  else
    nil
  end
end

#value=(val) ⇒ Object

Set the value of the property to val

val may be either:

  • A string which can be parsed as a DateTime

  • A Time instance

  • A Date instance

  • A DateTime instance



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/ri_cal/property_value/date_time.rb', line 91

def value=(val) # :nodoc:
  case val
  when nil
    @date_time_value = nil
  when String
    @date_time_value = FastDateTime.from_date_time(::DateTime.parse(val))
    if val =~/Z/
      self.tzid = 'UTC'
    else
      @tzid ||= :floating
    end
  when FastDateTime
    @date_time_value = val
  when ::DateTime
    @date_time_value = FastDateTime.from_date_time(val)
  when ::Date, ::Time
    @date_time_value = FastDateTime.from_date_time(::DateTime.parse(val.to_s))
  end
  reset_cached_values
end

#visible_params ⇒ Object

:nodoc:



154
155
156
157
158
159
160
161
162
 
# File 'lib/ri_cal/property_value/date_time.rb', line 154

def visible_params # :nodoc:
  result = {"VALUE" => "DATE-TIME"}.merge(params)
  if has_local_timezone?
    result['TZID'] = tzid
  else
    result.delete('TZID')
  end
  result
end

#wday ⇒ Object

Return the day of the week



259
260
261
 
# File 'lib/ri_cal/property_value/date_time.rb', line 259

def wday
  @date_time_value.wday
end

#with_date_time_value(date_time_value) ⇒ Object 



198
199
200
201
202
203
204
205
 
# File 'lib/ri_cal/property_value/date_time.rb', line 198

def with_date_time_value(date_time_value)
  PropertyValue::DateTime.new(
    timezone_finder,
    :value => date_time_value,
    :params => (params),
    :tzid => tzid
  )
end

#year ⇒ Object

Return the year (including the century)



242
243
244
 
# File 'lib/ri_cal/property_value/date_time.rb', line 242

def year
  @date_time_value.year
end