1% File src/library/utils/man/write.table.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2014 R Core Team
4% Distributed under GPL 2 or later
5
6\name{write.table}
7\alias{write.table}
8\alias{write.csv}
9\alias{write.csv2}
10\title{Data Output}
11\description{
12  \code{write.table} prints its required argument \code{x} (after
13  converting it to a data frame if it is not one nor a matrix) to
14  a file or \link{connection}.
15}
16\usage{
17write.table(x, file = "", append = FALSE, quote = TRUE, sep = " ",
18            eol = "\n", na = "NA", dec = ".", row.names = TRUE,
19            col.names = TRUE, qmethod = c("escape", "double"),
20            fileEncoding = "")
21
22write.csv(\dots)
23write.csv2(\dots)
24}
25\arguments{
26  \item{x}{the object to be written, preferably a matrix or data frame.
27    If not, it is attempted to coerce \code{x} to a data frame.}
28  \item{file}{either a character string naming a file or a \link{connection}
29    open for writing.  \code{""} indicates output to the console.}
30  \item{append}{logical. Only relevant if \code{file} is a character
31    string.  If \code{TRUE}, the output is appended to the
32    file.  If \code{FALSE}, any existing file of the name is destroyed.}
33  \item{quote}{a logical value (\code{TRUE} or \code{FALSE}) or a
34    numeric vector.  If \code{TRUE}, any character or factor columns
35    will be surrounded by double quotes.  If a numeric vector, its
36    elements are taken as the indices of columns to quote.  In both
37    cases, row and column names are quoted if they are written.  If
38    \code{FALSE}, nothing is quoted.}
39  \item{sep}{the field separator string.  Values within each row of
40    \code{x} are separated by this string.}
41  \item{eol}{the character(s) to print at the end of each line (row).
42    For example, \code{eol = "\r\n"} will produce Windows' line endings on
43    a Unix-alike OS, and \code{eol = "\r"} will produce files as expected by
44    Excel:mac 2004.}
45  \item{na}{the string to use for missing values in the data.}
46  \item{dec}{the string to use for decimal points in numeric or complex
47    columns: must be a single character.}
48  \item{row.names}{either a logical value indicating whether the row
49    names of \code{x} are to be written along with \code{x}, or a
50    character vector of row names to be written.}
51  \item{col.names}{either a logical value indicating whether the column
52    names of \code{x} are to be written along with \code{x}, or a
53    character vector of column names to be written.  See the section on
54    \sQuote{CSV files} for the meaning of \code{col.names = NA}.}
55  \item{qmethod}{a character string specifying how to deal with embedded
56    double quote characters when quoting strings.  Must be one of
57    \code{"escape"} (default for \code{write.table}), in which case the
58    quote character is escaped in C style by a backslash, or
59    \code{"double"} (default for \code{write.csv} and
60    \code{write.csv2}), in which case it is doubled.  You can specify
61    just the initial letter.}
62  \item{fileEncoding}{character string: if non-empty declares the
63    encoding to be used on a file (not a connection) so the character data can
64    be re-encoded as they are written.  See \code{\link{file}}.}
65
66  \item{\dots}{arguments to \code{write.table}: \code{append},
67    \code{col.names}, \code{sep}, \code{dec} and \code{qmethod}
68    cannot be altered.
69  }
70}
71\details{
72  If the table has no columns the rownames will be written only if
73  \code{row.names = TRUE}, and \emph{vice versa}.
74
75  Real and complex numbers are written to the maximal possible precision.
76
77  If a data frame has matrix-like columns these will be converted to
78  multiple columns in the result (\emph{via} \code{\link{as.matrix}})
79  and so a character \code{col.names} or a numeric \code{quote} should
80  refer to the columns in the result, not the input.  Such matrix-like
81  columns are unquoted by default.
82
83  Any columns in a data frame which are lists or have a class
84  (e.g., dates) will be converted by the appropriate \code{as.character}
85  method: such columns are unquoted by default.  On the other hand,
86  any class information for a matrix is discarded and non-atomic
87  (e.g., list) matrices are coerced to character.
88
89  Only columns which have been converted to character will be quoted if
90  specified by \code{quote}.
91
92  The \code{dec} argument only applies to columns that are not subject
93  to conversion to character because they have a class or are part of a
94  matrix-like column (or matrix), in particular to columns protected by
95  \code{\link{I}()}.  Use \code{\link{options}("OutDec")} to control
96  such conversions.
97
98  In almost all cases the conversion of numeric quantities is governed
99  by the option \code{"scipen"} (see \code{\link{options}}), but with
100  the internal equivalent of \code{digits = 15}.  For finer control, use
101  \code{\link{format}} to make a character matrix/data frame, and call
102  \code{write.table} on that.
103
104  These functions check for a user interrupt every 1000 lines of output.
105
106  If \code{file} is a non-open connection, an attempt is made to open it
107  and then close it after use.
108
109  To write a Unix-style file on Windows, use a binary connection
110  e.g.\sspace{}\code{file = file("filename", "wb")}.
111}
112\section{CSV files}{
113  By default there is no column name for a column of row names.  If
114  \code{col.names = NA} and \code{row.names = TRUE} a blank column name
115  is added, which is the convention used for CSV files to be read by
116  spreadsheets.  Note that such CSV files can be read in \R by
117\preformatted{  read.csv(file = "<filename>", row.names = 1)}
118
119  \code{write.csv} and \code{write.csv2} provide convenience wrappers
120  for writing CSV files.  They set \code{sep} and \code{dec} (see
121  below), \code{qmethod = "double"}, and \code{col.names} to \code{NA}
122  if \code{row.names = TRUE} (the default) and to \code{TRUE} otherwise.
123
124  \code{write.csv} uses \code{"."} for the decimal point and a comma for
125  the separator.
126
127  \code{write.csv2} uses a comma for the decimal point and a semicolon for
128  the separator, the Excel convention for CSV files in some Western
129  European locales.
130
131  These wrappers are deliberately inflexible: they are designed to
132  ensure that the correct conventions are used to write a valid file.
133  Attempts to change \code{append}, \code{col.names}, \code{sep},
134  \code{dec} or \code{qmethod} are ignored, with a warning.
135
136  CSV files do not record an encoding, and this causes problems if they
137  are not ASCII for many other applications.  Windows Excel 2007/10 will
138  open files (e.g., by the file association mechanism) correctly if they
139  are ASCII or UTF-16 (use \code{fileEncoding = "UTF-16LE"}) or perhaps
140  in the current Windows codepage (e.g., \code{"CP1252"}), but the
141  \sQuote{Text Import Wizard} (from the \sQuote{Data} tab) allows far
142  more choice of encodings.  Excel:mac 2004/8 can \emph{import} only
143  \sQuote{Macintosh} (which seems to mean Mac Roman), \sQuote{Windows}
144  (perhaps Latin-1) and \sQuote{PC-8} files.  OpenOffice 3.x asks for
145  the character set when opening the file.
146
147  There is an IETF RFC4180 (\url{https://tools.ietf.org/html/rfc4180})
148  for CSV files, which mandates comma as the separator and CRLF line
149  endings.  \code{write.csv} writes compliant files on Windows: use
150  \code{eol = "\r\n"} on other platforms.
151}
152\note{
153  \code{write.table} can be slow for data frames with large numbers
154  (hundreds or more) of columns: this is inevitable as each column could
155  be of a different class and so must be handled separately.  If they
156  are all of the same class, consider using a matrix instead.
157}
158
159\seealso{
160  The \sQuote{R Data Import/Export} manual.
161
162  \code{\link{read.table}}, \code{\link{write}}.
163
164  \code{\link[MASS]{write.matrix}} in package \CRANpkg{MASS}.
165}
166
167\examples{
168\dontrun{
169## To write a CSV file for input to Excel one might use
170x <- data.frame(a = I("a \" quote"), b = pi)
171write.table(x, file = "foo.csv", sep = ",", col.names = NA,
172            qmethod = "double")
173## and to read this file back into R one needs
174read.table("foo.csv", header = TRUE, sep = ",", row.names = 1)
175## NB: you do need to specify a separator if qmethod = "double".
176
177### Alternatively
178write.csv(x, file = "foo.csv")
179read.csv("foo.csv", row.names = 1)
180## or without row names
181write.csv(x, file = "foo.csv", row.names = FALSE)
182read.csv("foo.csv")
183
184## To write a file in Mac Roman for simple use in Mac Excel 2004/8
185write.csv(x, file = "foo.csv", fileEncoding = "macroman")
186## or for Windows Excel 2007/10
187write.csv(x, file = "foo.csv", fileEncoding = "UTF-16LE")
188}}
189\keyword{print}
190\keyword{file}
191