phonekeypad

Documentation

Overview

Package phonekeypad converts alphabetic strings and phone number literals to their numeric equivalents on a standard 12-key telephony keypad (ITU E.161 / ITU T.9).

Problem

Many telephony applications, vanity-number look-ups, DTMF generators, and T9-style input systems need to translate letters to the digits printed on a phone keypad. Doing this correctly—handling both upper- and lower-case input, skipping punctuation and separators, and producing either a []int slice or a plain string—requires repetitive boilerplate that this package encapsulates.

Keypad Layout

The standard keypad mapping (ITU E.161) used by this package:

+-----+-----+-----+
|  1  |  2  |  3  |
|     | ABC | DEF |
+-----+-----+-----+
|  4  |  5  |  6  |
| GHI | JKL | MNO |
+-----+-----+-----+
|  7  |  8  |  9  |
| PQRS| TUV | WXYZ|
+-----+-----+-----+
|     |  0  |     |
|     |     |     |
+-----+-----+-----+

Features

• Single-rune conversion (KeypadDigit): convert one character at a time; ideal for streaming input or custom filtering logic.
• Slice output (KeypadNumber): convert a full string to []int, preserving each digit as an integer for arithmetic or comparison.
• String output (KeypadNumberString): convert a full string directly to a digit string, ready for storage, display, or dialing.
• Case-insensitive: accepts both upper- and lower-case letters with no pre-processing required by the caller.
• ASCII-scoped: only ASCII digits '0'–'9' and ASCII letters 'A'–'Z'/'a'–'z' are mapped (per ITU E.161). Every other character — separators, punctuation, whitespace, and any non-ASCII rune such as accented or full-width letters — is silently skipped, so formatted phone numbers like "1-800-FLOWERS" work without sanitisation.
• Zero dependencies: uses only the Go standard library.

Quick Start

Translate a vanity phone number to its dialable form:

numStr := phonekeypad.KeypadNumberString("1-800-FLOWERS")
// numStr == "18003569377"

Or get the digit sequence as a slice for programmatic use:

digits := phonekeypad.KeypadNumber("1-800-FLOWERS")
// digits == []int{1, 8, 0, 0, 3, 5, 6, 9, 3, 7, 7}

Benefits

This package eliminates boilerplate in any Go application that deals with telephony, DTMF, vanity numbers, or T9 text encoding. Its simple, allocation- minimal design makes it suitable for both low-latency request handlers and batch-processing pipelines.

Index

• func KeypadDigit(r rune) (int, bool)
• func KeypadNumber(num string) []int
• func KeypadNumberString(num string) string

Examples

• KeypadDigit
• KeypadNumber
• KeypadNumberString

Functions

func KeypadDigit

func KeypadDigit(r rune) (int, bool)

KeypadDigit maps a single rune to its ITU E.161 phone-keypad digit.

Digits '0'–'9' map to themselves. Letters 'A'–'Z' and 'a'–'z' are mapped case-insensitively according to the standard keypad layout:

'A','B','C'         → 2
'D','E','F'         → 3
'G','H','I'         → 4
'J','K','L'         → 5
'M','N','O'         → 6
'P','Q','R','S'     → 7
'T','U','V'         → 8
'W','X','Y','Z'     → 9

Any rune that is not an ASCII digit or ASCII letter — punctuation, whitespace, symbols, and non-ASCII letters such as 'É' or full-width digits — returns (-1, false). This makes it safe to range over formatted phone strings like "(800) 555-1234" and simply skip characters where ok is false.

Example

package main

import (
	"fmt"

	"github.com/tecnickcom/nurago/pkg/phonekeypad"
)

func main() {
	phoneNumber := "999-EXAMPLE-1"
	numSeq := make([]int, 0, len(phoneNumber))

	for _, r := range phoneNumber {
		v, status := phonekeypad.KeypadDigit(r)
		if status {
			numSeq = append(numSeq, v)
		}
	}

	fmt.Println(numSeq)

}

Output:
[9 9 9 3 9 2 6 7 5 3 1]

func KeypadNumber

func KeypadNumber(num string) []int

KeypadNumber converts a string to a []int of keypad digits.

Each rune in s is passed to KeypadDigit. Characters that do not map to a keypad digit (separators, punctuation, etc.) are silently skipped, so formatted inputs such as "1-800-EXAMPLE" or "(555) 123-4567" are handled without pre-sanitisation.

The returned slice has the same length as the number of valid keypad characters in s. It is never nil: empty or all-separator input yields a non-nil, zero-length slice. Use KeypadNumberString when a plain digit string is preferred over a slice.

Example

package main

import (
	"fmt"

	"github.com/tecnickcom/nurago/pkg/phonekeypad"
)

func main() {
	phoneNumber := "999-EXAMPLE-2"

	numSeq := phonekeypad.KeypadNumber(phoneNumber)

	fmt.Println(numSeq)

}

Output:
[9 9 9 3 9 2 6 7 5 3 2]

func KeypadNumberString

func KeypadNumberString(num string) string

KeypadNumberString converts a string to a keypad digit string.

Each rune in num is mapped via KeypadDigit and the resulting digits are written into a plain string (e.g. "18003569377"), suitable for storage, display, or passing directly to a dialler. Non-keypad characters (separators, punctuation, etc.) are skipped just as in KeypadNumber, so an empty or all-punctuation input yields "".

Example

package main

import (
	"fmt"

	"github.com/tecnickcom/nurago/pkg/phonekeypad"
)

func main() {
	phoneNumber := "999-EXAMPLE-3"

	numStr := phonekeypad.KeypadNumberString(phoneNumber)

	fmt.Println(numStr)

}

Output:
99939267533