---
title: "phonenumber"
author: "Steve Myles"
date: 2015-09-07
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{phonenumber}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction to phonenumber

This document describes the usage of the two functions in the `phonenumber`
package. Note that, though this package's functions convert back and forth from
numbers to English letters as on a telephone's keypad, the length of
the character string need not conform to any standard length telephone number.

### Background

When I recently posted some of my [Turbo Pascal Stuff](https://stevemyles.site/blog/2015/06/19/turbo-pascal-stuff/), I found an incomplete 
program that was supposed to do this. I was active on [BBSes](https://en.wikipedia.org/wiki/Bulletin_board_system) and, though I don't 
recall the reason, I wanted a way to determine the possible words spelled by the
BBS phone numbers (and/or how to determine what phone numbers correspond to 
words/phrases). I never got around to finishing the second part (numbers to 
letters) in Turbo Pascal, though.

I decided to create this functionality in R for three reasons:

1. to see if I could write the functions
2. to learn to publish a package to CRAN
3. to serve as a possible pedagogical example for others as it involves working 
with lists, splitting strings, and the [expand.grid](https://stat.ethz.ch/R-manual/R-devel/library/base/html/expand.grid.html) function.

### phonenumber's functions

* `letterToNumber`
* `numberToLetter`

### Telephone keypad

For purposes of this package, the mapping of numbers to letters on a telephone's
keypad are as follows:

* *Default behavior* - if parameter `qz` is omitted (or has a value other than 0):  
    * 2 corresponds to A, B, C
    * 3 corresponds to D, E, F
    * 4 corresponds to G, H, I
    * 5 corresponds to J, K, L
    * 6 corresponds to M, N, O
    * 7 corresponds to P, Q, R, S
    * 8 corresponds to T, U, V
    * 9 corresponds to W, X, Y, Z
    * 0 and 1 have no corresponding letters
* *Alternate behavior* - if parameter `qz` = 0:
    * 2 corresponds to A, B, C
    * 3 corresponds to D, E, F
    * 4 corresponds to G, H, I
    * 5 corresponds to J, K, L
    * 6 corresponds to M, N, O
    * 7 corresponds to P, R, S
    * 8 corresponds to T, U, V
    * 9 corresponds to W, X, Y
    * 0 corresponds to Q, Z
    * 1 has no corresponding letters
  
```{r library, echo=FALSE}
library(phonenumber)
```

## `letterToNumber`

`letterToNumber` converts a string containing letters into the corresponding 
numbers on a telephone's keypad. For example, if the user wants to know what 
telephone number corresponds to "Texas:"

```{r letterToNumber ex1}
string <- "Texas"
letterToNumber(string)
```

The function is not limited to letters. Any numeric characters are
returned as is and any non-alphanumeric characters (including spaces) are 
converted to dashes (-):

```{r letterToNumber ex2, echo = TRUE}
string <- "Texas is #1"
letterToNumber(string)
```

Strings need not be limited to any specific format and all numbers are returned 
as is:

```{r letterToNumber ex3, echo = TRUE}
letterToNumber("Jenny's number is 867-5309")
```

## `numberToLetter`

`numberToLetter` converts a string containing numbers into the corresponding 
letters on a telephone's keypad. For example, if the user wants to know what 
possible character strings could be spelled by a sequence of numbers (e.g., 22):

```{r numberToLetter ex1}
string <- "22"
numberToLetter(string)
```

The function is not limited to numbers. Any alphabetic characters are
returned as is and any non-alphanumeric characters (including spaces) are 
converted to dashes (-) and 1 and 0 are returned as is:

```{r numberToLetter ex2, echo = TRUE}
string <- "806!"
numberToLetter(string)
```