isPossibleForType[WithReason] and getSupportedTypesFor* (#1650)

cpp/src/phonenumbers/phonenumberutil.cc

@@ -262,24 +262,112 @@ void NormalizeHelper(const std::map<char32, char>& normalization_replacements,
   number->assign(normalized_number);
 }
 
-// Helper method to check a number against possible lengths for this number, and
-// determine whether it matches, or is too short or too long. Currently, if a
-// number pattern suggests that numbers of length 7 and 10 are possible, and a
-// number in between these possible lengths is entered, such as of length 8,
-// this will return TOO_LONG.
+// Returns true if there is any possible number data set for a particular
+// PhoneNumberDesc.
+bool DescHasPossibleNumberData(const PhoneNumberDesc& desc) {
+  // If this is empty, it means numbers of this type inherit from the "general
+  // desc" -> the value "-1" means that no numbers exist for this type.
+  return desc.possible_length_size() != 1 || desc.possible_length(0) != -1;
+}
+
+// Returns true if there is any data set for a particular PhoneNumberDesc.
+bool DescHasData(const PhoneNumberDesc& desc) {
+  // Checking most properties since we don't know what's present, since a custom
+  // build may have stripped just one of them (e.g. USE_METADATA_LITE strips
+  // exampleNumber). We don't bother checking the PossibleLengthsLocalOnly,
+  // since if this is the only thing that's present we don't really support the
+  // type at all: no type-specific methods will work with only this data.
+  return desc.has_example_number() || DescHasPossibleNumberData(desc) ||
+         (desc.has_national_number_pattern() &&
+          !(desc.national_number_pattern() == "NA"));
+}
+
+// Returns the types we have metadata for based on the PhoneMetadata object
+// passed in.
+void GetSupportedTypesForMetadata(
+    const PhoneMetadata& metadata,
+    std::set<PhoneNumberUtil::PhoneNumberType>* types) {
+  DCHECK(types);
+  for (int i = 0; i < static_cast<int>(PhoneNumberUtil::UNKNOWN); ++i) {
+    PhoneNumberUtil::PhoneNumberType type =
+        static_cast<PhoneNumberUtil::PhoneNumberType>(i);
+    if (type == PhoneNumberUtil::FIXED_LINE_OR_MOBILE ||
+        type == PhoneNumberUtil::UNKNOWN) {
+      // Never return FIXED_LINE_OR_MOBILE (it is a convenience type, and
+      // represents that a particular number type can't be
+      // determined) or UNKNOWN (the non-type).
+      continue;
+    }
+    if (DescHasData(*GetNumberDescByType(metadata, type))) {
+      types->insert(type);
+    }
+  }
+}
+
+// Helper method to check a number against possible lengths for this number
+// type, and determine whether it matches, or is too short or too long.
+// Currently, if a number pattern suggests that numbers of length 7 and 10 are
+// possible, and a number in between these possible lengths is entered, such as
+// of length 8, this will return TOO_LONG.
 PhoneNumberUtil::ValidationResult TestNumberLength(
-    const string& number, const PhoneNumberDesc& phone_number_desc) {
-  RepeatedField<int> possible_lengths = phone_number_desc.possible_length();
+    const string& number, const PhoneMetadata& metadata,
+    PhoneNumberUtil::PhoneNumberType type) {
+  const PhoneNumberDesc* desc_for_type = GetNumberDescByType(metadata, type);
+  // There should always be "possibleLengths" set for every element. This is
+  // declared in the XML schema which is verified by
+  // PhoneNumberMetadataSchemaTest. For size efficiency, where a
+  // sub-description (e.g. fixed-line) has the same possibleLengths as the
+  // parent, this is missing, so we fall back to the general desc (where no
+  // numbers of the type exist at all, there is one possible length (-1) which
+  // is guaranteed not to match the length of any real phone number).
+  RepeatedField<int> possible_lengths =
+      desc_for_type->possible_length_size() == 0
+          ? metadata.general_desc().possible_length()
+          : desc_for_type->possible_length();
   RepeatedField<int> local_lengths =
-      phone_number_desc.possible_length_local_only();
+      desc_for_type->possible_length_local_only();
+  if (type == PhoneNumberUtil::FIXED_LINE_OR_MOBILE) {
+    const PhoneNumberDesc* fixed_line_desc =
+        GetNumberDescByType(metadata, PhoneNumberUtil::FIXED_LINE);
+    if (!DescHasPossibleNumberData(*fixed_line_desc)) {
+      // The rare case has been encountered where no fixedLine data is available
+      // (true for some non-geographical entities), so we just check mobile.
+      return TestNumberLength(number, metadata, PhoneNumberUtil::MOBILE);
+    } else {
+      const PhoneNumberDesc* mobile_desc =
+          GetNumberDescByType(metadata, PhoneNumberUtil::MOBILE);
+      if (DescHasPossibleNumberData(*mobile_desc)) {
+        // Merge the mobile data in if there was any. Note that when adding the
+        // possible lengths from mobile, we have to again check they aren't
+        // empty since if they are this indicates they are the same as the
+        // general desc and should be obtained from there.
+        possible_lengths.MergeFrom(
+            mobile_desc->possible_length_size() == 0
+            ? metadata.general_desc().possible_length()
+            : mobile_desc->possible_length());
+        std::sort(possible_lengths.begin(), possible_lengths.end());
+
+        if (local_lengths.size() == 0) {
+          local_lengths = mobile_desc->possible_length_local_only();
+        } else {
+          local_lengths.MergeFrom(mobile_desc->possible_length_local_only());
+          std::sort(local_lengths.begin(), local_lengths.end());
+        }
+      }
+    }
+  }
+
+  // If the type is not suported at all (indicated by the possible lengths
+  // containing -1 at this point) we return invalid length.
+  if (possible_lengths.Get(0) == -1) {
+    return PhoneNumberUtil::INVALID_LENGTH;
+  }
+
   int actual_length = number.length();
   if (std::find(local_lengths.begin(), local_lengths.end(), actual_length) !=
       local_lengths.end()) {
     return PhoneNumberUtil::IS_POSSIBLE;
   }
-  // There should always be "possibleLengths" set for every element. This will
-  // be a build-time check once ShortNumberMetadata.xml is migrated to contain
-  // this information as well.
   int minimum_length = possible_lengths.Get(0);
   if (minimum_length == actual_length) {
     return PhoneNumberUtil::IS_POSSIBLE;
@@ -300,6 +388,16 @@ PhoneNumberUtil::ValidationResult TestNumberLength(
              : PhoneNumberUtil::TOO_LONG;
 }
 
+// Helper method to check a number against possible lengths for this region,
+// based on the metadata being passed in, and determine whether it matches, or
+// is too short or too long. Currently, if a number pattern suggests that
+// numbers of length 7 and 10 are possible, and a number in between these
+// possible lengths is entered, such as of length 8, this will return TOO_LONG.
+PhoneNumberUtil::ValidationResult TestNumberLength(
+    const string& number, const PhoneMetadata& metadata) {
+  return TestNumberLength(number, metadata, PhoneNumberUtil::UNKNOWN);
+}
+
 // Returns a new phone number containing only the fields needed to uniquely
 // identify a phone number, rather than any fields that capture the context in
 // which the phone number was created.
@@ -723,6 +821,33 @@ void PhoneNumberUtil::GetSupportedGlobalNetworkCallingCodes(
   }
 }
 
+void PhoneNumberUtil::GetSupportedTypesForRegion(
+    const string& region_code,
+    std::set<PhoneNumberType>* types) const {
+  DCHECK(types);
+  if (!IsValidRegionCode(region_code)) {
+    LOG(WARNING) << "Invalid or unknown region code provided: " << region_code;
+    return;
+  }
+  const PhoneMetadata* metadata = GetMetadataForRegion(region_code);
+  GetSupportedTypesForMetadata(*metadata, types);
+}
+
+void PhoneNumberUtil::GetSupportedTypesForNonGeoEntity(
+    int country_calling_code,
+    std::set<PhoneNumberType>* types) const {
+  DCHECK(types);
+  const PhoneMetadata* metadata =
+      GetMetadataForNonGeographicalRegion(country_calling_code);
+  if (metadata == NULL) {
+    LOG(WARNING) << "Unknown country calling code for a non-geographical "
+                 << "entity provided: "
+                 << country_calling_code;
+    return;
+  }
+  GetSupportedTypesForMetadata(*metadata, types);
+}
+
 // Public wrapper function to get a PhoneNumberUtil instance with the default
 // metadata file.
 // static
@@ -1074,8 +1199,7 @@ void PhoneNumberUtil::FormatNumberForMobileDialing(
       string national_number;
       GetNationalSignificantNumber(number_no_extension, &national_number);
       if (CanBeInternationallyDialled(number_no_extension) &&
-          TestNumberLength(national_number, region_metadata->general_desc()) !=
-              TOO_SHORT) {
+          TestNumberLength(national_number, *region_metadata) != TOO_SHORT) {
         Format(number_no_extension, INTERNATIONAL, formatted_number);
       } else {
         Format(number_no_extension, NATIONAL, formatted_number);
@@ -1611,11 +1735,11 @@ void PhoneNumberUtil::GetRegionCodesForCountryCallingCode(
   // locate the pair with the same country_code in the sorted vector.
   IntRegionsPair target_pair;
   target_pair.first = country_calling_code;
-  typedef vector<IntRegionsPair>::const_iterator ConstIterator;
-  pair<ConstIterator, ConstIterator> range = equal_range(
-      country_calling_code_to_region_code_map_->begin(),
-      country_calling_code_to_region_code_map_->end(),
-      target_pair, OrderByFirst());
+  typedef std::vector<IntRegionsPair>::const_iterator ConstIterator;
+  std::pair<ConstIterator, ConstIterator> range =
+      std::equal_range(country_calling_code_to_region_code_map_->begin(),
+                       country_calling_code_to_region_code_map_->end(),
+                       target_pair, OrderByFirst());
   if (range.first != range.second) {
     region_codes->insert(region_codes->begin(),
                          range.first->second->begin(),
@@ -2044,8 +2168,8 @@ PhoneNumberUtil::ErrorType PhoneNumberUtil::ParseHelper(
     // and carrier code be long enough to be a possible length for the region.
     // Otherwise, we don't do the stripping, since the original number could be
     // a valid short number.
-    if (TestNumberLength(potential_national_number,
-                         country_metadata->general_desc()) != TOO_SHORT) {
+    if (TestNumberLength(potential_national_number, *country_metadata) !=
+        TOO_SHORT) {
       normalized_national_number.assign(potential_national_number);
       if (keep_raw_input && !carrier_code.empty()) {
         temp_number.set_preferred_domestic_carrier_code(carrier_code);
@@ -2125,6 +2249,11 @@ bool PhoneNumberUtil::IsPossibleNumber(const PhoneNumber& number) const {
   return IsPossibleNumberWithReason(number) == IS_POSSIBLE;
 }
 
+bool PhoneNumberUtil::IsPossibleNumberForType(
+    const PhoneNumber& number, const PhoneNumberType type) const {
+  return IsPossibleNumberForTypeWithReason(number, type) == IS_POSSIBLE;
+}
+
 bool PhoneNumberUtil::IsPossibleNumberForString(
     const string& number,
     const string& region_dialing_from) const {
@@ -2138,14 +2267,23 @@ bool PhoneNumberUtil::IsPossibleNumberForString(
 
 PhoneNumberUtil::ValidationResult PhoneNumberUtil::IsPossibleNumberWithReason(
     const PhoneNumber& number) const {
+  return IsPossibleNumberForTypeWithReason(number, PhoneNumberUtil::UNKNOWN);
+}
+
+PhoneNumberUtil::ValidationResult
+PhoneNumberUtil::IsPossibleNumberForTypeWithReason(const PhoneNumber& number,
+                                                   PhoneNumberType type) const {
   string national_number;
   GetNationalSignificantNumber(number, &national_number);
   int country_code = number.country_code();
-  // Note: For Russian Fed and NANPA numbers, we just use the rules from the
-  // default region (US or Russia) since the GetRegionCodeForNumber will not
-  // work if the number is possible but not valid. This would need to be
-  // revisited if the possible number pattern ever differed between various
-  // regions within those plans.
+  // Note: For regions that share a country calling code, like NANPA numbers, we
+  // just use the rules from the default region (US in this case) since the
+  // GetRegionCodeForNumber will not work if the number is possible but not
+  // valid. There is in fact one country calling code (290) where the possible
+  // number pattern differs between various regions (Saint Helena and Tristan da
+  // Cuñha), but this is handled by putting all possible lengths for any country
+  // with this country calling code in the metadata for the default region in
+  // this case.
   if (!HasValidCountryCallingCode(country_code)) {
     return INVALID_COUNTRY_CODE;
   }
@@ -2154,7 +2292,7 @@ PhoneNumberUtil::ValidationResult PhoneNumberUtil::IsPossibleNumberWithReason(
   // Metadata cannot be NULL because the country calling code is valid.
   const PhoneMetadata* metadata =
       GetMetadataForRegionOrCallingCode(country_code, region_code);
-  return TestNumberLength(national_number, metadata->general_desc());
+  return TestNumberLength(national_number, *metadata, type);
 }
 
 bool PhoneNumberUtil::TruncateTooLongNumber(PhoneNumber* number) const {
@@ -2794,7 +2932,8 @@ PhoneNumberUtil::ErrorType PhoneNumberUtil::MaybeExtractCountryCode(
       // be a better result and keep that instead.
       if ((!valid_number_pattern.FullMatch(*national_number) &&
            valid_number_pattern.FullMatch(potential_national_number)) ||
-           TestNumberLength(*national_number, general_num_desc) == TOO_LONG) {
+          TestNumberLength(*national_number, *default_region_metadata) ==
+              TOO_LONG) {
         national_number->assign(potential_national_number);
         if (keep_raw_input) {
           phone_number->set_country_code_source(

cpp/src/phonenumbers/phonenumberutil.h

@@ -159,19 +159,47 @@ class PhoneNumberUtil : public Singleton<PhoneNumberUtil> {
     // The number is longer than the shortest valid numbers for this region,
     // shorter than the longest valid numbers for this region, and does not
     // itself have a number length that matches valid numbers for this region.
+    // This can also be returned in the case where
+    // IsPossibleNumberForTypeWithReason was called, and there are no numbers of
+    // this type at all for this region.
     INVALID_LENGTH,
     // The number is longer than all valid numbers for this region.
     TOO_LONG,
   };
 
-  // Convenience method to get a list of what regions the library has metadata
-  // for.
-  void GetSupportedRegions(set<string>* regions) const;
+  // Returns all regions the library has metadata for.
+  // @returns an unordered set of the two-letter region codes for every
+  // geographical region the library supports
+  void GetSupportedRegions(
+      std::set<string>* regions) const;
 
-  // Convenience method to get a list of what global network calling codes the
-  // library has metadata for.
+  // Returns all global network calling codes the library has metadata for.
+  // @returns an unordered set of the country calling codes for every
+  // non-geographical entity the library supports
   void GetSupportedGlobalNetworkCallingCodes(
-      set<int>* calling_codes) const;
+      std::set<int>* calling_codes) const;
+
+  // Returns the types for a given region which the library has metadata for.
+  // Will not include FIXED_LINE_OR_MOBILE (if numbers for this non-geographical
+  // entity could be classified as FIXED_LINE_OR_MOBILE, both FIXED_LINE and
+  // MOBILE would be present) and UNKNOWN.
+  //
+  // No types will be returned for invalid or unknown region codes.
+  void GetSupportedTypesForRegion(
+      const string& region_code,
+      std::set<PhoneNumberType>* types) const;
+
+  // Returns the types for a country-code belonging to a non-geographical entity
+  // which the library has metadata for. Will not include FIXED_LINE_OR_MOBILE
+  // (instead both FIXED_LINE and FIXED_LINE_OR_MOBILE (if numbers for this
+  // non-geographical entity could be classified as FIXED_LINE_OR_MOBILE, both
+  // FIXED_LINE and MOBILE would be present) and UNKNOWN.
+  //
+  // No types will be returned for country calling codes that do not map to a
+  // known non-geographical entity.
+  void GetSupportedTypesForNonGeoEntity(
+      int country_calling_code,
+      std::set<PhoneNumberType>* types) const;
 
   // Gets a PhoneNumberUtil instance to carry out international phone number
   // formatting, parsing, or validation. The instance is loaded with phone
@@ -472,8 +500,8 @@ class PhoneNumberUtil : public Singleton<PhoneNumberUtil> {
   //      region. Therefore, it is much faster than IsValidNumber().
   //   3. For fixed line numbers, many regions have the concept of area code,
   //      which together with subscriber number constitute the national
-  //      significant number. It is sometimes okay to dial the subscriber
-  //      number only when dialing in the same area. This function will return
+  //      significant number. It is sometimes okay to dial only the subscriber
+  //      number when dialing in the same area. This function will return
   //      true if the subscriber-number-only version is passed in. On the other
   //      hand, because IsValidNumber() validates using information on both
   //      starting digits (for fixed line numbers, that would most likely be
@@ -482,10 +510,39 @@ class PhoneNumberUtil : public Singleton<PhoneNumberUtil> {
   //      subscriber-number-only version.
   ValidationResult IsPossibleNumberWithReason(const PhoneNumber& number) const;
 
-  // Convenience wrapper around IsPossibleNumberWithReason. Instead of returning
-  // the reason for failure, this method returns a boolean value.
+  // Convenience wrapper around IsPossibleNumberWithReason(). Instead of
+  // returning the reason for failure, this method returns a boolean value.
   bool IsPossibleNumber(const PhoneNumber& number) const;
 
+  // Check whether a phone number is a possible number of a particular type. For
+  // types that don't exist in a particular region, this will return a result
+  // that isn't so useful; it is recommended that you use
+  // GetSupportedTypesForRegion() or GetSupportedTypesForNonGeoEntity()
+  // respectively before calling this method to determine whether you should
+  // call it for this number at all.
+  //
+  // This provides a more lenient check than IsValidNumber() in the following
+  // sense:
+  //
+  // * It only checks the length of phone numbers. In particular, it doesn't
+  //   check starting digits of the number.
+  // * For fixed line numbers, many regions have the concept of area code, which
+  //   together with subscriber number constitute the national significant
+  //   number. It is sometimes okay to dial only the subscriber number when
+  //   dialing in the same area. This function will return true if the
+  //   subscriber-number-only version is passed in. On the other hand, because
+  //   IsValidNumber() validates using information on both starting digits (for
+  //   fixed line numbers, that would most likely be area codes) and length
+  //   (obviously includes the length of area codes for fixed line numbers), it
+  //   will return false for the subscriber-number-only version.
+  ValidationResult IsPossibleNumberForTypeWithReason(
+      const PhoneNumber& number, PhoneNumberType type) const;
+
+  // Convenience wrapper around IsPossibleNumberForTypeWithReason(). Instead of
+  // returning the reason for failure, this method returns a boolean value.
+  bool IsPossibleNumberForType(const PhoneNumber& number,
+                               PhoneNumberType type) const;
+
   // Checks whether a phone number is a possible number given a number in the
   // form of a string, and the country where the number could be dialed from.
   // It provides a more lenient check than IsValidNumber(). See
@@ -658,9 +715,6 @@ class PhoneNumberUtil : public Singleton<PhoneNumberUtil> {
   // country is Italy.
   bool IsLeadingZeroPossible(int country_calling_code) const;
 
-  bool IsNumberPossibleForDesc(const string& national_number,
-                               const PhoneNumberDesc& number_desc) const;
-
   bool IsNumberMatchingDesc(const string& national_number,
                             const PhoneNumberDesc& number_desc) const;
 

cpp/test/phonenumbers/phonenumberutil_test.cc

@@ -157,6 +157,42 @@ TEST_F(PhoneNumberUtilTest, GetSupportedGlobalNetworkCallingCodes) {
   }
 }
 
+TEST_F(PhoneNumberUtilTest, GetSupportedTypesForRegion) {
+  std::set<PhoneNumberUtil::PhoneNumberType> types;
+  phone_util_.GetSupportedTypesForRegion(RegionCode::BR(), &types);
+  EXPECT_NE(types.find(PhoneNumberUtil::FIXED_LINE), types.end());
+  // Our test data has no mobile numbers for Brazil.
+  EXPECT_EQ(types.find(PhoneNumberUtil::MOBILE), types.end());
+  // UNKNOWN should never be returned.
+  EXPECT_EQ(types.find(PhoneNumberUtil::UNKNOWN), types.end());
+
+  types.clear();
+  // In the US, many numbers are classified as FIXED_LINE_OR_MOBILE; but we
+  // don't want to expose this as a supported type, instead we say FIXED_LINE
+  // and MOBILE are both present.
+  phone_util_.GetSupportedTypesForRegion(RegionCode::US(), &types);
+  EXPECT_NE(types.find(PhoneNumberUtil::FIXED_LINE), types.end());
+  EXPECT_NE(types.find(PhoneNumberUtil::MOBILE), types.end());
+  EXPECT_EQ(types.find(PhoneNumberUtil::FIXED_LINE_OR_MOBILE), types.end());
+  types.clear();
+  phone_util_.GetSupportedTypesForRegion(RegionCode::ZZ(), &types);
+  // Test the invalid region code.
+  EXPECT_EQ(0, types.size());
+}
+
+TEST_F(PhoneNumberUtilTest, GetSupportedTypesForNonGeoEntity) {
+  std::set<PhoneNumberUtil::PhoneNumberType> types;
+  // No data exists for 999 at all, no types should be returned.
+  phone_util_.GetSupportedTypesForNonGeoEntity(999, &types);
+  EXPECT_EQ(0, types.size());
+
+  types.clear();
+  phone_util_.GetSupportedTypesForNonGeoEntity(979, &types);
+  EXPECT_NE(types.find(PhoneNumberUtil::PREMIUM_RATE), types.end());
+  EXPECT_EQ(types.find(PhoneNumberUtil::MOBILE), types.end());
+  EXPECT_EQ(types.find(PhoneNumberUtil::UNKNOWN), types.end());
+}
+
 TEST_F(PhoneNumberUtilTest, GetRegionCodesForCountryCallingCode) {
   list<string> regions;
 
@@ -182,7 +218,8 @@ TEST_F(PhoneNumberUtilTest, GetRegionCodesForCountryCallingCode) {
               != regions.end());
 
   regions.clear();
-  phone_util_.GetRegionCodesForCountryCallingCode(kInvalidCountryCode, &regions);
+  phone_util_.GetRegionCodesForCountryCallingCode(
+      kInvalidCountryCode, &regions);
   EXPECT_TRUE(regions.empty());
 }
 
@@ -329,39 +366,41 @@ TEST_F(PhoneNumberUtilTest, GetExampleNumber) {
   EXPECT_TRUE(success);
   EXPECT_EQ(de_number, test_number);
 
-  success = phone_util_.GetExampleNumberForType(RegionCode::DE(),
-                                                PhoneNumberUtil::FIXED_LINE,
-                                                &test_number);
+  success = phone_util_.GetExampleNumberForType(
+      RegionCode::DE(), PhoneNumberUtil::FIXED_LINE, &test_number);
   EXPECT_TRUE(success);
   EXPECT_EQ(de_number, test_number);
 
-  success = phone_util_.GetExampleNumberForType(RegionCode::DE(),
-                                                PhoneNumberUtil::MOBILE,
-                                                &test_number);
-  // Here we test that an example number was not returned, and that the number
-  // passed in was not modified.
+  // Should return the same response if asked for FIXED_LINE_OR_MOBILE too.
+  success = phone_util_.GetExampleNumberForType(
+      RegionCode::DE(), PhoneNumberUtil::FIXED_LINE_OR_MOBILE, &test_number);
+  EXPECT_EQ(de_number, test_number);
+
+  success = phone_util_.GetExampleNumberForType(
+      RegionCode::DE(), PhoneNumberUtil::MOBILE, &test_number);
+  // We have data for the US, but no data for VOICEMAIL, so the number passed in
+  // should be left empty.
+  success = phone_util_.GetExampleNumberForType(
+      RegionCode::US(), PhoneNumberUtil::VOICEMAIL, &test_number);
   test_number.Clear();
   EXPECT_FALSE(success);
   EXPECT_EQ(PhoneNumber::default_instance(), test_number);
 
-  success = phone_util_.GetExampleNumberForType(RegionCode::US(),
-                                                PhoneNumberUtil::FIXED_LINE,
-                                                &test_number);
+  success = phone_util_.GetExampleNumberForType(
+      RegionCode::US(), PhoneNumberUtil::FIXED_LINE, &test_number);
   // Here we test that the call to get an example number succeeded, and that the
   // number passed in was modified.
   EXPECT_TRUE(success);
   EXPECT_NE(PhoneNumber::default_instance(), test_number);
-  success = phone_util_.GetExampleNumberForType(RegionCode::US(),
-                                                PhoneNumberUtil::MOBILE,
-                                                &test_number);
+  success = phone_util_.GetExampleNumberForType(
+      RegionCode::US(), PhoneNumberUtil::MOBILE, &test_number);
   EXPECT_TRUE(success);
   EXPECT_NE(PhoneNumber::default_instance(), test_number);
 
   // CS is an invalid region, so we have no data for it. We should return false.
   test_number.Clear();
-  EXPECT_FALSE(phone_util_.GetExampleNumberForType(RegionCode::CS(),
-                                                   PhoneNumberUtil::MOBILE,
-                                                   &test_number));
+  EXPECT_FALSE(phone_util_.GetExampleNumberForType(
+      RegionCode::CS(), PhoneNumberUtil::MOBILE, &test_number));
   EXPECT_EQ(PhoneNumber::default_instance(), test_number);
 
   // RegionCode 001 is reserved for supporting non-geographical country calling
@@ -1757,6 +1796,129 @@ TEST_F(PhoneNumberUtilTest, IsPossibleNumber) {
                                                     RegionCode::UN001()));
 }
 
+TEST_F(PhoneNumberUtilTest, IsPossibleNumberForType_DifferentTypeLengths) {
+  // We use Argentinian numbers since they have different possible lengths for
+  // different types.
+  PhoneNumber number;
+  number.set_country_code(54);
+  number.set_national_number(12345ULL);
+  // Too short for any Argentinian number, including fixed-line.
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::UNKNOWN));
+
+  // 6-digit numbers are okay for fixed-line.
+  number.set_national_number(123456ULL);
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::FIXED_LINE));
+  // But too short for mobile.
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::MOBILE));
+  // And too short for toll-free.
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::TOLL_FREE));
+
+  // The same applies to 9-digit numbers.
+  number.set_national_number(123456789ULL);
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::MOBILE));
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::TOLL_FREE));
+
+  // 10-digit numbers are universally possible.
+  number.set_national_number(1234567890ULL);
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::MOBILE));
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::TOLL_FREE));
+
+  // 11-digit numbers are only possible for mobile numbers. Note we don't
+  // require the leading 9, which all mobile numbers start with, and would be
+  // required for a valid mobile number.
+  number.set_national_number(12345678901ULL);
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::MOBILE));
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::TOLL_FREE));
+}
+
+TEST_F(PhoneNumberUtilTest, IsPossibleNumberForType_LocalOnly) {
+  PhoneNumber number;
+  // Here we test a number length which matches a local-only length.
+  number.set_country_code(49);
+  number.set_national_number(12ULL);
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::FIXED_LINE));
+  // Mobile numbers must be 10 or 11 digits, and there are no local-only
+  // lengths.
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::MOBILE));
+}
+
+TEST_F(PhoneNumberUtilTest, IsPossibleNumberForType_DataMissingForSizeReasons) {
+  PhoneNumber number;
+  // Here we test something where the possible lengths match the possible
+  // lengths of the country as a whole, and hence aren't present in the binary
+  // for size reasons - this should still work.
+  // Local-only number.
+  number.set_country_code(55);
+  number.set_national_number(12345678ULL);
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::FIXED_LINE));
+  number.set_national_number(1234567890ULL);
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::FIXED_LINE));
+}
+
+TEST_F(PhoneNumberUtilTest,
+       IsPossibleNumberForType_NumberTypeNotSupportedForRegion) {
+  PhoneNumber number;
+  // There are *no* mobile numbers for this region at all, so we return false.
+  number.set_country_code(55);
+  number.set_national_number(12345678L);
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::MOBILE));
+  // This matches a fixed-line length though.
+  EXPECT_TRUE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_TRUE(phone_util_.IsPossibleNumberForType(
+      number, PhoneNumberUtil::FIXED_LINE_OR_MOBILE));
+
+  // There are *no* fixed-line OR mobile numbers for this country calling code
+  // at all, so we return false for these.
+  number.set_country_code(979);
+  number.set_national_number(123456789L);
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::MOBILE));
+  EXPECT_FALSE(
+      phone_util_.IsPossibleNumberForType(number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_FALSE(phone_util_.IsPossibleNumberForType(
+      number, PhoneNumberUtil::FIXED_LINE_OR_MOBILE));
+  EXPECT_TRUE(phone_util_.IsPossibleNumberForType(
+      number, PhoneNumberUtil::PREMIUM_RATE));
+}
+
 TEST_F(PhoneNumberUtilTest, IsPossibleNumberWithReason) {
   // FYI, national numbers for country code +1 that are within 7 to 10 digits
   // are possible.
@@ -1807,6 +1969,242 @@ TEST_F(PhoneNumberUtilTest, IsPossibleNumberWithReason) {
             phone_util_.IsPossibleNumberWithReason(number));
 }
 
+TEST_F(PhoneNumberUtilTest,
+       IsPossibleNumberForTypeWithReason_DifferentTypeLengths) {
+  // We use Argentinian numbers since they have different possible lengths for
+  // different types.
+  PhoneNumber number;
+  number.set_country_code(54);
+  number.set_national_number(12345ULL);
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+
+  // 6-digit numbers are okay for fixed-line.
+  number.set_national_number(123456ULL);
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  // But too short for mobile.
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  // And too short for toll-free.
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::TOLL_FREE));
+  // The same applies to 9-digit numbers.
+  number.set_national_number(123456789ULL);
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::TOLL_FREE));
+  // 10-digit numbers are universally possible.
+  number.set_national_number(1234567890ULL);
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::TOLL_FREE));
+  // 11-digit numbers are possible for mobile numbers. Note we don't require the
+  // leading 9, which all mobile numbers start with, and would be required for a
+  // valid mobile number.
+  number.set_national_number(12345678901ULL);
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_EQ(PhoneNumberUtil::TOO_LONG,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::TOO_LONG,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::TOLL_FREE));
+}
+
+TEST_F(PhoneNumberUtilTest, IsPossibleNumberForTypeWithReason_LocalOnly) {
+  PhoneNumber number;
+  // Here we test a number length which matches a local-only length.
+  number.set_country_code(49);
+  number.set_national_number(12ULL);
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  // Mobile numbers must be 10 or 11 digits, and there are no local-only
+  // lengths.
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+}
+
+TEST_F(PhoneNumberUtilTest,
+       IsPossibleNumberForTypeWithReason_DataMissingForSizeReasons) {
+  PhoneNumber number;
+  // Here we test something where the possible lengths match the possible
+  // lengths of the country as a whole, and hence aren't present in the binary
+  // for size reasons - this should still work.
+  // Local-only number.
+  number.set_country_code(55);
+  number.set_national_number(12345678ULL);
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  // Normal-length number.
+  number.set_national_number(1234567890ULL);
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::UNKNOWN));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+}
+
+TEST_F(PhoneNumberUtilTest,
+       IsPossibleNumberForTypeWithReason_NumberTypeNotSupportedForRegion) {
+  PhoneNumber number;
+  // There are *no* mobile numbers for this region at all, so we return
+  // INVALID_LENGTH.
+  number.set_country_code(55);
+  number.set_national_number(12345678ULL);
+  EXPECT_EQ(PhoneNumberUtil::INVALID_LENGTH,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  // This matches a fixed-line length though.
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE_OR_MOBILE));
+  // This is too short for fixed-line, and no mobile numbers exist.
+  number.set_national_number(1234567ULL);
+  EXPECT_EQ(PhoneNumberUtil::INVALID_LENGTH,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE_OR_MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  // This is too short for mobile, and no fixed-line number exist.
+  number.set_country_code(882);
+  number.set_national_number(1234567ULL);
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE_OR_MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::INVALID_LENGTH,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+
+  // There are *no* fixed-line OR mobile numbers for this country calling code
+  // at all, so we return INVALID_LENGTH.
+  number.set_country_code(979);
+  number.set_national_number(123456789ULL);
+  EXPECT_EQ(PhoneNumberUtil::INVALID_LENGTH,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::INVALID_LENGTH,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_EQ(PhoneNumberUtil::INVALID_LENGTH,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE_OR_MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::PREMIUM_RATE));
+}
+
+TEST_F(PhoneNumberUtilTest,
+       IsPossibleNumberForTypeWithReason_FixedLineOrMobile) {
+  PhoneNumber number;
+  // For FIXED_LINE_OR_MOBILE, a number should be considered valid if it matches
+  // the possible lengths for mobile *or* fixed-line numbers.
+  number.set_country_code(290);
+  number.set_national_number(1234ULL);
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE_OR_MOBILE));
+
+  number.set_national_number(12345ULL);
+  EXPECT_EQ(PhoneNumberUtil::TOO_SHORT,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_EQ(PhoneNumberUtil::TOO_LONG,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  // This will change to INVALID_LENGTH once we start returning this type in the
+  // main isPossibleNumberWithReason API.
+  EXPECT_EQ(PhoneNumberUtil::TOO_LONG,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE_OR_MOBILE));
+
+  number.set_national_number(123456ULL);
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_EQ(PhoneNumberUtil::TOO_LONG,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE_OR_MOBILE));
+
+  number.set_national_number(1234567ULL);
+  EXPECT_EQ(PhoneNumberUtil::TOO_LONG,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE));
+  EXPECT_EQ(PhoneNumberUtil::TOO_LONG,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::MOBILE));
+  EXPECT_EQ(PhoneNumberUtil::TOO_LONG,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE_OR_MOBILE));
+
+  number.set_national_number(12345678ULL);
+  EXPECT_EQ(PhoneNumberUtil::IS_POSSIBLE,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::TOLL_FREE));
+  EXPECT_EQ(PhoneNumberUtil::TOO_LONG,
+            phone_util_.IsPossibleNumberForTypeWithReason(
+                number, PhoneNumberUtil::FIXED_LINE_OR_MOBILE));
+}
+
 TEST_F(PhoneNumberUtilTest, IsNotPossibleNumber) {
   PhoneNumber number;
   number.set_country_code(1);
@@ -2388,8 +2786,8 @@ TEST_F(PhoneNumberUtilTest, GetNationalDiallingPrefixForRegion) {
   phone_util_.GetNddPrefixForRegion(RegionCode::NZ(), false, &ndd_prefix);
   EXPECT_EQ("0", ndd_prefix);
 
-  // Test case with non digit in the national prefix.
   ndd_prefix.clear();
+  // Test case with non digit in the national prefix.
   phone_util_.GetNddPrefixForRegion(RegionCode::AO(), false, &ndd_prefix);
   EXPECT_EQ("0~0", ndd_prefix);
 
@@ -2399,7 +2797,8 @@ TEST_F(PhoneNumberUtilTest, GetNationalDiallingPrefixForRegion) {
 
   // Test cases with invalid regions.
   ndd_prefix.clear();
-  phone_util_.GetNddPrefixForRegion(RegionCode::GetUnknown(), false, &ndd_prefix);
+  phone_util_.GetNddPrefixForRegion(RegionCode::GetUnknown(), false,
+                                    &ndd_prefix);
   EXPECT_EQ("", ndd_prefix);
 
   ndd_prefix.clear();

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

@@ -25,12 +25,14 @@ import com.google.i18n.phonenumbers.Phonenumber.PhoneNumber.CountryCodeSource;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
+import java.util.EnumSet;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.TreeSet;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 import java.util.regex.Matcher;
@@ -455,7 +457,9 @@ public class PhoneNumberUtil {
     /**
      * The number is longer than the shortest valid numbers for this region, shorter than the
      * longest valid numbers for this region, and does not itself have a number length that matches
-     * valid numbers for this region.
+     * valid numbers for this region. This can also be returned in the case where
+     * isPossibleNumberForTypeWithReason was called, and there are no numbers of this type at all
+     * for this region.
      */
     INVALID_LENGTH,
     /** The number is longer than all valid numbers for this region. */
@@ -949,20 +953,101 @@ public class PhoneNumberUtil {
   }
 
   /**
-   * Convenience method to get a list of what regions the library has metadata for.
+   * Returns all regions the library has metadata for.
+   *
+   * @return  an unordered set of the two-letter region codes for every geographical region the
+   *     library supports
    */
   public Set<String> getSupportedRegions() {
     return Collections.unmodifiableSet(supportedRegions);
   }
 
   /**
-   * Convenience method to get a list of what global network calling codes the library has metadata
-   * for.
+   * Returns all global network calling codes the library has metadata for.
+   *
+   * @return  an unordered set of the country calling codes for every non-geographical entity the
+   *     library supports
    */
   public Set<Integer> getSupportedGlobalNetworkCallingCodes() {
     return Collections.unmodifiableSet(countryCodesForNonGeographicalRegion);
   }
 
+  /**
+   * Returns true if there is any possible number data set for a particular PhoneNumberDesc.
+   */
+  private static boolean descHasPossibleNumberData(PhoneNumberDesc desc) {
+    // If this is empty, it means numbers of this type inherit from the "general desc" -> the value
+    // "-1" means that no numbers exist for this type.
+    return desc.getPossibleLengthCount() != 1 || desc.getPossibleLength(0) != -1;
+  }
+
+  /**
+   * Returns true if there is any data set for a particular PhoneNumberDesc.
+   */
+  private static boolean descHasData(PhoneNumberDesc desc) {
+    // Checking most properties since we don't know what's present, since a custom build may have
+    // stripped just one of them (e.g. liteBuild strips exampleNumber). We don't bother checking the
+    // possibleLengthsLocalOnly, since if this is the only thing that's present we don't really
+    // support the type at all: no type-specific methods will work with only this data.
+    return desc.hasExampleNumber()
+        || descHasPossibleNumberData(desc)
+        || (desc.hasNationalNumberPattern() && !desc.getNationalNumberPattern().equals("NA"));
+  }
+
+  /**
+   * Returns the types we have metadata for based on the PhoneMetadata object passed in, which must
+   * be non-null.
+   */
+  private Set<PhoneNumberType> getSupportedTypesForMetadata(PhoneMetadata metadata) {
+    Set<PhoneNumberType> types = new TreeSet<PhoneNumberType>();
+    for (PhoneNumberType type : PhoneNumberType.values()) {
+      if (type == PhoneNumberType.FIXED_LINE_OR_MOBILE || type == PhoneNumberType.UNKNOWN) {
+        // Never return FIXED_LINE_OR_MOBILE (it is a convenience type, and represents that a
+        // particular number type can't be determined) or UNKNOWN (the non-type).
+        continue;
+      }
+      if (descHasData(getNumberDescByType(metadata, type))) {
+        types.add(type);
+      }
+    }
+    return Collections.unmodifiableSet(types);
+  }
+
+  /**
+   * Returns the types for a given region which the library has metadata for. Will not include
+   * FIXED_LINE_OR_MOBILE (if numbers in this region could be classified as FIXED_LINE_OR_MOBILE,
+   * both FIXED_LINE and MOBILE would be present) and UNKNOWN.
+   *
+   * No types will be returned for invalid or unknown region codes.
+   */
+  public Set<PhoneNumberType> getSupportedTypesForRegion(String regionCode) {
+    if (!isValidRegionCode(regionCode)) {
+      logger.log(Level.WARNING, "Invalid or unknown region code provided: " + regionCode);
+      return Collections.unmodifiableSet(new TreeSet<PhoneNumberType>());
+    }
+    PhoneMetadata metadata = getMetadataForRegion(regionCode);
+    return getSupportedTypesForMetadata(metadata);
+  }
+
+  /**
+   * Returns the types for a country-code belonging to a non-geographical entity which the library
+   * has metadata for. Will not include FIXED_LINE_OR_MOBILE (if numbers for this non-geographical
+   * entity could be classified as FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would be
+   * present) and UNKNOWN.
+   *
+   * No types will be returned for country calling codes that do not map to a known non-geographical
+   * entity.
+   */
+  public Set<PhoneNumberType> getSupportedTypesForNonGeoEntity(int countryCallingCode) {
+    PhoneMetadata metadata = getMetadataForNonGeographicalRegion(countryCallingCode);
+    if (metadata == null) {
+      logger.log(Level.WARNING, "Unknown country calling code for a non-geographical entity "
+          + "provided: " + countryCallingCode);
+      return Collections.unmodifiableSet(new TreeSet<PhoneNumberType>());
+    }
+    return getSupportedTypesForMetadata(metadata);
+  }
+
   /**
    * Gets a {@link PhoneNumberUtil} instance to carry out international phone number formatting,
    * parsing, or validation. The instance is loaded with all phone number metadata.
@@ -1320,8 +1405,8 @@ public class PhoneNumberUtil {
         // short numbers, which are always dialled in national format.
         PhoneMetadata regionMetadata = getMetadataForRegion(regionCallingFrom);
         if (canBeInternationallyDialled(numberNoExt)
-            && testNumberLength(getNationalSignificantNumber(numberNoExt),
-                regionMetadata.getGeneralDesc()) != ValidationResult.TOO_SHORT) {
+            && testNumberLength(getNationalSignificantNumber(numberNoExt), regionMetadata)
+                != ValidationResult.TOO_SHORT) {
           formattedNumber = format(numberNoExt, PhoneNumberFormat.INTERNATIONAL);
         } else {
           formattedNumber = format(numberNoExt, PhoneNumberFormat.NATIONAL);
@@ -2387,20 +2472,89 @@ public class PhoneNumberUtil {
   }
 
   /**
-   * Helper method to check a number against possible lengths for this number, and determine whether
-   * it matches, or is too short or too long. Currently, if a number pattern suggests that numbers
-   * of length 7 and 10 are possible, and a number in between these possible lengths is entered,
-   * such as of length 8, this will return TOO_LONG.
+   * Convenience wrapper around {@link #isPossibleNumberForTypeWithReason}. Instead of returning the
+   * reason for failure, this method returns a boolean value.
+   *
+   * @param number  the number that needs to be checked
+   * @param type  the type we are interested in
+   * @return  true if the number is possible for this particular type
    */
-  private ValidationResult testNumberLength(String number, PhoneNumberDesc phoneNumberDesc) {
-    List<Integer> possibleLengths = phoneNumberDesc.getPossibleLengthList();
-    List<Integer> localLengths = phoneNumberDesc.getPossibleLengthLocalOnlyList();
+  public boolean isPossibleNumberForType(PhoneNumber number, PhoneNumberType type) {
+    return isPossibleNumberForTypeWithReason(number, type) == ValidationResult.IS_POSSIBLE;
+  }
+
+  /**
+   * Helper method to check a number against possible lengths for this region, based on the metadata
+   * being passed in, and determine whether it matches, or is too short or too long. Currently, if a
+   * number pattern suggests that numbers of length 7 and 10 are possible, and a number in between
+   * these possible lengths is entered, such as of length 8, this will return TOO_LONG.
+   */
+  private ValidationResult testNumberLength(String number, PhoneMetadata metadata) {
+    return testNumberLength(number, metadata, PhoneNumberType.UNKNOWN);
+  }
+
+  /**
+   * Helper method to check a number against possible lengths for this number type, and determine
+   * whether it matches, or is too short or too long. Currently, if a number pattern suggests that
+   * numbers of length 7 and 10 are possible, and a number in between these possible lengths is
+   * entered, such as of length 8, this will return TOO_LONG.
+   */
+  private ValidationResult testNumberLength(
+      String number, PhoneMetadata metadata, PhoneNumberType type) {
+    PhoneNumberDesc descForType = getNumberDescByType(metadata, type);
+    // There should always be "possibleLengths" set for every element. This is declared in the XML
+    // schema which is verified by PhoneNumberMetadataSchemaTest.
+    // For size efficiency, where a sub-description (e.g. fixed-line) has the same possibleLengths
+    // as the parent, this is missing, so we fall back to the general desc (where no numbers of the
+    // type exist at all, there is one possible length (-1) which is guaranteed not to match the
+    // length of any real phone number).
+    List<Integer> possibleLengths = descForType.getPossibleLengthList().isEmpty()
+        ? metadata.getGeneralDesc().getPossibleLengthList() : descForType.getPossibleLengthList();
+
+    List<Integer> localLengths = descForType.getPossibleLengthLocalOnlyList();
+
+    if (type == PhoneNumberType.FIXED_LINE_OR_MOBILE) {
+      if (!descHasPossibleNumberData(getNumberDescByType(metadata, PhoneNumberType.FIXED_LINE))) {
+        // The rare case has been encountered where no fixedLine data is available (true for some
+        // non-geographical entities), so we just check mobile.
+        return testNumberLength(number, metadata, PhoneNumberType.MOBILE);
+      } else {
+        PhoneNumberDesc mobileDesc = getNumberDescByType(metadata, PhoneNumberType.MOBILE);
+        if (descHasPossibleNumberData(mobileDesc)) {
+          // Merge the mobile data in if there was any. We have to make a copy to do this.
+          possibleLengths = new ArrayList<Integer>(possibleLengths);
+          // Note that when adding the possible lengths from mobile, we have to again check they
+          // aren't empty since if they are this indicates they are the same as the general desc and
+          // should be obtained from there.
+          possibleLengths.addAll(mobileDesc.getPossibleLengthList().size() == 0
+              ? metadata.getGeneralDesc().getPossibleLengthList()
+              : mobileDesc.getPossibleLengthList());
+          // The current list is sorted; we need to merge in the new list and re-sort (duplicates
+          // are okay). Sorting isn't so expensive because the lists are very small.
+          Collections.sort(possibleLengths);
+
+          if (localLengths.isEmpty()) {
+            localLengths = mobileDesc.getPossibleLengthLocalOnlyList();
+          } else {
+            localLengths = new ArrayList<Integer>(localLengths);
+            localLengths.addAll(mobileDesc.getPossibleLengthLocalOnlyList());
+            Collections.sort(localLengths);
+          }
+        }
+      }
+    }
+
+    // If the type is not supported at all (indicated by the possible lengths containing -1 at this
+    // point) we return invalid length.
+    if (possibleLengths.get(0) == -1) {
+      return ValidationResult.INVALID_LENGTH;
+    }
+
     int actualLength = number.length();
     if (localLengths.contains(actualLength)) {
       return ValidationResult.IS_POSSIBLE;
     }
-    // There should always be "possibleLengths" set for every element. This will be a build-time
-    // check once ShortNumberMetadata.xml is migrated to contain this information as well.
+
     int minimumLength = possibleLengths.get(0);
     if (minimumLength == actualLength) {
       return ValidationResult.IS_POSSIBLE;
@@ -2429,7 +2583,7 @@ public class PhoneNumberUtil {
    *      isValidNumber.
    * <li> For fixed line numbers, many regions have the concept of area code, which together with
    *      subscriber number constitute the national significant number. It is sometimes okay to dial
-   *      the subscriber number only when dialing in the same area. This function will return
+   *      only the subscriber number when dialing in the same area. This function will return
    *      true if the subscriber-number-only version is passed in. On the other hand, because
    *      isValidNumber validates using information on both starting digits (for fixed line
    *      numbers, that would most likely be area codes) and length (obviously includes the
@@ -2440,19 +2594,52 @@ public class PhoneNumberUtil {
    * @return  a ValidationResult object which indicates whether the number is possible
    */
   public ValidationResult isPossibleNumberWithReason(PhoneNumber number) {
+    return isPossibleNumberForTypeWithReason(number, PhoneNumberType.UNKNOWN);
+  }
+
+  /**
+   * Check whether a phone number is a possible number of a particular type. For types that don't
+   * exist in a particular region, this will return a result that isn't so useful; it is recommended
+   * that you use {@link #getSupportedTypesForRegion} or {@link #getSupportedTypesForNonGeoEntity}
+   * respectively before calling this method to determine whether you should call it for this number
+   * at all.
+   *
+   * This provides a more lenient check than {@link #isValidNumber} in the following sense:
+   *
+   * <ol>
+   *   <li> It only checks the length of phone numbers. In particular, it doesn't check starting
+   *       digits of the number.
+   *   <li> For fixed line numbers, many regions have the concept of area code, which together with
+   *       subscriber number constitute the national significant number. It is sometimes okay to
+   *       dial the subscriber number only when dialing in the same area. This function will return
+   *       true if the subscriber-number-only version is passed in. On the other hand, because
+   *       isValidNumber validates using information on both starting digits (for fixed line
+   *       numbers, that would most likely be area codes) and length (obviously includes the length
+   *       of area codes for fixed line numbers), it will return false for the
+   *       subscriber-number-only version.
+   * </ol>
+   *
+   * @param number  the number that needs to be checked
+   * @param type  the type we are interested in
+   * @return  a ValidationResult object which indicates whether the number is possible
+   */
+  public ValidationResult isPossibleNumberForTypeWithReason(
+      PhoneNumber number, PhoneNumberType type) {
     String nationalNumber = getNationalSignificantNumber(number);
     int countryCode = number.getCountryCode();
-    // Note: For Russian Fed and NANPA numbers, we just use the rules from the default region (US or
-    // Russia) since the getRegionCodeForNumber will not work if the number is possible but not
-    // valid. This would need to be revisited if the possible number pattern ever differed between
-    // various regions within those plans.
+    // Note: For regions that share a country calling code, like NANPA numbers, we just use the
+    // rules from the default region (US in this case) since the getRegionCodeForNumber will not
+    // work if the number is possible but not valid. There is in fact one country calling code (290)
+    // where the possible number pattern differs between various regions (Saint Helena and Tristan
+    // da Cuñha), but this is handled by putting all possible lengths for any country with this
+    // country calling code in the metadata for the default region in this case.
     if (!hasValidCountryCallingCode(countryCode)) {
       return ValidationResult.INVALID_COUNTRY_CODE;
     }
     String regionCode = getRegionCodeForCountryCode(countryCode);
     // Metadata cannot be null because the country calling code is valid.
     PhoneMetadata metadata = getMetadataForRegionOrCallingCode(countryCode, regionCode);
-    return testNumberLength(nationalNumber, metadata.getGeneralDesc());
+    return testNumberLength(nationalNumber, metadata, type);
   }
 
   /**
@@ -2626,8 +2813,9 @@ public class PhoneNumberUtil {
         // consider the number with the country calling code stripped to be a better result and
         // keep that instead.
         if ((!validNumberPattern.matcher(fullNumber).matches()
-              && validNumberPattern.matcher(potentialNationalNumber).matches())
-            || testNumberLength(fullNumber.toString(), generalDesc) == ValidationResult.TOO_LONG) {
+                && validNumberPattern.matcher(potentialNationalNumber).matches())
+            || testNumberLength(fullNumber.toString(), defaultRegionMetadata)
+                == ValidationResult.TOO_LONG) {
           nationalNumber.append(potentialNationalNumber);
           if (keepRawInput) {
             phoneNumber.setCountryCodeSource(CountryCodeSource.FROM_NUMBER_WITHOUT_PLUS_SIGN);
@@ -3039,8 +3227,8 @@ public class PhoneNumberUtil {
       // We require that the NSN remaining after stripping the national prefix and carrier code be
       // long enough to be a possible length for the region. Otherwise, we don't do the stripping,
       // since the original number could be a valid short number.
-      if (testNumberLength(potentialNationalNumber.toString(), regionMetadata.getGeneralDesc())
-              != ValidationResult.TOO_SHORT) {
+      if (testNumberLength(potentialNationalNumber.toString(), regionMetadata)
+          != ValidationResult.TOO_SHORT) {
         normalizedNationalNumber = potentialNationalNumber;
         if (keepRawInput && carrierCode.length() > 0) {
           phoneNumber.setPreferredDomesticCarrierCode(carrierCode.toString());
@@ -3111,7 +3299,7 @@ public class PhoneNumberUtil {
   /**
    * Returns a new phone number containing only the fields needed to uniquely identify a phone
    * number, rather than any fields that capture the context in which the phone number was created.
-   * These fields correspond to those set in parse() rather than parseHelper().
+   * These fields correspond to those set in parse() rather than parseAndKeepRawInput().
    */
   private static PhoneNumber copyCoreFieldsOnly(PhoneNumber phoneNumberIn) {
     PhoneNumber phoneNumber = new PhoneNumber();