tzinfo 1.2.9 → 2.0.4

data/lib/tzinfo/info_timezone.rb

@@ -1,30 +1,35 @@
+# encoding: UTF-8
+
 module TZInfo
 
-  # A Timezone based on a TimezoneInfo.
+  # A {Timezone} based on a {DataSources::TimezoneInfo}.
   #
-  # @private
-  class InfoTimezone < Timezone #:nodoc:
-    
-    # Constructs a new InfoTimezone with a TimezoneInfo instance.
-    def self.new(info)      
-      tz = super()
-      tz.send(:setup, info)
-      tz
+  # @abstract
+  class InfoTimezone < Timezone
+    # Initializes a new {InfoTimezone}.
+    #
+    # {InfoTimezone} instances should not normally be created directly. Use
+    # the {Timezone.get} method to obtain {Timezone} instances.
+    #
+    # @param info [DataSources::TimezoneInfo] a {DataSources::TimezoneInfo}
+    #   instance supplied by a {DataSource} that will be used as the source of
+    #   data for this {InfoTimezone}.
+    def initialize(info)
+      super()
+      @info = info
     end
-    
-    # The identifier of the timezone, e.g. "Europe/Paris".
+
+    # (see Timezone#identifier)
     def identifier
       @info.identifier
     end
-    
+
     protected
-      # The TimezoneInfo for this Timezone.
-      def info
-        @info
-      end
-          
-      def setup(info)
-        @info = info
-      end
-  end    
+
+    # @return [DataSources::TimezoneInfo] the {DataSources::TimezoneInfo} this
+    #   {InfoTimezone} is based on.
+    def info
+      @info
+    end
+  end
 end

data/lib/tzinfo/linked_timezone.rb

@@ -1,63 +1,44 @@
+# encoding: UTF-8
+
 module TZInfo
+  # Represents time zones that are defined as a link to or alias for another
+  # time zone.
+  class LinkedTimezone < InfoTimezone
+    # Initializes a new {LinkedTimezone}.
+    #
+    # {LinkedTimezone} instances should not normally be created directly. Use
+    # the {Timezone.get} method to obtain {Timezone} instances.
+    #
+    # @param info [DataSources::LinkedTimezoneInfo] a
+    #   {DataSources::LinkedTimezoneInfo} instance supplied by a {DataSource}
+    #   that will be used as the source of data for this {LinkedTimezone}.
+    def initialize(info)
+      super
+      @linked_timezone = Timezone.get(info.link_to_identifier)
+    end
 
-  # A Timezone based on a LinkedTimezoneInfo.
-  #
-  # @private
-  class LinkedTimezone < 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)
-      @linked_timezone.period_for_utc(utc)
+    # (see Timezone#period_for)
+    def period_for(time)
+      @linked_timezone.period_for(time)
     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)
-      @linked_timezone.periods_for_local(local)
+
+    # (see Timezone#periods_for_local)
+    def periods_for_local(local_time)
+      @linked_timezone.periods_for_local(local_time)
     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)
-      @linked_timezone.transitions_up_to(utc_to, utc_from)
+
+    # (see Timezone#transitions_up_to)
+    def transitions_up_to(to, from = nil)
+      @linked_timezone.transitions_up_to(to, from)
     end
-    
-    # Returns the canonical zone for this Timezone.
+
+    # Returns the canonical {Timezone} instance for this {LinkedTimezone}.
+    #
+    # For a {LinkedTimezone}, this is the canonical zone of the link target.
     #
-    # For a LinkedTimezone, this is the canonical zone of the link target.
+    # @return [Timezone] the canonical {Timezone} instance for this {Timezone}.
     def canonical_zone
       @linked_timezone.canonical_zone
     end
-    
-    protected
-      def setup(info)
-        super(info)
-        @linked_timezone = Timezone.get(info.link_to_identifier)
-      end
   end
 end

data/lib/tzinfo/offset_timezone_period.rb

@@ -0,0 +1,42 @@
+# encoding: UTF-8
+
+module TZInfo
+  # Represents the infinite period of time in a time zone that constantly
+  # observes the same offset from UTC (has an unbounded start and end).
+  class OffsetTimezonePeriod < TimezonePeriod
+    # Initializes an {OffsetTimezonePeriod}.
+    #
+    # @param offset [TimezoneOffset] the offset that is constantly observed.
+    # @raise [ArgumentError] if `offset` is `nil`.
+    def initialize(offset)
+      super
+    end
+
+    # @return [TimezoneTransition] the transition that defines the start of this
+    #   {TimezonePeriod}, always `nil` for {OffsetTimezonePeriod}.
+    def start_transition
+      nil
+    end
+
+    # @return [TimezoneTransition] the transition that defines the end of this
+    #   {TimezonePeriod}, always `nil` for {OffsetTimezonePeriod}.
+    def end_transition
+      nil
+    end
+
+    # Determines if this {OffsetTimezonePeriod} is equal to another instance.
+    #
+    # @param p [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `p` is a {OffsetTimezonePeriod} with the same
+    #   {offset}, otherwise `false`.
+    def ==(p)
+      p.kind_of?(OffsetTimezonePeriod) && offset == p.offset
+    end
+    alias eql? ==
+
+    # @return [Integer] a hash based on {offset}.
+    def hash
+      offset.hash
+    end
+  end
+end

