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, #compute_advance, #compute_change, #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, #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:



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

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:



120
121
122
 
# File 'lib/ri_cal/property_value/date_time.rb', line 120

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:



124
125
126
127
128
129
130
 
# File 'lib/ri_cal/property_value/date_time.rb', line 124

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.



108
109
110
111
112
113
114
115
116
117
 
# File 'lib/ri_cal/property_value/date_time.rb', line 108

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



174
175
176
 
# File 'lib/ri_cal/property_value/date_time.rb', line 174

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

#==(other) ⇒ Object

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



204
205
206
207
208
209
210
 
# File 'lib/ri_cal/property_value/date_time.rb', line 204

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:



322
323
324
 
# File 'lib/ri_cal/property_value/date_time.rb', line 322

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

#day ⇒ Object Also known as: mday

Return the day of the month



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

def day
  @date_time_value.day
end

#days_in_month ⇒ Object

Return the number of days in the month containing the receiver



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

def days_in_month
  @date_time_value.days_in_month
end

#for_occurrence(occurrence) ⇒ Object 



330
331
332
 
# File 'lib/ri_cal/property_value/date_time.rb', line 330

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

#for_parent(parent) ⇒ Object

:nodoc:



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

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



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

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) 


179
180
181
 
# File 'lib/ri_cal/property_value/date_time.rb', line 179

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:



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

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:



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

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



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

def min
  @date_time_value.min
end

#month ⇒ Object

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



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

def month
  @date_time_value.month
end

#nth_wday_in_month(n, which_wday) ⇒ Object

:nodoc:



183
184
185
 
# File 'lib/ri_cal/property_value/date_time.rb', line 183

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

#nth_wday_in_year(n, which_wday) ⇒ Object

:nodoc:



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

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

#occurrence_period(default_duration) ⇒ Object

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



213
214
215
 
# File 'lib/ri_cal/property_value/date_time.rb', line 213

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



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

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:



153
154
155
156
157
158
 
# File 'lib/ri_cal/property_value/date_time.rb', line 153

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

#ruby_value ⇒ Object

Returns a ruby DateTime object representing the receiver.



284
285
286
287
288
289
290
 
# File 'lib/ri_cal/property_value/date_time.rb', line 284

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



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

def sec
  @date_time_value.sec
end

#start_of_day? ⇒ Boolean

Returns:

  • (Boolean) 


326
327
328
 
# File 'lib/ri_cal/property_value/date_time.rb', line 326

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

#to_datetime ⇒ Object Also known as: to_ri_cal_ruby_value, to_finish_time

Return the Ruby DateTime representation of the receiver



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

def to_datetime #:nodoc:
  @date_time_value
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.”



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

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.



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

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



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

def to_ri_cal_date_value(timezone_finder=nil)
  PropertyValue::Date.new(timezone_finder, :value => @date_time_value.strftime("%Y%m%d"))
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



314
315
316
317
318
319
320
 
# File 'lib/ri_cal/property_value/date_time.rb', line 314

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



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

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

#to_zulu_time ⇒ Object 



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

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.strftime("%Y%m%dT%H%M%S#{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
 
# 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 = ::DateTime.parse(val)
    if val =~/Z/
      self.tzid = 'UTC'
    else
      @tzid ||= :floating
    end
  when ::DateTime
    @date_time_value = val
  when ::Date, ::Time
    @date_time_value = ::DateTime.parse(val.to_s)
  end
end

#visible_params ⇒ Object

:nodoc:



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

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



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

def wday
  @date_time_value.wday
end

#year ⇒ Object

Return the year (including the century)



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

def year
  @date_time_value.year
end