Skip to contents

Translate a vector of numbers to a cardinal character vector

Source: R/number-friendly.R
number_friendly.Rd

Convert a vector of numbers to a cardinal numeral (e.g. one tenth, one, two).

number_friendly_safe() checks that all arguments are of the correct type and raises an informative error otherwise. number_friendly() does not perform input validation to maximize its speed.

Usage

number_friendly(numbers, ...)

# S3 method for class 'numeric'
number_friendly(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  decimal = " and ",
  and = FALSE,
  hyphenate = TRUE,
  and_fractional = and,
  hyphenate_fractional = hyphenate,
  english_fractions = NULL,
  ...
)

# S3 method for class 'integer'
number_friendly(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE,
  ...
)

# S3 method for class 'bignum_biginteger'
number_friendly(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE,
  ...
)

# S3 method for class 'bignum_bigfloat'
number_friendly(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  decimal = " and ",
  and = FALSE,
  hyphenate = TRUE,
  and_fractional = and,
  hyphenate_fractional = hyphenate,
  english_fractions = NULL,
  ...
)

# Default S3 method
number_friendly(numbers, ...)

number_friendly_safe(numbers, ...)

# S3 method for class 'numeric'
number_friendly_safe(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  decimal = " and ",
  and = FALSE,
  hyphenate = TRUE,
  and_fractional = and,
  hyphenate_fractional = hyphenate,
  english_fractions = NULL,
  ...
)

# S3 method for class 'integer'
number_friendly_safe(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE,
  ...
)

# S3 method for class 'bignum_biginteger'
number_friendly_safe(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE,
  ...
)

# S3 method for class 'bignum_bigfloat'
number_friendly_safe(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  decimal = " and ",
  and = FALSE,
  hyphenate = TRUE,
  and_fractional = and,
  hyphenate_fractional = hyphenate,
  english_fractions = NULL,
  ...
)

# Default S3 method
number_friendly_safe(numbers, ...)

Arguments

numbers

A vector of numbers to translate. The friendlynumber package defines methods for integer, numeric, bignum::biginteger(), and bignum::bigfloat() numbers.

...

Additional arguments passed to or from other methods.

zero

[character(1)]

What to call values of 0 in numbers (e.g. zero = "zero").

na

[character(1)]

What to call values of NA in numbers (e.g. na = "missing").

nan

[character(1)]

What to call values of NaN in numbers (e.g. nan = "undefined").

inf

[character(1)]

What to call values of Inf in numbers (e.g. inf = "infinity").

negative

[character(1)]

A prefix added to the translation of negative elements of numbers. negative is the string "negative " by default.

decimal

[character(1)]

A word inserted between the whole and fractional part of translated numbers. decimal is the string " and " by default.

and

[TRUE / FALSE]

Whether to insert an " and " before the tens place of translated numbers. and is FALSE by default.

hyphenate

[TRUE / FALSE]

Whether to hyphenate numbers 21 through 99 (e.g. "twenty-one" vs. "twenty one"). hyphenate is TRUE by default.

and_fractional

[TRUE / FALSE]

Whether to insert an " and " before the smallest fractional tens place of translated numbers (e.g. "one hundred one thousandths" vs. "one hundred and one thousandths").

and_fractional is equal to and by default.

hyphenate_fractional

[TRUE / FALSE]

Whether to hyphenate numbers 21 through 99 in the fractional part of translated numbers (e.g. "twenty-one hundredths" or "twenty one hundredths"). This also determines the hyphenation of the fractional units (e.g. "one ten-millionth" vs. "one ten millionth").

hyphenate_fractional is equal to hyphenate by default.

english_fractions

[character]

A named character vector used as a dictionary for the translation of the fractional part of numbers. The names (i.e. keys) are the decimal digits of a fractional number and the values are the corresponding translations.

For example english_fractions = c("5" = "a half") matches the number 0.5 (translated as "a half") and 2.5 (translated as "two and a half").

By default english_fractions is a named character vector with translations for fractions x / y for x = 1, 2, ..., 8 and y = 1, 2, ..., 9. For example, 2 / 3 is translated as "two thirds" and 1 / 2 is translated as "one half".

Provide an empty character to english_fractions to opt out of any such translations. In this case 1 / 2 is translated as "five tenths" instead of "one half".

Value

A non-NA character vector of the same length as numbers.

See also

integerish_friendly(), numeric_friendly(), biginteger_friendly(), bigfloat_friendly()

Examples

number_friendly(c(1/3, 0, 0.999, NA, NaN, Inf, -Inf))
#> [1] "one third"                           
#> [2] "zero"                                
#> [3] "nine hundred ninety-nine thousandths"
#> [4] "missing"                             
#> [5] "not a number"                        
#> [6] "infinity"                            
#> [7] "negative infinity"                   
number_friendly(c(1L, 2L, 1001L))
#> [1] "one"              "two"              "one thousand one"

# Input validation
try(number_friendly_safe(1L, zero = c("a", "zero")))
#> Error : `zero` must be a string, not a character vector of length 2.