format()

format(x, trim = FALSE, digits = NULL, nsmall = 0, scientific = NA, ...)

The format() function formats R objects for pretty printing. It converts objects to character vectors with controlled formatting.

Syntax

format(x, trim = FALSE, digits = NULL, nsmall = 0, scientific = NA, 
       big.mark = "", big.interval = 3, small.mark = "", 
       small.interval = 5, decimal.mark = ".", ...)

Parameters

Parameter	Type	Default	Description
x	object	required	An atomic object to format
trim	logical	FALSE	If TRUE, removes leading whitespace
digits	integer	NULL	Number of significant digits
nsmall	integer	0	Minimum decimal places
scientific	logical	NA	Force/disable scientific notation
big.mark	character	""	Separator for thousands
decimal.mark	character	”.”	Decimal separator
...	arguments	passed to format.info()	Additional arguments forwarded to format.info()

Examples

Basic number formatting

# Default formatting pads with spaces
format(123.456)
# [1] "123.456"

# Fix decimal places
format(123.456, nsmall = 2)
# [1] "123.46"

Controlling decimal places

The nsmall argument sets a floor on decimal places — useful when every number in a column must show the same precision. The digits argument controls significant figures instead, which is the right choice for scientific contexts where the scale varies widely across values. Both arguments are ignored when x is not numeric.

# Minimum decimal places
format(c(1, 2.5, 3.14159), nsmall = 2)
# [1] "1.00"    "2.50"    "3.14"

# Significant digits
format(pi, digits = 5)
# [1] "3.1416"

Adding thousand separators

big.mark inserts a character between every big.interval digits (default 3), turning 1234567 into "1,234,567". This is standard for financial reports and makes large numbers scannable. Combined with nsmall, it produces the familiar accounting format with two decimal places and comma separators.

# Add commas as thousand separators
format(1234567, big.mark = ",")
# [1] "1,234,567"

format(1234567.89, big.mark = ",", nsmall = 2)
# [1] "1,234,567.89"

Trimming whitespace

By default, format() right-aligns numbers by padding with spaces so all elements in a vector have the same character width. Set trim = TRUE to strip that padding when you need the bare string. This matters most when embedding formatted numbers inside prose or passing to paste0() where leading spaces would create awkward gaps.

# Default adds padding for alignment
format(1:5)
# [1] "1" "2" "3" "4" "5"

# Trim to remove padding
format(1:5, trim = TRUE)
# [1] "1" "2" "3" "4" "5"

Common patterns

The examples above show individual arguments in isolation. Real workflows combine format() with other R functions to produce polished output for reports, dashboards, and data exports. The following patterns cover the most frequent use cases in data analysis pipelines.

Pretty-printing tables

# Create aligned numeric output
df <- data.frame(
  name = c("Sales", "Profit", "Growth"),
  value = c(1234567, 98765, 0.12345)
)

df$value <- format(df$value, big.mark = ",", nsmall = 2)
print(df)
#    name        value
# 1  Sales 1,234,567.00
# 2 Profit     98,765.00
# 3 Growth          0.12

Combining with paste

Once numbers are formatted, paste0() embeds them into human-readable labels. The currency pattern — paste0("$", format(amount, big.mark = ",", nsmall = 2)) — is a one-liner that turns a raw number into "$1,999.99". Wrap this in a function if you format many columns the same way; it keeps your data-cleaning scripts DRY.

# Create formatted output strings
x <- 1234.5678
paste0("The value is: ", format(x, nsmall = 2))
# [1] "The value is: 1234.57"

# Currency formatting
amount <- 1999.99
paste0("$", format(amount, big.mark = ",", nsmall = 2))
# [1] "$1,999.99"

format() vs formatC() vs sprintf()

format() is R-idiomatic and handles vectors well. It accepts named arguments like big.mark, scientific, nsmall, and trim that cover most number formatting needs without learning format codes. The output is always right-aligned by default to align columns when printing tables.

formatC() uses C-style format codes ("f", "e", "g", "d", "s") and is useful when you already know C printf conventions or need fine-grained control over field width and padding character. It is slightly lower-level than format() but produces more predictable output for fixed-width formatting.

sprintf() is the most powerful of the three, it lets you interpolate multiple values into a template string in one call. Use sprintf() for building formatted messages or constructing strings with multiple substitutions; use format() for standalone number rendering.

A common mistake with format() is forgetting that it returns a character vector, not a number. After formatting, the value cannot be used in arithmetic without converting back with as.numeric().

The trim = FALSE default right-aligns numbers within a field width, which is why the output of format(c(1, 10, 100)) produces " 1", " 10", "100", all three are the same width. This alignment behavior is intentional and useful when printing a column in a table or report. Set trim = TRUE to remove the leading spaces if you need the string without padding. Note that format() returns strings — if you later need the numeric value, you must convert back with as.numeric() or as.integer().

format() is the base R function for converting values to character strings with controlled formatting. It applies to vectors, returning a character vector of the same length. When called on a numeric vector, it pads all elements to the same width by default (justify = "right"), which makes the output suitable for column-aligned display. This automatic width normalization is why format(c(1, 100, 1000)) returns c(" 1", " 100", "1000") rather than c("1", "100", "1000").

For formatted output in strings, sprintf() is more flexible than format() when you need to embed values inside a template with multiple format codes. Use format() when you need a formatted character vector to assign to a variable, and sprintf() when you need to compose a sentence or line of text with embedded values.

See also

• formatC()
• sprintf()