class TZInfo::Country

The Country class represents an ISO 3166-1 country. It can be used to obtain a list of Timezones for a country. For example:

us = Country.get('US')
us.zone_identifiers
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 territorial claims.

Public Class Methods

_load(data) click to toggle source

Loads a marshalled Country.

# File lib/tzinfo/country.rb, line 174
def self._load(data)
  Country.get(data)
end
all() click to toggle source

Returns an Array of all the defined Countries.

# File lib/tzinfo/country.rb, line 76
def self.all
  data_source.country_codes.collect {|code| get(code)}
end
all_codes() click to toggle source

Returns an Array of all the valid country codes.

# File lib/tzinfo/country.rb, line 71
def self.all_codes
  data_source.country_codes
end
get(identifier) click to toggle source

Gets a Country by its ISO 3166-1 alpha-2 code. Raises an InvalidCountryCode exception if it couldn't be found.

# File lib/tzinfo/country.rb, line 39
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
new(identifier) click to toggle source

If identifier is a CountryInfo object, initializes the Country instance, otherwise calls get(identifier).

Calls superclass method
# File lib/tzinfo/country.rb, line 60
def self.new(identifier)      
  if identifier.kind_of?(CountryInfo)
    instance = super()
    instance.send :setup, identifier
    instance
  else
    get(identifier)
  end
end

Private Class Methods

data_source() click to toggle source

Returns the current DataSource

# File lib/tzinfo/country.rb, line 192
def self.data_source
  DataSource.get
end
init_countries() click to toggle source

Initializes @@countries.

# File lib/tzinfo/country.rb, line 186
def self.init_countries
  @@countries = ThreadSafe::Cache.new
end

Public Instance Methods

<=>(c) click to toggle source

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.

Returns nil if c is not comparable with Country instances.

# File lib/tzinfo/country.rb, line 152
def <=>(c)
  return nil unless c.is_a?(Country)
  code <=> c.code
end
_dump(limit) click to toggle source

Dumps this Country for marshalling.

# File lib/tzinfo/country.rb, line 169
def _dump(limit)
  code
end
code() click to toggle source

The ISO 3166-1 alpha-2 country code.

# File lib/tzinfo/country.rb, line 81
def code
  @info.code
end
eql?(c) click to toggle source

Returns true if and only if the code of c is equal to the code of this Country.

# File lib/tzinfo/country.rb, line 159
def eql?(c)
  self == c
end
hash() click to toggle source

Returns a hash value for this Country.

# File lib/tzinfo/country.rb, line 164
def hash
  code.hash
end
inspect() click to toggle source

Returns internal object state as a programmer-readable string.

# File lib/tzinfo/country.rb, line 96
def inspect
  "#<#{self.class}: #{@info.code}>"
end
name() click to toggle source

The name of the country.

# File lib/tzinfo/country.rb, line 86
def name
  @info.name
end
to_s() click to toggle source

Alias for name.

# File lib/tzinfo/country.rb, line 91
def to_s
  name
end
zone_identifiers() click to toggle source

Returns a frozen array of all the zone identifiers for 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.

Returned zone identifiers 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.

# File lib/tzinfo/country.rb, line 110
def zone_identifiers
  @info.zone_identifiers
end
Also aliased as: zone_names
zone_info() click to toggle source

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

  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.

# File lib/tzinfo/country.rb, line 144
def zone_info
  @info.zones
end
zone_names()
Alias for: zone_identifiers
zones() click to toggle source

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

  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.

# File lib/tzinfo/country.rb, line 127
def zones
  zone_identifiers.collect {|id|
    Timezone.get_proxy(id)        
  }
end

Private Instance Methods

setup(info) click to toggle source

Called by Country.new to initialize a new Country instance. The info parameter is a CountryInfo that defines the country.

# File lib/tzinfo/country.rb, line 181
def setup(info)
  @info = info        
end