* Copyright (C) 2009 Google Inc.

*

* Licensed under the Apache License, Version 2.0 (the "License");

* you may not use this file except in compliance with the License.

* You may obtain a copy of the License at

*

* http://www.apache.org/licenses/LICENSE-2.0

*

* Unless required by applicable law or agreed to in writing, software

* distributed under the License is distributed on an "AS IS" BASIS,

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

* See the License for the specific language governing permissions and

* limitations under the License.

*/

* Utility for international phone numbers. Functionality includes formatting, parsing and

* validation.

*

* @author Shaopeng Jia

* @author Lara Rennie

*/

  // The minimum and maximum length of the national significant number.

  private static final int MIN_LENGTH_FOR_NSN = 3;

  private static final int MAX_LENGTH_FOR_NSN = 15;

  static final String META_DATA_FILE_PREFIX =

      "/com/google/i18n/phonenumbers/data/PhoneNumberMetadataProto";

  static final String COUNTRY_CODE_TO_REGION_CODE_MAP_CLASS_NAME =

      "CountryCodeToRegionCodeMap";

  private String currentFilePrefix = META_DATA_FILE_PREFIX;

  private static final Logger LOGGER = Logger.getLogger(PhoneNumberUtil.class.getName());

  // A mapping from a country code to the region codes which denote the country/region

  // represented by that country code. In the case of multiple countries sharing a calling code,

  // such as the NANPA countries, the one indicated with "isMainCountryForCode" in the metadata

  // should be first.

  private Map<Integer, List<String>> countryCodeToRegionCodeMap = null;

  // The set of countries the library supports.

  // There are roughly 220 of them and we set the initial capacity of the HashSet to 300 to offer a

  // load factor of roughly 0.75.

  private final Set<String> supportedCountries = new HashSet<String>(300);

  // The set of countries that share country code 1.

  // There are roughly 26 countries of them and we set the initial capacity of the HashSet to 35

  // to offer a load factor of roughly 0.75.

  private final Set<String> nanpaCountries = new HashSet<String>(35);

  private static final int NANPA_COUNTRY_CODE = 1;

  // The PLUS_SIGN signifies the international prefix.

  static final char PLUS_SIGN = '+';

  // These mappings map a character (key) to a specific digit that should replace it for

  // normalization purposes. Non-European digits that may be used in phone numbers are mapped to a

  // European equivalent.

  static final Map<Character, Character> DIGIT_MAPPINGS;

  // Only upper-case variants of alpha characters are stored.

  private static final Map<Character, Character> ALPHA_MAPPINGS;

  // For performance reasons, amalgamate both into one map.

  private static final Map<Character, Character> ALL_NORMALIZATION_MAPPINGS;

  static {

    HashMap<Character, Character> digitMap = new HashMap<Character, Character>(50);

    digitMap.put('0', '0');

    digitMap.put('\uFF10', '0');  // Fullwidth digit 0

    digitMap.put('\u0660', '0');  // Arabic-indic digit 0

    digitMap.put('1', '1');

    digitMap.put('\uFF11', '1');  // Fullwidth digit 1

    digitMap.put('\u0661', '1');  // Arabic-indic digit 1

    digitMap.put('2', '2');

    digitMap.put('\uFF12', '2');  // Fullwidth digit 2

    digitMap.put('\u0662', '2');  // Arabic-indic digit 2

    digitMap.put('3', '3');

    digitMap.put('\uFF13', '3');  // Fullwidth digit 3

    digitMap.put('\u0663', '3');  // Arabic-indic digit 3

    digitMap.put('4', '4');

    digitMap.put('\uFF14', '4');  // Fullwidth digit 4

    digitMap.put('\u0664', '4');  // Arabic-indic digit 4

    digitMap.put('5', '5');

    digitMap.put('\uFF15', '5');  // Fullwidth digit 5

    digitMap.put('\u0665', '5');  // Arabic-indic digit 5

    digitMap.put('6', '6');

    digitMap.put('\uFF16', '6');  // Fullwidth digit 6

    digitMap.put('\u0666', '6');  // Arabic-indic digit 6

    digitMap.put('7', '7');

    digitMap.put('\uFF17', '7');  // Fullwidth digit 7

    digitMap.put('\u0667', '7');  // Arabic-indic digit 7

    digitMap.put('8', '8');

    digitMap.put('\uFF18', '8');  // Fullwidth digit 8

    digitMap.put('\u0668', '8');  // Arabic-indic digit 8

    digitMap.put('9', '9');

    digitMap.put('\uFF19', '9');  // Fullwidth digit 9

    digitMap.put('\u0669', '9');  // Arabic-indic digit 9

    DIGIT_MAPPINGS = Collections.unmodifiableMap(digitMap);

    HashMap<Character, Character> alphaMap = new HashMap<Character, Character>(40);

    alphaMap.put('A', '2');

    alphaMap.put('B', '2');

    alphaMap.put('C', '2');

    alphaMap.put('D', '3');

    alphaMap.put('E', '3');

    alphaMap.put('F', '3');

    alphaMap.put('G', '4');

    alphaMap.put('H', '4');

    alphaMap.put('I', '4');

    alphaMap.put('J', '5');

    alphaMap.put('K', '5');

    alphaMap.put('L', '5');

    alphaMap.put('M', '6');

    alphaMap.put('N', '6');

    alphaMap.put('O', '6');

    alphaMap.put('P', '7');

    alphaMap.put('Q', '7');

    alphaMap.put('R', '7');

    alphaMap.put('S', '7');

    alphaMap.put('T', '8');

    alphaMap.put('U', '8');

    alphaMap.put('V', '8');

    alphaMap.put('W', '9');

    alphaMap.put('X', '9');

    alphaMap.put('Y', '9');

    alphaMap.put('Z', '9');

    ALPHA_MAPPINGS = Collections.unmodifiableMap(alphaMap);

    HashMap<Character, Character> combinedMap = new HashMap<Character, Character>(100);

    combinedMap.putAll(alphaMap);

    combinedMap.putAll(digitMap);

    ALL_NORMALIZATION_MAPPINGS = Collections.unmodifiableMap(combinedMap);

  }

  // A list of all country codes where national significant numbers (excluding any national prefix)

  // exist that start with a leading zero.

  private static final Set<Integer> LEADING_ZERO_COUNTRIES;

  static {

    HashSet<Integer> aSet = new HashSet<Integer>(10);

    aSet.add(39);  // Italy

    aSet.add(47);  // Norway

    aSet.add(225);  // Cote d'Ivoire

    aSet.add(227);  // Niger

    aSet.add(228);  // Togo

    aSet.add(241);  // Gabon

    aSet.add(379);  // Vatican City

    LEADING_ZERO_COUNTRIES = Collections.unmodifiableSet(aSet);

  }

  // Pattern that makes it easy to distinguish whether a country has a unique international dialing

  // prefix or not. If a country has a unique international prefix (e.g. 011 in USA), it will be

  // represented as a string that contains a sequence of ASCII digits. If there are multiple

  // available international prefixes in a country, they will be represented as a regex string that

  // always contains character(s) other than ASCII digits.

  // Note this regex also includes tilde, which signals waiting for the tone.

  private static final Pattern UNIQUE_INTERNATIONAL_PREFIX =

      Pattern.compile("[\\d]+(?:[~\u2053\u223C\uFF5E][\\d]+)?");

  // Regular expression of acceptable punctuation found in phone numbers. This excludes punctuation

  // found as a leading character only.

  // This consists of dash characters, white space characters, full stops, slashes,

  // square brackets, parentheses and tildes. It also includes the letter 'x' as that is found as a

  // placeholder for carrier information in some phone numbers.

  private static final String VALID_PUNCTUATION = "-x\u2010-\u2015\u2212\uFF0D-\uFF0F " +

      "\u00A0\u200B\u2060\u3000()\uFF08\uFF09\uFF3B\uFF3D.\\[\\]/~\u2053\u223C\uFF5E";

  // Digits accepted in phone numbers

  private static final String VALID_DIGITS =

      Arrays.toString(DIGIT_MAPPINGS.keySet().toArray()).replaceAll(", ", "");

  // We accept alpha characters in phone numbers, ASCII only, upper and lower case.

  private static final String VALID_ALPHA =

      Arrays.toString(ALPHA_MAPPINGS.keySet().toArray()).replaceAll(", ", "") +

      Arrays.toString(ALPHA_MAPPINGS.keySet().toArray()).toLowerCase().replaceAll(", ", "");

  private static final String PLUS_CHARS = "+\uFF0B";

  private static final Pattern PLUS_CHARS_PATTERN = Pattern.compile("[" + PLUS_CHARS + "]+");

  private static final Pattern CAPTURING_DIGIT_PATTERN =

      Pattern.compile("([" + VALID_DIGITS + "])");

  // Regular expression of acceptable characters that may start a phone number for the purposes of

  // parsing. This allows us to strip away meaningless prefixes to phone numbers that may be

  // mistakenly given to us. This consists of digits, the plus symbol and arabic-indic digits. This

  // does not contain alpha characters, although they may be used later in the number. It also does

  // not include other punctuation, as this will be stripped later during parsing and is of no

  // information value when parsing a number.

  private static final String VALID_START_CHAR = "[" + PLUS_CHARS + VALID_DIGITS + "]";

  static final Pattern VALID_START_CHAR_PATTERN = Pattern.compile(VALID_START_CHAR);

  // Regular expression of characters typically used to start a second phone number for the purposes

  // of parsing. This allows us to strip off parts of the number that are actually the start of

  // another number, such as for: (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.

  private static final String SECOND_NUMBER_START = "[\\\\/] *x";

  private static final Pattern SECOND_NUMBER_START_PATTERN = Pattern.compile(SECOND_NUMBER_START);

  // Regular expression of trailing characters that we want to remove. We remove all characters that

  // are not alpha or numerical characters. The hash character is retained here, as it may signify

  // the previous block was an extension.

  private static final String UNWANTED_END_CHARS = "[[\\P{N}&&\\P{L}]&&[^#]]+$";

  private static final Pattern UNWANTED_END_CHAR_PATTERN = Pattern.compile(UNWANTED_END_CHARS);

  // We use this pattern to check if the phone number has at least three letters in it - if so, then

  // we treat it as a number where some phone-number digits are represented by letters.

  private static final Pattern VALID_ALPHA_PHONE_PATTERN = Pattern.compile("(?:.*?[A-Za-z]){3}.*");

  // Regular expression of viable phone numbers. This is location independent. Checks we have at

  // least three leading digits, and only valid punctuation, alpha characters and

  // digits in the phone number. Does not include extension data.

  // The symbol 'x' is allowed here as valid punctuation since it is often used as a placeholder for

  // carrier codes, for example in Brazilian phone numbers. We also allow multiple "+" characters at

  // the start.

  // Corresponds to the following:

  // plus_sign*([punctuation]*[digits]){3,}([punctuation]|[digits]|[alpha])*

  private static final String VALID_PHONE_NUMBER =

      "[" + PLUS_CHARS + "]*(?:[" + VALID_PUNCTUATION + "]*[" + VALID_DIGITS + "]){3,}[" +

      VALID_ALPHA + VALID_PUNCTUATION + VALID_DIGITS + "]*";

  // Default extension prefix to use when formatting. This will be put in front of any extension

  // component of the number, after the main national number is formatted. For example, if you wish

  // the default extension formatting to be " extn: 3456", then you should specify " extn: " here

  // as the default extension prefix. This can be overridden by country-specific preferences.

  private static final String DEFAULT_EXTN_PREFIX = " ext. ";

  // Regexp of all possible ways to write extensions, for use when parsing. This will be run as a

  // case-insensitive regexp match. Wide character versions are also provided after each ascii

  // version. There are two regular expressions here: the more generic one starts with optional

  // white space and ends with an optional full stop (.), followed by zero or more spaces/tabs and

  // then the numbers themselves. The other one covers the special case of American numbers where

  // the extension is written with a hash at the end, such as "- 503#".

  // Note that the only capturing groups should be around the digits that you want to capture as

  // part of the extension, or else parsing will fail!

  private static final String KNOWN_EXTN_PATTERNS = "[ \u00A0\\t,]*(?:ext(?:ensio)?n?|" +

      "\uFF45\uFF58\uFF54\uFF4E?|[,x\uFF58#\uFF03~\uFF5E]|int|anexo|\uFF49\uFF4E\uFF54)" +

      "[:\\.\uFF0E]?[ \u00A0\\t,-]*([" + VALID_DIGITS + "]{1,7})#?|[- ]+([" + VALID_DIGITS +

      "]{1,5})#";

  // Regexp of all known extension prefixes used by different countries followed by 1 or more valid

  // digits, for use when parsing.

  private static final Pattern EXTN_PATTERN =

      Pattern.compile("(?:" + KNOWN_EXTN_PATTERNS + ")$",

                      Pattern.UNICODE_CASE | Pattern.CASE_INSENSITIVE);

  // We append optionally the extension pattern to the end here, as a valid phone number may

  // have an extension prefix appended, followed by 1 or more digits.

  private static final Pattern VALID_PHONE_NUMBER_PATTERN =

      Pattern.compile(VALID_PHONE_NUMBER + "(?:" + KNOWN_EXTN_PATTERNS + ")?",

                      Pattern.UNICODE_CASE | Pattern.CASE_INSENSITIVE);

  private static final Pattern NON_DIGITS_PATTERN = Pattern.compile("(\\D+)");

  private static final Pattern FIRST_GROUP_PATTERN = Pattern.compile("(\\$1)");

  private static final Pattern NP_PATTERN = Pattern.compile("\\$NP");

  private static final Pattern FG_PATTERN = Pattern.compile("\\$FG");

  private static final Pattern CC_PATTERN = Pattern.compile("\\$CC");

  private static PhoneNumberUtil instance = null;

  // A mapping from a region code to the PhoneMetadata for that region.

  private Map<String, PhoneMetadata> countryToMetadataMap =

      new HashMap<String, PhoneMetadata>();

  // A cache for frequently used country-specific regular expressions.

  // As most people use phone numbers primarily from one to two countries, and there are roughly 60

  // regular expressions needed, the initial capacity of 100 offers a rough load factor of 0.75.

  private RegexCache regexCache = new RegexCache(100);

  /**

   * INTERNATIONAL and NATIONAL formats are consistent with the definition in ITU-T Recommendation

   * E. 123. For example, the number of the Google Zurich office will be written as

   * "+41 44 668 1800" in INTERNATIONAL format, and as "044 668 1800" in NATIONAL format.

   * E164 format is as per INTERNATIONAL format but with no formatting applied, e.g. +41446681800.

   *

   * Note: If you are considering storing the number in a neutral format, you are highly advised to

   * use the phonenumber.proto.

   */

  public enum PhoneNumberFormat {

    E164,

    INTERNATIONAL,

    NATIONAL

  }

  /**

   * Type of phone numbers.

   */

  public enum PhoneNumberType {

    FIXED_LINE,

    MOBILE,

    // In some countries (e.g. the USA), it is impossible to distinguish between fixed-line and

    // mobile numbers by looking at the phone number itself.

    FIXED_LINE_OR_MOBILE,

    // Freephone lines

    TOLL_FREE,

    PREMIUM_RATE,

    // The cost of this call is shared between the caller and the recipient, and is hence typically

    // less than PREMIUM_RATE calls. See // http://en.wikipedia.org/wiki/Shared_Cost_Service for

    // more information.

    SHARED_COST,

    // Voice over IP numbers. This includes TSoIP (Telephony Service over IP).

    VOIP,

    // A personal number is associated with a particular person, and may be routed to either a

    // MOBILE or FIXED_LINE number. Some more information can be found here:

    // http://en.wikipedia.org/wiki/Personal_Numbers

    PERSONAL_NUMBER,

    PAGER,

    // A phone number is of type UNKNOWN when it does not fit any of the known patterns for a

    // specific country.

    UNKNOWN

  }

  /**

   * Types of phone number matches. See detailed description beside the isNumberMatch() method.

   */

  public enum MatchType {

    NO_MATCH,

    SHORT_NSN_MATCH,

    NSN_MATCH,

    EXACT_MATCH,

  }

  /**

   * Possible outcomes when testing if a PhoneNumber is possible.

   */

  public enum ValidationResult {

    IS_POSSIBLE,

    INVALID_COUNTRY_CODE,

    TOO_SHORT,

    TOO_LONG,

  }

  /**

   * This class implements a singleton, so the only constructor is private.

   */

  private PhoneNumberUtil() {

  }

  private void init(String filePrefix) {

    currentFilePrefix = filePrefix;

    for (List<String> regionCodes : countryCodeToRegionCodeMap.values()) {

      supportedCountries.addAll(regionCodes);

    }

    nanpaCountries.addAll(countryCodeToRegionCodeMap.get(NANPA_COUNTRY_CODE));

  }

  private void loadMetadataForRegionFromFile(String filePrefix, String regionCode) {

    InputStream source =

        PhoneNumberUtil.class.getResourceAsStream(filePrefix + "_" + regionCode);

    ObjectInputStream in;

    try {

      in = new ObjectInputStream(source);

      PhoneMetadataCollection metadataCollection = new PhoneMetadataCollection();

      metadataCollection.readExternal(in);

      for (PhoneMetadata metadata : metadataCollection.getMetadataList()) {

        countryToMetadataMap.put(regionCode, metadata);

      }

    } catch (IOException e) {

      LOGGER.log(Level.WARNING, e.toString());

    }

  }

  /**

   * 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 number  the string that might contain a phone number

   * @return        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

   */

  static String extractPossibleNumber(String number) {

    Matcher m = VALID_START_CHAR_PATTERN.matcher(number);

    if (m.find()) {

      number = number.substring(m.start());

      // Remove trailing non-alpha non-numerical characters.

      Matcher trailingCharsMatcher = UNWANTED_END_CHAR_PATTERN.matcher(number);

      if (trailingCharsMatcher.find()) {

        number = number.substring(0, trailingCharsMatcher.start());

      }

      // Check for extra numbers at the end.

      Matcher secondNumber = SECOND_NUMBER_START_PATTERN.matcher(number);

      if (secondNumber.find()) {

        number = number.substring(0, secondNumber.start());

      }

      return number;

    } else {

      return "";

    }

  }

  /**

   * 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 number  string to be checked for viability as a phone number

   * @return        true if the number could be a phone number of some sort, otherwise false

   */

  static boolean isViablePhoneNumber(String number) {

    if (number.length() < MIN_LENGTH_FOR_NSN) {

      return false;

    }

    Matcher m = VALID_PHONE_NUMBER_PATTERN.matcher(number);

    return m.matches();

  }

  /**

   * Normalizes a string of characters representing a phone number. This performs the following

   * conversions:

   *   Wide-ascii digits are converted to normal ASCII (European) digits.

   *   Letters are converted to their numeric representation on a telephone keypad. The keypad

   *       used here is the one defined in ITU Recommendation E.161. This is only done if there are

   *       3 or more letters in the number, to lessen the risk that such letters are typos -

   *       otherwise alpha characters are stripped.

   *   Punctuation is stripped.

   *   Arabic-Indic numerals are converted to European numerals.

   *

   * @param number  a string of characters representing a phone number

   * @return        the normalized string version of the phone number

   */

  static String normalize(String number) {

    Matcher m = VALID_ALPHA_PHONE_PATTERN.matcher(number);

    if (m.matches()) {

      return normalizeHelper(number, ALL_NORMALIZATION_MAPPINGS, true);

    } else {

      return normalizeHelper(number, DIGIT_MAPPINGS, true);

    }

  }

  /**

   * 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 number  a StringBuffer of characters representing a phone number that will be normalized

   *     in place

   */

  static void normalize(StringBuffer number) {

    String normalizedNumber = normalize(number.toString());

    number.replace(0, number.length(), normalizedNumber);

  }

  /**

   * Normalizes a string of characters representing a phone number. This converts wide-ascii and

   * arabic-indic numerals to European numerals, and strips punctuation and alpha characters.

   *

   * @param number  a string of characters representing a phone number

   * @return        the normalized string version of the phone number

   */

  public static String normalizeDigitsOnly(String number) {

    return normalizeHelper(number, DIGIT_MAPPINGS, true);

  }

  /**

   * Converts all alpha characters in a number to their respective digits on a keypad, but retains

   * existing formatting. This Java implementation of this function also converts wide-ascii digits

   * to normal ascii digits, and converts Arabic-Indic numerals to European numerals.

   */

  public static String convertAlphaCharactersInNumber(String number) {

    return normalizeHelper(number, ALL_NORMALIZATION_MAPPINGS, false);

  }

  /**

   * Gets the length of the geographical area code from the national_number field of the PhoneNumber

   * object passed in, so that clients could use it to split a national significant number into

   * geographical area code and subscriber number. It works in such a way that the resultant

   * subscriber number should be diallable, at least on some devices. An example of how this could

   * be used:

   *

   * PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();

   * PhoneNumber number = phoneUtil.parse("16502530000", "US");

   * String nationalSignificantNumber = PhoneNumberUtil.getNationalSignificantNumber(number);

   * String areaCode;

   * String subscriberNumber;

   *

   * int areaCodeLength = phoneUtil.getLengthOfGeographicalAreaCode(number);

   * if (areaCodeLength > 0) {

   *   areaCode = nationalSignificantNumber.substring(0, areaCodeLength);

   *   subscriberNumber = nationalSignificantNumber.substring(areaCodeLength);

   * } else {

   *   areaCode = "";

   *   subscriberNumber = nationalSignificantNumber;

   * }

   *

   * N.B.: area code is a very ambiguous concept, so the I18N team generally recommends against

   * using it for most purposes, but recommends using the more general national_number instead. Read

   * the following carefully before deciding to use this method:

   *

   *  - geographical area codes change over time, and this method honors those changes; therefore,

   *    it doesn't guarantee the stability of the result it produces.

   *  - subscriber numbers may not be diallable from all devices (notably mobile devices, which

   *    typically requires the full national_number to be dialled in most countries).

   *  - most non-geographical numbers have no area codes.

   *  - some geographical numbers have no area codes.

   *

   * @param number  the PhoneNumber object for which clients want to know the length of the area

   *     code in the national_number field.

   * @return  the length of area code of the PhoneNumber object passed in.

   */

  public int getLengthOfGeographicalAreaCode(PhoneNumber number) {

    String regionCode = getRegionCodeForNumber(number);

    if (!isValidRegionCode(regionCode)) {

      return 0;

    }

    PhoneMetadata metadata = getMetadataForRegion(regionCode);

    // For NANPA countries, national prefix is the same as country code, but it is not stored in

    // the metadata.

    if (!metadata.hasNationalPrefix() && !isNANPACountry(regionCode)) {

      return 0;

    }

    PhoneNumberType type = getNumberTypeHelper(getNationalSignificantNumber(number),

                                               metadata);

    // Most numbers other than the two types below have to be dialled in full.

    if (type != PhoneNumberType.FIXED_LINE && type != PhoneNumberType.FIXED_LINE_OR_MOBILE) {

      return 0;

    }

    PhoneNumber copiedProto;

    if (number.hasExtension()) {

      // We don't want to alter the proto given to us, but we don't want to include the extension

      // when we format it, so we copy it and clear the extension here.

      copiedProto = new PhoneNumber();

      copiedProto.mergeFrom(number);

      copiedProto.clearExtension();

    } else {

      copiedProto = number;

    }

    String nationalSignificantNumber = format(copiedProto,

                                              PhoneNumberUtil.PhoneNumberFormat.INTERNATIONAL);

    String[] numberGroups = NON_DIGITS_PATTERN.split(nationalSignificantNumber);

    // The pattern will start with "+COUNTRY_CODE " so the first group will always be the empty

    // string (before the + symbol) and the second group will be the country code. The third group

    // will be area code if it is not the last group.

    if (numberGroups.length <= 3) {

      return 0;

    }

    return numberGroups[2].length();

  }

  /**

   * 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 number                     a string of characters representing a phone number

   * @param normalizationReplacements  a mapping of characters to what they should be replaced by in

   *                                   the normalized version of the phone number

   * @param 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  the normalized string version of the phone number

   */

  private static String normalizeHelper(String number,

                                        Map<Character, Character> normalizationReplacements,

                                        boolean removeNonMatches) {

    StringBuffer normalizedNumber = new StringBuffer(number.length());

    char[] numberAsCharArray = number.toCharArray();

    for (char character : numberAsCharArray) {

      Character newDigit = normalizationReplacements.get(Character.toUpperCase(character));

      if (newDigit != null) {

        normalizedNumber.append(newDigit);

      } else if (!removeNonMatches) {

        normalizedNumber.append(character);

      }

      // If neither of the above are true, we remove this character.

    }

    return normalizedNumber.toString();

  }

  static synchronized PhoneNumberUtil getInstance(

      String baseFileLocation,

      Map<Integer, List<String>> countryCodeToRegionCodeMap) {

    if (instance == null) {

      instance = new PhoneNumberUtil();

      instance.countryCodeToRegionCodeMap = countryCodeToRegionCodeMap;

      instance.init(baseFileLocation);

    }

    return instance;

  }

  /**

   * Used for testing purposes only to reset the PhoneNumberUtil singleton to null.

   */

  static synchronized void resetInstance() {

    instance = null;

  }

  /**

   * Convenience method to enable tests to get a list of what countries the library has metadata

   * for.

   */

  public Set<String> getSupportedCountries() {

    return supportedCountries;

  }

  /**

   * Gets a PhoneNumberUtil instance to carry out international phone number formatting, parsing,

   * or validation. The instance is loaded with phone number metadata for a number of most commonly

   * used countries/regions.

   *

   * The PhoneNumberUtil is implemented as a singleton. Therefore, calling getInstance multiple

   * times will only result in one instance being created.

   *

   * @return a PhoneNumberUtil instance

   */

  public static synchronized PhoneNumberUtil getInstance() {

    if (instance == null) {

      return getInstance(META_DATA_FILE_PREFIX,

          CountryCodeToRegionCodeMap.getCountryCodeToRegionCodeMap());

    }

    return instance;

  }

  /**

   * Helper function to check region code is not unknown or null.

   */

  private boolean isValidRegionCode(String regionCode) {

    return regionCode != null && supportedCountries.contains(regionCode.toUpperCase());

  }

  /**

   * 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 number         the phone number to be formatted

   * @param numberFormat   the format the phone number should be formatted into

   * @return  the formatted phone number

   */

  public String format(PhoneNumber number, PhoneNumberFormat numberFormat) {

    StringBuffer formattedNumber = new StringBuffer(20);

    format(number, numberFormat, formattedNumber);

    return formattedNumber.toString();

  }

  // Same as format(PhoneNumber, PhoneNumberFormat), but accepts mutable StringBuffer as parameters

  // to decrease object creation when invoked many times.

  public void format(PhoneNumber number, PhoneNumberFormat numberFormat,

                     StringBuffer formattedNumber) {

    // Clear the StringBuffer first.

    formattedNumber.setLength(0);

    int countryCode = number.getCountryCode();

    String nationalSignificantNumber = getNationalSignificantNumber(number);

    if (numberFormat == PhoneNumberFormat.E164) {

      // Early exit for E164 case since no formatting of the national number needs to be applied.

      // Extensions are not formatted.

      formattedNumber.append(nationalSignificantNumber);

      formatNumberByFormat(countryCode, PhoneNumberFormat.E164, formattedNumber);

      return;

    }

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

    String regionCode = getRegionCodeForCountryCode(countryCode);

    if (!isValidRegionCode(regionCode)) {

      formattedNumber.append(nationalSignificantNumber);

      return;

    }

    formattedNumber.append(formatNationalNumber(nationalSignificantNumber,

                                                regionCode, numberFormat));

    maybeGetFormattedExtension(number, regionCode, formattedNumber);

    formatNumberByFormat(countryCode, numberFormat, formattedNumber);

  }

  /**

   * Formats a phone number in the specified format using client-defined formatting rules. Note that

   * if the phone number has a country code of zero or an otherwise invalid country code, we cannot

   * work out things like whether there should be a national prefix applied, or how to format

   * extensions, so we return the national significant number with no formatting applied.

   *

   * @param number                        the phone number to be formatted

   * @param numberFormat                  the format the phone number should be formatted into

   * @param userDefinedFormats            formatting rules specified by clients

   * @return  the formatted phone number

   */

  public String formatByPattern(PhoneNumber number,

                                PhoneNumberFormat numberFormat,

                                List<NumberFormat> userDefinedFormats) {

    int countryCode = number.getCountryCode();

    String nationalSignificantNumber = getNationalSignificantNumber(number);

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

    String regionCode = getRegionCodeForCountryCode(countryCode);

    if (!isValidRegionCode(regionCode)) {

      return nationalSignificantNumber;

    }

    List<NumberFormat> userDefinedFormatsCopy =

        new ArrayList<NumberFormat>(userDefinedFormats.size());

    for (NumberFormat numFormat : userDefinedFormats) {

      String nationalPrefixFormattingRule = numFormat.getNationalPrefixFormattingRule();

      if (nationalPrefixFormattingRule.length() > 0) {

        // Before we do a replacement of the national prefix pattern $NP with the national prefix,

        // we need to copy the rule so that subsequent replacements for different numbers have the

        // appropriate national prefix.

        NumberFormat numFormatCopy = new NumberFormat();

        numFormatCopy.mergeFrom(numFormat);

        String nationalPrefix = getMetadataForRegion(regionCode).getNationalPrefix();

        if (nationalPrefix.length() > 0) {

          // Replace $NP with national prefix and $FG with the first group ($1).

          nationalPrefixFormattingRule =

              NP_PATTERN.matcher(nationalPrefixFormattingRule).replaceFirst(nationalPrefix);

          nationalPrefixFormattingRule =

              FG_PATTERN.matcher(nationalPrefixFormattingRule).replaceFirst("\\$1");

          numFormatCopy.setNationalPrefixFormattingRule(nationalPrefixFormattingRule);

        } else {

          // We don't want to have a rule for how to format the national prefix if there isn't one.

          numFormatCopy.clearNationalPrefixFormattingRule();

        }

        userDefinedFormatsCopy.add(numFormatCopy);

      } else {

        // Otherwise, we just add the original rule to the modified list of formats.

        userDefinedFormatsCopy.add(numFormat);

      }

    }

    StringBuffer formattedNumber =

        new StringBuffer(formatAccordingToFormats(nationalSignificantNumber,

                                                  userDefinedFormatsCopy,

                                                  numberFormat));

    maybeGetFormattedExtension(number, regionCode, formattedNumber);

    formatNumberByFormat(countryCode, numberFormat, formattedNumber);

    return formattedNumber.toString();

  }

  public String formatNationalNumberWithCarrierCode(PhoneNumber number, String carrierCode) {

    int countryCode = number.getCountryCode();

    String nationalSignificantNumber = getNationalSignificantNumber(number);

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

    String regionCode = getRegionCodeForCountryCode(countryCode);

    if (!isValidRegionCode(regionCode)) {

      return nationalSignificantNumber;

    }

    StringBuffer formattedNumber = new StringBuffer(20);

    formattedNumber.append(formatNationalNumber(nationalSignificantNumber,

                                                regionCode,

                                                PhoneNumberFormat.NATIONAL,

                                                carrierCode));

    maybeGetFormattedExtension(number, regionCode, formattedNumber);

    formatNumberByFormat(countryCode, PhoneNumberFormat.NATIONAL, formattedNumber);

    return formattedNumber.toString();

  }

  /**

   * Formats a phone number for out-of-country dialing purpose. If no countryCallingFrom

   * is supplied, we format the number in its INTERNATIONAL format. If the countryCallingFrom is

   * the same as the country where the number is from, then NATIONAL formatting will be applied.

   *

   * If the number itself has a country code of zero or an otherwise invalid country code, then we

   * return the number with no formatting applied.

   *

   * Note this function takes care of the case for calling inside of NANPA and between Russia and

   * Kazakhstan (who share the same country code). In those cases, no international prefix is used.

   * For countries which have multiple international prefixes, the number in its INTERNATIONAL

   * format will be returned instead.

   *

   * @param number               the phone number to be formatted

   * @param countryCallingFrom   the ISO 3166-1 two-letter country code that denotes

   *                             the foreign country where the call is being placed

   * @return  the formatted phone number

   */

  public String formatOutOfCountryCallingNumber(PhoneNumber number,

                                                String countryCallingFrom) {

    if (!isValidRegionCode(countryCallingFrom)) {

      return format(number, PhoneNumberFormat.INTERNATIONAL);

    }

    int countryCode = number.getCountryCode();

    String regionCode = getRegionCodeForCountryCode(countryCode);

    String nationalSignificantNumber = getNationalSignificantNumber(number);

    if (!isValidRegionCode(regionCode)) {

      return nationalSignificantNumber;

    }

    if (countryCode == NANPA_COUNTRY_CODE) {

      if (isNANPACountry(countryCallingFrom)) {

        // For NANPA countries, return the national format for these countries but prefix it with

        // the country code.

        return countryCode + " " + format(number, PhoneNumberFormat.NATIONAL);

      }

    } else if (countryCode == getCountryCodeForRegion(countryCallingFrom)) {

    // For countries that share a country calling code, the country code need not be dialled. This

    // also applies when dialling within a country, so this if clause covers both these cases.

    // Technically this is the case for dialling from la Reunion to other overseas departments of

    // France (French Guiana, Martinique, Guadeloupe), but not vice versa - so we don't cover this

    // edge case for now and for those cases return the version including country code.

    // Details here: http://www.petitfute.com/voyage/225-info-pratiques-reunion

      return format(number, PhoneNumberFormat.NATIONAL);

    }

    String formattedNationalNumber =

        formatNationalNumber(nationalSignificantNumber,

                             regionCode, PhoneNumberFormat.INTERNATIONAL);

    PhoneMetadata metadata = getMetadataForRegion(countryCallingFrom);

    String internationalPrefix = metadata.getInternationalPrefix();

    // For countries that have multiple international prefixes, the international format of the

    // number is returned, unless there is a preferred international prefix.

    String internationalPrefixForFormatting = "";

    if (UNIQUE_INTERNATIONAL_PREFIX.matcher(internationalPrefix).matches()) {

      internationalPrefixForFormatting = internationalPrefix;

    } else if (metadata.hasPreferredInternationalPrefix()) {

      internationalPrefixForFormatting = metadata.getPreferredInternationalPrefix();

    }

    StringBuffer formattedNumber = new StringBuffer(formattedNationalNumber);

    maybeGetFormattedExtension(number, regionCode, formattedNumber);

    if (internationalPrefixForFormatting.length() > 0) {

      formattedNumber.insert(0, " ").insert(0, countryCode).insert(0, " ")

          .insert(0, internationalPrefixForFormatting);

    } else {

      formatNumberByFormat(countryCode,

                           PhoneNumberFormat.INTERNATIONAL,

                           formattedNumber);

    }

    return formattedNumber.toString();

  }

  /**

   * Formats a phone number using the original phone number format that the number is parsed from.

   * The original format is embedded in the country_code_source field of the PhoneNumber object

   * passed in. If such information is missing, the number will be formatted into the NATIONAL

   * format by default.

   *

   * @param number  the PhoneNumber that needs to be formatted in its original number format

   * @param countryCallingFrom  the country whose IDD needs to be prefixed if the original number

   *     has one

   * @return  the formatted phone number in its original number format

   */

  public String formatInOriginalFormat(PhoneNumber number, String countryCallingFrom) {

    if (!number.hasCountryCodeSource()) {

      return format(number, PhoneNumberFormat.NATIONAL);

    }

    switch (number.getCountryCodeSource()) {

      case FROM_NUMBER_WITH_PLUS_SIGN:

        return format(number, PhoneNumberFormat.INTERNATIONAL);

      case FROM_NUMBER_WITH_IDD:

        return formatOutOfCountryCallingNumber(number, countryCallingFrom);

      case FROM_NUMBER_WITHOUT_PLUS_SIGN:

        return format(number, PhoneNumberFormat.INTERNATIONAL).substring(1);

      case FROM_DEFAULT_COUNTRY:

      default:

        return format(number, PhoneNumberFormat.NATIONAL);

    }

  }

  /**

   * 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 number  the PhoneNumber object for which the national significant number is needed

   * @return  the national significant number of the PhoneNumber object passed in

   */

  public static String getNationalSignificantNumber(PhoneNumber number) {

    // The leading zero in the national (significant) number of an Italian phone number has a

    // special meaning. Unlike the rest of the world, it indicates the number is a landline

    // number. There have been plans to migrate landline numbers to start with the digit two since

    // December 2000, but it has not yet happened.

    // See http://en.wikipedia.org/wiki/%2B39 for more details.

    // Other countries such as Cote d'Ivoire and Gabon use this for their mobile numbers.

    StringBuffer nationalNumber = new StringBuffer(

        (number.hasItalianLeadingZero() &&

         number.getItalianLeadingZero() &&

         isLeadingZeroCountry(number.getCountryCode()))

        ? "0" : ""

    );

    nationalNumber.append(number.getNationalNumber());

    return nationalNumber.toString();

  }

  /**

   * A helper function that is used by format and formatByPattern.

   */

  private void formatNumberByFormat(int countryCode,

                                    PhoneNumberFormat numberFormat,

                                    StringBuffer formattedNumber) {

    switch (numberFormat) {

      case E164:

        formattedNumber.insert(0, countryCode).insert(0, PLUS_SIGN);

        return;

      case INTERNATIONAL:

        formattedNumber.insert(0, " ").insert(0, countryCode).insert(0, PLUS_SIGN);

        return;

      case NATIONAL:

      default:

        return;

    }

  }

  // Simple wrapper of formatNationalNumber for the common case of no carrier code.

  private String formatNationalNumber(String number,

                                      String regionCode,

                                      PhoneNumberFormat numberFormat) {

    return formatNationalNumber(number, regionCode, numberFormat, null);

  }

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

  private String formatNationalNumber(String number,

                                      String regionCode,

                                      PhoneNumberFormat numberFormat,

                                      String carrierCode) {

    PhoneMetadata metadata = getMetadataForRegion(regionCode);

    List<NumberFormat> intlNumberFormats = metadata.getIntlNumberFormatList();

    // When the intlNumberFormats exists, we use that to format national number for the

    // INTERNATIONAL format instead of using the numberDesc.numberFormats.

    List<NumberFormat> availableFormats =

        (intlNumberFormats.size() == 0 || numberFormat == PhoneNumberFormat.NATIONAL)

        ? metadata.getNumberFormatList()

        : metadata.getIntlNumberFormatList();

    return formatAccordingToFormats(number, availableFormats, numberFormat, carrierCode);

  }

  // Simple wrapper of formatAccordingToFormats for the common case of no carrier code.

  private String formatAccordingToFormats(String nationalNumber,

                                          List<NumberFormat> availableFormats,

                                          PhoneNumberFormat numberFormat) {

    return formatAccordingToFormats(nationalNumber, availableFormats, numberFormat, null);

  }

  // Note that carrierCode is optional - if NULL or an empty string, no carrier code replacement

  // will take place. Carrier code replacement occurs before national prefix replacement.

  private String formatAccordingToFormats(String nationalNumber,

                                          List<NumberFormat> availableFormats,

                                          PhoneNumberFormat numberFormat,

                                          String carrierCode) {

    for (NumberFormat numFormat : availableFormats) {

      int size = numFormat.getLeadingDigitsPatternCount();

      if (size == 0 || regexCache.getPatternForRegex(

              // We always use the last leading_digits_pattern, as it is the most detailed.

              numFormat.getLeadingDigitsPattern(size - 1)).matcher(nationalNumber).lookingAt()) {

        Matcher m = regexCache.getPatternForRegex(numFormat.getPattern()).matcher(nationalNumber);

        String numberFormatRule = numFormat.getFormat();

        if (m.matches()) {

          if (carrierCode != null && carrierCode.length() > 0 &&

              numFormat.getDomesticCarrierCodeFormattingRule().length() > 0) {

            // Replace the $CC in the formatting rule with the desired carrier code.

            String carrierCodeFormattingRule = numFormat.getDomesticCarrierCodeFormattingRule();

            carrierCodeFormattingRule =

                CC_PATTERN.matcher(carrierCodeFormattingRule).replaceFirst(carrierCode);

            // Now replace the $FG in the formatting rule with the first group and the carrier code

            // combined in the appropriate way.

            numberFormatRule = FIRST_GROUP_PATTERN.matcher(numberFormatRule)

                .replaceFirst(carrierCodeFormattingRule);

          }

          String nationalPrefixFormattingRule = numFormat.getNationalPrefixFormattingRule();

          if (numberFormat == PhoneNumberFormat.NATIONAL &&

              nationalPrefixFormattingRule != null &&

              nationalPrefixFormattingRule.length() > 0) {

            Matcher firstGroupMatcher = FIRST_GROUP_PATTERN.matcher(numberFormatRule);

            return m.replaceAll(firstGroupMatcher.replaceFirst(nationalPrefixFormattingRule));

          } else {

            return m.replaceAll(numberFormatRule);

          }

        }

      }

    }

    // If no pattern above is matched, we format the number as a whole.

    return nationalNumber;

  }

  /**

   * Gets a valid number for the specified country.

   *

   * @param regionCode  the ISO 3166-1 two-letter country code that denotes

   *                    the country for which an example number is needed

   * @return  a valid fixed-line number for the specified country. Returns null when the metadata

   *    does not contain such information.

   */

  public PhoneNumber getExampleNumber(String regionCode) {

    return getExampleNumberForType(regionCode, PhoneNumberType.FIXED_LINE);

  }

  /**

   * Gets a valid number for the specified country and number type.

   *

   * @param regionCode  the ISO 3166-1 two-letter country code that denotes

   *                    the country for which an example number is needed

   * @param type  the type of number that is needed

   * @return  a valid number for the specified country and type. Returns null when the metadata

   *     does not contain such information.

   */

  public PhoneNumber getExampleNumberForType(String regionCode, PhoneNumberType type) {

    PhoneNumberDesc desc = getNumberDescByType(getMetadataForRegion(regionCode), type);

    try {

      if (desc.hasExampleNumber()) {

        return parse(desc.getExampleNumber(), regionCode);

      }

    } catch (NumberParseException e) {

      LOGGER.log(Level.SEVERE, e.toString());

    }

    return null;

  }

  /**

   * Appends the formatted extension of a phone number to formattedNumber, if the phone number had

   * an extension specified.

   */

  private void maybeGetFormattedExtension(PhoneNumber number, String regionCode,

                                          StringBuffer formattedNumber) {

    if (number.hasExtension()) {

      // Formats the extension part of the phone number by prefixing it with the appropriate

      // extension prefix. This will be the default extension prefix, unless overridden by a

      // preferred extension prefix for this country.

      PhoneMetadata metadata = getMetadataForRegion(regionCode);

      if (metadata.hasPreferredExtnPrefix()) {

        formattedNumber.append(metadata.getPreferredExtnPrefix());

      } else {

        formattedNumber.append(DEFAULT_EXTN_PREFIX);

      }

      formattedNumber.append(number.getExtension());

    }

  }

  PhoneNumberDesc getNumberDescByType(PhoneMetadata metadata, PhoneNumberType type) {

    switch (type) {

      case PREMIUM_RATE:

        return metadata.getPremiumRate();

      case TOLL_FREE:

        return metadata.getTollFree();

      case MOBILE:

        return metadata.getMobile();

      case FIXED_LINE:

      case FIXED_LINE_OR_MOBILE:

        return metadata.getFixedLine();

      case SHARED_COST:

        return metadata.getSharedCost();

      case VOIP:

        return metadata.getVoip();

      case PERSONAL_NUMBER:

        return metadata.getPersonalNumber();

      case PAGER:

        return metadata.getPager();

      default:

        return metadata.getGeneralDesc();

    }

  }

  /**

   * Gets the type of a phone number.

   *

   * @param number  the phone number that we want to know the type

   * @return  the type of the phone number

   */

  public PhoneNumberType getNumberType(PhoneNumber number) {

    String regionCode = getRegionCodeForNumber(number);

    if (!isValidRegionCode(regionCode)) {

      return PhoneNumberType.UNKNOWN;

    }

    String nationalSignificantNumber = getNationalSignificantNumber(number);

    return getNumberTypeHelper(nationalSignificantNumber, getMetadataForRegion(regionCode));

  }

  private PhoneNumberType getNumberTypeHelper(String nationalNumber, PhoneMetadata metadata) {

    PhoneNumberDesc generalNumberDesc = metadata.getGeneralDesc();

    if (!generalNumberDesc.hasNationalNumberPattern() ||

        !isNumberMatchingDesc(nationalNumber, generalNumberDesc)) {

      return PhoneNumberType.UNKNOWN;

    }

    if (isNumberMatchingDesc(nationalNumber, metadata.getPremiumRate())) {

      return PhoneNumberType.PREMIUM_RATE;

    }

    if (isNumberMatchingDesc(nationalNumber, metadata.getTollFree())) {

      return PhoneNumberType.TOLL_FREE;

    }

    if (isNumberMatchingDesc(nationalNumber, metadata.getSharedCost())) {

      return PhoneNumberType.SHARED_COST;

    }

    if (isNumberMatchingDesc(nationalNumber, metadata.getVoip())) {

      return PhoneNumberType.VOIP;

    }

    if (isNumberMatchingDesc(nationalNumber, metadata.getPersonalNumber())) {

      return PhoneNumberType.PERSONAL_NUMBER;

    }

    if (isNumberMatchingDesc(nationalNumber, metadata.getPager())) {

      return PhoneNumberType.PAGER;

    }

    boolean isFixedLine = isNumberMatchingDesc(nationalNumber, metadata.getFixedLine());

    if (isFixedLine) {

      if (metadata.getSameMobileAndFixedLinePattern()) {

        return PhoneNumberType.FIXED_LINE_OR_MOBILE;

      } else if (isNumberMatchingDesc(nationalNumber, metadata.getMobile())) {

        return PhoneNumberType.FIXED_LINE_OR_MOBILE;

      }

      return PhoneNumberType.FIXED_LINE;

    }

    // 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.getSameMobileAndFixedLinePattern() &&

        isNumberMatchingDesc(nationalNumber, metadata.getMobile())) {

      return PhoneNumberType.MOBILE;

    }

    return PhoneNumberType.UNKNOWN;

  }

  PhoneMetadata getMetadataForRegion(String regionCode) {

    if (!isValidRegionCode(regionCode)) {

      return null;

    }

    regionCode = regionCode.toUpperCase();

    if (!countryToMetadataMap.containsKey(regionCode)) {

      loadMetadataForRegionFromFile(currentFilePrefix, regionCode);

    }

    return countryToMetadataMap.get(regionCode);

  }

  private boolean isNumberMatchingDesc(String nationalNumber, PhoneNumberDesc numberDesc) {

    Matcher possibleNumberPatternMatcher =

        regexCache.getPatternForRegex(numberDesc.getPossibleNumberPattern())

            .matcher(nationalNumber);

    Matcher nationalNumberPatternMatcher =

        regexCache.getPatternForRegex(numberDesc.getNationalNumberPattern())

            .matcher(nationalNumber);

    return possibleNumberPatternMatcher.matches() && nationalNumberPatternMatcher.matches();

  }

  /**

   * 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 number       the phone number that we want to validate

   * @return  a boolean that indicates whether the number is of a valid pattern

   */

  public boolean isValidNumber(PhoneNumber number) {

    String regionCode = getRegionCodeForNumber(number);

    return isValidRegionCode(regionCode)

           && isValidNumberForRegion(number, regionCode);

  }

  /**

   * 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 number       the phone number that we want to validate

   * @param regionCode   the ISO 3166-1 two-letter country code that denotes

   *                     the region/country that we want to validate the phone number for

   * @return  a boolean that indicates whether the number is of a valid pattern

   */

  public boolean isValidNumberForRegion(PhoneNumber number, String regionCode) {

    if (number.getCountryCode() != getCountryCodeForRegion(regionCode)) {

      return false;

    }

    PhoneMetadata metadata = getMetadataForRegion(regionCode);

    PhoneNumberDesc generalNumDesc = metadata.getGeneralDesc();

    String 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.hasNationalNumberPattern()) {

      int numberLength = nationalSignificantNumber.length();

      return numberLength > MIN_LENGTH_FOR_NSN && numberLength <= MAX_LENGTH_FOR_NSN;

    }

    return getNumberTypeHelper(nationalSignificantNumber, metadata) != PhoneNumberType.UNKNOWN;

  }

  /**

   * Returns the country/region where a phone number is from. This could be used for geo-coding in

   * the country/region level.

   *

   * @param number  the phone number whose origin we want to know

   * @return  the country/region where the phone number is from, or null if no country matches this