nombre

License: MIT R build status Dependencies

nombre (French) /nɔ̃bʁ/: number
nombre (Spanish) /ˈnom.bɾe/: name
nombre: package to convert numbers to their names in R

nombre converts numeric vectors to character vectors of English words. You can use it to express numbers as cardinals (one, two, three) or ordinals (first, second, third), as well as numerators and denominators. nombre supports not just whole numbers, but also negatives and fractions.

Installation

You can install the released version of nombre from CRAN with:

install.packages("nombre")

or the development version from GitHub with:

# install.packages("remotes")
remotes::install_github("rossellhayes/nombre")

Usage

nombre converts numerics into words:

nom_card(2)
#> [1] "two"
nom_card(2L)
#> [1] "two"
x <- rep(TRUE, 525600)
nom_card(length(x))
#> [1] "five hundred twenty-five thousand six hundred"

It also works for numeric vectors:

nom_card(8^(1:10))
#>  [1] "eight"                                                                                       
#>  [2] "sixty-four"                                                                                  
#>  [3] "five hundred twelve"                                                                         
#>  [4] "four thousand ninety-six"                                                                    
#>  [5] "thirty-two thousand seven hundred sixty-eight"                                               
#>  [6] "two hundred sixty-two thousand one hundred forty-four"                                       
#>  [7] "two million ninety-seven thousand one hundred fifty-two"                                     
#>  [8] "sixteen million seven hundred seventy-seven thousand two hundred sixteen"                    
#>  [9] "one hundred thirty-four million two hundred seventeen thousand seven hundred twenty-eight"   
#> [10] "one billion seventy-three million seven hundred forty-one thousand eight hundred twenty-four"

nombre can also generate ordinals, adverbials, collectives, numerators and denominators:

nom_ord(1:5)
#> [1] "first"  "second" "third"  "fourth" "fifth"
nom_adv(1:5)
#> [1] "once"        "twice"       "three times" "four times"  "five times"
nom_coll(1:5)
#> [1] "the"       "both"      "all three" "all four"  "all five"
nom_numer(1:5)
#> [1] "one"   "two"   "three" "four"  "five"
nom_denom(1:5)
#> [1] "whole"   "half"    "third"   "quarter" "fifth"
nom_denom(1:5, numerator = 1:5)
#> [1] "whole"    "halves"   "thirds"   "quarters" "fifths"

🤫 (numerators are almost always the same as cardinals)

You can also add ordinal suffixes to numerics or arbitrary number-like strings:

nom_ord(1:5, cardinal = FALSE)
#> [1] "1st" "2nd" "3rd" "4th" "5th"
nom_ord(c("n", "dozen", "umpteen", "eleventy", "one zillion"))
#> [1] "nth"           "dozenth"       "umpteenth"     "eleventieth"  
#> [5] "one-zillionth"

It can also handle less common numerics, like negatives and fractions:

nom_card(-2)
#> [1] "negative two"
nom_card(9.75)
#> [1] "nine and three quarters"

Math with nombres

nombre implements an S3 class that seamlessly decides when to treat nombres like characters and when to treat them like numerics.

x <- nom_card(25)
x
#> [1] "twenty-five"
x + 2
#> [1] "twenty-seven"
sqrt(x)
#> [1] "five"
x < 30
#> [1] TRUE
x == "twenty-five"
#> [1] TRUE

Advantages 🚀

nombre is implemented using vectorized base R and runs faster than alternatives like english:

bench::mark(as.character(nom_card(1:1000)), as.character(english::english(1:1000)))
#> Warning: Some expressions had a GC in every iteration; so filtering is disabled.
#> # A tibble: 2 x 6
#>   expression                               min  median `itr/sec` mem_alloc
#>   <bch:expr>                             <bch> <bch:t>     <dbl> <bch:byt>
#> 1 as.character(nom_card(1:1000))          15ms  20.1ms     50.6     1.02MB
#> 2 as.character(english::english(1:1000)) 198ms 206.4ms      4.84  389.29KB
#> # ... with 1 more variable: `gc/sec` <dbl>

Hex sticker image adapted from artwork by @allison_horst.

Hex sticker fonts are Source Code Pro by Adobe and Permanent Marker by Font Diner.

Please note that nombre is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.