From 921bcfc6efc4b1e41304d4200dc032abaebcff97 Mon Sep 17 00:00:00 2001
From: lararennie <lararennie@users.noreply.github.com>
Date: Fri, 10 Feb 2017 10:39:49 +0100
Subject: [PATCH] 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           | 13 +++++++++++++
 .../i18n/phonenumbers/PhoneNumberUtil.java       | 16 ++++++++++++++++
 java/pending_code_changes.txt                    |  9 ++++++++-
 javascript/i18n/phonenumbers/phonenumberutil.js  | 16 ++++++++++++++++
 4 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/cpp/src/phonenumbers/phonenumberutil.h b/cpp/src/phonenumbers/phonenumberutil.h
index 20134133f..0b44fe682 100644
--- a/cpp/src/phonenumbers/phonenumberutil.h
+++ b/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,
   };
 
diff --git a/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java b/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java
index b03f068b7..68961c43a 100644
--- a/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java
+++ b/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,
   }
 
diff --git a/java/pending_code_changes.txt b/java/pending_code_changes.txt
index 8b1378917..f51397c7c 100644
--- a/java/pending_code_changes.txt
+++ b/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.
diff --git a/javascript/i18n/phonenumbers/phonenumberutil.js b/javascript/i18n/phonenumbers/phonenumberutil.js
index 7b7b46c3d..89345ca6d 100644
--- a/javascript/i18n/phonenumbers/phonenumberutil.js
+++ b/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
 };