tzinfo 1.2.1 → 2.0.5

data/lib/tzinfo/timezone_proxy.rb

@@ -1,70 +1,96 @@
+# encoding: UTF-8
+
 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.
+  # A proxy class standing in for a {Timezone} with a given identifier.
+  # {TimezoneProxy} inherits from {Timezone} and can be treated identically to
+  # {Timezone} instances loaded with {Timezone.get}.
+  #
+  # {TimezoneProxy} instances are used to avoid the performance overhead of
+  # loading time zone data into memory, for example, by {Timezone.all}.
   #
-  # 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.  
+  # The first time an attempt is made to access the data for the time zone, the
+  # real {Timezone} will be loaded 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
+    # Initializes a new {TimezoneProxy}.
+    #
+    # The `identifier` parameter is not checked when initializing the proxy. It
+    # will be validated when the real {Timezone} instance is loaded.
+    #
+    # @param identifier [String] an IANA Time Zone Database time zone
+    #   identifier.
+    def initialize(identifier)
+      super()
+      @identifier = identifier
+      @real_timezone = nil
     end
-        
-    # The identifier of the timezone, e.g. "Europe/Paris".
+
+    # (see Timezone#identifier)
     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)            
+
+    # (see Timezone#period_for)
+    def period_for(time)
+      real_timezone.period_for_utc(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.
-    # Returns an empty array if no periods are found for the given time.
-    def periods_for_local(local)
-      real_timezone.periods_for_local(local)
+
+    # (see Timezone#periods_for_local)
+    def periods_for_local(local_time)
+      real_timezone.periods_for_local(local_time)
+    end
+
+    # (see Timezone#transitions_up_to)
+    def transitions_up_to(to, from = nil)
+      real_timezone.transitions_up_to(to, from)
     end
-    
-    # Returns the canonical zone for this Timezone.
+
+    # (see Timezone#canonical_zone)
     def canonical_zone
       real_timezone.canonical_zone
     end
-    
-    # Dumps this TimezoneProxy for marshalling.
+
+    # Returns a serialized representation of this {TimezoneProxy}. This method
+    # is called when using `Marshal.dump` with an instance of {TimezoneProxy}.
+    #
+    # @param limit [Integer] the maximum depth to dump - ignored. @return
+    #   [String] a serialized representation of this {TimezoneProxy}.
+    # @return [String] a serialized representation of this {TimezoneProxy}.
     def _dump(limit)
       identifier
     end
-    
-    # Loads a marshalled TimezoneProxy.
+
+    # Loads a {TimezoneProxy} from the serialized representation returned by
+    # {_dump}. This is method is called when using `Marshal.load` or
+    # `Marshal.restore` to restore a serialized {Timezone}.
+    #
+    # @param data [String] a serialized representation of a {TimezoneProxy}.
+    # @return [TimezoneProxy] the result of converting `data` back into a
+    #   {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.
-        @real_timezone ||= Timezone.get(@identifier)
-      end     
-  end 
+
+    # Returns the real {Timezone} instance being proxied.
+    #
+    # The real {Timezone} is loaded using {Timezone.get} on the first access.
+    #
+    # @return [Timezone] the real {Timezone} instance being proxied.
+    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

@@ -1,120 +1,98 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
 module TZInfo
-  # Represents a transition from one timezone offset to another at a particular
-  # date and time.
+  # Represents a transition from one observed UTC offset ({TimezoneOffset} to
+  # another for a time zone.
   class TimezoneTransition
-    # The offset this transition changes to (a TimezoneOffset instance).
+    # @return [TimezoneOffset] the offset this transition changes to.
     attr_reader :offset
-    
-    # The offset this transition changes from (a TimezoneOffset instance).
+
+    # @return [TimezoneOffset] the offset this transition changes from.
     attr_reader :previous_offset
-    
-    # Initializes a new TimezoneTransition.
+
+    # When this 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). Equivalent to the result of calling the
+    # {Timestamp#value value} method on the {Timestamp} returned by {at}.
+    #
+    # @return [Integer] when this transition occurs as a number of seconds since
+    #   1970-01-01 00:00:00 UTC ignoring leap seconds.
+    attr_reader :timestamp_value
+
+    # Initializes a new {TimezoneTransition}.
+    #
+    # {TimezoneTransition} instances should not normally be constructed
+    # manually.
     #
-    # TimezoneTransition instances should not normally be constructed manually.
-    def initialize(offset, previous_offset)
+    # @param offset [TimezoneOffset] the offset the transition changes to.
+    # @param previous_offset [TimezoneOffset] the offset the transition changes
+    #   from.
+    # @param timestamp_value [Integer] when the transition occurs as a
+    #   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).
+    def initialize(offset, previous_offset, timestamp_value)
       @offset = offset
       @previous_offset = previous_offset
-      @local_end_at = nil
-      @local_start_at = nil
+      @timestamp_value = timestamp_value
     end
-    
-    # A TimeOrDateTime instance representing the UTC time when this transition
-    # occurs.
+
+    # Returns a {Timestamp} instance representing the UTC time when this
+    # transition occurs.
+    #
+    # To obtain the result as a `Time` or `DateTime`, call either
+    # {Timestamp#to_time to_time} or {Timestamp#to_datetime to_datetime} on the
+    # {Timestamp} instance that is returned.
+    #
+    # @return [Timestamp] 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
+      Timestamp.utc(@timestamp_value)
     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).
