com.google.i18n.phonenumbers
Class PhoneNumberUtil

java.lang.Object
  com.google.i18n.phonenumbers.PhoneNumberUtil

public class PhoneNumberUtil
extends Object

Utility for international phone numbers. Functionality includes formatting, parsing and validation.

Author:

Shaopeng Jia, Lara Rennie

Nested Class Summary

static class	PhoneNumberUtil.Leniency Leniency when finding potential phone numbers in text segments.
static class	PhoneNumberUtil.MatchType Types of phone number matches.
static class	PhoneNumberUtil.PhoneNumberFormat INTERNATIONAL and NATIONAL formats are consistent with the definition in ITU-T Recommendation E.
static class	PhoneNumberUtil.PhoneNumberType Type of phone numbers.
static class	PhoneNumberUtil.ValidationResult Possible outcomes when testing if a PhoneNumber is possible.

Method Summary

static String	convertAlphaCharactersInNumber(String number) Converts all alpha characters in a number to their respective digits on a keypad, but retains existing formatting.
Iterable<PhoneNumberMatch>	findNumbers(CharSequence text, String defaultCountry) Returns an iterable over all PhoneNumberMatches in text.
Iterable<PhoneNumberMatch>	findNumbers(CharSequence text, String defaultCountry, PhoneNumberUtil.Leniency leniency, long maxTries) Returns an iterable over all PhoneNumberMatches in text.
String	format(Phonenumber.PhoneNumber number, PhoneNumberUtil.PhoneNumberFormat numberFormat) Formats a phone number in the specified format using default rules.
void	format(Phonenumber.PhoneNumber number, PhoneNumberUtil.PhoneNumberFormat numberFormat, StringBuffer formattedNumber)
String	formatByPattern(Phonenumber.PhoneNumber number, PhoneNumberUtil.PhoneNumberFormat numberFormat, List<Phonemetadata.NumberFormat> userDefinedFormats) Formats a phone number in the specified format using client-defined formatting rules.
String	formatInOriginalFormat(Phonenumber.PhoneNumber number, String countryCallingFrom) Formats a phone number using the original phone number format that the number is parsed from.
String	formatNationalNumberWithCarrierCode(Phonenumber.PhoneNumber number, String carrierCode) Formats a phone number in national format for dialing using the carrier as specified in the carrierCode.
String	formatNationalNumberWithPreferredCarrierCode(Phonenumber.PhoneNumber number, String fallbackCarrierCode) Formats a phone number in national format for dialing using the carrier as specified in the preferred_domestic_carrier_code field of the PhoneNumber object passed in.
String	formatOutOfCountryCallingNumber(Phonenumber.PhoneNumber number, String countryCallingFrom) Formats a phone number for out-of-country dialing purpose.
AsYouTypeFormatter	getAsYouTypeFormatter(String regionCode) Gets an AsYouTypeFormatter for the specific country.
int	getCountryCodeForRegion(String regionCode) Returns the country calling code for a specific region.
Phonenumber.PhoneNumber	getExampleNumber(String regionCode) Gets a valid number for the specified country.
Phonenumber.PhoneNumber	getExampleNumberForType(String regionCode, PhoneNumberUtil.PhoneNumberType type) Gets a valid number for the specified country and number type.
static PhoneNumberUtil	getInstance() Gets a PhoneNumberUtil instance to carry out international phone number formatting, parsing, or validation.
int	getLengthOfGeographicalAreaCode(Phonenumber.PhoneNumber number) Gets the length of the geographical area code from the national_number field of the PhoneNumber object passed in, so that clients could use it to split a national significant number into geographical area code and subscriber number.
int	getLengthOfNationalDestinationCode(Phonenumber.PhoneNumber number) Gets the length of the national destination code (NDC) from the PhoneNumber object passed in, so that clients could use it to split a national significant number into NDC and subscriber number.
static String	getNationalSignificantNumber(Phonenumber.PhoneNumber number) Gets the national significant number of the a phone number.
String	getNddPrefixForRegion(String regionCode, boolean stripNonDigits) Returns the national dialling prefix for a specific region.
PhoneNumberUtil.PhoneNumberType	getNumberType(Phonenumber.PhoneNumber number) Gets the type of a phone number.
String	getRegionCodeForCountryCode(int countryCode) Returns the region code that matches the specific country code.
String	getRegionCodeForNumber(Phonenumber.PhoneNumber number) Returns the country/region where a phone number is from.
Set<String>	getSupportedCountries() Convenience method to enable tests to get a list of what countries the library has metadata for.
static boolean	isLeadingZeroCountry(int countryCode) Check whether countryCode represents the country calling code from a country whose national significant number could contain a leading zero.
boolean	isNANPACountry(String regionCode) Check if a country is one of the countries under the North American Numbering Plan Administration (NANPA).
PhoneNumberUtil.MatchType	isNumberMatch(Phonenumber.PhoneNumber firstNumberIn, Phonenumber.PhoneNumber secondNumberIn) Takes two phone numbers and compares them for equality.
PhoneNumberUtil.MatchType	isNumberMatch(Phonenumber.PhoneNumber firstNumber, String secondNumber) Takes two phone numbers and compares them for equality.
PhoneNumberUtil.MatchType	isNumberMatch(String firstNumber, String secondNumber) Takes two phone numbers as strings and compares them for equality.
boolean	isPossibleNumber(Phonenumber.PhoneNumber number) Convenience wrapper around isPossibleNumberWithReason.
boolean	isPossibleNumber(String number, String countryDialingFrom) Check whether a phone number is a possible number given a number in the form of a string, and the country where the number could be dialed from.
PhoneNumberUtil.ValidationResult	isPossibleNumberWithReason(Phonenumber.PhoneNumber number) Check whether a phone number is a possible number.
boolean	isValidNumber(Phonenumber.PhoneNumber number) Tests whether a phone number matches a valid pattern.
boolean	isValidNumberForRegion(Phonenumber.PhoneNumber number, String regionCode) Tests whether a phone number is valid for a certain region.
static String	normalizeDigitsOnly(String number) Normalizes a string of characters representing a phone number.
Phonenumber.PhoneNumber	parse(String numberToParse, String defaultCountry) Parses a string and returns it in proto buffer format.
void	parse(String numberToParse, String defaultCountry, Phonenumber.PhoneNumber phoneNumber)
Phonenumber.PhoneNumber	parseAndKeepRawInput(String numberToParse, String defaultCountry) Parses a string and returns it in proto buffer format.
void	parseAndKeepRawInput(String numberToParse, String defaultCountry, Phonenumber.PhoneNumber phoneNumber)
boolean	truncateTooLongNumber(Phonenumber.PhoneNumber number) Attempts to extract a valid number from a phone number that is too long to be valid, and resets the PhoneNumber object passed in to that valid version.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

