cat

 ## Basic usage `cat()` prints output to the console. ```r cat("Miaow!") ``` If you pass it an atomic vector, it prints the each element of the input separated by spaces. For comparison, look at how [`paste()`](https://www.rdocumentation.org/packages/base/topics/paste) behaves with the same input. ```r cat(LETTERS) paste(LETTERS) ``` `cat()` returns `NULL`; it exists purely for the side-effect of writing output, not for creating new variables. ```r x <- cat(1:10) is.null(x) ``` If you pass multiple atomic vectors to `cat()`, the vectors are written one after the other. Again, compare the behavior to [`paste()`](https://www.rdocumentation.org/packages/base/topics/paste). ```r cat(LETTERS, letters) paste(LETTERS, letters) ``` `cat()` can be thought of as a low-level version of [`print()`](https://www.rdocumentation.org/packages/base/topics/print). In the following example, notice how `cat()` and `print()` behave differently with the tab (`\t`) and newline (`\n`) characters. ```r x <- "a b\tc\nd" print(x) cat(x) ``` The names of the input vectors are ignored. ```r cat(setNames(letters, LETTERS)) ``` ## Passing `matrix`, `list`, and other object types If you pass a `matrix` to `cat()`, it will ignore the dimensions and pretend that you passed a vector. ```r cat(matrix(month.abb, 3)) ``` If you pass a `list` to `cat()`, it will throw an error. You may wish to use [`do.call()`](https://www.rdocumentation.org/packages/base/topics/do.call), or change the input type to `cat()` using [`purrr::lift_dl()`](https://www.rdocumentation.org/packages/purrr/topics/lift). ```r tryCatch( cat(list(1, 2, 3)), error = print ) do.call(cat, list(1, 2, 3)) purrr::lift_dl(cat)(list(1, 2, 3)) ``` `cat()` will drop attributes of its inputs. This is particularly tricksy when it comes to `factor`s and `Date`s. Convert them to `character` before calling `cat()`. ```r cat(Sys.Date()) cat(as.character(Sys.Date())) cat(factor(letters)) cat(as.character(factor(letters))) ``` ## `file` argument As well as writing output to the console, `cat()` can write to a file by passing a string to the `file` argument. ```r tmp <- tempfile() cat(1:10, file = tmp) readLines(tmp) ``` `cat()` also supports writing to file [`connection()`](https://www.rdocumentation.org/packages/base/topics/connections)s. ```r tmp <- tempfile() conn <- file(tmp, "w") cat(1:10, file = conn) close(conn) readLines(tmp) ``` ## `sep` argument The spacing between elements of the vectors can be controlled with the `sep` argument. ```r cat(letters, sep = "***") ``` `sep` is vectorized. ```r cat(letters, sep = LETTERS) ``` ## `fill` argument If `fill` is a positive integer then the output is wrapped with a newline (`\n`) after `fill` characters. See [`strwrap()`](https://www.rdocumentation.org/packages/base/topics/strwrap) for comparison. ```r cat(letters, fill = 10) strwrap( paste(letters, collapse = " "), width = 10 ) ``` `fill = TRUE` is a short way of writing `fill = getOption("width")`. See [`options()`](https://www.rdocumentation.org/packages/base/topics/options) for details of the global options, and [`withr::with_option()`](https://www.rdocumentation.org/packages/withr/topics/with-option) for a way to temporarily change global options. ```r withr::with_options( c(width = 20), cat(letters, fill = TRUE) ) ``` ## `append` argument When writing a file, by default `cat()` will overwrite the existing contents of the file. ```r tmp <- tempfile() cat(1:10, file = tmp) cat(11:20, file = tmp) readLines(tmp) # only the 2nd line is present in the file ``` Set `append = TRUE` in all calls to `cat()` after the first to fix this problem. ```r tmp <- tempfile() cat(1:10, file = tmp) cat(11:20, file = tmp, append = TRUE) readLines(tmp) # both lines are present in the file ``` ## Writing `print()` functions [`print()`](https://www.rdocumentation.org/packages/base/topics/print) is a generic function that controls how objects are displayed in the console. Most `print()` methods include calls to `cat()` to create that output. ```r print.Date stats:::print.lm ```