tzinfo 1.0.1 → 1.1.0

data/lib/tzinfo/data_timezone_info.rb

@@ -36,6 +36,32 @@ module TZInfo
       raise NotImplementedError, 'Subclasses must override periods_for_local'
     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)
+      raise NotImplementedError, 'Subclasses must override transitions_up_to'
+    end
+    
     # Constructs a Timezone instance for the timezone represented by this
     # DataTimezoneInfo.
     def create_timezone

data/lib/tzinfo/info_timezone.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2010 Philip Ross
+# Copyright (c) 2006-2013 Philip Ross
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -23,6 +23,8 @@
 module TZInfo
 
   # A Timezone based on a TimezoneInfo.
+  #
+  # @private
   class InfoTimezone < Timezone #:nodoc:
     
     # Constructs a new InfoTimezone with a TimezoneInfo instance.

data/lib/tzinfo/linked_timezone.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2010 Philip Ross
+# Copyright (c) 2006-2013 Philip Ross
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -22,6 +22,9 @@
 
 module TZInfo
 
+  # 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 
@@ -40,6 +43,32 @@ module TZInfo
       @linked_timezone.periods_for_local(local)
     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)
+    end
+    
     protected
       def setup(info)
         super(info)

data/lib/tzinfo/offset_rationals.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2010 Philip Ross
+# Copyright (c) 2006-2013 Philip Ross
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -26,7 +26,9 @@ module TZInfo
   
   # Provides a method for getting Rationals for a timezone offset in seconds.
   # Pre-reduced rationals are returned for all the half-hour intervals between
-  # -14 and +14 hours to avoid having to call gcd at runtime.  
+  # -14 and +14 hours to avoid having to call gcd at runtime.
+  #
+  # @private
   module OffsetRationals #:nodoc:
     @@rational_cache = {
       -50400 => RubyCoreSupport.rational_new!(-7,12), 
@@ -85,7 +87,7 @@ module TZInfo
        45000 => RubyCoreSupport.rational_new!(25,48),
        46800 => RubyCoreSupport.rational_new!(13,24),
        48600 => RubyCoreSupport.rational_new!(9,16),
-       50400 => RubyCoreSupport.rational_new!(7,12)}
+       50400 => RubyCoreSupport.rational_new!(7,12)}.freeze
     
     # Returns a Rational expressing the fraction of a day that offset in 
     # seconds represents (i.e. equivalent to Rational(offset, 86400)). 

data/lib/tzinfo/ruby_core_support.rb

@@ -26,6 +26,8 @@ require 'rational' unless defined?(Rational)
 module TZInfo
   
   # Methods to support different versions of Ruby.
+  #
+  # @private
   module RubyCoreSupport #:nodoc:
   
     # Use Rational.new! for performance reasons in Ruby 1.8.

data/lib/tzinfo/ruby_country_info.rb

@@ -22,6 +22,8 @@
 
 module TZInfo  
   # Represents information about a country returned by RubyDataSource.
+  #
+  # @private
   class RubyCountryInfo < CountryInfo #:nodoc:
     # Constructs a new CountryInfo with an ISO 3166 country code, name and 
     # block. The block will be evaluated to obtain the timezones for the 
@@ -36,6 +38,11 @@ module TZInfo
     # Returns a frozen array of all the zone identifiers for the country. These
     # are in the order they were added using the timezone method.
     def zone_identifiers
+      # Thread-safey: It is possible that the value of @zone_identifiers 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 @zone_identifiers
         @zone_identifiers = zones.collect {|zone| zone.identifier}.freeze
       end
@@ -47,6 +54,11 @@ module TZInfo
     # CountryTimezone instances. These are in the order they were added using 
     # the timezone method.
     def zones
+      # Thread-safey: It is possible that the value of @zones may be 
+      # calculated multiple times in concurrently executing threads. It is not 
+      # worth the overhead of locking to ensure that @zones is only 
+      # calculated once.
+    
       unless @zones
         zones = Zones.new
         @block.call(zones) if @block
@@ -59,6 +71,8 @@ module TZInfo
     
     # An instance of the Zones class is passed to the block used to define
     # timezones.
+    #
+    # @private
     class Zones #:nodoc:
       attr_reader :list
     

data/lib/tzinfo/ruby_data_source.rb

