countries 4.1.1 → 4.2.1

data/lib/countries/country/class_methods.rb

@@ -39,7 +39,7 @@ module ISO3166
 
     def all_names_with_codes(locale = 'en')
       Country.all.map do |c|
-        lc = (c.translation(locale) || c.name)
+        lc = (c.translation(locale) || c.iso_short_name)
         [lc.respond_to?('html_safe') ? lc.html_safe : lc, c.alpha2]
       end.sort
     end
@@ -55,7 +55,7 @@ module ISO3166
 
       custom_countries = (ISO3166::Data.codes - i18n_data_countries.keys).map do |code|
         country = ISO3166::Country[code]
-        translation = country.translations[locale] || country.name
+        translation = country.translations[locale] || country.iso_short_name
         [code, translation]
       end.to_h
 
@@ -76,6 +76,14 @@ module ISO3166
       return_all = matches[1]
       super unless matches
 
+      if matches[3] == 'names'
+        if RUBY_VERSION =~ /^3\.\d\.\d/
+          warn "DEPRECATION WARNING: 'find_by_name' and 'find_*_by_name' methods are deprecated, please refer to the README file for more information on this change.", uplevel: 1, category: :deprecated
+        else
+          warn "DEPRECATION WARNING: 'find_by_name' and 'find_*_by_name' methods are deprecated, please refer to the README file for more information on this change.", uplevel: 1
+        end
+      end
+
       countries = find_by(matches[3], arguments[0], matches[2])
       return_all ? countries : countries.last
     end
@@ -128,10 +136,15 @@ module ISO3166
       raise "Invalid attribute name '#{attribute}'" unless searchable_attribute?(attribute.to_sym)
 
       attributes = Array(attribute.to_s)
-      if attributes == ['name']
-        attributes << 'unofficial_names'
-        # TODO: Revisit when better data from i18n_data
-        # attributes << 'translated_names'
+      if attribute.to_s == 'name'
+        if RUBY_VERSION =~ /^3\.\d\.\d/
+          warn "DEPRECATION WARNING: 'find_by_name' and 'find_*_by_name' methods are deprecated, please refer to the README file for more information on this change.", uplevel: 1, category: :deprecated
+        else
+          warn "DEPRECATION WARNING: 'find_by_name' and 'find_*_by_name' methods are deprecated, please refer to the README file for more information on this change.", uplevel: 1
+        end
+        # 'find_by_name' and 'find_*_by_name' will be changed for 5.0
+        # The addition of 'iso_short_name' here ensures the behaviour of 4.1 is kept for 4.2
+        attributes = %w[iso_short_name unofficial_names translated_names]
       end
 
       [attributes, parse_value(val)]

data/lib/countries/country/currency_methods.rb

@@ -1,8 +1,11 @@
 require 'money'
 
 module ISO3166
-  # Optional extension which allows you to get back a Money::Currency object with all the currency info
+  # Optional extension which allows you to get back a +Money::Currency+ object with all the currency info.
+  # This requires enabling the integration with the {Money}[https://github.com/RubyMoney/money] gem (See {ISO3166::Configuration#enable_currency_extension!})
   module CountryCurrencyMethods
+
+    # @return [Money::Currency] The currency data for this Country's +currency_code+
     def currency
       Money::Currency.find(data['currency_code'])
     end

data/lib/countries/country/emoji.rb

@@ -32,6 +32,9 @@ module ISO3166
       'z' => '🇿'
     }.freeze
 
+    # @return [String] the emoji flag for this country
+    #
+    # The emoji flag for this country, using Unicode Regional Indicator characters. e.g: "U+1F1FA U+1F1F8" for 🇺🇸
     def emoji_flag
       alpha2.downcase.chars.map { |c| CODE_POINTS[c] }.join('')
     end

data/lib/countries/country.rb

@@ -30,7 +30,24 @@ module ISO3166
     alias postal_code? postal_code
     alias zip_format postal_code_format
     alias languages languages_official
