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 time zones observed by a country. For example:

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.

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

Constructor Details

#initialize(info) ⇒ Country

Initializes a new TZInfo::Country based upon a DataSources::CountryInfo instance.

TZInfo::Country instances should not normally be constructed directly. Use the get method to obtain instances instead.

Parameters:



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

def initialize(info)
  @info = info
end

Class Method Details

._load(data) ⇒ Country

Loads a TZInfo::Country from the serialized representation returned by #_dump. This is method is called when using Marshal.load or Marshal.restore to restore a serialized TZInfo::Country.

Parameters:

Returns:



204
205
206
 
# File 'lib/tzinfo/country.rb', line 204

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

.all ⇒ Array<Country>

Returns an Array containing one TZInfo::Country instance for each defined country.

Returns:



52
53
54
 
# File 'lib/tzinfo/country.rb', line 52

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

.all_codes ⇒ Array<String>

Returns an Array containing all the valid ISO 3166-1 alpha-2 country codes.

Returns:

  • (Array<String>) —

    an Array containing all the valid ISO 3166-1 alpha-2 country codes.



46
47
48
 
# File 'lib/tzinfo/country.rb', line 46

def all_codes
  data_source.country_codes
end

.get(code) ⇒ Country

Gets a TZInfo::Country by its ISO 3166-1 alpha-2 code.

The all_codes method can be used to obtain a list of valid ISO 3166-1 alpha-2 codes.

Parameters:

  • code (String) —

    An ISO 3166-1 alpha-2 code.

Returns:

  • (Country) —

    a TZInfo::Country instance representing the ISO-3166-1 country identified by the code parameter.

Raises:



40
41
42
 
# File 'lib/tzinfo/country.rb', line 40

def get(code)
  Country.new(data_source.get_country_info(code))
end

Instance Method Details

#<=>(c) ⇒ Integer

Compares this TZInfo::Country with another based on their #code.

Parameters:

Returns:

  • (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 TZInfo::Country.



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

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

#=~(regexp) ⇒ Integer

Matches regexp against the #code of this TZInfo::Country.

Parameters:

Returns:

  • (Integer) —

    the position the match starts, or nil if there is no match.



185
186
187
 
# File 'lib/tzinfo/country.rb', line 185

def =~(regexp)
  regexp =~ code
end

#_dump(limit) ⇒ String

Returns a serialized representation of this TZInfo::Country. This method is called when using Marshal.dump with an instance of TZInfo::Country.

Parameters:

  • limit (Integer) —

    the maximum depth to dump - ignored.

Returns:



194
195
196
 
# File 'lib/tzinfo/country.rb', line 194

def _dump(limit)
  code
end

#code ⇒ String

Returns the ISO 3166-1 alpha-2 country code.

Returns:

  • (String) —

    the ISO 3166-1 alpha-2 country code.



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

def code
  @info.code
end

#eql?(c) ⇒ Boolean

Returns true if c is an instance of TZInfo::Country and has the same code as self, otherwise false.

Parameters:

Returns:

  • (Boolean) —

    true if c is an instance of TZInfo::Country and has the same code as self, otherwise false.



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

def eql?(c)
  self == c
end

#hash ⇒ Integer

Returns a hash based on the #code.

Returns:

  • (Integer) —

    a hash based on the #code.



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

def hash
  code.hash
end

#inspect ⇒ String

Returns the internal object state as a programmer-readable String.

Returns:

  • (String) —

    the internal object state as a programmer-readable String.



94
95
96
 
# File 'lib/tzinfo/country.rb', line 94

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

#name ⇒ String

Returns the name of the country.

Returns:

  • (String) —

    the name of the country.



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

def name
  @info.name
end

#to_s ⇒ String

Returns a String representation of this TZInfo::Country (the name of the country).

Returns:

  • (String) —

    a String representation of this TZInfo::Country (the name of the country).



88
89
90
 
# File 'lib/tzinfo/country.rb', line 88

def to_s
  name
end

#zone_identifiers ⇒ Array<String> Also known as: zone_names

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.

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.

Returns:

  • (Array<String>) —

    an Array containing the identifier for each time zone observed by the country



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

def zone_identifiers
  zone_info.map(&:identifier)
end

#zone_info ⇒ Array<CountryTimezone>

Returns a frozen Array containing a TZInfo::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.

The TZInfo::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.

Returns:



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

def zone_info
  @info.zones
end

#zones ⇒ Array<Timezone>

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.

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.

Returns:

  • (Array<Timezone>) —

    an Array containing a Timezone instance for each time zone observed by the country.



132
133
134
 
# File 'lib/tzinfo/country.rb', line 132

def zones
  zone_info.map(&:timezone)
end