JAVA: libphonenumber 4.2. Includes rest of emergency number data, new region SX.

java/release_notes.txt

@@ -1,3 +1,19 @@
+November 10th, 2011: libphonenumber-4.2
+* Code changes
+ - Providing an "exact match" isEmergencyNumber method
+ - Improvement to PhoneNumberMatcher: requires national prefix to be present
+   when matching national-format numbers, unless matching for a region where it
+   is explicitly marked in the metadata that they may be omitted. Applies to
+   leniency level VALID and higher.
+ - Change formatNumberForMobileDialing not to modify the phoneNumber passed in.
+
+* Metadata changes
+ - Emergency numbers added for all remaining countries
+ - Collected data on which numbers we format with a national prefix are
+   commonly written without one and added this
+ - Updates for AR, AT, BH, CZ, GR, IR, KM, LT, MX, PT, SE, SO, UG
+ - Addition of SX (Sint Maarten)
+
 October 19th, 2011: libphonenumber-4.1
 * Code changes
  - Update code and metadata for countries with IDD "8~10" to accept phone

java/src/com/google/i18n/phonenumbers/CountryCodeToRegionCodeMap.java

@@ -38,7 +38,7 @@ public class CountryCodeToRegionCodeMap {
 
     ArrayList<String> listWithRegionCode;
 
-    listWithRegionCode = new ArrayList<String>(24);
+    listWithRegionCode = new ArrayList<String>(25);
     listWithRegionCode.add("US");
     listWithRegionCode.add("AG");
     listWithRegionCode.add("AI");
@@ -58,6 +58,7 @@ public class CountryCodeToRegionCodeMap {
     listWithRegionCode.add("MP");
     listWithRegionCode.add("MS");
     listWithRegionCode.add("PR");
+    listWithRegionCode.add("SX");
     listWithRegionCode.add("TC");
     listWithRegionCode.add("TT");
     listWithRegionCode.add("VC");

java/src/com/google/i18n/phonenumbers/PhoneNumberMatcher.java

@@ -279,6 +279,7 @@ final class PhoneNumberMatcher implements Iterator<PhoneNumberMatch> {
    * combining marks should also return true since we assume they have been added to a preceding
    * Latin character.
    */
+  // @VisibleForTesting
   static boolean isLatinLetter(char letter) {
     // Combining marks are a subset of non-spacing-mark.
     if (!Character.isLetter(letter) && Character.getType(letter) != Character.NON_SPACING_MARK) {
@@ -420,8 +421,14 @@ final class PhoneNumberMatcher implements Iterator<PhoneNumberMatch> {
         }
       }
 
-      PhoneNumber number = phoneUtil.parse(candidate, preferredRegion);
+      PhoneNumber number = phoneUtil.parseAndKeepRawInput(candidate, preferredRegion);
       if (leniency.verify(number, candidate, phoneUtil)) {
+        // We used parseAndKeepRawInput to create this number, but for now we don't return the extra
+        // values parsed. TODO: stop clearing all values here and switch all users over
+        // to using rawInput() rather than the rawString() of PhoneNumberMatch.
+        number.clearCountryCodeSource();
+        number.clearRawInput();
+        number.clearPreferredDomesticCarrierCode();
         return new PhoneNumberMatch(offset, candidate, number);
       }
     } catch (NumberParseException e) {

java/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java

@@ -420,15 +420,18 @@ public class PhoneNumberUtil {
     /**
      * Phone numbers accepted are
      * {@linkplain PhoneNumberUtil#isPossibleNumber(Phonenumber.PhoneNumber) possible} and
-     * {@linkplain PhoneNumberUtil#isValidNumber(Phonenumber.PhoneNumber) valid}.
+     * {@linkplain PhoneNumberUtil#isValidNumber(Phonenumber.PhoneNumber) valid}. Numbers written
+     * in national format must have their national-prefix present if it is usually written for a
+     * number of this type.
      */
     VALID {
       @Override
       boolean verify(PhoneNumber number, String candidate, PhoneNumberUtil util) {
-        if (!util.isValidNumber(number)) {
+        if (!util.isValidNumber(number) ||
+            !containsOnlyValidXChars(number, candidate, util)) {
           return false;
         }
-        return containsOnlyValidXChars(number, candidate, util);
+        return isNationalPrefixPresentIfRequired(number, util);
       }
     },
     /**
@@ -447,7 +450,8 @@ public class PhoneNumberUtil {
       boolean verify(PhoneNumber number, String candidate, PhoneNumberUtil util) {
         if (!util.isValidNumber(number) ||
             !containsOnlyValidXChars(number, candidate, util) ||
-            containsMoreThanOneSlash(candidate)) {
+            containsMoreThanOneSlash(candidate) ||
+            !isNationalPrefixPresentIfRequired(number, util)) {
           return false;
         }
         // TODO: Evaluate how this works for other locales (testing has been
@@ -501,7 +505,8 @@ public class PhoneNumberUtil {
       boolean verify(PhoneNumber number, String candidate, PhoneNumberUtil util) {
         if (!util.isValidNumber(number) ||
             !containsOnlyValidXChars(number, candidate, util) ||
-            containsMoreThanOneSlash(candidate)) {
+            containsMoreThanOneSlash(candidate) ||
+            !isNationalPrefixPresentIfRequired(number, util)) {
           return false;
         }
         // TODO: Evaluate how this works for other locales (testing has been
@@ -591,6 +596,51 @@ public class PhoneNumberUtil {
       return true;
     }
 
+    private static boolean isNationalPrefixPresentIfRequired(
+        PhoneNumber number, PhoneNumberUtil util) {
+      // First, check how we deduced the country code. If it was written in international format,
+      // then the national prefix is not required.
+      if (number.getCountryCodeSource() != CountryCodeSource.FROM_DEFAULT_COUNTRY) {
+        return true;
+      }
+      String phoneNumberRegion =
+          util.getRegionCodeForCountryCode(number.getCountryCode());
+      PhoneMetadata metadata = util.getMetadataForRegion(phoneNumberRegion);
+      if (metadata == null) {
+        return true;
+      }
+      // Check if a national prefix should be present when formatting this number.
+      String nationalNumber = util.getNationalSignificantNumber(number);
+      NumberFormat formatRule =
+          util.chooseFormattingPatternForNumber(metadata.numberFormats(), nationalNumber);
+      // To do this, we check that a national prefix formatting rule was present and that it wasn't
+      // just the first-group symbol ($1) with punctuation.
+      if ((formatRule != null) && formatRule.getNationalPrefixFormattingRule().length() > 0) {
+        if (formatRule.isNationalPrefixOptionalWhenFormatting()) {
+          // The national-prefix is optional in these cases, so we don't need to check if it was
+          // present.
+          return true;
+        }
+        // Remove the first-group symbol.
+        String candidateNationalPrefixRule = formatRule.getNationalPrefixFormattingRule();
+        // We assume that the first-group symbol will never be _before_ the national prefix.
+        candidateNationalPrefixRule =
+            candidateNationalPrefixRule.substring(0, candidateNationalPrefixRule.indexOf("$1"));
+        candidateNationalPrefixRule = util.normalizeDigitsOnly(candidateNationalPrefixRule);
+        if (candidateNationalPrefixRule.length() == 0) {
+          // National Prefix not needed for this number.
+          return true;
+        }
+        // Normalize the remainder.
+        String rawInputCopy = util.normalizeDigitsOnly(number.getRawInput());
+        StringBuilder rawInput = new StringBuilder(rawInputCopy);
+        // Check if we found a national prefix and/or carrier code at the start of the raw input,
+        // and return the result.
+        return util.maybeStripNationalPrefixAndCarrierCode(rawInput, metadata, null);
+      }
+      return true;
+    }
+
     /** Returns true if {@code number} is a verified number according to this leniency. */
     abstract boolean verify(PhoneNumber number, String candidate, PhoneNumberUtil util);
   }
@@ -1476,6 +1526,22 @@ public class PhoneNumberUtil {
     return formattedNationalNumber;
   }
 
+  private NumberFormat chooseFormattingPatternForNumber(List<NumberFormat> availableFormats,
+                                                        String nationalNumber) {
+    for (NumberFormat numFormat : availableFormats) {
+      int size = numFormat.leadingDigitsPatternSize();
+      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);
+        if (m.matches()) {
+          return numFormat;
+        }
+      }
+    }
+    return null;
+  }
+
   // Simple wrapper of formatAccordingToFormats for the common case of no carrier code.
   private String formatAccordingToFormats(String nationalNumber,
                                           List<NumberFormat> availableFormats,
@@ -1489,44 +1555,37 @@ public class PhoneNumberUtil {
                                           List<NumberFormat> availableFormats,
                                           PhoneNumberFormat numberFormat,
                                           String carrierCode) {
-    for (NumberFormat numFormat : availableFormats) {
-      int size = numFormat.leadingDigitsPatternSize();
-      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);
-        if (m.matches()) {
-          String numberFormatRule = numFormat.getFormat();
-          if (numberFormat == PhoneNumberFormat.NATIONAL &&
-              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);
-            return m.replaceAll(numberFormatRule);
-          } else {
-            // Use the national prefix formatting rule instead.
-            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);
-            }
-          }
-        }
+    NumberFormat numFormat = chooseFormattingPatternForNumber(availableFormats, nationalNumber);
+    if (numFormat == null) {
+      // If no pattern above is matched, we format the number as a whole.
+      return nationalNumber;
+    }
+    String numberFormatRule = numFormat.getFormat();
+    Matcher m = regexCache.getPatternForRegex(numFormat.getPattern()).matcher(nationalNumber);
+    if (numberFormat == PhoneNumberFormat.NATIONAL &&
+        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);
+      return m.replaceAll(numberFormatRule);
+    } else {
+      // Use the national prefix formatting rule instead.
+      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;
   }
 
   /**
@@ -2131,7 +2190,8 @@ public class PhoneNumberUtil {
         PhoneNumberDesc generalDesc = defaultRegionMetadata.getGeneralDesc();
         Pattern validNumberPattern =
             regexCache.getPatternForRegex(generalDesc.getNationalNumberPattern());
-        maybeStripNationalPrefixAndCarrierCode(potentialNationalNumber, defaultRegionMetadata);
+        maybeStripNationalPrefixAndCarrierCode(
+            potentialNationalNumber, defaultRegionMetadata, null /* Don't need the carrier code */);
         Pattern possibleNumberPattern =
             regexCache.getPatternForRegex(generalDesc.getPossibleNumberPattern());
         // If the number was not valid before but is valid now, or if it was too long before, we