@@ -44,7 +44,12 @@ module TZInfo
       raise InvalidTimezoneIdentifier, 'Invalid identifier' if identifier !~ /^[A-Za-z0-9\+\-_]+(\/[A-Za-z0-9\+\-_]+)*$/
       
       identifier = identifier.gsub(/-/, '__m__').gsub(/\+/, '__p__')
+      
+      # Untaint identifier after it has been reassigned to a new string. We
+      # don't want to modify the original identifier. identifier may also be 
+      # frozen and therefore cannot be untainted.
       identifier.untaint
+      
       identifier = identifier.split('/')
       begin
         require_definition(identifier)

data/lib/tzinfo/time_or_datetime.rb

@@ -27,7 +27,7 @@ require 'time'
 module TZInfo
   # Used by TZInfo internally to represent either a Time, DateTime or
   # an Integer timestamp (seconds since 1970-01-01 00:00:00).
-  class TimeOrDateTime #:nodoc:
+  class TimeOrDateTime
     include Comparable
     
     # Constructs a new TimeOrDateTime. timeOrDateTime can be a Time, DateTime
@@ -70,6 +70,11 @@ module TZInfo
     # When converting from a DateTime, the result is truncated to microsecond
     # precision.
     def to_time
+      # Thread-safey: It is possible that the value of @time may be 
+      # calculated multiple times in concurrently executing threads. It is not 
+      # worth the overhead of locking to ensure that @time is only 
+      # calculated once.
+    
       unless @time
         if @timestamp
           @time = Time.at(@timestamp).utc
@@ -86,6 +91,11 @@ module TZInfo
     # When converting from a Time, the result is truncated to microsecond
     # precision.
     def to_datetime
+      # Thread-safey: It is possible that the value of @datetime may be 
+      # calculated multiple times in concurrently executing threads. It is not 
+      # worth the overhead of locking to ensure that @datetime is only 
+      # calculated once.
+    
       unless @datetime
         # Avoid using Rational unless necessary.
         u = usec
@@ -98,6 +108,11 @@ module TZInfo
     
     # Returns the time as an integer timestamp.
     def to_i
+      # Thread-safey: It is possible that the value of @timestamp may be 
+      # calculated multiple times in concurrently executing threads. It is not 
+      # worth the overhead of locking to ensure that @timestamp is only 
+      # calculated once.
+    
       unless @timestamp
         @timestamp = to_time.to_i
       end

data/lib/tzinfo/timezone.rb

@@ -21,6 +21,8 @@
 #++
 
 require 'date'
+require 'set'
+require 'thread_safe'
 
 module TZInfo
   # AmbiguousTime is raised to indicates that a specified time in a local 
@@ -47,8 +49,8 @@ module TZInfo
   class UnknownTimezone < StandardError
   end
   
-  # Timezone is the base class of all timezones. It provides a factory method
-  # get to access timezones by identifier. Once a specific Timezone has been
+  # Timezone is the base class of all timezones. It provides a factory method,
+  # 'get', to access timezones by identifier. Once a specific Timezone has been
   # retrieved, DateTimes, Times and timestamps can be converted between the UTC 
   # and the local time for the zone. For example:
   #
@@ -59,15 +61,23 @@ module TZInfo
   #
   # Each time conversion method returns an object of the same type it was 
   # passed.
+  #
+  # The Timezone class is thread-safe. It is safe to use class and instance 
+  # methods of Timezone in concurrently executing threads. Instances of Timezone
+  # can be shared across thread boundaries.
   class Timezone
     include Comparable
     
     # Cache of loaded zones by identifier to avoid using require if a zone
     # has already been loaded.
-    @@loaded_zones = {}
+    #
+    # @!visibility private
+    @@loaded_zones = nil
         
     # Default value of the dst parameter of the local_to_utc and 
     # period_for_local methods.
+    #
+    # @!visibility private
     @@default_dst = nil
     
     # Sets the default value of the optional dst parameter of the 
@@ -93,7 +103,14 @@ module TZInfo
     def self.get(identifier)
       instance = @@loaded_zones[identifier]
       
