.BG
.FN scan
.TL
Input Data from a File
.CS
scan(file="", what=numeric(), n, sep,
     multi.line = F, flush = F, append = F)
.AG file
character string naming the file containing the data.
If the string is empty (`""'),
data will be read from standard input,
`scan' will prompt with the index for the next data item,
and data input can be terminated by a blank line.
Otherwise, the end of input must be signalled by an end-of-file.
.AG what
a pattern for the data to be read, in the form of an S object.
If `what' is a numeric, character, or complex vector,
`scan' will interpret all fields on the
file as data of the same mode as that object. So, `what=character()'
causes `scan' to read data as character fields.
.PP
It is possible to read simultaneously data of more than one mode.
For example, if fields were alternately numeric and character (e.g., two
columns of data on the file),
.Cs
scan(myfile,list(0,""))
.Ce
would read them and return an object of mode list, with a numeric vector
and a character vector as its two elements.
The elements of `what' can be anything, so long as you have numbers
where you want numeric fields, character data where you want character
fields and complex numbers where you want complex fields.
An element `NULL' in `what' causes the corresponding field to be skipped
during input.
The elements are used only to decide the kind of field, unless `append'
is `TRUE' (see below).
Notice that `scan' retains the names attribute, if any, of the list,
so that
.Cs
z <- scan(myfile,list(pop=0,city=""))
.Ce
would let you refer to `z$pop' and `z$city'.
.AG n
maximum number of items to read from the file.
If omitted, the function reads to the end of file (or to an empty
line, if reading from standard input).
.AG sep
optional separator (single character).  If omitted, any amount of white
space (blanks or tabs) can separate fields.
The main use for separators is to allow white space inside character fields.
For example, suppose in the above the numeric field was to be followed
by a tab with text filling out the rest of the line.
.Cs
z <- scan(myfile,list(pop=0,city=""),sep="\\t")
.Ce
would allow blanks in the text.  (The alternative would be to quote the
text and omit the separator.)
.AG multi.line
if `FALSE', all the fields must appear on one line: if `scan' reaches the
end of the line without reading all the fields, an error occurs.
This is useful for checking that no fields have been omitted.
If this argument is `TRUE', reading will continue disregarding where
new lines occur.
.AG flush
if `TRUE', `scan' will flush to the end of the line after reading the
last of the fields requested.
This allows putting comments after the last field that are not read by `scan',
but also prevents putting multiple sets of items on one line.
.AG append
if `TRUE', the returned object will include all the elements in the
`what' argument, with the input data for the respective fields appended
to each component.
If `FALSE' (the default), the data in `what' is ignored, and only the
modes matter.
.RT
as described above, an object like that presented in the `what' argument.
.PP
Any numeric field containing the characters `NA' will be returned
as a missing value.
If field separator (`sep=' argument) is given and the field is empty,
the returned value will be an `NA' for a numeric field or a "" for
a character field.
.PP
Any field that cannot be interpreted according to the mode(s) supplied to
`scan' will cause an error.
The reading of numeric data in `scan' is done by means of C scan formats,
rather than by the rules of the S parser (the function `parse').
This should not cause any serious inconsistencies between the two functions,
but there is no guarantee that the same input read both ways would
produce numeric results that are exactly equal.
.PP
Reading  of large amounts of data is more efficiently done by `scan'
than by `parse', which on the other hand does not need
to know in advance what type of data to expect in each field.
.SA
`parse'.
.EX
scan() # read numeric values from standard input
# read a label & two numeric fields, make a matrix
z \(<- scan("myfile",list(n="",0,0))
mat \(<- cbind(z[[2]],z[[3]])
dimnames(mat)  \(<- list(z$n,c("X","Y"))
.KW file
.WR
