tzinfo 1.2.11 → 2.0.0

data/lib/tzinfo/data_sources/zoneinfo_reader.rb

@@ -0,0 +1,284 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  module DataSources
+    # An {InvalidZoneinfoFile} exception is raised if an attempt is made to load
+    # an invalid zoneinfo file.
+    class InvalidZoneinfoFile < StandardError
+    end
+
+    # Reads compiled zoneinfo TZif (\0, 2 or 3) files.
+    class ZoneinfoReader #:nodoc:
+      # Initializes a new {ZoneinfoReader}.
+      #
+      # @param string_deduper [StringDeduper] a {StringDeduper} instance to use
+      #   when deduping abbreviations.
+      def initialize(string_deduper)
+        @string_deduper = string_deduper
+      end
+
+      # Reads a zoneinfo structure from the given path. Returns either a
+      # {TimezoneOffset} that is constantly observed or an `Array`
+      # {TimezoneTransition}s.
+      #
+      # @param file_path [String] the path of a zoneinfo file.
+      # @return [Object] either a {TimezoneOffset} or an `Array` of
+      #   {TimezoneTransition}s.
+      # @raise [SecurityError] if safe mode is enabled and `file_path` is
+      #   tainted.
+      # @raise [InvalidZoneinfoFile] if `file_path`` does not refer to a valid
+      #   zoneinfo file.
+      def read(file_path)
+        File.open(file_path, 'rb') { |file| parse(file) }
+      end
+
+      private
+
+      # Translates an unsigned 32-bit integer (as returned by unpack) to signed
+      # 32-bit.
+      #
+      # @param long [Integer] an unsigned 32-bit integer.
+      # @return [Integer] {long} translated to signed 32-bit.
+      def make_signed_int32(long)
+        long >= 0x80000000 ? long - 0x100000000 : long
+      end
+
+      # Translates a pair of unsigned 32-bit integers (as returned by unpack,
+      # most significant first) to a signed 64-bit integer.
+      #
+      # @param high [Integer] the most significant 32-bits.
+      # @param low [Integer] the least significant 32-bits.
+      # @return [Integer] {high} and {low} combined and translated to signed
+      #   64-bit.
+      def make_signed_int64(high, low)
+        unsigned = (high << 32) | low
+        unsigned >= 0x8000000000000000 ? unsigned - 0x10000000000000000 : unsigned
+      end
+
+      # Reads the given number of bytes from the given file and checks that the
+      # correct number of bytes could be read.
+      #
+      # @param file [IO] the file to read from.
+      # @param bytes [Integer] the number of bytes to read.
+      # @return [String] the bytes that were read.
+      # @raise [InvalidZoneinfoFile] if the number of bytes available didn't
+      #   match the number requested.
+      def check_read(file, bytes)
+        result = file.read(bytes)
+
+        unless result && result.length == bytes
+          raise InvalidZoneinfoFile, "Expected #{bytes} bytes reading '#{file.path}', but got #{result ? result.length : 0} bytes"
+        end
+
+        result
+      end
+
+      # Zoneinfo files don't include the offset from standard time (std_offset)
+      # for DST periods. Derive the base offset (base_utc_offset) where DST is
+      # observed from either the previous or next non-DST period.
+      #
+      # @param transitions [Array<Hash>] an `Array` of transition hashes.
+      # @param offsets [Array<Hash>] an `Array` of offset hashes.
+      # @return [Integer] the index of the offset to be used prior to the first
+      #   transition.
+      def derive_offsets(transitions, offsets)
+        # The first non-DST offset (if there is one) is the offset observed
+        # before the first transition. Fall back to the first DST offset if
+        # there are no non-DST offsets.
+        first_non_dst_offset_index = offsets.index {|o| !o[:is_dst] }
+        first_offset_index = first_non_dst_offset_index || 0
+        return first_offset_index if transitions.empty?
+
+        # Determine the base_utc_offset of the next non-dst offset at each transition.
+        base_utc_offset_from_next = nil
+
+        transitions.reverse_each do |transition|
+          offset = offsets[transition[:offset]]
+          if offset[:is_dst]
+            transition[:base_utc_offset_from_next] = base_utc_offset_from_next if base_utc_offset_from_next
+          else
+            base_utc_offset_from_next = offset[:observed_utc_offset]
+          end
+        end
+
+        base_utc_offset_from_previous = first_non_dst_offset_index ? offsets[first_non_dst_offset_index][:observed_utc_offset] : nil
+        defined_offsets = {}
+
+        transitions.each do |transition|
+          offset_index = transition[:offset]
+          offset = offsets[offset_index]
+          observed_utc_offset = offset[:observed_utc_offset]
+
+          if offset[:is_dst]
+            base_utc_offset_from_next = transition[:base_utc_offset_from_next]
+
+            difference_to_previous = (observed_utc_offset - (base_utc_offset_from_previous || observed_utc_offset)).abs
+            difference_to_next = (observed_utc_offset - (base_utc_offset_from_next || observed_utc_offset)).abs
+
+            base_utc_offset = if difference_to_previous == 3600
+              base_utc_offset_from_previous
+            elsif difference_to_next == 3600
+              base_utc_offset_from_next
+            elsif difference_to_previous > 0 && difference_to_next > 0
+              difference_to_previous < difference_to_next ? base_utc_offset_from_previous : base_utc_offset_from_next
+            elsif difference_to_previous > 0
+              base_utc_offset_from_previous
+            elsif difference_to_next > 0
+              base_utc_offset_from_next
+            else
+              # No difference, assume a 1 hour offset from standard time.
+              observed_utc_offset - 3600
+            end
+
+            if !offset[:base_utc_offset]
+              offset[:base_utc_offset] = base_utc_offset
+              defined_offsets[offset] = offset_index
+            elsif offset[:base_utc_offset] != base_utc_offset
+              # An earlier transition has already derived a different
+              # base_utc_offset. Define a new offset or reuse an existing identically
+              # defined offset.
+              new_offset = offset.dup
+              new_offset[:base_utc_offset] = base_utc_offset
+
+              offset_index = defined_offsets[new_offset]
+
+              unless offset_index
+                offsets << new_offset
+                offset_index = offsets.length - 1
+                defined_offsets[new_offset] = offset_index
+              end
+
+              transition[:offset] = offset_index
+            end
+          else
+            base_utc_offset_from_previous = observed_utc_offset
+          end
+        end
+
+        first_offset_index
+      end
+
+      # Parses a zoneinfo file and returns either a {TimezoneOffset} that is
+      # constantly observed or an `Array` of {TimezoneTransition}s.
+      #
+      # @param file [IO] the file to be read.
+      # @return [Object] either a {TimezoneOffset} or an `Array` of
+      #   {TimezoneTransition}s.
+      # @raise [InvalidZoneinfoFile] if the file is not a valid zoneinfo file.
+      def parse(file)
+        magic, version, ttisgmtcnt, ttisstdcnt, leapcnt, timecnt, typecnt, charcnt =
+          check_read(file, 44).unpack('a4 a x15 NNNNNN')
+
+        if magic != 'TZif'
+          raise InvalidZoneinfoFile, "The file '#{file.path}' does not start with the expected header."
+        end
+
+        if version == '2' || version == '3'
+          # Skip the first 32-bit section and read the header of the second 64-bit section
+          file.seek(timecnt * 5 + typecnt * 6 + charcnt + leapcnt * 8 + ttisgmtcnt + ttisstdcnt, IO::SEEK_CUR)
+
+          prev_version = version
+
+          magic, version, ttisgmtcnt, ttisstdcnt, leapcnt, timecnt, typecnt, charcnt =
+            check_read(file, 44).unpack('a4 a x15 NNNNNN')
+
+          unless magic == 'TZif' && (version == prev_version)
+            raise InvalidZoneinfoFile, "The file '#{file.path}' contains an invalid 64-bit section header."
+          end
+
+          using_64bit = true
+        elsif version != '3' && version != '2' && version != "\0"
+          raise InvalidZoneinfoFile, "The file '#{file.path}' contains a version of the zoneinfo format that is not currently supported."
+        else
+          using_64bit = false
+        end
+
+        unless leapcnt == 0
+          raise InvalidZoneinfoFile, "The file '#{file.path}' contains leap second data. TZInfo requires zoneinfo files that omit leap seconds."
+        end
+
+        transitions = if using_64bit
+          timecnt.times.map do |i|
+            high, low = check_read(file, 8).unpack('NN'.freeze)
+            transition_time = make_signed_int64(high, low)
+            {at: transition_time}
+          end
+        else
+          timecnt.times.map do |i|
+            transition_time = make_signed_int32(check_read(file, 4).unpack('N'.freeze)[0])
+            {at: transition_time}
+          end
+        end
+
+        check_read(file, timecnt).unpack('C*'.freeze).each_with_index do |localtime_type, i|
+          raise InvalidZoneinfoFile, "Invalid offset referenced by transition in file '#{file.path}'." if localtime_type >= typecnt
+          transitions[i][:offset] = localtime_type
+        end
+
+        offsets = typecnt.times.map do |i|
+          gmtoff, isdst, abbrind = check_read(file, 6).unpack('NCC'.freeze)
+          gmtoff = make_signed_int32(gmtoff)
+          isdst = isdst == 1
+          {observed_utc_offset: gmtoff, is_dst: isdst, abbr_index: abbrind}
+        end
+
+        abbrev = check_read(file, charcnt)
+
+        # Derive the offsets from standard time (std_offset).
+        first_offset_index = derive_offsets(transitions, offsets)
+
+        offsets = offsets.map do |o|
+          observed_utc_offset = o[:observed_utc_offset]
+          base_utc_offset = o[:base_utc_offset]
+
+          if base_utc_offset
+            # DST offset with base_utc_offset derived by derive_offsets.
+            std_offset = observed_utc_offset - base_utc_offset
+          elsif o[:is_dst]
+            # DST offset unreferenced by a transition (offset in use before the
+            # first transition). No derived base UTC offset, so assume 1 hour
+            # DST.
+            base_utc_offset = observed_utc_offset - 3600
+            std_offset = 3600
+          else
+            # Non-DST offset.
+            base_utc_offset = observed_utc_offset
+            std_offset = 0
+          end
+
+          abbrev_start = o[:abbr_index]
+          raise InvalidZoneinfoFile, "Abbreviation index is out of range in file '#{file.path}'." unless abbrev_start < abbrev.length
+
+          abbrev_end = abbrev.index("\0", abbrev_start)
+          raise InvalidZoneinfoFile, "Missing abbreviation null terminator in file '#{file.path}'." unless abbrev_end
+
+          abbr = @string_deduper.dedupe(abbrev[abbrev_start...abbrev_end].force_encoding(Encoding::UTF_8).untaint)
+
+          TimezoneOffset.new(base_utc_offset, std_offset, abbr)
+        end
+
+        first_offset = offsets[first_offset_index]
+
+
+        if transitions.empty?
+          first_offset
+        else
+          previous_offset = first_offset
+          previous_at = nil
+
+          transitions.map do |t|
+            offset = offsets[t[:offset]]
+            at = t[:at]
+            raise InvalidZoneinfoFile, "Transition at #{at} is not later than the previous transition at #{previous_at} in file '#{file.path}'." if previous_at && previous_at >= at
+            tt = TimezoneTransition.new(offset, previous_offset, at)
+            previous_offset = offset
+            previous_at = at
+            tt
+          end
+        end
+      end
+    end
+    private_constant :ZoneinfoReader
+  end
+end

