Parent

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

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.