tzinfo 1.2.11 → 2.0.0

data/lib/tzinfo/data_sources/country_info.rb

@@ -0,0 +1,42 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  module DataSources
+    # Represents a country and references to its time zones as returned by a
+    # {DataSource}.
+    class CountryInfo
+      # @return [String] the ISO 3166-1 alpha-2 country code.
+      attr_reader :code
+
+      # @return [String] the name of the country.
+      attr_reader :name
+
+      # @return [Array<CountryTimezone>] the time zones observed in the country.
+      attr_reader :zones
+
+      # Initializes a new {CountryInfo}. The passed in `code`, `name` and
+      # `zones` instances will be frozen.
+      #
+      # @param code [String] an ISO 3166-1 alpha-2 country code.
+      # @param name [String] the name of the country.
+      # @param zones [Array<CountryTimezone>] the time zones observed in the
+      #   country.
+      # @raise [ArgumentError] if `code`, `name` or `zones` is `nil`.
+      def initialize(code, name, zones)
+        raise ArgumentError, 'code must be specified' unless code
+        raise ArgumentError, 'name must be specified' unless name
+        raise ArgumentError, 'zones must be specified' unless zones
+        @code = code.freeze
+        @name = name.freeze
+        @zones = zones.freeze
+      end
+
+      # @return [String] the internal object state as a programmer-readable
+      #   `String`.
+      def inspect
+        "#<#{self.class}: #@code>"
+      end
+    end
+  end
+end

data/lib/tzinfo/data_sources/data_timezone_info.rb

@@ -0,0 +1,91 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  module DataSources
+    # The base class for time zones defined as either a series of transitions
+    # ({TransitionsDataTimezoneInfo}) or a constantly observed offset
+    # ({ConstantOffsetDataTimezoneInfo}).
+    #
+    # @abstract Data sources return instances of {DataTimezoneInfo} subclasses.
+    class DataTimezoneInfo < TimezoneInfo
+      # @param timestamp [Timestamp] a {Timestamp} with a specified
+      #   {Timestamp#utc_offset utc_offset}.
+      # @return [TimezonePeriod] the {TimezonePeriod} observed at the time
+      #   specified by `timestamp`.
+      # @raise [ArgumentError] may be raised if `timestamp` is `nil` or does not
+      #   have a specified {Timestamp#utc_offset utc_offset}.
+      def period_for(timestamp)
+        raise_not_implemented('period_for')
+      end
+
+      # Returns an `Array` containing the {TimezonePeriod TimezonePeriods} that
+      # could be observed at the local time specified by `local_timestamp`. The
+      # results are are ordered by increasing UTC start date. An empty `Array`
+      # is returned if no periods are found for the given local time.
+      #
+      # @param local_timestamp [Timestamp] a {Timestamp} representing a local
+      #   time - must have an unspecified {Timestamp#utc_offset utc_offset}.
+      # @return [Array<TimezonePeriod>] an `Array` containing the
+      #   {TimezonePeriod TimezonePeriods} that could be observed at the local
+      #   time specified by `local_timestamp`.
+      # @raise [ArgumentError] may be raised if `local_timestamp` is `nil`, or
+      #   has a specified {Timestamp#utc_offset utc_offset}.
+      def periods_for_local(local_timestamp)
+        raise_not_implemented('periods_for_local')
+      end
+
+      # Returns an `Array` of {TimezoneTransition} instances representing the
+      # times where the UTC offset of the time zone changes.
+      #
+      # Transitions are returned up to a given {Timestamp} (`to_timestamp`).
+      #
+      # A from {Timestamp} may also be supplied using the `from_timestamp`
+      # parameter. If `from_timestamp` is specified, only transitions from that
+      # time onwards will be returned.
+      #
+      # Comparisons with `to_timestamp` are exclusive. Comparisons with
+      # `from_timestamp` are inclusive. If a transition falls precisely on
+      # `to_timestamp`, it will be excluded. If a transition falls on
+      # `from_timestamp`, it will be included.
+      #
+      # Transitions returned are ordered by when they occur, from earliest to
+      # latest.
+      #
+      # @param to_timestamp [Timestamp] a {Timestamp} with a specified
+      #   {Timestamp#utc_offset utc_offset}. Transitions are returned if they
+      #   occur before this time.
+      # @param from_timestamp [Timestamp] an optional {Timestamp} with a
+      #   specified {Timestamp#utc_offset utc_offset}. If specified, transitions
+      #   are returned if they occur at or after this time.
+      # @return [Array<TimezoneTransition>] an `Array` of {TimezoneTransition}
+      #   instances representing the times where the UTC offset of the time zone
+      #   changes.
+      # @raise [ArgumentError] may be raised if `to_timestamp` is `nil` or does
+      #   not have a specified {Timestamp#utc_offset utc_offset}.
+      # @raise [ArgumentError] may be raised if `from_timestamp` is specified
+      #   but does not have a specified {Timestamp#utc_offset utc_offset}.
+      # @raise [ArgumentError] may be raised if `from_timestamp` is specified
+      #   but is not earlier than or at the same time as `to_timestamp`.
+      def transitions_up_to(to_timestamp, from_timestamp = nil)
+        raise_not_implemented('transitions_up_to')
+      end
+
+      # @return [DataTimezone] a new {DataTimezone} instance for the time zone
+      #   represented by this {DataTimezoneInfo}.
+      def create_timezone
+        DataTimezone.new(self)
+      end
+
+      private
+
+      # Raises a {NotImplementedError} to indicate that the base class is
+      # incorrectly being used directly.
+      #
+      # raise [NotImplementedError] always.
+      def raise_not_implemented(method_name)
+        raise NotImplementedError, "Subclasses must override #{method_name}"
+      end
+    end
+  end
+end

