itu_codes 0.4.3 → 0.4.7

data/README.md

@@ -9,74 +9,114 @@ Country code lookup based on official ISO-3166-1 specifications:
 * [Country Codes - ISO 3166][3]
 * [list of alpha-2 country codes in XML format][4]
 
+The main goal of this library is to closely match the latest official specifications from the ITU and the ISO relating to callign codes. If you find any discrepancies in the data, please let me know!
+
+Some complicating factors when dealing with calling codes:
+* In North America, 25 countries and territories follow the [North American Numbering Plan][5] and share the ITU code '1'.
+* Russia and Kazakhstan share the ITU code '7'.
+* The ITU does not use ISO 3166 alpha-2 codes to specify countries or regions in its documents.
+* In general, each ITU code corresponds to exactly one ISO 3166 code. However, there are exceptions. For examples, the Australian External Territories have a single ITU code of '672', but have 4 distinct ISO 3166 codes (CC, CX, HM, NF).
+
+
 ## Usage:
 
-    ItuCodes.valid_code? '8392813'
-    # => false
+```ruby
+
+# The following methods are provided:
+
+# ItuCodes.country_for(full_or_partial_number)
+# ItuCodes.find_by_itu_code(code)
+# ItuCodes.find_by_name(country_name)
+# ItuCodes.valid_code?(exact_itu_code)
+# ItuCodes.parse_code(full_or_partial_number)
+# ItuCodes.parse_number(full_or_partial_number)
+# ItuCodes.iso2itu(iso_2_letter_country_code)
+# ItuCodes.itu2iso(exact_itu_code)
+# ItuCodes.compatriots?(full_or_partial_number1, full_or_partial_number2)
+
+
+# Examples
+
+# Any full or partial number will work
+ItuCodes.country_for('33')
+# => "France"
+
+# Country names are returned EXACTLY as specified in ITU E.164 document
+ItuCodes.country_for('18184442222')
+# => "United States of America"
+
+ItuCodes.country_for('7')
+# => [ "Kazakhstan (Republic of)", "Russian Federation" ]
+
+ItuCodes.find_by_itu_code '995'
+# => "Georgia"
 
-    ItuCodes.valid_code? '7'
-    # => true
+ItuCodes.find_by_itu_code '123123995'
+# => nil
 
-    ItuCodes.parse_code '1818'
-    # => 1
+# Name should match EXACTLY as specified in ITU E.164 document
+# ItuCodes.iso2itu accepts 2 letter ISO 3166 codes
+ItuCodes.find_by_name 'France'
+# => "33"
 
-    ItuCodes.parse_code '822'
-    # => "82"
+ItuCodes.find_by_name 'Erewhon'
+# => nil
 
-    ItuCodes.parse_code '4'
-    # => nil
+ItuCodes.valid_code? '8392813'
+# => false
 
-    ItuCodes.find_by_name 'France'
-    # => "33"
+ItuCodes.valid_code? '7'
+# => true
 
-    ItuCodes.find_by_itu_code '995'
-    # => "Georgia"
+ItuCodes.parse_code '18185558888'
+# => 1
 
-    ItuCodes.find_by_name 'Erewhon'
-    # => nil
+ItuCodes.parse_code '822'
+# => "82"
 
-    ItuCodes.find_by_itu_code '123123995'
-    # => nil
+ItuCodes.parse_code '4'
+# => nil
 
-    # Despite the same 1st digit,
-    # these are for different
-    # countries ...
-    ItuCodes.compatriots? '822', '811'
-    # => false
+ItuCodes.parse_number '18185558888'
+# => "8185558888"
 
-    # ... but these are for
-    # the same country ...
-    ItuCodes.compatriots? '1984', '1985'
-    # => true
+# Convert from and to ISO 2-letter country codes:
+ItuCodes.iso2itu('US')
+# => "1"
 
-    # ... and then there's the
-    # North American 'situation' ...
-    ItuCodes.compatriots? '1264', '1818'
-    # => false
+# Convert from and to ISO 2-letter country codes:
+ItuCodes.itu2iso('1')
+# => ["AS", "AI", "AG", "BS", "BB", "BM", "VG", "CA", "KY", "DM", "DO", "GD", "GU", "JM", "MS", "MP", "PR", "KN", "LC", "VC", "SX", "TT", "TC", "US", "VI"]
 
-    # =====================================================
-    # = Using 2-letter ISO country codes is most reliable =
-    # =====================================================
+# Mexico
+# ISO 3361 code : MX
+# ITU code      : 52
+ItuCodes.iso2itu('MX')
+# => "52"
 
-    # Convert from and to ISO 2-letter country codes:
-    ItuCodes.iso2itu('US')
-    # => "1"
+ItuCodes.itu2iso('52')
+# => "MX"
 
-    # Convert from and to ISO 2-letter country codes:
-    ItuCodes.itu2iso('1')
-    # => ["AS", "AI", "AG", "BS", "BB", "BM", "VG", "CA", "KY", "DM", "DO", "GD", "GU", "JM", "MS", "MP", "PR", "KN", "LC", "VC", "SX", "TT", "TC", "US", "VI"]
+# Despite the same 1st digit,
+# these are for different
+# countries ...
+ItuCodes.compatriots? '822', '811'
+# => false
 
-    # Mexico
-    # ISO 3361 code : MX
-    # ITU code      : 52
-    ItuCodes.iso2itu('MX')
-    # => "52"
+# ... but these are for
+# the same country ...
+ItuCodes.compatriots? '1984', '1985'
+# => true
 
-    ItuCodes.itu2iso('52')
-    # => "MX"
+# ... and then there's the
+# North American 'situation' ...
+ItuCodes.compatriots? '1264', '1818'
+# => false
 
+```
 
 [1]: http://www.itu.int/pub/T-SP-E.164D-11-2011
 [2]: http://www.itu.int/dms_pub/itu-t/opb/sp/T-SP-E.164D-11-2011-PDF-E.pdf
 [3]: http://www.iso.org/iso/home/standards/country_codes
