scan | R Documentation |
Read data into a vector or list from the console or file.
scan(file = "", what = double(), 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, fileEncoding = "", encoding = "unknown", text, skipNul = FALSE)
file |
the name of a file to read data values from. If the
specified file is Otherwise, the file name is interpreted relative to the
current working directory (given by This can be a compressed file (see Alternatively,
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
|
what |
the type of |
nmax |
the maximum number of data values to be read, or if
|
n |
integer: the maximum number of data values to be read, defaulting to no limit. Invalid values will be ignored. |
sep |
by default, scan expects to read ‘white-space’
delimited input fields. Alternatively, If specified this should be the empty character string (the default)
or |
quote |
the set of quoting characters as a single character
string or |
dec |
decimal point character. This should be a character string
containing just one single-byte character. ( |
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 ( |
flush |
logical: if |
fill |
logical: if |
strip.white |
vector of logical value(s) corresponding to items
in the If |
quiet |
logical: if |
blank.lines.skip |
logical: if |
multi.line |
logical. Only used if |
comment.char |
character: a character vector of length one
containing a single character or an empty string. Use |
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 representations like \040 and \0x2A. Any other escaped character is treated as itself, including backslash. Note that Unicode escapes (starting \u or \U: see Quotes) are never processed. |
fileEncoding |
character string: if non-empty declares the
encoding used on a file (not a connection nor the keyboard) so the
character data can be re-encoded. See the ‘Encoding’ section
of the help for |
encoding |
encoding to be assumed for input strings. If the
value is |
text |
character string: if |
skipNul |
logical: should nuls be skipped when reading character fields? |
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 nor vertical tab, but in Latin-1 and Windows 8-bit locales (but not UTF-8) 'space' includes the non-breaking space "\xa0".
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.
The allowed input for a numeric field is optional whitespace followed
either NA
or an optional sign followed by a decimal or
hexadecimal constant (see NumericConstants), or NaN
,
Inf
or infinity
(ignoring case). Out-of-range values
are recorded as Inf
, -Inf
or 0
.
For an integer field the allowed input is optional whitespace,
followed by either NA
or an optional sign and one or more
digits (0-9): all out-of-range values are converted to
NA_integer_
.
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.
There is a line-length limit of 4095 bytes when reading from the console (which may impose a lower limit: see ‘An Introduction to R’).
There is a check for a user interrupt every 1000 lines if what
is a list, otherwise every 10000 items.
If file
is a character string and fileEncoding
is
non-default, or if it is a not-already-open connection with a
non-default encoding
argument, the text is converted to UTF-8
and declared as such (and the encoding
argument to scan
is ignored). See the examples of readLines
.
Embedded nuls in the input stream will terminate the field currently
being read, with a warning once per call to scan
. Setting
skipNul = TRUE
causes them to be ignored.
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
.
Character strings in the result will have a declared encoding if
encoding
is "latin1"
or "UTF-8"
.
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 newlines.)
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.
Having nul
bytes in fields (including \0 if
allowEscapes = TRUE
) may lead to interpretation of the
field being terminated at the nul
. They not normally present
in text files – see readBin
.
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 ## "inline" usage scan(text = "1 2 3")
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.