-    alias names unofficial_names
+
+    def latitude_dec
+      if RUBY_VERSION =~ /^3\.\d\.\d/
+        warn "DEPRECATION WARNING: The Country#latitude_dec method has been deprecated and will be removed in 5.0. Please use Country#latitude instead.", uplevel: 1, category: :deprecated
+      else
+        warn "DEPRECATION WARNING: The Country#latitude_dec method has been deprecated and will be removed in 5.0. Please use Country#latitude instead.", uplevel: 1
+      end
+      latitude
+    end
+
+    def longitude_dec
+      if RUBY_VERSION =~ /^3\.\d\.\d/
+        warn "DEPRECATION WARNING: The Country#longitude_dec method has been deprecated and will be removed in 5.0. Please use Country#longitude instead.", uplevel: 1, category: :deprecated
+      else
+        warn "DEPRECATION WARNING: The Country#longitude_dec method has been deprecated and will be removed in 5.0. Please use Country#longitude instead.", uplevel: 1
+      end
+      longitude
+    end
 
     def ==(other)
       other.respond_to?(:alpha2) && other.alpha2 == alpha2
@@ -48,14 +65,12 @@ module ISO3166
       to_s <=> other.to_s
     end
 
-    def start_of_week
-      data['start_of_week']
-    end
-
+    #  +true+ if this Country has any Subdivisions.
     def subdivisions?
       !subdivisions.empty?
     end
 
+    # @return [Array<ISO3166::Subdivision>] the list of subdivisions for this Country.
     def subdivisions
       @subdivisions ||= if data['subdivisions']
                           self.class.create_subdivisions(data['subdivisions'])
@@ -64,37 +79,51 @@ module ISO3166
                         end
     end
 
+    # @param locale [String] The locale to use for translations.
+    # @return [Array<Array>] This Country's subdivision pairs of names and codes.
     def subdivision_names_with_codes(locale = 'en')
       subdivisions.map { |k, v| [v.translations[locale] || v.name, k] }
     end
 
     alias states subdivisions
 
+    # +true+ if this country is a member of the European Union.
     def in_eu?
       data['eu_member'].nil? ? false : data['eu_member']
     end
 
+    # +true+ if this country is a member of the European Economic Area.
     def in_eea?
       data['eea_member'].nil? ? false : data['eea_member']
     end
 
+    # +true+ if this country is a member of the European Single Market.
     def in_esm?
       data['esm_member'].nil? ? in_eea? : data['esm_member']
     end
 
     def to_s
-      data['name']
+      data['iso_short_name']
     end
 
+    # @return [Array<String>] the list of names for this Country in all loaded locales.
     def translated_names
       data['translations'].values
     end
 
+    # @param locale [String] The locale to use for translations.
+    # @return [String] the name of this Country in the selected locale.
     def translation(locale = 'en')
       data['translations'][locale.to_s.downcase]
     end
 
-    # TODO: Looping through locale langs could be be very slow across multiple countries
+    # @return [String] the “common name” of this Country in English.
+    def common_name
+      ISO3166.configuration.locales = ISO3166.configuration.locales.append(:en).uniq
+      translation('en')
+    end
+
+    # @return [Array<String>] TThe list of names for this Country, in this Country's locales.
     def local_names
       ISO3166.configuration.locales = (ISO3166.configuration.locales + languages.map(&:to_sym)).uniq
       reload
@@ -102,10 +131,121 @@ module ISO3166
       @local_names ||= languages.map { |language| translations[language] }
     end
 
+    # @return [String] The name for this Country, in this Country's locale.
     def local_name
       @local_name ||= local_names.first
     end
 