data/lib/tzinfo/data_sources/linked_timezone_info.rb

@@ -0,0 +1,33 @@
+# encoding: UTF-8
+
+module TZInfo
+  module DataSources
+    # Represents a time zone that is defined as a link to or alias of another
+    # zone.
+    class LinkedTimezoneInfo < TimezoneInfo
+      # @return [String] the identifier of the time zone that provides the data
+      # (that this zone links to or is an alias for).
+      attr_reader :link_to_identifier
+
+      # Initializes a new {LinkedTimezoneInfo}. The passed in `identifier` and
+      # `link_to_identifier` instances will be frozen.
+      #
+      # @param identifier [String] the identifier of the time zone.
+      # @param link_to_identifier [String] the identifier of the time zone that
+      #   this zone link to.
+      # @raise [ArgumentError] if `identifier` or `link_to_identifier` are
+      # `nil`.
+      def initialize(identifier, link_to_identifier)
+        super(identifier)
+        raise ArgumentError, 'link_to_identifier must be specified' unless link_to_identifier
+        @link_to_identifier = link_to_identifier.freeze
+      end
+
+      # @return [LinkedTimezone] a new {LinkedTimezone} instance for the time
+      #   zone represented by this {LinkedTimezoneInfo}.
+      def create_timezone
+        LinkedTimezone.new(self)
+      end
+    end
+  end
+end

data/lib/tzinfo/data_sources/ruby_data_source.rb

