Add isCarrierSpecificForRegion() API in ShortNumberInfo class. (#1504)

cpp/src/phonenumbers/shortnumberinfo.cc

@@ -381,5 +381,19 @@ bool ShortNumberInfo::IsCarrierSpecific(const PhoneNumber& number) const {
              phone_metadata->carrier_specific());
 }
 
+bool ShortNumberInfo::IsCarrierSpecificForRegion(const PhoneNumber& number,
+    const string& region_dialing_from) const {
+  if (!RegionDialingFromMatchesNumber(number, region_dialing_from)) {
+    return false;
+  }
+  string national_number;
+  phone_util_.GetNationalSignificantNumber(number, &national_number);
+  const PhoneMetadata* phone_metadata =
+      GetMetadataForRegion(region_dialing_from);
+  return phone_metadata &&
+         MatchesPossibleNumberAndNationalNumber(*matcher_api_, national_number,
+             phone_metadata->carrier_specific());
+}
+
 }  // namespace phonenumbers
 }  // namespace i18n

cpp/src/phonenumbers/shortnumberinfo.h

@@ -144,11 +144,24 @@ class ShortNumberInfo {
                          const string& region_code) const;
 
   // Given a valid short number, determines whether it is carrier-specific
-  // (however, nothing is implied about its validity). If it is important that
-  // the number is valid, then its validity must first be checked using
-  // IsValidShortNumber or IsValidShortNumberForRegion.
+  // (however, nothing is implied about its validity). Carrier-specific numbers
+  // may connect to a different end-point, or not connect at all, depending on
+  // the user's carrier. If it is important that the number is valid, then its
+  // validity must first be checked using IsValidShortNumber or
+  // IsValidShortNumberForRegion.
   bool IsCarrierSpecific(const PhoneNumber& number) const;
 
+  // Given a valid short number, determines whether it is carrier-specific when
+  // dialed from the given region (however, nothing is implied about its
+  // validity). Carrier-specific numbers may connect to a different end-point,
+  // or not connect at all, depending on the user's carrier. If it is important
+  // that the number is valid, then its validity must first be checked using
+  // IsValidShortNumber or IsValidShortNumberForRegion. Returns false if the
+  // number doesn't match the region provided.
+  bool IsCarrierSpecificForRegion(
+      const PhoneNumber& number,
+      const string& region_dialing_from) const;
+
  private:
   const PhoneNumberUtil& phone_util_;
   const scoped_ptr<const MatcherApi> matcher_api_;

cpp/test/phonenumbers/shortnumberinfo_test.cc

@@ -97,6 +97,32 @@ TEST_F(ShortNumberInfoTest, IsValidShortNumber) {
   EXPECT_TRUE(short_info_.IsValidShortNumber(shared_number));
 }
 
