NAME

read - read values from a file

SYNOPSIS

Formatted, text-mode file reads:

Formatted, internal string reads:

Unformatted, binary-mode file reads:

DESCRIPTION

The read() intrinsic procedure / method is used for text-mode file formatted reads, internal string formatted reads, and binary-mode file unformatted reads. OADL distinguishes between the three cases according to this table (a string may be a String or a WideString):

File Formatted Reads

Formatted text-mode read()s from a file read UTF-8 sequences, matching them to an OADL Format Specification, fmtspec. This is a string that contains one or more Format Descriptors, separated by commas. The most common Format Descriptors describe how each val is to be formatted; these include:

The [width] is an optional field width; if omitted, a field width will be computed based on white-space separation of the input. The format value descriptors may be prefixed with a repeat count, which indicates that the descriptor is to be repeated for that many values.

Embedded literal strings must be matched character-for-character in the input. If a mismatch occurs, a RangeCheck error will be thrown.

Reads of input formatted by OADL print that includes boxes cannot be automatically read by OADL.

Internal String Formatted Reads

Formatted reads from an OADL string or packed character array are similar to reads from a File, except they take their input characters from the provided array. The input is not a list of UTF-8 sequences; rather, the characters or wide characters are taken as presented.

Unformatted Reads

Unformatted binary-mode reads do not use a format specifier. Rather, they rely on the one or more Type arguments passed in to determine what to read. Each Type argument may be a simple scalar type (for example, Int, Float, etc.) or a fully-qualified packed array type (for example, String[40] or PackInt[1024]). From one to eight unsigned bytes are read from the input file for each base-type element, and optionally byte-swapped, according to this table:

See setswab and getswab for more information on byte swapping.

RETURN VALUE

A List of items read (or a single scalar, if only one column was requested by type or implied by the fmtspec)

ERRORS

ArgCheck for an incorrect number of arguments
TypeCheck for a non-string fmtspec or a non-File file or non-Type typ
AccessCheck for an attempt to access a closed file
FormatCheck for a syntax error in fmtspec (note that static format strings will be checked at compile-time, not run-time)
RangeCheck for input that does not match a literal or for input characters that don't match the field type
UTF8Check for an illegal UTF-8 input byte from a text-mode file
IoCheck for other miscellaneous I/O errors (see ferror)

EXAMPLES

        // Formatted read from io::Input
        v = read("L,I")  // Next line is input from keyboard
    False 3
        v  // v is a List of the values read - note case-insensitivity of read
    false 3
    
        // Formatted read with type specification
        v = read("F,F", Int, Float)
    1.4 2.4
        v  // note the type coversion performed on the first element
    1 2.4

        // Read an array
        v = read("I", PackInt[2,3])
    7 6 5
    4 2 6
        v  // It will be a List because more than one element was read
    +-----+
    |7 6 5|
    |4 2 6|
    +-----+

        // Formatted read from a string
        v = "False 3".read("L,I")
        v
    false 3

        // Formatted read from a packed char array
        x = "1 2 3 4 5 6 ".reshape(2,6)
        v = x.read("I",PackInt[2,3])
        v
    +-----+
    |1 2 3|
    |4 5 6|
    +-----+

        // Unformatted I/O
        f = new File("foo.bin", "wb+")
        f.write(1,2.5)
        f.rewind()
        v = f.read(Int, Float)
        v
    1 2.5
        f.close("delete")

SEE ALSO

OADL Format Specifiers
format
readstr
print
write
new File