@@ -0,0 +1,141 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  module DataSources
+    # A {TZInfoDataNotFound} exception is raised if the tzinfo-data gem could
+    # not be found (i.e. `require 'tzinfo/data'` failed) when selecting the Ruby
+    # data source.
+    class TZInfoDataNotFound < StandardError
+    end
+
+    # A DataSource implementation that loads data from the set of Ruby modules
+    # included in the tzinfo-data gem.
+    #
+    # TZInfo will use {RubyDataSource} by default if the tzinfo-data gem
+    # is available on the load path. It can also be selected by calling
+    # {DataSource.set} as follows:
+    #
+    #     TZInfo::DataSource.set(:ruby)
+    class RubyDataSource < DataSource
+      # (see DataSource#data_timezone_identifiers)
+      attr_reader :data_timezone_identifiers
+
+      # (see DataSource#linked_timezone_identifiers)
+      attr_reader :linked_timezone_identifiers
+
+      # (see DataSource#country_codes)
+      attr_reader :country_codes
+
+      # Initializes a new {RubyDataSource} instance.
+      #
+      # @raise [TZInfoDataNotFound] if the tzinfo-data gem could not be found
+      #   (i.e. `require 'tzinfo/data'` failed).
+      def initialize
+        super
+
+        begin
+          require('tzinfo/data')
+        rescue LoadError
+          raise TZInfoDataNotFound, "The tzinfo-data gem could not be found (require 'tzinfo/data' failed)."
+        end
+
+        if TZInfo::Data.const_defined?(:LOCATION)
+          # Format 2
+          @base_path = File.join(TZInfo::Data::LOCATION, 'tzinfo', 'data')
+        else
+          # Format 1
+          data_file = File.join('', 'tzinfo', 'data.rb')
+          path = $".reverse_each.detect {|p| p.end_with?(data_file) }
+          if path
+            @base_path = File.join(File.dirname(path), 'data')
+          else
+            @base_path = 'tzinfo/data'
+          end
+        end
+
+        require_index('timezones')
+        require_index('countries')
+
+        @data_timezone_identifiers = Data::Indexes::Timezones.data_timezones
+        @linked_timezone_identifiers = Data::Indexes::Timezones.linked_timezones
+        @countries = Data::Indexes::Countries.countries
+        @country_codes = @countries.keys.sort!.freeze
+      end
+
+      # (see DataSource#to_s)
+      def to_s
+        "Ruby DataSource: #{version_info}"
+      end
+
+      # (see DataSource#inspect)
+      def inspect
+        "#<TZInfo::DataSources::RubyDataSource: #{version_info}>"
+      end
+
+      protected
+
+      # Returns a {TimezoneInfo} instance for the given time zone identifier.
+      # The result will either be a {ConstantOffsetDataTimezoneInfo}, a
+      # {TransitionsDataTimezoneInfo} or a {LinkedTimezoneInfo} depending on the
+      # type of time zone.
+      #
+      # @param identifier [String] A time zone identifier.
+      # @return [TimezoneInfo] a {TimezoneInfo} instance for the given time zone
+      #   identifier.
+      # @raise [InvalidTimezoneIdentifier] if the time zone is not found or the
+      #   identifier is invalid.
+      def load_timezone_info(identifier)
+        valid_identifier = validate_timezone_identifier(identifier)
+        split_identifier = valid_identifier.gsub(/-/, '__m__').gsub(/\+/, '__p__').split('/')
+
+        begin
+          require_definition(split_identifier)
+
+          m = Data::Definitions
+          split_identifier.each {|part| m = m.const_get(part) }
+          m.get
+        rescue LoadError, NameError => e
+          raise InvalidTimezoneIdentifier, "#{e.message.encode(Encoding::UTF_8)} (loading #{valid_identifier})"
+        end
+      end
+
+      # (see DataSource#load_country_info)
+      def load_country_info(code)
+        lookup_country_info(@countries, code)
+      end
+
+      private
+
+      # Requires a zone definition by its identifier (split on /).
+      #
+      # @param identifier [Array<string>] the component parts of a time zone
+      #   identifier (split on /). This must have already been validated.
+      def require_definition(identifier)
+        require_data(*(['definitions'] + identifier))
+      end
+
+      # Requires an index by its name.
+      #
+      # @param name [String] an index name.
+      def require_index(name)
+        require_data(*['indexes', name])
+      end
+
+      # Requires a file from tzinfo/data.
+      #
+      # @param file [Array<String>] a relative path to a file to be required.
+      def require_data(*file)
+        require(File.join(@base_path, *file))
+      end
+
+      # @return [String] a `String` containing TZInfo::Data version infomation
+      #   for inclusion in the #to_s and #inspect output.
+      def version_info
+        # The TZInfo::Data::VERSION constant is only available from v1.2014.8
+        # onwards.
+        "tzdb v#{TZInfo::Data::Version::TZDATA}#{TZInfo::Data.const_defined?(:VERSION) ? ", tzinfo-data v#{TZInfo::Data::VERSION}" : ''}"
+      end
+    end
+  end
+end

data/lib/tzinfo/data_sources/timezone_info.rb

@@ -0,0 +1,47 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  module DataSources
+    # Represents a time zone defined by a data source.
+    #
+    # @abstract Data sources return instances of {TimezoneInfo} subclasses.
+    class TimezoneInfo
+      # @return [String] the identifier of the time zone.
+      attr_reader :identifier
+
+      # Initializes a new TimezoneInfo. The passed in `identifier` instance will
+      # be frozen.
+      #
+      # @param identifier [String] the identifier of the time zone.
+      # @raise [ArgumentError] if `identifier` is `nil`.
+      def initialize(identifier)
+        raise ArgumentError, 'identifier must be specified' unless identifier
+        @identifier = identifier.freeze
+      end
+
+      # @return [String] the internal object state as a programmer-readable
+      #   `String`.
+      def inspect
+        "#<#{self.class}: #@identifier>"
+      end
+
+      # @return [Timezone] a new {Timezone} instance for the time zone
+      #   represented by this {TimezoneInfo}.
+      def create_timezone
+        raise_not_implemented('create_timezone')
+      end
+
+      private
+
+      # Raises a {NotImplementedError}.
+      #
+      # @param method_name [String] the name of the method that must be
+      #   overridden.
+      # @raise NotImplementedError always.
+      def raise_not_implemented(method_name)
+        raise NotImplementedError, "Subclasses must override #{method_name}"
+      end
+    end
+  end
+end

