Class: RiCal::PropertyValue::DateTime

Inherits:
RiCal::PropertyValue show all
Includes:
Comparable, AdditiveMethods, TimeMachine, TimezoneSupport
Defined in:
lib/ri_cal/property_value/date_time.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

Instance Attribute Summary

Attributes inherited from RiCal::PropertyValue

#params, #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

#has_local_timezone?, #in_time_zone, #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, #enumerator, #equality_value, #initialize, #parms_string, #to_options_hash, #to_ri_cal_property_value, #to_s, #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:



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

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:



134
135
136
 
# File 'lib/ri_cal/property_value/date_time.rb', line 134

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

.convert_with_tzid_or_nil(timezone_finder, ruby_object) ⇒ Object

:nodoc:



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

def self.convert_with_tzid_or_nil(timezone_finder, ruby_object) # :nodoc:
  time, identifier = *self.time_and_tzid(ruby_object)
  if identifier
    new(
    timezone_finder,
    :params => params_for_tzid(identifier),
    :value => time.strftime("%Y%m%d%H%M%S")
    )
  else
    nil
  end
end

.default_tzid ⇒ Object

:nodoc:



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

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 ‘none’ 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.



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

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

.default_tzid_hash ⇒ Object

:nodoc:



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

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

.from_string(string) ⇒ Object

:nodoc:



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

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

.from_time(time_or_date_time) ⇒ Object

Create an instance of RiCal::PropertyValue::DateTime representing a Ruby Time or DateTime If the ruby object has been extended by ActiveSupport to have a time_zone method, then the timezone will be used as the TZID parameter.

Otherwise the class level default tzid will be used.

See

  • RiCal::PropertyValue::DateTime.default_tzid

  • RiCal::PropertyValue::DateTime#object_time_zone



146
147
148
149
 
# File 'lib/ri_cal/property_value/date_time.rb', line 146

def self.from_time(time_or_date_time)
  convert_with_tzid_or_nil(nil, time_or_date_time) ||
  new(nil, :value => time_or_date_time.strftime("%Y%m%dT%H%M%S"), :params => default_tzid_hash)
end

.or_date(parent, line) ⇒ Object

def initialize(timezone_finder, options={}) #:nodoc:

super(timezone_finder ? timezone_finder : Calendar.new, options)

end



24
25
26
27
28
29
30
 
# File 'lib/ri_cal/property_value/date_time.rb', line 24

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:



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

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

.single_time_or_date?(ruby_object) ⇒ Boolean

A hack to detect whether an array passed to convert is a

Returns:

  • (Boolean) 


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

def self.single_time_or_date?(ruby_object)
  if (::Array === ruby_object) 
    if (ruby_object.length == 2) && (::String === ruby_object[1])
      case ruby_object[0]
      when ::Date, ::DateTime, ::Time, PropertyValue::Date, PropertyValue::DateTime
        ruby_object
      else
        nil
      end
    end
  else
    ruby_object
  end
end

.time_and_tzid(object) ⇒ Object

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

If the object is an array it is expected to have a time or datetime as its first element, and a time zone identifier string as the second element

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



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

def self.time_and_tzid(object)
  if ::Array === object
    object, identifier = object[0], object[1]
  else
    activesupport_time = object.acts_like_time? rescue nil
    time_zone = activesupport_time && object.time_zone rescue nil
    identifier = time_zone && (time_zone.respond_to?(:tzinfo) ? time_zone.tzinfo  : time_zone).identifier
  end
  [object, identifier]
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



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

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

#==(other) ⇒ Object

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



238
239
240
241
242
243
244
 
# File 'lib/ri_cal/property_value/date_time.rb', line 238

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:



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

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



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

def day
  @date_time_value.day
end

#days_in_month ⇒ Object

Return the number of days in the month containing the receiver



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

def days_in_month
  @date_time_value.days_in_month
end

#for_parent(parent) ⇒ Object

:nodoc:



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

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



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

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) 


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

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

#inspect ⇒ Object

:nodoc:



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

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

#iso_weeks_in_year(wkst) ⇒ Object 



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

def iso_weeks_in_year(wkst)
  @date_time_value.iso_weeks_in_year(wkst)
end

#iso_year_and_week_one_start(wkst) ⇒ Object

:nodoc:



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

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



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

def min
  @date_time_value.min
end

#month ⇒ Object

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



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

def month
  @date_time_value.month
end

#nth_wday_in_month(n, which_wday) ⇒ Object 



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

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

#nth_wday_in_year(n, which_wday) ⇒ Object 



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

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

#occurrence_hash(default_duration) ⇒ Object

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



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

def occurrence_hash(default_duration) # :nodoc:
  {:start => self, :end => (default_duration ? self + default_duration : nil)}
end

#params=(value) ⇒ Object

:nodoc:



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

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

#ruby_value ⇒ Object Also known as: to_ri_cal_ruby_value

Returns a ruby DateTime object representing the receiver.



313
314
315
 
# File 'lib/ri_cal/property_value/date_time.rb', line 313

def ruby_value
  to_datetime
end

#sec ⇒ Object

Return the second



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

def sec
  @date_time_value.sec
end

#to_datetime ⇒ Object

Return the Ruby DateTime representation of the receiver



308
309
310
 
# File 'lib/ri_cal/property_value/date_time.rb', line 308

def to_datetime
  @date_time_value
end

#to_ri_cal_date_or_date_time_value ⇒ Object

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



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

def to_ri_cal_date_or_date_time_value
  self
end

#to_ri_cal_date_time_value ⇒ Object

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



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

def to_ri_cal_date_time_value
  self
end

#value ⇒ Object

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



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

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



84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/ri_cal/property_value/date_time.rb', line 84

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

#visible_params ⇒ Object

:nodoc:



183
184
185
186
187
188
189
190
191
 
# File 'lib/ri_cal/property_value/date_time.rb', line 183

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



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

def wday
  @date_time_value.wday
end

#year ⇒ Object

Return the year (including the century)



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

def year
  @date_time_value.year
end