Skip to content

Most visited

Recently visited

navigation

PhoneNumberUtils

public class PhoneNumberUtils
extends Object

java.lang.Object
   ↳ android.telephony.PhoneNumberUtils


Various utilities for dealing with phone number strings.

Summary

Constants

int FORMAT_JAPAN

Japanese formatting

int FORMAT_NANP

NANP formatting

int FORMAT_UNKNOWN

The current locale is unknown, look for a country code or don't format

char PAUSE

int TOA_International

int TOA_Unknown

char WAIT

char WILD

Public constructors

PhoneNumberUtils()

Public methods

static void addTtsSpan(Spannable s, int start, int endExclusive)

Attach a TtsSpan to the supplied Spannable at the indicated location, annotating that location as containing a phone number.

static String calledPartyBCDFragmentToString(byte[] bytes, int offset, int length)

Like calledPartyBCDToString, but field does not start with a TOA byte.

static String calledPartyBCDToString(byte[] bytes, int offset, int length)

3GPP TS 24.008 10.5.4.7 Called Party BCD Number See Also TS 51.011 10.5.1 "dialing number/ssc string" and TS 11.11 "10.3.1 EF adn (Abbreviated dialing numbers)"

static boolean compare(Context context, String a, String b)

Compare phone numbers a and b, and return true if they're identical enough for caller ID purposes.

static boolean compare(String a, String b)

Compare phone numbers a and b, return true if they're identical enough for caller ID purposes.

static String convertKeypadLettersToDigits(String input)