data/lib/tzinfo/data_sources/transitions_data_timezone_info.rb

@@ -0,0 +1,214 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  module DataSources
+    # Represents a data time zone defined by a list of transitions that change
+    # the locally observed time.
+    class TransitionsDataTimezoneInfo < DataTimezoneInfo
+      # @return [Array<TimezoneTransition>] the transitions that define this
+      #   time zone in order of ascending timestamp.
+      attr_reader :transitions
+
+      # Initializes a new {TransitionsDataTimezoneInfo}.
+      #
+      # The passed in `identifier` instance will be frozen. A reference to the
+      # passed in `Array` will be retained.
+      #
+      # The `transitions` `Array` must be sorted in order of ascending
+      # timestamp. Each transition must have a
+      # {TimezoneTransition#timestamp_value timestamp_value} that is greater
+      # than the {TimezoneTransition#timestamp_value timestamp_value} of the
+      # prior transition.
+      #
+      # @param identifier [String] the identifier of the time zone.
+      # @param transitions [Array<TimezoneTransitions>] an `Array` of
+      #   transitions that each indicate when a change occurs in the locally
+      #   observed time.
+      # @raise [ArgumentError] if `identifier` is `nil`.
+      # @raise [ArgumentError] if `transitions` is `nil`.
+      # @raise [ArgumentError] if `transitions` is an empty `Array`.
+      def initialize(identifier, transitions)
+        super(identifier)
+        raise ArgumentError, 'transitions must be specified' unless transitions
+        raise ArgumentError, 'transitions must not be an empty Array' if transitions.empty?
+        @transitions = transitions.freeze
+      end
+
+      # (see DataTimezoneInfo#period_for)
+      def period_for(timestamp)
+        raise ArgumentError, 'timestamp must be specified' unless timestamp
+        raise ArgumentError, 'timestamp must have a specified utc_offset' unless timestamp.utc_offset
+
+        timestamp_value = timestamp.value
+
+        index = find_minimum_transition {|t| t.timestamp_value >= timestamp_value }
+
+        if index
+          transition = @transitions[index]
+
+          if transition.timestamp_value == timestamp_value
+            # timestamp occurs within the second of the found transition, so is
+            # the transition that starts the period.
+            start_transition = transition
+            end_transition = @transitions[index + 1]
+          else
+            # timestamp occurs before the second of the found transition, so is
+            # the transition that ends the period.
+            start_transition = index == 0 ? nil : @transitions[index - 1]
+            end_transition = transition
+          end
+        else
+          start_transition = @transitions.last
+          end_transition = nil
+        end
+
+        TransitionsTimezonePeriod.new(start_transition, end_transition)
+      end
+
+      # (see DataTimezoneInfo#periods_for_local)
+      def periods_for_local(local_timestamp)
+        raise ArgumentError, 'local_timestamp must be specified' unless local_timestamp
+        raise ArgumentError, 'local_timestamp must have an unspecified utc_offset' if local_timestamp.utc_offset
+
+        local_timestamp_value = local_timestamp.value
+        latest_possible_utc_value = local_timestamp_value + 86400
+        earliest_possible_utc_value = local_timestamp_value - 86400
+
+        # Find the index of the first transition that occurs after a latest
+        # possible UTC representation of the local timestamp and then search
+        # backwards until an earliest possible UTC representation.
+
+        index = find_minimum_transition {|t| t.timestamp_value >= latest_possible_utc_value }
+
+        # No transitions after latest_possible_utc_value, set to max index + 1
+        # to search backwards including the period after the last transition
+        index = @transitions.length unless index
+
+        result = []
+
+        index.downto(0) do |i|
+          start_transition = i > 0 ? @transitions[i - 1] : nil
+          end_transition = @transitions[i]
+          offset = start_transition ? start_transition.offset : end_transition.previous_offset
+          utc_timestamp_value = local_timestamp_value - offset.observed_utc_offset
+
+          # It is not necessary to compare the sub-seconds because a timestamp
+          # is in the period if is >= the start transition (sub-seconds would
+          # make == become >) and if it is < the end transition (which
+          # sub-seconds cannot affect).
+          if (!start_transition || utc_timestamp_value >= start_transition.timestamp_value) && (!end_transition || utc_timestamp_value < end_transition.timestamp_value)
+            result << TransitionsTimezonePeriod.new(start_transition, end_transition)
+          elsif end_transition && end_transition.timestamp_value < earliest_possible_utc_value
+            break
+          end
+        end
+
+        result.reverse!
+      end
+
+      # (see DataTimezoneInfo#transitions_up_to)
+      def transitions_up_to(to_timestamp, from_timestamp = nil)
+        raise ArgumentError, 'to_timestamp must be specified' unless to_timestamp
+        raise ArgumentError, 'to_timestamp must have a specified utc_offset' unless to_timestamp.utc_offset
+
+        if from_timestamp
+          raise ArgumentError, 'from_timestamp must have a specified utc_offset' unless from_timestamp.utc_offset
+          raise ArgumentError, 'to_timestamp must be greater than from_timestamp' if to_timestamp <= from_timestamp
+        end
+
+        if from_timestamp
+          from_index = find_minimum_transition {|t| transition_on_or_after_timestamp?(t, from_timestamp) }
+          return [] unless from_index
+        else
+          from_index = 0
+        end
+
+        to_index = find_minimum_transition {|t| transition_on_or_after_timestamp?(t, to_timestamp) }
+
+        if to_index
+          return [] if to_index < 1
+          to_index -= 1
+        else
+          to_index = -1
+        end
+
+        @transitions[from_index..to_index]
+      end
+
+      private
+
+      # Array#bsearch_index was added in Ruby 2.3.0. Use bsearch_index to find
+      # transitions if it is available, otherwise use a Ruby implementation.
+      if [].respond_to?(:bsearch_index)
+        # Performs a binary search on {transitions} to find the index of the
+        # earliest transition satisfying a condition.
+        #
+        # @yield [transition] the caller will be yielded to to test the search
+        #   condition.
+        # @yieldparam transition [TimezoneTransition] a {TimezoneTransition}
+        #   instance from {transitions}.
+        # @yieldreturn [Boolean] `true` for the earliest transition that
+        #   satisfies the condition and return `true` for all subsequent
+        #   transitions. In all other cases, the result of the block must be
+        #   `false`.
+        # @return [Integer] the index of the earliest transition safisfying
+        #   the condition or `nil` if there are no such transitions.
+        #
+        # :nocov_no_array_bsearch_index:
+        def find_minimum_transition(&block)
+          @transitions.bsearch_index(&block)
+        end
+        # :nocov_no_array_bsearch_index:
+      else
+        # Performs a binary search on {transitions} to find the index of the
+        # earliest transition satisfying a condition.
+        #
+        # @yield [transition] the caller will be yielded to to test the search
+        #   condition.
+        # @yieldparam transition [TimezoneTransition] a {TimezoneTransition}
+        #   instance from {transitions}.
+        # @yieldreturn [Boolean] `true` for the earliest transition that
+        #   satisfies the condition and return `true` for all subsequent
+        #   transitions. In all other cases, the result of the block must be
+        #   `false`.
+        # @return [Integer] the index of the earliest transition safisfying
+        #   the condition or `nil` if there are no such transitions.
+        #
+        # :nocov_array_bsearch_index:
+        def find_minimum_transition
+          # A Ruby implementation of the find-minimum mode of Array#bsearch_index.
+          low = 0
+          high = @transitions.length
+          satisfied = false
+
+          while low < high do
+            mid = (low + high).div(2)
+            if yield @transitions[mid]
+              satisfied = true
+              high = mid
+            else
+              low = mid + 1
+            end
+          end
+
+          satisfied ? low : nil
+        end
+        # :nocov_array_bsearch_index:
+      end
+
+      # Determines if a transition occurs at or after a given {Timestamp},
+      # taking the {Timestamp#sub_second sub_second} into consideration.
+      #
+      # @param transition [TimezoneTransition] the transition to compare.
+      # @param timestamp [Timestamp] the timestamp to compare.
+      # @return [Boolean] `true` if `transition` occurs at or after `timestamp`,
+      #   otherwise `false`.
+      def transition_on_or_after_timestamp?(transition, timestamp)
+        transition_timestamp_value = transition.timestamp_value
+        timestamp_value = timestamp.value
+        transition_timestamp_value > timestamp_value || transition_timestamp_value == timestamp_value && timestamp.sub_second == 0
+      end
+    end
+  end
+end