From a3aa632a6dab9d51c7fc446e7277724ff3df476f Mon Sep 17 00:00:00 2001 From: Keghani Kouzoujian Date: Thu, 6 Jul 2017 17:29:47 +0200 Subject: [PATCH] Minor update to documentation in PhoneNumberUtil (#1838) --- CONTRIBUTORS | 2 +- cpp/src/phonenumbers/phonenumberutil.cc | 30 +++++++++------- cpp/src/phonenumbers/phonenumberutil.h | 3 -- .../i18n/phonenumbers/PhoneNumberUtil.java | 26 +++++++------- .../i18n/phonenumbers/phonenumberutil.js | 36 +++++++++---------- pending_code_changes.txt | 5 ++- 6 files changed, 52 insertions(+), 50 deletions(-) diff --git a/CONTRIBUTORS b/CONTRIBUTORS index fd5425956..e3f5a8e0a 100644 --- a/CONTRIBUTORS +++ b/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. diff --git a/cpp/src/phonenumbers/phonenumberutil.cc b/cpp/src/phonenumbers/phonenumberutil.cc index 18f20afa1..c9359297c 100644 --- a/cpp/src/phonenumbers/phonenumberutil.cc +++ b/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 @@ -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 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 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 single_international_prefix_; scoped_ptr digits_pattern_; scoped_ptr 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(); } diff --git a/cpp/src/phonenumbers/phonenumberutil.h b/cpp/src/phonenumbers/phonenumberutil.h index 6bce280c3..ad83738f4 100644 --- a/cpp/src/phonenumbers/phonenumberutil.h +++ b/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_ diff --git a/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java b/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java index 6eddb249a..68bbbaee0 100644 --- a/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java +++ b/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java @@ -46,14 +46,12 @@ import java.util.regex.Pattern; * validation. * *

If you use this library, and want to be notified about important changes, please sign up to - * our mailing list. + * our mailing list. * * 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(); } diff --git a/javascript/i18n/phonenumbers/phonenumberutil.js b/javascript/i18n/phonenumbers/phonenumberutil.js index 767c5f41d..7f6363078 100644 --- a/javascript/i18n/phonenumbers/phonenumberutil.js +++ b/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(); diff --git a/pending_code_changes.txt b/pending_code_changes.txt index 8b1378917..2e4986375 100644 --- a/pending_code_changes.txt +++ b/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.