normalizeDigitsOnly

public static String normalizeDigitsOnly(String number)

Normalizes a string of characters representing a phone number. This converts wide-ascii and arabic-indic numerals to European numerals, and strips punctuation and alpha characters.

Parameters:

number - a string of characters representing a phone number

Returns:

the normalized string version of the phone number

convertAlphaCharactersInNumber

public static String convertAlphaCharactersInNumber(String number)

Converts all alpha characters in a number to their respective digits on a keypad, but retains existing formatting. This Java implementation of this function also converts wide-ascii digits to normal ascii digits, and converts Arabic-Indic numerals to European numerals.

getLengthOfGeographicalAreaCode

public int getLengthOfGeographicalAreaCode(Phonenumber.PhoneNumber number)

Gets the length of the geographical area code from the national_number field of the PhoneNumber object passed in, so that clients could use it to split a national significant number into geographical area code and subscriber number. It works in such a way that the resultant subscriber number should be diallable, at least on some devices. An example of how this could be used: PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance(); PhoneNumber number = phoneUtil.parse("16502530000", "US"); String nationalSignificantNumber = PhoneNumberUtil.getNationalSignificantNumber(number); String areaCode; String subscriberNumber; int areaCodeLength = phoneUtil.getLengthOfGeographicalAreaCode(number); if (areaCodeLength > 0) { areaCode = nationalSignificantNumber.substring(0, areaCodeLength); subscriberNumber = nationalSignificantNumber.substring(areaCodeLength); } else { areaCode = ""; subscriberNumber = nationalSignificantNumber; } N.B.: area code is a very ambiguous concept, so the I18N team generally recommends against using it for most purposes, but recommends using the more general national_number instead. Read the following carefully before deciding to use this method: - geographical area codes change over time, and this method honors those changes; therefore, it doesn't guarantee the stability of the result it produces. - subscriber numbers may not be diallable from all devices (notably mobile devices, which typically requires the full national_number to be dialled in most countries). - most non-geographical numbers have no area codes. - some geographical numbers have no area codes.

