tzinfo 1.2.5

data/lib/tzinfo/timezone_proxy.rb

@@ -0,0 +1,105 @@
+module TZInfo
+
+  # A proxy class representing a timezone with a given identifier. TimezoneProxy
+  # inherits from Timezone and can be treated like any Timezone loaded with
+  # Timezone.get.
+  #
+  # The first time an attempt is made to access the data for the timezone, the 
+  # real Timezone is loaded. If the proxy's identifier was not valid, then an 
+  # exception will be raised at this point.  
+  class TimezoneProxy < Timezone
+    # Construct a new TimezoneProxy for the given identifier. The identifier
+    # is not checked when constructing the proxy. It will be validated on the
+    # when the real Timezone is loaded.
+    def self.new(identifier)
+      # Need to override new to undo the behaviour introduced in Timezone#new.
+      tzp = super()
+      tzp.send(:setup, identifier)
+      tzp
+    end
+        
+    # The identifier of the timezone, e.g. "Europe/Paris".
+    def identifier
+      @real_timezone ? @real_timezone.identifier : @identifier
+    end
+    
+    # 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).        
+    def period_for_utc(utc)            
+      real_timezone.period_for_utc(utc)            
+    end
+    
+    # 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 abiguities should be resolved.
+    # Returns an empty array if no periods are found for the given time.
+    def periods_for_local(local)
+      real_timezone.periods_for_local(local)
+    end
+    
+    # Returns an Array of TimezoneTransition instances representing the times
+    # where the UTC offset of the timezone changes.
+    #
+    # Transitions are returned up to a given date and time up to a given date
+    # and time (to).
+    #
+    # A from date and time may also be supplied using the from parameter. If
+    # from is not nil, only transitions from that date and time onwards will be
+    # returned.
+    #
+    # Comparisons with to are exclusive. Comparisons with from are inclusive.
+    # If a transition falls precisely on to, it will be excluded. If a
+    # transition falls on from, it will be included.
+    #
+    # Transitions returned are ordered by when they occur, from earliest to
+    # latest.
+    #
+    # to and from can be specified using either a Time, DateTime, Time or
+    # Timestamp.
+    #
+    # If from is specified and to is not greater than from, then an
+    # ArgumentError exception is raised.
+    #
+    # ArgumentError is raised if to is nil or of either to or from are
+    # Timestamps with unspecified offsets.
+    def transitions_up_to(to, from = nil)
+      real_timezone.transitions_up_to(to, from)
+    end
+
+    # Returns the canonical zone for this Timezone.
+    def canonical_zone
+      real_timezone.canonical_zone
+    end
+    
+    # Dumps this TimezoneProxy for marshalling.
+    def _dump(limit)
+      identifier
+    end
+    
+    # Loads a marshalled TimezoneProxy.
+    def self._load(data)
+      TimezoneProxy.new(data)
+    end
+    
+    private
+      def setup(identifier)
+        @identifier = identifier
+        @real_timezone = nil
+      end  
+    
+      def real_timezone
+        # Thread-safety: It is possible that the value of @real_timezone may be 
+        # calculated multiple times in concurrently executing threads. It is not 
+        # worth the overhead of locking to ensure that @real_timezone is only 
+        # calculated once.
+        unless @real_timezone
+          result = Timezone.get(@identifier)
+          return result if frozen?
+          @real_timezone = result
+        end
+
+        @real_timezone
+      end     
+  end 
+end

data/lib/tzinfo/timezone_transition.rb

