dialr-phone: Phone number parsing and formatting

Description

A phone vector stores phone numbers parsed with libphonenumber for formatting and further processing.

Usage

phone(
  x = character(),
  region = character(),
  show_progress = getOption("dialr.show_progress")
)
phone_reparse(x)
is.phone(x)
# S3 method for phone
print(x, n = 10, ...)
# S3 method for phone
format(
  x,
  format = c("E164", "NATIONAL", "INTERNATIONAL", "RFC3966"),
  home = NULL,
  clean = TRUE,
  strict = FALSE,
  ...
)
# S3 method for phone
as.character(x, raw = TRUE, ...)

Arguments

x

A character vector of phone numbers.

region

A character vector of ISO country codes with the default region for each phone number in x. A region vector of length 1 will be recycled to the length of x.

If NA or "", numbers written in international format (with a leading +) will be parsed without a default region.

show_progress

Should a progress bar be displayed? Defaults to the option dialr.show_progress.

n

Number of elements to print.

...

Additional arguments for specific methods.

format

Phone number format to use from one of four standards:

"E164": general format for international telephone numbers from ITU-T Recommendation E.164
"NATIONAL": national notation from ITU-T Recommendation E.123
"INTERNATIONAL": international notation from ITU-T Recommendation E.123
"RFC3966": "tel" URI syntax from the IETF tel URI for Telephone Numbers

See notes from the libphonenumber javadocs for more details.

format defaults to "E164". The default can be set in option dialr.format.

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 TRUE, keeps numbers and leading "+".

strict

Should invalid phone numbers be removed? If TRUE, invalid phone numbers are replaced with NA.

raw

If TRUE, the raw phone number is returned. Otherwise elements are cleaned with format().

libphonenumber reference

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.

Details

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.

Examples

Run this code

  # 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"))