---
title: "Introduction to dialr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to dialr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, include = FALSE}
library(dialr)
# load dplyr here to avoid mask warnings
library(dplyr, warn.conflicts = FALSE)
```

dialr is an R interface to [Google's libphonenumber java library](https://github.com/google/libphonenumber).

libphonenumber defines the `PhoneNumberUtil` class, a set of functions for extracting information from and performing processing on a parsed `Phonenumber` object. A phone number must be parsed before any other operations (e.g. checking phone number validity, formatting) can be performed.

dialr provides an interface to these functions to easily parse and process phone numbers in R.

## Parsing phone numbers

A phone class vector stores a parsed java `Phonenumber` object for further processing alongside the original raw text phone number and default region. This "default region" is required to determine the processing context for non-international numbers.

To create a phone vector, use the `phone()` function. This takes a character vector of phone numbers to parse and a default region for phone numbers not stored in an international format (i.e. with a leading "+").

```{r}
library(dialr)

# Parse phone number vector
x <- c(0, 0123, "0404 753 123", "61410123817", "+12015550123")
x <- phone(x, "AU")

is.phone(x)
print(x)
```

## Basic phone functions

```{r}
is_parsed(x)    # Was the phone number successfully parsed?
is_valid(x)     # Is the phone number valid?
is_possible(x)  # Is the phone number possible?
get_region(x)   # What region (ISO country code) is the phone number from?
get_type(x)     # Is the phone number a fixed line, mobile etc.
```

## Comparing phone numbers

Equality comparisons for phone numbers ignore formatting differences and compare the underlying phone number.

```{r}
phone("0404 753 123", "AU") == phone("+61404753123", "US")
phone("0404 753 123", "AU") == phone("0404 753 123", "US")
phone("0404 753 123", "AU") != phone("0404 753 123", "US")
```

Parsed phone numbers can also be compared to character phone numbers stored in an international format.

```{r}
phone("0404 753 123", "AU") == c("+61404753123", "0404 753 123")
```

Use `is_match()` for more customisable comparisons.

```{r}
is_match(phone("0404 753 123", "AU"), c("+61404753123", "0404753123", "1234"))
is_match(phone("0404 753 123", "AU"), c("+61404753123", "0404753123", "1234"), detailed = TRUE)
is_match(phone("0404 753 123", "AU"), c("+61404753123", "0404753123", "1234"), strict = FALSE)
```

## Formatting phone numbers

The phone class has a `format()` method implementing libphonenumber's core formatting functionality.

There are four phone number formats used by libphonenumber (see "Further reading" for details): `"E164"`, `"NATIONAL"`, `"INTERNATIONAL"` and`"RFC3966"`.
These can be specified by the `format` argument, or a default can be specifed in option `dialr.format`.

If `clean = TRUE`, all non-numeric characters are removed except for a leading `+`. `clean = TRUE` by default.

```{r}
x <- phone(c(0, 0123, "0404 753 123", "61410123817", "+12015550123"), "AU")

format(x, format = "RFC3966")
format(x, format = "RFC3966", clean = FALSE)

format(x, format = "E164", clean = FALSE)
format(x, format = "NATIONAL", clean = FALSE)
format(x, format = "INTERNATIONAL", clean = FALSE)
format(x, format = "RFC3966", clean = FALSE)

# Change the default
getOption("dialr.format")
format(x)
options(dialr.format = "NATIONAL")
format(x)
options(dialr.format = "E164")
```

If the `home` argument is supplied, the phone number is formatted for dialling from the specified country.

```{r}
format(x, home = "AU")
format(x, home = "US")
format(x, home = "JP")
```

If `strict = TRUE`, invalid phone numbers (determined using `is_valid()`) return `NA`.

```{r}
format(x)
format(x, strict = TRUE)
```

By default, `as.character()` returns the raw text phone number. Use `raw = FALSE` to use the `format()` method instead.

```{r}
as.character(x)
as.character(x, raw = FALSE)
```

## Use with dplyr

dialr functions are designed to work well in dplyr workflows.

```{r}
# Use with dplyr
library(dplyr)

y <- tibble(id = 1:4,
            phone1 = c(0, 0123, "0404 753 123", "61410123817"),
            phone2 = c("03 9388 1234", 1234, "+12015550123", 0),
            country = c("AU", "AU", "AU", "AU"))

y %>%
  mutate_at(vars(matches("^phone")), ~phone(., country)) %>%
  mutate_at(vars(matches("^phone")),
            list(valid = is_valid,
                 region = get_region,
                 type = get_type,
                 clean = format))
```

## Further reading

### libphonenumber

[GitHub](https://github.com/google/libphonenumber)

[Frequently Asked Questions](https://github.com/google/libphonenumber/blob/master/FAQ.md)

[Falsehoods Programmers Believe About Phone Numbers](https://github.com/google/libphonenumber/blob/master/FALSEHOODS.md)

[javadocs](https://javadoc.io/doc/com.googlecode.libphonenumber/libphonenumber/)

### Phone number format standards

`"E164"`: general format for international telephone numbers from [ITU-T Recommendation E.164](https://en.wikipedia.org/wiki/E.164)

`"NATIONAL"`: national notation from [ITU-T Recommendation E.123](https://en.wikipedia.org/wiki/E.123)

`"INTERNATIONAL"`: international notation from [ITU-T Recommendation E.123](https://en.wikipedia.org/wiki/E.123)

`"RFC3966"`: "tel" URI syntax from the IETF [tel URI for Telephone Numbers](https://datatracker.ietf.org/doc/rfc3966/)

### ISO country codes

[ISO 3166](https://www.iso.org/iso-3166-country-codes.html)

[Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1)