Title: | Parse, Format, and Validate International Phone Numbers |
---|---|
Description: | Parse, format, and validate international phone numbers using Google's 'libphonenumber' java library, <https://github.com/google/libphonenumber>. |
Authors: | Danny Smith [aut, cre, cph], The Social Research Centre [cph] |
Maintainer: | Danny Smith <[email protected]> |
License: | GPL (>= 3) |
Version: | 0.4.1.9000 |
Built: | 2024-12-08 03:46:13 UTC |
Source: | https://github.com/socialresearchcentre/dialr |
Check whether an ISO country code is valid.
check_cc(country)
check_cc(country)
country |
A character vector of ISO country codes. |
A logical vector flagging which elements are valid codes.
check_cc(c("AU", "US", "CN", "WRONG", NA))
check_cc(c("AU", "US", "CN", "WRONG", NA))
Produces example phone numbers for the given region
,
type
and valid
combinations. Input vectors are recycled as
necessary if a vector of length 1 is provided.
get_example(region, type = NULL, valid = TRUE)
get_example(region, type = NULL, valid = TRUE)
region |
A character vector of ISO country codes. |
type |
A character vector of phone number types for each
region. If |
valid |
A logical vector. For each |
A phone vector.
get_example()
: PhoneNumberUtil.getExampleNumberForType()
;
PhoneNumberUtil.getExampleNumber()
if type
is NULL
or NA
;
PhoneNumberUtil.getInvalidExampleNumber()
if valid
is FALSE
.
get_supported_regions()
for valid region codes,
get_types_for_region()
to get valid phone types for a region.
Other phone functions:
dialr-match
,
dialr-phone
,
dialr-region
,
dialr-type
,
dialr-valid
,
dialr
# Get a basic example number get_example("AU") # Get an example mobile number get_example("AU", type = "MOBILE") # Example phone number for an invalid type get_example("AU", type = "VOICEMAIL") # Get an example invalid number get_example("AU", valid = FALSE) # Get a combination of the previous examples get_example(c("AU", "AU", "AU", "AU" ), c(NA, "MOBILE", "VOICEMAIL", NA ), c(TRUE, TRUE, TRUE, FALSE))
# Get a basic example number get_example("AU") # Get an example mobile number get_example("AU", type = "MOBILE") # Example phone number for an invalid type get_example("AU", type = "VOICEMAIL") # Get an example invalid number get_example("AU", valid = FALSE) # Get a combination of the previous examples get_example(c("AU", "AU", "AU", "AU" ), c(NA, "MOBILE", "VOICEMAIL", NA ), c(TRUE, TRUE, TRUE, FALSE))
Check if two vectors contain matching phone numbers. See Details section for
a full list of match types. is_match()
with default arguments is used to
implement ==
and !=
for phone vectors.
is_match()
accepts phone or atomic vectors. Atomic vectors are converted to
character for comparison. Note that although they can contain formatting
character vectors are not parsed with a default region, so they will only
ever be an "EXACT_MATCH"
if a country calling code is specified with +
at
the start. See Examples.
is_match(e1, e2, detailed = FALSE, strict = TRUE, not_number_na = TRUE)
is_match(e1, e2, detailed = FALSE, strict = TRUE, not_number_na = TRUE)
e1 |
A phone or character vector. |
e2 |
A phone or character vector. |
detailed |
If |
strict |
If |
not_number_na |
If |
Possible return values for is_match(x, detailed = TRUE)
:
"EXACT_MATCH"
: The country_code, NSN, presence of a leading zero for
Italian numbers and any extension present are the same.
"NSN_MATCH"
: Either or both values has no region specified, and the NSNs
and extensions are the same.
"SHORT_NSN_MATCH"
: Either or both values has no region specified, or the
region 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.
"NOT_A_NUMBER"
: One of the input phone numbers failed to parse.
"NO_MATCH"
: All others.
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"
.
A logical or character vector.
is_match()
: PhoneNumberUtil.isNumberMatch()
Other phone functions:
dialr-example
,
dialr-phone
,
dialr-region
,
dialr-type
,
dialr-valid
,
dialr
is_match(phone("0412 345 678", "AU"), phone("+61412345678", "AU")) phone("0412 345 678", "AU") == phone("+61412345678", "AU") phone("0412 345 678", "AU") != phone("+61412345678", "AU") # character vectors are only fully specified with a country calling code is_match("0412345678", "0412345678", detailed = TRUE) is_match("+61412345678", "+61412345678", detailed = TRUE) is_match(phone("0412345678", "AU"), "0412345678", detailed = TRUE) is_match(phone("+61412345678", "AU"), "+61412345678", detailed = TRUE)
is_match(phone("0412 345 678", "AU"), phone("+61412345678", "AU")) phone("0412 345 678", "AU") == phone("+61412345678", "AU") phone("0412 345 678", "AU") != phone("+61412345678", "AU") # character vectors are only fully specified with a country calling code is_match("0412345678", "0412345678", detailed = TRUE) is_match("+61412345678", "+61412345678", detailed = TRUE) is_match(phone("0412345678", "AU"), "0412345678", detailed = TRUE) is_match(phone("+61412345678", "AU"), "+61412345678", detailed = TRUE)
A phone vector stores phone numbers parsed with libphonenumber for formatting and further processing.
phone( x = character(), region = character(), show_progress = getOption("dialr.show_progress") ) phone_reparse(x) is.phone(x) ## S3 method for class 'phone' print(x, n = 10, ...) ## S3 method for class 'phone' format( x, format = c("E164", "NATIONAL", "INTERNATIONAL", "RFC3966"), home = NULL, clean = TRUE, strict = FALSE, ... ) ## S3 method for class 'phone' as.character(x, raw = TRUE, ...)
phone( x = character(), region = character(), show_progress = getOption("dialr.show_progress") ) phone_reparse(x) is.phone(x) ## S3 method for class 'phone' print(x, n = 10, ...) ## S3 method for class 'phone' format( x, format = c("E164", "NATIONAL", "INTERNATIONAL", "RFC3966"), home = NULL, clean = TRUE, strict = FALSE, ... ) ## S3 method for class 'phone' as.character(x, raw = TRUE, ...)
x |
A character vector of phone numbers. |
region |
A character vector of ISO country codes with
the default region for each phone number in If |
show_progress |
Should a progress bar be displayed? Defaults to the
option |
n |
Number of elements to print. |
... |
Additional arguments for specific methods. |
format |
Phone number format to use from one of four standards:
See notes from the libphonenumber javadocs for more details.
|
home |
ISO country code for home region. If provided, numbers will be formatted for dialing from the home region. |
clean |
Should non-numeric characters be removed? If |
strict |
Should invalid phone numbers be removed? If |
raw |
If |
libphonenumber defines the PhoneNumberUtil
class, with a set of functions
for extracting information from and performing processing on a parsed
Phonenumber
object. A text phone number must be parsed before any other
operations (e.g. checking phone number validity, formatting) can be
performed. When parsing a phone number a "default region" is
required to determine the processing context for non-international numbers.
A phone vector stores the raw phone number, the default region and a java
Phonenumber
object for each element. The java object is cached so should
persist between R sessions. In case of issues, use phone_reparse()
to
recreate the phone vector from the original phone number and region.
Phone number parsing functions display a progress bar in interactive sessions
by default. This can be disabled globally by setting option
dialr.show_progress
to FALSE
, or locally using the show_progress
function argument.
phone()
: Phone numbers are parsed using
PhoneNumberUtil.parseAndKeepRawInput()
. A phone vector stores the
returned Phonenumber.PhoneNumber
object alongside the original raw text
and default region for later reference.
format()
: PhoneNumberUtil.format()
by default, or
PhoneNumberUtil.formatOutOfCountryCallingNumber()
if home
is provided.
Other phone functions:
dialr-example
,
dialr-match
,
dialr-region
,
dialr-type
,
dialr-valid
,
dialr
# Create a phone vector x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") is.phone(x) print(x) as.character(x) format(x) format(x, home = "AU") # Parse international number with no default region phone("+61412345678", NA) # Will fail to parse if number is not in international format phone("0412345678", NA) # A combination can be used phone(c("+61412345678", "0412345678"), c(NA, "AU"))
# Create a phone vector x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") is.phone(x) print(x) as.character(x) format(x) format(x, home = "AU") # Parse international number with no default region phone("+61412345678", NA) # Will fail to parse if number is not in international format phone("0412345678", NA) # A combination can be used phone(c("+61412345678", "0412345678"), c(NA, "AU"))
In libphonenumber a phone number region is represented by a 2 digit ISO
country code. get_region(x)
returns the 2-digit ISO country code for each element of a phone
vector.
Use get_supported_regions()
to see a full list of supported regions.
Region can also be retrieved from an international calling code.
get_region_for_calling_code(x)
returns the main region for each provided
calling code. Since multiple regions can share a single calling code,
get_regions_for_calling_code(x)
returns a list of character vectors of
regions for each.
get_region(x) get_supported_regions() get_region_for_calling_code(x) get_regions_for_calling_code(x)
get_region(x) get_supported_regions() get_region_for_calling_code(x) get_regions_for_calling_code(x)
x |
A phone vector, or a vector of calling codes. |
A character vector of country codes.
get_regions_for_calling_code()
returns a list of character vectors for
each provided calling code.
get_region()
: PhoneNumberUtil.getRegionCodeForNumber()
get_supported_regions()
: PhoneNumberUtil.getSupportedRegions()
get_region_for_calling_code()
:
PhoneNumberUtil.getRegionCodeForCountryCode()
get_regions_for_calling_code()
:
PhoneNumberUtil.getRegionCodesForCountryCode()
Other phone functions:
dialr-example
,
dialr-match
,
dialr-phone
,
dialr-type
,
dialr-valid
,
dialr
# Get regions for a phone vector x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") get_region(x) # All supported region codes get_supported_regions() # Primary region for a calling code get_region_for_calling_code(c(1, 61, 84)) # All regions for a calling code get_regions_for_calling_code(c(1, 61, 84))
# Get regions for a phone vector x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") get_region(x) # All supported region codes get_supported_regions() # Primary region for a calling code get_region_for_calling_code(c(1, 61, 84)) # All regions for a calling code get_regions_for_calling_code(c(1, 61, 84))
In addition to validity, libphonenumber can identify phone number type - it is able to distinguish Fixed-line, Mobile, Toll-free, Premium Rate, Shared Cost, VoIP, Personal Numbers, UAN, Pager, and Voicemail (whenever feasible).
get_type(x)
returns the phone number type for each element of a phone
vector.
Valid phone number types differ by region. get_types_for_region(x)
returns
a list of character vectors of valid types for each provided
ISO country code. Use get_supported_types()
to see a full
list of supported types.
get_type(x, strict = FALSE) get_supported_types() get_types_for_region(x)
get_type(x, strict = FALSE) get_supported_types() get_types_for_region(x)
x |
A phone vector, or a character vector of ISO country codes. |
strict |
If |
A character vector of phone types.
get_types_for_region()
returns a list of character vectors for each
provided country code.
get_type()
: PhoneNumberUtil.getNumberType()
get_supported_types()
: PhoneNumberUtil.PhoneNumberType
get_types_for_region()
: PhoneNumberUtil.getSupportedTypesForRegion()
Other phone functions:
dialr-example
,
dialr-match
,
dialr-phone
,
dialr-region
,
dialr-valid
,
dialr
# Get phone types for a phone vector x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") get_type(x) # All supported phone types get_supported_types() # Get supported types for specified regions get_types_for_region("AU") get_types_for_region(c("GB", "US")) get_types_for_region(get_supported_regions())[1:5]
# Get phone types for a phone vector x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") get_type(x) # All supported phone types get_supported_types() # Get supported types for specified regions get_types_for_region("AU") get_types_for_region(c("GB", "US")) get_types_for_region(get_supported_regions())[1:5]
For each element of x
:
is_parsed(x)
: Was this successfully parsed?
is_valid(x)
: Is this a valid phone number?
is_possible(x)
: Is this a possible phone number? Return type depends on
detailed
.
is_parsed(x) is_valid(x) is_possible(x, detailed = FALSE, type = NULL)
is_parsed(x) is_valid(x) is_possible(x, detailed = FALSE, type = NULL)
x |
A phone vector. |
detailed |
If |
type |
If provided, checks if |
Possible return values for is_possible(x, detailed = TRUE)
:
"INVALID_COUNTRY_CODE"
: The number has an invalid country calling code.
"INVALID_LENGTH"
: The number is longer than the shortest valid numbers
for this region, shorter than the longest valid numbers for this region,
and does not itself have a number length that matches valid numbers for
this region.
"IS_POSSIBLE"
: The number length matches that of valid numbers for this
region.
"IS_POSSIBLE_LOCAL_ONLY"
: The number length matches that of local numbers
for this region only (i.e. numbers that may be able to be dialled within an
area, but do not have all the information to be dialled from anywhere inside
or outside the country).
"TOO_LONG"
: The number is longer than all valid numbers for this region.
"TOO_SHORT"
: The number is shorter than all valid numbers for this
region.
is_valid()
: PhoneNumberUtil.isValidNumber()
is_possible()
: PhoneNumberUtil.isPossibleNumber()
is_possible(detailed = TRUE)
: PhoneNumberUtil.isPossibleNumberWithReason()
is_possible(type = type)
: PhoneNumberUtil.isPossibleNumberForType()
is_possible(detailed = TRUE, type = type)
: PhoneNumberUtil.sPossibleNumberForTypeWthReason()
Other phone functions:
dialr-example
,
dialr-match
,
dialr-phone
,
dialr-region
,
dialr-type
,
dialr
x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") is_parsed(x) is_valid(x) is_possible(x) is_possible(x, detailed = TRUE) is_possible(x, type = "MOBILE") is_possible(x, detailed = TRUE, type = "MOBILE")
x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") is_parsed(x) is_valid(x) is_possible(x) is_possible(x, detailed = TRUE) is_possible(x, type = "MOBILE") is_possible(x, detailed = TRUE, type = "MOBILE")
Returns a carrier name for each phone number, in the language provided
in locale
.
get_carrier( x, strict = FALSE, safe = FALSE, locale = getOption("dialr.locale") )
get_carrier( x, strict = FALSE, safe = FALSE, locale = getOption("dialr.locale") )
x |
A phone vector. |
strict |
Should invalid phone numbers be removed? If |
safe |
If |
locale |
The Java locale
used to retrieve localised results. The default is set in option
|
The carrier name is the one the number was originally allocated to, however
if the country supports mobile number portability the number might not belong
to the returned carrier anymore. If no mapping is found ""
is returned.
A carrier name for each phone number for the given locale, or ""
if
the number is invalid.
get_geocode()
: PhoneNumberToCarrierMapper.getNameForValidNumber()
by
default, or PhoneNumberToCarrierMapper.getSafeDisplayName()
if safe = TRUE
.
x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") get_carrier(x) get_carrier(x, strict = TRUE) get_carrier(x, safe = TRUE)
x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") get_carrier(x) get_carrier(x, strict = TRUE) get_carrier(x, safe = TRUE)
Get ISO country code from a country name.
get_cc(country)
get_cc(country)
country |
A character vector of country names. |
A vector of ISO country codes (NA
where not found).
get_cc("Australia") get_cc(c("Australia", "China", "United states"))
get_cc("Australia") get_cc(c("Australia", "China", "United states"))
Returns a text description for each phone number, in the language provided in
locale
.
get_geocode(x, home = NULL, strict = FALSE, locale = getOption("dialr.locale"))
get_geocode(x, home = NULL, strict = FALSE, locale = getOption("dialr.locale"))
x |
A phone vector. |
home |
ISO country code for home region. See Details. |
strict |
Should invalid phone numbers be removed? If |
locale |
The Java locale
used to retrieve localised results. The default is set in option
|
The description might consist of the name of the country where the phone number is from, or the name of the geographical area the phone number is from if more detailed information is available.
If a phone number is from the region specified in home
, only a
lower-level description will be returned, if one exists. Otherwise, the phone
number's region will be returned, with optionally some more detailed
information.
For example, for a user from the region "US"
(United States), we would show
"Mountain View, CA"
for a particular number, omitting the United States
from the description. For a user from the United Kingdom (region "GB"
), for
the same number we may show "Mountain View, CA, United States"
or even just
"United States"
.
A text description for each phone number for the given locale, or
""
if the number is invalid or could belong to multiple countries.
get_geocode()
:
PhoneNumberOfflineGeocoder.getDescriptionForValidNumber()
.
x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") get_geocode(x) get_geocode(x, strict = TRUE) # Specify a home country get_geocode(x, home = "AU") get_geocode(x, home = "US") # Specify a language get_geocode(x, home = "DE", locale = "de")
x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") get_geocode(x) get_geocode(x, strict = TRUE) # Specify a home country get_geocode(x, home = "AU") get_geocode(x, home = "US") # Specify a language get_geocode(x, home = "DE", locale = "de")
Retrieve a list of CLDR time zones to which a phone number belongs.
get_timezone( x, strict = FALSE, show_progress = getOption("dialr.show_progress") )
get_timezone( x, strict = FALSE, show_progress = getOption("dialr.show_progress") )
x |
A phone vector. |
strict |
Should invalid phone numbers be removed? If |
show_progress |
Should a progress bar be displayed? Defaults to the
option |
This function assumes the phone number is geo-localizable. Fixed-line and mobile numbers are considered possible candidates for geo-localization.
A character vector of time zones to which each phone number belongs,
separated by ;
, or the default unknown time zone "Etc/Unknown"
if no
other time zone was found.
get_timezone()
:
PhoneNumberToTimeZonesMapper.getTimeZonesForGeographicalNumber()
.
x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") get_timezone(x) get_timezone(x, strict = TRUE) # Return a list strsplit(get_timezone(x), ";")
x <- phone(c(0, 0123, "0412 345 678", "61412987654", "03 9123 4567", "+12015550123"), "AU") get_timezone(x) get_timezone(x, strict = TRUE) # Return a list strsplit(get_timezone(x), ";")