SRead

(Engine-Level Function)

Description:	Reads values from a formatted stream and returns the number of values not read.
Returns:	Numeric
Usage:	Script Only.
Function Groups:	Stream and Socket
Related to:	BuffRead \| CloseStream \| FileSize \| FileStream \| FRead \| GetStreamLength \| StreamEnd \| SWrite
Format:	SRead(Stream, Format, V1, V2, V3, ... )
Parameters:

Stream

Required. Any expression that returns the stream to read.

Format

Required. Any text expression giving the format of how the values (Vn parameters) are to be read.
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 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…

Is a mandatory character

The optional asterisk causes the read to occur as per the format specification, but suppresses any assignment to the Vn parameters.

width

Width is optional, specifying the maximum number of characters to read.

type

The specifications for type are listed in the following table:

Note: Format strings are case insensitive. Additionally, specifying a character for a type that is not in this list results in all the characters following the % up to that point to be read exactly as they appear in the Format string and discarded.

Type	Meaning
Nb	Binary format, where n is a number indicating the type of value (see below)
c	Single ASCII character (byte)
d	Signed decimal integer
e	Signed exponential
f	Signed floating point
g	e or f formats
i	Signed decimal integer
l	Line of characters terminated by a carriage return, line feed, or both
n	Present offset in the buffer
o	Unsigned octal
s	Text string
t	Counted string
u	Unsigned decimal integer
x	Unsigned hex integer using "abcdef"
znnn	Escape character where nnn is the 3-digit ASCII code

nb, Binary type For the format specification of %nb, where n specifies the type of number, n must be a single digit from one of the following choices. All are low-byte-first.

n value	Type
0	Byte
1	Short integer (2 bytes, low byte first)
2	Long integer (4 bytes, low bytes first)
3	IEEE single precision float (4 bytes)
4	<obsolete>
5	IEEE double precision float (8 bytes)
6	<obsolete>
7	Binary unsigned short (2 bytes, low byte first)
8	Unsigned 32-bit integer
9	64-bit FileTime. This reads or writes a 64 bit time value in the Microsoft FileTime format. When reading, the value is converted from the FileTime epoch and units (100 nanosecond intervals since Jan 1, 1601) to the VTS epoch and units (seconds since 1/1/1970) any times earlier than this will result in a value of 0. When writing, the value is converted from the VTS epoch and units to the FileTime epoch and units.

c, ASCII character type: Unlike BuffWrite this type deals with characters in a string; each character being equal to one byte. Unlike the %s option, which reads only up to the first white-space character, the %c option reads the number of characters/bytes specified by its width and is not terminated by any particular character. If no width is specified, a single character is read.

d, Signed decimal integer

e, Signed exponential

f, Signed floating point

g, e or f formats

i, Signed decimal integer type: This option normally reads a decimal integer; however, if a leading "0b" is encountered, the number will be interpreted as binary. If a leading "0" (zero only) is encountered, the number will be interpreted as octal. If a leading "0x" is encountered, the number will be interpreted as hexadecimal.

l, Line of characters: This option reads a line of characters terminated by a carriage return, a line feed, or both (in either order). The carriage return and line feed will be discarded, and the next character read will be the first character on the next line. The maximum number of characters read is 2GiB (2^30 bytes) or less if the width option is used.

n, Buffer offset: This option does not read a value, but returns the present offset in Buffer and can be useful in subsequent reads.

o, Unsigned Octal

s, Text string type: 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.

t, Counted string type A counted string is encoded as a sequence of UTF-8 characters without a null terminator and preceded by the length in bytes.

The length in bytes is encoded as Int32, i.e. a "%2b". A value of −1 is used to indicate an invalid string, a value of 0 indicates a null ("") string.

Do not apply width or precision modifiers to a "%t" counted string.

The caret symbol ^. If the first character inside the square brackets is a caret ( ^ ), the read progresses up to, but not including, the first character that appears 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 ^.

Because 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. \\).

x, Hexadecimal characters: the %x option reads the number of characters/bytes specified by its width and is not terminated by any particular character. If no width is specified, it will continue reading all bytes that can be recognized as hexadecimal characters. For example, given the string "…= 3D", %[^=]=%2x would read the hedadecimal value, 3D (decimal value, 61).

znnn, Escape characters: 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 lower case.

Code	Meaning
\b	Backspace
\f	Form Feed
\n	Line Feed
\r	Carriage Return
\t	Horizontal Tab
\v	Vertical Tab

In addition to the predefined codes, an alternate form may be used:

\nnn: where nnn is a three digit integer in the range of 0 to 255 specifying a certain ASCII character. If the number contains less than three digits, the leading spaces must be padded with zeroes; this is not the case with the previously listed single character control characters. For example, to include the one byte ASCII character G in the output, you could place its decimal equivalent of 71 in the Format string as \071.

V1, V2, V3, ...

These parameters 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:

This function is useful for reading formatted streams. Data exchange between many formats is possible if the 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.

Strings are limited to 2GiB (2^30 bytes)

Examples:

If ! Valid(err);
[
  err = SRead(recipeStream, "%f%f%f",compoundA, compoundB,
  resin);
]

This reads three ASCII format floating-point numbers, from the current position in the stream in the variable recipeStream. The three numbers are placed in compoundA, compoundB and resin, respectively. If the read were successful, err is 0. Otherwise err is the number of items which were not read.

streamData = "Hello!World!How!Are!You!";
If ! Valid(notRead);
[
  notRead = SRead(streamData, "%[^!]!%[^!]!%[^!]!%[^!]!%[^!]!",
  word1, word2, word3, word4, word5);
]

This is an example of multiple fields delimited by the same character, in this case an exclamation point, that can be read by using the %[ ^ aCharacter] format. Notice the exclamation point following each format character - this causes the string read into each of the variables to be without its trailing exclamation point.