Format Numeric Columns to Fixed-Decimal Character Strings

format_digits(
  data,
  cols = NULL,
  digits = 2L,
  percentage = FALSE,
  nan_as_na = FALSE
)

Arguments

data: A data.frame or data.table. The input dataset.
cols: A character or integer vector specifying columns to format. If NULL (default), all numeric columns are formatted.
digits: A non-negative integer specifying decimal places. Defaults to 2.
percentage: Logical. If TRUE, values are multiplied by 100 and a "%" sign is appended. Defaults to FALSE.
nan_as_na: Logical. If TRUE, NaN is treated identically to NA and coerced to NA_character_. If FALSE (default), NaN is preserved as the string "NaN".

Value

A data.table with the specified numeric columns formatted as character strings. The original object is never modified.

Details

The function processes columns in the following order:

Validates all input parameters with informative error messages.
Copies the input only once: data.table inputs are deep-copied via copy(); data.frame inputs are copied implicitly by as.data.table(), avoiding a redundant second copy.
Resolves cols to a character vector of valid numeric column names, warning and skipping any non-numeric columns specified.
Applies a vectorised formatting function via lapply(.SD, fn) and :=, so all target columns are dispatched in a single data.table call rather than a column-by-column loop.

NA and NaN handling:

NA_real_ is always returned as NA_character_.
NaN is returned as "NaN" by default. Set nan_as_na = TRUE to coerce it to NA_character_ instead.

Rounding uses explicit round() before sprintf() to guarantee consistent results across platforms (Windows, Linux, macOS), where the underlying C library's rounding behaviour may otherwise differ.

Note

data must be a data.frame or data.table.
Integer column indices in cols are converted to column names internally; duplicates are silently removed.
digits accepts numeric values such as 2.0 and coerces them to integer; non-integer-valued numbers raise an error.
The function depends only on data.table and base R.

Examples

# Example: Number formatting demonstrations

# Setup test data
dt <- data.table::data.table(
  a = c(0.1234, 0.5678),      # Numeric column 1
  b = c(0.2345, 0.6789),      # Numeric column 2
  c = c("text1", "text2")     # Text column
)

# Example 1: Format all numeric columns
format_digits(
  dt,                         # Input data table
  digits = 2                  # Round to 2 decimal places
)
#>         a      b      c
#>    <char> <char> <char>
#> 1:   0.12   0.23  text1
#> 2:   0.57   0.68  text2

# Example 2: Format specific column as percentage
format_digits(
  dt,                         # Input data table
  cols = c("a"),              # Only format column 'a'
  digits = 2,                 # Round to 2 decimal places
  percentage = TRUE           # Convert to percentage
)
#>         a      b      c
#>    <char>  <num> <char>
#> 1: 12.34% 0.2345  text1
#> 2: 56.78% 0.6789  text2