data/lib/tzinfo/data_sources.rb

@@ -0,0 +1,8 @@
+# encoding: UTF-8
+
+module TZInfo
+  # {DataSource} implementations and classes used by {DataSource}
+  # implementations.
+  module DataSources
+  end
+end

data/lib/tzinfo/data_timezone.rb

@@ -1,56 +1,42 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
 module TZInfo
+  # Represents time zones that are defined by rules that set out when
+  # transitions occur.
+  class DataTimezone < InfoTimezone
+    # (see Timezone#period_for)
+    def period_for(time)
+      raise ArgumentError, 'time must be specified' unless time
+      timestamp = Timestamp.for(time)
+      raise ArgumentError, 'time must have a specified utc_offset' unless timestamp.utc_offset
+      info.period_for(timestamp)
+    end
 
-  # A Timezone based on a DataTimezoneInfo.
-  #
-  # @private
-  class DataTimezone < InfoTimezone #:nodoc:
-    
-    # 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).        
-    #
-    # If no TimezonePeriod could be found, PeriodNotFound is raised.
-    def period_for_utc(utc)
-      info.period_for_utc(utc)
+    # (see Timezone#periods_for_local)
+    def periods_for_local(local_time)
+      raise ArgumentError, 'local_time must be specified' unless local_time
+      info.periods_for_local(Timestamp.for(local_time, :ignore))
     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.
