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