format_digits: Format Numeric Columns to Fixed-Decimal Character Strings

In mintyr: Grouped and Nested Data Pipelines Built on 'data.table'

Format Numeric Columns to Fixed-Decimal Character Strings

Description

Format Numeric Columns to Fixed-Decimal Character Strings

Usage

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".

Details

The function processes columns in the following order:

1. Validates all input parameters with informative error messages.

2. 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.

3. Resolves cols to a character vector of valid numeric column names, warning and skipping any non-numeric columns specified.

4. 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.

Value

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

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
)

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

mintyr documentation built on Oct. 5, 2026, 5:08 p.m.