formatC

# `formatC()` `formatC()` is based upon the C/C++ function `printf()`. The [documentation](http://www.cplusplus.com/reference/cstdio/printf) for that function contains details on how many of the arguments to `formatC()` work. ## Basic usage `formatC()` takes a numeric vector as an input and returns a character vector. With no arguments other than `x`, `formatC()` works like [`signif()`](https://www.rdocumentation.org/packages/base/topics/signif) + [`as.character()`](https://www.rdocumentation.org/packages/base/topics/character), (though with different rules for rounding). ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x) as.character(signif(x, 4)) ``` ## `digits` and `format` arguments These arguments affect each other, and need to be discussed together. `format` determines whether the numbers should be displayed using fixed, scientific, or integer-like formatting. `digits` determines either the number of _significant digits_ or the number of _decimal paces_ to round the numbers to, depending upon the value of `format`. Note that the documentation is apparently wrong (as of v3.3.2) – the default value of `digits` is always 4, even for `integer` inputs. `format = "d"` treats the numbers as integers, so nothing after the decimal place is shown. Conversion to integer using [`as.integer()`](https://www.rdocumentation.org/packages/base/topics/integer) is shown for comparison. ```{r} (x <- c(1.2345, 6.789) * 10 ^ (-2:3) * c(1, -1, 1)) formatC(x, format = "d") as.character(as.integer(x)) ``` `format = "e"` uses scientific formatting. In this case, `digits` refers to the number of significant digits to round each number to. See [`signif()`](https://www.rdocumentation.org/packages/base/topics/signif) for comparison. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, format = "e", digits = 1) formatC(x, format = "e", digits = 2) formatC(x, format = "e", digits = 3) formatC(x, format = "e") # implicitly digits = 4 formatC(x, format = "e", digits = 5) ``` `format = "E"` is a variant of `format = "e"` that prints an upper-case `"E"` to denote the start of the exponent. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, format = "E") ``` `format = "f"` uses fixed formatting. In this case, `digits` refers to the number of decimal places to round each number to. See [`round()`](https://www.rdocumentation.org/packages/base/topics/round) for comparison. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, format = "f", digits = 1) formatC(x, format = "f", digits = 2) formatC(x, format = "f", digits = 3) formatC(x, format = "f") # implicitly digits = 4 formatC(x, format = "f", digits = 5) ``` `format = "g"` automatically mixes fixed or scientific, trying to choose whichever takes the least amount of space. `digits` refers to significant digits. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, format = "g", digits = 1) formatC(x, format = "g", digits = 2) formatC(x, format = "g", digits = 3) formatC(x, format = "g") # implicitly digits = 4 formatC(x, format = "g", digits = 5) ``` `format = "G"` is a variant of `format = "g"` that prints an upper-case `"E"` to denote the start of the exponent in scientifically formatted values. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, format = "G") ``` `format = "fg"` works like `format = "g"`, except that `digits` refers to decimal places. In this case, trailing zeroes are dropped. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, format = "fg", digits = 1) formatC(x, format = "fg", digits = 2) formatC(x, format = "fg", digits = 3) formatC(x, format = "fg") # implicitly digits = 4 formatC(x, format = "fg", digits = 5) ``` Negative values of `digits` are treated as `digits = 6`. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, format = "e", digits = -1) formatC(x, format = "f", digits = -1) ``` The largest allowed value of `digits` is `324` when `format = "f"`, and 50 otherwise. Note that under most circumstances, you won't be better than 15 significant figures of accuracy, so the rest will be gibberish. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, format = "f", digits = 325) formatC(x, format = "e", digits = 51) ``` `format = "s"` is a little different. It is designed to be used with an input that is already contains strings (rather than numbers). It's main purpose is to be used with the `width` argument (see below) to pad strings to a specified number of characters. ## `width` argument `width` specifies the minimum number of characters of each element of the result. If the number is too short, it is padded on the left with spaces. This is mostly useful for getting columns of numbers to line up. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, format = "f", width = 6) formatC(x, format = "f", width = 7) formatC(x, format = "f", width = 8) formatC(x, format = "f", width = 9) ``` You can specify a negative width to pad on the right instead. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, format = "f", width = -6) formatC(x, format = "f", width = -7) formatC(x, format = "f", width = -8) formatC(x, format = "f", width = -9) ``` `width = 0` is interpreted as `width = digits`, in which case you should never have padding. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, format = "f", digits = 8, width = 0) formatC(x, format = "f", digits = 8, width = 8) ``` ## `flag` argument There are five modifying flags available: `+`, `` ``, `-`, `0`, and `#`. `flag` takes a sting containing zero or more of these flags in any order. `flag = "+"` means that positive numbers are prefixed with a plus sign. ```{r} (x <- c(1, -1, 1) * 1.2345 * 10 ^ (-4:4)) formatC(x, flag = "+") ``` `flag = "+"` means that positive numbers are prefixed with a space. When `flag = "+ "`, the plus sign takes priority. ```{r} (x <- c(1, -1, 1) * 1.2345 * 10 ^ (-4:4)) formatC(x, flag = " ") # space flag ignored formatC(x, flag = "+ ") formatC(x, flag = " +") ``` `flag = "-"` means pad short strings on the right, exactly like using a negative `width`. Using `flag = "-"` and a negative `width` _doesn't_ double reverse the padding; it still pads on the right. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, width = 10, flag = "-") formatC(x, width = -10, flag = "-") ``` `flag = "0"` means pad short strings with zeroes, not spaces. It cannot be used in combination with `flag = "-"` to pad with zeroes on the right. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, width = 10, flag = "0") formatC(x, width = 10, flag = "-0") # zero flag ignored ``` `flag = "#"` prints a trailing decimal point in the case where `digits = 0`. ```{r} (x <- 1.2345 * 10 ^ (-4:4)) formatC(x, digits = 0, format = "e") formatC(x, digits = 0, format = "e", flag = "#") formatC(x, digits = 0, format = "f") formatC(x, digits = 0, format = "f", flag = "#") formatC(x, digits = 0, format = "g") formatC(x, digits = 0, format = "g", flag = "#") ``` ## `big.mark` and `big.interval` arguments When the format is a fixed type (`format %in% c("d", "f", "fg")`), `big.mark` and `big.interval` control separators of digits before the decimal point. For example, in the USA, monetary quantities are often separated the a comma after every 3 digits. In France, monetary quantities are separated by a space every three digits. See [`Sys.localeconv()`](https://www.rdocumentation.org/packages/base/topics/Sys.localeconv) and the C++ documentation for [`lconv` structures](http://www.cplusplus.com/reference/clocale/lconv) describe the correct formatting for numbers in a given locale. In particular, note the `thousands_sep`, `grouping`, `mon_thousands_sep`, and `mon_grouping` elements. ```{r} (x <- 1.2345 * 10 ^ (1:10)) formatC(x, format = "d", big.mark = ",", big.interval = 3) formatC(x, format = "d", big.mark = " ", big.interval = 3) ``` ## `small.mark`, `small.interval`, and `decimal.mark` arguments These work in in a similar way to `big.mark` and `big.interval`, but they control the decimal place, and what happens afterwards. Use of these arguments only makes sense when `format %in% c("f", "fg")`. ```{r} (x <- 1.2345 * 10 ^ (0:-10)) formatC(x, format = "fg", decimal.mark = ".", small.mark = ",", small.interval = 3) formatC(x, format = "fg", decimal.mark = ",", small.mark = " ", small.interval = 3) ```