Formatting Options

Duncan Murdoch

2023-11-05

Many formatting functions eventually make use of base::format(), which has a large number of formatting options. This document shows examples of all of the current options in R 4.3.1.

For more formatting options, there’s also base::prettyNum(). It has a few options that are not documented here: input.d.mark, preserve.width, replace.zero, is.cmplx.

To format using C-like format strings, use base::sprintf(). The base::formatC() function offers many of the same options using arguments like the ones in base::format() or base::prettyNum().

The following vectors are used in the examples:

small <- 10^(-(5:9))
big <- 10^(5:9)
mixed <- c(0, 0.1, 1, 10, 100)
decimals <- c(1, 1.2, 1.23, 1.234, 12.234)
char <- c("a", "ab", "abc", "abcd", NA)

Options are presented in alphabetical order. The descriptions are mostly taken from the R documentation, either ?base::format or ?base::prettyNum.

big.interval

digits between big.mark; defaults to 3.

format(big, big.interval = 3, big.mark = " ", scientific = FALSE)
#> [1] "      100 000" "    1 000 000" "   10 000 000" "  100 000 000"
#> [5] "1 000 000 000"
format(big, big.interval = 4, big.mark = " ", scientific = FALSE)
#> [1] "     10 0000" "    100 0000" "   1000 0000" " 1 0000 0000" "10 0000 0000"

big.mark

character; if not empty used as mark between every big.interval decimals before (hence big) the decimal point.

format(big, big.mark = ",", scientific = FALSE)
#> [1] "      100,000" "    1,000,000" "   10,000,000" "  100,000,000"
#> [5] "1,000,000,000"
format(big, big.mark = " ", scientific = FALSE)
#> [1] "      100 000" "    1 000 000" "   10 000 000" "  100 000 000"
#> [5] "1 000 000 000"

decimal.mark

the character to be used to indicate the numeric decimal point.

format(decimals, decimal.mark = ".")
#> [1] " 1.000" " 1.200" " 1.230" " 1.234" "12.234"
format(decimals, decimal.mark = ",")
#> [1] " 1,000" " 1,200" " 1,230" " 1,234" "12,234"

digits

a positive integer indicating how many significant digits are to be used for numeric and complex x. The default, NULL, uses getOption(“digits”). This is a suggestion: enough decimal places will be used so that the smallest (in magnitude) number has this many significant digits, and also to satisfy nsmall. (For more, notably the interpretation for complex numbers see signif.)

format(decimals, digits = 2)
#> [1] " 1.0" " 1.2" " 1.2" " 1.2" "12.2"
format(decimals, digits = 3)
#> [1] " 1.00" " 1.20" " 1.23" " 1.23" "12.23"

drop0trailing

logical, indicating if trailing zeros, i.e., “0” after the decimal mark, should be removed; also drops “e+00” in exponential formats.

format(decimals, drop0trailing = FALSE)
#> [1] " 1.000" " 1.200" " 1.230" " 1.234" "12.234"
format(decimals, drop0trailing = TRUE)
#> [1] " 1"     " 1.2"   " 1.23"  " 1.234" "12.234"

justify

should a character vector be left-justified (the default), right-justified, centred or left alone. Can be abbreviated.

format(char, justify = "left")
#> [1] "a   " "ab  " "abc " "abcd" "NA  "
format(char, justify = "right")
#> [1] "   a" "  ab" " abc" "abcd" "  NA"
format(char, justify = "centre")
#> [1] " a  " " ab " "abc " "abcd" " NA "
format(char, justify = "none")
#> [1] "a"    "ab"   "abc"  "abcd" "NA"

na.encode

logical: should NA strings be encoded? Note this only applies to elements of character vectors, not to numerical, complex nor logical NAs, which are always encoded as “NA”.

format(char, na.encode = TRUE)
#> [1] "a   " "ab  " "abc " "abcd" "NA  "
format(char, na.encode = FALSE)
#> [1] "a   " "ab  " "abc " "abcd" NA

nsmall

the minimum number of digits to the right of the decimal point in formatting real/complex numbers in non-scientific formats. Allowed values are 0 <= nsmall <= 20.

format(decimals, nsmall = 1)
#> [1] " 1.000" " 1.200" " 1.230" " 1.234" "12.234"
format(decimals, nsmall = 4)
#> [1] " 1.0000" " 1.2000" " 1.2300" " 1.2340" "12.2340"

scientific

Either a logical specifying whether elements of a real or complex vector should be encoded in scientific format, or an integer penalty (see options(“scipen”)). Missing values correspond to the current default penalty.

format(big, scientific = TRUE)
#> [1] "1e+05" "1e+06" "1e+07" "1e+08" "1e+09"
format(big, scientific = FALSE)
#> [1] "    100000" "   1000000" "  10000000" " 100000000" "1000000000"

small.interval

digits between small.mark; defaults to 5.

format(small, small.interval = 3, small.mark = " ", scientific = FALSE)
#> [1] "0.000 010 000" "0.000 001 000" "0.000 000 100" "0.000 000 010"
#> [5] "0.000 000 001"
format(small, small.interval = 5, small.mark = " ", scientific = FALSE)
#> [1] "0.00001 0000" "0.00000 1000" "0.00000 0100" "0.00000 0010" "0.00000 0001"

small.mark

character; if not empty used as mark between every small.interval decimals after (hence small) the decimal point.

format(small, small.mark = " ", scientific = FALSE)
#> [1] "0.00001 0000" "0.00000 1000" "0.00000 0100" "0.00000 0010" "0.00000 0001"
format(small, small.mark = "", scientific = FALSE)
#> [1] "0.000010000" "0.000001000" "0.000000100" "0.000000010" "0.000000001"

trim

logical; if FALSE, logical, numeric and complex values are right-justified to a common width: if TRUE the leading blanks for justification are suppressed.

format(mixed, trim = FALSE)
#> [1] "  0.0" "  0.1" "  1.0" " 10.0" "100.0"
format(mixed, trim = TRUE)
#> [1] "0.0"   "0.1"   "1.0"   "10.0"  "100.0"

width

By default:

the minimum field width or NULL or 0 for no restriction.

For the AsIs method:

the maximum field width for non-character objects. NULL corresponds to the default 12.

format(char, width = 2)
#> [1] "a   " "ab  " "abc " "abcd" "NA  "
format(char, width = 8)
#> [1] "a       " "ab      " "abc     " "abcd    " "NA      "
format(I(list(small, big)), width = 6)
#> [1] "1e...." "1e...."
format(I(list(small, big)), width = 20)
#> [1] "1e-05, 1e-06, 1e...." "1e+05, 1e+06, 1e...."

zero.print

logical, character string or NULL specifying if and how zeros should be formatted specially. Useful for pretty printing ‘sparse’ objects.

format(mixed, zero.print = TRUE)
#> [1] "  0  " "  0.1" "  1.0" " 10.0" "100.0"
format(mixed, zero.print = FALSE)
#> [1] "     " "  0.1" "  1.0" " 10.0" "100.0"
format(mixed, zero.print = "zero")
#> [1] " zero" "  0.1" "  1.0" " 10.0" "100.0"