scan                  package:base                  R Documentation

_R_e_a_d _D_a_t_a _V_a_l_u_e_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

    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. 

_D_e_t_a_i_l_s:

     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 as from R
     1.8.0 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.

     As from R 2.1.0, '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.

_V_a_l_u_e:

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

_N_o_t_e:

     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.

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

     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