-    # Raises PeriodNotFound if no periods are found for the given time.
-    def periods_for_local(local)
-      info.periods_for_local(local)
+
+    # (see Timezone#transitions_up_to)
+    def transitions_up_to(to, from = nil)
+      raise ArgumentError, 'to must be specified' unless to
+      to_timestamp = Timestamp.for(to)
+      from_timestamp = from && Timestamp.for(from)
+
+      begin
+        info.transitions_up_to(to_timestamp, from_timestamp)
+      rescue ArgumentError => e
+        raise ArgumentError, e.message.gsub('_timestamp', '')
+      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).
+
+    # Returns the canonical {Timezone} instance for this {DataTimezone}.
     #
-    # 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)
-      info.transitions_up_to(utc_to, utc_from)
-    end
-    
-    # Returns the canonical zone for this Timezone.
+    # For a {DataTimezone}, this is always `self`.
     #
-    # For a DataTimezone, this is always self.
+    # @return [Timezone] `self`.
     def canonical_zone
       self
     end

data/lib/tzinfo/datetime_with_offset.rb

@@ -0,0 +1,153 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require 'date'
+
+module TZInfo
+  # A subclass of `DateTime` used to represent local times. {DateTimeWithOffset}
+  # holds a reference to the related {TimezoneOffset} and overrides various
+  # methods to return results appropriate for the {TimezoneOffset}. Certain
+  # operations will clear the associated {TimezoneOffset} (if the
+  # {TimezoneOffset} would not necessarily be valid for the result). Once the
+  # {TimezoneOffset} has been cleared, {DateTimeWithOffset} behaves identically
+  # to `DateTime`.
+  #
+  # Arithmetic performed on {DateTimeWithOffset} instances is _not_ time
+  # zone-aware. Regardless of whether transitions in the time zone are crossed,
+  # results of arithmetic operations will always maintain the same offset from
+  # UTC (`offset`). The associated {TimezoneOffset} will aways be cleared.
+  class DateTimeWithOffset < DateTime
+    include WithOffset
+
+    # @return [TimezoneOffset] the {TimezoneOffset} associated with this
+    #   instance.
+    attr_reader :timezone_offset
+
+    # Sets the associated {TimezoneOffset}.
+    #
+    # @param timezone_offset [TimezoneOffset] a {TimezoneOffset} valid at the
+    #   time and for the offset of this {DateTimeWithOffset}.
+    # @return [DateTimeWithOffset] `self`.
+    # @raise [ArgumentError] if `timezone_offset` is `nil`.
+    # @raise [ArgumentError] if `timezone_offset.observed_utc_offset` does not
+    #   equal `self.offset * 86400`.
+    def set_timezone_offset(timezone_offset)
+      raise ArgumentError, 'timezone_offset must be specified' unless timezone_offset
+      raise ArgumentError, 'timezone_offset.observed_utc_offset does not match self.utc_offset' if offset * 86400 != timezone_offset.observed_utc_offset
+      @timezone_offset = timezone_offset
+      self
+    end
+
+    # An overridden version of `DateTime#to_time` that, if there is an
+    # associated {TimezoneOffset}, returns a {DateTimeWithOffset} with that
+    # offset.
+    #
+    # @return [Time] if there is an associated {TimezoneOffset}, a
+    #   {TimeWithOffset} representation of this {DateTimeWithOffset}, otherwise
+    #   a `Time` representation.
+    def to_time
+      if_timezone_offset(super) do |o,t|
+        # Ruby 2.4.0 changed the behaviour of to_time so that it preserves the
+        # offset instead of converting to the system local timezone.
+        #
+        # When self has an associated TimezonePeriod, this implementation will
+        # preserve the offset on all versions of Ruby.
+        TimeWithOffset.at(t.to_i, t.subsec * 1_000_000).set_timezone_offset(o)
+      end
+    end
+
+    # An overridden version of `DateTime#downto` that clears the associated
+    # {TimezoneOffset} of the returned or yielded instances.
+    def downto(min)
+      if block_given?
+        super {|dt| yield dt.clear_timezone_offset }
+      else
+        enum = super
+        enum.each {|dt| dt.clear_timezone_offset }
+        enum
+      end
+    end
+
+    # An overridden version of `DateTime#england` that preserves the associated
+    # {TimezoneOffset}.
+    #
+    # @return [DateTime]
+    def england
+      # super doesn't call #new_start on MRI, so each method has to be
+      # individually overridden.
+      if_timezone_offset(super) {|o,dt| dt.set_timezone_offset(o) }
+    end
+
+    # An overridden version of `DateTime#gregorian` that preserves the
+    # associated {TimezoneOffset}.
+    #
+    # @return [DateTime]
+    def gregorian
+      # super doesn't call #new_start on MRI, so each method has to be
+      # individually overridden.
+      if_timezone_offset(super) {|o,dt| dt.set_timezone_offset(o) }
+    end
+
+    # An overridden version of `DateTime#italy` that preserves the associated
+    # {TimezoneOffset}.
+    #
+    # @return [DateTime]
+    def italy
+      # super doesn't call #new_start on MRI, so each method has to be
+      # individually overridden.
+      if_timezone_offset(super) {|o,dt| dt.set_timezone_offset(o) }
+    end
+
+    # An overridden version of `DateTime#julian` that preserves the associated
+    # {TimezoneOffset}.
+    #
+    # @return [DateTime]
+    def julian
+      # super doesn't call #new_start on MRI, so each method has to be
+      # individually overridden.
+      if_timezone_offset(super) {|o,dt| dt.set_timezone_offset(o) }
+    end
+
+    # An overridden version of `DateTime#new_start` that preserves the
+    # associated {TimezoneOffset}.
+    #
+    # @return [DateTime]
+    def new_start(start = Date::ITALY)
+      if_timezone_offset(super) {|o,dt| dt.set_timezone_offset(o) }
+    end
+
+    # An overridden version of `DateTime#step` that clears the associated
+    # {TimezoneOffset} of the returned or yielded instances.
+    def step(limit, step = 1)
+      if block_given?
+        super {|dt| yield dt.clear_timezone_offset }
+      else
+        enum = super
+        enum.each {|dt| dt.clear_timezone_offset }
+        enum
+      end
+    end
+
+    # An overridden version of `DateTime#upto` that clears the associated
+    # {TimezoneOffset} of the returned or yielded instances.
+    def upto(max)
+      if block_given?
+        super {|dt| yield dt.clear_timezone_offset }
+      else
+        enum = super
+        enum.each {|dt| dt.clear_timezone_offset }
+        enum
+      end
+    end
+
+    protected
+
+    # Clears the associated {TimezoneOffset}.
+    #
+    # @return [DateTimeWithOffset] `self`.
+    def clear_timezone_offset
+      @timezone_offset = nil
+      self
+    end
+  end
+end

