tzinfo 1.2.11 → 2.0.0

data/lib/tzinfo/country.rb

@@ -1,104 +1,102 @@
-require 'thread_safe'
+# encoding: UTF-8
+# frozen_string_literal: true
 
 module TZInfo
-  # Raised by Country#get if the code given is not valid.
+  # {InvalidCountryCode} is raised by {Country#get} if the code given is not a
+  # valid ISO 3166-1 alpha-2 code.
   class InvalidCountryCode < StandardError
   end
-  
-  # The Country class represents an ISO 3166-1 country. It can be used to 
-  # obtain a list of Timezones for a country. For example:
+
+  # The {Country} class represents an ISO 3166-1 country. It can be used to
+  # obtain a list of time zones observed by a country. For example:
   #
-  #  us = Country.get('US')
-  #  us.zone_identifiers
-  #  us.zones
-  #  us.zone_info
+  #     united_states = Country.get('US')
+  #     united_states.zone_identifiers
+  #     united_states.zones
+  #     united_states.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.
+  # 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 
+  # 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
   # territorial claims.
   class Country
     include Comparable
-    
-    # Defined 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 
-    # InvalidCountryCode exception if it couldn't be found.
-    def self.get(identifier)
-      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
-      end      
-      
-      instance        
-    end
-    
-    # If identifier is a CountryInfo object, initializes the Country instance, 
-    # otherwise calls get(identifier).
-    def self.new(identifier)      
-      if identifier.kind_of?(CountryInfo)
-        instance = super()
-        instance.send :setup, identifier
-        instance
-      else
-        get(identifier)
+
+    class << self
+      # Gets a {Country} by its ISO 3166-1 alpha-2 code.
+      #
+      # The {Country.all_codes} method can be used to obtain a list of valid ISO
+      # 3166-1 alpha-2 codes.
+      #
+      # @param code [String] An ISO 3166-1 alpha-2 code.
+      # @return [Country] a {Country} instance representing the ISO-3166-1
+      #   country identified by the `code` parameter.
+      # @raise [InvalidCountryCode] If {code} is not a valid ISO 3166-1 alpha-2
+      #   code it couldn't be found.
+      def get(code)
+        Country.new(data_source.get_country_info(code))
+      end
+
+      # @return [Array<String>] an `Array` containing all the valid ISO 3166-1
+      #   alpha-2 country codes.
+      def all_codes
+        data_source.country_codes
+      end
+
+      # @return [Array<Country>] an `Array` containing one {Country} instance
+      #   for each defined country.
+      def all
+        data_source.country_codes.collect {|code| get(code)}
+      end
+
+      private
+
+      # @return [DataSource] the current DataSource.
+      def data_source
+        DataSource.get
       end
     end
-    
-    # Returns an Array of all the valid country codes.
-    def self.all_codes
-      data_source.country_codes
+
+    # Initializes a new {Country} based upon a {DataSources::CountryInfo}
+    # instance.
+    #
+    # {Country} instances should not normally be constructed directly. Use
+    # the {Country.get} method to obtain instances instead.
+    #
+    # @param info [DataSources::CountryInfo] the data to base the new {Country}
+    #   instance upon.
+    def initialize(info)
+      @info = info
     end
-    
-    # Returns an Array of all the defined Countries.
-    def self.all
-      data_source.country_codes.collect {|code| get(code)}
-    end       
-    
-    # The ISO 3166-1 alpha-2 country code.
+
+    # @return [String] the ISO 3166-1 alpha-2 country code.
     def code
       @info.code
     end
-    
-    # The name of the country.
+
+    # @return [String] the name of the country.
     def name
       @info.name
     end
-    
-    # Alias for name.
+
+    # @return [String] a `String` representation of this {Country} (the name of
+    #   the country).
     def to_s
       name
     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}: #{@info.code}>"
     end
-    
-    # Returns a frozen array of all the zone identifiers for the country. These
-    # are in an order that
+
+    # Returns an `Array` containing the identifier for each time zone observed
+    # by the country. These are in an order that
     #
     # 1. makes some geographical sense, and
     # 2. puts the most populous zones first, where that does not contradict 1.
@@ -107,90 +105,94 @@ module TZInfo
     # country. This will occur if the zone covers multiple countries. Any zones
     # referring to a city or region in a different country will be listed after
     # those relating to this country.