@@ -2219,16 +2279,17 @@ public class PhoneNumberUtil {
    * @param number  the normalized telephone number that we wish to strip any national
    *     dialing prefix from
    * @param metadata  the metadata for the region that we think this number is from
-   * @return the carrier code extracted if it is present, otherwise return an empty string.
+   * @param carrierCode  a place to insert the carrier code if one is extracted
+   * @return true if a national prefix or carrier code (or both) could be extracted.
    */
   // @VisibleForTesting
-  String maybeStripNationalPrefixAndCarrierCode(StringBuilder number, PhoneMetadata metadata) {
-    String carrierCode = "";
+  boolean maybeStripNationalPrefixAndCarrierCode(
+      StringBuilder number, PhoneMetadata metadata, StringBuilder carrierCode) {
     int numberLength = number.length();
     String possibleNationalPrefix = metadata.getNationalPrefixForParsing();
     if (numberLength == 0 || possibleNationalPrefix.length() == 0) {
       // Early return for numbers of zero length.
-      return "";
+      return false;
     }
     // Attempt to parse the first digits as a national prefix.
     Matcher prefixMatcher = regexCache.getPatternForRegex(possibleNationalPrefix).matcher(number);
@@ -2247,12 +2308,13 @@ public class PhoneNumberUtil {
         // If the original number was viable, and the resultant number is not, we return.
         if (isViableOriginalNumber &&
             !nationalNumberRule.matcher(number.substring(prefixMatcher.end())).matches()) {
-          return "";
+          return false;
         }
-        if (numOfGroups > 0 && prefixMatcher.group(numOfGroups) != null) {
-          carrierCode = prefixMatcher.group(1);
+        if (carrierCode != null && numOfGroups > 0 && prefixMatcher.group(numOfGroups) != null) {
+          carrierCode.append(prefixMatcher.group(1));
         }
         number.delete(0, prefixMatcher.end());
+        return true;
       } else {
         // Check that the resultant number is still viable. If not, return. Check this by copying
         // the string buffer and making the transformation on the copy first.
@@ -2260,15 +2322,16 @@ public class PhoneNumberUtil {
         transformedNumber.replace(0, numberLength, prefixMatcher.replaceFirst(transformRule));
         if (isViableOriginalNumber &&
             !nationalNumberRule.matcher(transformedNumber.toString()).matches()) {
-          return "";
+          return false;
         }
-        if (numOfGroups > 1) {
-          carrierCode = prefixMatcher.group(1);
+        if (carrierCode != null && numOfGroups > 1) {
+          carrierCode.append(prefixMatcher.group(1));
         }
         number.replace(0, number.length(), transformedNumber.toString());
+        return true;
       }
     }
-    return carrierCode;
+    return false;
   }
 
   /**
@@ -2511,10 +2574,10 @@ public class PhoneNumberUtil {
                                      "The string supplied is too short to be a phone number.");
     }
     if (regionMetadata != null) {
-      String carrierCode =
-          maybeStripNationalPrefixAndCarrierCode(normalizedNationalNumber, regionMetadata);
+      StringBuilder carrierCode = new StringBuilder();
+      maybeStripNationalPrefixAndCarrierCode(normalizedNationalNumber, regionMetadata, carrierCode);
       if (keepRawInput) {
-        phoneNumber.setPreferredDomesticCarrierCode(carrierCode);
+        phoneNumber.setPreferredDomesticCarrierCode(carrierCode.toString());
       }
     }
     int lengthOfNationalNumber = normalizedNationalNumber.length();

java/src/com/google/i18n/phonenumbers/Phonemetadata.java

@@ -102,6 +102,19 @@ public final class Phonemetadata {
       return this;
     }
 
+    // optional bool national_prefix_optional_when_formatting = 6;
+    private boolean hasNationalPrefixOptionalWhenFormatting;
+    private boolean nationalPrefixOptionalWhenFormatting_ = false;
+    public boolean hasNationalPrefixOptionalWhenFormatting() {
+      return hasNationalPrefixOptionalWhenFormatting; }
+    public boolean isNationalPrefixOptionalWhenFormatting() {
+      return nationalPrefixOptionalWhenFormatting_; }
+    public NumberFormat setNationalPrefixOptionalWhenFormatting(boolean value) {
+      hasNationalPrefixOptionalWhenFormatting = true;
+      nationalPrefixOptionalWhenFormatting_ = value;
+      return this;
+    }
+
     // optional string domestic_carrier_code_formatting_rule = 5;
     private boolean hasDomesticCarrierCodeFormattingRule;
     private String domesticCarrierCodeFormattingRule_ = "";
@@ -132,6 +145,7 @@ public final class Phonemetadata {
       if (other.hasDomesticCarrierCodeFormattingRule()) {
         setDomesticCarrierCodeFormattingRule(other.getDomesticCarrierCodeFormattingRule());
       }
+      setNationalPrefixOptionalWhenFormatting(other.isNationalPrefixOptionalWhenFormatting());
       return this;
     }
 
@@ -152,6 +166,7 @@ public final class Phonemetadata {
       if (hasDomesticCarrierCodeFormattingRule) {
         objectOutput.writeUTF(domesticCarrierCodeFormattingRule_);
       }
+      objectOutput.writeBoolean(nationalPrefixOptionalWhenFormatting_);
     }
 
     public void readExternal(ObjectInput objectInput) throws IOException {
@@ -167,6 +182,7 @@ public final class Phonemetadata {
       if (objectInput.readBoolean()) {
         setDomesticCarrierCodeFormattingRule(objectInput.readUTF());
       }
+      setNationalPrefixOptionalWhenFormatting(objectInput.readBoolean());
     }
   }
 

java/src/com/google/i18n/phonenumbers/ShortNumberUtil.java

@@ -16,6 +16,7 @@
 
 package com.google.i18n.phonenumbers;
 
+import com.google.i18n.phonenumbers.Phonemetadata.PhoneMetadata;
 import com.google.i18n.phonenumbers.Phonemetadata.PhoneNumberDesc;
 
 import java.util.regex.Pattern;
@@ -51,6 +52,25 @@ public class ShortNumberUtil {
    * @return  if the number might be used to connect to an emergency service in the given region.
    */
   public boolean connectsToEmergencyNumber(String number, String regionCode) {
+    return matchesEmergencyNumberHelper(number, regionCode, true /* allows prefix match */);
+  }
+
+  /**
+   * Returns true if the number exactly matches an emergency service number in the given region.
+   *
+   * This method takes into account cases where the number might contain formatting, but doesn't
+   * allow additional digits to be appended.
+   *
+   * @param number  the phone number to test
+   * @param regionCode  the region where the phone number is being dialed
+   * @return  if the number exactly matches an emergency services number in the given region.
+   */
+  public boolean isEmergencyNumber(String number, String regionCode) {
+    return matchesEmergencyNumberHelper(number, regionCode, false /* doesn't allow prefix match */);
+  }
+
+  private boolean matchesEmergencyNumberHelper(String number, String regionCode,
+      boolean allowPrefixMatch) {
     number = PhoneNumberUtil.extractPossibleNumber(number);
     if (PhoneNumberUtil.PLUS_CHARS_PATTERN.matcher(number).lookingAt()) {
       // Returns false if the number starts with a plus sign. We don't believe dialing the country
@@ -58,20 +78,17 @@ public class ShortNumberUtil {
       // add additional logic here to handle it.
       return false;
     }
-    String normalizedNumber = PhoneNumberUtil.normalizeDigitsOnly(number);
-    PhoneNumberDesc emergencyNumberDesc = phoneUtil.getMetadataForRegion(regionCode).getEmergency();
-    Pattern emergencyNumberPattern =
-        Pattern.compile(emergencyNumberDesc.getNationalNumberPattern());
-    if (regionCode.equals("BR")) {
-      // This is to prevent Brazilian local numbers which start with 911 being incorrectly
-      // classified as emergency numbers. In Brazil, it is impossible to append additional digits to
-      // an emergency number to dial the number.
-      if (!emergencyNumberPattern.matcher(normalizedNumber).matches()) {
-        return false;
-      }
+    PhoneMetadata metadata = phoneUtil.getMetadataForRegion(regionCode);
+    if (metadata == null || !metadata.hasEmergency()) {
+      return false;
     }
-
-    // Check the prefix against possible emergency numbers for this region.
-    return emergencyNumberPattern.matcher(normalizedNumber).lookingAt();
+    Pattern emergencyNumberPattern =
+        Pattern.compile(metadata.getEmergency().getNationalNumberPattern());
+    String normalizedNumber = PhoneNumberUtil.normalizeDigitsOnly(number);
+    // In Brazil, it is impossible to append additional digits to an emergency number to dial the
+    // number.
+    return (!allowPrefixMatch || regionCode.equals("BR"))
+        ? emergencyNumberPattern.matcher(normalizedNumber).matches()
+        : emergencyNumberPattern.matcher(normalizedNumber).lookingAt();
   }
 }