tzinfo 1.2.1 → 2.0.5

data/lib/tzinfo/timezone_offset.rb

@@ -1,74 +1,111 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
 module TZInfo
-  # Represents an offset defined in a Timezone data file.
+  # Represents an offset from UTC observed by a time zone.
   class TimezoneOffset
-    # The base offset of the timezone from UTC in seconds.
-    attr_reader :utc_offset
-    
-    # The offset from standard time for the zone in seconds (i.e. non-zero if 
-    # daylight savings is being observed).
+    # Returns the base offset from UTC in seconds (`observed_utc_offset -
+    # std_offset`). This does not include any adjustment made for daylight
+    # savings time and will typically remain constant throughout the year.
+    #
+    # To obtain the currently observed offset from UTC, including the effect of
+    # daylight savings time, use {observed_utc_offset} instead.
+    #
+    # If you require accurate {base_utc_offset} values, you should install the
+    # tzinfo-data gem and set {DataSources::RubyDataSource} as the {DataSource}.
+    # When using {DataSources::ZoneinfoDataSource}, the value of
+    # {base_utc_offset} has to be derived from changes to the observed UTC
+    # offset and DST status since it is not included in zoneinfo files.
+    #
+    # @return [Integer] the base offset from UTC in seconds.
+    attr_reader :base_utc_offset
+    alias utc_offset base_utc_offset
+
+    # Returns the offset from the time zone's standard time in seconds
+    # (`observed_utc_offset - base_utc_offset`). Zero when daylight savings time
+    # is not in effect. Non-zero (usually 3600 = 1 hour) if daylight savings is
+    # being observed.
+    #
+    # If you require accurate {std_offset} values, you should install the
+    # tzinfo-data gem and set {DataSources::RubyDataSource} as the {DataSource}.
+    # When using {DataSources::ZoneinfoDataSource}, the value of {std_offset}
+    # has to be derived from changes to the observed UTC offset and DST status
+    # since it is not included in zoneinfo files.
+    #
+    # @return [Integer] the offset from the time zone's standard time in
+    #   seconds.
     attr_reader :std_offset
-    
-    # The total offset of this observance from UTC in seconds 
-    # (utc_offset + std_offset).
-    attr_reader :utc_total_offset
-    
-    # The abbreviation that identifies this observance, e.g. "GMT" 
-    # (Greenwich Mean Time) or "BST" (British Summer Time) for "Europe/London". The returned identifier is a 
-    # symbol.
+
+    # Returns the observed offset from UTC in seconds (`base_utc_offset +
+    # std_offset`). This includes adjustments made for daylight savings time.
+    #
+    # @return [Integer] the observed offset from UTC in seconds.
+    attr_reader :observed_utc_offset
+    alias utc_total_offset observed_utc_offset
+
+    # The abbreviation that identifies this offset. For example GMT
+    # (Greenwich Mean Time) or BST (British Summer Time) for Europe/London.
+    #
+    # @return [String] the abbreviation that identifies this offset.
     attr_reader :abbreviation
-    
-    # Constructs a new TimezoneOffset. utc_offset and std_offset are specified 
-    # in seconds.
-    def initialize(utc_offset, std_offset, abbreviation)
-      @utc_offset = utc_offset
-      @std_offset = std_offset      
-      @abbreviation = abbreviation
-      
-      @utc_total_offset = @utc_offset + @std_offset
+    alias abbr abbreviation
+
+    # Initializes a new {TimezoneOffset}.
+    #
+    # {TimezoneOffset} instances should not normally be constructed manually.
+    #
+    # The passed in `abbreviation` instance will be frozen.
+    #
+    # @param base_utc_offset [Integer] the base offset from UTC in seconds.
+    # @param std_offset [Integer] the offset from standard time in seconds.
+    # @param abbreviation [String] the abbreviation identifying the offset.
+    def initialize(base_utc_offset, std_offset, abbreviation)
+      @base_utc_offset = base_utc_offset
+      @std_offset = std_offset
+      @abbreviation = abbreviation.freeze
+
+      @observed_utc_offset = @base_utc_offset + @std_offset
     end