@@ -0,0 +1,130 @@
+module TZInfo
+  # Represents a transition from one timezone offset to another at a particular
+  # date and time.
+  class TimezoneTransition
+    # The offset this transition changes to (a TimezoneOffset instance).
+    attr_reader :offset
+    
+    # The offset this transition changes from (a TimezoneOffset instance).
+    attr_reader :previous_offset
+    
+    # Initializes a new TimezoneTransition.
+    #
+    # TimezoneTransition instances should not normally be constructed manually.
+    def initialize(offset, previous_offset)
+      @offset = offset
+      @previous_offset = previous_offset
+      @local_end_at = nil
+      @local_start_at = nil
+    end
+    
+    # A TimeOrDateTime instance representing the UTC time when this transition
+    # occurs.
+    def at
+      raise_not_implemented('at')
+    end
+    
+    # The UTC time when this transition occurs, returned as a DateTime instance.
+    def datetime
+      at.to_datetime
+    end
+    
+    # The UTC time when this transition occurs, returned as a Time instance.
+    def time
+      at.to_time
+    end
+    
+    # A TimeOrDateTime instance representing the local time when this transition
+    # causes the previous observance to end (calculated from at using 
+    # previous_offset).
+    def local_end_at
+      # Thread-safety: It is possible that the value of @local_end_at may be
+      # calculated multiple times in concurrently executing threads. It is not 
+      # worth the overhead of locking to ensure that @local_end_at is only
+      # calculated once.
+    
+      unless @local_end_at
+        result = at.add_with_convert(@previous_offset.utc_total_offset)
+        return result if frozen?
+        @local_end_at = result
+      end
+
+      @local_end_at
+    end
+    
+    # The local time when this transition causes the previous observance to end,
+    # returned as a DateTime instance.
+    def local_end
+      local_end_at.to_datetime
+    end
+    
+    # The local time when this transition causes the previous observance to end,
+    # returned as a Time instance.
+    def local_end_time
+      local_end_at.to_time
+    end
+    
+    # A TimeOrDateTime instance representing the local time when this transition
+    # causes the next observance to start (calculated from at using offset).
+    def local_start_at
+      # Thread-safety: It is possible that the value of @local_start_at may be
+      # calculated multiple times in concurrently executing threads. It is not 
+      # worth the overhead of locking to ensure that @local_start_at is only
+      # calculated once.
+    
+      unless @local_start_at
+        result = at.add_with_convert(@offset.utc_total_offset)
+        return result if frozen?
+        @local_start_at = result
+      end
+
+      @local_start_at
+    end
+    
+    # The local time when this transition causes the next observance to start,
+    # returned as a DateTime instance.
+    def local_start
+      local_start_at.to_datetime
+    end
+    
+    # The local time when this transition causes the next observance to start,
+    # returned as a Time instance.
+    def local_start_time
+      local_start_at.to_time
+    end
+    
+    # Returns true if this TimezoneTransition is equal to the given
+    # TimezoneTransition. Two TimezoneTransition instances are 
+    # considered to be equal by == if offset, previous_offset and at are all 
+    # equal.
+    def ==(tti)
+      tti.kind_of?(TimezoneTransition) &&
+        offset == tti.offset && previous_offset == tti.previous_offset && at == tti.at
+    end
+    
+    # Returns true if this TimezoneTransition is equal to the given
+    # TimezoneTransition. Two TimezoneTransition instances are 
+    # considered to be equal by eql? if offset, previous_offset and at are all
+    # equal and the type used to define at in both instances is the same.
+    def eql?(tti)
+      tti.kind_of?(TimezoneTransition) &&
+        offset == tti.offset && previous_offset == tti.previous_offset && at.eql?(tti.at)
+    end
+    
+    # Returns a hash of this TimezoneTransition instance.
+    def hash
+      @offset.hash ^ @previous_offset.hash ^ at.hash
+    end
+    
+    # Returns internal object state as a programmer-readable string.
+    def inspect
+      "#<#{self.class}: #{at.inspect},#{@offset.inspect}>"      
+    end
+
+    private
+
+    def raise_not_implemented(method_name)
+      raise NotImplementedError, "Subclasses must override #{method_name}"
+    end
+  end
+end

data/lib/tzinfo/timezone_transition_definition.rb