+    # @return [String] This Country's ISO Short Name
+    # @deprecated Use {#iso_short_name} instead.
+    def name
+      if RUBY_VERSION =~ /^3\.\d\.\d/
+        warn "DEPRECATION WARNING: The Country#name method has been deprecated. Please use Country#iso_short_name instead or refer to the README file for more information on this change.", uplevel: 1, category: :deprecated
+      else
+        warn "DEPRECATION WARNING: The Country#name method has been deprecated. Please use Country#iso_short_name instead or refer to the README file for more information on this change.", uplevel: 1
+      end
+      iso_short_name
+    end
+
+    # @return [Array<String>] Array of unofficial, slang names or aliases for this Country
+    # @deprecated Use {#unofficial_names} instead.
+    def names
+      if RUBY_VERSION =~ /^3\.\d\.\d/
+        warn "DEPRECATION WARNING: The Country#names method has been deprecated. Please use Country#unofficial_names instead or refer to the README file for more information on this change.", uplevel: 1, category: :deprecated
+      else
+        warn "DEPRECATION WARNING: The Country#names method has been deprecated. Please use Country#unofficial_names instead or refer to the README file for more information on this change.", uplevel: 1
+      end
+      unofficial_names
+    end
+
+    # @!attribute alpha2
+    #   @return [String] the ISO3166 alpha-2 code for this Country
+    #
+    # @!attribute alpha3
+    #   @return [String] the ISO3166 alpha-3 code for this Country
+    #
+    # @!attribute address_format
+    #   @return [String] a template for formatting addresses in this Country.
+    #
+    # @!attribute continent
+    #   @return [String] the continent for this Country
+    #
+    # @!attribute country_code
+    #   @return [String] the country calling code for this Country
+    #
+    # @!attribute currency_code
+    #   @return [String] the ISO 4217 currency code for this Country
+    #
+    # @!attribute gec
+    #   @return [String] the "Geopolitical Entities and Codes", formerly FIPS 10-4 code for this Country
+    #
+    # @!attribute geo
+    #   @return [Hash] the hash of coordinates for this Country.
+    #
+    # @!attribute international_prefix
+    #   @return [String] the phone prefix used in this Country for dialing international numbers
+    #
+    # @!attribute ioc
+    #   @return [String] The International Olympic Committee code for for this Country
+    #
+    # @!attribute national_destination_code_lengths
+    #   @return [Array<Integer>] Lengths of phone number destination codes
+    #
+    # @!attribute national_number_lengths
+    #   @return [Array<Integer>] Lengths of phone numbers
+    #
+    # @!attribute national_prefix
+    #   @return [String] the phone prefix used in this Country for dialing national numbers
+    #
+    # @!attribute nanp_prefix
+    #   @return [String] the NANP prefix code
+    #
+    # @!attribute nationality
+    #   @return [String] the nationality for this Country, in English
+    #
+    # @!attribute number
+    #   @return [String] The ISO 3166-1 numeric code for this Country
+    #
+    # @!attribute languages_official
+    #   @return [Array<String>] the list of official languages (locale codes) for this Country
+    #
+    # @!attribute languages_spoken
+    #   @return [Array<String>] the list of spoken languages (locale codes) for this Country
+    #
+    # @!attribute translations
+    #   @return [Hash] The hash of country name translations for this Country.
+    #
+    # @!attribute postal_code
+    #   @return [Boolean] Does this Country uses postal codes in addresses
+    #
+    # @!attribute postal_code_format
+    #   @return [String] The regex for valid postal codes in this Country
+    #
+    # @!attribute region
+    #   @return [String] The Region this country is in. Approximately matches the United Nations geoscheme
+    #
+    # @!attribute unofficial_names
+    #   @return [Array<String>] Array of unofficial, slang names or aliases for this Country
+    #
+    # @!attribute start_of_week
+    # @return [String] The starting day of the week ( +'monday'+ or +'sunday'+ )
+    #
+    # @!attribute subregion
+    #   @return [String] The Subegion this country is in. Approximately matches the United Nations geoscheme's Subregions
+    #
+    # @!attribute un_locode
+    #   @return [String] The UN/LOCODE prefix for this Country
+    #
+    # @!attribute vat_rates
+    #   @return [Hash] the hash of VAT Rates for this Country
+    #
+    # @!attribute world_region
+    #   @return [String] The "World Region" this country is in: +"AMER"+ , +"APAC"+ or +"EMEA"+
+
+
+
+    private
+
     def reload
       @data = if @country_data_or_code.is_a?(Hash)
                 @country_data_or_code