-[4]: http://www.iso.org/iso/home/standards/country_codes/country_names_and_code_elements_xml
+[4]: http://www.iso.org/iso/home/standards/country_codes/country_names_and_code_elements_xml
+[5]: http://www.nanpa.com

data/lib/data/north_american_area_codes.yml

@@ -4,6 +4,90 @@
 #   * http://www.itu.int/pub/T-SP-E.164D-11-2011
 #   * vendor/itu/T-SP-E.164D-11-2011-PDF-E.pdf
 
+American Samoa:
+  - '1684'
+Anguilla:
+  - '1264'
+Antigua and Barbuda:
+  - '1268'
+Bahamas (Commonwealth of the):
+  - '1242'
+Barbados:
+  - '1246'
+Bermuda:
+  - '1441'
+British Virgin Islands:
+  - '1284'
+Canada:
+  - '1204'
+  - '1226'
+  - '1236'
+  - '1249'
+  - '1250'
+  - '1289'
+  - '1306'
+  - '1343'
+  - '1365'
+  - '1403'
+  - '1416'
+  - '1418'
+  - '1431'
+  - '1437'
+  - '1438'
+  - '1450'
+  - '1506'
+  - '1514'
+  - '1519'
+  - '1579'
+  - '1581'
+  - '1587'
+  - '1604'
+  - '1613'
+  - '1639'
+  - '1647'
+  - '1705'
+  - '1709'
+  - '1778'
+  - '1780'
+  - '1807'
+  - '1819'
+  - '1867'
+  - '1873'
+  - '1902'
+  - '1905'
+Cayman Islands:
+  - '1345'
+Dominica (Commonwealth of):
+  - '1767'
+Dominican Republic:
+  - '1809'
+  - '1829'
+  - '1849'
+Grenada:
+  - '1473'
+Guam:
+  - '1671'
+Jamaica:
+  - '1876'
+Montserrat:
+  - '1664'
+Northern Mariana Islands (Commonwealth of the):
+  - '1670'
+Puerto Rico:
+  - '1787'
+  - '1939'
+Saint Kitts and Nevis:
+  - '1869'
+Saint Lucia:
+  - '1758'
+Saint Vincent and the Grenadines:
+  - '1784'
+Sint Maarten (Dutch part):
+  - '1721'
+Trinidad and Tobago:
+  - '1868'
+Turks and Caicos Islands:
+  - '1649'
 United States of America:
   - '1201'
   - '1202'
@@ -328,67 +412,5 @@ United States of America:
   - '1984'
   - '1985'
   - '1989'
