Convert a data frame to a delimited string

These functions are equivalent to write_csv() etc., but instead of writing to disk, they return a string.

format_delim(
  x,
  delim,
  na = "NA",
  append = FALSE,
  col_names = !append,
  quote_escape = "double",
  eol = "\n"
)

format_csv(
  x,
  na = "NA",
  append = FALSE,
  col_names = !append,
  quote_escape = "double",
  eol = "\n"
)

format_csv2(
  x,
  na = "NA",
  append = FALSE,
  col_names = !append,
  quote_escape = "double",
  eol = "\n"
)

format_tsv(
  x,
  na = "NA",
  append = FALSE,
  col_names = !append,
  quote_escape = "double",
  eol = "\n"
)

Arguments

x	A data frame.
delim	Delimiter used to separate values. Defaults to " " for write_delim(), "," for write_excel_csv() and ";" for write_excel_csv2(). Must be a single character.
na	String used for missing values. Defaults to NA. Missing values will never be quoted; strings with the same value as na will always be quoted.
append	If FALSE, will overwrite existing file. If TRUE, will append to existing file. In both cases, if the file does not exist a new file is created.
col_names	If FALSE, column names will not be included at the top of the file. If TRUE, column names will be included. If not specified, col_names will take the opposite value given to append.
quote_escape	The type of escaping to use for quoted values, one of "double", "backslash" or "none". You can also use FALSE, which is equivalent to "none". The default is "double", which is expected format for Excel.
eol	The end of line character to use. Most commonly either "\n" for Unix style newlines, or "\r\n" for Windows style newlines.

Value

A string.

Output

Factors are coerced to character. Doubles are formatted to a decimal string using the grisu3 algorithm. POSIXct values are formatted as ISO8601 with a UTC timezone Note: POSIXct objects in local or non-UTC timezones will be converted to UTC time before writing.

All columns are encoded as UTF-8. write_excel_csv() and write_excel_csv2() also include a UTF-8 Byte order mark which indicates to Excel the csv is UTF-8 encoded.

write_excel_csv2() and write_csv2 were created to allow users with different locale settings to save .csv files using their default settings (e.g. ; as the column separator and , as the decimal separator). This is common in some European countries.

Values are only quoted if they contain a comma, quote or newline.

The write_*() functions will automatically compress outputs if an appropriate extension is given. Three extensions are currently supported: .gz for gzip compression, .bz2 for bzip2 compression and .xz for lzma compression. See the examples for more information.

References

Florian Loitsch, Printing Floating-Point Numbers Quickly and Accurately with Integers, PLDI '10, http://www.cs.tufts.edu/~nr/cs257/archive/florian-loitsch/printf.pdf

Examples

data(band_members, package = "dplyr")
# format_()* functions are useful for testing and reprexes
cat(format_csv(band_members))
#> name,band
#> Mick,Stones
#> John,Beatles
#> Paul,Beatles
cat(format_tsv(band_members))
#> name	band
#> Mick	Stones
#> John	Beatles
#> Paul	Beatles
cat(format_delim(band_members, ";"))
#> name;band
#> Mick;Stones
#> John;Beatles
#> Paul;Beatles

# Specifying missing values
df <- data.frame(x = c(1, NA, 3))
format_csv(df, na = "missing")
#> [1] "x\n1\nmissing\n3\n"

# Quotes are automatically added as needed
df <- data.frame(x = c("a ", '"', ",", "\n"))
cat(format_csv(df))
#> x
#> a 
#> """"
#> ","
#> "
#> "