tzinfo 1.2.5

data/lib/tzinfo/country_index_definition.rb

@@ -0,0 +1,31 @@
+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
+      base.extend(ClassMethods)
+      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.
+      # Calls Country.country_defined with the definition of each country.
+      def country(code, name, &block)
+        @countries[code] = RubyCountryInfo.new(code, name, &block)      
+      end
+      
+      # Returns a frozen hash of all the countries that have been defined in
+      # the index.
+      def countries
+        @countries.freeze
+      end
+    end
+  end
+end

data/lib/tzinfo/country_info.rb

@@ -0,0 +1,42 @@
+module TZInfo  
+  # Represents a country and references to its timezones as returned by a
+  # DataSource.
+  class CountryInfo
+    # The ISO 3166 country code.
+    attr_reader :code
+    
+    # The name of the country.
+    attr_reader :name
+    
+    # Constructs a new CountryInfo with an ISO 3166 country code and name
+    def initialize(code, name)
+      @code = code
+      @name = name
+    end
+    
+    # Returns internal object state as a programmer-readable string.
+    def inspect
+      "#<#{self.class}: #@code>"
+    end
+    
+    # Returns a frozen array of all the zone identifiers for the country.
+    # The identifiers are ordered by importance according to the DataSource.
+    def zone_identifiers
+      raise_not_implemented('zone_identifiers')
+    end
+    
+    # Returns a frozen array of all the timezones for the for the country as
+    # CountryTimezone instances.
+    #
+    # The timezones are ordered by importance according to the DataSource.
+    def zones
+      raise_not_implemented('zones')
+    end
+
+    private
+
+    def raise_not_implemented(method_name)
+      raise NotImplementedError, "Subclasses must override #{method_name}"
+    end
+  end
+end

data/lib/tzinfo/country_timezone.rb

@@ -0,0 +1,135 @@
+module TZInfo
+  # A Timezone within a Country. This contains extra information about the
+  # Timezone that is specific to the Country (a Timezone could be used by
+  # multiple countries).
+  class CountryTimezone
+    # The zone identifier.
+    attr_reader :identifier      
+    
+    # A description of this timezone in relation to the country, e.g. 
+    # "Eastern Time". This is usually nil for countries having only a single
+    # Timezone.
+    attr_reader :description
+    
+    class << self
+      # Creates a new CountryTimezone with a timezone identifier, latitude,
+      # longitude and description. The latitude and longitude are specified as
+      # rationals - a numerator and denominator. For performance reasons, the 
+      # numerators and denominators must be specified in their lowest form.
+      #
+      # For use internally within TZInfo.
+      #
+      # @!visibility private
+      alias :new! :new
+      
+      # Creates a new CountryTimezone with a timezone identifier, latitude,
+      # longitude and description. The latitude and longitude must be specified
+      # as instances of Rational.
+      #
+      # CountryTimezone instances should normally only be constructed when
+      # creating new DataSource implementations.
+      def new(identifier, latitude, longitude, description = nil)
+        super(identifier, latitude, nil, longitude, nil, description)      
+      end
+    end
+    
+    # Creates a new CountryTimezone with a timezone identifier, latitude,
+    # longitude and description. The latitude and longitude are specified as
+    # rationals - a numerator and denominator. For performance reasons, the 
+    # numerators and denominators must be specified in their lowest form.
+    #
+    # @!visibility private
+    def initialize(identifier, latitude_numerator, latitude_denominator, 
+                   longitude_numerator, longitude_denominator, description = nil) #:nodoc:
+      @identifier = identifier
+      
+      if latitude_numerator.kind_of?(Rational)
+        @latitude = latitude_numerator
+      else
+        @latitude = nil
+        @latitude_numerator = latitude_numerator
+        @latitude_denominator = latitude_denominator
+      end
+      
+      if longitude_numerator.kind_of?(Rational)
+        @longitude = longitude_numerator
+      else
+        @longitude = nil
+        @longitude_numerator = longitude_numerator
+        @longitude_denominator = longitude_denominator
+      end
+        
+      @description = description
+    end
+    
+    # The Timezone (actually a TimezoneProxy for performance reasons).
+    def timezone
+      Timezone.get_proxy(@identifier)
+    end
+    
+    # if description is not nil, this method returns description; otherwise it
+    # returns timezone.friendly_identifier(true).
+    def description_or_friendly_identifier
+      description || timezone.friendly_identifier(true)
+    end
+    
+    # The latitude of this timezone in degrees as a Rational.
+    def latitude
+      # Thread-safety: 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.
+      unless @latitude
+         result = RubyCoreSupport.rational_new!(@latitude_numerator, @latitude_denominator)
+         return result if frozen?
+         @latitude = result
+      end
+
+      @latitude
+    end
+    
+    # The longitude of this timezone in degrees as a Rational.
+    def longitude
+      # Thread-safety: 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.
+      unless @longitude
+        result = RubyCoreSupport.rational_new!(@longitude_numerator, @longitude_denominator)
+        return result if frozen?
+        @longitude = result
+      end
+
+      @longitude
+    end
+    
+    # Returns true if and only if the given CountryTimezone is equal to the
+    # current CountryTimezone (has the same identifer, latitude, longitude
+    # and description).
+    def ==(ct)
+      ct.kind_of?(CountryTimezone) &&
+        identifier == ct.identifier  && latitude == ct.latitude &&
+        longitude == ct.longitude   && description == ct.description         
+    end
+            
+    # Returns true if and only if the given CountryTimezone is equal to the
+    # current CountryTimezone (has the same identifer, latitude, longitude
+    # and description).
+    def eql?(ct)
+      self == ct
+    end
+    
+    # Returns a hash of this CountryTimezone. 
+    def hash
+      @identifier.hash ^ 
+        (@latitude ? @latitude.numerator.hash ^ @latitude.denominator.hash : @latitude_numerator.hash ^ @latitude_denominator.hash) ^
+        (@longitude ? @longitude.numerator.hash ^ @longitude.denominator.hash : @longitude_numerator.hash ^ @longitude_denominator.hash) ^
+        @description.hash
+    end
+    
+    # Returns internal object state as a programmer-readable string.
+    def inspect
+      "#<#{self.class}: #@identifier>"
+    end
+  end
+end