Translates any alphabetic letters (i.e.

static TtsSpan createTtsSpan(String phoneNumberString)

Create a TtsSpan for the supplied String.

static CharSequence createTtsSpannable(CharSequence phoneNumber)

Wrap the supplied CharSequence with a TtsSpan, annotating it as containing a phone number in its entirety.

static String extractNetworkPortion(String phoneNumber)

Extracts the network address portion and canonicalizes (filters out separators.) Network address portion is everything up to DTMF control digit separators (pause or wait), but without non-dialable characters.

static String extractPostDialPortion(String phoneNumber)

Extracts the post-dial sequence of DTMF control digits, pauses, and waits.

static void formatJapaneseNumber(Editable text)

This method was deprecated in API level 21. Use link #formatNumber(String phoneNumber, String defaultCountryIso) instead

static void formatNanpNumber(Editable text)

This method was deprecated in API level 21. Use link #formatNumber(String phoneNumber, String defaultCountryIso) instead

static String formatNumber(String phoneNumber, String phoneNumberE164, String defaultCountryIso)

Format the phone number only if the given number hasn't been formatted.

static void formatNumber(Editable text, int defaultFormattingType)

This method was deprecated in API level 21. Use link #formatNumber(String phoneNumber, String defaultCountryIso) instead

static String formatNumber(String source)

This method was deprecated in API level 21. Use link #formatNumber(String phoneNumber, String defaultCountryIso) instead

static String formatNumber(String phoneNumber, String defaultCountryIso)

Format a phone number.

static String formatNumberToE164(String phoneNumber, String defaultCountryIso)

Formats the specified phoneNumber to the E.164 representation.

static String formatNumberToRFC3966(String phoneNumber, String defaultCountryIso)

Formats the specified phoneNumber to the RFC3966 representation.

static int getFormatTypeForLocale(Locale locale)

This method was deprecated in API level 21. Use link #formatNumber(String phoneNumber, String defaultCountryIso) instead

static String getNumberFromIntent(Intent intent, Context context)

Extracts the phone number from an Intent.

static String getStrippedReversed(String phoneNumber)

Returns the network portion reversed.

static final boolean is12Key(char c)

True if c is ISO-LATIN characters 0-9, *, #

static final boolean isDialable(char c)

True if c is ISO-LATIN characters 0-9, *, # , +, WILD

static boolean isEmergencyNumber(String number)

Checks a given number against the list of emergency numbers provided by the RIL and SIM card.

static boolean isGlobalPhoneNumber(String phoneNumber)
static boolean isISODigit(char c)

True if c is ISO-LATIN characters 0-9

static boolean isLocalEmergencyNumber(Context context, String number)

Checks if a given number is an emergency number for the country that the user is in.

static final boolean isNonSeparator(char c)

True if c is ISO-LATIN characters 0-9, *, # , +, WILD, WAIT, PAUSE

static final boolean isReallyDialable(char c)

True if c is ISO-LATIN characters 0-9, *, # , + (no WILD)

static final boolean isStartsPostDial(char c)

This any anything to the right of this char is part of the post-dial string (eg this is PAUSE or WAIT)

static boolean isVoiceMailNumber(String number)

isVoiceMailNumber: checks a given number against the voicemail number provided by the RIL and SIM card.

static boolean isWellFormedSmsAddress(String address)

Return true iff the network portion of address is, as far as we can tell on the device, suitable for use as an SMS destination address.

static byte[] networkPortionToCalledPartyBCD(String s)

Note: calls extractNetworkPortion(), so do not use for SIM EF[ADN] style records Returns null if network portion is empty.

static byte[] networkPortionToCalledPartyBCDWithLength(String s)

Same as networkPortionToCalledPartyBCD(String), but includes a one-byte length prefix.

static String normalizeNumber(String phoneNumber)

Normalize a phone number by removing the characters other than digits.

static byte[] numberToCalledPartyBCD(String number)

Convert a dialing number to BCD byte array

static String replaceUnicodeDigits(String number)

Replaces all unicode(e.g.

static String stringFromStringAndTOA(String s, int TOA)

Basically: makes sure there's a + in front of a TOA_International number Returns null if s == null

static String stripSeparators(String phoneNumber)

Strips separators from a phone number string.

static String toCallerIDMinMatch(String phoneNumber)

Returns the rightmost MIN_MATCH (5) characters in the network portion in *reversed* order This can be used to do a database lookup against the column that stores getStrippedReversed() Returns null if phoneNumber == null

static int toaFromString(String s)

Returns the TOA for the given dial string Basically, returns TOA_International if there's a + prefix

Inherited methods

From class java.lang.Object

Constants

FORMAT_JAPAN

Added in API level 3
int FORMAT_JAPAN

Japanese formatting

Constant Value: 2 (0x00000002)

FORMAT_NANP

Added in API level 1
int FORMAT_NANP

NANP formatting

Constant Value: 1 (0x00000001)

FORMAT_UNKNOWN

Added in API level 1
int FORMAT_UNKNOWN

The current locale is unknown, look for a country code or don't format

Constant Value: 0 (0x00000000)

PAUSE

Added in API level 1
char PAUSE

Constant Value: 44 (0x0000002c)

TOA_International

Added in API level 1
int TOA_International

Constant Value: 145 (0x00000091)

TOA_Unknown

Added in API level 1
int TOA_Unknown

Constant Value: 129 (0x00000081)

WAIT

Added in API level 1
char WAIT

Constant Value: 59 (0x0000003b)

WILD

Added in API level 1
char WILD

Constant Value: 78 (0x0000004e)

Public constructors

PhoneNumberUtils

Added in API level 1
PhoneNumberUtils ()

Public methods

addTtsSpan

Added in API level 23
void addTtsSpan (Spannable s, 
                int start, 
                int endExclusive)

Attach a TtsSpan to the supplied Spannable at the indicated location, annotating that location as containing a phone number.

Parameters
s Spannable: A Spannable to annotate.
start int: The starting character position of the phone number in s.
endExclusive int: The position after the ending character in the phone number s.

calledPartyBCDFragmentToString

Added in API level 1
String calledPartyBCDFragmentToString (byte[] bytes, 
                int offset, 
                int length)

Like calledPartyBCDToString, but field does not start with a TOA byte. For example: SIM ADN extension fields

Parameters
bytes byte
offset int
length int
Returns
String

calledPartyBCDToString

Added in API level 1
String calledPartyBCDToString (byte[] bytes, 
                int offset, 
                int length)

3GPP TS 24.008 10.5.4.7 Called Party BCD Number See Also TS 51.011 10.5.1 "dialing number/ssc string" and TS 11.11 "10.3.1 EF adn (Abbreviated dialing numbers)"

Parameters
bytes byte: the data buffer
offset int: should point to the TOA (aka. TON/NPI) octet after the length byte
length int: is the number of bytes including TOA byte and must be at least 2
Returns
String partial string on invalid decode FIXME(mkf) support alphanumeric address type currently implemented in SMSMessage.getAddress()

compare

Added in API level 5
boolean compare (Context context, 
                String a, 
                String b)

Compare phone numbers a and b, and return true if they're identical enough for caller ID purposes. Checks a resource to determine whether to use a strict or loose comparison algorithm.

Parameters
context Context
a String
b String
Returns
boolean

compare

Added in API level 1
boolean compare (String a, 
                String b)

Compare phone numbers a and b, return true if they're identical enough for caller ID purposes.

Parameters
a String
b String
Returns
boolean

convertKeypadLettersToDigits

Added in API level 1
String convertKeypadLettersToDigits (String input)

Translates any alphabetic letters (i.e. [A-Za-z]) in the specified phone number into the equivalent numeric digits, according to the phone keypad letter mapping described in ITU E.161 and ISO/IEC 9995-8.

Parameters
input String
Returns
String the input string, with alpha letters converted to numeric digits using the phone keypad letter mapping. For example, an input of "1-800-GOOG-411" will return "1-800-4664-411".

createTtsSpan

Added in API level 23
TtsSpan createTtsSpan (String phoneNumberString)

Create a TtsSpan for the supplied String.

Parameters
phoneNumberString String: A String the entirety of which represents a phone number.
Returns
TtsSpan A TtsSpan for .

createTtsSpannable

Added in API level 23
CharSequence createTtsSpannable (CharSequence phoneNumber)

Wrap the supplied CharSequence with a TtsSpan, annotating it as containing a phone number in its entirety.

Parameters
phoneNumber CharSequence: A CharSequence the entirety of which represents a phone number.
Returns
CharSequence A CharSequence with appropriate annotations.

extractNetworkPortion

Added in API level 1
String extractNetworkPortion (String phoneNumber)

Extracts the network address portion and canonicalizes (filters out separators.) Network address portion is everything up to DTMF control digit separators (pause or wait), but without non-dialable characters. Please note that the GSM wild character is allowed in the result. This must be resolved before dialing. Returns null if phoneNumber == null

Parameters
phoneNumber String
Returns
String

extractPostDialPortion

Added in API level 1
String extractPostDialPortion (String phoneNumber)

Extracts the post-dial sequence of DTMF control digits, pauses, and waits. Strips separators. This string may be empty, but will not be null unless phoneNumber == null. Returns null if phoneNumber == null

Parameters
phoneNumber String
Returns
String

formatJapaneseNumber

Added in API level 3
void formatJapaneseNumber (Editable text)

This method was deprecated in API level 21.
Use link #formatNumber(String phoneNumber, String defaultCountryIso) instead

Formats a phone number in-place using the Japanese formatting rules. Numbers will be formatted as:

03-xxxx-xxxx 090-xxxx-xxxx 0120-xxx-xxx +81-3-xxxx-xxxx +81-90-xxxx-xxxx

Parameters
text Editable: the number to be formatted, will be modified with the formatting

formatNanpNumber

Added in API level 1
void formatNanpNumber (Editable text)

This method was deprecated in API level 21.
Use link #formatNumber(String phoneNumber, String defaultCountryIso) instead

Formats a phone number in-place using the NANP formatting rules. Numbers will be formatted as:

xxxxx xxx-xxxx xxx-xxx-xxxx 1-xxx-xxx-xxxx +1-xxx-xxx-xxxx

Parameters
text Editable: the number to be formatted, will be modified with the formatting

formatNumber

Added in API level 21
String formatNumber (String phoneNumber, 
                String phoneNumberE164, 
                String defaultCountryIso)

Format the phone number only if the given number hasn't been formatted.

The number which has only dailable character is treated as not being formatted.

Parameters
phoneNumber String: the number to be formatted.
phoneNumberE164 String: the E164 format number whose country code is used if the given phoneNumber doesn't have the country code.
defaultCountryIso String: the ISO 3166-1 two letters country code whose convention will be used if the phoneNumberE164 is null or invalid, or if phoneNumber contains IDD.
Returns
String the formatted number if the given number has been formatted, otherwise, return the given number.

formatNumber

Added in API level 1
void formatNumber (Editable text, 
                int defaultFormattingType)

This method was deprecated in API level 21.
Use link #formatNumber(String phoneNumber, String defaultCountryIso) instead

Formats a phone number in-place. Currently FORMAT_JAPAN and FORMAT_NANP is supported as a second argument.

Parameters
text Editable: The number to be formatted, will be modified with the formatting
defaultFormattingType int: The default formatting rules to apply if the number does not begin with +[country_code]

formatNumber

Added in API level 1
String formatNumber (String source)

This method was deprecated in API level 21.
Use link #formatNumber(String phoneNumber, String defaultCountryIso) instead

Breaks the given number down and formats it according to the rules for the country the number is from.

Parameters
source String: The phone number to format
Returns
String A locally acceptable formatting of the input, or the raw input if formatting rules aren't known for the number

formatNumber

Added in API level 21
String formatNumber (String phoneNumber, 
                String defaultCountryIso)

Format a phone number.

If the given number doesn't have the country code, the phone will be formatted to the default country's convention.

Parameters
phoneNumber String: the number to be formatted.
defaultCountryIso String: the ISO 3166-1 two letters country code whose convention will be used if the given number doesn't have the country code.
Returns
String the formatted number, or null if the given number is not valid.

formatNumberToE164

Added in API level 21
String formatNumberToE164 (String phoneNumber, 
                String defaultCountryIso)

Formats the specified phoneNumber to the E.164 representation.

Parameters
phoneNumber String: the phone number to format.
defaultCountryIso String: the ISO 3166-1 two letters country code.
Returns
String the E.164 representation, or null if the given phone number is not valid.

formatNumberToRFC3966

Added in API level 23
String formatNumberToRFC3966 (String phoneNumber, 
                String defaultCountryIso)

Formats the specified phoneNumber to the RFC3966 representation.

Parameters
phoneNumber String: the phone number to format.
defaultCountryIso String: the ISO 3166-1 two letters country code.
Returns
String the RFC3966 representation, or null if the given phone number is not valid.

getFormatTypeForLocale

Added in API level 1
int getFormatTypeForLocale (Locale locale)

This method was deprecated in API level 21.
Use link #formatNumber(String phoneNumber, String defaultCountryIso) instead

Returns the phone number formatting type for the given locale.

Parameters
locale Locale: The locale of interest, usually getDefault()
Returns
int The formatting type for the given locale, or FORMAT_UNKNOWN if the formatting rules are not known for the given locale

getNumberFromIntent

Added in API level 1
String getNumberFromIntent (Intent intent, 
                Context context)

Extracts the phone number from an Intent.

Parameters
intent Intent: the intent to get the number of
context Context: a context to use for database access
Returns
String the phone number that would be called by the intent, or null if the number cannot be found.

getStrippedReversed

Added in API level 1
String getStrippedReversed (String phoneNumber)

Returns the network portion reversed. This string is intended to go into an index column for a database lookup. Returns null if phoneNumber == null

Parameters
phoneNumber String
Returns
String

is12Key

Added in API level 1
boolean is12Key (char c)

True if c is ISO-LATIN characters 0-9, *, #

Parameters
c char
Returns
boolean

isDialable

Added in API level 1
boolean isDialable (char c)

True if c is ISO-LATIN characters 0-9, *, # , +, WILD

Parameters
c char
Returns
boolean

isEmergencyNumber

Added in API level 1
boolean isEmergencyNumber (String number)

Checks a given number against the list of emergency numbers provided by the RIL and SIM card.

Parameters
number String: the number to look up.
Returns
boolean true if the number is in the list of emergency numbers listed in the RIL / SIM, otherwise return false.

isGlobalPhoneNumber

Added in API level 1
boolean isGlobalPhoneNumber (String phoneNumber)

Parameters
phoneNumber String
Returns
boolean

isISODigit

Added in API level 1
boolean isISODigit (char c)

True if c is ISO-LATIN characters 0-9

Parameters
c char
Returns
boolean

isLocalEmergencyNumber

Added in API level 21
boolean isLocalEmergencyNumber (Context context, 
                String number)

Checks if a given number is an emergency number for the country that the user is in.

Parameters
context Context: the specific context which the number should be checked against
number String: the number to look up.
Returns
boolean true if the specified number is an emergency number for the country the user is currently in.

isNonSeparator

Added in API level 1
boolean isNonSeparator (char c)

True if c is ISO-LATIN characters 0-9, *, # , +, WILD, WAIT, PAUSE

Parameters
c char
Returns
boolean

isReallyDialable

Added in API level 1
boolean isReallyDialable (char c)

True if c is ISO-LATIN characters 0-9, *, # , + (no WILD)

Parameters
c char
Returns
boolean

isStartsPostDial

Added in API level 1
boolean isStartsPostDial (char c)

This any anything to the right of this char is part of the post-dial string (eg this is PAUSE or WAIT)

Parameters
c char
Returns
boolean

isVoiceMailNumber

Added in API level 21
boolean isVoiceMailNumber (String number)

isVoiceMailNumber: checks a given number against the voicemail number provided by the RIL and SIM card. The caller must have the READ_PHONE_STATE credential.

Parameters
number String: the number to look up.
Returns
boolean true if the number is in the list of voicemail. False otherwise, including if the caller does not have the permission to read the VM number.

isWellFormedSmsAddress

Added in API level 1
boolean isWellFormedSmsAddress (String address)

Return true iff the network portion of address is, as far as we can tell on the device, suitable for use as an SMS destination address.

Parameters
address String
Returns
boolean

networkPortionToCalledPartyBCD

Added in API level 1
byte[] networkPortionToCalledPartyBCD (String s)

Note: calls extractNetworkPortion(), so do not use for SIM EF[ADN] style records Returns null if network portion is empty.

Parameters
s String
Returns
byte[]

networkPortionToCalledPartyBCDWithLength

Added in API level 1
byte[] networkPortionToCalledPartyBCDWithLength (String s)

Same as networkPortionToCalledPartyBCD(String), but includes a one-byte length prefix.

Parameters
s String
Returns
byte[]

normalizeNumber

Added in API level 21
String normalizeNumber (String phoneNumber)

Normalize a phone number by removing the characters other than digits. If the given number has keypad letters, the letters will be converted to digits first.

Parameters
phoneNumber String: the number to be normalized.
Returns
String the normalized number.

numberToCalledPartyBCD

Added in API level 1
byte[] numberToCalledPartyBCD (String number)

Convert a dialing number to BCD byte array

Parameters
number String: dialing number string if the dialing number starts with '+', set to international TOA
Returns
byte[] BCD byte array

replaceUnicodeDigits

Added in API level 21
String replaceUnicodeDigits (String number)

Replaces all unicode(e.g. Arabic, Persian) digits with their decimal digit equivalents.

Parameters
number String: the number to perform the replacement on.
Returns
String the replaced number.

stringFromStringAndTOA

Added in API level 1
String stringFromStringAndTOA (String s, 
                int TOA)

Basically: makes sure there's a + in front of a TOA_International number Returns null if s == null

Parameters
s String
TOA int
Returns
String

stripSeparators

Added in API level 1
String stripSeparators (String phoneNumber)

Strips separators from a phone number string.

Parameters
phoneNumber String: phone number to strip.
Returns
String phone string stripped of separators.

toCallerIDMinMatch

Added in API level 1
String toCallerIDMinMatch (String phoneNumber)

Returns the rightmost MIN_MATCH (5) characters in the network portion in *reversed* order This can be used to do a database lookup against the column that stores getStrippedReversed() Returns null if phoneNumber == null

Parameters
phoneNumber String
Returns
String

toaFromString

Added in API level 1
int toaFromString (String s)

Returns the TOA for the given dial string Basically, returns TOA_International if there's a + prefix

Parameters
s String
Returns
int
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.