Class: Addressing::Country

Inherits:
Object
  • Object
show all
Defined in:
lib/addressing/country.rb

Overview

Provides country information including names, codes, currency, and timezones.

Country names are available in over 250 locales powered by CLDR data.

Examples:

Get a country by code

brazil = Addressing::Country.get('BR')
brazil.name          # => "Brazil"
brazil.currency_code # => "BRL"

Get all countries

countries = Addressing::Country.all('fr-FR')

Get a simple list of countries

list = Addressing::Country.list('en')

Constant Summary collapse

AVAILABLE_LOCALES = 
[
  "af", "am", "ar", "ar-LY", "ar-SA", "as", "az", "be", "bg", "bn",
  "bn-IN", "bs", "ca", "chr", "cs", "cy", "da", "de", "de-AT", "de-CH",
  "dsb", "el", "el-polyton", "en", "en-001", "en-AU", "en-CA", "en-ID",
  "en-MV", "es", "es-419", "es-AR", "es-BO", "es-CL", "es-CO", "es-CR",
  "es-DO", "es-EC", "es-GT", "es-HN", "es-MX", "es-NI", "es-PA", "es-PE",
  "es-PR", "es-PY", "es-SV", "es-US", "es-VE", "et", "eu", "fa", "fa-AF",
  "fi", "fil", "fr", "fr-BE", "fr-CA", "ga", "gd", "gl", "gu", "he",
  "hi", "hi-Latn", "hr", "hsb", "hu", "hy", "id", "ig", "is", "it", "ja",
  "ka", "kk", "km", "ko", "ko-KP", "kok", "ky", "lo", "lt", "lv", "mk",
  "ml", "mn", "mr", "ms", "my", "ne", "nl", "nn", "no", "or", "pa", "pl",
  "ps", "ps-PK", "pt", "pt-PT", "ro", "ro-MD", "ru", "ru-UA", "si", "sk",
  "sl", "so", "sq", "sr", "sr-Cyrl-BA", "sr-Cyrl-ME", "sr-Cyrl-XK",
  "sr-Latn", "sr-Latn-BA", "sr-Latn-ME", "sr-Latn-XK", "sv", "sw",
  "sw-CD", "sw-KE", "ta", "te", "th", "tk", "tr", "uk", "ur", "ur-IN",
  "uz", "vi", "yue", "yue-Hans", "zh", "zh-Hant", "zh-Hant-HK", "zu"
]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(definition = {}) ⇒ Country

Returns a new instance of Country.



380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
 
# File 'lib/addressing/country.rb', line 380

def initialize(definition = {})
  # Validate the presence of required properties.
  [:country_code, :name, :locale].each do |required_property|
    if definition[required_property].nil?
      raise ArgumentError, "Missing required property #{required_property}."
    end
  end

  @country_code = definition[:country_code]
  @name = definition[:name]
  @three_letter_code = definition[:three_letter_code]
  @numeric_code = definition[:numeric_code]
  @currency_code = definition[:currency_code]
  @locale = definition[:locale]
end

Instance Attribute Details

#country_code ⇒ Object (readonly)

Returns the value of attribute country_code.



378
379
380
 
# File 'lib/addressing/country.rb', line 378

def country_code
  @country_code
end

#currency_code ⇒ Object (readonly)

Returns the value of attribute currency_code.



378
379
380
 
# File 'lib/addressing/country.rb', line 378

def currency_code
  @currency_code
end

#locale ⇒ Object (readonly)

Returns the value of attribute locale.



378
379
380
 
# File 'lib/addressing/country.rb', line 378

def locale
  @locale
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



378
379
380
 
# File 'lib/addressing/country.rb', line 378

def name
  @name
end

#numeric_code ⇒ Object (readonly)

Returns the value of attribute numeric_code.



378
379
380
 
# File 'lib/addressing/country.rb', line 378

def numeric_code
  @numeric_code
end

#three_letter_code ⇒ Object (readonly)

Returns the value of attribute three_letter_code.



378
379
380
 
# File 'lib/addressing/country.rb', line 378

def three_letter_code
  @three_letter_code
end

Class Method Details

.all(locale = "en", fallback_locale = "en") ⇒ Hash<String, Country>

Gets all Country instances.

Parameters:

  • locale (String) (defaults to: "en") —

    Locale for country names (default: “en”)

  • fallback_locale (String) (defaults to: "en") —

    Fallback locale if requested locale is unavailable

Returns:

  • (Hash<String, Country>) —

    Hash of country code => Country instance



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/addressing/country.rb', line 68

def all(locale = "en", fallback_locale = "en")
  locale = Locale.resolve(AVAILABLE_LOCALES, locale, fallback_locale)
  definitions = load_definitions(locale)

  definitions.map do |country_code, country_name|
    country = new(
      country_code: country_code,
      name: country_name,
      three_letter_code: base_definitions[country_code][0],
      numeric_code: base_definitions[country_code][1],
      currency_code: base_definitions[country_code][2],
      locale: locale
    )

    [country_code, country]
  end.to_h
end

.get(country_code, locale = "en", fallback_locale = "en") ⇒ Country

Gets a Country instance for the provided country code.

Parameters:

  • country_code (String) —

    ISO 3166-1 alpha-2 country code

  • locale (String) (defaults to: "en") —

    Locale for the country name (default: “en”)

  • fallback_locale (String) (defaults to: "en") —

    Fallback locale if requested locale is unavailable

Returns:

Raises:



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/addressing/country.rb', line 45

def get(country_code, locale = "en", fallback_locale = "en")
  country_code = country_code.upcase

  raise UnknownCountryError.new(country_code) unless base_definitions.key?(country_code)

  locale = Locale.resolve(AVAILABLE_LOCALES, locale, fallback_locale)
  definitions = load_definitions(locale)

  new(
    country_code: country_code,
    name: definitions[country_code],
    three_letter_code: base_definitions[country_code][0],
    numeric_code: base_definitions[country_code][1],
    currency_code: base_definitions[country_code][2],
    locale: locale
  )
end

.list(locale = "en", fallback_locale = "en") ⇒ Hash<String, String>

Gets a list of country codes and names.

Parameters:

  • locale (String) (defaults to: "en") —

    Locale for country names (default: “en”)

  • fallback_locale (String) (defaults to: "en") —

    Fallback locale if requested locale is unavailable

Returns:

  • (Hash<String, String>) —

    Hash of country code => country name



91
92
93
94
95
96
97
98
 
# File 'lib/addressing/country.rb', line 91

def list(locale = "en", fallback_locale = "en")
  locale = Locale.resolve(AVAILABLE_LOCALES, locale, fallback_locale)
  definitions = load_definitions(locale)

  definitions.map do |country_code, country_name|
    [country_code, country_name]
  end.to_h
end

Instance Method Details

#timezones ⇒ Object

Gets the timezones.

Note that a country can span more than one timezone. For example, Germany has [“Europe/Berlin”, “Europe/Busingen”].



400
401
402
 
# File 'lib/addressing/country.rb', line 400

def timezones
  @timezones ||= TZInfo::Country.get(@country_code).zone_identifiers
end

#to_s ⇒ Object

Gets the string representation of the Country.



405
406
407
 
# File 'lib/addressing/country.rb', line 405

def to_s
  @country_code
end