\HeaderA{read.fwf}{Read Fixed Width Format Files}{read.fwf}
\keyword{file}{read.fwf}
\keyword{connection}{read.fwf}
\begin{Description}\relax
Read a table of \bold{f}ixed \bold{w}idth \bold{f}ormatted
data into a \code{\LinkA{data.frame}{data.frame}}.
\end{Description}
\begin{Usage}
\begin{verbatim}
read.fwf(file, widths, header = FALSE, sep = "\t", as.is = FALSE,
         skip = 0, row.names, col.names, n = -1,
         buffersize = 2000, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{file}] the name of the file which the data are to be read from.

Alternatively, \code{file} can be a \code{\LinkA{connection}{connection}}, which
will be opened if necessary, and if so closed at the end of the
function call.

\item[\code{widths}] integer vector, giving the widths of the fixed-width
fields (of one line), or list of integer vectors giving widths for
multiline records.
\item[\code{header}] a logical value indicating whether the file contains the
names of the variables as its first line.  If present, the names
must be delimited by \code{sep}.
\item[\code{sep}] character; the separator used internally; should be a
character that does not occur in the file (except in the header).
\item[\code{as.is}] see \code{\LinkA{read.table}{read.table}}.
\item[\code{skip}] number of initial lines to skip; see
\code{\LinkA{read.table}{read.table}}.
\item[\code{row.names}] see \code{\LinkA{read.table}{read.table}}.
\item[\code{col.names}] see \code{\LinkA{read.table}{read.table}}.
\item[\code{n}] the maximum number of records (lines) to be read, defaulting
to no limit.
\item[\code{buffersize}] Maximum number of lines to read at one time
\item[\code{...}] further arguments to be passed to
\code{\LinkA{read.table}{read.table}}.  Useful further arguments include
\code{na.strings}, \code{colClasses} and \code{strip.white}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Multiline records are concatenated to a single line before processing.
Fields that are of zero-width or are wholly beyond the end of the line
in \code{file} are replaced by \code{NA}.

Negative-width fields are used to indicate columns to be skipped, eg
\code{-5} to skip 5 columns.  These fields are not seen by
\code{read.table} and so should not be included in a \code{col.names}
or \code{colClasses} argument (nor in the header line, if present).

Reducing the \code{buffersize} argument may reduce memory use when
reading large files with long lines.  Increasing \code{buffersize} may
result in faster processing when enough memory is available.
\end{Details}
\begin{Value}
A \code{\LinkA{data.frame}{data.frame}} as produced by \code{\LinkA{read.table}{read.table}}
which is called internally.
\end{Value}
\begin{Author}\relax
Brian Ripley for \R{} version: original \code{Perl} by Kurt Hornik.
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{scan}{scan}} and \code{\LinkA{read.table}{read.table}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
ff <- tempfile()
cat(file=ff, "123456", "987654", sep="\n")
read.fwf(ff, widths=c(1,2,3))    #> 1 23 456 \ 9 87 654
read.fwf(ff, widths=c(1,-2,3))   #> 1 456 \ 9 654
unlink(ff)
cat(file=ff, "123", "987654", sep="\n")
read.fwf(ff, widths=c(1,0, 2,3))    #> 1 NA 23 NA \ 9 NA 87 654
unlink(ff)
cat(file=ff, "123456", "987654", sep="\n")
read.fwf(ff, widths=list(c(1,0, 2,3), c(2,2,2))) #> 1 NA 23 456 98 76 54
unlink(ff)
\end{ExampleCode}
\end{Examples}