-Canada:
-  - '1204'
-  - '1226'
-  - '1236'
-  - '1249'
-  - '1250'
-  - '1289'
-  - '1306'
-  - '1343'
-  - '1365'
-  - '1403'
-  - '1416'
-  - '1418'
-  - '1431'
-  - '1437'
-  - '1438'
-  - '1450'
-  - '1506'
-  - '1514'
-  - '1519'
-  - '1579'
-  - '1581'
-  - '1587'
-  - '1604'
-  - '1613'
-  - '1639'
-  - '1647'
-  - '1705'
-  - '1709'
-  - '1778'
-  - '1780'
-  - '1807'
-  - '1819'
-  - '1867'
-  - '1873'
-  - '1902'
-  - '1905'
-American Samoa: '1684'
-Anguilla: '1264'
-Antigua and Barbuda: '1268'
-Bahamas: '1242'
-Barbados: '1246'
-Bermuda: '1441'
-British Virgin Islands: '1284'
-Cayman Islands: '1345'
-Dominica: '1767'
-Dominican Republic:
-  - '1809'
-  - '1829'
-  - '1849'
-Grenada: '1473'
-Guam: '1671'
-Jamaica: '1876'
-Montserrat: '1664'
-Northern Mariana Islands: '1670'
-Puerto Rico:
-  - '1787'
-  - '1939'
-Saint Kitts and Nevis: '1869'
-Saint Lucia: '1758'
-Saint Vincent and the Grenadines: '1784'
-Trinidad and Tobago: '1868'
-Turks and Caicos Islands: '1649'
-United States Virgin Islands: '1340'
+United States Virgin Islands:
+  - '1340'

data/lib/itu_codes.rb

@@ -1,24 +1,52 @@
-# to-do: deal with headache codes:
-# 1 --> Non-US need to be separated by area code
-# 7 --> Kazakhstan!
-
 require 'itu_codes/constants'
 require 'itu_codes/helpers'
 
-# TODO: add ability to search for common names (i.e. 'USA' or 'United States of America' for 'United States')
-
 module ItuCodes
   class << self
-    def find_by_itu_code(code)
-      returner = lookup(code)
 
-      if returner.size <= 1
-        returner.first
+    # number is a full or partial number
+    def country_for(number)
+      parsed = parse_code(number)
+
+      return if parsed.nil?
+      
+      matching_countries = if north_american?(parsed)
+        north_american_codes.select do |k, v|
+          v.any? do |na_area_code|
+            na_area_code =~ /^#{number[0,4]}/
+          end
+        end.keys
+      elsif eurasian?(parsed)
+        temp = []
+        temp << "Kazakhstan (Republic of)" if kazakh?(number[0,2])
+        temp << "Russian Federation" if russian?(number[0,2])
+        temp
       else
-        returner
+        country_codes[parsed]
+      end
+
+      if matching_countries.is_a?(Array) && matching_countries.length === 1
+        matching_countries.first
+      else
+        matching_countries
+      end
+    end
+
+    # Must pass a valid ITU code
+    def find_by_itu_code(code)
+      if valid_code?(code)
+        returner = country_for(code)
+
+        if returner.size <= 1
+          returner.first
+        else
+          returner
+        end
       end
     end
 
+    # Passed name must match exact name specified in ITU spec
+    # see: lib/data/assigned_country_codes.yml
     def find_by_name(name)
       matching = country_codes.select do |k, v|
         [*v].include? name
@@ -33,16 +61,17 @@ module ItuCodes
       end
     end
 
-    # lookup by ISO 3166 country code
-    # e.g. iso2itu('US')
+    # lookup by ISO 3166 alpha-2 country code
+    # e.g. find_by_iso_code('US')
     # see : http://www.iso.org/iso/country_codes.htm
     def iso2itu(iso_code)
       country_name = Helpers.country_name_lookup(iso_code)
       find_by_name(country_name)
     end
 
-    def itu2iso(itu)
-      name = find_by_itu_code(itu)
+    # number is a full or partial number
+    def itu2iso(number)
+      name = country_for(number)
 
       if name.is_a?(String)
         Helpers.country_code_lookup(name)
@@ -60,10 +89,6 @@ module ItuCodes
       country_codes.has_key?(some_code)
     end
 
-    def north_american?(some_code)
-      some_code[0,1] == '1'
-    end
-
     # parse a destination code (probably with area code) to find the ITU code
     #   ex:  parse_code(1818) =>  1
     def parse_code(some_number)
@@ -78,33 +103,62 @@ module ItuCodes
     #   ex:  parse_number(18184443322) => 8184443322
     def parse_number(some_number)
       country_code = parse_code(some_number)