data/lib/tzinfo/string_deduper.rb

@@ -0,0 +1,118 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module TZInfo
+  # Maintains a pool of `String` instances. The {#dedupe} method will return
+  # either a pooled copy of a given `String` or add the instance to the pool.
+  #
+  # @private
+  class StringDeduper #:nodoc:
+    class << self
+      # @return [StringDeduper] a globally available singleton instance of
+      #   {StringDeduper}. This instance is safe for use in concurrently
+      #   executing threads.
+      attr_reader :global
+    end
+
+    # Initializes a new {StringDeduper}.
+    def initialize
+      @strings = create_hash do |h, k|
+        v = k.dup.freeze
+        h[v] = v
+      end
+    end
+
+    # @param string [String] the string to deduplicate.
+    # @return [bool] `string` if it is frozen, otherwise a frozen, possibly
+    #   pre-existing copy of `string`.
+    def dedupe(string)
+      return string if string.frozen?
+      @strings[string]
+    end
+
+    protected
+
+    # Creates a `Hash` to store pooled `String` instances.
+    #
+    # @param block [Proc] Default value block to be passed to `Hash.new`.
+    # @return [Hash] a `Hash` to store pooled `String` instances.
+    def create_hash(&block)
+      Hash.new(&block)
+    end
+  end
+  private_constant :StringDeduper
+
+  # A thread-safe version of {StringDeduper}.
+  #
+  # @private
+  class ConcurrentStringDeduper < StringDeduper #:nodoc:
+    protected
+
+    def create_hash(&block)
+      Concurrent::Map.new(&block)
+    end
+  end
+  private_constant :ConcurrentStringDeduper
+
+
+  string_unary_minus_does_dedupe = if '0'.respond_to?(:-@)
+    # :nocov_no_string_-@:
+    s1 = -('0'.dup)
+    s2 = -('0'.dup)
+    s1.object_id == s2.object_id
+    # :nocov_no_string_-@:
+  else
+    # :nocov_string_-@:
+    false
+    # :nocov_string_-@:
+  end
+
+  if string_unary_minus_does_dedupe
+    # :nocov_no_deduping_string_unary_minus:
+
+    # An implementation of {StringDeduper} using the `String#-@` method where
+    # that method performs deduplication (Ruby 2.5 and later).
+    #
+    # Note that this is slightly different to the plain {StringDeduper}
+    # implementation. In this implementation, frozen literal strings are already
+    # in the pool and are candidates for being returned, even when passed
+    # another equal frozen non-literal string. {StringDeduper} will always
+    # return frozen strings.
+    #
+    # There are also differences in encoding handling. This implementation will
+    # treat strings with different encodings as different strings.
+    # {StringDeduper} will treat strings with the compatible encodings as the
+    # same string.
+    #
+    # @private
+    class UnaryMinusGlobalStringDeduper #:nodoc:
+      # @param string [String] the string to deduplicate.
+      # @return [bool] `string` if it is frozen, otherwise a frozen, possibly
+      #   pre-existing copy of `string`.
+      def dedupe(string)
+        # String#-@ on Ruby 2.6 will dedupe a frozen non-literal String. Ruby
+        # 2.5 will just return frozen strings.
+        #
+        # The pooled implementation can't tell the difference between frozen
+        # literals and frozen non-literals, so must always return frozen String
+        # instances to avoid doing unncessary work when loading format 2
+        # TZInfo::Data modules.
+        #
+        # For compatibility with the pooled implementation, just return frozen
+        # string instances (acting like Ruby 2.5).
+        return string if string.frozen?
+        -string
+      end
+    end
+    private_constant :UnaryMinusGlobalStringDeduper
+
+    StringDeduper.instance_variable_set(:@global, UnaryMinusGlobalStringDeduper.new)
+    # :nocov_no_deduping_string_unary_minus:
+  else
+    # :nocov_deduping_string_unary_minus:
+    StringDeduper.instance_variable_set(:@global, ConcurrentStringDeduper.new)
+    # :nocov_deduping_string_unary_minus:
+  end
+end

data/lib/tzinfo/time_with_offset.rb

