| scan {base} | R Documentation |
Read data into a vector or list from the console or file.
scan(file = "", what = double(0), nmax = -1, n = -1, sep = "",
quote = if(identical(sep, "\n")) "" else "'\"", dec = ".",
skip = 0, nlines = 0, na.strings = "NA",
flush = FALSE, fill = FALSE, strip.white = FALSE,
quiet = FALSE, blank.lines.skip = TRUE, multi.line = TRUE,
comment.char = "", allowEscapes = FALSE)
file |
the name of a file to read data values from. If the
specified file is "", then input is taken from the keyboard
(or stdin if input is redirected).
(In this case input can be terminated by a blank line or an EOF
signal, Ctrl-D on Unix and Ctrl-Z on Windows.)
Otherwise, the file name is interpreted relative to the current working directory (given by getwd()),
unless it specifies an absolute path.
Tilde-expansion is performed where supported.
Alternatively, file can be a connection,
which will be opened if necessary, and if so closed at the end of
the function call. Whatever mode the connection is opened in,
any of LF, CRLF or CR will be accepted as the EOL marker for a line
and so will match sep = "\n".
file can also be a complete URL.
To read a data file not in the current encoding (for example a Latin-1 file in a UTF-8 locale or conversely) use a file connection setting the encoding argument.
|
what |
the type of what gives the type of data to be read.
The supported types are logical, integer, numeric,
complex, character, raw and list.
If what is a list, it is assumed that the lines of the data file
are records each containing length(what) items
(“fields”) and the list components should have elements which
are one of the first six types listed or NULL, see section
‘Details’ below. |
nmax |
the maximum number of data values to be read, or if
what is a list, the maximum number of records to be read. If
omitted or not positive (and nlines is not set to a
positive value), scan will read to the end of file. |
n |
the maximum number of data values to be read, defaulting to no limit. |
sep |
by default, scan expects to read white-space delimited
input fields. Alternatively, sep can be used to specify a
character which delimits fields. A field is always delimited by an
end-of-line marker unless it is quoted.
If specified this should be the empty character string (the default) or NULL or a character string containing just one single-byte
character.
|
quote |
the set of quoting characters as a single character
string or NULL. In a multibyte locale the quoting characters
must be ASCII (single-byte). |
dec |
decimal point character. This should be a character string
containing just one single-byte character. (NULL and a
zero-length character vector are also accepted, and taken as the
default.) |
skip |
the number of lines of the input file to skip before beginning to read data values. |
nlines |
if positive, the maximum number of lines of data to be read. |
na.strings |
character vector. Elements of this vector are to be
interpreted as missing (NA) values. Blank fields are
also considered to be missing values in logical, integer, numeric
and complex fields. |
flush |
logical: 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, but precludes
putting more that one record on a line. |
fill |
logical: if TRUE, scan will implicitly add
empty fields to any lines with fewer fields than implied by
what. |
strip.white |
vector of logical value(s) corresponding to items
in the what argument. It is used only when sep has
been specified, and allows the stripping of leading and trailing
white space from character fields (numeric fields
are always stripped).
If strip.white is of length 1, it applies to all fields;
otherwise, if strip.white[i] is TRUE and the
i-th field is of mode character (because what[i] is)
then the leading and trailing white space from field i is
stripped. |
quiet |
logical: if FALSE (default), scan() will print a
line, saying how many items have been read. |
blank.lines.skip |
logical: if TRUE blank lines in the
input are ignored, except when counting skip and nlines. |
multi.line |
logical. Only used if what is a list.
If FALSE, all of a record must appear on one line (but more
than one record can appear on a single line). Note that using
fill = TRUE implies that a record will terminated at the end
of a line. |
comment.char |
character: a character vector of length one
containing a single character or an empty string. Use "" to
turn off the interpretation of comments altogether (the default). |
allowEscapes |
logical. Should C-style escapes such as
\n be processed (the default) or read verbatim? Note that if
not within quotes these could be interpreted as a delimiter (but not
as a comment character).
The escapes which are interpreted are the control characters \a, \b, \f, \n, \r, \t, \v and octal and
hexadecimal representatons like \040 and \0x2A. Any
other escaped character is treated as itself, including backslash.
|
The value of what can be a list of types, in which case
scan returns a list of vectors with the types given by the
types of the elements in what. This provides a way of reading
columnar data. If any of the types is NULL, the corresponding
field is skipped (but a NULL component appears in the result).
The type of what or its components can be one of the six
atomic vector types or NULL (see is.atomic).
‘White space’ is defined for the purposes of this function as one or more contiguous characters from the set space, horizontal tab, carriage return and line feed. It does not include form feed, vertical tab or other non-ASCII space characters.
Empty numeric fields are always regarded as missing values.
Empty character fields are scanned as empty character vectors, unless
na.strings contains "" when they are regarded as missing
values.
If sep is the default (""), the character \
in a quoted string escapes the following character, so quotes may be
included in the string by escaping them.
If sep is non-default, the fields may be quoted in the style of
‘.csv’ files where separators inside quotes ('' or
"") are ignored and quotes may be put inside strings by
doubling them. However, if sep = "\n" it is assumed
by default that one wants to read entire lines verbatim.
Quoting is only interpreted in character fields and in NULL
fields (which might be skipping character fields).
Note that since sep is a separator and not a terminator,
reading a file by scan("foo", sep="\n", blank.lines.skip=FALSE)
will give an empty final line if the file ends in a linefeed and not if
it does not. This might not be what you expected; see also
readLines.
If comment.char occurs (except inside a quoted character
field), it signals that the rest of the line
should be regarded as a comment and be discarded. Lines beginning
with a comment character (possibly after white space with the default
separator) are treated as blank lines.
scan attempts to share storage with character strings that have
already been read in the call. If an upper bound on the number of
character strings cannot be deduced from nmax or n,
sharing is used for the first 10000 unique strings which are read in.
There is a check for a user interrupt every 1000 lines if what
is a list, otherwise every 10000 items.
if what is a list, a list of the same length and same names (as
any) as what.
Otherwise, a vector of the type of what.
The default for multi.line differs from S. To read one record
per line, use flush = TRUE and multi.line = FALSE.
(Note that quoted character strings can still include embedded new lines.)
If number of items is not specified, the internal
mechanism re-allocates memory in powers of two and so could use up
to three times as much memory as needed. (It needs both old and new
copies.) If you can, specify either n or nmax whenever
inputting a large vector, and nmax or nlines when
inputting a large list.
Using scan on an open connection to read partial lines can lose
chars: use an explicit separator to avoid this.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
read.table for more user-friendly reading of data
matrices;
readLines to read a file a line at a time.
write.
Quotes for the details of C-style escape sequences.
readChar and readBin to read fixed or
variable length character strings or binary representations of numbers
a few at a time from a connection.
cat("TITLE extra line", "2 3 5 7", "11 13 17", file="ex.data", sep="\n")
pp <- scan("ex.data", skip = 1, quiet= TRUE)
scan("ex.data", skip = 1)
scan("ex.data", skip = 1, nlines=1)# only 1 line after the skipped one
scan("ex.data", what = list("","","")) # flush is F -> read "7"
scan("ex.data", what = list("","",""), flush = TRUE)
unlink("ex.data") # tidy up