Parameters:

number - the PhoneNumber object for which clients want to know the length of the area code.

Returns:

the length of area code of the PhoneNumber object passed in.

getLengthOfNationalDestinationCode

public int getLengthOfNationalDestinationCode(Phonenumber.PhoneNumber number)

Gets the length of the national destination code (NDC) from the PhoneNumber object passed in, so that clients could use it to split a national significant number into NDC and subscriber number. The NDC of a phone number is normally the first group of digit(s) right after the country code when the number is formatted in the international format, if there is a subscriber number part that follows. An example of how this could be used: PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance(); PhoneNumber number = phoneUtil.parse("18002530000", "US"); String nationalSignificantNumber = PhoneNumberUtil.getNationalSignificantNumber(number); String nationalDestinationCode; String subscriberNumber; int nationalDestinationCodeLength = phoneUtil.getLengthOfNationalDestinationCode(number); if (nationalDestinationCodeLength > 0) { nationalDestinationCode = nationalSignificantNumber.substring(0, nationalDestinationCodeLength); subscriberNumber = nationalSignificantNumber.substring(nationalDestinationCodeLength); } else { nationalDestinationCode = ""; subscriberNumber = nationalSignificantNumber; } Refer to the unittests to see the difference between this function and getLengthOfGeographicalAreaCode().

Parameters:

number - the PhoneNumber object for which clients want to know the length of the NDC.

Returns:

the length of NDC of the PhoneNumber object passed in.

getSupportedCountries

public Set<String> getSupportedCountries()

Convenience method to enable tests to get a list of what countries the library has metadata for.

getInstance

public static PhoneNumberUtil getInstance()

Gets a PhoneNumberUtil instance to carry out international phone number formatting, parsing, or validation. The instance is loaded with phone number metadata for a number of most commonly used countries/regions. The PhoneNumberUtil is implemented as a singleton. Therefore, calling getInstance multiple times will only result in one instance being created.

Returns:

a PhoneNumberUtil instance

format

public String format(Phonenumber.PhoneNumber number,
                     PhoneNumberUtil.PhoneNumberFormat numberFormat)

Formats a phone number in the specified format using default rules. Note that this does not promise to produce a phone number that the user can dial from where they are - although we do format in either 'national' or 'international' format depending on what the client asks for, we do not currently support a more abbreviated format, such as for users in the same "area" who could potentially dial the number without area code. Note that if the phone number has a country code of 0 or an otherwise invalid country code, we cannot work out which formatting rules to apply so we return the national significant number with no formatting applied.

Parameters:

number - the phone number to be formatted

numberFormat - the format the phone number should be formatted into

Returns:

the formatted phone number

format

public void format(Phonenumber.PhoneNumber number,
                   PhoneNumberUtil.PhoneNumberFormat numberFormat,
                   StringBuffer formattedNumber)

formatByPattern

public String formatByPattern(Phonenumber.PhoneNumber number,
                              PhoneNumberUtil.PhoneNumberFormat numberFormat,
                              List<Phonemetadata.NumberFormat> userDefinedFormats)

Formats a phone number in the specified format using client-defined formatting rules. Note that if the phone number has a country code of zero or an otherwise invalid country code, we cannot work out things like whether there should be a national prefix applied, or how to format extensions, so we return the national significant number with no formatting applied.

Parameters:

number - the phone number to be formatted

numberFormat - the format the phone number should be formatted into

userDefinedFormats - formatting rules specified by clients

Returns:

the formatted phone number

formatNationalNumberWithCarrierCode

public String formatNationalNumberWithCarrierCode(Phonenumber.PhoneNumber number,
                                                  String carrierCode)

