Skip to contents

Round and prepare a value for display

Source: R/format_value.R
round_fmt.Rd

This function is used within format_value() to prepare numeric values within cells for formatting and display.

Usage 

round_fmt(x, digits, na_str = "NA", round_type = c("iec", "sas"))

Arguments

x

(numeric(1))
value to format.

digits

(numeric(1))
number of digits to round to, or NA to convert to a character value with no rounding.

na_str

(string)
the value to return if x is NA.

round_type

("iec" or "sas")
the type of rounding to perform. iec, the default, peforms rounding compliant with IEC 60559 (see details), while sas performs nearest-value rounding consistent with rounding within SAS.

Value

A character value representing the value after rounding, containing any trailing zeros required to display exactly digits elements.

Details

This function combines rounding behavior with the strict decimal display of sprintf(). By default, R's standards-compliant round() function (see the Details section of that documentation) is used. The exact behavior is as follows:

  1. If x is NA, the value of na_str is returned.

  2. If x is non-NA but digits is NA, x is converted to a character and returned.

  3. If x and digits are both non-NA, round() is called first, and then sprintf() is used to convert the rounded value to a character with the appropriate number of trailing zeros enforced.

Note

This differs from the base R round() function in that NA digits indicate x should be converted to character and returned unchanged whereas round(x, digits=NA) returns NA for all values of x.

This behavior will differ from as.character(round(x, digits = digits)) in the case where there are not at least digits significant digits after the decimal that remain after rounding. It may differ from sprintf("\%.Nf", x) for values ending in 5 after the decimal place on many popular operating systems due to round's stricter adherence to the IEC 60559 standard, particularly for R versions > 4.0.0 (see warning in round() documentation).

See also

format_value(), round(), sprintf()

Examples 

round_fmt(0, digits = 3)
#> [1] "0.000"
round_fmt(.395, digits = 2)
#> [1] "0.40"
round_fmt(NA, digits = 1)
#> [1] "NA"
round_fmt(NA, digits = 1, na_str = "-")
#> [1] "-"
round_fmt(2.765923, digits = NA)
#> [1] "2.765923"
round_fmt(0.845, digits = 2)
#> [1] "0.84"
round_fmt(0.845, digits = 2, round_type = "sas")
#> [1] "0.85"