data/lib/tzinfo/data_source.rb

@@ -0,0 +1,190 @@
+require 'thread'
+
+module TZInfo
+  # InvalidDataSource is raised if the DataSource is used doesn't implement one 
+  # of the required methods.
+  class InvalidDataSource < StandardError
+  end
+  
+  # DataSourceNotFound is raised if no data source could be found (i.e. 
+  # if 'tzinfo/data' cannot be found on the load path and no valid zoneinfo 
+  # directory can be found on the system).
+  class DataSourceNotFound < StandardError
+  end
+
+  # The base class for data sources of timezone and country data.
+  #
+  # Use DataSource.set to change the data source being used.
+  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
+      # 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
+    
+    # Sets the currently selected data source for Timezone and Country data.
+    #
+    # This should usually be set to one of the two standard data source types:
+    #
+    # * +:ruby+ - read data from the Ruby modules included in the TZInfo::Data 
+    #   library (tzinfo-data gem).
+    # * +:zoneinfo+ - read data from the zoneinfo files included with most
+    #   Unix-like operating sytems (e.g. in /usr/share/zoneinfo).
+    #
+    # To set TZInfo to use one of the standard data source types, call
+    # \TZInfo::DataSource.set in one of the following ways:
+    #
+    #   TZInfo::DataSource.set(:ruby)
+    #   TZInfo::DataSource.set(:zoneinfo)
+    #   TZInfo::DataSource.set(:zoneinfo, zoneinfo_dir)
+    #   TZInfo::DataSource.set(:zoneinfo, zoneinfo_dir, iso3166_tab_file)
+    #
+    # \DataSource.set(:zoneinfo) will automatically search for the zoneinfo
+    # directory by checking the paths specified in 
+    # ZoneinfoDataSource.search_paths. ZoneinfoDirectoryNotFound will be raised
+    # if no valid zoneinfo directory could be found.
+    #
+    # \DataSource.set(:zoneinfo, zoneinfo_dir) uses the specified zoneinfo
+    # directory as the data source. If the directory is not a valid zoneinfo
+    # directory, an InvalidZoneinfoDirectory exception will be raised.
+    #
+    # \DataSource.set(:zoneinfo, zoneinfo_dir, iso3166_tab_file) uses the
+    # specified zoneinfo directory as the data source, but loads the iso3166.tab
+    # file from an alternate path. If the directory is not a valid zoneinfo
+    # directory, an InvalidZoneinfoDirectory exception will be raised.
+    #
+    # Custom data sources can be created by subclassing TZInfo::DataSource and
+    # implementing the following methods:
+    #
+    # * \load_timezone_info
+    # * \timezone_identifiers
+    # * \data_timezone_identifiers
+    # * \linked_timezone_identifiers
+    # * \load_country_info
+    # * \country_codes
+    #
+    # To have TZInfo use the custom data source, call \DataSource.set 
+    # as follows:
+    #
+    #   TZInfo::DataSource.set(CustomDataSource.new)
+    #
+    # To avoid inconsistent data, \DataSource.set should be called before
+    # accessing any Timezone or Country data.
+    #
+    # 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)
+        @@instance = data_source_or_type
+      elsif data_source_or_type == :ruby
+        @@instance = RubyDataSource.new
+      elsif data_source_or_type == :zoneinfo
+        @@instance = ZoneinfoDataSource.new(*args)
+      else
+        raise ArgumentError, 'data_source_or_type must be a DataSource instance or a data source type (:ruby)'
+      end
+    end
+    
+    # Returns a TimezoneInfo instance for a given identifier. The TimezoneInfo
+    # instance should derive from either DataTimzoneInfo for timezones that
+    # define their own data or LinkedTimezoneInfo for links or aliases to
+    # other timezones.
+    #
+    # Raises InvalidTimezoneIdentifier if the timezone is not found or the 
+    # identifier is invalid.
+    def load_timezone_info(identifier)
+      raise_invalid_data_source('load_timezone_info')
+    end
+    
+    # Returns an array of all the available timezone identifiers.
+    def timezone_identifiers
+      raise_invalid_data_source('timezone_identifiers')
+    end
+    
+    # Returns an array of all the available timezone identifiers for
+    # data timezones (i.e. those that actually contain definitions).
+    def data_timezone_identifiers
+      raise_invalid_data_source('data_timezone_identifiers')
+    end
+    
+    # Returns an array of all the available timezone identifiers that
+    # are links to other timezones.
+    def linked_timezone_identifiers
+      raise_invalid_data_source('linked_timezone_identifiers')
+    end
+    
+    # Returns a CountryInfo instance for the given ISO 3166-1 alpha-2
+    # country code. Raises InvalidCountryCode if the country could not be found
+    # or the code is invalid.
+    def load_country_info(code)
+      raise_invalid_data_source('load_country_info')
+    end
+    
+    # Returns an array of all the available ISO 3166-1 alpha-2
+    # country codes.
+    def country_codes
+      raise_invalid_data_source('country_codes')
+    end
+    
+    # Returns the name of this DataSource.
+    def to_s
+      "Default DataSource"
+    end
+    
+    # Returns internal object state as a programmer-readable string.
+    def inspect
+      "#<#{self.class}>"
+    end
+    
+    private
+    
+    # Creates a DataSource instance for use as the default. Used if
+    # no preference has been specified manually.
+    def self.create_default_data_source
+      has_tzinfo_data = false
+      
+      begin
+        require 'tzinfo/data'
+        has_tzinfo_data = true
+      rescue LoadError
+      end
+    
+      return RubyDataSource.new if has_tzinfo_data
+      
+      begin
+        return ZoneinfoDataSource.new
+      rescue ZoneinfoDirectoryNotFound
+        raise DataSourceNotFound, "No source of timezone data could be found.\nPlease refer to http://tzinfo.github.io/datasourcenotfound for help resolving this error."
+      end
+    end
+
+    def raise_invalid_data_source(method_name)
+      raise InvalidDataSource, "#{method_name} not defined"
+    end
+  end
+end

data/lib/tzinfo/data_timezone.rb

@@ -0,0 +1,58 @@
+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
+    # 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)
+      info.period_for_utc(utc)
+    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)
+      info.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)
+      info.transitions_up_to(utc_to, utc_from)
+    end
+    
+    # Returns the canonical zone for this Timezone.
+    #
+    # For a DataTimezone, this is always self.
+    def canonical_zone
+      self
+    end
+  end
+end