1% Generated by roxygen2: do not edit by hand 2% Please edit documentation in R/write.R 3\name{format_delim} 4\alias{format_delim} 5\alias{format_csv} 6\alias{format_csv2} 7\alias{format_tsv} 8\title{Convert a data frame to a delimited string} 9\usage{ 10format_delim( 11 x, 12 delim, 13 na = "NA", 14 append = FALSE, 15 col_names = !append, 16 quote = c("needed", "all", "none"), 17 escape = c("double", "backslash", "none"), 18 eol = "\\n", 19 quote_escape = deprecated() 20) 21 22format_csv( 23 x, 24 na = "NA", 25 append = FALSE, 26 col_names = !append, 27 quote = c("needed", "all", "none"), 28 escape = c("double", "backslash", "none"), 29 eol = "\\n", 30 quote_escape = deprecated() 31) 32 33format_csv2( 34 x, 35 na = "NA", 36 append = FALSE, 37 col_names = !append, 38 quote = c("needed", "all", "none"), 39 escape = c("double", "backslash", "none"), 40 eol = "\\n", 41 quote_escape = deprecated() 42) 43 44format_tsv( 45 x, 46 na = "NA", 47 append = FALSE, 48 col_names = !append, 49 quote = c("needed", "all", "none"), 50 escape = c("double", "backslash", "none"), 51 eol = "\\n", 52 quote_escape = deprecated() 53) 54} 55\arguments{ 56\item{x}{A data frame.} 57 58\item{delim}{Delimiter used to separate values. Defaults to \code{" "} for \code{write_delim()}, \code{","} for \code{write_excel_csv()} and 59\code{";"} for \code{write_excel_csv2()}. Must be a single character.} 60 61\item{na}{String used for missing values. Defaults to NA. Missing values 62will never be quoted; strings with the same value as \code{na} will 63always be quoted.} 64 65\item{append}{If \code{FALSE}, will overwrite existing file. If \code{TRUE}, 66will append to existing file. In both cases, if the file does not exist a new 67file is created.} 68 69\item{col_names}{If \code{FALSE}, column names will not be included at the top of the file. If \code{TRUE}, 70column names will be included. If not specified, \code{col_names} will take the opposite value given to \code{append}.} 71 72\item{quote}{How to handle fields which contain characters that need to be quoted. 73\itemize{ 74\item \code{needed} - Only quote fields which need them. 75\item \code{all} - Quote all fields. 76\item \code{none} - Never quote fields. 77}} 78 79\item{escape}{The type of escape to use when quotes are in the data. 80\itemize{ 81\item \code{double} - quotes are escaped by doubling them. 82\item \code{backslash} - quotes are escaped by a preceding backslash. 83\item \code{none} - quotes are not escaped. 84}} 85 86\item{eol}{The end of line character to use. Most commonly either \code{"\\n"} for 87Unix style newlines, or \code{"\\r\\n"} for Windows style newlines.} 88 89\item{quote_escape}{\Sexpr[results=rd, stage=render]{lifecycle::badge("deprecated")}, use the \code{escape} argument instead.} 90} 91\value{ 92A string. 93} 94\description{ 95These functions are equivalent to \code{\link[=write_csv]{write_csv()}} etc., but instead 96of writing to disk, they return a string. 97} 98\section{Output}{ 99 100Factors are coerced to character. Doubles are formatted to a decimal string 101using the grisu3 algorithm. \code{POSIXct} values are formatted as ISO8601 with a 102UTC timezone \emph{Note: \code{POSIXct} objects in local or non-UTC timezones will be 103converted to UTC time before writing.} 104 105All columns are encoded as UTF-8. \code{write_excel_csv()} and \code{write_excel_csv2()} also include a 106\href{https://en.wikipedia.org/wiki/Byte_order_mark}{UTF-8 Byte order mark} 107which indicates to Excel the csv is UTF-8 encoded. 108 109\code{write_excel_csv2()} and \code{write_csv2} were created to allow users with 110different locale settings to save .csv files using their default settings 111(e.g. \verb{;} as the column separator and \verb{,} as the decimal separator). 112This is common in some European countries. 113 114Values are only quoted if they contain a comma, quote or newline. 115 116The \verb{write_*()} functions will automatically compress outputs if an appropriate extension is given. 117Three extensions are currently supported: \code{.gz} for gzip compression, \code{.bz2} for bzip2 compression and 118\code{.xz} for lzma compression. See the examples for more information. 119} 120 121\examples{ 122# format_()* functions are useful for testing and reprexes 123cat(format_csv(mtcars)) 124cat(format_tsv(mtcars)) 125cat(format_delim(mtcars, ";")) 126 127# Specifying missing values 128df <- data.frame(x = c(1, NA, 3)) 129format_csv(df, na = "missing") 130 131# Quotes are automatically added as needed 132df <- data.frame(x = c("a ", '"', ",", "\n")) 133cat(format_csv(df)) 134} 135\references{ 136Florian Loitsch, Printing Floating-Point Numbers Quickly and 137Accurately with Integers, PLDI '10, 138\url{http://www.cs.tufts.edu/~nr/cs257/archive/florian-loitsch/printf.pdf} 139} 140