data/lib/tzinfo/format1/country_definer.rb

@@ -0,0 +1,17 @@
+# encoding: UTF-8
+
+module TZInfo
+  module Format1
+    # Instances of {Format1::CountryDefiner} are yielded to the format 1 version
+    # of `TZInfo::Data::Indexes::Countries` by {CountryIndexDefinition} to allow
+    # the zones of a country to be specified.
+    #
+    # @private
+    class CountryDefiner < Format2::CountryDefiner #:nodoc:
+      # Initializes a new {CountryDefiner}.
+      def initialize(identifier_deduper, description_deduper)
+        super(nil, identifier_deduper, description_deduper)
+      end
+    end
+  end
+end

data/lib/tzinfo/format1/country_index_definition.rb

@@ -0,0 +1,64 @@
+# encoding: UTF-8
+
+module TZInfo
+  module Format1
+    # The format 1 TZInfo::Data country index file includes
+    # {Format1::CountryIndexDefinition}, which provides a
+    # {CountryIndexDefinition::ClassMethods#country country} method used to
+    # define each country in the index.
+    #
+    # @private
+    module CountryIndexDefinition #:nodoc:
+      # Adds class methods to the includee and initializes class instance
+      # variables.
+      #
+      # @param base [Module] the includee.
+      def self.append_features(base)
+        super
+        base.extend(ClassMethods)
+        base.instance_eval { @countries = {} }
+      end
+
+      # Class methods for inclusion.
+      #
+      # @private
+      module ClassMethods #:nodoc:
+        # @return [Hash<String, DataSources::CountryInfo>] a frozen `Hash`
+        #   of all the countries that have been defined in the index keyed by
+        #   their codes.
+        def countries
+          @description_deduper = nil
+          @countries.freeze
+        end
+
+        private
+
+        # Defines a country with an ISO 3166-1 alpha-2 country code and name.
+        #
+        # @param code [String] the ISO 3166-1 alpha-2 country code.
+        # @param name [String] the name of the country.
+        # @yield [definer] (optional) to obtain the time zones for the country.
+        # @yieldparam definer [CountryDefiner] a {CountryDefiner} instance.
+        def country(code, name)
+          @description_deduper ||= StringDeduper.new
+
+          zones = if block_given?
+            definer = CountryDefiner.new(StringDeduper.global, @description_deduper)
+            yield definer
+            definer.timezones
+          else
+            []
+          end
+
+          @countries[code.freeze] = DataSources::CountryInfo.new(code, name, zones)
+        end
+      end
+    end
+  end
+
+  # Alias used by TZInfo::Data format1 releases.
+  #
+  # @private
+  CountryIndexDefinition = Format1::CountryIndexDefinition #:nodoc:
+  private_constant :CountryIndexDefinition
+end

