READ
Variable = READ [ # Stream ] AS Datatype
Variable = READ [ # Stream , ] Length
Reading a specific datatype
The first syntax reads the stream
Stream as binary data whose type is specified by the
Datatype argument. The binary representation is the one used by the
WRITE instruction.
If the stream is not specified, then the standard input is used.
The returned datatype can be one of the following:
NULL,
Boolean,
Byte,
Short,
Integer,
Long,
Pointer,
Single,
Float,
Date,
String,
Variant, any
Array,
Collection or structure.
When reading a string, the length of the string must precede the string contents in the stream data.
See
Binary Data Representation for more information.
Since 3.15
If the
Stream.NullTerminatedString property is set, then the length of the string is not read, and the string is read until a null byte is encountered.
If the stream contents cannot be interpreted, an error is raised.
This instruction uses the byte order of the stream to read the data.
Reading any object
Since 3.15
Any object can be unserialized, provided that its class implements the
_read special method.
If the object has been previously serialized to the stream in the right way, it is rebuild by calling its constructor with no argument, and then the
_read method is called.
You read the object by using one of the following syntax:
Object = READ # Stream As ObjectClass
Object = READ # Stream As Object
Object = READ # Stream As Variant
If you read the object by using
'As Variant' or
'As Object', you have to have written it by using
'As Variant' or
'As Object'.
Because in that case the needed object class name is written to the stream. Otherwise the
READ instruction does not have the class name needed to instanciate the object.
Reading the contents of a string
The second syntax reads from the stream
Stream a number of bytes specified by the
Length argument, and returns it as a string.
If
Length is negative, then at most (-
Length) bytes are read until the end of the stream.
If the stream is not specified, then the standard input is used.
Compatibility with Gambas 2
WRITE #Stream, Expression writes the binary form of
Expression in Gambas 2.0.
In Gambas 3.0 it writes
Expression as a string.
So you
HAVE to check all your
WRITE instructions when converting a Gambas project from 2.0 to 3.0, and
specified
AS Datatype when need.
By default, the compiler supports the old READ syntax, and the old WRITE syntax as it is compatible.
If you want to detect where you should rewrite your READ / WRITE syntax, you can
compile your project by hand with the "--no-old-read-write-syntax" flag. Then
the
Length argument of WRITE becomes mandatory if the second syntax is used.
Using a
Pointer as a stream is not possible anymore. Create a memory stream with the
OPEN MEMORY instruction instead.
See also