Formats a phone number in national format for dialing using the carrier as specified in the carrierCode. The carrierCode will always be used regardless of whether the phone number already has a preferred domestic carrier code stored. If carrierCode contains an empty string, return the number in national format without any carrier code.

Parameters:

number - the phone number to be formatted

carrierCode - the carrier selection code to be used

Returns:

the formatted phone number in national format for dialing using the carrier as specified in the carrierCode

formatNationalNumberWithPreferredCarrierCode

public String formatNationalNumberWithPreferredCarrierCode(Phonenumber.PhoneNumber number,
                                                           String fallbackCarrierCode)

Formats a phone number in national format for dialing using the carrier as specified in the preferred_domestic_carrier_code field of the PhoneNumber object passed in. If that is missing, use the fallbackCarrierCode passed in instead. If there is no preferred_domestic_carrier_code, and the fallbackCarrierCode contains an empty string, return the number in national format without any carrier code. Use formatNationalNumberWithCarrierCode instead if the carrier code passed in should take precedence over the number's preferred_domestic_carrier_code when formatting.

Parameters:

number - the phone number to be formatted

fallbackCarrierCode - the carrier selection code to be used, if none is found in the phone number itself

Returns:

the formatted phone number in national format for dialing using the number's preferred_domestic_carrier_code, or the fallbackCarrierCode passed in if none is found

formatOutOfCountryCallingNumber

public String formatOutOfCountryCallingNumber(Phonenumber.PhoneNumber number,
                                              String countryCallingFrom)

Formats a phone number for out-of-country dialing purpose. If no countryCallingFrom is supplied, we format the number in its INTERNATIONAL format. If the countryCallingFrom is the same as the country where the number is from, then NATIONAL formatting will be applied. If the number itself has a country code of zero or an otherwise invalid country code, then we return the number with no formatting applied. Note this function takes care of the case for calling inside of NANPA and between Russia and Kazakhstan (who share the same country code). In those cases, no international prefix is used. For countries which have multiple international prefixes, the number in its INTERNATIONAL format will be returned instead.

Parameters:

number - the phone number to be formatted

countryCallingFrom - the ISO 3166-1 two-letter country code that denotes the foreign country where the call is being placed

Returns:

the formatted phone number

formatInOriginalFormat

public String formatInOriginalFormat(Phonenumber.PhoneNumber number,
                                     String countryCallingFrom)

Formats a phone number using the original phone number format that the number is parsed from. The original format is embedded in the country_code_source field of the PhoneNumber object passed in. If such information is missing, the number will be formatted into the NATIONAL format by default.

Parameters:

number - the PhoneNumber that needs to be formatted in its original number format

countryCallingFrom - the country whose IDD needs to be prefixed if the original number has one

Returns:

the formatted phone number in its original number format

getNationalSignificantNumber

public static String getNationalSignificantNumber(Phonenumber.PhoneNumber number)

Gets the national significant number of the a phone number. Note a national significant number doesn't contain a national prefix or any formatting.

Parameters:

number - the PhoneNumber object for which the national significant number is needed

Returns:

the national significant number of the PhoneNumber object passed in

getExampleNumber

public Phonenumber.PhoneNumber getExampleNumber(String regionCode)

Gets a valid number for the specified country.

Parameters:

regionCode - the ISO 3166-1 two-letter country code that denotes the country for which an example number is needed

Returns:

a valid fixed-line number for the specified country. Returns null when the metadata does not contain such information.

getExampleNumberForType

public Phonenumber.PhoneNumber getExampleNumberForType(String regionCode,
                                                       PhoneNumberUtil.PhoneNumberType type)

Gets a valid number for the specified country and number type.

Parameters:

regionCode - the ISO 3166-1 two-letter country code that denotes the country for which an example number is needed

type - the type of number that is needed

Returns:

a valid number for the specified country and type. Returns null when the metadata does not contain such information.

getNumberType

public PhoneNumberUtil.PhoneNumberType getNumberType(Phonenumber.PhoneNumber number)

Gets the type of a phone number.

Parameters:

number - the phone number that we want to know the type

Returns:

the type of the phone number

isValidNumber