data/lib/countries/data/countries/AD.yaml

@@ -1,13 +1,33 @@
 ---
 AD:
-  continent: Europe
   alpha2: AD
   alpha3: AND
+  continent: Europe
   country_code: '376'
+  currency_code: EUR
+  gec: AN
+  geo:
+    latitude: 42.506285
+    longitude: 1.521801
+    max_latitude: 42.655791
+    max_longitude: 1.786639
+    min_latitude: 42.4287488
+    min_longitude: 1.4087052
+    bounds:
+      northeast:
+        lat: 42.655791
+        lng: 1.786639
+      southwest:
+        lat: 42.4287488
+        lng: 1.4087052
   international_prefix: '00'
   ioc: AND
-  gec: AN
-  name: Andorra
+  iso_long_name: The Principality of Andorra
+  iso_short_name: Andorra
+  languages_official:
+  - ca
+  languages_spoken:
+  - ca
   national_destination_code_lengths:
   - 2
   national_number_lengths:
@@ -16,37 +36,16 @@ AD:
   - 8
   - 9
   national_prefix: None
+  nationality: Andorran
   number: '020'
+  postal_code: true
+  postal_code_format: AD[1-7]0\d
   region: Europe
+  start_of_week: monday
   subregion: Southern Europe
-  world_region: EMEA
   un_locode: AD
-  nationality: Andorran
-  postal_code: true
-  postal_code_format: AD[1-7]0\d
   unofficial_names:
   - Andorre
   - Andorra
   - アンドラ
-  languages_official:
-  - ca
-  languages_spoken:
-  - ca
-  geo:
-    latitude: 42.506285
-    latitude_dec: '42.5506591796875'
-    longitude: 1.521801
-    longitude_dec: '1.5762332677841187'
-    max_latitude: 42.655791
-    max_longitude: 1.786639
-    min_latitude: 42.4287488
-    min_longitude: 1.4087052
-    bounds:
-      northeast:
-        lat: 42.655791
-        lng: 1.786639
-      southwest:
-        lat: 42.4287488
-        lng: 1.4087052
-  currency_code: EUR
-  start_of_week: monday
+  world_region: EMEA

data/lib/countries/data/countries/AE.yaml

@@ -1,6 +1,5 @@
 ---
 AE:
-  continent: Asia
   address_format: |-
     {{recipient}}
     {{street}}
@@ -8,11 +7,32 @@ AE:
     {{country}}
   alpha2: AE
   alpha3: ARE
+  continent: Asia
   country_code: '971'
+  currency_code: AED
+  gec: AE
+  geo:
+    latitude: 23.424076
+    longitude: 53.847818
+    max_latitude: 26.0765
+    max_longitude: 56.4395001
+    min_latitude: 22.6315138
+    min_longitude: 51.4723
+    bounds:
+      northeast:
+        lat: 26.0765
+        lng: 56.4395001
+      southwest:
+        lat: 22.6315138
+        lng: 51.4723
   international_prefix: '00'
   ioc: UAE
-  gec: AE
-  name: United Arab Emirates
+  iso_long_name: The United Arab Emirates
+  iso_short_name: United Arab Emirates
+  languages_official:
+  - ar
+  languages_spoken:
+  - ar
   national_destination_code_lengths:
   - 2
   national_number_lengths:
@@ -20,18 +40,13 @@ AE:
   - 8
   - 9
   national_prefix: '0'