+
+    # Returns a {TimestampWithOffset} instance representing the local time when
+    # this transition causes the previous observance to end (calculated from
+    # {at} using {previous_offset}).
+    #
+    # To obtain the result as a `Time` or `DateTime`, call either
+    # {TimestampWithOffset#to_time to_time} or {TimestampWithOffset#to_datetime
+    # to_datetime} on the {TimestampWithOffset} instance that is returned.
+    #
+    # @return [TimestampWithOffset] the local time when this transition causes
+    #   the previous observance to end.
     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.
-    
-      @local_end_at = at.add_with_convert(@previous_offset.utc_total_offset) unless @local_end_at
-      @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
+      TimestampWithOffset.new(@timestamp_value, 0, @previous_offset.observed_utc_offset).set_timezone_offset(@previous_offset)
     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).
+
+    # Returns a {TimestampWithOffset} instance representing the local time when
+    # this transition causes the next observance to start (calculated from {at}
+    # using {offset}).
+    #
+    # To obtain the result as a `Time` or `DateTime`, call either
+    # {TimestampWithOffset#to_time to_time} or {TimestampWithOffset#to_datetime
+    # to_datetime} on the {TimestampWithOffset} instance that is returned.
+    #
+    # @return [TimestampWithOffset] the local time when this transition causes
+    #   the next observance to start.
     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.
-    
-      @local_start_at = at.add_with_convert(@offset.utc_total_offset) unless @local_start_at
-      @local_start_at
+      TimestampWithOffset.new(@timestamp_value, 0, @offset.observed_utc_offset).set_timezone_offset(@offset)
     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.
+
+    # Determines if this {TimezoneTransition} is equal to another instance.
+    #
+    # @param tti [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `tti` is a {TimezoneTransition} with the same
+    #   {offset}, {previous_offset} and {timestamp_value} as this
+    #   {TimezoneTransition}, otherwise `false`.
     def ==(tti)
       tti.kind_of?(TimezoneTransition) &&
-        offset == tti.offset && previous_offset == tti.previous_offset && at == tti.at
+        offset == tti.offset && previous_offset == tti.previous_offset && timestamp_value == tti.timestamp_value
     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
+    alias eql? ==
 
-    def raise_not_implemented(method_name)
-      raise NotImplementedError, "Subclasses must override #{method_name}"
+    # @return [Integer] a hash based on {offset}, {previous_offset} and
+    #   {timestamp_value}.
+    def hash
+      [@offset, @previous_offset, @timestamp_value].hash
     end
   end
 end