Minor update to documentation in PhoneNumberUtil (#1838)

CONTRIBUTORS

@@ -4,7 +4,7 @@
 # but not in AUTHORS, because Google holds the copyright.
 
 # Core team:
-# 
+#
 # These people were responsible for the initial implementations in Java and
 # C++, and carry out the bulk of metadata maintenance, bug fixes & feature
 # requests, and porting new features to Javascript.

cpp/src/phonenumbers/phonenumberutil.cc

@@ -12,9 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Author: Shaopeng Jia
-// Open-sourced by: Philippe Liard
-
 #include "phonenumbers/phonenumberutil.h"
 
 #include <string.h>
@@ -63,6 +60,13 @@ const int PhoneNumberUtil::kNanpaCountryCode;
 
 // static
 const char PhoneNumberUtil::kPlusChars[] = "+\xEF\xBC\x8B";  /* "+＋" */
+// Regular expression of acceptable punctuation found in phone numbers, used to
+// find numbers in text and to decide what is a viable phone number. This
+// excludes diallable characters.
+// This consists of dash characters, white space characters, full stops,
+// slashes, square brackets, parentheses and tildes. It also includes the letter
+// 'x' as that is found as a placeholder for carrier information in some phone
+// numbers. Full-width variants are also present.
 // To find out the unicode code-point of the characters below in vim, highlight
 // the character and type 'ga'. Note that the - is used to express ranges of
 // full-width punctuation below, as well as being present in the expression
@@ -613,14 +617,14 @@ class PhoneNumberRegExpsAndMappings {
   // find geographical mobile numbers or hear from user reports.
   set<int> geo_mobile_countries_;
 
-  // Pattern that makes it easy to distinguish whether a region has a unique
-  // international dialing prefix or not. If a region has a unique international
+  // Pattern that makes it easy to distinguish whether a region has a single
+  // international dialing prefix or not. If a region has a single international
   // prefix (e.g. 011 in USA), it will be represented as a string that contains
-  // a sequence of ASCII digits. If there are multiple available international
-  // prefixes in a region, they will be represented as a regex string that
-  // always contains character(s) other than ASCII digits.
-  // Note this regex also includes tilde, which signals waiting for the tone.
-  scoped_ptr<const RegExp> unique_international_prefix_;
+  // a sequence of ASCII digits, and possibly a tilde, which signals waiting for
+  // the tone. If there are multiple available international prefixes in a
+  // region, they will be represented as a regex string that always contains one
+  // or more characters that are not ASCII digits or a tilde.
+  scoped_ptr<const RegExp> single_international_prefix_;
 
   scoped_ptr<const RegExp> digits_pattern_;
   scoped_ptr<const RegExp> capturing_digit_pattern_;
@@ -695,7 +699,7 @@ class PhoneNumberRegExpsAndMappings {
         mobile_token_mappings_(),
         geo_mobile_countries_without_mobile_area_codes_(),
         geo_mobile_countries_(),
-        unique_international_prefix_(regexp_factory_->CreateRegExp(
+        single_international_prefix_(regexp_factory_->CreateRegExp(
             /* "[\\d]+(?:[~⁓∼～][\\d]+)?" */
             "[\\d]+(?:[~\xE2\x81\x93\xE2\x88\xBC\xEF\xBD\x9E][\\d]+)?")),
         digits_pattern_(
@@ -1307,7 +1311,7 @@ void PhoneNumberUtil::FormatOutOfCountryCallingNumber(
   // format of the number is returned, unless there is a preferred international
   // prefix.
   const string international_prefix_for_formatting(
-      reg_exps_->unique_international_prefix_->FullMatch(international_prefix)
+      reg_exps_->single_international_prefix_->FullMatch(international_prefix)
       ? international_prefix
       : metadata_calling_from->preferred_international_prefix());
 
@@ -1557,7 +1561,7 @@ void PhoneNumberUtil::FormatOutOfCountryKeepingAlphaChars(
   if (metadata) {
     const string& international_prefix = metadata->international_prefix();
     international_prefix_for_formatting =
-        reg_exps_->unique_international_prefix_->FullMatch(international_prefix)
+        reg_exps_->single_international_prefix_->FullMatch(international_prefix)
         ? international_prefix
         : metadata->preferred_international_prefix();
   }

cpp/src/phonenumbers/phonenumberutil.h

@@ -13,9 +13,6 @@
 // limitations under the License.
 
 // Utility for international phone numbers.
-//
-// Author: Shaopeng Jia
-// Open-sourced by: Philippe Liard
 
 #ifndef I18N_PHONENUMBERS_PHONENUMBERUTIL_H_
 #define I18N_PHONENUMBERS_PHONENUMBERUTIL_H_

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

@@ -46,14 +46,12 @@ import java.util.regex.Pattern;
  * validation.
  *
  * <p>If you use this library, and want to be notified about important changes, please sign up to
- * our <a href="http://groups.google.com/group/libphonenumber-discuss/about">mailing list</a>.
+ * our <a href="https://groups.google.com/forum/#!aboutgroup/libphonenumber-discuss">mailing list</a>.
  *
  * NOTE: A lot of methods in this class require Region Code strings. These must be provided using
  * CLDR two-letter region-code format. These should be in upper-case. The list of the codes
  * can be found here:
  * http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html
- *
- * @author Shaopeng Jia
  */
 public class PhoneNumberUtil {
   private static final Logger logger = Logger.getLogger(PhoneNumberUtil.class.getName());
@@ -223,17 +221,17 @@ public class PhoneNumberUtil {
     ALL_PLUS_NUMBER_GROUPING_SYMBOLS = Collections.unmodifiableMap(allPlusNumberGroupings);
   }
 
-  // Pattern that makes it easy to distinguish whether a region has a unique international dialing
-  // prefix or not. If a region has a unique international prefix (e.g. 011 in USA), it will be
-  // represented as a string that contains a sequence of ASCII digits. If there are multiple
-  // available international prefixes in a region, they will be represented as a regex string that
-  // always contains character(s) other than ASCII digits.
-  // Note this regex also includes tilde, which signals waiting for the tone.
-  private static final Pattern UNIQUE_INTERNATIONAL_PREFIX =
+  // Pattern that makes it easy to distinguish whether a region has a single international dialing
+  // prefix or not. If a region has a single international prefix (e.g. 011 in USA), it will be
+  // represented as a string that contains a sequence of ASCII digits, and possibly a tilde, which
+  // signals waiting for the tone. If there are multiple available international prefixes in a
+  // region, they will be represented as a regex string that always contains one or more characters
+  // that are not ASCII digits or a tilde.
+  private static final Pattern SINGLE_INTERNATIONAL_PREFIX =
       Pattern.compile("[\\d]+(?:[~\u2053\u223C\uFF5E][\\d]+)?");
 
-  // Regular expression of acceptable punctuation found in phone numbers. This excludes punctuation
-  // found as a leading character only.
+  // Regular expression of acceptable punctuation found in phone numbers, used to find numbers in
+  // text and to decide what is a viable phone number. This excludes diallable characters.
   // This consists of dash characters, white space characters, full stops, slashes,
   // square brackets, parentheses and tildes. It also includes the letter 'x' as that is found as a
   // placeholder for carrier information in some phone numbers. Full-width variants are also
@@ -1503,7 +1501,7 @@ public class PhoneNumberUtil {
     // For regions that have multiple international prefixes, the international format of the
     // number is returned, unless there is a preferred international prefix.
     String internationalPrefixForFormatting = "";
-    if (UNIQUE_INTERNATIONAL_PREFIX.matcher(internationalPrefix).matches()) {
+    if (SINGLE_INTERNATIONAL_PREFIX.matcher(internationalPrefix).matches()) {
       internationalPrefixForFormatting = internationalPrefix;
     } else if (metadataForRegionCallingFrom.hasPreferredInternationalPrefix()) {
       internationalPrefixForFormatting =
@@ -1768,7 +1766,7 @@ public class PhoneNumberUtil {
     if (metadataForRegionCallingFrom != null) {
       String internationalPrefix = metadataForRegionCallingFrom.getInternationalPrefix();
       internationalPrefixForFormatting =
-          UNIQUE_INTERNATIONAL_PREFIX.matcher(internationalPrefix).matches()
+          SINGLE_INTERNATIONAL_PREFIX.matcher(internationalPrefix).matches()
           ? internationalPrefix
           : metadataForRegionCallingFrom.getPreferredInternationalPrefix();
     }

javascript/i18n/phonenumbers/phonenumberutil.js

@@ -24,8 +24,6 @@
  * be provided using CLDR two-letter region-code format. These should be in
  * upper-case. The list of the codes can be found here:
  * http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html
- *
- * Credits to Nikolaos Trogkanis for original implementation.
  */
 
 goog.provide('i18n.phonenumbers.Error');
@@ -524,30 +522,32 @@ i18n.phonenumbers.PhoneNumberUtil.ALL_PLUS_NUMBER_GROUPING_SYMBOLS_ = {
 };
 
 
+
 /**
- * Pattern that makes it easy to distinguish whether a region has a unique
- * international dialing prefix or not. If a region has a unique international
- * prefix (e.g. 011 in USA), it will be represented as a string that contains a
- * sequence of ASCII digits. If there are multiple available international
- * prefixes in a region, they will be represented as a regex string that always
- * contains character(s) other than ASCII digits. Note this regex also includes
- * tilde, which signals waiting for the tone.
+ * Pattern that makes it easy to distinguish whether a region has a single
+ * international dialing prefix or not. If a region has a single international
+ * prefix (e.g. 011 in USA), it will be represented as a string that contains
+ * a sequence of ASCII digits, and possibly a tilde, which signals waiting for
+ * the tone. If there are multiple available international prefixes in a
+ * region, they will be represented as a regex string that always contains one
+ * or more characters that are not ASCII digits or a tilde.
  *
  * @const
  * @type {!RegExp}
  * @private
  */
-i18n.phonenumbers.PhoneNumberUtil.UNIQUE_INTERNATIONAL_PREFIX_ =
+i18n.phonenumbers.PhoneNumberUtil.SINGLE_INTERNATIONAL_PREFIX_ =
     /[\d]+(?:[~\u2053\u223C\uFF5E][\d]+)?/;
 
 
 /**
- * Regular expression of acceptable punctuation found in phone numbers. This
- * excludes punctuation found as a leading character only. This consists of dash
- * characters, white space characters, full stops, slashes, square brackets,
- * parentheses and tildes. It also includes the letter 'x' as that is found as a
- * placeholder for carrier information in some phone numbers. Full-width
- * variants are also present.
+ * Regular expression of acceptable punctuation found in phone numbers, used to
+ * find numbers in text and to decide what is a viable phone number. This
+ * excludes diallable characters.
+ * This consists of dash characters, white space characters, full stops,
+ * slashes, square brackets, parentheses and tildes. It also includes the letter
+ * 'x' as that is found as a placeholder for carrier information in some phone
+ * numbers. Full-width variants are also present.
  *
  * @const
  * @type {string}
@@ -2049,7 +2049,7 @@ i18n.phonenumbers.PhoneNumberUtil.prototype.formatOutOfCountryCallingNumber =
   /** @type {string} */
   var internationalPrefixForFormatting = '';
   if (i18n.phonenumbers.PhoneNumberUtil.matchesEntirely_(
-      i18n.phonenumbers.PhoneNumberUtil.UNIQUE_INTERNATIONAL_PREFIX_,
+      i18n.phonenumbers.PhoneNumberUtil.SINGLE_INTERNATIONAL_PREFIX_,
       internationalPrefix)) {
     internationalPrefixForFormatting = internationalPrefix;
   } else if (metadataForRegionCallingFrom.hasPreferredInternationalPrefix()) {
@@ -2389,7 +2389,7 @@ i18n.phonenumbers.PhoneNumberUtil.prototype.
         metadataForRegionCallingFrom.getInternationalPrefixOrDefault();
     internationalPrefixForFormatting =
         i18n.phonenumbers.PhoneNumberUtil.matchesEntirely_(
-            i18n.phonenumbers.PhoneNumberUtil.UNIQUE_INTERNATIONAL_PREFIX_,
+            i18n.phonenumbers.PhoneNumberUtil.SINGLE_INTERNATIONAL_PREFIX_,
             internationalPrefix) ?
         internationalPrefix :
         metadataForRegionCallingFrom.getPreferredInternationalPrefixOrDefault();

pending_code_changes.txt

@@ -1 +1,4 @@
-
+Code changes:
+ - Documentation update for private variables VALID_PUNCTUATION and
+   SINGLE_INTERNATIONAL_PREFIX, also renaming the latter from
+   UNIQUE_INTERNATIONAL_PREFIX.