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

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:



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

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:



129
130
131
 
# File 'lib/ri_cal/property_value/date_time.rb', line 129

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:



29
30
31
 
# File 'lib/ri_cal/property_value/date_time.rb', line 29

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.



48
49
50
 
# File 'lib/ri_cal/property_value/date_time.rb', line 48

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

.default_tzid_hash ⇒ Object

:nodoc:



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

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

.from_string(string) ⇒ Object

:nodoc:



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

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:



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

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:



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

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.



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

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) 


25
26
27
 
# File 'lib/ri_cal/property_value/date_time.rb', line 25

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



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

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



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

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:



344
345
346
 
# File 'lib/ri_cal/property_value/date_time.rb', line 344

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 



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

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

#day ⇒ Object Also known as: mday

Return the day of the month



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

def day
  @date_time_value.day
end

#days_in_month ⇒ Object

Return the number of days in the month containing the receiver



221
222
223
 
# File 'lib/ri_cal/property_value/date_time.rb', line 221

def days_in_month
  @date_time_value.days_in_month
end

#fast_date_tme ⇒ Object

:nodoc:



77
78
79
 
# File 'lib/ri_cal/property_value/date_time.rb', line 77

def fast_date_tme # :nodoc:
  @date_time_value
end

#for_occurrence(occurrence) ⇒ Object 



352
353
354
 
# File 'lib/ri_cal/property_value/date_time.rb', line 352

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

#for_parent(parent) ⇒ Object

:nodoc:



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

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



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

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) 


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

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

#inspect ⇒ Object

:nodoc:



60
61
62
 
# File 'lib/ri_cal/property_value/date_time.rb', line 60

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

#iso_weeks_in_year(wkst) ⇒ Object

:nodoc:



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

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:



282
283
284
 
# File 'lib/ri_cal/property_value/date_time.rb', line 282

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



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

def min
  @date_time_value.min
end

#month ⇒ Object

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



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

def month
  @date_time_value.month
end

#nth_wday_in_month(n, which_wday) ⇒ Object

:nodoc:



205
206
207
 
# File 'lib/ri_cal/property_value/date_time.rb', line 205

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:



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

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



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

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



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

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:



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

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.



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

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



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

def sec
  @date_time_value.sec
end

#start_of_day? ⇒ Boolean

Returns:

  • (Boolean) 


348
349
350
 
# File 'lib/ri_cal/property_value/date_time.rb', line 348

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



301
302
303
 
# File 'lib/ri_cal/property_value/date_time.rb', line 301

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



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

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.



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

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



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

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 



73
74
75
 
# File 'lib/ri_cal/property_value/date_time.rb', line 73

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



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

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



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

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 



317
318
319
 
# File 'lib/ri_cal/property_value/date_time.rb', line 317

def to_zulu_time
  utc.to_datetime
end

#value ⇒ Object

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



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

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



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

def value=(val) # :nodoc:
  case val
  when nil
    @date_time_value = nil
  when String
    @date_time_value = FastDateTime.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:



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

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



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

def wday
  @date_time_value.wday
end

#with_date_time_value(date_time_value) ⇒ Object 



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

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)



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

def year
  @date_time_value.year
end