Adding a new enum for CountryCodeSource UNSPECIFIED (#1829)

This enum won't be noticed by most users, because the country_code_source field of the phone number is only populated with ParseAndKeepRawInput, and in this case, this enum won't be used.

However, it provides a better result for users who incorrectly call parse() and then getCountryCodeSource() and expect to get a sensible answer; now they will get UNSPECIFIED instead of FROM_NUMBER_WITH_PLUS_SIGN which was the default before. In JS this method returns null, but getCountryCodeSourceOrDefault() will now return UNSPECIFIED instead.

The numeric values of the existing enums have not changed (relevant for JS and C++) and in Java the new enum was added to the end so that any stored serialized phone numbers should be able to be restored as they were before.

Suggested in issue #1218

cpp/test/phonenumbers/phonenumberutil_test.cc

@@ -3492,6 +3492,10 @@ TEST_F(PhoneNumberUtilTest, ParseNationalNumber) {
   EXPECT_EQ(PhoneNumberUtil::NO_PARSING_ERROR,
             phone_util_.Parse("033316005", RegionCode::NZ(), &test_number));
   EXPECT_EQ(nz_number, test_number);
+  // Some fields are not filled in by Parse, but only by ParseAndKeepRawInput.
+  EXPECT_FALSE(nz_number.has_country_code_source());
+  EXPECT_EQ(PhoneNumber::UNSPECIFIED, nz_number.country_code_source());
+
   // National prefix missing.
   EXPECT_EQ(PhoneNumberUtil::NO_PARSING_ERROR,
             phone_util_.Parse("33316005", RegionCode::NZ(), &test_number));

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

@@ -32,11 +32,12 @@ public final class Phonenumber {
       FROM_NUMBER_WITH_PLUS_SIGN,
       FROM_NUMBER_WITH_IDD,
       FROM_NUMBER_WITHOUT_PLUS_SIGN,
-      FROM_DEFAULT_COUNTRY
+      FROM_DEFAULT_COUNTRY,
+      UNSPECIFIED
     }
 
     public PhoneNumber() {
-      countryCodeSource_ = CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN;
+      countryCodeSource_ = CountryCodeSource.UNSPECIFIED;
     }
 
     // required int32 country_code = 1;
@@ -156,7 +157,7 @@ public final class Phonenumber {
     }
     public PhoneNumber clearCountryCodeSource() {
       hasCountryCodeSource = false;
-      countryCodeSource_ = CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN;
+      countryCodeSource_ = CountryCodeSource.UNSPECIFIED;
       return this;
     }
 

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

@@ -2045,6 +2045,10 @@ public class PhoneNumberUtilTest extends TestMetadataTestCase {
   public void testParseNationalNumber() throws Exception {
     // National prefix attached.
     assertEquals(NZ_NUMBER, phoneUtil.parse("033316005", RegionCode.NZ));
+    // Some fields are not filled in by parse, but only by parseAndKeepRawInput.
+    assertFalse(NZ_NUMBER.hasCountryCodeSource());
+    assertEquals(CountryCodeSource.UNSPECIFIED, NZ_NUMBER.getCountryCodeSource());
+
     assertEquals(NZ_NUMBER, phoneUtil.parse("33316005", RegionCode.NZ));
     // National prefix attached and some formatting present.
     assertEquals(NZ_NUMBER, phoneUtil.parse("03-331 6005", RegionCode.NZ));

javascript/i18n/phonenumbers/demo-compiled.js

@@ -2,7 +2,7 @@
 function ca(a,b){if(b){for(var c=ba,d=a.split("."),e=0;e<d.length-1;e++){var f=d[e];f in c||(c[f]={});c=c[f]}d=d[d.length-1];e=c[d];f=b(e);f!=e&&null!=f&&aa(c,d,{configurable:!0,writable:!0,value:f})}}
 ca("String.prototype.repeat",function(a){return a?a:function(a){var b;if(null==this)throw new TypeError("The 'this' value for String.prototype.repeat must not be null or undefined");b=this+"";if(0>a||1342177279<a)throw new RangeError("Invalid count value");a|=0;for(var d="";a;)if(a&1&&(d+=b),a>>>=1)b+=b;return d}});ca("Math.sign",function(a){return a?a:function(a){a=Number(a);return!a||isNaN(a)?a:0<a?1:-1}});
 function da(a){var b=typeof a;if("object"==b)if(a){if(a instanceof Array)return"array";if(a instanceof Object)return b;var c=Object.prototype.toString.call(a);if("[object Window]"==c)return"object";if("[object Array]"==c||"number"==typeof a.length&&"undefined"!=typeof a.splice&&"undefined"!=typeof a.propertyIsEnumerable&&!a.propertyIsEnumerable("splice"))return"array";if("[object Function]"==c||"undefined"!=typeof a.call&&"undefined"!=typeof a.propertyIsEnumerable&&!a.propertyIsEnumerable("call"))return"function"}else return"null";
-else if("function"==b&&"undefined"==typeof a.call)return"object";return b}function k(a){return"string"==typeof a}function m(a,b){function c(){}c.prototype=b.prototype;a.ha=b.prototype;a.prototype=new c;a.prototype.constructor=a;a.ma=function(a,c,f){for(var d=Array(arguments.length-2),e=2;e<arguments.length;e++)d[e-2]=arguments[e];return b.prototype[c].apply(a,d)}};function n(a){if(Error.captureStackTrace)Error.captureStackTrace(this,n);else{var b=Error().stack;b&&(this.stack=b)}a&&(this.message=String(a))}m(n,Error);n.prototype.name="CustomError";function ea(a,b){for(var c=a.split("%s"),d="",e=Array.prototype.slice.call(arguments,1);e.length&&1<c.length;)d+=c.shift()+e.shift();return d+c.join("%s")};function fa(a,b){b.unshift(a);n.call(this,ea.apply(null,b));b.shift()}m(fa,n);fa.prototype.name="AssertionError";function ga(a,b){throw new fa("Failure"+(a?": "+a:""),Array.prototype.slice.call(arguments,1));};var p=Array.prototype.indexOf?function(a,b,c){return Array.prototype.indexOf.call(a,b,c)}:function(a,b,c){c=null==c?0:0>c?Math.max(0,a.length+c):c;if(k(a))return k(b)&&1==b.length?a.indexOf(b,c):-1;for(;c<a.length;c++)if(c in a&&a[c]===b)return c;return-1};function ha(a,b){a.sort(b||ia)}function ia(a,b){return a>b?1:a<b?-1:0};function ja(a){var b=[],c=0,d;for(d in a)b[c++]=a[d];return b}function ka(a,b){var c;a:{for(c in a)if(b.call(void 0,a[c],c,a))break a;c=void 0}return c&&a[c]};function q(a){var b=document;return k(a)?b.getElementById(a):a};function la(a){var b=[];ma(new na,a,b);return b.join("")}function na(){}
+else if("function"==b&&"undefined"==typeof a.call)return"object";return b}function k(a){return"string"==typeof a}function m(a,b){function c(){}c.prototype=b.prototype;a.ha=b.prototype;a.prototype=new c;a.prototype.constructor=a;a.na=function(a,c,f){for(var d=Array(arguments.length-2),e=2;e<arguments.length;e++)d[e-2]=arguments[e];return b.prototype[c].apply(a,d)}};function n(a){if(Error.captureStackTrace)Error.captureStackTrace(this,n);else{var b=Error().stack;b&&(this.stack=b)}a&&(this.message=String(a))}m(n,Error);n.prototype.name="CustomError";function ea(a,b){for(var c=a.split("%s"),d="",e=Array.prototype.slice.call(arguments,1);e.length&&1<c.length;)d+=c.shift()+e.shift();return d+c.join("%s")};function fa(a,b){b.unshift(a);n.call(this,ea.apply(null,b));b.shift()}m(fa,n);fa.prototype.name="AssertionError";function ga(a,b){throw new fa("Failure"+(a?": "+a:""),Array.prototype.slice.call(arguments,1));};var p=Array.prototype.indexOf?function(a,b,c){return Array.prototype.indexOf.call(a,b,c)}:function(a,b,c){c=null==c?0:0>c?Math.max(0,a.length+c):c;if(k(a))return k(b)&&1==b.length?a.indexOf(b,c):-1;for(;c<a.length;c++)if(c in a&&a[c]===b)return c;return-1};function ha(a,b){a.sort(b||ia)}function ia(a,b){return a>b?1:a<b?-1:0};function ja(a){var b=[],c=0,d;for(d in a)b[c++]=a[d];return b}function ka(a,b){var c;a:{for(c in a)if(b.call(void 0,a[c],c,a))break a;c=void 0}return c&&a[c]};function q(a){var b=document;return k(a)?b.getElementById(a):a};function la(a){var b=[];ma(new na,a,b);return b.join("")}function na(){}
 function ma(a,b,c){if(null==b)c.push("null");else{if("object"==typeof b){if("array"==da(b)){var d=b;b=d.length;c.push("[");for(var e="",f=0;f<b;f++)c.push(e),ma(a,d[f],c),e=",";c.push("]");return}if(b instanceof String||b instanceof Number||b instanceof Boolean)b=b.valueOf();else{c.push("{");e="";for(d in b)Object.prototype.hasOwnProperty.call(b,d)&&(f=b[d],"function"!=typeof f&&(c.push(e),oa(d,c),c.push(":"),ma(a,f,c),e=","));c.push("}");return}}switch(typeof b){case "string":oa(b,c);break;case "number":c.push(isFinite(b)&&
 !isNaN(b)?String(b):"null");break;case "boolean":c.push(String(b));break;case "function":c.push("null");break;default:throw Error("Unknown type: "+typeof b);}}}var pa={'"':'\\"',"\\":"\\\\","/":"\\/","\b":"\\b","\f":"\\f","\n":"\\n","\r":"\\r","\t":"\\t","\x0B":"\\u000b"},qa=/\uffff/.test("\uffff")?/[\\\"\x00-\x1f\x7f-\uffff]/g:/[\\\"\x00-\x1f\x7f-\xff]/g;
 function oa(a,b){b.push('"',a.replace(qa,function(a){var b=pa[a];b||(b="\\u"+(a.charCodeAt(0)|65536).toString(16).substr(1),pa[a]=b);return b}),'"')};function ra(a,b){this.a=a;this.l=b.name;this.f=!!b.u;this.b=b.c;this.j=b.type;this.i=!1;switch(this.b){case sa:case ta:case ua:case va:case wa:case xa:case ya:this.i=!0}this.g=b.defaultValue}var ya=1,xa=2,sa=3,ta=4,ua=6,va=16,wa=18;function za(a,b){this.b=a;this.a={};for(var c=0;c<b.length;c++){var d=b[c];this.a[d.a]=d}}function Aa(a){a=ja(a.a);ha(a,function(a,c){return a.a-c.a});return a}function Ba(a,b){return ka(a.a,function(a){return a.l==b})||null};function r(){this.b={};this.f=this.h().a;this.a=this.g=null}function Ca(a,b){for(var c in a.b){var d=Number(c);a.f[d]||b.call(a,d,a.b[c])}}r.prototype.has=function(a){return t(this,a.a)};r.prototype.get=function(a,b){return u(this,a.a,b)};r.prototype.set=function(a,b){v(this,a.a,b)};
@@ -33,9 +33,9 @@ E.prototype.h=function(){var a=Ja;a||(Ja=a=Ha(E,{0:{name:"NumberFormat",ba:"i18n
 F.prototype.h=function(){var a=Ka;a||(Ka=a=Ha(F,{0:{name:"PhoneNumberDesc",ba:"i18n.phonenumbers.PhoneNumberDesc"},2:{name:"national_number_pattern",c:9,type:String},3:{name:"possible_number_pattern",c:9,type:String},9:{name:"possible_length",u:!0,c:5,type:Number},10:{name:"possible_length_local_only",u:!0,c:5,type:Number},6:{name:"example_number",c:9,type:String},7:{name:"national_number_matcher_data",c:12,type:String}}));return a};F.h=F.prototype.h;
 G.prototype.h=function(){var a=La;a||(La=a=Ha(G,{0:{name:"PhoneMetadata",ba:"i18n.phonenumbers.PhoneMetadata"},1:{name:"general_desc",c:11,type:F},2:{name:"fixed_line",c:11,type:F},3:{name:"mobile",c:11,type:F},4:{name:"toll_free",c:11,type:F},5:{name:"premium_rate",c:11,type:F},6:{name:"shared_cost",c:11,type:F},7:{name:"personal_number",c:11,type:F},8:{name:"voip",c:11,type:F},21:{name:"pager",c:11,type:F},25:{name:"uan",c:11,type:F},27:{name:"emergency",c:11,type:F},28:{name:"voicemail",c:11,type:F},
 24:{name:"no_international_dialling",c:11,type:F},9:{name:"id",required:!0,c:9,type:String},10:{name:"country_code",c:5,type:Number},11:{name:"international_prefix",c:9,type:String},17:{name:"preferred_international_prefix",c:9,type:String},12:{name:"national_prefix",c:9,type:String},13:{name:"preferred_extn_prefix",c:9,type:String},15:{name:"national_prefix_for_parsing",c:9,type:String},16:{name:"national_prefix_transform_rule",c:9,type:String},18:{name:"same_mobile_and_fixed_line_pattern",c:8,defaultValue:!1,
-type:Boolean},19:{name:"number_format",u:!0,c:11,type:E},20:{name:"intl_number_format",u:!0,c:11,type:E},22:{name:"main_country_for_code",c:8,defaultValue:!1,type:Boolean},23:{name:"leading_digits",c:9,type:String},26:{name:"leading_zero_possible",c:8,defaultValue:!1,type:Boolean}}));return a};G.h=G.prototype.h;function Ma(){}m(Ma,A);Ma.prototype.f=function(a,b){var c=new a.b;c.g=this;c.b=b;c.a={};return c};Ma.prototype.i=function(){throw Error("Unimplemented");};function H(){}m(H,Ma);H.prototype.g=function(a){for(var b=Aa(a.h()),c=[],d=0;d<b.length;d++){var e=b[d];if(a.has(e)){var f=e.a;if(e.f){c[f]=[];for(var g=0;g<z(a,e.a);g++)c[f][g]=this.b(e,a.get(e,g))}else c[f]=this.b(e,a.get(e))}}Ca(a,function(a,b){c[a]=b});return c};H.prototype.b=function(a,b){return 8==a.b?b?1:0:A.prototype.b.apply(this,arguments)};H.prototype.a=function(a,b){return 8==a.b?!!b:A.prototype.a.apply(this,arguments)};function I(){r.call(this)}var Na;m(I,r);var Oa={la:1,ka:5,ja:10,ia:20};
-I.prototype.h=function(){Na||(Na=Ha(I,{0:{name:"PhoneNumber",ba:"i18n.phonenumbers.PhoneNumber"},1:{name:"country_code",required:!0,c:5,type:Number},2:{name:"national_number",required:!0,c:4,type:Number},3:{name:"extension",c:9,type:String},4:{name:"italian_leading_zero",c:8,type:Boolean},8:{name:"number_of_leading_zeros",c:5,defaultValue:1,type:Number},5:{name:"raw_input",c:9,type:String},6:{name:"country_code_source",c:14,defaultValue:1,type:Oa},7:{name:"preferred_domestic_carrier_code",c:9,type:String}}));
-return Na};I.ctor=I;I.ctor.h=I.prototype.h;/*
+type:Boolean},19:{name:"number_format",u:!0,c:11,type:E},20:{name:"intl_number_format",u:!0,c:11,type:E},22:{name:"main_country_for_code",c:8,defaultValue:!1,type:Boolean},23:{name:"leading_digits",c:9,type:String},26:{name:"leading_zero_possible",c:8,defaultValue:!1,type:Boolean}}));return a};G.h=G.prototype.h;function Ma(){}m(Ma,A);Ma.prototype.f=function(a,b){var c=new a.b;c.g=this;c.b=b;c.a={};return c};Ma.prototype.i=function(){throw Error("Unimplemented");};function H(){}m(H,Ma);H.prototype.g=function(a){for(var b=Aa(a.h()),c=[],d=0;d<b.length;d++){var e=b[d];if(a.has(e)){var f=e.a;if(e.f){c[f]=[];for(var g=0;g<z(a,e.a);g++)c[f][g]=this.b(e,a.get(e,g))}else c[f]=this.b(e,a.get(e))}}Ca(a,function(a,b){c[a]=b});return c};H.prototype.b=function(a,b){return 8==a.b?b?1:0:A.prototype.b.apply(this,arguments)};H.prototype.a=function(a,b){return 8==a.b?!!b:A.prototype.a.apply(this,arguments)};function I(){r.call(this)}m(I,r);var Na=null,Oa={ma:0,la:1,ka:5,ja:10,ia:20};
+I.prototype.h=function(){var a=Na;a||(Na=a=Ha(I,{0:{name:"PhoneNumber",ba:"i18n.phonenumbers.PhoneNumber"},1:{name:"country_code",required:!0,c:5,type:Number},2:{name:"national_number",required:!0,c:4,type:Number},3:{name:"extension",c:9,type:String},4:{name:"italian_leading_zero",c:8,type:Boolean},8:{name:"number_of_leading_zeros",c:5,defaultValue:1,type:Number},5:{name:"raw_input",c:9,type:String},6:{name:"country_code_source",c:14,defaultValue:0,type:Oa},7:{name:"preferred_domestic_carrier_code",
+c:9,type:String}}));return a};I.ctor=I;I.ctor.h=I.prototype.h;/*
 
  Copyright (C) 2010 The Libphonenumber Authors
 

javascript/i18n/phonenumbers/phonenumber.pb.js

@@ -33,6 +33,7 @@ goog.require('goog.proto2.Message');
  * Message PhoneNumber.
  * @constructor
  * @extends {goog.proto2.Message}
+ * @final
  */
 i18n.phonenumbers.PhoneNumber = function() {
   goog.proto2.Message.call(this);
@@ -40,6 +41,13 @@ i18n.phonenumbers.PhoneNumber = function() {
 goog.inherits(i18n.phonenumbers.PhoneNumber, goog.proto2.Message);
 
 
+/**
+ * Descriptor for this message, deserialized lazily in getDescriptor().
+ * @private {?goog.proto2.Descriptor}
+ */
+i18n.phonenumbers.PhoneNumber.descriptor_ = null;
+
+
 /**
  * Overrides {@link goog.proto2.Message#clone} to specify its exact return type.
  * @return {!i18n.phonenumbers.PhoneNumber} The cloned message.
@@ -365,16 +373,16 @@ i18n.phonenumbers.PhoneNumber.prototype.getCountryCodeSource = function() {
 
 /**
  * Gets the value of the country_code_source field or the default value if not set.
- * @return {i18n.phonenumbers.PhoneNumber.CountryCodeSource} The value.
+ * @return {!i18n.phonenumbers.PhoneNumber.CountryCodeSource} The value.
  */
 i18n.phonenumbers.PhoneNumber.prototype.getCountryCodeSourceOrDefault = function() {
-  return /** @type {i18n.phonenumbers.PhoneNumber.CountryCodeSource} */ (this.get$ValueOrDefault(6));
+  return /** @type {!i18n.phonenumbers.PhoneNumber.CountryCodeSource} */ (this.get$ValueOrDefault(6));
 };
 
 
 /**
  * Sets the value of the country_code_source field.
- * @param {i18n.phonenumbers.PhoneNumber.CountryCodeSource} value The value.
+ * @param {!i18n.phonenumbers.PhoneNumber.CountryCodeSource} value The value.
  */
 i18n.phonenumbers.PhoneNumber.prototype.setCountryCodeSource = function(value) {
   this.set$Value(6, value);
@@ -461,6 +469,7 @@ i18n.phonenumbers.PhoneNumber.prototype.clearPreferredDomesticCarrierCode = func
  * @enum {number}
  */
 i18n.phonenumbers.PhoneNumber.CountryCodeSource = {
+  UNSPECIFIED: 0,
   FROM_NUMBER_WITH_PLUS_SIGN: 1,
   FROM_NUMBER_WITH_IDD: 5,
   FROM_NUMBER_WITHOUT_PLUS_SIGN: 10,
@@ -470,7 +479,8 @@ i18n.phonenumbers.PhoneNumber.CountryCodeSource = {
 
 /** @override */
 i18n.phonenumbers.PhoneNumber.prototype.getDescriptor = function() {
-  if (!i18n.phonenumbers.PhoneNumber.descriptor_) {
+  var descriptor = i18n.phonenumbers.PhoneNumber.descriptor_;
+  if (!descriptor) {
     // The descriptor is created lazily when we instantiate a new instance.
     var descriptorObj = {
       0: {
@@ -513,7 +523,7 @@ i18n.phonenumbers.PhoneNumber.prototype.getDescriptor = function() {
       6: {
         name: 'country_code_source',
         fieldType: goog.proto2.Message.FieldType.ENUM,
-        defaultValue: i18n.phonenumbers.PhoneNumber.CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN,
+        defaultValue: i18n.phonenumbers.PhoneNumber.CountryCodeSource.UNSPECIFIED,
         type: i18n.phonenumbers.PhoneNumber.CountryCodeSource
       },
       7: {
@@ -522,11 +532,11 @@ i18n.phonenumbers.PhoneNumber.prototype.getDescriptor = function() {
         type: String
       }
     };
-    i18n.phonenumbers.PhoneNumber.descriptor_ =
+    i18n.phonenumbers.PhoneNumber.descriptor_ = descriptor =
         goog.proto2.Message.createDescriptor(
              i18n.phonenumbers.PhoneNumber, descriptorObj);
   }
-  return i18n.phonenumbers.PhoneNumber.descriptor_;
+  return descriptor;
 };
 
 

javascript/i18n/phonenumbers/phonenumberutil_test.js

@@ -2647,6 +2647,12 @@ function testMaybeExtractCountryCode() {
 function testParseNationalNumber() {
   // National prefix attached.
   assertTrue(NZ_NUMBER.equals(phoneUtil.parse('033316005', RegionCode.NZ)));
+  // Some fields are not filled in by parse, but only by parseAndKeepRawInput.
+  assertFalse(NZ_NUMBER.hasCountryCodeSource());
+  assertNull(NZ_NUMBER.getCountryCodeSource());
+  assertEquals(i18n.phonenumbers.PhoneNumber.CountryCodeSource.UNSPECIFIED,
+      NZ_NUMBER.getCountryCodeSourceOrDefault());
+
   assertTrue(NZ_NUMBER.equals(phoneUtil.parse('33316005', RegionCode.NZ)));
   // National prefix attached and some formatting present.
   assertTrue(NZ_NUMBER.equals(phoneUtil.parse('03-331 6005', RegionCode.NZ)));

pending_code_changes.txt

@@ -12,3 +12,8 @@ Code changes:
  - Updated the documentation for the isNumberGeographical API.
  - Small comment improvements for parse() method to point users at
    parseAndKeepRawInput().
+ - Added a new enum for CountryCodeSource called UNSPECIFIED. This is used as a
+   default value, and will be returned if someone calls parse() and then
+   getCountryCodeSource() on the result. If users want an actual value for this
+   then they should call parseAndKeepRawInput() instead; the values that were
+   previously returned after calling this method will not change.

resources/phonenumber.proto

@@ -68,7 +68,7 @@ message PhoneNumber {
   // dialling internationally, set this flag to true, and also set the number of
   // leading zeros.
   //
-  // Clients who use the parsing or conversion functionality of the i18n phone
+  // Clients who use the parsing functionality of the i18n phone
   // number libraries will have these fields set if necessary automatically.
   optional bool italian_leading_zero = 4;
   optional int32 number_of_leading_zeros = 8 [ default = 1 ];
@@ -87,6 +87,11 @@ message PhoneNumber {
   // general parsing method, but in the method that parses and keeps raw_input.
   // New fields could be added upon request.
   enum CountryCodeSource {
+    // Default value returned if this is not set, because the phone number was
+    // created using parse, not parseAndKeepRawInput. hasCountryCodeSource will
+    // return false if this is the case.
+    UNSPECIFIED = 0;
+
     // The country_code is derived based on a phone number with a leading "+",
     // e.g. the French number "+33 1 42 68 53 00".
     FROM_NUMBER_WITH_PLUS_SIGN = 1;