i18n_phone_numbers 0.0.1

data/lib/i18n_phone_numbers/util.rb

@@ -0,0 +1,1237 @@
+module I18nPhoneNumbers
+  
+  module Util
+    
+    # TODO : wait for ruby 1.9 to use unicode
+    #
+    # PLUS_CHARS_ = '+\uFF0B'
+    # VALID_DIGITS_ = '0-9\uFF10-\uFF19\u0660-\u0669\u06F0-\u06F9'
+    # VALID_PUNCTUATION = '-x\u2010-\u2015\u2212\u30FC\uFF0D-\uFF0F \u00A0\u200B\u2060\u3000()' +
+    #                     '\uFF08\uFF09\uFF3B\uFF3D.\\[\\]/~\u2053\u223C\uFF5E'
+    
+    # TODO ? : support alpha in numbers ?
+    # VALID_ALPHA_ = 'A-Za-z'
+    
+    # TODO ? : support extensions ?
+    # KNOWN_EXTN_PATTERNS_ = ...
+    
+    PLUS_SIGN = '+'
+    STAR_SIGN = '*'
+    PLUS_CHARS_ = '+'
+    PLUS_CHARS_PATTERN = Regexp.compile('[' + PLUS_CHARS_ + ']+')
+    LEADING_PLUS_CHARS_PATTERN_ = Regexp.compile('\A[' + PLUS_CHARS_ + ']+')
+    VALID_DIGITS_ = '0-9'
+    VALID_ALPHA_ = '' # we don't support it yet
+    VALID_PUNCTUATION = '-x ().\\/\\[\\]~' # add "\-escapes" for [ and ] (will be further included in a [] group in another regexp)
+    KNOWN_EXTN_PATTERNS_ = '' # we don't support extensions yet
+    VALID_START_CHAR_PATTERN = Regexp.compile('[' + PLUS_CHARS_ + VALID_DIGITS_ + ']')
+    SECOND_NUMBER_START_PATTERN_ = /[\\\/] *x/
+    UNWANTED_END_CHAR_PATTERN_ = Regexp.compile('[^' + VALID_DIGITS_ + VALID_ALPHA_ + '#]+\z')
+    CAPTURING_DIGIT_PATTERN = /([0-9])/
+    # This was originally set to \\1 but there are some countries for which the
+    # first group is not used in the national pattern (e.g. Argentina) so the \\1
+    # group does not match correctly.  Therefore, we use \d, so that the first
+    # group actually used in the pattern will be matched.
+    FIRST_GROUP_PATTERN_ = /(\\\d)/
+    NP_PATTERN_ = /\$NP/
+    FG_PATTERN_ = /\$FG/
+    CC_PATTERN_ = /\$CC/
+    REGION_CODE_FOR_NON_GEO_ENTITY = '001'
+    
+    # Regular expression of viable phone numbers. This is location independent.
+    #    -> plus_sign*(([punctuation]|[star])*[digits]){3,}([punctuation]|[star]|[digits]|[alpha])*
+    VALID_PHONE_NUMBER_ = '[' + PLUS_CHARS_ + ']*(?:[' +
+                          VALID_PUNCTUATION + STAR_SIGN + ']*[' +
+                          VALID_DIGITS_ + ']){3,}[' +
+                          VALID_PUNCTUATION +
+                          STAR_SIGN +
+                          VALID_ALPHA_ +
+                          VALID_DIGITS_ + ']*'
+                          
+    VALID_PHONE_NUMBER_PATTERN_ = Regexp.compile('\A' + VALID_PHONE_NUMBER_ + '(?:' + KNOWN_EXTN_PATTERNS_ + ')?' + '\z', 'i')
+    
+    
+    MAX_LENGTH_COUNTRY_CODE_ = 3
+    UNKNOWN_REGION_ = 'ZZ'
+    # The minimum and maximum length of the national significant number.
+    MIN_LENGTH_FOR_NSN_ = 3
+    # The ITU says the maximum length should be 15, but we have found longer numbers in Germany.
+    MAX_LENGTH_FOR_NSN_ = 16
+    
+    
+    DIGIT_MAPPINGS = {
+      '0' => '0',
+      '1' => '1',
+      '2' => '2',
+      '3' => '3',
+      '4' => '4',
+      '5' => '5',
+      '6' => '6',
+      '7' => '7',
+      '8' => '8',
+      '9' => '9' #,
+      
+      # TODO : wait for ruby 1.9 to use unicode
+      
+      # '\uFF10' => '0', # Fullwidth digit 0
+      # '\uFF11' => '1', # Fullwidth digit 1
+      # '\uFF12' => '2', # Fullwidth digit 2
+      # '\uFF13' => '3', # Fullwidth digit 3
+      # '\uFF14' => '4', # Fullwidth digit 4
+      # '\uFF15' => '5', # Fullwidth digit 5
+      # '\uFF16' => '6', # Fullwidth digit 6
+      # '\uFF17' => '7', # Fullwidth digit 7
+      # '\uFF18' => '8', # Fullwidth digit 8
+      # '\uFF19' => '9', # Fullwidth digit 9
+      # '\u0660' => '0', # Arabic-indic digit 0
+      # '\u0661' => '1', # Arabic-indic digit 1
+      # '\u0662' => '2', # Arabic-indic digit 2
+      # '\u0663' => '3', # Arabic-indic digit 3
+      # '\u0664' => '4', # Arabic-indic digit 4
+      # '\u0665' => '5', # Arabic-indic digit 5
+      # '\u0666' => '6', # Arabic-indic digit 6
+      # '\u0667' => '7', # Arabic-indic digit 7
+      # '\u0668' => '8', # Arabic-indic digit 8
+      # '\u0669' => '9', # Arabic-indic digit 9
+      # '\u06F0' => '0', # Eastern-Arabic digit 0
+      # '\u06F1' => '1', # Eastern-Arabic digit 1
+      # '\u06F2' => '2', # Eastern-Arabic digit 2
+      # '\u06F3' => '3', # Eastern-Arabic digit 3
+      # '\u06F4' => '4', # Eastern-Arabic digit 4
+      # '\u06F5' => '5', # Eastern-Arabic digit 5
+      # '\u06F6' => '6', # Eastern-Arabic digit 6
+      # '\u06F7' => '7', # Eastern-Arabic digit 7
+      # '\u06F8' => '8', # Eastern-Arabic digit 8
+      # '\u06F9' => '9'  # Eastern-Arabic digit 9
+    }
+    
+    class << self
+      
+      def parse(numberToParse, alpha2)
+        
+        return self.parseHelper_(numberToParse, alpha2.upcase, false, true)
+        
+      end
+      
+      def parseAndKeepRawInput(numberToParse, alpha2)
+        
+        if !isValidRegionCode_(alpha2)
+          if (numberToParse.length > 0 && numberToParse[0..0] != PLUS_SIGN)
+            raise "INVALID_COUNTRY_CODE"
+          end
+        end
+        
+        return self.parseHelper_(numberToParse, alpha2.upcase, true, true)
+        
+      end
+      
+      
+      def parseHelper_(numberToParse, defaultRegion, keepRawInput, checkRegion)
+        
+        if numberToParse.blank?
+          raise "NOT_A_NUMBER"
+        end
+        
+        nationalNumber = extractPossibleNumber(numberToParse)
+        
+        if !isViablePhoneNumber(nationalNumber)
+          raise "NOT_A_NUMBER"
+        end
+        
+        if checkRegion && !checkRegionForParsing_(nationalNumber, defaultRegion)
+          raise "INVALID_COUNTRY_CODE"
+        end
+        
+        # build PhoneNumber instance
+        phoneNumber = I18nPhoneNumbers::PhoneNumber.new
+        
+        if keepRawInput
+          phoneNumber.raw_input = numberToParse
+        end
+        
+        # Attempt to parse extension first, since it doesn't require
+        # country-specific data and we want to have the non-normalised number here.
+        #
+        # phoneNumber.extension = self.maybeStripExtension(nationalNumber)
+        
+        
+        regionMetadata = I18nPhoneNumbers::Metadata.countryToMetadata[defaultRegion]
+        
+        # Check to see if the number is given in international format so we know
+        # whether this number is from the default country or not.
+        normalizedNationalNumber = ''
+        
+        countryCode = maybeExtractCountryCode(nationalNumber, regionMetadata, normalizedNationalNumber, keepRawInput, phoneNumber)
+        
+        
+        if countryCode != 0
+          
+          phoneNumberRegion = getRegionCodeForCountryCode(countryCode)
+          
+          if phoneNumberRegion != defaultRegion
+            regionMetadata = getMetadataForRegion(phoneNumberRegion)
+          end
+          
+        else
+          # If no extracted country code, use the region supplied instead. The
+          # national number is just the normalized version of the number we were
+          # given to parse
+          normalizeSB_(nationalNumber)
+          
+          normalizedNationalNumber.replace(nationalNumber.dup)
+          
+          if !defaultRegion.nil?
+            countryCode = regionMetadata.country_code
+            phoneNumber.country_code = countryCode
+          elsif keepRawInput
+            phoneNumber.country_code_source = nil
+          end
+          
+        end
+        
+        if normalizedNationalNumber.length < MIN_LENGTH_FOR_NSN_
+          raise "TOO_SHORT_NSN"
+        end
+          
+        if !regionMetadata.nil?
+          
+          carrierCode = ''
+          
+          maybeStripNationalPrefixAndCarrierCode(normalizedNationalNumber, regionMetadata, carrierCode)
+          
+          if keepRawInput
+            phoneNumber.preferred_domestic_carrier_code = carrierCode
+          end
+          
+        end
+        
+        normalizedNationalNumberStr = normalizedNationalNumber.dup
+        
+        lengthOfNationalNumber = normalizedNationalNumberStr.length
+        
+        
+        raise "TOO_SHORT_NSN" if lengthOfNationalNumber < MIN_LENGTH_FOR_NSN_
+        
+        raise "TOO_LONG" if lengthOfNationalNumber > MAX_LENGTH_FOR_NSN_
+        
+        if normalizedNationalNumberStr[0..0] == '0' && regionMetadata.leading_zero_possible
+          phoneNumber.italian_leading_zero = true
+        end
+        
+        phoneNumber.national_number = normalizedNationalNumberStr.to_i # to_i, really ?
+        
+        return phoneNumber
+        
+      end
+      
+      
+      
+      # Checks to see that the region code used is valid, or if it is not valid, that the number to
+      # parse starts with a + symbol so that we can attempt to infer the region from the number.
+      # Returns false if it cannot use the region provided and the region cannot be inferred.
+      def checkRegionForParsing_(numberToParse, defaultRegion)
+        
+        return isValidRegionCode_(defaultRegion) ||
+               (!numberToParse.nil? && numberToParse.length > 0 && numberToParse.match(LEADING_PLUS_CHARS_PATTERN_))
+        
+      end
+      
+      
+      # Tries to extract a country code from a number. This method will return zero
+      # if no country code is considered to be present. Country codes are extracted
+      # in the following ways:
+      #  - by stripping the international dialing prefix of the country the person is
+      # dialing from, if this is present in the number, and looking at the next
+      # digits
+      #  - by stripping the '+' sign if present and then looking at the next digits
+      #  - by comparing the start of the number and the country code of the default
+      # region. If the number is not considered possible for the numbering plan of
+      # the default region initially, but starts with the country code of this
+      # region, validation will be reattempted after stripping this country code. If
+      # this number is considered a possible number, then the first digits will be
+      # considered the country code and removed as such.
+      #
+      # It will throw a i18n.phonenumbers.Error if the number starts with a '+' but
+      # the country code supplied after this does not match that of any known
+      # country.
+      #
+      # @param {string} number non-normalized telephone number that we wish to
+      #     extract a country code from - may begin with '+'.
+      # @param {i18n.phonenumbers.PhoneMetadata} defaultRegionMetadata metadata
+      #     about the region this number may be from.
+      # @param {!goog.string.StringBuffer} nationalNumber a string buffer to store
+      #     the national significant number in, in the case that a country code was
+      #     extracted. The number is appended to any existing contents. If no country
+      #     code was extracted, this will be left unchanged.
+      # @param {boolean} keepRawInput true if the country_code_source and
+      #     preferred_carrier_code fields of phoneNumber should be populated.
+      #     of phoneNumber should be populated.
+      # @param {i18n.phonenumbers.PhoneNumber} phoneNumber the PhoneNumber object
+      #     that needs to be populated with country code and country code source.
+      #     Note the country code is always populated, whereas country code source is
+      #     only populated when keepCountryCodeSource is true.
+      # @return {number} the country code extracted or 0 if none could be extracted.
+      # @throws {i18n.phonenumbers.Error}
+      def maybeExtractCountryCode(number, defaultRegionMetadata, nationalNumber, keepRawInput, phoneNumber)
+      
+        if (number.length == 0)
+          return 0
+        end
+        
+        fullNumber = number.dup
+        
+        possibleCountryIddPrefix = nil
+        
+        if !defaultRegionMetadata.nil?
+          possibleCountryIddPrefix = defaultRegionMetadata.international_prefix
+        end
+        
+        if possibleCountryIddPrefix.nil?
+          possibleCountryIddPrefix = 'NonMatch' # put something that will NEVER match
+        end
+        
+        countryCodeSource = maybeStripInternationalPrefixAndNormalize(fullNumber, possibleCountryIddPrefix)
+        
+        if keepRawInput
+          phoneNumber.country_code_source = countryCodeSource
+        end
+        
+        
+        if countryCodeSource != I18nPhoneNumbers::CountryCodeSource::FROM_DEFAULT_COUNTRY
+          
+          if fullNumber.length < MIN_LENGTH_FOR_NSN_
+            raise "TOO_SHORT_AFTER_IDD"
+          end
+          
+          potentialCountryCode = extractCountryCode(fullNumber, nationalNumber)
+          
+          if potentialCountryCode != 0
+            phoneNumber.country_code = potentialCountryCode
+            return potentialCountryCode
+          end
+          
+          # If this fails, they must be using a strange country code that we don't
+          # recognize, or that doesn't exist.
+          raise "INVALID_COUNTRY_CODE"
+        
+        elsif !defaultRegionMetadata.nil?
+          
+          # Check to see if the number starts with the country calling code for the
+          # default region. If so, we remove the country calling code, and do some
+          # checks on the validity of the number before and after.
+          defaultCountryCode = defaultRegionMetadata.country_code
+          
+          defaultCountryCodeString = defaultCountryCode.to_s
+          
+          normalizedNumber = fullNumber.dup
+          
+          if normalizedNumber.match(Regexp.new('\A' + defaultCountryCodeString))
+            
+            potentialNationalNumber = normalizedNumber[(defaultCountryCodeString.length)..-1]
+            
+            generalDesc = defaultRegionMetadata.general_desc
+            
+            validNumberPattern = Regexp.new(generalDesc.national_number_pattern)
+            
+            maybeStripNationalPrefixAndCarrierCode(potentialNationalNumber, defaultRegionMetadata, nil)
+            
+            potentialNationalNumberStr = potentialNationalNumber.dup
+            
+            possibleNumberPattern = generalDesc.possible_number_pattern
+            
+            # If the number was not valid before but is valid now, or if it was too
+            # long before, we consider the number with the country calling code
+            # stripped to be a better result and keep that instead.
+            if (!matchesEntirely_(validNumberPattern, fullNumber) && matchesEntirely_(validNumberPattern, potentialNationalNumberStr)) ||
+               (testNumberLengthAgainstPattern_(possibleNumberPattern, fullNumber) == "TOO_LONG")
+              
+              nationalNumber = nationalNumber.replace(potentialNationalNumberStr)
+              
+              if keepRawInput
+                phoneNumber.country_code_source = I18nPhoneNumbers::CountryCodeSource::FROM_NUMBER_WITHOUT_PLUS_SIGN
+              end
+              
+              phoneNumber.country_code = defaultCountryCode
+              
+              return defaultCountryCode
+              
+            end
+          end
+          
+        end
+        
+        # No country code present.
+        phoneNumber.country_code = 0
+        return 0
+        
+      end
+      
+      
+      def testNumberLengthAgainstPattern_(numberPattern, number)
+        
+        if matchesEntirely_(numberPattern, number)
+          return "IS_POSSIBLE"
+        end
+        
+        return number.match('\A' + numberPattern) ? "TOO_LONG" : "TOO_SHORT"
+        
+      end
+      
+      
+      # Strips any international prefix (such as +, 00, 011) present in the number
+      # provided, normalizes the resulting number, and indicates if an international
+      # prefix was present.
+      #
+      # @param {!goog.string.StringBuffer} number the non-normalized telephone number
+      #     that we wish to strip any international dialing prefix from.
+      # @param {string} possibleIddPrefix the international direct dialing prefix
+      #     from the country we think this number may be dialed in.
+      # @return {i18n.phonenumbers.PhoneNumber.CountryCodeSource} the corresponding
+      #     CountryCodeSource if an international dialing prefix could be removed
+      #     from the number, otherwise CountryCodeSource::FROM_DEFAULT_COUNTRY if
+      #     the number did not seem to be in international format.
+      def maybeStripInternationalPrefixAndNormalize(number, possibleIddPrefix)
+        
+        numberStr = number.dup
+        
+        if numberStr.length == 0
+          return I18nPhoneNumbers::CountryCodeSource::FROM_DEFAULT_COUNTRY
+        end
+        
+        # Check to see if the number begins with one or more plus signs.
+        if numberStr.match(LEADING_PLUS_CHARS_PATTERN_)
+          
+          numberStr = numberStr.sub(LEADING_PLUS_CHARS_PATTERN_, '') # strip leading +
+          
+          # Can now normalize the rest of the number since we've consumed the "+"
+          # sign at the start.
+          number.replace(normalize(numberStr))
+          return I18nPhoneNumbers::CountryCodeSource::FROM_NUMBER_WITH_PLUS_SIGN
+          
+        end
+        
+        # Attempt to parse the first digits as an international prefix.
+        iddPattern = Regexp.new(possibleIddPrefix)
+        
+        normalizeSB_(number)
+        
+        return parsePrefixAsIdd_(iddPattern, number) ?
+            I18nPhoneNumbers::CountryCodeSource::FROM_NUMBER_WITH_IDD :
+            I18nPhoneNumbers::CountryCodeSource::FROM_DEFAULT_COUNTRY
+        
+      end
+      
+      
+      # Strips the IDD from the start of the number if present. Helper function used
+      # by maybeStripInternationalPrefixAndNormalize.
+      #
+      # @param {RegExp} iddPattern the regular expression for the international
+      #     prefix.
+      # @param {!goog.string.StringBuffer} number the phone number that we wish to
+      #     strip any international dialing prefix from.
+      # @return {boolean} true if an international prefix was present.
+      # @private
+      def parsePrefixAsIdd_(iddPattern, number)
+        
+        if number.index(iddPattern) == 0
+          
+          matchEnd = number.match(iddPattern)[0].length
+          
+          matchedGroups = number[matchEnd..-1].match(CAPTURING_DIGIT_PATTERN)
+          
+          if matchedGroups && matchedGroups[1] == '0'
+            return false
+          end
+          
+          number.replace(number[matchEnd..-1])
+          return true
+        end
+        
+        return false
+        
+      end
+      
+      
+      # Normalizes a string of characters representing a phone number. This is a
+      # wrapper for normalize(String number) but does in-place normalization of the
+      # StringBuffer provided.
+      #
+      # @param {!goog.string.StringBuffer} number a StringBuffer of characters
+      #     representing a phone number that will be normalized in place.
+      # @private
+      def normalizeSB_(number)
+        
+        normalizedNumber = normalize(number)
+        number.replace(normalizedNumber)
+        
+      end
+      
+      
+      
+      # Normalizes a string of characters representing a phone number. This performs
+      # the following conversions:
+      #  - Wide-ascii digits are converted to normal ASCII (European) digits.
+      #  - Punctuation is stripped.
+      #  - Arabic-Indic numerals are converted to European numerals.
+      #
+      # @param {string} number a string of characters representing a phone number.
+      # @return {string} the normalized string version of the phone number.
+      def normalize(number)
+        return normalizeHelper_(number, DIGIT_MAPPINGS, true)
+      end
+      
+      
+      # Normalizes a string of characters representing a phone number by replacing
+      # all characters found in the accompanying map with the values therein, and
+      # stripping all other characters if removeNonMatches is true.
+      #
+      # @param {string} number a string of characters representing a phone number.
+      # @param {!Object} normalizationReplacements a mapping of characters to what
+      #     they should be replaced by in the normalized version of the phone number.
+      # @param {boolean} removeNonMatches indicates whether characters that are not
+      #     able to be replaced should be stripped from the number. If this is false,
+      #     they will be left unchanged in the number.
+      # @return {string} the normalized string version of the phone number.
+      # @private
+      def normalizeHelper_(number, normalizationReplacements = DIGIT_MAPPINGS, removeNonMatches = true)
+        
+        normalizedNumber = ''
+        
+        number.each_char do |character|
+          
+          newDigit = normalizationReplacements[character.upcase()]
+          
+          if !newDigit.nil?
+            normalizedNumber << newDigit
+          elsif !removeNonMatches
+            normalizedNumber << character
+          end
+          # If neither of the above are true, we remove this character.
+        end
+        
+        return normalizedNumber
+      end
+      
+      
+      # Check whether the entire input sequence can be matched against the regular
+      # expression.
+      #
+      # @param {RegExp|string} regex the regular expression to match against.
+      # @param {string} str the string to test.
+      # @return {boolean} true if str can be matched entirely against regex.
+      # @private
+      def matchesEntirely_(regex, str)
+        
+        matchedGroups = str.match(regex) # regex is a string, match will correctly convert it into a regex first
+        
+        return !!(matchedGroups && matchedGroups[0].length == str.length)
+        
+      end
+      
+      
+      def extractCountryCode(fullNumber, nationalNumber)
+        
+        [fullNumber.length, MAX_LENGTH_COUNTRY_CODE_].min.times do |i|
+          
+          potentialCountryCode = fullNumber[0..i].to_i
+          
+          if I18nPhoneNumbers::Metadata.countryCodeToRegionCodeMap.has_key?(potentialCountryCode)
+            nationalNumber.replace(fullNumber[(i+1)..-1])
+            return potentialCountryCode
+          end
+          
+        end
+        
+        return 0
+        
+      end
+      
+      
+      # Strips any national prefix (such as 0, 1) present in the number provided.
+      #
+      # @param {!goog.string.StringBuffer} number the normalized telephone number
+      #     that we wish to strip any national dialing prefix from.
+      # @param {i18n.phonenumbers.PhoneMetadata} metadata the metadata for the
+      #     country that we think this number is from.
+      # @return {string} the carrier code extracted if it is present, otherwise
+      #     return an empty string.
+      def maybeStripNationalPrefixAndCarrierCode(number, metadata, carrierCode)
+        
+        numberStr = number.dup
+        
+        possibleNationalPrefix = metadata.national_prefix_for_parsing
+        
+        if numberStr == '' || possibleNationalPrefix.blank?
+          # Early return for numbers of zero length.
+          return false
+        end
+        
+        # Attempt to parse the first digits as a national prefix.
+        prefixPattern = Regexp.new('\A(?:' + possibleNationalPrefix + ')')
+        
+        prefixMatcher = numberStr.match(prefixPattern) # nil or MatchData instance (same behavior as Array)
+        
+        if (prefixMatcher)
+          
+          nationalNumberRule = Regexp.new(metadata.general_desc.national_number_pattern)
+          
+          # prefixMatcher[numOfGroups] == nil implies nothing was captured by the
+          # capturing groups in possibleNationalPrefix; therefore, no transformation
+          # is necessary, and we just remove the national prefix.
+          numOfGroups = prefixMatcher.length - 1
+          
+          transformRule = metadata.national_prefix_transform_rule
+          
+          noTransform = transformRule.blank? || prefixMatcher[numOfGroups].nil? || prefixMatcher[numOfGroups].length == 0
+          
+          # Juste remove the national prefix
+          if noTransform
+            transformedNumber = numberStr[(prefixMatcher[0].length)..-1]
+            
+          # Apply the transformRule
+          else
+            transformedNumber = numberStr.sub(prefixPattern, transformRule)
+          end
+          
+          # If the original number was viable, and the resultant number is not,
+          # we return.
+          if matchesEntirely_(nationalNumberRule, numberStr) && !matchesEntirely_(nationalNumberRule, transformedNumber)
+            return false
+          end
+          
+          if (noTransform && numOfGroups > 0 && !prefixMatcher[1].nil?) ||
+             (!noTransform && numOfGroups > 1)
+            
+            if !carrierCode.nil?
+              carrierCode += prefixMatcher[1]
+            end
+          end
+          
+          number.replace(transformedNumber)
+          return true
+        end
+        
+        return false
+        
+      end
+      
+      
+      # Returns the region code that matches the specific country code. In the case
+      # of no region code being found, ZZ will be returned. In the case of multiple
+      # regions, the one designated in the metadata as the "main" country for this
+      # calling code will be returned.
+      #
+      # @param {number} countryCode the country calling code.
+      # @return {string}
+      def getRegionCodeForCountryCode(countryCode)
+        
+        regionCodes = I18nPhoneNumbers::Metadata::countryCodeToRegionCodeMap[countryCode]
+        
+        return regionCodes.nil? ? UNKNOWN_REGION_ : regionCodes[0]
+        
+      end
+      
+      
+      # @param {?string} regionCode
+      # @return {i18n.phonenumbers.PhoneMetadata}
+      def getMetadataForRegion(regionCode)
+        
+        return regionCode.nil? ? nil : I18nPhoneNumbers::Metadata::countryToMetadata[regionCode.upcase]
+        
+      end
+      
+      
+      # Gets the type of a phone number.
+      #
+      # @param {i18n.phonenumbers.PhoneNumber} number the phone number that we want
+      #     to know the type.
+      # @return {i18n.phonenumbers.PhoneNumberType} the type of the phone number.
+      def getNumberType(number)
+        
+        regionCode = getRegionCodeForNumber(number)
+        
+        if !isValidRegionCode_(regionCode) && REGION_CODE_FOR_NON_GEO_ENTITY != regionCode
+          return I18nPhoneNumbers::PhoneNumberType::UNKNOWN
+        end
+        
+        nationalSignificantNumber = getNationalSignificantNumber(number)
+        
+        return getNumberTypeHelper_(nationalSignificantNumber, getMetadataForRegion(regionCode))
+        
+      end
+      
+      
+      # Gets the type of a phone number.
+      #
+      # @param {i18n.phonenumbers.PhoneNumber} number the phone number that we want
+      #     to know the type.
+      # @return {boolean}
+      def isMobile?(number)
+        return [I18nPhoneNumbers::PhoneNumberType::MOBILE,
+                I18nPhoneNumbers::PhoneNumberType::FIXED_LINE_OR_MOBILE].include?(getNumberType(number))
+      end
+      
+      
+      # Returns the country/region where a phone number is from. This could be used
+      # for geo-coding in the country/region level.
+      #
+      # @param {i18n.phonenumbers.PhoneNumber} number the phone number whose origin
+      #     we want to know.
+      # @return {?string} the country/region where the phone number is from, or null
+      #     if no country matches this calling code.
+      def getRegionCodeForNumber(number)
+        
+        return nil if number.nil?
+        
+        countryCode = number.country_code || 0
+        
+        regions = I18nPhoneNumbers::Metadata::countryCodeToRegionCodeMap[countryCode]
+        
+        return nil if regions.nil?
+        
+        if regions.length == 1
+          return regions[0]
+        else
+          return getRegionCodeForNumberFromRegionList_(number, regions)
+        end
+        
+      end
+      
+      
+      # @param {i18n.phonenumbers.PhoneNumber} number
+      # @param {Array.<string>} regionCodes
+      # @return {?string}
+      # @private
+      def getRegionCodeForNumberFromRegionList_(number, regionCodes)
+        
+        nationalNumber = number.national_number.to_s
+        
+        regionCodes.each { |regionCode|
+          
+          # If leadingDigits is present, use this. Otherwise, do full validation.
+          metadata = getMetadataForRegion(regionCode)
+          
+          if !metadata.leading_digits.blank?
+            
+            return regionCode if !!nationalNumber.match(Regexp.compile('\A' + metadata.leading_digits)) # starts with leading_digits pattern
+            
+          elsif getNumberTypeHelper_(nationalNumber, metadata) != I18nPhoneNumbers::PhoneNumberType::UNKNOWN
+            
+            return regionCode
+            
+          end
+        
+        }
+        
+        return nil
+        
+      end
+      
+      
+      # @param {string} nationalNumber
+      # @param {i18n.phonenumbers.PhoneMetadata} metadata
+      # @return {i18n.phonenumbers.PhoneNumberType}
+      # @private
+      def getNumberTypeHelper_(nationalNumber, metadata)
+        
+        generalNumberDesc = metadata.general_desc
+        
+        if generalNumberDesc.national_number_pattern.nil? || !isNumberMatchingDesc_(nationalNumber, generalNumberDesc)
+          return I18nPhoneNumbers::PhoneNumberType::UNKNOWN
+        end
+        
+        # TODO : init and use types different from MOBILE and FIXED
+        
+        # if isNumberMatchingDesc_(nationalNumber, metadata.premium_rate)
+        #   return I18nPhoneNumbers::PhoneNumberType::PREMIUM_RATE
+        # end
+        # 
+        # if isNumberMatchingDesc_(nationalNumber, metadata.toll_free)
+        #   return I18nPhoneNumbers::PhoneNumberType::TOLL_FREE
+        # end
+        # 
+        # if isNumberMatchingDesc_(nationalNumber, metadata.shared_cost)
+        #   return I18nPhoneNumbers::PhoneNumberType::SHARED_COST
+        # end
+        # 
+        # if isNumberMatchingDesc_(nationalNumber, metadata.voip)
+        #   return I18nPhoneNumbers::PhoneNumberType::VOIP
+        # end
+        # 
+        # if isNumberMatchingDesc_(nationalNumber, metadata.personal_number)
+        #   return I18nPhoneNumbers::PhoneNumberType::PERSONAL_NUMBER
+        # end
+        # 
+        # if isNumberMatchingDesc_(nationalNumber, metadata.pager)
+        #   return I18nPhoneNumbers::PhoneNumberType::PAGER
+        # end
+        # 
+        # if isNumberMatchingDesc_(nationalNumber, metadata.uan)
+        #   return I18nPhoneNumbers::PhoneNumberType::UAN
+        # end
+        # 
+        # if isNumberMatchingDesc_(nationalNumber, metadata.voicemail)
+        #   return I18nPhoneNumbers::PhoneNumberType::VOICEMAIL
+        # end
+        
+        isFixedLine = isNumberMatchingDesc_(nationalNumber, metadata.fixed_line)
+        
+        if isFixedLine
+          
+          if metadata.same_mobile_and_fixed_line_pattern
+            return I18nPhoneNumbers::PhoneNumberType::FIXED_LINE_OR_MOBILE
+            
+          elsif isNumberMatchingDesc_(nationalNumber, metadata.mobile)
+            return I18nPhoneNumbers::PhoneNumberType::FIXED_LINE_OR_MOBILE
+          end
+          
+          return I18nPhoneNumbers::PhoneNumberType::FIXED_LINE
+        
+        end
+        
+        # Otherwise, test to see if the number is mobile. Only do this if certain
+        # that the patterns for mobile and fixed line aren't the same.
+        if !metadata.same_mobile_and_fixed_line_pattern && isNumberMatchingDesc_(nationalNumber, metadata.mobile)
+          return I18nPhoneNumbers::PhoneNumberType::MOBILE
+        end
+        
+        return I18nPhoneNumbers::PhoneNumberType::UNKNOWN
+      end
+      
+      
+      # @param {string} nationalNumber
+      # @param {i18n.phonenumbers.PhoneNumberDesc} numberDesc
+      # @return {boolean}
+      # @private
+      def isNumberMatchingDesc_(nationalNumber, numberDesc)
+        
+        return matchesEntirely_(numberDesc.possible_number_pattern, nationalNumber) &&
+               matchesEntirely_(numberDesc.national_number_pattern, nationalNumber)
+               
+      end
+      
+      
+      # Helper function to check region code is not unknown or null.
+      #
+      # @param {?string} regionCode the ISO 3166-1 two-letter country code that
+      #     denotes the country/region that we want to get the country code for.
+      # @return {boolean} true if region code is valid.
+      # @private
+      def isValidRegionCode_(regionCode)
+        
+        return !regionCode.nil? &&
+                regionCode != REGION_CODE_FOR_NON_GEO_ENTITY &&
+                I18nPhoneNumbers::Metadata::countryToMetadata.has_key?(regionCode.upcase)
+        
+      end
+      
+      
+      # Gets the national significant number of the a phone number. Note a national
+      # significant number doesn't contain a national prefix or any formatting.
+      #
+      # @param {i18n.phonenumbers.PhoneNumber} number the PhoneNumber object for
+      #     which the national significant number is needed.
+      # @return {string} the national significant number of the PhoneNumber object
+      #     passed in.
+      def getNationalSignificantNumber(number)
+        
+        # If a leading zero has been set, we prefix this now. Note this is not a
+        # national prefix.
+        nationalNumber = number.national_number.to_s
+        
+        if number.italian_leading_zero
+          return '0' + nationalNumber
+        end
+        
+        return nationalNumber
+        
+      end
+      
+      
+      # Attempts to extract a possible number from the string passed in. This
+      # currently strips all leading characters that could not be used to start a
+      # phone number. Characters that can be used to start a phone number are defined
+      # in the VALID_START_CHAR_PATTERN. If none of these characters are found in the
+      # number passed in, an empty string is returned. This function also attempts to
+      # strip off any alternative extensions or endings if two or more are present,
+      # such as in the case of: (530) 583-6985 x302/x2303. The second extension here
+      # makes this actually two phone numbers, (530) 583-6985 x302 and (530) 583-6985
+      # x2303. We remove the second extension so that the first number is parsed
+      # correctly.
+      #
+      # @param {string} number the string that might contain a phone number.
+      # @return {string} the number, stripped of any non-phone-number prefix (such as
+      #     'Tel:') or an empty string if no character used to start phone numbers
+      #     (such as + or any digit) is found in the number.
+      #
+      def extractPossibleNumber(number)
+        
+        start = number.index(VALID_START_CHAR_PATTERN)
+        
+        if !start.nil?
+          
+          possibleNumber = number[start..-1]
+          
+          # Remove trailing non-alpha non-numerical characters.
+          possibleNumber = possibleNumber.gsub(UNWANTED_END_CHAR_PATTERN_, '')
+          
+          # Check for extra numbers at the end.
+          secondNumberStart = possibleNumber.index(SECOND_NUMBER_START_PATTERN_)
+          
+          if !secondNumberStart.nil?
+            possibleNumber = possibleNumber[0..secondNumberStart]
+          end
+          
+        else
+          possibleNumber = ''
+        end
+        
+        return possibleNumber
+        
+      end
+      
+      
+      # Checks to see if the string of characters could possibly be a phone number at
+      # all. At the moment, checks to see that the string begins with at least 3
+      # digits, ignoring any punctuation commonly found in phone numbers. This method
+      # does not require the number to be normalized in advance - but does assume
+      # that leading non-number symbols have been removed, such as by the method
+      # extractPossibleNumber.
+      #
+      # @param {string} number string to be checked for viability as a phone number.
+      # @return {boolean} true if the number could be a phone number of some sort,
+      #     otherwise false.
+      def isViablePhoneNumber(number)
+        
+        return false if (number.length < MIN_LENGTH_FOR_NSN_)
+        
+        return matchesEntirely_(VALID_PHONE_NUMBER_PATTERN_, number)
+        
+      end
+      
+      
+      # Tests whether a phone number matches a valid pattern. Note this doesn't
+      # verify the number is actually in use, which is impossible to tell by just
+      # looking at a number itself.
+      #
+      # @param {i18n.phonenumbers.PhoneNumber} number the phone number that we want
+      #     to validate.
+      # @return {boolean} a boolean that indicates whether the number is of a valid
+      #     pattern.
+      def isValidNumber(number)
+        
+        regionCode = getRegionCodeForNumber(number)
+        
+        return isValidRegionCode_(regionCode) && isValidNumberForRegion(number, regionCode)
+      end
+      
+      
+      # Tests whether a phone number is valid for a certain region. Note this doesn't
+      # verify the number is actually in use, which is impossible to tell by just
+      # looking at a number itself. If the country code is not the same as the
+      # country code for the region, this immediately exits with false. After this,
+      # the specific number pattern rules for the region are examined. This is useful
+      # for determining for example whether a particular number is valid for Canada,
+      # rather than just a valid NANPA number.
+      #
+      # @param {i18n.phonenumbers.PhoneNumber} number the phone number that we want
+      #     to validate.
+      # @param {string} regionCode the ISO 3166-1 two-letter country code that
+      #     denotes the region/country that we want to validate the phone number for.
+      # @return {boolean} a boolean that indicates whether the number is of a valid
+      #     pattern.
+      def isValidNumberForRegion(number, regionCode)
+        
+        return false if (number.country_code || 0) != getCountryCodeForRegion(regionCode)
+        
+        metadata = getMetadataForRegion(regionCode)
+        
+        generalNumDesc = metadata.general_desc
+        
+        nationalSignificantNumber = getNationalSignificantNumber(number)
+        
+        # For countries where we don't have metadata for PhoneNumberDesc, we treat
+        # any number passed in as a valid number if its national significant number
+        # is between the minimum and maximum lengths defined by ITU for a national
+        # significant number.
+        if generalNumDesc.national_number_pattern.blank?
+          
+          numberLength = nationalSignificantNumber.length
+          
+          return numberLength > MIN_LENGTH_FOR_NSN_ && numberLength <= MAX_LENGTH_FOR_NSN_
+        end
+        
+        return getNumberTypeHelper_(nationalSignificantNumber, metadata) != I18nPhoneNumbers::PhoneNumberType::UNKNOWN
+      end
+      
+      
+      # Returns the country calling code for a specific region. For example, this
+      # would be 1 for the United States, and 64 for New Zealand.
+      #
+      # @param {?string} regionCode the ISO 3166-1 two-letter country code that
+      #     denotes the country/region that we want to get the country code for.
+      # @return {number} the country calling code for the country/region denoted by
+      #     regionCode.
+      def getCountryCodeForRegion(regionCode)
+        
+        return 0 if !isValidRegionCode_(regionCode)
+        
+        metadata = getMetadataForRegion(regionCode)
+        return 0 if metadata == nil
+        
+        return metadata.country_code || 0
+      end
+      
+      
+      
+      # Formats a phone number in the specified format using default rules. Note that
+      # this does not promise to produce a phone number that the user can dial from
+      # where they are - although we do format in either 'national' or
+      # 'international' format depending on what the client asks for, we do not
+      # currently support a more abbreviated format, such as for users in the same
+      # "area" who could potentially dial the number without area code. Note that if
+      # the phone number has a country code of 0 or an otherwise invalid country
+      # code, we cannot work out which formatting rules to apply so we return the
+      # national significant number with no formatting applied.
+      #
+      # @param {i18n.phonenumbers.PhoneNumber} number the phone number to be
+      #     formatted.
+      # @param {i18n.phonenumbers.PhoneNumberFormat} numberFormat the format the
+      #     phone number should be formatted into.
+      # @return {string} the formatted phone number.
+      def format(number, numberFormat)
+        
+        countryCallingCode = number.country_code || 0
+        
+        nationalSignificantNumber = getNationalSignificantNumber(number)
+        
+        if (numberFormat == I18nPhoneNumbers::PhoneNumberFormat::E164)
+          
+          # Early exit for E164 case since no formatting of the national number needs
+          # to be applied. Extensions are not formatted.
+          return formatNumberByFormat_(countryCallingCode, I18nPhoneNumbers::PhoneNumberFormat::E164, nationalSignificantNumber, '')
+        
+        end
+        
+        # Note getRegionCodeForCountryCode() is used because formatting information
+        # for countries which share a country code is contained by only one country
+        # for performance reasons. For example, for NANPA countries it will be
+        # contained in the metadata for US.
+        regionCode = getRegionCodeForCountryCode(countryCallingCode)
+        
+        return nationalSignificantNumber if !isValidRegionCode_(regionCode)
+        
+        metadata = getMetadataForRegion(regionCode)
+        
+        formattedExtension = maybeGetFormattedExtension_(number, regionCode)
+        
+        formattedNationalNumber = formatNationalNumber_(nationalSignificantNumber, metadata, numberFormat)
+        
+        return formatNumberByFormat_(countryCallingCode, numberFormat, formattedNationalNumber, formattedExtension)
+        
+      end
+      
+      
+      # A helper function that is used by format and formatByPattern.
+      #
+      # @param {number} countryCode the country calling code.
+      # @param {i18n.phonenumbers.PhoneNumberFormat} numberFormat the format the
+      #     phone number should be formatted into.
+      # @param {string} formattedNationalNumber
+      # @param {string} formattedExtension
+      # @return {string} the formatted phone number.
+      # @private
+      def formatNumberByFormat_(countryCode, numberFormat, formattedNationalNumber, formattedExtension)
+        
+        pnf = I18nPhoneNumbers::PhoneNumberFormat
+        
+        res = case numberFormat
+          when pnf::E164          then PLUS_SIGN + countryCode.to_s + formattedNationalNumber + formattedExtension
+          when pnf::INTERNATIONAL then PLUS_SIGN + countryCode.to_s + ' ' + formattedNationalNumber + formattedExtension
+          # "else" is including pnf::NATIONAL
+          else formattedNationalNumber + formattedExtension
+        end
+        
+        return res
+      end
+      
+      
+      
+      # Gets the formatted extension of a phone number, if the phone number had an
+      # extension specified. If not, it returns an empty string.
+      #
+      # @param {i18n.phonenumbers.PhoneNumber} number the PhoneNumber that might have
+      #     an extension.
+      # @param {string} regionCode the ISO 3166-1 two-letter country code.
+      # @return {string} the formatted extension if any.
+      # @private
+      def maybeGetFormattedExtension_(number, regionCode)
+        
+        # NOT SUPPORTED YET
+        return ''
+        
+        # if number.extension.blank?
+        #   return ''
+        # else
+        #   return formatExtension_(number.getExtensionOrDefault(), regionCode)
+        # end
+        
+      end
+      
+      
+      # Note in some countries, the national number can be written in two completely
+      # different ways depending on whether it forms part of the NATIONAL format or
+      # INTERNATIONAL format. The numberFormat parameter here is used to specify
+      # which format to use for those cases. If a carrierCode is specified, this will
+      # be inserted into the formatted string to replace $CC.
+      #
+      # @param {string} number a string of characters representing a phone number.
+      # @param {i18n.phonenumbers.PhoneMetadata} metadata the metadata for the
+      #     region that we think this number is from.
+      # @param {i18n.phonenumbers.PhoneNumberFormat} numberFormat the format the
+      #     phone number should be formatted into.
+      # @param {string=} opt_carrierCode
+      # @return {string} the formatted phone number.
+      # @private
+      def formatNationalNumber_(number, metadata, numberFormat, opt_carrierCode = nil)
+        
+        intlNumberFormats = metadata.intl_number_formats
+        
+        # When the intlNumberFormats exists, we use that to format national number
+        # for the INTERNATIONAL format instead of using the numberDesc.numberFormats.
+        if (intlNumberFormats.length == 0 || numberFormat == I18nPhoneNumbers::PhoneNumberFormat::NATIONAL)
+          availableFormats = metadata.number_formats
+        else
+          availableFormats = metadata.intl_number_formats
+        end
+        
+        return formatAccordingToFormats_(number, availableFormats, numberFormat, opt_carrierCode)
+      end
+      
+      
+      # Note that carrierCode is optional - if nil or an empty string, no carrier
+      # code replacement will take place.
+      #
+      # @param {string} nationalNumber a string of characters representing a phone
+      #     number.
+      # @param {Array.<i18n.phonenumbers.NumberFormat>} availableFormats the
+      #     available formats the phone number could be formatted into.
+      # @param {i18n.phonenumbers.PhoneNumberFormat} numberFormat the format the
+      #     phone number should be formatted into.
+      # @param {string=} opt_carrierCode
+      # @return {string} the formatted phone number.
+      # @private
+      def formatAccordingToFormats_(nationalNumber, availableFormats, numberFormat, opt_carrierCode = nil)
+        
+        availableFormats.each do |numFormat|
+          
+          ldp = numFormat.leading_digits_patterns
+          
+                           # We always use the last leading_digits_pattern, as it is the most detailed.
+          if ldp.empty? || nationalNumber.index(Regexp.compile(ldp[-1])) == 0
+            
+            patternToMatch = Regexp.new(numFormat.pattern)
+            
+            if matchesEntirely_(patternToMatch, nationalNumber)
+              
+              numberFormatRule = numFormat.format
+              
+              domesticCarrierCodeFormattingRule = numFormat.carrier_code_formatting_rule
+              
+              if (numberFormat == I18nPhoneNumbers::PhoneNumberFormat::NATIONAL &&
+                  !opt_carrierCode.blank? &&
+                  !domesticCarrierCodeFormattingRule.blank?)
+                  
+                # Replace the $CC in the formatting rule with the desired carrier code.
+                carrierCodeFormattingRule = domesticCarrierCodeFormattingRule.sub(CC_PATTERN_, opt_carrierCode)
+                
+                # Now replace the $FG in the formatting rule with the first group
+                # and the carrier code combined in the appropriate way.
+                numberFormatRule = numberFormatRule.sub(FIRST_GROUP_PATTERN_, carrierCodeFormattingRule)
+                
+                return nationalNumber.sub(patternToMatch, numberFormatRule)
+                
+              else
+                # Use the national prefix formatting rule instead.
+                nationalPrefixFormattingRule = numFormat.national_prefix_formatting_rule
+                
+                if (numberFormat == I18nPhoneNumbers::PhoneNumberFormat::NATIONAL &&
+                    !nationalPrefixFormattingRule.blank?)
+                  return nationalNumber.sub(patternToMatch, numberFormatRule.sub(FIRST_GROUP_PATTERN_, nationalPrefixFormattingRule))
+                else
+                  return nationalNumber.sub(patternToMatch, numberFormatRule)
+                end
+              end
+            end
+          end
+        end
+        
+        # If no pattern above is matched, we format the number as a whole.
+        return nationalNumber
+      end
+      
+      
+      
+      # Gets a valid number for the specified country.
+      #
+      # @param {string} regionCode the ISO 3166-1 two-letter country code that
+      #     denotes the country for which an example number is needed.
+      # @return {i18n.phonenumbers.PhoneNumber} a valid fixed-line number for the
+      #     specified country. Returns null when the metadata does not contain such
+      #     information.
+      def getExampleNumber(regionCode)
+        return getExampleNumberForType(regionCode, I18nPhoneNumbers::PhoneNumberType::FIXED_LINE)
+      end
+      
+      
+      # Gets a valid number, if any, for the specified country and number type.
+      #
+      # @param {string} regionCode the ISO 3166-1 two-letter country code that
+      #     denotes the country for which an example number is needed.
+      # @param {i18n.phonenumbers.PhoneNumberType} type the type of number that is
+      #     needed.
+      # @return {i18n.phonenumbers.PhoneNumber} a valid number for the specified
+      #     country and type. Returns null when the metadata does not contain such
+      #     information.
+      def getExampleNumberForType(regionCode, type)
+        
+        desc = getNumberDescByType_(getMetadataForRegion(regionCode), type)
+        
+        begin
+          if !desc.example_number.blank?
+            return parse(desc.example_number, regionCode)
+          end
+        rescue
+        end
+        
+        return nil
+      end
+      
+      
+      #
+      # @param {i18n.phonenumbers.PhoneMetadata} metadata
+      # @param {i18n.phonenumbers.PhoneNumberType} type
+      # @return {i18n.phonenumbers.PhoneNumberDesc}
+      # @private
+      def getNumberDescByType_(metadata, type)
+        
+        case type
+          # when I18nPhoneNumbers::PhoneNumberType::PREMIUM_RATE then metadata.premium_rate
+          # when I18nPhoneNumbers::PhoneNumberType::TOLL_FREE then metadata.toll_free
+          when I18nPhoneNumbers::PhoneNumberType::MOBILE then metadata.mobile
+          when I18nPhoneNumbers::PhoneNumberType::FIXED_LINE, I18nPhoneNumbers::PhoneNumberType::FIXED_LINE_OR_MOBILE then metadata.fixed_line
+          # when I18nPhoneNumbers::PhoneNumberType::SHARED_COST then metadata.shared_cost
+          # when I18nPhoneNumbers::PhoneNumberType::VOIP then metadata.voip
+          # when I18nPhoneNumbers::PhoneNumberType::PERSONAL_NUMBER then metadata.personal_number
+          # when I18nPhoneNumbers::PhoneNumberType::PAGER then metadata.pager
+          # when I18nPhoneNumbers::PhoneNumberType::UAN then metadata.uan
+          else metadata.general_desc
+        end
+        
+      end
+      
+    end # end of class << self
+    
+  end # end of Util module
+  
+end