public boolean isValidNumber(Phonenumber.PhoneNumber number)

Tests whether a phone number matches a valid pattern. Note this doesn't verify the number is actually in use, which is impossible to tell by just looking at a number itself.

Parameters:

number - the phone number that we want to validate

Returns:

a boolean that indicates whether the number is of a valid pattern

isValidNumberForRegion

public boolean isValidNumberForRegion(Phonenumber.PhoneNumber number,
                                      String regionCode)

Tests whether a phone number is valid for a certain region. Note this doesn't verify the number is actually in use, which is impossible to tell by just looking at a number itself. If the country code is not the same as the country code for the region, this immediately exits with false. After this, the specific number pattern rules for the region are examined. This is useful for determining for example whether a particular number is valid for Canada, rather than just a valid NANPA number.

Parameters:

number - the phone number that we want to validate

regionCode - the ISO 3166-1 two-letter country code that denotes the region/country that we want to validate the phone number for

Returns:

a boolean that indicates whether the number is of a valid pattern

getRegionCodeForNumber

public String getRegionCodeForNumber(Phonenumber.PhoneNumber number)

Returns the country/region where a phone number is from. This could be used for geo-coding in the country/region level.

Parameters:

number - the phone number whose origin we want to know

Returns:

the country/region where the phone number is from, or null if no country matches this calling code.

getRegionCodeForCountryCode

public String getRegionCodeForCountryCode(int countryCode)

Returns the region code that matches the specific country code. In the case of no region code being found, ZZ will be returned. In the case of multiple regions, the one designated in the metadata as the "main" country for this calling code will be returned.

getCountryCodeForRegion

public int getCountryCodeForRegion(String regionCode)

Returns the country calling code for a specific region. For example, this would be 1 for the United States, and 64 for New Zealand.

Parameters:

regionCode - the ISO 3166-1 two-letter country code that denotes the country/region that we want to get the country code for

Returns:

the country calling code for the country/region denoted by regionCode

getNddPrefixForRegion

public String getNddPrefixForRegion(String regionCode,
                                    boolean stripNonDigits)

Returns the national dialling prefix for a specific region. For example, this would be 1 for the United States, and 0 for New Zealand. Set stripNonDigits to true to strip symbols like "~" (which indicates a wait for a dialling tone) from the prefix returned. If no national prefix is present, we return null. Warning: Do not use this method for do-your-own formatting - for some countries, the national dialling prefix is used only for certain types of numbers. Use the library's formatting functions to prefix the national prefix when required.

Parameters:

regionCode - the ISO 3166-1 two-letter country code that denotes the country/region that we want to get the dialling prefix for

stripNonDigits - true to strip non-digits from the national dialling prefix

Returns:

the dialling prefix for the country/region denoted by regionCode

isNANPACountry

public boolean isNANPACountry(String regionCode)

Check if a country is one of the countries under the North American Numbering Plan Administration (NANPA).

Returns:

true if regionCode is one of the countries under NANPA

isLeadingZeroCountry

public static boolean isLeadingZeroCountry(int countryCode)

Check whether countryCode represents the country calling code from a country whose national significant number could contain a leading zero. An example of such a country is Italy.

isPossibleNumber

public boolean isPossibleNumber(Phonenumber.PhoneNumber number)

Convenience wrapper around isPossibleNumberWithReason. Instead of returning the reason for failure, this method returns a boolean value.

Parameters:

number - the number that needs to be checked

Returns:

true if the number is possible

isPossibleNumberWithReason

public PhoneNumberUtil.ValidationResult isPossibleNumberWithReason(Phonenumber.PhoneNumber number)

Check whether a phone number is a possible number. It provides a more lenient check than isValidNumber in the following sense: 1. It only checks the length of phone numbers. In particular, it doesn't check starting digits of the number. 2. It doesn't attempt to figure out the type of the number, but uses general rules which applies to all types of phone numbers in a country. Therefore, it is much faster than isValidNumber. 3. For fixed line numbers, many countries have the concept of area code, which together with subscriber number constitute the national significant number. It is sometimes okay to dial the subscriber number only when dialing in the same area. This function will return true if the subscriber-number-only version is passed in. On the other hand, because isValidNumber validates using information on both starting digits (for fixed line numbers, that would most likely be area codes) and length (obviously includes the length of area codes for fixed line numbers), it will return false for the subscriber-number-only version.

