123456789_123456789_123456789_123456789_123456789_

Class: TZInfo::Country

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, Comparable
Inherits: Object
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

Instance Method Summary

Constructor Details

.new(info) ⇒ Country

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

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

Parameters:

[ GitHub ] 

  


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



def initialize(info)
  @info = info
end


  







Class Method Details



  

    ._load(data)  ⇒ 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.


  





  
Parameters:


    
  
  • 
    data
    (String)
—    
    a serialized representation of a Country.
    

    
  
    • 



Returns:


    
  
  • 
    (Country)
—    
    the result of converting data back into a Country.
    

    
  
    • 





  [ GitHub ]


  

  


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



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


  








  

    .all  ⇒ Array<Country> 
  



  

    
  





  
Returns:


    
  
  • 
    (Array<Country>)
—    
    an Array containing one Country instance
for each defined country.
    

    
  
    • 





  [ GitHub ]


  

  


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



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


  








  

    .all_codes  ⇒ Array<String> 
  



  

    
  





  
Returns:


    
  
  • 
    (Array<String>)
—    
    an Array containing all the valid ISO 3166-1
alpha-2 country codes.
    

    
  
    • 





  [ GitHub ]


  

  


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



def all_codes
  data_source.country_codes
end


  








  

    .data_source  ⇒ DataSource  (private)
  



  

    
  





  
Returns:





  [ GitHub ]


  

  


# File 'lib/tzinfo/country.rb', line 59



def data_source
  DataSource.get
end


  








  

    .get(code)  ⇒ Country 
  



  

    
Gets a 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 Country instance representing the ISO-3166-1
country identified by the #code parameter.
    

    
  
    • 



Raises:





  [ GitHub ]


  

  


# 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 Country with another based on their #code.


  





  
Parameters:


    
  
  • 
    c
    (Object)
—    
    an Object to compare this Country with.
    

    
  
    • 



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 Country.
    

    
  
    • 





  [ GitHub ]


  

  


# 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 Country.


  





  
Parameters:


    
  
  • 
    regexp
    (Regexp)
—    
    a Regexp to match against the #code of
this Country.
    

    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the position the match starts, or nil if there is no
match.
    

    
  
    • 





  [ GitHub ]


  

  


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



def =~(regexp)
  regexp =~ code
end


  








  

    #_dump(limit)  ⇒ String 
  



  

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


  





  
Parameters:


    
  
  • 
    limit
    (Integer)
—    
    the maximum depth to dump - ignored.
    

    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    a serialized representation of this Country.
    

    
  
    • 





  [ GitHub ]


  

  


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



def _dump(limit)
  code
end


  








  

    #code  ⇒ String 
  



  

    
  





  
Returns:


    
  
  • 
    (String)
—    
    the ISO 3166-1 alpha-2 country code.
    

    
  
    • 





  [ GitHub ]


  

  


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



def code
  @info.code
end


  








  

    #eql?(c)  ⇒ Boolean 
  



  

    
  





  
Parameters:


    
  
  • 
    c
    (Object)
—    
    an Object to compare this Country with.
    

    
  
    • 



Returns:


    
  
  • 
    (Boolean)
—    
    true if c is an instance of Country and has the
same code as self, otherwise false.
    

    
  
    • 





  [ GitHub ]


  

  


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



def eql?(c)
  self == c
end


  








  

    #hash  ⇒ Integer 
  



  

    
  





  
Returns:


    
  
  • 
    (Integer)
—    
    a hash based on the #code.
    

    
  
    • 





  [ GitHub ]


  

  


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



def hash
  code.hash
end


  








  

    #inspect  ⇒ String 
  



  

    
  





  
Returns:


    
  
  • 
    (String)
—    
    the internal object state as a programmer-readable
String.
    

    
  
    • 





  [ GitHub ]


  

  


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



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


  








  

    #name  ⇒ String 
  



  

    
  





  
Returns:


    
  
  • 
    (String)
—    
    the name of the country.
    

    
  
    • 





  [ GitHub ]


  

  


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



def name
  @info.name
end


  








  

    #to_s  ⇒ String 
  



  

    
  





  
Returns:


    
  
  • 
    (String)
—    
    a String representation of this Country (the name of
the country).
    

    
  
    • 





  [ GitHub ]


  

  


# 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. 

  2. puts the most populous zones first, where that does not contradict 1.
    3. 




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
    

    
  
    • 





  [ GitHub ]


  

  


# 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 CountryTimezone instance for each
time zone observed by the country. These are in an order that



    

  1. makes some geographical sense, and
    2. 

  2. puts the most populous zones first, where that does not contradict 1.
    3. 




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.


  





  
Returns:





  [ GitHub ]


  

  


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



def zone_info
  @info.zones
end


  








  

    #zone_names  
  



  

    
Alias for #zone_identifiers.


  



  [ GitHub ]


  

  


# File 'lib/tzinfo/country.rb', line 114



alias zone_names zone_identifiers


  








  

    #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. 

  2. puts the most populous zones first, where that does not contradict 1.
    3. 




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.
    

    
  
    • 





  [ GitHub ]


  

  


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



def zones
  zone_info.map(&:timezone)
end