Next: vector()
Up: MacAnova Help File
Previous: vecread_file
Contents
Usage:
List of keywords that can be used on vecread() or readcols().
Keyword Value
badkeyok T or F*
badvalue REAL scalar or MISSING
bychar T or F*
byfields T or F*
bylines T or F*
bypass Nonnegative integer
bywords T or F*
echo T or F
file CHARACTER scalar file name
go CHARACTER scalar with one character
n Positive integer
nofileok T or F*
printname T or F*
prompt T* or F
quiet T or F*
silent T or F*
skip CHARACTER scalar with one character, default "#"
skipthru CHARACTER scalar with one character
startline Positive integer
stop CHARACTER scalar with one character
string CHARACTER scalar or vector
* Default
|
Keywords:
files, input, output
This topic summarizes the use of keyword phrases as arguments to
vecread() which reads data items row by row from a text file. Type
usage(vecread_keys) for a list of vecread() keywords. See also topics
vecread() and 'vecread_file'.
Some of the examples use keyword 'string'. See below for information.
Keyword phrases specifying that CHARACTER data should be read
bywords:T Read CHARACTER data by words
The file is interpreted as a sequence "words" or fields separated by
commas, or "invisible" characters (spaces, tab characters and ends of
lines). The result is a CHARACTER vector, each element of which is a
word from the file.
Each word is empty or consists of a sequence of visible characters
that are not commas. An empty word occurs before a leading comma,
after a trailing comma or between two commas with no intervening
visible characters and is read as "". For example
vecread(string:",a ,, b,",bywords:T) returns vector("","a","","b","")
bylines:T Read CHARACTER data by lines
Each line read becomes a single element of a CHARACTER vector. The
line-separating character "\n" is not included. All other characters,
including commas and invisible characters are read. If no line starts
with the stopping character, the length of the result is the number of
lines in the file.
bychar:T Read CHARACTER data as separate characters
Each character read, including commas, invisible characters and line
separating characters, is read as a single element. If no line starts
with the stopping character, the length of the result is the number of
characters in the file.
Keyword phrase specifying how REAL data will be read
byfields:T REAL items read by "fields"
The file is interpreted as a sequence of "fields" separated by commas
or "invisible" characters. The result is a REAL vector, each element
of which is derived from a field in the file.
A field is either empty or consists of a sequence of visible
characters that are not commas. An empty field occurs before a
leading comma, after a trailing comma or between two commas with no
intervening visible characters and is read as MISSING. A non-empty
field that is a well formed number (for example, -17, 3.14e73 or
2.7182818) is read as that number. If the number is too large to be
represented in the computer (for example -3.1e3000), it is read as
MISSING. When a non-empty field is not a well formed number (for
example 3.5a7 or Foo), it is read as badV when 'badvalue:badV' is an
argument, or as MISSING otherwise.
Keyword phrases specifying what to read
file:FileName Read from file FileName
This is an alternate way to specify the file to be read. That is
vecread(file:FileName [,keyword phrases]) is equivalent to
vecread(FileName [,keyword phrases]). Filename must be a quoted
string or CHARACTER scalar.
string:CharVar "Read" from CHARACTER scalar or vector CharVar
CharVar is "read" as if it were a file whose contents are specified by
CharVar. Any instances of "\n" are treated as terminating a line.
When CharVar is a vector, each element is assumed to start a new line.
When CharVar is a CHARACTER vector, each element is read as for a
CHARACTER scalar, with each element starting with a new line. With
bychar:T, "" is inserted between each element of CharVar.
Examples: Suppose S1 is "12\n34" and S2 is vector("12","34").
vecread(string:S1 [,byfields:T]) and vecread(string:S2 [,byfields:T])
return vector(12,34).
vecread(string:S1, bywords:T or bylines:T) and vecread(string:S2,
bywords:T or bylines:T) return vector("12","34")
vecread(string:S1, bychars:T) returns vector("1","2","\n","3","4")
vecread(string:S2, bychars:T) returns vector("1","2","","3","4")
Keyword phrase limiting the number of items to be returned
n:N No more than N items to be returned
If fewer than N items are found before the stop character or the end
of the file, a warning message is printed. N must be a positive
integer.
Keyword 'n' is illegal as an argument to readdata().
Keyword phrases specifying which lines should be read as data.
stop:"$" Set stop character to '$' (default is "!")
Reading stops when a stop character is encountered. With 'bychars:T'
and 'bylines:T', a stop characters is recognized only as the first
character in a line. With 'byfields:T' and 'bywords:T' it is
recognized only as the first character in a field or word.
For numerical data, the stop character can be any punctuation
character except '+', '-', ',', '?' or '.', that is, any of
!"#$%&'()*/:;<=>@[\]^_`{|}~.
For CHARACTER data, the stop character can be any punctuation
character except ',', including '+', '-', '?' or '.'.
For both numerical and CHARACTER data, the stop character can also be
a "non-ASCII" character (code >= 128 = octal 200 = hexadecimal 80)
such as "\200", "\377", "\x80" or "\xff", except when reading from
CONSOLE. This might be called for when you want to ensure the whole
file is read, and you know the file does not contain non-ASCII
characters.
bypass:P Skips past P lines starting with stop character
When P > 0, nothing is read or echoed until P lines starting with
the stop character have been read. This allows you to read several
sets of data on the same file provided they are separated by lines
starting with the stop character. This takes precedence over all
other keywords that control which lines are read. 'bypass' is
illegal with readdata().
startline:M Sets the first line to be scanned.
Start reading on line M of the file, that is, the first M-1 lines are
ignored and never echoed. This takes precedence over all other
keywords except bypass that control which lines are read. Stop,
skip, skipthru, and go characters are not recognized if they come
before line M. The default value for M is 1. With bypass:P, reading
starts on line M after the P-th line starting with the stop character.
skipthru:"@" Set skipthru character to '@' (no default)
Lines up to and including the first line starting with the skipthru
character are ignored. They may be echoed, depending on the values of
keywords 'echo', 'quiet' and 'silent'.
The skipthru character can be any character. When the skipthru
character is "\n", reading starts after the first completely "white"
line, that is, a line with no visible characters.
The skipthru character takes precedence over and can be the same as
the skip, stop or go characters. It is ignored until after the lines
skipped because of keywords 'bypass' and 'startline'.
go:"%" Set go character to '%' (no default)
Reading stops with the first line that does not start with the go
character. It is ignored until after the lines skipped because of
keywords 'bypass' and 'startline'.
skip:"#" Set skip character to '#' (default is "#")
Lines starting with skip character are ignored (they may be echoed).
For numerical data, the allowable skip characters are the same as for
stop characters.
For CHARACTER data, any visible printing character, including a comma,
may be a skip character.
When the skip character is the same as the stop character (for
example, stop:"#",skip:"#"), scanning will be stopped only if the stop
character occurs after the first character in a non-skipped line (for
example, by a line starting " #..." but not by "#...").
Keyword phrases controlling what is printed
quiet:F Prints skipped lines, if any
The lines printed are those skipped because of the skip or skipthru
characters, but not those skipped by 'bypass:P' or 'startline:M'.
echo:T or F Control echoing of lines scanned.
With echo:T, all lines scanned, including lines skipped because of the
skip or skipthru character, are echoed to output. With echo:F, the
only lines echoed are skipped lines with quiet:F.
When FileName is CONSOLE and the vecread() command is in a batch file,
data that is read is echoed to output unless echo:F is an argument.
This also happens in windowed versions (Macintosh, Windows, Motif)
even when not reading from a batch file.
silent:T Suppress all warning messages and echoing
This is incompatible with echo:T or quiet:F.
printname:F Suppress printing the name of the file read
The default is printname:T except with string:CharVar.
prompt:F Suppresses prompt when reading from CONSOLE
Keyword phrases related to anomalies
badkeyok:T Ignore unrecognized or duplicate keywords
Without badkeyok:T, unrecognized or duplicate keywords are considered
errors. This feature is useful in a macro where a line like
@x <- vecread("data.txt",silent:T,badkeyok:T,$K) should work,
even if the argument list to the macro includes keyword 'silent' or
other keywords not recognized by vecread().
badvalue:badVal Replace unreadable REAL items by badVal
When reading REAL data with badvalue:badVal an argument, any
unreadable items are replaced by badVal, which must be a REAL scalar
or MISSING. Without badvalue:badVal, unreadable items are replaced by
MISSING when 'byfields:T' is an argument and are skipped otherwise.
nofileok:T Failure to open the file is OK.
When a file can't be opened, NULL is returned and no error message is
printed. Without nofileok:T, this is an error.
Gary Oehlert
2003-01-15