+    #
+    # @return [Array<String>] an `Array` containing the identifier for each time
+    #   zone observed by the country
     def zone_identifiers
-      @info.zone_identifiers
+      zone_info.map(&:identifier)
     end
     alias zone_names zone_identifiers
-    
-    # An array of all the Timezones for this country. Returns TimezoneProxy
-    # objects to avoid the overhead of loading Timezone definitions until
-    # a conversion is actually required. The Timezones are returned in an order
-    # that
+
+    # Returns An `Array` containing a {Timezone} instance for each time zone
+    # observed by the country. These are in an order that
     #
     # 1. makes some geographical sense, and
     # 2. puts the most populous zones first, where that does not contradict 1.
     #
-    # Identifiers of the zones returned may refer to cities and regions outside
-    # of the country. This will occur if the zone covers multiple countries. Any
-    # zones referring to a city or region in a different country will be listed
-    # after those relating to this country.
+    # The identifiers of the time zones returned may refer to cities and regions
+    # outside of the country. This will occur if the time zone covers multiple
+    # countries. Any zones referring to a city or region in a different country
+    # will be listed after those relating to this country.
+    #
+    # The results are actually instances of {TimezoneProxy} in order to defer
+    # loading of the time zone transition data until it is first needed.
+    #
+    # @return [Array<Timezone>] an `Array` containing a {Timezone} instance for
+    #   each time zone observed by the country.
     def zones
-      zone_identifiers.collect {|id|
-        Timezone.get_proxy(id)        
-      }
+      zone_info.map(&:timezone)
     end
-    
-    # Returns a frozen array of all the timezones for the for the country as
-    # CountryTimezone instances (containing extra information about each zone). 
-    # These are in an order that
+
+    # Returns a frozen `Array` containing a {CountryTimezone} instance for each
+    # time zone observed by the country. These are in an order that
     #
     # 1. makes some geographical sense, and
     # 2. puts the most populous zones first, where that does not contradict 1.
     #
-    # Identifiers and descriptions of the zones returned may refer to cities and
-    # regions outside of the country. This will occur if the zone covers
-    # multiple countries. Any zones referring to a city or region in a different
-    # country will be listed after those relating to this country.
+    # The {CountryTimezone} instances can be used to obtain the location and
+    # descriptions of the observed time zones.
+    #
+    # Identifiers and descriptions of the time zones returned may refer to
+    # cities and regions outside of the country. This will occur if the time
+    # zone covers multiple countries. Any zones referring to a city or region in
+    # a different country will be listed after those relating to this country.
+    #
+    # @return [Array<CountryTimezone>] a frozen `Array` containing a
+    #   {CountryTimezone} instance for each time zone observed by the country.
     def zone_info
       @info.zones
     end
-        
-    # Compare two Countries based on their code. Returns -1 if c is less
-    # than self, 0 if c is equal to self and +1 if c is greater than self.
+
+    # Compares this {Country} with another based on their {code}.
     #
-    # Returns nil if c is not comparable with Country instances.
+    # @param c [Object] an `Object` to compare this {Country} with.
+    # @return [Integer] -1 if `c` is less than `self`, 0 if `c` is equal to
+    #   `self` and +1 if `c` is greater than `self`, or `nil` if `c` is not an
+    #   instance of {Country}.
     def <=>(c)
       return nil unless c.is_a?(Country)
       code <=> c.code
     end
-    
-    # Returns true if and only if the code of c is equal to the code of this
-    # Country.
+
+    # @param c [Object] an `Object` to compare this {Country} with.
+    # @return [Boolean] `true` if `c` is an instance of {Country} and has the
+    #   same code as `self`, otherwise `false`.
     def eql?(c)
       self == c
     end
-    
-    # Returns a hash value for this Country.
+
+    # @return [Integer] a hash based on the {code}.
     def hash
       code.hash
     end
-    
-    # Dumps this Country for marshalling.
+
+    # Returns a serialized representation of this {Country}. This method is
+    # called when using `Marshal.dump` with an instance of {Country}.
+    #
+    # @param limit [Integer] the maximum depth to dump - ignored.
+    # @return [String] a serialized representation of this {Country}.
     def _dump(limit)
       code
     end
