46.7. read

read reads values from an input file, a STRING, or a memory location.

The forms that read a BOOLEAN, (LONG) INTEGER, (LONG) REAL, or (LONG) BITS from a text file or STRING use a scan for the proper constant representation. As soon as the scan finds what could be the start of a constant of the desired type, it begins forming the value. All characters involved in the scan are removed from the source STRING or text file. Characters not involved in the scan are not removed; e.g., if the characters involved in the scan occur immediately before an eol, the eol is left in the source.

The forms of read that read a BOOLEAN from a text file or STRING scan for the STRING representation "TRUE" or "FALSE". Case is ignored. As soon as one of these STRING representations is found, or there are no more characters in the source STRING or text file, the scan stops. All scanned characters are removed from the source STRING or text file. The BOOLEAN value produced is TRUE if the characters TRUE were found in the source; otherwise, it is FALSE. The characters TRUE or FALSE need not be preceded or followed by a blank, tab, or end of line.

Numeric ((LONG) INTEGER and (LONG) REAL) and (LONG) BITS scans ignore dots, single quotes, and minuses that are not associated with valid digits. For example, if the STRING:

"These ' and - and . are ignored; the value read is 2"

is scanned for a numeric or BITS, the 2 is found, and the symbols ', -, and . are ignored since they are not associated with valid digits.

The L that follows LONG constants as written in a source program is not used by the scan. For example, if the STRING:

"123L 456"

is scanned for a (LONG) INTEGER, 123 is returned, and the STRING becomes:

"L 456"

A (LONG) INTEGER scan looks for one or more digits, possibly preceded by -. For example, if the STRING:

"123. 456"

is scanned for an INTEGER, 123 is returned, and the STRING becomes:

". 456"

On the other hand, if it were scanned for a REAL, then 123. would be returned, and the STRING would become:

" 456"

A (LONG) REAL scan accepts an INTEGER constant. For example, if the STRING:

"123 456."

is scanned for a REAL, 123. is returned, and the STRING becomes:

" 456."

A BITS scan accepts the standard representation, i.e., ' optionally followed by a base letter, then digits. It also accepts a sequence of octal digits not preceded by '. For example, if the STRING:

"1238 '456"

is scanned for a BITS, '123 is returned, and the STRING becomes:

"8 '456"

The effect is undefined of reading a (LONG) INTEGER or (LONG) REAL from a STRING or text file if the text scanned represents a value outside the MAINSAIL guaranteed range.

A STRING read from a STRING or file returns the next line by scanning for eol (end-of-line), which is then discarded. Characters in a data file are stored one per character unit, as in a text file. If the file is opened for PDF I/O, characters may be translated to the host character set. In the area forms, area specifies the destination area for the resulting STRING if new STRING text is generated; see Section 29.4.

When a STRING is read from a data file, null characters and carriage returns present in the file are included in the STRING; in other words, data files always act as if the keepNul bit were set, regardless of the setting of that bit when the file was opened.

Data types other than STRING read from a data file are removed from the file; i.e., the file position is updated to be immediately beyond the values read. This means that, in reading a non-STRING variable from a text file, the remainder of the line on which the value occurs is left in the file; for example, the following code fragment:

INTEGER i; STRING s;
...
read(cmdFile,i): read(cmdFile,s);

given the input line (read from cmdFile):

16<eol>

sets i to the value 16, leaving the <eol> in cmdFile, unread. The next call to the textFile/STRING form of read scans up to the (still unread) eol, discards it, and therefore sets s to the empty STRING. Only one line is read from cmdFile for both calls to read, since the first call does not exhaust the input line.

In all reads from a file or STRING, the result is Zero if no value is found when reading from the file or STRING (i.e., if end-of-file or end-of-STRING is encountered).

After reading from an ADDRESS, the ADDRESS is displaced to the location immediately following that from which the value was read. The result is undefined if the ADDRESS is NULLADDRESS, if the ADDRESS is unaligned (see Section 3.9), or if displace(a,size(data type of v)) is undefined.

Note that unlike ADDRESSes, there is no alignment restriction on the current file position when reading from a file; any data type may be read from any position in either a text or a data file.