@@ -0,0 +1,154 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  # A subclass of `Time` used to represent local times. {TimeWithOffset} 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, {TimeWithOffset} behaves identically to `Time`.
+  #
+  # Arithmetic performed on {TimeWithOffset} 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
+  # (`utc_offset`). The associated {TimezoneOffset} will aways be cleared.
+  class TimeWithOffset < Time
+    include WithOffset
+
+    # @return [TimezoneOffset] the {TimezoneOffset} associated with this
+    #   instance.
+    attr_reader :timezone_offset
+
+    # Marks this {TimeWithOffset} as a local time with the UTC offset of a given
+    # {TimezoneOffset} and sets the associated {TimezoneOffset}.
+    #
+    # @param timezone_offset [TimezoneOffset] the {TimezoneOffset} to use to set
+    #   the offset of this {TimeWithOffset}.
+    # @return [TimeWithOffset] `self`.
+    # @raise [ArgumentError] if `timezone_offset` is `nil`.
+    def set_timezone_offset(timezone_offset)
+      raise ArgumentError, 'timezone_offset must be specified' unless timezone_offset
+      localtime(timezone_offset.observed_utc_offset)
+      @timezone_offset = timezone_offset
+      self
+    end
+
+    # An overridden version of `Time#dst?` that, if there is an associated
+    # {TimezoneOffset}, returns the result of calling {TimezoneOffset#dst? dst?}
+    # on that offset.
+    #
+    # @return [Boolean] `true` if daylight savings time is being observed,
+    #   otherwise `false`.
+    def dst?
+      to = timezone_offset
+      to ? to.dst? : super
+    end
+    alias isdst dst?
+
+    # An overridden version of `Time#getlocal` that clears the associated
+    # {TimezoneOffset} if the base implementation of `getlocal` returns a
+    # {TimeWithOffset}.
+    #
+    # @return [Time] a representation of the {TimeWithOffset} using either the
+    #   local time zone or the given offset.
+    def getlocal(*args)
+      # JRuby < 9.3 returns a Time in all cases.
+      # JRuby >= 9.3 returns a Time when called with no arguments and a
+      # TimeWithOffset with a timezone_offset assigned when called with an
+      # offset argument.
+      result = super
+      result.clear_timezone_offset if result.kind_of?(TimeWithOffset)
+      result
+    end
+
+    # An overridden version of `Time#gmtime` that clears the associated
+    # {TimezoneOffset}.
+    #
+    # @return [TimeWithOffset] `self`.
+    def gmtime
+      super
+      @timezone_offset = nil
+      self
+    end
+
+    # An overridden version of `Time#localtime` that clears the associated
+    # {TimezoneOffset}.
+    #
+    # @return [TimeWithOffset] `self`.
+    def localtime(*args)
+      super
+      @timezone_offset = nil
+      self
+    end
+
+    # An overridden version of `Time#round` that, if there is an associated
+    # {TimezoneOffset}, returns a {TimeWithOffset} preserving that offset.
+    #
+    # @return [Time] the rounded time.
+    def round(ndigits = 0)
+      if_timezone_offset(super) {|o,t| self.class.at(t.to_i, t.subsec * 1_000_000).set_timezone_offset(o) }
+    end
+
+    # An overridden version of `Time#to_a`. The `isdst` (index 8) and `zone`
+    # (index 9) elements of the array are set according to the associated
+    # {TimezoneOffset}.
+    #
+    # @return [Array] an `Array` representation of the {TimeWithOffset}.
+    def to_a
+      if_timezone_offset(super) do |o,a|
+        a[8] = o.dst?
+        a[9] = o.abbreviation
+        a
+      end
+    end
+
+    # An overridden version of `Time#utc` that clears the associated
+    # {TimezoneOffset}.
+    #
+    # @return [TimeWithOffset] `self`.
+    def utc
+      super
+      @timezone_offset = nil
+      self
+    end
+
+    # An overridden version of `Time#zone` that, if there is an associated
+    # {TimezoneOffset}, returns the {TimezoneOffset#abbreviation abbreviation}
+    # of that offset.
+    #
+    # @return [String] the {TimezoneOffset#abbreviation abbreviation} of the
+    #   associated {TimezoneOffset}, or the result from `Time#zone` if there is
+    #   no such offset.
+    def zone
+      to = timezone_offset
+      to ? to.abbreviation : super
+    end
+
+    # An overridden version of `Time#to_datetime` that, if there is an
+    # associated {TimezoneOffset}, returns a {DateTimeWithOffset} with that
+    # offset.
+    #
+    # @return [DateTime] if there is an associated {TimezoneOffset}, a
+    #   {DateTimeWithOffset} representation of this {TimeWithOffset}, otherwise
+    #   a `Time` representation.
+    def to_datetime
+      if_timezone_offset(super) do |o,dt|
+        offset = dt.offset
+        result = DateTimeWithOffset.jd(dt.jd + dt.day_fraction - offset)
+        result = result.new_offset(offset) unless offset == 0
+        result.set_timezone_offset(o)
+      end
+    end
+
+    protected
+
+    # Clears the associated {TimezoneOffset}.
+    #
+    # @return [TimeWithOffset] `self`.
+    def clear_timezone_offset
+      @timezone_offset = nil
+      self
+    end
+  end
+end