data/lib/tzinfo/format1/timezone_definer.rb

@@ -0,0 +1,64 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  module Format1
+    # Instances of {Format1::TimezoneDefiner} are yielded to TZInfo::Data
+    # format 1 modules by {TimezoneDefinition} to allow the offsets and
+    # transitions of the time zone to be specified.
+    #
+    # @private
+    class TimezoneDefiner < Format2::TimezoneDefiner #:nodoc:
+      undef_method :subsequent_rules
+
+      # Defines an offset.
+      #
+      # @param id [Symbol] an arbitrary value used identify the offset in
+      #   subsequent calls to transition. It must be unique.
+      # @param utc_offset [Integer] the base offset from UTC of the zone in
+      #   seconds. This does not include daylight savings time.
+      # @param std_offset [Integer] the daylight savings offset from the base
+      #   offset in seconds. Typically either 0 or 3600.
+      # @param abbreviation [Symbol] an abbreviation for the offset, for
+      #   example, `:EST` or `:EDT`.
+      # @raise [ArgumentError] if another offset has already been defined with
+      #   the given id.
+      def offset(id, utc_offset, std_offset, abbreviation)
+        super(id, utc_offset, std_offset, abbreviation.to_s)
+      end
+
+      # Defines a transition to a given offset.
+      #
+      # Transitions must be defined in increasing time order.
+      #
+      # @param year [Integer] the UTC year in which the transition occurs. Used
+      #   in earlier versions of TZInfo, but now ignored.
+      # @param month [Integer] the UTC month in which the transition occurs.
+      #   Used in earlier versions of TZInfo, but now ignored.
+      # @param offset_id [Symbol] references the id of a previously defined
+      #   offset (see #offset).
+      # @param timestamp_value [Integer] the time the transition occurs as an
+      #   Integer number of seconds since 1970-01-01 00:00:00 UTC ignoring leap
+      #   seconds (i.e. each day is treated as if it were 86,400 seconds long).
+      # @param datetime_numerator [Integer] the time of the transition as the
+      #   numerator of the `Rational` returned by `DateTime#ajd`. Used in
+      #   earlier versions of TZInfo, but now ignored.
+      # @param datetime_denominator [Integer] the time of the transition as the
+      #   denominator of the `Rational` returned by `DateTime#ajd`. Used in
+      #   earlier versions of TZInfo, but now ignored.
+      # @raise [ArgumentError] if `offset_id` does not reference a defined
+      #   offset.
+      # @raise [ArgumentError] if `timestamp_value` is not greater than the
+      #   `timestamp_value` of the previously defined transition.
+      # @raise [ArgumentError] if `datetime_numerator` is specified, but
+      #   `datetime_denominator` is not. In older versions of TZInfo, it was
+      #   possible to define a transition with the `DateTime` numerator as the
+      #   4th parameter and the denominator as the 5th parameter. This style of
+      #   definition is not used in released versions of TZInfo::Data.
+      def transition(year, month, offset_id, timestamp_value, datetime_numerator = nil, datetime_denominator = nil)
+        raise ArgumentError, 'DateTime-only transitions are not supported' if datetime_numerator && !datetime_denominator
+        super(offset_id, timestamp_value)
+      end
+    end
+  end
+end