Translate a bigfloat to a cardinal character vector

Description

Convert a ⁠<bignum_bigfloat>⁠ to a cardinal numeral (e.g. one tenth, one, two).

A bignum::bigfloat() can store numbers with up to 50 decimal digits of precision, which is useful for manipulating numbers which can't be accurately represented in a ⁠<numeric>⁠ vector.

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

Usage

bigfloat_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
)

bigfloat_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
)

Arguments

Value

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

Examples

bigfloat_friendly(bignum::bigfloat(c(0.5, 0, 0.123, NA, NaN, Inf)))

# Specify the translations of "special" numbers
bigfloat_friendly(bignum::bigfloat(NaN), nan = "NAN")

# Modify the output formatting
big <- bignum::bigfloat(1234.5678)
bigfloat_friendly(big)
bigfloat_friendly(big, decimal = " point ")
bigfloat_friendly(big, hyphenate_fractional = FALSE)
bigfloat_friendly(big, and = TRUE, and_fractional = TRUE, decimal = " . ")

# The `friendlynumber.bigfloat.digits` option specifies the number of
# `<bignum_bigfloat>` digits mentioned by `bigfloat_friendly()`
opts <- options()
options(friendlynumber.bigfloat.digits = 5)
bigfloat_friendly(bignum::bigpi)

options(friendlynumber.bigfloat.digits = 10)
bigfloat_friendly(bignum::bigpi)
options(opts)

# Set `english_fractions` to specify the translation of certain
# fractions. The names (keys) of `english_fractions` should match
# the decimal part of a fraction (e.g. `"04"` matches `0.04`).
bigfloat_friendly(
  bignum::bigfloat(c(1/2, 0.04, 1.5, 10)),
  english_fractions = c(`5` = "1/2", `04` = "4/100")
)

# Input validation
try(bigfloat_friendly_safe(bignum::bigpi, and = NA))

Translate a biginteger to a cardinal character vector

Description

Convert a ⁠<bignum_biginteger>⁠ to a cardinal numeral (e.g. one, two, three).

A bignum::biginteger() can store any integer (i.e. arbitrary precision), which is useful for manipulating numbers too large to be represented (accurately) in an ⁠<integer>⁠ or ⁠<numeric>⁠ vector.

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

Usage

biginteger_friendly(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE
)

biginteger_friendly_safe(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE
)

Arguments

Value

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

Examples

biginteger_friendly(bignum::biginteger(c(0, 1, 2, NA, 10001)))

# Specify the translations of "special" numbers
biginteger_friendly(bignum::biginteger(-10), negative = "minus ")
biginteger_friendly(bignum::biginteger(NA), na = "unknown")

# Modify the output formatting
biginteger_friendly(bignum::biginteger(9999))
biginteger_friendly(bignum::biginteger(9999), and = TRUE)
biginteger_friendly(bignum::biginteger(9999), hyphenate = FALSE)

# Translate large numbers
large <- bignum::biginteger(10L)^1001L
biginteger_friendly(large)

# Input validation
try(biginteger_friendly_safe(1L))

Format a vector of numbers

Description

Format a vector of numbers using format().

Usage

format_number(x, ...)

## S3 method for class 'integer'
format_number(x, bigmark = TRUE, ...)

## S3 method for class 'bignum_biginteger'
format_number(x, bigmark = TRUE, ...)

## S3 method for class 'numeric'
format_number(x, bigmark = TRUE, ...)

## S3 method for class 'bignum_bigfloat'
format_number(x, bigmark = TRUE, ...)

## Default S3 method:
format_number(x, ...)

Arguments

Details

The number of decimal digits shown in the output of format_number() is controlled the friendlynumber.numeric.digits option for numeric vectors and friendlynumber.bigfloat.digits for bignum::bigfloat() vectors.

These options also control the number of decimal digits translated by numeric_friendly() and bigfloat_friendly() respectively. Because of this, format_number() is useful for verifying that the output of these ⁠*_friendly()⁠ functions is correct.

Value

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

Examples

format_number(c(1/3, 0, 0.999, NA, NaN, Inf, -Inf))
format_number(c(1L, 2L, 1001L))
format_number(1001L, bigmark = FALSE)

# Set `friendlynumber.numeric.digits` to control the decimal output
opts <- options()
options(friendlynumber.numeric.digits = 2)
format_number(1234.1234)
options(opts)