+  nationality: Emirian
   number: '784'
+  postal_code: false
   region: Asia
+  start_of_week: sunday
   subregion: Western Asia
-  world_region: EMEA
   un_locode: AE
-  nationality: Emirian
-  vat_rates:
-    standard: 5
-    reduced: []
-    super_reduced: 
-    parking: 
-  postal_code: false
   unofficial_names:
   - United Arab Emirates
   - الإمارات العربية المتحدة
@@ -40,25 +55,9 @@ AE:
   - Emiratos Árabes Unidos
   - アラブ首長国連邦
   - Verenigde Arabische Emiraten
-  languages_official:
-  - ar
-  languages_spoken:
-  - ar
-  geo:
-    latitude: 23.424076
-    latitude_dec: '23.684776306152344'
-    longitude: 53.847818
-    longitude_dec: '54.536643981933594'
-    max_latitude: 26.0765
-    max_longitude: 56.4395001
-    min_latitude: 22.6315138
-    min_longitude: 51.4723
-    bounds:
-      northeast:
-        lat: 26.0765
-        lng: 56.4395001
-      southwest:
-        lat: 22.6315138
-        lng: 51.4723
-  currency_code: AED
-  start_of_week: sunday
+  vat_rates:
+    standard: 5
+    reduced: []
+    super_reduced:
+    parking:
+  world_region: EMEA

data/lib/countries/data/countries/AF.yaml

@@ -1,44 +1,14 @@
 ---
 AF:
-  continent: Asia
   alpha2: AF
   alpha3: AFG
+  continent: Asia
   country_code: '93'
-  international_prefix: '00'
-  ioc: AFG
+  currency_code: AFN
   gec: AF
-  name: Afghanistan
-  national_destination_code_lengths:
-  - 2
-  national_number_lengths:
-  - 8
-  - 9
-  national_prefix: '0'
-  number: '004'
-  region: Asia
-  subregion: Southern Asia
-  world_region: APAC
-  un_locode: AF
-  nationality: Afghan
-  postal_code: true
-  postal_code_format: "\\d{4}"
-  unofficial_names:
-  - Afghanistan
-  - Afganistán
-  - アフガニスタン
-  languages_official:
-  - ps
-  - uz
-  - tk
-  languages_spoken:
-  - ps
-  - uz
-  - tk
   geo:
     latitude: 33.93911
-    latitude_dec: '33.833248138427734'
     longitude: 67.709953
-    longitude_dec: '66.02528381347656'
     max_latitude: 38.49087670000001
     max_longitude: 74.8898619
     min_latitude: 29.3772
@@ -50,5 +20,34 @@ AF:
       southwest:
         lat: 29.3772
         lng: 60.5170005
-  currency_code: AFN
+  international_prefix: '00'
+  ioc: AFG
+  iso_long_name: The Islamic Republic of Afghanistan
+  iso_short_name: Afghanistan
+  languages_official:
+  - ps
+  - uz
+  - tk
+  languages_spoken:
+  - ps
+  - uz
+  - tk
+  national_destination_code_lengths:
+  - 2
+  national_number_lengths:
+  - 8
+  - 9
+  national_prefix: '0'
+  nationality: Afghan
+  number: '004'
+  postal_code: true
+  postal_code_format: "\\d{4}"
+  region: Asia
   start_of_week: monday
+  subregion: Southern Asia
+  un_locode: AF
+  unofficial_names:
+  - Afghanistan
+  - Afganistán
+  - アフガニスタン
+  world_region: APAC

data/lib/countries/data/countries/AG.yaml

@@ -1,26 +1,46 @@
 ---
 AG:
-  continent: North America
   alpha2: AG
   alpha3: ATG
+  continent: North America
   country_code: '1'