-    
-    # True if std_offset is non-zero.
+
+    # Determines if daylight savings is in effect (i.e. if {std_offset} is
+    # non-zero).
+    #
+    # @return [Boolean] `true` if {std_offset} is non-zero, otherwise `false`.
     def dst?
       @std_offset != 0
     end
-    
-    # Converts a UTC Time, DateTime or integer timestamp to local time, based on 
-    # the offset of this period.
-    def to_local(utc)
-      TimeOrDateTime.wrap(utc) {|wrapped|
-        wrapped + @utc_total_offset
-      }
-    end
-    
-    # Converts a local Time, DateTime or integer timestamp to UTC, based on the
-    # offset of this period.
-    def to_utc(local)
-      TimeOrDateTime.wrap(local) {|wrapped|
-        wrapped - @utc_total_offset
-      }
-    end
-    
-    # Returns true if and only if toi has the same utc_offset, std_offset
-    # and abbreviation as this TimezoneOffset.
+
+    # Determines if this {TimezoneOffset} is equal to another instance.
+    #
+    # @param toi [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `toi` is a {TimezoneOffset} with the same
+    #   {utc_offset}, {std_offset} and {abbreviation} as this {TimezoneOffset},
+    #   otherwise `false`.
     def ==(toi)
       toi.kind_of?(TimezoneOffset) &&
-        utc_offset == toi.utc_offset && std_offset == toi.std_offset && abbreviation == toi.abbreviation
+        base_utc_offset == toi.base_utc_offset && std_offset == toi.std_offset && abbreviation == toi.abbreviation
     end
-    
-    # Returns true if and only if toi has the same utc_offset, std_offset
-    # and abbreviation as this TimezoneOffset.
+
+    # Determines if this {TimezoneOffset} is equal to another instance.
+    #
+    # @param toi [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `toi` is a {TimezoneOffset} with the same
+    #   {utc_offset}, {std_offset} and {abbreviation} as this {TimezoneOffset},
+    #   otherwise `false`.
     def eql?(toi)
       self == toi
     end
-    
-    # Returns a hash of this TimezoneOffset.
+
+    # @return [Integer] a hash based on {utc_offset}, {std_offset} and
+    #   {abbreviation}.
     def hash
-      utc_offset.hash ^ std_offset.hash ^ abbreviation.hash
+      [@base_utc_offset, @std_offset, @abbreviation].hash
     end
-    
-    # Returns internal object state as a programmer-readable string.
+
+    # @return [String] the internal object state as a programmer-readable
+    #   `String`.
     def inspect
-      "#<#{self.class}: #@utc_offset,#@std_offset,#@abbreviation>"
+      "#<#{self.class}: @base_utc_offset=#{@base_utc_offset}, @std_offset=#{@std_offset}, @abbreviation=#{@abbreviation}>"
     end
   end
 end

data/lib/tzinfo/timezone_period.rb

@@ -1,204 +1,179 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
 module TZInfo
-  # A period of time in a timezone where the same offset from UTC applies.
+  # {TimezonePeriod} represents a period of time for a time zone where the same
+  # offset from UTC applies. It provides access to the observed offset, time
+  # zone abbreviation, start time and end time.
   #
-  # All the methods that take times accept instances of Time or DateTime as well
-  # as Integer timestamps.
+  # The period of time can be unbounded at the start, end, or both the start
+  # and end.
+  #
+  # @abstract Time zone period data will returned as an instance of one of the
+  #  subclasses of {TimezonePeriod}.
   class TimezonePeriod
-    # The TimezoneTransition that defines the start of this TimezonePeriod 
-    # (may be nil if unbounded).
-    attr_reader :start_transition
-    
-    # The TimezoneTransition that defines the end of this TimezonePeriod
-    # (may be nil if unbounded).
-    attr_reader :end_transition
-    
-    # The TimezoneOffset for this period.
+    # @return [TimezoneOffset] the offset that applies in the period of time.
     attr_reader :offset
