Included Modules

Class/Module Index [+]

Quicksearch

RiCal::Component::Timezone

An Timezone (VTIMEZONE) calendar component describes a timezone used within the calendar.
A Timezone has two or more TimezonePeriod subcomponents which describe the transitions between
standard and daylight saving time.

to see the property accessing methods for this class see the RiCal::Properties::Timezone module

Public Instance Methods

identifier() click to toggle source

The identifier of the timezone, e.g. “Europe/Paris”.

# File lib/ri_cal/component/timezone.rb, line 19
def identifier
  tzid
end
local_to_utc(time) click to toggle source

convert time from this time zone to utc time

# File lib/ri_cal/component/timezone.rb, line 146
def local_to_utc(time)
  time = time.to_ri_cal_date_time_value
  period = period_for_local(time)
  converted = time - period.tzoffsetto_property
  converted.tzid = "UTC"
  converted
end
name() click to toggle source

An alias for identifier.

# File lib/ri_cal/component/timezone.rb, line 24
def name
  # Don't use alias, as identifier gets overridden.
  identifier
end
period_for_local(local, dst=nil) click to toggle source

Returns the TimezonePeriod for the given local time. local can either be a DateTime, Time or integer timestamp (Time.to_i). Any timezone information in local is ignored (it is treated as a time in the current timezone).

Warning: There are local times that have no equivalent UTC times (e.g. in the transition from standard time to daylight savings time). There are also local times that have more than one UTC equivalent (e.g. in the transition from daylight savings time to standard time).

In the first case (no equivalent UTC time), a PeriodNotFound exception will be raised.

In the second case (more than one equivalent UTC time), an AmbiguousTime exception will be raised unless the optional dst parameter or block handles the ambiguity.

If the ambiguity is due to a transition from daylight savings time to standard time, the dst parameter can be used to select whether the daylight savings time or local time is used. For example,

Timezone.get('America/New_York').period_for_local(DateTime.new(2004,10,31,1,30,0))

would raise an AmbiguousTime exception.

Specifying dst=true would the daylight savings period from April to October 2004. Specifying dst=false would return the standard period from October 2004 to April 2005.

If the dst parameter does not resolve the ambiguity, and a block is specified, it is called. The block must take a single parameter - an array of the periods that need to be resolved. The block can select and return a single period or return nil or an empty array to cause an AmbiguousTime exception to be raised.

TODO: need to check for ambiguity

# File lib/ri_cal/component/timezone.rb, line 102
def period_for_local(local, dst=nil)
  results = periods_for_local(local)

  if results.empty?
    raise TZInfo::PeriodNotFound
  elsif results.size < 2
    results.first
  else
    # ambiguous result try to resolve

    unless dst.nil?
      matches = results.find_all {|period| period.dst? == dst}
      results = matches unless matches.empty?
    end

    if results.size < 2
      results.first
    else
      # still ambiguous, try the block

      if block_given?
        results = yield results
      end

      if results.is_a?(TimezonePeriod)
        results
      elsif results && results.size == 1
        results.first
      else
        raise TZInfo::AmbiguousTime, "#{local} is an ambiguous local time."
      end
    end
  end
end
period_for_utc(time) click to toggle source

Returns the TimezonePeriod for the given UTC time. utc can either be a DateTime, Time or integer timestamp (Time.to_i). Any timezone information in utc is ignored (it is treated as a UTC time).

# File lib/ri_cal/component/timezone.rb, line 36
def period_for_utc(time)
  last_period(last_before_utc(standard, time), last_before_utc(daylight, time))
end
periods_for_local(local) click to toggle source

Returns the set of TimezonePeriod instances that are valid for the given local time as an array. If you just want a single period, use period_for_local instead and specify how ambiguities should be resolved. Returns an empty array if no periods are found for the given time.

# File lib/ri_cal/component/timezone.rb, line 44
def periods_for_local(local)
  local = local.to_ri_cal_date_time_value
  candidate_standard = last_before_local(standard, local)
  candidate_daylight = last_before_local(daylight, local)
  if candidate_daylight && candidate_daylight.swallows_local?(local, candidate_standard)
    []  # Invalid local time
  elsif candidate_standard
    if candidate_daylight
      if candidate_daylight.dtstart > candidate_standard.dtstart
        [candidate_daylight]
      elsif candidate_standard.ambiguous_local?(local)
        [candidate_daylight, candidate_standard]
      else
        [candidate_standard].compact
      end
    else
      [candidate_standard].compact
    end
  end
end
utc_to_local(time) click to toggle source

convert time from utc time to this time zone

# File lib/ri_cal/component/timezone.rb, line 138
def utc_to_local(time)
  time = time.to_ri_cal_date_time_value
  converted = time + period_for_utc(time).tzoffsetto_property
  converted.tzid = identifier
  converted
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.