@@ -0,0 +1,104 @@
+module TZInfo
+  # A TimezoneTransition defined by as integer timestamp, as a rational to
+  # create a DateTime or as both.
+  #
+  # @private 
+  class TimezoneTransitionDefinition < TimezoneTransition #:nodoc:
+    # The numerator of the DateTime if the transition time is defined as a 
+    # DateTime, otherwise the transition time as a timestamp.
+    attr_reader :numerator_or_time
+    protected :numerator_or_time
+    
+    # Either the denominator of the DateTime if the transition time is defined
+    # as a DateTime, otherwise nil. 
+    attr_reader :denominator
+    protected :denominator
+    
+    # Creates a new TimezoneTransitionDefinition with the given offset, 
+    # previous_offset (both TimezoneOffset instances) and UTC time.
+    #
+    # The time can be specified as a timestamp, as a rational to create a
+    # DateTime, or as both.
+    #
+    # If both a timestamp and rational are given, then the rational will only
+    # be used if the timestamp falls outside of the range of Time on the
+    # platform being used at runtime.
+    #
+    # DateTimes are created from the rational as follows:
+    # 
+    #  RubyCoreSupport.datetime_new!(RubyCoreSupport.rational_new!(numerator, denominator), 0, Date::ITALY)
+    #
+    # For performance reasons, the numerator and denominator must be specified
+    # in their lowest form.
+    def initialize(offset, previous_offset, numerator_or_timestamp, denominator_or_numerator = nil, denominator = nil)
+      super(offset, previous_offset)
+      
+      if denominator
+        numerator = denominator_or_numerator
+        timestamp = numerator_or_timestamp
+      elsif denominator_or_numerator
+        numerator = numerator_or_timestamp
+        denominator = denominator_or_numerator
+        timestamp = nil
+      else
+        numerator = nil
+        denominator = nil
+        timestamp = numerator_or_timestamp
+      end
+      
+      # Determine whether to use the timestamp or the numerator and denominator.
+      if numerator && (
+        !timestamp || 
+        (timestamp < 0 && !RubyCoreSupport.time_supports_negative) || 
+        ((timestamp < -2147483648 || timestamp > 2147483647) && !RubyCoreSupport.time_supports_64bit)
+        )
+        
+        @numerator_or_time = numerator
+        @denominator = denominator
+      else
+        @numerator_or_time = timestamp
+        @denominator = nil
+      end
+      
+      @at = nil
+    end
+    
+    # A TimeOrDateTime instance representing the UTC time when this transition
+    # occurs.
+    def at
+      # Thread-safety: It is possible that the value of @at may be calculated
+      # multiple times in concurrently executing threads. It is not worth the
+      # overhead of locking to ensure that @at is only calculated once.
+      
+      unless @at
+        result = unless @denominator
+          TimeOrDateTime.new(@numerator_or_time)
+        else
+          r = RubyCoreSupport.rational_new!(@numerator_or_time, @denominator)
+          dt = RubyCoreSupport.datetime_new!(r, 0, Date::ITALY)
+          TimeOrDateTime.new(dt)
+        end
+
+        return result if frozen?
+        @at = result
+      end
+      
+      @at
+    end
+    
+    # Returns true if this TimezoneTransitionDefinition is equal to the given
+    # TimezoneTransitionDefinition. Two TimezoneTransitionDefinition instances 
+    # are considered to be equal by eql? if offset, previous_offset, 
+    # numerator_or_time and denominator are all equal.
+    def eql?(tti)
+      tti.kind_of?(TimezoneTransitionDefinition) &&
+        offset == tti.offset && previous_offset == tti.previous_offset &&
+        numerator_or_time == tti.numerator_or_time && denominator == tti.denominator        
+    end
+    
+    # Returns a hash of this TimezoneTransitionDefinition instance.
+    def hash
+      @offset.hash ^ @previous_offset.hash ^ @numerator_or_time.hash ^ @denominator.hash
+    end
+  end
+end

data/lib/tzinfo/transition_data_timezone_info.rb

