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.

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

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.

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

### See Also

`read.table` for more user-friendly reading of data matrices; `readLines` to read a file a line at a time. `write`.

### 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 Contents]