Adding new enum values for ValidationResult (#1562)

- Adding new enums IS_POSSIBLE_LOCAL_ONLY and INVALID_LENGTH for
ValidationResult, to be later returned by IsPossibleWithReason.
- Documenting existing enum values better.

See email on discuss list:
https://groups.google.com/d/msg/libphonenumber-discuss/sPhYzdzFCmg/6tYsS1f6DgAJ

cpp/src/phonenumbers/phonenumberutil.h

@@ -145,9 +145,22 @@ class PhoneNumberUtil : public Singleton<PhoneNumberUtil> {
 
   // Possible outcomes when testing if a PhoneNumber is possible.
   enum ValidationResult {
+    // The number length matches that of valid numbers for this region.
     IS_POSSIBLE,
+    // The number length matches that of local numbers for this region only
+    // (i.e. numbers that may be able to be dialled within an area, but do not
+    // have all the information to be dialled from anywhere inside or outside
+    // the country).
+    IS_POSSIBLE_LOCAL_ONLY,
+    // The number has an invalid country calling code.
     INVALID_COUNTRY_CODE,
+    // The number is shorter than all valid numbers for this region.
     TOO_SHORT,
+    // 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.
+    INVALID_LENGTH,
+    // The number is longer than all valid numbers for this region.
     TOO_LONG,
   };
 

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

@@ -440,9 +440,25 @@ public class PhoneNumberUtil {
    * Possible outcomes when testing if a PhoneNumber is possible.
    */
   public enum ValidationResult {
+    /** The number length matches that of valid numbers for this region. */
     IS_POSSIBLE,
+    /**
+     * The number length matches that of local numbers for this region only (i.e. numbers that may
+     * be able to be dialled within an area, but do not have all the information to be dialled from
+     * anywhere inside or outside the country).
+     */
+    IS_POSSIBLE_LOCAL_ONLY,
+    /** The number has an invalid country calling code. */
     INVALID_COUNTRY_CODE,
+    /** The number is shorter than all valid numbers for this region. */
     TOO_SHORT,
+    /**
+     * 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.
+     */
+    INVALID_LENGTH,
+    /** The number is longer than all valid numbers for this region. */
     TOO_LONG,
   }
 

java/pending_code_changes.txt

@@ -1 +1,8 @@
-
+Code changes:
+ - Added two new enum values to ValidationResult - IS_POSSIBLE_LOCAL_ONLY and
+   INVALID_LENGTH. Added more documentation to the existing values; see the
+   javadoc for when these are going to be used. Note that the API for
+   IsPossibleNumberWithReason has not yet been changed to return these values.
+   IS_POSSIBLE_LOCAL_ONLY will be returned for some values which currently
+   return IS_POSSIBLE, and INVALID_LENGTH will be returned for some values which
+   currently return TOO_LONG.

javascript/i18n/phonenumbers/phonenumberutil.js

@@ -963,9 +963,25 @@ i18n.phonenumbers.PhoneNumberUtil.MatchType = {
  * @enum {number}
  */
 i18n.phonenumbers.PhoneNumberUtil.ValidationResult = {
+  /** The number length matches that of valid numbers for this region. */
   IS_POSSIBLE: 0,
+  /**
+   * The number length matches that of local numbers for this region only (i.e. numbers that may
+   * be able to be dialled within an area, but do not have all the information to be dialled from
+   * anywhere inside or outside the country).
+   */
+  IS_POSSIBLE_LOCAL_ONLY: 4,
+  /** The number has an invalid country calling code. */
   INVALID_COUNTRY_CODE: 1,
+  /** The number is shorter than all valid numbers for this region. */
   TOO_SHORT: 2,
+  /**
+   * 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.
+   */
+  INVALID_LENGTH: 5,
+  /** The number is longer than all valid numbers for this region. */
   TOO_LONG: 3
 };