R: Phone number parsing and formatting

dialr-phone {dialr}

R Documentation

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 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, ...)

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()`.

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.

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.

Examples

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

[Package dialr version 0.4.2 Index]