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

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:



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

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:



123
124
125
 
# File 'lib/ri_cal/property_value/date_time.rb', line 123

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:



127
128
129
130
131
132
133
 
# File 'lib/ri_cal/property_value/date_time.rb', line 127

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.



111
112
113
114
115
116
117
118
119
120
 
# File 'lib/ri_cal/property_value/date_time.rb', line 111

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



177
178
179
 
# File 'lib/ri_cal/property_value/date_time.rb', line 177

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



220
221
222
223
224
225
226
 
# File 'lib/ri_cal/property_value/date_time.rb', line 220

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:



338
339
340
 
# File 'lib/ri_cal/property_value/date_time.rb', line 338

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 



181
182
183
 
# File 'lib/ri_cal/property_value/date_time.rb', line 181

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

#day ⇒ Object Also known as: mday

Return the day of the month



244
245
246
 
# File 'lib/ri_cal/property_value/date_time.rb', line 244

def day
  @date_time_value.day
end

#days_in_month ⇒ Object

Return the number of days in the month containing the receiver



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

def days_in_month
  @date_time_value.days_in_month
end

#for_occurrence(occurrence) ⇒ Object 



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

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

#for_parent(parent) ⇒ Object

:nodoc:



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

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



256
257
258
 
# File 'lib/ri_cal/property_value/date_time.rb', line 256

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) 


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

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:



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

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:



276
277
278
 
# File 'lib/ri_cal/property_value/date_time.rb', line 276

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



261
262
263
 
# File 'lib/ri_cal/property_value/date_time.rb', line 261

def min
  @date_time_value.min
end

#month ⇒ Object

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



239
240
241
 
# File 'lib/ri_cal/property_value/date_time.rb', line 239

def month
  @date_time_value.month
end

#nth_wday_in_month(n, which_wday) ⇒ Object

:nodoc:



199
200
201
 
# File 'lib/ri_cal/property_value/date_time.rb', line 199

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:



203
204
205
 
# File 'lib/ri_cal/property_value/date_time.rb', line 203

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



229
230
231
 
# File 'lib/ri_cal/property_value/date_time.rb', line 229

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



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

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:



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

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.



300
301
302
303
304
305
306
 
# File 'lib/ri_cal/property_value/date_time.rb', line 300

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



266
267
268
 
# File 'lib/ri_cal/property_value/date_time.rb', line 266

def sec
  @date_time_value.sec
end

#start_of_day? ⇒ Boolean

Returns:

  • (Boolean) 


342
343
344
 
# File 'lib/ri_cal/property_value/date_time.rb', line 342

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



295
296
297
 
# File 'lib/ri_cal/property_value/date_time.rb', line 295

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.”



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

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.



272
273
274
 
# File 'lib/ri_cal/property_value/date_time.rb', line 272

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



290
291
292
 
# File 'lib/ri_cal/property_value/date_time.rb', line 290

def to_ri_cal_date_value(timezone_finder=nil)
  PropertyValue::Date.new(timezone_finder, :value => @date_time_value.ical_date_str)
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



330
331
332
333
334
335
336
 
# File 'lib/ri_cal/property_value/date_time.rb', line 330

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



318
319
320
321
322
323
324
 
# File 'lib/ri_cal/property_value/date_time.rb', line 318

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 



311
312
313
 
# File 'lib/ri_cal/property_value/date_time.rb', line 311

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



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/ri_cal/property_value/date_time.rb', line 83

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:



146
147
148
149
150
151
152
153
154
 
# File 'lib/ri_cal/property_value/date_time.rb', line 146

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



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

def wday
  @date_time_value.wday
end

#with_date_time_value(date_time_value) ⇒ Object 



190
191
192
193
194
195
196
197
 
# File 'lib/ri_cal/property_value/date_time.rb', line 190

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)



234
235
236
 
# File 'lib/ri_cal/property_value/date_time.rb', line 234

def year
  @date_time_value.year
end