-      unless instance  
+      unless instance
+        # Thread-safety: It is possible that multiple equivalent Timezone 
+        # instances could be created here in concurrently executing threads. 
+        # The consequences of this are that the data may be loaded more than 
+        # once (depending on the data source) and memoized calculations could
+        # be discarded. The performance benefit of ensuring that only a single
+        # instance is created is unlikely to be worth the overhead of only
+        # allowing one Timezone to be loaded at a time.
         info = data_source.load_timezone_info(identifier)
         instance = info.create_timezone
         @@loaded_zones[instance.identifier] = instance         
@@ -284,6 +301,32 @@ module TZInfo
       raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
     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)
+      raise UnknownTimezone, 'TZInfo::Timezone constructed directly'
+    end
+    
     # Returns the TimezonePeriod for the given local time. local can either be
     # a DateTime, Time or integer timestamp (Time.to_i). Any timezone 
     # information in local is ignored (it is treated as a time in the current 
@@ -418,6 +461,59 @@ module TZInfo
       }
     end
     
+    # Returns information about offsets used by the Timezone up to a given
+    # date and time, specified using UTC (utc_to). The information is returned
+    # as an Array of TimezoneOffset instances.
+    #
+    # 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 offsets used from 
+    # that date and time forward will be returned.
+    #
+    # Comparisons with utc_to are exclusive. Comparisons with utc_from are
+    # inclusive.
+    #
+    # Offsets may be returned in any order.
+    #
+    # 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
+    # offsets_up_to raises an ArgumentError exception.
+    def offsets_up_to(utc_to, utc_from = nil)
+      utc_to = TimeOrDateTime.wrap(utc_to)
+      transitions = transitions_up_to(utc_to, utc_from)
+      
+      if transitions.empty?
+        # No transitions in the range, find the period that covers it.
+
+        if utc_from
+          # Use the from date as it is inclusive.
+          period = period_for_utc(utc_from)
+        else
+          # utc_to is exclusive, so this can't be used with period_for_utc.
+          # However, any time earlier than utc_to can be used.
+          
+          # Subtract 1 hour (since this is one of the cached OffsetRationals).
+          # Use add_with_convert so that conversion to DateTime is performed if
+          # required.
+          period = period_for_utc(utc_to.add_with_convert(-3600))
+        end
+      
+        [period.offset]
+      else
+        result = Set.new
+        
+        first = transitions.first        
+        result << first.previous_offset unless utc_from && first.at == utc_from
+        
+        transitions.each do |t|
+          result << t.offset
+        end
+        
+        result.to_a
+      end
+    end
+    
     # Returns the current time in the timezone as a Time.
     def now
       utc_to_local(Time.now.utc)
@@ -487,7 +583,13 @@ module TZInfo
       Timezone.get(data)
     end
     
-    private      
+    private
+      # Initializes @@loaded_zones.
+      def self.init_loaded_zones
+        @@loaded_zones = ThreadSafe::Cache.new
+      end
+      init_loaded_zones
+    
       # Returns an array of proxies corresponding to the given array of 
       # identifiers.
       def self.get_proxies(identifiers)

data/lib/tzinfo/timezone_definition.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2010 Philip Ross
+# Copyright (c) 2006-2013 Philip Ross
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -24,6 +24,8 @@ module TZInfo
   
   # TimezoneDefinition is included into Timezone definition modules.
   # TimezoneDefinition provides the methods for defining timezones.
+  #
+  # @private
   module TimezoneDefinition #:nodoc:
     # Add class methods to the includee.
     def self.append_features(base)
@@ -32,6 +34,8 @@ module TZInfo
     end
     
     # Class methods for inclusion.
+    #
+    # @private
     module ClassMethods #:nodoc:
       # Returns and yields a TransitionDataTimezoneInfo object to define a 
       # timezone.

data/lib/tzinfo/timezone_index_definition.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006 Philip Ross
+# Copyright (c) 2006-2013 Philip Ross
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -23,7 +23,10 @@
 module TZInfo
   # The timezone index file includes TimezoneIndexDefinition which provides
   # methods used to define timezones in the index.
+  #
+  # @private
   module TimezoneIndexDefinition #:nodoc:
+    # Add class methods to the includee and initialize class instance variables.
     def self.append_features(base)
       super
       base.extend(ClassMethods)
@@ -34,6 +37,9 @@ module TZInfo
       end
     end
     
+    # Class methods for inclusion.
+    #
+    # @private
     module ClassMethods #:nodoc:
       # Defines a timezone based on data.
       def timezone(identifier)