if (requireNamespace("bignum", quietly = TRUE)) {
  format_number(bignum::bigfloat(1234.1234))
  format_number(bignum::biginteger(2000000))

  # Set `friendlynumber.bigfloat.digits` to control the decimal output
  opts <- options()
  options(friendlynumber.bigfloat.digits = 3)
  format_number(bignum::bigfloat(1234.1234))
  options(opts)
}

Get the default options set by the friendlynumber package

Description

Returns a list of options provided to options() when the friendlynumber package is loaded. Options set prior to loading the friendlynumber package are not overwritten on load.

Usage

friendlynumber_default_options()

Value

A named list of options.

Examples

friendlynumber_default_options()

Translate integer-ish numbers to a cardinal character vector

Description

Convert an integer vector, or numeric vector which is coercible to an integer without loss of precision, to a cardinal numeral (e.g. one, two, three).

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

Usage

integerish_friendly(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE
)

integerish_friendly_safe(
  numbers,
  zero = "zero",
  na = "missing",
  nan = "not a number",
  inf = "infinity",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE
)

Arguments

Value

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

Examples

integerish_friendly(c(0, 1, 2, NA, NaN, Inf, -Inf))
integerish_friendly(10^10)

# Specify the translations of "special" numbers
integerish_friendly(-10, negative = "minus ")
integerish_friendly(NaN, nan = "undefined")

# Modify the output formatting
integerish_friendly(1234)
integerish_friendly(1234, and = TRUE)
integerish_friendly(1234, hyphenate = FALSE)

# Input validation
try(integerish_friendly_safe(0.5))
try(integerish_friendly_safe(1L, na = TRUE))

Translate integer-ish numbers to a character vector of nths (1st, 2nd, 3rd)

Description

Convert an integer vector, or numeric vector which is coercible to an integer without loss of precision, to an "nth" (e.g. 1st, 2nd, 3rd, 22nd, 1,000th).

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

Usage

nth_friendly(
  numbers,
  zero = "0th",
  na = "missingth",
  nan = "not a numberth",
  inf = "infinitieth",
  negative = "negative ",
  bigmark = TRUE
)

nth_friendly_safe(
  numbers,
  zero = "zeroth",
  na = "missingth",
  nan = "not a numberth",
  inf = "infinitieth",
  negative = "negative ",
  bigmark = TRUE
)

Arguments

Value

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

Examples

nth_friendly(c(0, 1, 2, 3, 22, 1001, NA, NaN, Inf, -Inf))

# Specify the translations of "special" numbers
nth_friendly(c(1, 0, NA), zero = "noneth", na = "?")

# Use `bigmark` to add or remove commas
nth_friendly(1234, bigmark = TRUE)
nth_friendly(1234, bigmark = FALSE)

# Input validation
try(nth_friendly_safe(1234, bigmark = ","))

Translate integer-ish numbers to a character vector of counts (once, twice, three times)

Description

Convert an integer vector, or numeric vector which is coercible to an integer without loss of precision, to a count (e.g. no times, once, twice, four times).

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

Usage

ntimes_friendly(
  numbers,
  one = "once",
  two = "twice",
  three = "three times",
  zero = "no times",
  na = "an unknown number of times",
  nan = "an undefined number of times",
  inf = "infinite times",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE
)

ntimes_friendly_safe(
  numbers,
  one = "once",
  two = "twice",
  three = "three times",
  zero = "no times",
  na = "an unknown number of times",
  nan = "an undefined number of times",
  inf = "infinite times",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE
)

Arguments

Value

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

Examples

ntimes_friendly(c(0, 1, 2, 3, 22, 1001, NA, NaN, Inf, -Inf))

# Specify the translations of "special" numbers
ntimes_friendly(c(3, NA), three = "thrice", na = "some times")

# Modify the output formatting
ntimes_friendly(5678)
ntimes_friendly(5678, and = TRUE)
ntimes_friendly(5678, hyphenate = FALSE)

# Input validation
try(ntimes_friendly_safe(1234, and = " - "))

Translate a vector of numbers to a cardinal character vector

Description

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

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))
number_friendly(c(1L, 2L, 1001L))

# Input validation
try(number_friendly_safe(1L, zero = c("a", "zero")))

Translate a numeric vector to a cardinal character vector

Description

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

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

Usage

numeric_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
)

numeric_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
)

Arguments

Value

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

Examples

numeric_friendly(c(1/3, 0, 0.999, NA, NaN, Inf, -Inf))

