R: Read Data Values

scan {base}

R Documentation

Read Data Values

Description

Read data into a vector or list from the console or file.

Usage

scan(file = "", what = double(0), nmax = -1, n = -1, sep = "",
     quote = if (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 = "")

Arguments

file

the name of a file to read data values from. If the specified file is "", then input is taken from the keyboard (in this case input can be terminated by a blank line).

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.

file can also be a complete URL.

what

the type of what gives the type of data to be read. If what is a list, it is assumed that the lines of the data file are records each containing length(what) items (“fields”).

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 (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 a newline unless it is quoted.

quote

the set of quoting characters as a single character string.

dec

decimal point character.

skip

the number of lines of the input file to skip before beginning to read data values.

nlines

the maximum number of lines of data to be read.

na.strings

character vector. Elements of this vector are to be interpeted as missing (NA) values.

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).

Details

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 type is NULL, the corresponding field is skipped (but a NULL component appears in the result).

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 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.

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 file line if the file ends in a linefeed and not it 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) are treated as blank lines.

Value

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.

Note

The default for multi.line differs from S. To read one record per line, use flush = TRUE and multi.line = FALSE.

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.

Examples

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
str(scan("ex.data", what = list("","",""))) # flush is F -> read "7"
str(scan("ex.data", what = list("","",""), flush = TRUE))
unlink("ex.data") # tidy up

[Package base version 1.5.0 ]