1  #--
   2  # Copyright (c) 2006 Philip Ross
   3  # 
   4  # Permission is hereby granted, free of charge, to any person obtaining a copy
   5  # of this software and associated documentation files (the "Software"), to deal
   6  # in the Software without restriction, including without limitation the rights
   7  # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   8  # copies of the Software, and to permit persons to whom the Software is
   9  # furnished to do so, subject to the following conditions:
  10  # 
  11  # The above copyright notice and this permission notice shall be included in all
  12  # copies or substantial portions of the Software.
  13  #
  14  # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15  # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16  # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  17  # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18  # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  19  # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  20  # THE SOFTWARE.
  21  #++
  22 
  23  require 'date'
  24  require 'tzinfo/time_or_datetime'
  25 
  26  module TZInfo
  27    # Represents an offset defined in a Timezone data file.
  28    class TimezoneTransitionInfo #:nodoc:
  29      # The offset this transition changes to (a TimezoneOffsetInfo instance).
  30      attr_reader :offset
  31      
  32      # The offset this transition changes from (a TimezoneOffsetInfo instance).
  33      attr_reader :previous_offset
  34      
  35      # The numerator of the DateTime if the transition time is defined as a 
  36      # DateTime, otherwise the transition time as a timestamp.
  37      attr_reader :numerator_or_time
  38      protected :numerator_or_time
  39      
  40      # Either the denominotor of the DateTime if the transition time is defined
  41      # as a DateTime, otherwise nil. 
  42      attr_reader :denominator
  43      protected :denominator
  44      
  45      # Creates a new TimezoneTransitionInfo with the given offset, 
  46      # previous_offset (both TimezoneOffsetInfo instances) and UTC time. 
  47      # if denominator is nil, numerator_or_time is treated as a number of 
  48      # seconds since the epoch. If denominator is specified numerator_or_time
  49      # and denominator are used to create a DateTime as follows:
  50      # 
  51      #  DateTime.new!(Rational.send(:new!, numerator_or_time, denominator), 0, Date::ITALY)
  52      #
  53      # For performance reasons, the numerator and denominator must be specified
  54      # in their lowest form.
  55      def initialize(offset, previous_offset, numerator_or_time, denominator = nil)
  56        @offset = offset
  57        @previous_offset = previous_offset
  58        @numerator_or_time = numerator_or_time
  59        @denominator = denominator
  60        
  61        @at = nil
  62        @local_end = nil
  63        @local_start = nil
  64      end
  65      
  66      # A TimeOrDateTime instance representing the UTC time when this transition
  67      # occurs.
  68      def at
  69        unless @at
  70          unless @denominator 
  71            @at = TimeOrDateTime.new(@numerator_or_time)
  72          else
  73            r = RubyCoreSupport.rational_new!(@numerator_or_time, @denominator)
  74            dt = RubyCoreSupport.datetime_new!(r, 0, Date::ITALY)
  75            @at = TimeOrDateTime.new(dt)
  76          end
  77        end
  78        
  79        @at
  80      end
  81      
  82      # A TimeOrDateTime instance representing the local time when this transition
  83      # causes the previous observance to end (calculated from at using 
  84      # previous_offset).
  85      def local_end
  86        @local_end = at.add_with_convert(@previous_offset.utc_total_offset) unless @local_end      
  87        @local_end
  88      end
  89      
  90      # A TimeOrDateTime instance representing the local time when this transition
  91      # causes the next observance to start (calculated from at using offset).
  92      def local_start
  93        @local_start = at.add_with_convert(@offset.utc_total_offset) unless @local_start
  94        @local_start
  95      end
  96      
  97      # Returns true if this TimezoneTransitionInfo is equal to the given
  98      # TimezoneTransitionInfo. Two TimezoneTransitionInfo instances are 
  99      # considered to be equal by == if offset, previous_offset and at are all 
 100      # equal.
 101      def ==(tti)
 102        tti.respond_to?(:offset) && tti.respond_to?(:previous_offset) && tti.respond_to?(:at) &&
 103          offset == tti.offset && previous_offset == tti.previous_offset && at == tti.at
 104      end
 105      
 106      # Returns true if this TimezoneTransitionInfo is equal to the given
 107      # TimezoneTransitionInfo. Two TimezoneTransitionInfo instances are 
 108      # considered to be equal by eql? if offset, previous_offset, 
 109      # numerator_or_time and denominator are all equal. This is stronger than ==,
 110      # which just requires the at times to be equal regardless of how they were
 111      # originally specified.
 112      def eql?(tti)
 113        tti.respond_to?(:offset) && tti.respond_to?(:previous_offset) &&
 114          tti.respond_to?(:numerator_or_time) && tti.respond_to?(:denominator) &&
 115          offset == tti.offset && previous_offset == tti.previous_offset &&
 116          numerator_or_time == tti.numerator_or_time && denominator == tti.denominator        
 117      end
 118      
 119      # Returns a hash of this TimezoneTransitionInfo instance.
 120      def hash
 121        @offset.hash ^ @previous_offset.hash ^ @numerator_or_time.hash ^ @denominator.hash
 122      end
 123      
 124      # Returns internal object state as a programmer-readable string.
 125      def inspect
 126        "#<#{self.class}: #{at.inspect},#{@offset.inspect}>"      
 127      end
 128    end
 129  end