@@ -0,0 +1,274 @@
+module TZInfo
+  # Raised if no offsets have been defined when calling period_for_utc or
+  # periods_for_local. Indicates an error in the timezone data.
+  class NoOffsetsDefined < StandardError
+  end
+    
+  # Represents a data timezone defined by a set of offsets and a set 
+  # of transitions.
+  #
+  # @private
+  class TransitionDataTimezoneInfo < DataTimezoneInfo #:nodoc:
+            
+    # Constructs a new TransitionDataTimezoneInfo with its identifier.
+    def initialize(identifier)   
+      super(identifier)
+      @offsets = {}
+      @transitions = []
+      @previous_offset = nil
+      @transitions_index = nil
+    end
+ 
+    # Defines a offset. The id uniquely identifies this offset within the
+    # timezone. utc_offset and std_offset define the offset in seconds of 
+    # standard time from UTC and daylight savings from standard time 
+    # respectively. abbreviation describes the timezone offset (e.g. GMT, BST,
+    # EST or EDT).
+    #
+    # The first offset to be defined is treated as the offset that applies
+    # until the first transition. This will usually be in Local Mean Time (LMT).
+    #
+    # ArgumentError will be raised if the id is already defined.
+    def offset(id, utc_offset, std_offset, abbreviation)
+      raise ArgumentError, 'Offset already defined' if @offsets.has_key?(id)
+      
+      offset = TimezoneOffset.new(utc_offset, std_offset, abbreviation)
+      @offsets[id] = offset
+      @previous_offset = offset unless @previous_offset
+    end
+    
+    # Defines a transition. Transitions must be defined in chronological order.
+    # ArgumentError will be raised if a transition is added out of order.
+    # offset_id refers to an id defined with offset. ArgumentError will be 
+    # raised if the offset_id cannot be found. numerator_or_time and
+    # denomiator specify the time the transition occurs as. See 
+    # TimezoneTransition for more detail about specifying times.
+    def transition(year, month, offset_id, numerator_or_timestamp, denominator_or_numerator = nil, denominator = nil)
+      offset = @offsets[offset_id]      
+      raise ArgumentError, 'Offset not found' unless offset
+            
+      if @transitions_index
+        if year < @last_year || (year == @last_year && month < @last_month)
+          raise ArgumentError, 'Transitions must be increasing date order'
+        end
+        
+        # Record the position of the first transition with this index.
+        index = transition_index(year, month)
+        @transitions_index[index] ||= @transitions.length
+                
+        # Fill in any gaps       
+        (index - 1).downto(0) do |i|
+          break if @transitions_index[i]
+          @transitions_index[i] = @transitions.length
+        end
+      else
+        @transitions_index = [@transitions.length]
+        @start_year = year
+        @start_month = month        
+      end
+      
+      @transitions << TimezoneTransitionDefinition.new(offset, @previous_offset,
+        numerator_or_timestamp, denominator_or_numerator, denominator)
+      @last_year = year
+      @last_month = month             
+      @previous_offset = offset
+    end           
+    
+    # Returns the TimezonePeriod for the given UTC time.
+    # Raises NoOffsetsDefined if no offsets have been defined.
+    def period_for_utc(utc)
+      unless @transitions.empty?
+        utc = TimeOrDateTime.wrap(utc)               
+        index = transition_index(utc.year, utc.mon)
+        
+        start_transition = nil
+        start = transition_before_end(index)
+        if start
+          start.downto(0) do |i|
+            if @transitions[i].at <= utc
+              start_transition = @transitions[i]
+              break
+            end
+          end
+        end
+        
+        end_transition = nil
+        start = transition_after_start(index)      
+        if start
+          start.upto(@transitions.length - 1) do |i|
+            if @transitions[i].at > utc
+              end_transition = @transitions[i]
+              break
+            end
+          end
+        end
+               
+        if start_transition || end_transition
+          TimezonePeriod.new(start_transition, end_transition)
+        else
+          # Won't happen since there are transitions. Must always find one
+          # transition that is either >= or < the specified time.
+          raise 'No transitions found in search'
+        end        
+      else
+        raise NoOffsetsDefined, 'No offsets have been defined' unless @previous_offset        
+        TimezonePeriod.new(nil, nil, @previous_offset)
+      end
+    end
+    
+    # Returns the set of TimezonePeriods for the given local time as an array.    
+    # Results returned are ordered by increasing UTC start date.
+    # Returns an empty array if no periods are found for the given time.
+    # Raises NoOffsetsDefined if no offsets have been defined.    
+    def periods_for_local(local)
+      unless @transitions.empty?
+        local = TimeOrDateTime.wrap(local)
+        index = transition_index(local.year, local.mon)
+        
+        result = []
+       
+        start_index = transition_after_start(index - 1)       
+        if start_index && @transitions[start_index].local_end_at > local
+          if start_index > 0
+            if @transitions[start_index - 1].local_start_at <= local
+              result << TimezonePeriod.new(@transitions[start_index - 1], @transitions[start_index])
+            end
+          else
+            result << TimezonePeriod.new(nil, @transitions[start_index])
+          end
+        end
+        
+        end_index = transition_before_end(index + 1)
+        
+        if end_index        
+          start_index = end_index unless start_index
+          
+          start_index.upto(transition_before_end(index + 1)) do |i|
+            if @transitions[i].local_start_at <= local
+              if i + 1 < @transitions.length
+                if @transitions[i + 1].local_end_at > local
+                  result << TimezonePeriod.new(@transitions[i], @transitions[i + 1])
+                end
+              else
+                result << TimezonePeriod.new(@transitions[i], nil)
+              end
+            end
+          end
+        end
+        
+        result
+      else
+        raise NoOffsetsDefined, 'No offsets have been defined' unless @previous_offset
+        [TimezonePeriod.new(nil, nil, @previous_offset)]
+      end
+    end
+    
+    # Returns an Array of TimezoneTransition instances representing the times
+    # where the UTC offset of the timezone changes.
+    #
+    # Transitions are returned up to a given date and time up to a given date 
+    # and time, specified in UTC (utc_to).
+    #
+    # A from date and time may also be supplied using the utc_from parameter
+    # (also specified in UTC). If utc_from is not nil, only transitions from 
+    # that date and time onwards will be returned.
+    #
+    # Comparisons with utc_to are exclusive. Comparisons with utc_from are
+    # inclusive. If a transition falls precisely on utc_to, it will be excluded.
+    # If a transition falls on utc_from, it will be included.
+    #
+    # Transitions returned are ordered by when they occur, from earliest to 
+    # latest.
+    #
+    # utc_to and utc_from can be specified using either DateTime, Time or 
+    # integer timestamps (Time.to_i).
+    #
+    # If utc_from is specified and utc_to is not greater than utc_from, then
+    # transitions_up_to raises an ArgumentError exception.
+    def transitions_up_to(utc_to, utc_from = nil)
+      utc_to = TimeOrDateTime.wrap(utc_to)
+      utc_from = utc_from ? TimeOrDateTime.wrap(utc_from) : nil
+      
+      if utc_from && utc_to <= utc_from
+        raise ArgumentError, 'utc_to must be greater than utc_from'
+      end
+      
+      unless @transitions.empty?
+        if utc_from
+          from = transition_after_start(transition_index(utc_from.year, utc_from.mon))
+          
+          if from
+            while from < @transitions.length && @transitions[from].at < utc_from
+              from += 1
+            end
+            
+            if from >= @transitions.length
+              return []
+            end
+          else
+            # utc_from is later than last transition.
+            return []
+          end
+        else
+          from = 0
+        end
+        
+        to = transition_before_end(transition_index(utc_to.year, utc_to.mon))
+        
+        if to
+          while to >= 0 && @transitions[to].at >= utc_to
+            to -= 1
+          end
+          
+          if to < 0
+            return []
+          end
+        else
+          # utc_to is earlier than first transition.
+          return []
+        end
+
+        @transitions[from..to]
+      else
+        []
+      end
+    end
+    
+    private
+      # Returns the index into the @transitions_index array for a given year 
+      # and month.
+      def transition_index(year, month)
+        index = (year - @start_year) * 2
+        index += 1 if month > 6
+        index -= 1 if @start_month > 6
+        index
+      end
+      
+      # Returns the index into @transitions of the first transition that occurs
+      # on or after the start of the given index into @transitions_index.
+      # Returns nil if there are no such transitions.
+      def transition_after_start(index)
+        if index >= @transitions_index.length
+          nil
+        else
+          index = 0 if index < 0
+          @transitions_index[index]
+        end
+      end
+      
+      # Returns the index into @transitions of the first transition that occurs
+      # before the end of the given index into @transitions_index.
+      # Returns nil if there are no such transitions.
+      def transition_before_end(index)
+        index = index + 1
+        
+        if index <= 0
+          nil
+        elsif index >= @transitions_index.length          
+          @transitions.length - 1
+        else      
+          @transitions_index[index] - 1          
+        end
+      end            
+  end
+end