1% File src/library/utils/man/read.fwf.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{read.fwf}
7\alias{read.fwf}
8\title{Read Fixed Width Format Files}
9\description{
10  Read a table of \bold{f}ixed \bold{w}idth \bold{f}ormatted
11  data into a \code{\link{data.frame}}.
12}
13\usage{
14read.fwf(file, widths, header = FALSE, sep = "\t",
15         skip = 0, row.names, col.names, n = -1,
16         buffersize = 2000, fileEncoding = "", \dots)
17}
18\arguments{
19  \item{file}{
20    the name of the file which the data are to be read from.
21
22    Alternatively, \code{file} can be a \link{connection}, which
23    will be opened if necessary, and if so closed at the end of the
24    function call.
25  }
26  \item{widths}{integer vector, giving the widths of the fixed-width
27    fields (of one line), or list of integer vectors giving widths for
28    multiline records.}
29  \item{header}{a logical value indicating whether the file contains the
30    names of the variables as its first line.  If present, the names
31    must be delimited by \code{sep}.}
32  \item{sep}{character; the separator used internally; should be a
33    character that does not occur in the file (except in the header).}
34  \item{skip}{number of initial lines to skip; see
35    \code{\link{read.table}}.}
36  \item{row.names}{see \code{\link{read.table}}.}
37  \item{col.names}{see \code{\link{read.table}}.}
38  \item{n}{the maximum number of records (lines) to be read, defaulting
39    to no limit.}
40  \item{buffersize}{Maximum number of lines to read at one time}
41
42  \item{fileEncoding}{character string: if non-empty declares the
43    encoding used on a file (not a connection) so the character data can
44    be re-encoded.  See the \sQuote{Encoding} section of the help for
45    \code{\link{file}}, the \sQuote{R Data Import/Export} manual and
46    \sQuote{Note}.}
47
48  \item{\dots}{further arguments to be passed to
49    \code{\link{read.table}}.  Useful such arguments include
50    \code{as.is}, \code{na.strings}, \code{colClasses} and \code{strip.white}.}
51}
52% PR#8083 mentions strip.white
53\value{
54  A \code{\link{data.frame}} as produced by \code{\link{read.table}}
55  which is called internally.
56}
57\details{
58  Multiline records are concatenated to a single line before processing.
59  Fields that are of zero-width or are wholly beyond the end of the line
60  in \code{file} are replaced by \code{NA}.
61
62  Negative-width fields are used to indicate columns to be skipped, e.g.,
63  \code{-5} to skip 5 columns.  These fields are not seen by
64  \code{read.table} and so should not be included in a \code{col.names}
65  or \code{colClasses} argument (nor in the header line, if present).
66
67  Reducing the \code{buffersize} argument may reduce memory use when
68  reading large files with long lines.  Increasing \code{buffersize} may
69  result in faster processing when enough memory is available.
70
71  Note that \code{read.fwf} (not \code{read.table}) reads the supplied
72  file, so the latter's argument \code{encoding} will not be useful.
73}
74\author{
75  Brian Ripley for \R version: originally in \code{Perl} by Kurt Hornik.
76}
77\seealso{
78  \code{\link{scan}} and \code{\link{read.table}}.
79
80  \code{\link{read.fortran}} for another style of fixed-format files.
81}
82\examples{
83ff <- tempfile()
84cat(file = ff, "123456", "987654", sep = "\n")
85read.fwf(ff, widths = c(1,2,3))    #> 1 23 456 \\ 9 87 654
86read.fwf(ff, widths = c(1,-2,3))   #> 1 456 \\ 9 654
87unlink(ff)
88cat(file = ff, "123", "987654", sep = "\n")
89read.fwf(ff, widths = c(1,0, 2,3))    #> 1 NA 23 NA \\ 9 NA 87 654
90unlink(ff)
91cat(file = ff, "123456", "987654", sep = "\n")
92read.fwf(ff, widths = list(c(1,0, 2,3), c(2,2,2))) #> 1 NA 23 456 98 76 54
93unlink(ff)
94}
95\keyword{file}
96\keyword{connection}
97