tzinfo 1.0.1 → 1.1.0

data/{README → README.md}

@@ -1,18 +1,20 @@
-= TZInfo - Ruby Timezone Library
+TZInfo - Ruby Timezone Library
+==============================
 
-TZInfo[http://tzinfo.rubyforge.org] provides daylight savings aware 
+[TZInfo](http://tzinfo.github.io) provides daylight savings aware 
 transformations between times in different timezones.
 
 
-== Data Sources
+Data Sources
+------------
 
 TZInfo requires a source of timezone data. There are two built-in options:
 
 1. The TZInfo::Data library (the tzinfo-data gem). TZInfo::Data contains a set 
-   of Ruby modules that are generated from the {IANA Time Zone Database}[http://www.iana.org/time-zones].
+   of Ruby modules that are generated from the [IANA Time Zone Database](http://www.iana.org/time-zones).
 2. A zoneinfo directory. Most Unix-like systems include a zoneinfo directory 
    containing timezone definitions. These are also generated from the 
-   {IANA Time Zone Database}[http://www.iana.org/time-zones].
+   [IANA Time Zone Database](http://www.iana.org/time-zones).
 
 By default, TZInfo::Data will be used. If TZInfo::Data is not available (i.e. 
 if require 'tzinfo/data' fails), then TZInfo will search for a zoneinfo
@@ -29,33 +31,29 @@ Custom data sources can also be used. See TZInfo::DataSource.set for
 further details.
 
 
-== Installation
+Installation
+------------
 
 The TZInfo gem can be installed by running:
 
-  $ gem install tzinfo
+    gem install tzinfo
 
 To use the Ruby modules as the data source, TZInfo::Data will also need to be
 installed:
 
-  $ gem install tzinfo-data
+    gem install tzinfo-data
   
 
-== Download
-
-Tar, Zip and RubyGem packages of TZInfo and TZInfo::Data can be downloaded from
-http://rubyforge.org/frs/?group_id=894
-
-
-== Example usage
+Example Usage
+-------------
 
 The following code will obtain the America/New_York timezone (as an instance
 of TZInfo::Timezone) and covert a time in UTC to local New York time:
 
-  require 'tzinfo'
-  
-  tz = TZInfo::Timezone.get('America/New_York')
-  local = tz.utc_to_local(Time.utc(2005,8,29,15,35,0))
+    require 'tzinfo'
+    
+    tz = TZInfo::Timezone.get('America/New_York')
+    local = tz.utc_to_local(Time.utc(2005,8,29,15,35,0))
 
 Note that the local Time returned will have a UTC timezone (local.zone will 
 return "UTC"). This is because the Ruby Time class only supports two timezones: 
@@ -64,28 +62,28 @@ UTC and the current system local timezone.
 To convert from a local time to UTC, the local_to_utc method can be used as
 follows:
 
-  utc = tz.local_to_utc(local)
+    utc = tz.local_to_utc(local)
 
 Note that the timezone information of the local Time object is ignored (TZInfo
 will just read the date and time and treat them as if there were in the 'tz'
 timezone). The following two lines will return the same result regardless of 
 the system's local timezone:
 
-  tz.local_to_utc(Time.local(2006,6,26,1,0,0))
-  tz.local_to_utc(Time.utc(2006,6,26,1,0,0))
+    tz.local_to_utc(Time.local(2006,6,26,1,0,0))
+    tz.local_to_utc(Time.utc(2006,6,26,1,0,0))
   
 To obtain information about the rules in force at a particular UTC or local 
 time, the TZInfo::Timezone.period_for_utc and TZInfo::Timezone.period_for_local
 methods can be used. Both of these methods return TZInfo::TimezonePeriod 
 objects. The following gets the identifier for the period (in this case EDT).
 
-  period = tz.period_for_utc(Time.utc(2005,8,29,15,35,0))
-  id = period.zone_identifier
+    period = tz.period_for_utc(Time.utc(2005,8,29,15,35,0))
+    id = period.zone_identifier
   
 The current local time in a Timezone can be obtained with the 
 TZInfo::Timezone#now method:
 
-  now = tz.now
+    now = tz.now
 
 All methods in TZInfo that operate on a time can be used with either Time or 
 DateTime instances or with Integer timestamps (i.e. as returned by Time#to_i). 
@@ -100,8 +98,8 @@ code). The following code retrieves the TZInfo::Country instance representing
 the USA (country code 'US') and then gets all the Timezone identifiers used in 
 the USA.
 
-  us = TZInfo::Country.get('US')
-  timezones = us.zone_identifiers
+    us = TZInfo::Country.get('US')
+    timezones = us.zone_identifiers
   
 The TZInfo::Country#zone_info method provides an additional description and 
 geographic location for each Timezone in a Country.
@@ -114,19 +112,35 @@ For further detail, please refer to the API documentation for the
 TZInfo::Timezone and TZInfo::Country classes.
 
 
-== Documentation
+Thread-Safety
+-------------
+
+The TZInfo::Country and TZInfo::Timezone classes are thread-safe. It is safe to 
+use class and instance methods of TZInfo::Country and TZInfo::Timezone in 
+concurrently executing threads. Instances of both classes can be shared across 
+thread boundaries.
 
-API documentation can be found at 
 
-* http://tzinfo.rubyforge.org/doc/
+Documentation
+-------------
 
+API documentation for TZInfo is available on [RubyDoc.info](http://rubydoc.info/gems/tzinfo/frames).
 
-== License
+
+License
+-------
 
 TZInfo is released under the MIT license, see LICENSE for details.
 
 
-== Support
+Source Code
+-----------
+
+Source code for TZInfo is available on [GitHub](https://github.com/tzinfo/tzinfo).
+
+
+Issue Tracker
+-------------
 
-Please post to the {TZInfo Users mailing list}[http://rubyforge.org/mailman/listinfo/tzinfo-users]
-if you require assistance or have any suggestions.
+Please post any bugs, issues, feature requests or questions to the 
+[GitHub issue tracker](https://github.com/tzinfo/tzinfo/issues).

data/Rakefile

@@ -1,15 +1,40 @@
-# Available options:
+#--
+# Copyright (c) 2005-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
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
 #
-# rake test - Runs all test cases.
-# rake package - Runs test cases and builds packages for distribution.
-# rake rdoc - Builds API documentation in doc dir.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#++
 
-require 'rake'
-require 'rake/testtask'
-require 'rdoc/task'
 require 'rubygems'
 require 'rubygems/package_task'
 require 'fileutils'
+require 'rake/testtask'
+
+# Ignore errors loading rdoc/task (the rdoc tasks will be excluded if
+# rdoc is unavailable).
+begin
+  require 'rdoc/task'
+rescue LoadError, RuntimeError
+end
+
+BASE_DIR = File.expand_path(File.dirname(__FILE__))
+
+task :default => [:test]
 
 spec = eval(File.read('tzinfo.gemspec'))
 
@@ -34,17 +59,17 @@ package_task = TZInfoPackageTask.new(spec) do |pkg|
   pkg.tar_command = '__tar_with_owner__'
 end
 
-RDoc::Task.new do |rdoc|
-  rdoc.rdoc_dir = 'doc'
-  rdoc.title = 'TZInfo'
-  rdoc.main = 'README'
-  rdoc.options.concat spec.rdoc_options
-  rdoc.rdoc_files.include(spec.extra_rdoc_files) 
-  rdoc.rdoc_files.include('lib')  
+# Skip the rdoc task if RDoc::Task is unavailable
+if defined?(RDoc) && defined?(RDoc::Task)
+  RDoc::Task.new do |rdoc|
+    rdoc.rdoc_dir = 'doc'
+    rdoc.options.concat spec.rdoc_options
+    rdoc.rdoc_files.include(spec.extra_rdoc_files) 
+    rdoc.rdoc_files.include('lib')  
+  end
 end
 
 Rake::Task[package_task.package_dir_path].enhance do
-  File.chmod(0755, package_task.package_dir_path)
   recurse_chmod(package_task.package_dir_path)
 end
 
@@ -67,21 +92,19 @@ def recurse_chmod(dir)
   end
 end
 
+desc 'Run tests using RubyDataSource, then ZoneinfoDataSource'
 task :test => [:test_ruby, :test_zoneinfo] do
 end
 
 def setup_tests(test_task, type)
-  # Force a particular timezone to be local (helps find issues when local
-  # timezone isn't GMT). This won't work on Windows.
-  ENV['TZ'] = 'America/Los_Angeles'
-  
-  test_task.pattern = File.join(File.expand_path(File.dirname(__FILE__)), 'test', "ts_all_#{type}.rb")
+  test_task.libs = [File.join(BASE_DIR, 'lib')]
+  test_task.pattern = File.join(BASE_DIR, 'test', "ts_all_#{type}.rb")
 end
 
-Rake::TestTask.new('test_ruby') do |t|
+Rake::TestTask.new(:test_ruby) do |t|
   setup_tests(t, :ruby)
 end
 
-Rake::TestTask.new('test_zoneinfo') do |t|
+Rake::TestTask.new(:test_zoneinfo) do |t|
   setup_tests(t, :zoneinfo)
 end

data/lib/tzinfo.rb

@@ -20,14 +20,19 @@
 # THE SOFTWARE.
 #++
 
+# Top level module for TZInfo.
+module TZInfo
+end
+
 require 'tzinfo/ruby_core_support'
 require 'tzinfo/offset_rationals'
 require 'tzinfo/time_or_datetime'
 
 require 'tzinfo/timezone_definition'
 
-require 'tzinfo/timezone_offset_info'
-require 'tzinfo/timezone_transition_info'
+require 'tzinfo/timezone_offset'
+require 'tzinfo/timezone_transition'
+require 'tzinfo/timezone_transition_definition'
 
 require 'tzinfo/timezone_index_definition'
 

data/lib/tzinfo/country.rb

@@ -20,6 +20,8 @@
 # THE SOFTWARE.
 #++
 
+require 'thread_safe'
+
 module TZInfo
   # Raised by Country#get if the code given is not valid.
   class InvalidCountryCode < StandardError
@@ -33,6 +35,10 @@ module TZInfo
   #  us.zones
   #  us.zone_info
   #
+  # The Country class is thread-safe. It is safe to use class and instance 
+  # methods of Country in concurrently executing threads. Instances of Country
+  # can be shared across thread boundaries.
+  #
   # Country information available through TZInfo is intended as an aid for 
   # users, to help them select time zone data appropriate for their practical 
   # needs. It is not intended to take or endorse any position on legal or 
@@ -41,9 +47,13 @@ module TZInfo
     include Comparable
     
     # Defined countries.
-    @@countries = {}
+    #
+    # @!visibility private
+    @@countries = nil
     
     # Whether the countries index has been loaded yet.
+    #
+    # @!visibility private
     @@index_loaded = false
     
     # Gets a Country by its ISO 3166-1 alpha-2 code. Raises an 
@@ -52,6 +62,13 @@ module TZInfo
       instance = @@countries[identifier]
       
       unless instance
+        # Thread-safety: It is possible that multiple equivalent Country 
+        # 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 Country to be loaded at a time.
         info = data_source.load_country_info(identifier)  
         instance = Country.new(info)
         @@countries[identifier] = instance
@@ -169,6 +186,11 @@ module TZInfo
         @info = info        
       end
       
+      def self.init_countries
+        @@countries = ThreadSafe::Cache.new
+      end
+      init_countries
+      
       # Returns the current DataSource
       def self.data_source
         DataSource.get

data/lib/tzinfo/country_index_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
@@ -23,6 +23,8 @@
 module TZInfo
   # The country index file includes CountryIndexDefinition which provides
   # a country method used to define each country in the index.
+  #
+  # @private
   module CountryIndexDefinition #:nodoc:
     def self.append_features(base)
       super
@@ -30,6 +32,9 @@ module TZInfo
       base.instance_eval { @countries = {} }
     end
     
+    # Class methods for inclusion.
+    #
+    # @private
     module ClassMethods #:nodoc:
       # Defines a country with an ISO 3166 country code, name and block. The
       # block will be evaluated to obtain all the timezones for the country.

data/lib/tzinfo/country_timezone.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2012 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
@@ -62,11 +62,19 @@ module TZInfo
     
     # The latitude of this timezone in degrees as a Rational.
     def latitude
+      # Thread-safey: It is possible that the value of @latitude may be 
+      # calculated multiple times in concurrently executing threads. It is not 
+      # worth the overhead of locking to ensure that @latitude is only 
+      # calculated once.
       @latitude ||= RubyCoreSupport.rational_new!(@latitude_numerator, @latitude_denominator)
     end
     
     # The longitude of this timezone in degrees as a Rational.
     def longitude
+      # Thread-safey: It is possible that the value of @longitude may be 
+      # calculated multiple times in concurrently executing threads. It is not 
+      # worth the overhead of locking to ensure that @longitude is only 
+      # calculated once.
       @longitude ||= RubyCoreSupport.rational_new!(@longitude_numerator, @longitude_denominator)
     end
     

data/lib/tzinfo/data_source.rb

@@ -20,6 +20,8 @@
 # THE SOFTWARE.
 #++
 
+require 'thread'
+
 module TZInfo
   # InvalidDataSource is raised if the DataSource is used doesn't implement one 
   # of the required methods.
@@ -38,10 +40,29 @@ module TZInfo
   class DataSource
     # The currently selected data source.
     @@instance = nil
+    
+    # Mutex used to ensure the default data source is only created once.
+    @@default_mutex = Mutex.new
         
     # Returns the currently selected DataSource instance.
     def self.get
-      set(create_default_data_source) unless @@instance
+      # If a DataSource hasn't been manually set when the first request is
+      # made to obtain a DataSource, then a Default data source is created.
+      
+      # This is done at the first request rather than when TZInfo is loaded to
+      # avoid unnecessary (or in some cases potentially harmful) attempts to 
+      # find a suitable DataSource.
+      
+      # A Mutex is used to ensure that only a single default instance is
+      # created (having two different DataSources in use simultaneously could 
+      # cause unexpected results).
+      
+      unless @@instance
+        @@default_mutex.synchronize do
+          set(create_default_data_source) unless @@instance
+        end
+      end      
+      
       @@instance
     end
     
@@ -88,10 +109,10 @@ module TZInfo
     # To avoid inconsistent data, \DataSource.set should be called before
     # accessing any Timezone or Country data.
     #
-    # If \DataSource.set is not called, TZInfo will use TZInfo::Data as the
-    # data source. If TZInfo::Data is not available (i.e. if 
-    # require 'tzinfo/data' fails), then TZInfo will search for a zoneinfo 
-    # directory instead (using the search path specified by
+    # If \DataSource.set is not called, TZInfo will by default use TZInfo::Data 
+    # as the data source. If TZInfo::Data is not available (i.e. if require 
+    # 'tzinfo/data' fails), then TZInfo will search for a zoneinfo directory 
+    # instead (using the search path specified by
     # TZInfo::ZoneinfoDataSource::DEFAULT_SEARCH_PATH).
     def self.set(data_source_or_type, *args)
       if data_source_or_type.kind_of?(DataSource)

data/lib/tzinfo/data_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 DataTimezoneInfo.
+  #
+  # @private
   class DataTimezone < InfoTimezone #:nodoc:
     
     # Returns the TimezonePeriod for the given UTC time. utc can either be
@@ -40,6 +42,32 @@ module TZInfo
     # Raises PeriodNotFound if no periods are found for the given time.
     def periods_for_local(local)
       info.periods_for_local(local)
-    end    
+    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)
+      info.transitions_up_to(utc_to, utc_from)
+    end
   end
 end