-  nanp_prefix: '1268'
+  currency_code: XCD
+  gec: AC
+  geo:
+    latitude: 17.060816
+    longitude: -61.796428
+    max_latitude: 17.7499946
+    max_longitude: -61.6394
+    min_latitude: 16.9018
+    min_longitude: -62.38100009999999
+    bounds:
+      northeast:
+        lat: 17.7499946
+        lng: -61.6394
+      southwest:
+        lat: 16.9018
+        lng: -62.38100009999999
   international_prefix: '011'
   ioc: ANT
-  gec: AC
-  name: Antigua and Barbuda
+  iso_long_name: Antigua and Barbuda
+  iso_short_name: Antigua and Barbuda
+  languages_official:
+  - en
+  languages_spoken:
+  - en
+  nanp_prefix: '1268'
   national_destination_code_lengths:
   - 3
   national_number_lengths:
   - 10
   national_prefix: '1'
+  nationality: Antiguan, Barbudan
   number: '028'
+  postal_code: false
   region: Americas
+  start_of_week: monday
   subregion: Caribbean
-  world_region: AMER
   un_locode: AG
-  nationality: Antiguan, Barbudan
-  postal_code: false
   unofficial_names:
   - Antigua and Barbuda
   - Antigua und Barbuda
@@ -28,25 +48,4 @@ AG:
   - Antigua y Barbuda
   - アンティグア・バーブーダ
   - Antigua en Barbuda
-  languages_official:
-  - en
-  languages_spoken:
-  - en
-  geo:
-    latitude: 17.060816
-    latitude_dec: '17.09273910522461'
-    longitude: -61.796428
-    longitude_dec: "-61.81040954589844"
-    max_latitude: 17.7499946
-    max_longitude: -61.6394
-    min_latitude: 16.9018
-    min_longitude: -62.38100009999999
-    bounds:
-      northeast:
-        lat: 17.7499946
-        lng: -61.6394
-      southwest:
-        lat: 16.9018
-        lng: -62.38100009999999
-  currency_code: XCD
-  start_of_week: monday
+  world_region: AMER

data/lib/countries/data/countries/AI.yaml

@@ -1,39 +1,14 @@
 ---
 AI:
-  continent: North America
   alpha2: AI
   alpha3: AIA
+  continent: North America
   country_code: '1'
-  nanp_prefix: '1264'
-  international_prefix: '011'
-  ioc: 
+  currency_code: XCD
   gec: AV
-  name: Anguilla
-  national_destination_code_lengths:
-  - 3
-  national_number_lengths:
-  - 10
-  national_prefix: '1'
-  number: '660'
-  region: Americas
-  subregion: Caribbean
-  world_region: AMER
-  un_locode: AI
-  nationality: Anguillian
-  postal_code: true
-  postal_code_format: "(?:AI-)?2640"
-  unofficial_names:
-  - Anguilla
-  - アンギラ
-  languages_official:
-  - en
-  languages_spoken:
-  - en
   geo:
     latitude: 18.220554
-    latitude_dec: '18.22646713256836'
     longitude: -63.06861499999999
-    longitude_dec: "-63.0473518371582"
     max_latitude: 18.6332326
     max_longitude: -62.91999999999999
     min_latitude: 18.1465043
@@ -45,5 +20,29 @@ AI:
       southwest:
         lat: 18.1465043
         lng: -63.4803
-  currency_code: XCD
+  international_prefix: '011'
+  ioc:
+  iso_long_name: Anguilla
+  iso_short_name: Anguilla
+  languages_official:
+  - en
+  languages_spoken:
+  - en
+  nanp_prefix: '1264'
+  national_destination_code_lengths:
+  - 3
+  national_number_lengths:
+  - 10
+  national_prefix: '1'
+  nationality: Anguillian
+  number: '660'
+  postal_code: true
+  postal_code_format: "(?:AI-)?2640"
+  region: Americas
   start_of_week: monday
+  subregion: Caribbean
+  un_locode: AI
+  unofficial_names:
+  - Anguilla
+  - アンギラ
+  world_region: AMER