-    
-    # Initializes a new TimezonePeriod.
-    #
-    # TimezonePeriod instances should not normally be constructed manually.
-    def initialize(start_transition, end_transition, offset = nil)
-      @start_transition = start_transition
-      @end_transition = end_transition
-      
-      if offset
-        raise ArgumentError, 'Offset specified with transitions' if @start_transition || @end_transition
-        @offset = offset
-      else
-        if @start_transition 
-          @offset = @start_transition.offset
-        elsif @end_transition
-          @offset = @end_transition.previous_offset
-        else
-          raise ArgumentError, 'No offset specified and no transitions to determine it from'
-        end
-      end
-      
-      @utc_total_offset_rational = nil      
-    end
-            
-    # Base offset of the timezone from UTC (seconds).
-    def utc_offset
-      @offset.utc_offset
-    end
-    
-    # Offset from the local time where daylight savings is in effect (seconds).
-    # E.g.: utc_offset could be -5 hours. Normally, std_offset would be 0. 
-    # During daylight savings, std_offset would typically become +1 hours.
+
+    # Initializes a {TimezonePeriod}.
+    #
+    # @param offset [TimezoneOffset] the offset that is observed for the period
+    #   of time.
+    # @raise [ArgumentError] if `offset` is `nil`.
+    def initialize(offset)
+      raise ArgumentError, 'offset must be specified' unless offset
+      @offset = offset
+    end
+
+    # @return [TimezoneTransition] the transition that defines the start of this
+    #   {TimezonePeriod} (`nil` if the start is unbounded).
+    def start_transition
+      raise_not_implemented(:start_transition)
+    end
+
+    # @return [TimezoneTransition] the transition that defines the end of this
+    #   {TimezonePeriod} (`nil` if the end is unbounded).
+    def end_transition
+      raise_not_implemented(:end_transition)
+    end
+
+    # Returns the base offset from UTC in seconds (`observed_utc_offset -
+    # std_offset`). This does not include any adjustment made for daylight
+    # savings time and will typically remain constant throughout the year.
+    #
+    # To obtain the currently observed offset from UTC, including the effect of
+    # daylight savings time, use {observed_utc_offset} instead.
+    #
+    # If you require accurate {base_utc_offset} values, you should install the
+    # tzinfo-data gem and set {DataSources::RubyDataSource} as the {DataSource}.
+    # When using {DataSources::ZoneinfoDataSource}, the value of
+    # {base_utc_offset} has to be derived from changes to the observed UTC
+    # offset and DST status since it is not included in zoneinfo files.
+    #
+    # @return [Integer] the base offset from UTC in seconds.
+    def base_utc_offset
+      @offset.base_utc_offset
+    end
+    alias utc_offset base_utc_offset
+
+    # Returns the offset from the time zone's standard time in seconds
+    # (`observed_utc_offset - base_utc_offset`). Zero when daylight savings time
+    # is not in effect. Non-zero (usually 3600 = 1 hour) if daylight savings is
+    # being observed.
+    #
+    # If you require accurate {std_offset} values, you should install the
+    # tzinfo-data gem and set {DataSources::RubyDataSource} as the {DataSource}.
+    # When using {DataSources::ZoneinfoDataSource}, the value of {std_offset}
+    # has to be derived from changes to the observed UTC offset and DST status
+    # since it is not included in zoneinfo files.
+    #
+    # @return [Integer] the offset from the time zone's standard time in
+    #   seconds.
     def std_offset
       @offset.std_offset
     end
-    
-    # The identifier of this period, e.g. "GMT" (Greenwich Mean Time) or "BST"
-    # (British Summer Time) for "Europe/London". The returned identifier is a 
-    # symbol.
+
+    # The abbreviation that identifies this offset. For example GMT
+    # (Greenwich Mean Time) or BST (British Summer Time) for Europe/London.
+    #
+    # @return [String] the abbreviation that identifies this offset.
     def abbreviation
       @offset.abbreviation
     end