Parameters:

number - the number that needs to be checked

Returns:

a ValidationResult object which indicates whether the number is possible

isPossibleNumber

public boolean isPossibleNumber(String number,
                                String countryDialingFrom)

Check whether a phone number is a possible number given a number in the form of a string, and the country where the number could be dialed from. It provides a more lenient check than isValidNumber. See isPossibleNumber(PhoneNumber number) for details. This method first parses the number, then invokes isPossibleNumber(PhoneNumber number) with the resultant PhoneNumber object.

Parameters:

number - the number that needs to be checked, in the form of a string

countryDialingFrom - the ISO 3166-1 two-letter country code that denotes the country that we are expecting the number to be dialed from. Note this is different from the country where the number belongs. For example, the number +1 650 253 0000 is a number that belongs to US. When written in this form, it could be dialed from any country. When it is written as 00 1 650 253 0000, it could be dialed from any country which uses an international dialling prefix of 00. When it is written as 650 253 0000, it could only be dialed from within the US, and when written as 253 0000, it could only be dialed from within a smaller area in the US (Mountain View, CA, to be more specific).

Returns:

true if the number is possible

truncateTooLongNumber

public boolean truncateTooLongNumber(Phonenumber.PhoneNumber number)

Attempts to extract a valid number from a phone number that is too long to be valid, and resets the PhoneNumber object passed in to that valid version. If no valid number could be extracted, the PhoneNumber object passed in will not be modified.

Parameters:

number - a PhoneNumber object which contains a number that is too long to be valid.

Returns:

true if a valid phone number can be successfully extracted.

getAsYouTypeFormatter

public AsYouTypeFormatter getAsYouTypeFormatter(String regionCode)

Gets an AsYouTypeFormatter for the specific country.

Parameters:

regionCode - the ISO 3166-1 two-letter country code that denotes the country/region where the phone number is being entered

Returns:

an AsYouTypeFormatter object, which could be used to format phone numbers in the specific country "as you type"

parse

public Phonenumber.PhoneNumber parse(String numberToParse,
                                     String defaultCountry)
                              throws NumberParseException

Parses a string and returns it in proto buffer format. This method will throw a NumberParseException exception if the number is not considered to be a possible number. Note that validation of whether the number is actually a valid number for a particular country/region is not performed. This can be done separately with isValidNumber.

Parameters:

