---
title: "Getting started with dialvalidator"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with dialvalidator}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

dialvalidator parses, validates, formats, and classifies international phone
numbers using Google's [libphonenumber](https://github.com/google/libphonenumber)
metadata. It covers 240+ territories and requires no Java runtime -- the
metadata is pre-parsed into a native R object and shipped with the package.

```{r setup}
library(dialvalidator)
```

## Validating numbers

`phone_valid()` checks whether a number is valid for its territory. Numbers
can be supplied in international format (with a leading `+`) or national
format (with a `default_region`):

```{r}
# International format -- region inferred from country code
phone_valid("+64211234567")

# National format -- supply the region
phone_valid("021 123 4567", default_region = "NZ")

# Invalid: too short
phone_valid("+6421")

# Vectorised
phone_valid(c("+64211234567", "+12125551234", "not a number", "+61412345678"))
```

## Formatting numbers

Three output formats, matching libphonenumber's conventions:

```{r}
# E.164: compact, no spaces, machine-readable
phone_format("+64211234567", "E164")

# National: how you'd dial it locally
phone_format("+64211234567", "NATIONAL")

# International: with country code and spacing
phone_format("+64211234567", "INTERNATIONAL")
```

Formatting rules are territory-specific -- the same function handles US
parenthesised area codes, UK spacing, and every other convention:

```{r}
phone_format("+12125551234", "NATIONAL")
phone_format("+442071234567", "NATIONAL")
phone_format("+61412345678", "NATIONAL")
```

## Detecting number type

`phone_type()` classifies numbers by matching against per-territory patterns
for each number type:

```{r}
# NZ mobile
phone_type("+64211234567")

# US toll-free
phone_type("+18005551234")
```

Possible types: `mobile`, `fixed_line`, `fixed_line_or_mobile`, `toll_free`,
`premium_rate`, `shared_cost`, `personal_number`, `voip`, `pager`, `uan`,
`voicemail`, `unknown`.

## Country resolution

`phone_country()` returns the ISO 3166-1 alpha-2 region code. For shared
country codes like +1 (NANPA), the package resolves the correct territory
using area-code-level patterns:

```{r}
phone_country(c("+64211234567", "+12125551234", "+14165551234", "+442071234567"))
```

Note that +1 212 resolves to US (New York) while +1 416 resolves to CA (Toronto).

## All-in-one with phone_info()

For batch processing or exploratory analysis, `phone_info()` returns
everything in a single data frame:

```{r}
phone_info(c("+64211234567", "+12125551234", "+61412345678", "+81312345678"))
```

## Working with national-format numbers

When processing numbers from a known country, set `default_region` once:

```{r}
nz_numbers <- c("021 123 4567", "09 300 1234", "0800 123 456")
phone_info(nz_numbers, default_region = "NZ")
```

## Inspecting metadata

You can inspect the underlying libphonenumber metadata for any territory:

```{r}
nz <- dv_territory("NZ")
nz$country_code
nz$national_prefix
nz$mobile$example
```

## Updating metadata

The bundled metadata is current as of the package build date. To fetch the
latest version from Google's repository:

```{r, eval = FALSE}
dv_update_metadata()
```

Updated metadata is cached locally and used for the remainder of the session.
No internet access is needed during normal use.