-    
-    # Loads a marshalled Country.
+
+    # Loads a {Country} from the serialized representation returned by {_dump}.
+    # This is method is called when using `Marshal.load` or `Marshal.restore`
+    # to restore a serialized {Country}.
+    #
+    # @param data [String] a serialized representation of a {Country}.
+    # @return [Country] the result of converting `data` back into a {Country}.
     def self._load(data)
       Country.get(data)
     end
-    
-    private
-      # Called by Country.new to initialize a new Country instance. The info
-      # parameter is a CountryInfo that defines the country.
-      def setup(info)
-        @info = info        
-      end
-
-      # Initializes @@countries.
-      def self.init_countries
-        @@countries = ThreadSafe::Cache.new
-      end
-      init_countries
-      
-      # Returns the current DataSource
-      def self.data_source
-        DataSource.get
-      end
-  end 
+  end
 end

data/lib/tzinfo/country_timezone.rb

@@ -1,135 +1,93 @@
+# encoding: UTF-8
+
 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).
+  # Information about a time zone used by a {Country}.
   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.
+    # @return [String] the identifier of the {Timezone} being described.
+    attr_reader :identifier
+
+    # The latitude of this time zone in degrees. Positive numbers are degrees
+    # north and negative numbers are degrees south.
+    #
+    # Note that depending on the data source, the position given by {#latitude}
+    # and {#longitude} may not be within the country.
+    #
+    # @return [Rational] the latitude in degrees.
+    attr_reader :latitude
+
+    # The longitude of this time zone in degrees. Positive numbers are degrees
+    # east and negative numbers are degrees west.
+    #
+    # Note that depending on the data source, the position given by {#latitude}
+    # and {#longitude} may not be within the country.
+    #
+    # @return [Rational] the longitude in degrees.
+    attr_reader :longitude
+
+    # A description of this time zone in relation to the country, e.g. "Eastern
+    # Time". This is usually `nil` for countries that have a single time zone.
+    #
+    # @return [String] an optional description of the time zone.
     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.
+
+    # Creates a new {CountryTimezone}.
+    #
+    # The passed in identifier and description instances will be frozen.
+    #
+    # {CountryTimezone} instances should normally only be constructed
+    # by implementations of {DataSource}.
     #
-    # @!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
+    # @param identifier [String] the {Timezone} identifier.
+    # @param latitude [Rational] the latitude of the time zone.
+    # @param longitude [Rational] the longitude of the time zone.
+    # @param description [String] an optional description of the time zone.
+    def initialize(identifier, latitude, longitude, description = nil)
+      @identifier = identifier.freeze
+      @latitude = latitude
+      @longitude = longitude
+      @description = description && description.freeze
     end
-    
-    # The Timezone (actually a TimezoneProxy for performance reasons).
+
+    # Returns the associated {Timezone}.
+    #
+    # The result is actually an instance of {TimezoneProxy} in order to defer
+    # loading of the time zone transition data until it is first needed.
+    #
+    # @return [Timezone] the associated {Timezone}.
     def timezone
       Timezone.get_proxy(@identifier)
     end
-    
-    # if description is not nil, this method returns description; otherwise it
-    # returns timezone.friendly_identifier(true).
+
+    # @return [String] the {description} if present, otherwise a human-readable
+    #   representation of the identifier (using {Timezone#friendly_identifier}).
     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).
+    # Tests if the given object is equal to the current instance (has the same
+    # identifier, latitude, longitude and description).
+    #
+    # @param ct [Object] the object to be compared.
+    # @return [TrueClass] `true` if `ct` is equal to the current instance.
     def ==(ct)
       ct.kind_of?(CountryTimezone) &&
         identifier == ct.identifier  && latitude == ct.latitude &&
-        longitude == ct.longitude   && description == ct.description         
+        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).
+
+    # Tests if the given object is equal to the current instance (has the same
+    # identifier, latitude, longitude and description).
+    #
+    # @param ct [Object] the object to be compared.
+    # @return [Boolean] `true` if `ct` is equal to the current instance.
     def eql?(ct)
       self == ct
     end
-    
-    # Returns a hash of this CountryTimezone. 
+
+    # @return [Integer] a hash based on the {identifier}, {latitude},
+    # {longitude} and {description}.
     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>"
+      [@identifier, @latitude, @longitude, @description].hash
     end
   end
 end