Class: TZInfo::Country

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/tzinfo/country.rb

Overview

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.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

._load(data) ⇒ Object

Loads a marshalled Country.



174
175
176
 
# File 'lib/tzinfo/country.rb', line 174

def self._load(data)
  Country.get(data)
end

.all ⇒ Object

Returns an Array of all the defined Countries.



76
77
78
 
# File 'lib/tzinfo/country.rb', line 76

def self.all
  data_source.country_codes.collect {|code| get(code)}
end

.all_codes ⇒ Object

Returns an Array of all the valid country codes.



71
72
73
 
# File 'lib/tzinfo/country.rb', line 71

def self.all_codes
  data_source.country_codes
end

.get(identifier) ⇒ Object

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



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# 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) ⇒ Object

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



60
61
62
63
64
65
66
67
68
 
# 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

Instance Method Details

#<=>(c) ⇒ Object

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.



152
153
154
155
 
# File 'lib/tzinfo/country.rb', line 152

def <=>(c)
  return nil unless c.is_a?(Country)
  code <=> c.code
end

#_dump(limit) ⇒ Object

Dumps this Country for marshalling.



169
170
171
 
# File 'lib/tzinfo/country.rb', line 169

def _dump(limit)
  code
end

#code ⇒ Object

The ISO 3166-1 alpha-2 country code.



81
82
83
 
# File 'lib/tzinfo/country.rb', line 81

def code
  @info.code
end

#eql?(c) ⇒ Boolean

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

Returns:

  • (Boolean) 


159
160
161
 
# File 'lib/tzinfo/country.rb', line 159

def eql?(c)
  self == c
end

#hash ⇒ Object

Returns a hash value for this Country.



164
165
166
 
# File 'lib/tzinfo/country.rb', line 164

def hash
  code.hash
end

#inspect ⇒ Object

Returns internal object state as a programmer-readable string.



96
97
98
 
# File 'lib/tzinfo/country.rb', line 96

def inspect
  "#<#{self.class}: #{@info.code}>"
end

#name ⇒ Object

The name of the country.



86
87
88
 
# File 'lib/tzinfo/country.rb', line 86

def name
  @info.name
end

#to_s ⇒ Object

Alias for name.



91
92
93
 
# File 'lib/tzinfo/country.rb', line 91

def to_s
  name
end

#zone_identifiers ⇒ Object Also known as: zone_names

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.



110
111
112
 
# File 'lib/tzinfo/country.rb', line 110

def zone_identifiers
  @info.zone_identifiers
end

#zone_info ⇒ Object

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.



144
145
146
 
# File 'lib/tzinfo/country.rb', line 144

def zone_info
  @info.zones
end

#zones ⇒ Object

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.



127
128
129
130
131
 
# File 'lib/tzinfo/country.rb', line 127

def zones
  zone_identifiers.collect {|id|
    Timezone.get_proxy(id)        
  }
end