-      some_number.gsub(/^#{country_code}/) unless country_code.nil?
+      some_number[country_code.length,some_number.length] unless country_code.nil?
     end
 
     def compatriots?(some, other)
-      both_valid = ! ( parse_code(some).nil? or parse_code(other).nil? )
+      both_valid = ! ( parse_code(some).nil? || parse_code(other).nil? )
 
       if north_american?(some) && north_american?(other)
-        both_valid && !(lookup(some) & lookup(other)).empty?
+        both_valid && !([*country_for(some)] & [*country_for(other)]).empty?
+      elsif eurasian?(some) && eurasian?(other)
+        both_valid && !([*country_for(some)] & [*country_for(other)]).empty?
       else
         some  = parse_code(some)
         other = parse_code(other)
-        both_valid && lookup(some) == lookup(other)
+        both_valid && some === other
       end
     end
 
+    def north_american?(some_code)
+      some_code[0,1] == '1'
+    end
+
+    def eurasian?(some_code)
+      some_code[0,1] == '7'
+    end
+
     def american?(some_code)
-      # for non-US North American codes, parse_code will return a 4 digit code
-      # for US, '1' will be returned
-      countries = lookup(some_code[0,4]) || []
-      countries.include?('United States of America')
+      [* country_for(some_code) ].include?('United States of America')
     end
 
     def canadian?(some_code)
-      countries = lookup(some_code[0,4])
-      north_american?(some_code) && (countries.include?('Canada'))
+      [* country_for(some_code) ].include?('Canada')
     end
 
+    # Russian codes start with 7
+    # and are not codes defined for Kazakhstan
+    def russian?(some_code)
+      if some_code.length < 2
+        eurasian?(some_code)
+      else
+        eurasian?(some_code) && !kazakh?(some_code)
+      end
+    end
+
+    # Kazakhstan country code will start with either 76 or 77
+    # see: http://www.itu.int/oth/T020200006F/en
+    #      http://www.itu.int/dms_pub/itu-t/oth/02/02/T020200006F0001PDFE.pdf
+    # NOTE: apparently, some numbers are still jointly used by Kazakhstan and Russia
+    #       7000-0009, 7100-7199, 7200-7299, 7800-7809, 7881-7899
+    #       ItuCodes reports these as Russian codes for the time being
+    def kazakh?(some_code)
+      if some_code.length < 2
+        eurasian?(some_code)
+      else
+        %(77 76).include?(some_code[0,2])
+      end
+    end
 
     private
 
@@ -112,19 +166,12 @@ module ItuCodes
       Constants::NORTH_AMERICAN_AREA_CODES
     end
 
-    def country_codes
-      Constants::ASSIGNED_COUNTRY_CODES
+    def eurasian_codes
+      Constants::NORTH_AMERICAN_AREA_CODES
     end
 
-    def lookup(code)
-      cleaned = clean(code)
-      matching_countries = country_codes[cleaned] || []
-
-      matching_north_americans = north_american_codes.select do |k, v|
-        [*v].include?(code)
-      end || {}
-
-      [*matching_countries] + matching_north_americans.keys.compact
+    def country_codes
+      Constants::ASSIGNED_COUNTRY_CODES
     end
 
     # converts input to string, then strips any non-numeric characters

data/lib/itu_codes/constants.rb

@@ -2,7 +2,8 @@ require 'yaml'
 
 module ItuCodes
   module Constants
-    ASSIGNED_COUNTRY_CODES    = YAML.load_file(File.expand_path(File.dirname(__FILE__)) + '/../data/assigned_country_codes.yml')
-    NORTH_AMERICAN_AREA_CODES = YAML.load_file(File.expand_path(File.dirname(__FILE__)) + '/../data/north_american_area_codes.yml')
+    base_path = File.expand_path(File.dirname(__FILE__))
+    ASSIGNED_COUNTRY_CODES    = YAML.load_file base_path + '/../data/assigned_country_codes.yml'
+    NORTH_AMERICAN_AREA_CODES = YAML.load_file base_path + '/../data/north_american_area_codes.yml'
   end
 end

data/lib/itu_codes/version.rb

@@ -1,3 +1,3 @@
 module ItuCodes
-  VERSION = "0.4.3"
+  VERSION = "0.4.7"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: itu_codes
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.7
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-17 00:00:00.000000000 Z
+date: 2013-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake