---
title: "Formatting Options"
author: "Duncan Murdoch"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Formatting Options}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

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 formatting, 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:
```{r}
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.


```{r}
format(big, big.interval = 3, big.mark = " ", scientific = FALSE)
format(big, big.interval = 4, big.mark = " ", scientific = FALSE)
```

## `big.mark`

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

```{r}
format(big, big.mark = ",", scientific = FALSE)
format(big, big.mark = " ", scientific = FALSE)
```

## `decimal.mark`

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

```{r}
format(decimals, decimal.mark = ".")
format(decimals, decimal.mark = ",")
```

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

```{r}
format(decimals, digits = 2)
format(decimals, digits = 3)
```

## `drop0trailing`

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

```{r}
format(decimals, drop0trailing = FALSE)
format(decimals, drop0trailing = TRUE)
```

## `justify`

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

```{r}
format(char, justify = "left")
format(char, justify = "right")
format(char, justify = "centre")
format(char, justify = "none")
```

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

```{r}
format(char, na.encode = TRUE)
format(char, na.encode = FALSE)
```

## `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.

```{r}
format(decimals, nsmall = 1)
format(decimals, nsmall = 4)
```

## `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.

```{r}
format(big, scientific = TRUE)
format(big, scientific = FALSE)
```

## `small.interval`

> digits between `small.mark`; defaults to 5.

```{r}
format(small, small.interval = 3, small.mark = " ", scientific = FALSE)
format(small, small.interval = 5, small.mark = " ", scientific = FALSE)
```

## `small.mark`

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

```{r}
format(small, small.mark = " ", scientific = FALSE)
format(small, small.mark = "", scientific = FALSE)
```

## `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.

```{r}
format(mixed, trim = FALSE)
format(mixed, trim = TRUE)
```

## `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.

```{r}
format(char, width = 2)
format(char, width = 8)
format(I(list(small, big)), width = 6)
format(I(list(small, big)), width = 20)
```

## `zero.print`

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

```{r}
format(mixed, zero.print = TRUE)
format(mixed, zero.print = FALSE)
format(mixed, zero.print = "zero")
```