-    alias :zone_identifier :abbreviation
-    
-    # Total offset from UTC (seconds). Equal to utc_offset + std_offset.
-    def utc_total_offset
-      @offset.utc_total_offset
-    end
-    
-    # Total offset from UTC (days). Result is a Rational.
-    def utc_total_offset_rational
-      # Thread-safety: It is possible that the value of 
-      # @utc_total_offset_rational may be calculated multiple times in 
-      # concurrently executing threads. It is not worth the overhead of locking
-      # to ensure that @zone_identifiers is only calculated once.
-    
-      unless @utc_total_offset_rational
-        @utc_total_offset_rational = OffsetRationals.rational_for_offset(utc_total_offset) 
-      end
-      @utc_total_offset_rational
-    end
-    
-    # The start time of the period in UTC as a DateTime. May be nil if unbounded.
-    def utc_start
-      @start_transition ? @start_transition.at.to_datetime : nil
-    end
-    
-    # The start time of the period in UTC as a Time. May be nil if unbounded.
-    def utc_start_time
-      @start_transition ? @start_transition.at.to_time : nil
-    end
-    
-    # The end time of the period in UTC as a DateTime. May be nil if unbounded.
-    def utc_end
-      @end_transition ? @end_transition.at.to_datetime : nil
-    end
-    
-    # The end time of the period in UTC as a Time. May be nil if unbounded.
-    def utc_end_time
-      @end_transition ? @end_transition.at.to_time : nil
-    end
-    
-    # The start time of the period in local time as a DateTime. May be nil if 
-    # unbounded.
-    def local_start
-      @start_transition ? @start_transition.local_start_at.to_datetime : nil
-    end
-    
-    # The start time of the period in local time as a Time. May be nil if 
-    # unbounded.
-    def local_start_time
-      @start_transition ? @start_transition.local_start_at.to_time : nil
-    end
-    
-    # The end time of the period in local time as a DateTime. May be nil if 
-    # unbounded.
-    def local_end
-      @end_transition ? @end_transition.local_end_at.to_datetime : nil
-    end
-    
-    # The end time of the period in local time as a Time. May be nil if 
-    # unbounded.
-    def local_end_time
-      @end_transition ? @end_transition.local_end_at.to_time : nil
-    end
-    
-    # true if daylight savings is in effect for this period; otherwise false.
+    alias abbr abbreviation
+    alias zone_identifier abbreviation
+
+    # Returns the observed offset from UTC in seconds (`base_utc_offset +
+    # std_offset`). This includes adjustments made for daylight savings time.
+    #
+    # @return [Integer] the observed offset from UTC in seconds.
+    def observed_utc_offset
+      @offset.observed_utc_offset
+    end
+    alias utc_total_offset observed_utc_offset
+
+    # Determines if daylight savings is in effect (i.e. if {std_offset} is
+    # non-zero).
+    #
+    # @return [Boolean] `true` if {std_offset} is non-zero, otherwise `false`.
     def dst?
       @offset.dst?
     end