# Specify the translations of "special" numbers
numeric_friendly(c(1, 0, Inf), zero = "none", inf = "all")

# Modify the output formatting
frac <- 8765.4321
numeric_friendly(frac)
numeric_friendly(frac, decimal = " dot ")
numeric_friendly(frac, hyphenate = TRUE, hyphenate_fractional = FALSE)
numeric_friendly(frac, and = TRUE, and_fractional = TRUE, decimal = " . ")

# The `friendlynumber.numeric.digits` option specifies the number of
# numeric digits mentioned by `numeric_friendly()`
opts <- options()
options(friendlynumber.numeric.digits = 5)
numeric_friendly(0.0987654321)

options(friendlynumber.numeric.digits = 10)
numeric_friendly(0.0987654321)
options(opts)

# Set `english_fractions` to specify the translation of certain
# fractions. The names (keys) of `english_fractions` should match
# the decimal part of a fraction (e.g. `"5"` matches `0.5`).
numeric_friendly(
  c(1/2, 6/5, 12),
  english_fractions = c(`5` = "1/2", `2` = "1/5")
)

# Input validation
try(numeric_friendly_safe("A"))

Translate integer-ish numbers to an ordinal character vector

Description

Convert an integer vector, or numeric vector which is coercible to an integer without loss of precision, to an ordinal numeral (e.g. first, second, third).

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

Usage

ordinal_friendly(
  numbers,
  zero = "zeroth",
  na = "missingth",
  nan = "not a numberth",
  inf = "infinitieth",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE
)

ordinal_friendly_safe(
  numbers,
  zero = "zeroth",
  na = "missingth",
  nan = "not a numberth",
  inf = "infinitieth",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE
)

Arguments

Value

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

Examples

ordinal_friendly(c(0, 1, 2, 3, NA, NaN, Inf, -Inf))
ordinal_friendly(10^10)

# Specify the translations of "special" numbers
ordinal_friendly(0, zero = "noneth")

# Modify the output formatting
ordinal_friendly(1234)
ordinal_friendly(1234, and = TRUE)
ordinal_friendly(1234, hyphenate = FALSE)

# Input validation
try(ordinal_friendly_safe(0.5))

Parameter Descriptions for friendlynumber Package

Description

Default parameter descriptions which may be overridden in individual functions.

Arguments

Value

The value NULL.

Translate integer-ish numbers to a character vector of quantifiers (the, both, all three)

Description

Convert an integer vector, or numeric vector which is coercible to an integer without loss of precision, to a quantifier (e.g. no, the, every, all five).

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

Usage

quantifier_friendly(
  numbers,
  one = "the",
  two = "both",
  zero = "no",
  na = "a missing",
  nan = "an undefined",
  inf = "every",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE,
  bigmark = TRUE,
  max_friendly = 100
)

quantifier_friendly_safe(
  numbers,
  one = "the",
  two = "both",
  zero = "no",
  na = "a missing",
  nan = "an undefined",
  inf = "every",
  negative = "negative ",
  and = FALSE,
  hyphenate = TRUE,
  bigmark = TRUE,
  max_friendly = 100
)

Arguments

Value

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

Examples

quantifier_friendly(c(0, 1, 2, 3, NA, NaN, Inf))

# The `negative` prefix appears after the `"all"` prefix
quantifier_friendly(-4)

# `-1` and `-2` are not translated using `one` and `two`
quantifier_friendly(c(1, 2, -1, -2), one = "the", two = "both")

# Suppress the translation of large numbers
quantifier_friendly(c(99, 1234), max_friendly = -Inf)
quantifier_friendly(c(99, 1234), max_friendly = 100)
quantifier_friendly(c(99, 1234), max_friendly = 1500)

# Specify the translations of "special" numbers
quantifier_friendly(c(1, Inf), one = "a", inf = "all")

# Arguments `one`, `two`, `inf`, etc. take precedence over `max_friendly`
quantifier_friendly(1:3, one = "one", two = "two", max_friendly = -1)

# Modify the output formatting
quantifier_friendly(1021, max_friendly = Inf)
quantifier_friendly(1021, and = TRUE, max_friendly = Inf)
quantifier_friendly(1021, hyphenate = FALSE, max_friendly = Inf)
quantifier_friendly(1021, bigmark = FALSE, max_friendly = 10)
quantifier_friendly(1021, bigmark = TRUE, max_friendly = 10)

# Input validation
try(quantifier_friendly_safe(1234, max_friendly = NA))