numberToParse - number that we are attempting to parse. This can contain formatting such as +, ( and -, as well as a phone number extension.

defaultCountry - the ISO 3166-1 two-letter country code that denotes the country that we are expecting the number to be from. This is only used if the number being parsed is not written in international format. The country code for the number in this case would be stored as that of the default country supplied. If the number is guaranteed to start with a '+' followed by the country code, then "ZZ" or null can be supplied.

Returns:

a phone number proto buffer filled with the parsed number

Throws:

NumberParseException - if the string is not considered to be a viable phone number or if no default country was supplied and the number is not in international format (does not start with +)

parse

public void parse(String numberToParse,
                  String defaultCountry,
                  Phonenumber.PhoneNumber phoneNumber)
           throws NumberParseException

Throws:

NumberParseException

parseAndKeepRawInput

public Phonenumber.PhoneNumber parseAndKeepRawInput(String numberToParse,
                                                    String defaultCountry)
                                             throws NumberParseException

Parses a string and returns it in proto buffer format. This method differs from parse() in that it always populates the raw_input field of the protocol buffer with numberToParse as well as the country_code_source field.

Parameters:

numberToParse - number that we are attempting to parse. This can contain formatting such as +, ( and -, as well as a phone number extension.

defaultCountry - the ISO 3166-1 two-letter country code that denotes the country that we are expecting the number to be from. This is only used if the number being parsed is not written in international format. The country code for the number in this case would be stored as that of the default country supplied.

Returns:

a phone number proto buffer filled with the parsed number

Throws:

NumberParseException - if the string is not considered to be a viable phone number or if no default country was supplied

parseAndKeepRawInput

public void parseAndKeepRawInput(String numberToParse,
                                 String defaultCountry,
                                 Phonenumber.PhoneNumber phoneNumber)
                          throws NumberParseException

Throws:

NumberParseException

findNumbers

public Iterable<PhoneNumberMatch> findNumbers(CharSequence text,
                                              String defaultCountry)

Returns an iterable over all PhoneNumberMatches in text. This is a shortcut for getMatcher(text, defaultCountry, Leniency.VALID, Long.MAX_VALUE).

Parameters:

text - the text to search for phone numbers, null for no text

defaultCountry - the ISO 3166-1 two-letter country code that denotes the country that we are expecting the number to be from. This is only used if the number being parsed is not written in international format. The country code for the number in this case would be stored as that of the default country supplied. May be null if only international numbers are expected.

findNumbers

public Iterable<PhoneNumberMatch> findNumbers(CharSequence text,
                                              String defaultCountry,
                                              PhoneNumberUtil.Leniency leniency,
                                              long maxTries)

Returns an iterable over all PhoneNumberMatches in text.

Parameters:

text - the text to search for phone numbers, null for no text

defaultCountry - the ISO 3166-1 two-letter country code that denotes the country that we are expecting the number to be from. This is only used if the number being parsed is not written in international format. The country code for the number in this case would be stored as that of the default country supplied. May be null if only international numbers are expected.

leniency - the leniency to use when evaluating candidate phone numbers

maxTries - the maximum number of invalid numbers to try before giving up on the text. This is to cover degenerate cases where the text has a lot of false positives in it. Must be >= 0.

isNumberMatch

public PhoneNumberUtil.MatchType isNumberMatch(Phonenumber.PhoneNumber firstNumberIn,
                                               Phonenumber.PhoneNumber secondNumberIn)

Takes two phone numbers and compares them for equality. Returns EXACT_MATCH if the country code, NSN, presence of a leading zero for Italian numbers and any extension present are the same. Returns NSN_MATCH if either or both has no country specified, and the NSNs and extensions are the same. Returns SHORT_NSN_MATCH if either or both has no country specified, or the country specified is the same, and one NSN could be a shorter version of the other number. This includes the case where one has an extension specified, and the other does not. Returns NO_MATCH otherwise. For example, the numbers +1 345 657 1234 and 657 1234 are a SHORT_NSN_MATCH. The numbers +1 345 657 1234 and 345 657 are a NO_MATCH.

Parameters:

firstNumberIn - first number to compare

secondNumberIn - second number to compare

Returns:

NO_MATCH, SHORT_NSN_MATCH, NSN_MATCH or EXACT_MATCH depending on the level of equality of the two numbers, described in the method definition.

isNumberMatch

public PhoneNumberUtil.MatchType isNumberMatch(String firstNumber,
                                               String secondNumber)

Takes two phone numbers as strings and compares them for equality. This is a convenience wrapper for isNumberMatch(PhoneNumber firstNumber, PhoneNumber secondNumber). No default region is known.

Parameters:

firstNumber - first number to compare. Can contain formatting, and can have country code specified with + at the start.

secondNumber - second number to compare. Can contain formatting, and can have country code specified with + at the start.

Returns:

NOT_A_NUMBER, NO_MATCH, SHORT_NSN_MATCH, NSN_MATCH, EXACT_MATCH. See isNumberMatch(PhoneNumber firstNumber, PhoneNumber secondNumber) for more details.

isNumberMatch

public PhoneNumberUtil.MatchType isNumberMatch(Phonenumber.PhoneNumber firstNumber,
                                               String secondNumber)

Takes two phone numbers and compares them for equality. This is a convenience wrapper for isNumberMatch(PhoneNumber firstNumber, PhoneNumber secondNumber). No default region is known.

Parameters:

firstNumber - first number to compare in proto buffer format.

secondNumber - second number to compare. Can contain formatting, and can have country code specified with + at the start.

Returns:

NOT_A_NUMBER, NO_MATCH, SHORT_NSN_MATCH, NSN_MATCH, EXACT_MATCH. See isNumberMatch(PhoneNumber firstNumber, PhoneNumber secondNumber) for more details.