+TEST_F(ShortNumberInfoTest, IsCarrierSpecific) {
+  PhoneNumber carrier_specific_number;
+  carrier_specific_number.set_country_code(1);
+  carrier_specific_number.set_national_number(33669ULL);
+  EXPECT_TRUE(short_info_.IsCarrierSpecific(carrier_specific_number));
+  EXPECT_TRUE(short_info_.IsCarrierSpecificForRegion(
+      ParseNumberForTesting("33669", RegionCode::US()), RegionCode::US()));
+
+  PhoneNumber not_carrier_specific_number;
+  not_carrier_specific_number.set_country_code(1);
+  not_carrier_specific_number.set_national_number(911ULL);
+  EXPECT_FALSE(short_info_.IsCarrierSpecific(not_carrier_specific_number));
+  EXPECT_FALSE(short_info_.IsCarrierSpecificForRegion(
+      ParseNumberForTesting("911", RegionCode::US()), RegionCode::US()));
+
+  PhoneNumber carrier_specific_number_for_some_region;
+  carrier_specific_number_for_some_region.set_country_code(1);
+  carrier_specific_number_for_some_region.set_national_number(211ULL);
+  EXPECT_TRUE(short_info_.IsCarrierSpecific(
+      carrier_specific_number_for_some_region));
+  EXPECT_TRUE(short_info_.IsCarrierSpecificForRegion(
+      carrier_specific_number_for_some_region, RegionCode::US()));
+  EXPECT_FALSE(short_info_.IsCarrierSpecificForRegion(
+      carrier_specific_number_for_some_region, RegionCode::BB()));
+}
+
 TEST_F(ShortNumberInfoTest, GetExpectedCost) {
   uint64 national_number;
   const string& premium_rate_example =

java/libphonenumber/src/com/google/i18n/phonenumbers/ShortNumberInfo.java

@@ -456,8 +456,9 @@ public class ShortNumberInfo {
 
   /**
    * Given a valid short number, determines whether it is carrier-specific (however, nothing is
-   * implied about its validity). If it is important that the number is valid, then its validity
-   * must first be checked using {@link #isValidShortNumber} or
+   * implied about its validity). Carrier-specific numbers may connect to a different end-point, or
+   * not connect at all, depending on the user's carrier. If it is important that the number is
+   * valid, then its validity must first be checked using {@link #isValidShortNumber} or
    * {@link #isValidShortNumberForRegion}.
    *
    * @param number the valid short number to check
@@ -474,6 +475,31 @@ public class ShortNumberInfo {
                 phoneMetadata.getCarrierSpecific()));
   }
 
+  /**
+   * Given a valid short number, determines whether it is carrier-specific when dialed from the
+   * given region (however, nothing is implied about its validity). Carrier-specific numbers may
+   * connect to a different end-point, or not connect at all, depending on the user's carrier. If
+   * it is important that the number is valid, then its validity must first be checked using
+   * {@link #isValidShortNumber} or {@link #isValidShortNumberForRegion}. Returns false if the
+   * number doesn't match the region provided.
+   *
+   * @param number  the valid short number to check
+   * @param regionDialingFrom  the region from which the number is dialed
+   * @return  whether the short number is carrier-specific (assuming the input was a valid short
+   *     number)
+   */
+  public boolean isCarrierSpecificForRegion(PhoneNumber number, String regionDialingFrom) {
+    if (!regionDialingFromMatchesNumber(number, regionDialingFrom)) {
+      return false;
+    }
+    String nationalNumber = getNationalSignificantNumber(number);
+    PhoneMetadata phoneMetadata =
+        MetadataManager.getShortNumberMetadataForRegion(regionDialingFrom);
+    return (phoneMetadata != null)
+        && (matchesPossibleNumberAndNationalNumber(nationalNumber,
+                phoneMetadata.getCarrierSpecific()));
+  }
+
   /**
    * Gets the national significant number of the a phone number. Note a national significant number
    * doesn't contain a national prefix or any formatting.

java/libphonenumber/test/com/google/i18n/phonenumbers/ExampleNumbersTest.java

@@ -266,7 +266,7 @@ public class ExampleNumbersTest extends TestCase {
         String exampleNumber = desc.getExampleNumber();
         PhoneNumber carrierSpecificNumber = phoneNumberUtil.parse(exampleNumber, regionCode);
         if (!shortNumberInfo.isPossibleShortNumberForRegion(carrierSpecificNumber, regionCode)
-            || !shortNumberInfo.isCarrierSpecific(carrierSpecificNumber)) {
+            || !shortNumberInfo.isCarrierSpecificForRegion(carrierSpecificNumber, regionCode)) {
           wrongTagCounter++;
           logger.log(Level.SEVERE, "Carrier-specific test failed for " + regionCode);
         }

java/libphonenumber/test/com/google/i18n/phonenumbers/ShortNumberInfoTest.java

@@ -57,6 +57,28 @@ public class ShortNumberInfoTest extends TestMetadataTestCase {
         new PhoneNumber().setCountryCode(44).setNationalNumber(18001L)));
   }
 
+  public void testIsCarrierSpecific() {
+    PhoneNumber carrierSpecificNumber = new PhoneNumber();
+    carrierSpecificNumber.setCountryCode(1).setNationalNumber(33669L);
+    assertTrue(shortInfo.isCarrierSpecific(carrierSpecificNumber));
+    assertTrue(
+        shortInfo.isCarrierSpecificForRegion(parse("33669", RegionCode.US), RegionCode.US));
+
+    PhoneNumber notCarrierSpecificNumber = new PhoneNumber();
+    notCarrierSpecificNumber.setCountryCode(1).setNationalNumber(911L);
+    assertFalse(shortInfo.isCarrierSpecific(notCarrierSpecificNumber));
+    assertFalse(
+        shortInfo.isCarrierSpecificForRegion(parse("911", RegionCode.US), RegionCode.US));
+
+    PhoneNumber carrierSpecificNumberForSomeRegion = new PhoneNumber();
+    carrierSpecificNumberForSomeRegion.setCountryCode(1).setNationalNumber(211L);
+    assertTrue(shortInfo.isCarrierSpecific(carrierSpecificNumberForSomeRegion));
+    assertTrue(
+        shortInfo.isCarrierSpecificForRegion(carrierSpecificNumberForSomeRegion, RegionCode.US));
+    assertFalse(
+        shortInfo.isCarrierSpecificForRegion(carrierSpecificNumberForSomeRegion, RegionCode.BB));
+  }
+
   public void testGetExpectedCost() {
     String premiumRateExample = shortInfo.getExampleShortNumberForCost(RegionCode.FR,
         ShortNumberInfo.ShortNumberCost.PREMIUM_RATE);

java/pending_code_changes.txt

@@ -1 +1,4 @@
-
+Code changes:
+ - Introduced new isCarrierSpecificForRegion() API in ShortNumberInfo class.
+   This determines whether the provided short code is carrier-specific or
+   not when dialed from the given region.