FRead

Description:              This function reads values from a formatted file and returns the number not read.

Returns:                    Numeric

Usage:                       Script

Format:                      FRead([N], File, Offset, Format, V1[, V2, V3, ...])

Parameters:             N    { numeric }  { optional }  { no default: }

                                      An optional parameter for backward compatibility. If used it must be a constant non-zero decimal number that specifies the exact number of additional Vn parameters.

                                    File    { text }  { required }  { no default: }

                                      Any text expression specifying the path, file name, and extension to read.

                                    Offset    { numeric }  { required }  { no default: }

                                      Any numeric expression giving the starting file position for the read in bytes, starting at 0.

                                    Format    { text }  { required }  { no default: }

                                      Any text expression giving the format of how the values (Vn parameters) are to be read from the file. This format is similar, but not identical, to the C language format string for the scanf function, whereby each of the % format specifications assigns a value to one of the Vn parameters in the FRead statement in the order in which each appears in the list. Note that like a standard text string, these format specifiers must also be enclosed by double quotes. If a format specification appears for which there are no remaining V parameters, the format specification value is read and discarded. For the % format specifications, the following form applies (where the [ ] indicates optional elements):

%[ * ][ width ]type

                             where the % is mandatory; * causes the read to occur as per the format specification, but suppresses any assignment to the Vn parameters; width is a number specifying the maximum number of characters to read; and type is mandatory. Type must be one of the characters listed below. Note that the case of the letter is important. Specifying a character for the type which is not in this list will result in all the characters following the % up to that point to be read exactly as they appear in the Format string and discarded:

 

                             Text string type s Text in the string is read up until a white-space character is encountered, or the specified Width has been read, whichever is smaller. Square brackets enclosing a character, group of characters, or a caret and a group of characters used in the format string reads strings not delimited by spaces. This is a substitute for the %s format specification. The input is read up to the first character that does not appear inside the square brackets (note that this is case-sensitive). A dash may be used to specify a range of characters. For example, the following format specifier:

                              %[A-Fa-f]

                             will read a string up to the first which is not an A, B, C, D, E, or F, both upper and lower case.

                              If the first character inside the square brackets is a caret ( ^ ), the read progresses up to the first character that does not appear inside the square brackets:

                              %[^X-Z]

                              This would read a string up to, but not including, the first X, Y or Z (upper-case only); if the string were terminated by an X, the next character read would be that X. Inside the square brackets, the backslash is used as an escape character - any character following a backslash (such as a caret, dash, or backslash) is taken as that character without special meaning. For example:

                              %[^X-Z\^]

                              would behave as described previously, except that the string would now be read up to but not including the first X, Y, Z, or ^.

                              Since format specifications for the Vn parameters are indicated by a percentage sign, to read (and discard) an actual percentage sign as part of the text string, precede it with a backslash character (i.e. \%). Also, since the backslash character is used in this manner, as well as with special control characters such as line feed, carriage return and form feed, to read and discard a backslash, use two backslash characters (i.e. \\).

 

                             Escape characters znnn This specifies an escape character that will be thrown away when read, where nnn is a 3-digit number giving the ASCII character code of the escape character. This option is generally used as the sole format specifier that reads an entire string, spaces included, discarding every single occurrence of an escape character, or the first occurrence of every pair of escape characters. For example, if the string to be read looked like:

                              abXc dXXfghiXXXjXXXXkl mX Xn o

                              and the format specifier indicated that the ASCII code for 'X' (88) was to be the escape code:

                              %25z088

                              then the variable that this was read into would contain:

                             abc dXfghiXjXXkl m n o

                              Notice that for each occurrence of X, the character immediately following it is saved, even if it is itself an escape character. Then the next occurrence of the escape character is discarded, with the character following it being saved, regardless of what it is, and so on. The width field specifies the maximum number of bytes to place in the output string; if this number is smaller than the input string (less the offending escape characters), the string will be truncated. If no width is specified, a single character will be read.

                             Control characters In order to encode certain control characters as part of the Format parameter, one of two methods may be used. The first is to use a backslash character followed by one of the single character codes listed below to produce the desired result. Please note that the letters must be in lower case.

 

                            

                                    V1, V2, …    { varies }  { required }  { no default: }

                                      Are the variables to be read in the form described by the Format parameter; expressions are not allowed. Each of the Vn parameters is read in the order in which each appears in the parameter list; V1 has the format given by the first % sequence in the Format parameter, V2 has the second, and so on.

Comments:               Data exchange between many file formats is possible if the file formats are known. The return value is optional and is the number of Vn parameters NOT read; this can be used as an error flag.

Example:

If ! Valid(err)

[

  err = FRead(3 { Number of parms }, 

              "G:\RECIPES\GLUE.DAT" { File to read from }, 

              0 { Starting point }, 

              "%f%f%n" { Format }, 

              compoundA, resin, offset { Parameters }); 

]

This reads two ASCII format floating-point numbers, starting at the beginning of G:\RECIPES\GLUE.DAT and places them in compoundA and resin, respectively. After the read is complete, the ending file position is stored in offset. If the read were successful, err is 0; otherwise it is the number of items which were not read.

See Also:

BuffRead | BuffWrite | FileSize | FWrite | SRead | SWrite