round_fmt: Round and prepare a value for display

In formatters: ASCII Formatting for Values and Tables

Round and prepare a value for display

Description

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.

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.

Value

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

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)
round_fmt(.395, digits = 2)
round_fmt(NA, digits = 1)
round_fmt(NA, digits = 1, na_str = "-")
round_fmt(2.765923, digits = NA)
round_fmt(0.845, digits = 2)
round_fmt(0.845, digits = 2, round_type = "sas")

formatters documentation built on April 11, 2025, 5:48 p.m.