-    
-    # true if this period is valid for the given UTC DateTime; otherwise false.
-    def valid_for_utc?(utc)
-      utc_after_start?(utc) && utc_before_end?(utc) 
-    end
-    
-    # true if the given UTC DateTime is after the start of the period 
-    # (inclusive); otherwise false.
-    def utc_after_start?(utc)
-      !@start_transition || @start_transition.at <= utc
-    end
-    
-    # true if the given UTC DateTime is before the end of the period 
-    # (exclusive); otherwise false.
-    def utc_before_end?(utc)
-      !@end_transition || @end_transition.at > utc
-    end
-    
-    # true if this period is valid for the given local DateTime; otherwise false.
-    def valid_for_local?(local)      
-      local_after_start?(local) && local_before_end?(local) 
-    end
-    
-    # true if the given local DateTime is after the start of the period 
-    # (inclusive); otherwise false.
-    def local_after_start?(local)
-      !@start_transition || @start_transition.local_start_at <= local
-    end
-    
-    # true if the given local DateTime is before the end of the period 
-    # (exclusive); otherwise false.
-    def local_before_end?(local)
-      !@end_transition || @end_transition.local_end_at > local
-    end
-    
-    # Converts a UTC DateTime to local time based on the offset of this period.
-    def to_local(utc)
-      @offset.to_local(utc)
-    end
-    
-    # Converts a local DateTime to UTC based on the offset of this period.
-    def to_utc(local)
-      @offset.to_utc(local)
-    end
-    
-    # Returns true if this TimezonePeriod is equal to p. This compares the 
-    # start_transition, end_transition and offset using ==.
-    def ==(p)
-      p.kind_of?(TimezonePeriod) &&
-        start_transition == p.start_transition &&
-        end_transition == p.end_transition &&
-        offset == p.offset
-    end
-    
-    # Returns true if this TimezonePeriods is equal to p. This compares the
-    # start_transition, end_transition and offset using eql?
-    def eql?(p)
-      p.kind_of?(TimezonePeriod) &&
-        start_transition.eql?(p.start_transition) &&
-        end_transition.eql?(p.end_transition) &&
-        offset.eql?(p.offset)
-    end
-    
-    # Returns a hash of this TimezonePeriod.
-    def hash
-      result = @start_transition.hash ^ @end_transition.hash
-      result ^= @offset.hash unless @start_transition || @end_transition
-      result       
-    end
-    
-    # Returns internal object state as a programmer-readable string.
-    def inspect
-      result = "#<#{self.class}: #{@start_transition.inspect},#{@end_transition.inspect}"
-      result << ",#{@offset.inspect}>" unless @start_transition || @end_transition
-      result + '>'
+
+    # Returns the UTC start time of the period or `nil` if the start of the
+    # period is unbounded.
+    #
+    # The result is returned as a {Timestamp}. To obtain the start time as a
+    # `Time` or `DateTime`, call either {Timestamp#to_time to_time} or
+    # {Timestamp#to_datetime to_datetime} on the result.
+    #
+    # @return [Timestamp] the UTC start time of the period or `nil` if the start
+    #   of the period is unbounded.
+    def starts_at
+      timestamp(start_transition)
+    end
+
+    # Returns the UTC end time of the period or `nil` if the end of the period
+    # is unbounded.
+    #
+    # The result is returned as a {Timestamp}. To obtain the end time as a
+    # `Time` or `DateTime`, call either {Timestamp#to_time to_time} or
+    # {Timestamp#to_datetime to_datetime} on the result.
+    #
+    # @return [Timestamp] the UTC end time of the period or `nil` if the end of
+    #   the period is unbounded.
+    def ends_at
+      timestamp(end_transition)
+    end
+
+    # Returns the local start time of the period or `nil` if the start of the
+    # period is unbounded.
+    #
+    # The result is returned as a {TimestampWithOffset}. To obtain the start
+    # time as a `Time` or `DateTime`, call either {TimestampWithOffset#to_time
+    # to_time} or {TimestampWithOffset#to_datetime to_datetime} on the result.
+    #
+    # @return [TimestampWithOffset] the local start time of the period or `nil`
+    #   if the start of the period is unbounded.
+    def local_starts_at
+      timestamp_with_offset(start_transition)
+    end
+
+    # Returns the local end time of the period or `nil` if the end of the period
+    # is unbounded.
+    #
+    # The result is returned as a {TimestampWithOffset}. To obtain the end time
+    # as a `Time` or `DateTime`, call either {TimestampWithOffset#to_time
+    # to_time} or {TimestampWithOffset#to_datetime to_datetime} on the result.
+    #
+    # @return [TimestampWithOffset] the local end time of the period or `nil` if
+    #   the end of the period is unbounded.
+    def local_ends_at
+      timestamp_with_offset(end_transition)
+    end
+
+    private
+
+    # Raises a {NotImplementedError} to indicate that subclasses should override
+    # a method.
+    #
+    # @raise [NotImplementedError] always.
+    def raise_not_implemented(method_name)
+      raise NotImplementedError, "Subclasses must override #{method_name}"
+    end
+
+    # @param  transition [TimezoneTransition] a transition or `nil`.
+    # @return [Timestamp] the {Timestamp} representing when a transition occurs,
+    #   or `nil` if `transition` is `nil`.
+    def timestamp(transition)
+      transition ? transition.at : nil
+    end
+
+    # @param transition [TimezoneTransition] a transition or `nil`.
+    # @return [TimestampWithOffset] a {Timestamp} representing when a transition
+    #   occurs with offset set to {#offset}, or `nil` if `transition` is `nil`.
+    def timestamp_with_offset(transition)
+      transition ? TimestampWithOffset.set_timezone_offset(transition.at, offset) : nil
     end
   end
 end