WRITE
WRITE [ # Stream , ] Expression AS Datatype
WRITE [ # Stream , ] String [ , Length ]
WRITE [ # Stream , ] Pointer , Length
Writing a specific datatype
The first syntax writes an expression to the stream
Stream by using their binary representation.
If the stream is not specified, the standard output is used.
When writing a string, the length of the string is sent before the string contents.
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 written, but a null byte is written after the end of the string.
The datatype of
Expression can be one of the following :
NULL,
Boolean,
Byte,
Short,
Integer,
Long,
Pointer,
Single,
Float,
Date,
String,
Variant, any
Array or
Collection, or any structure.
If
Expression is a collection, an array, or a structure, then its contents are written recursively.
When writing a structure, the structure type must be specified as
Datatype.
If an unsupported datatype is written, or if a circular reference is detected, an error is raised.
This instruction uses the byte order of the stream to write the data.
Writing the contents of a string
The second syntax writes
Length bytes from the string
String to the specified stream.
If the stream is not specified, the standard output is used.
If
Length is not specified, the length of
String is used.
Writing the contents of memory
The third syntax writes
Length bytes from the memory address
Pointer to the specified stream.
If the stream is not specified, the standard output is used.
Length must be specified, otherwise nothing is done.
Writing any object
Since 3.15
Any object can be serialized, provided that its class implements the
_write special method.
You write the object by using one of the following syntax:
WRITE #Stream, Object As <ObjectClass>
WRITE #Stream, Object As Object
WRITE #Stream, Object As Variant
If you read the object later by using
'As Variant' or
'As Object', you have to write 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.
Writing the same object several times
Since 3.17
Before the 3.17 version, objects written several times were duplicated.
Since the 3.17 version, they are not duplicated anymore. Once an object has been serialized, it is written as a five bytes reference each time it is written again.
Similarly, when read back, the object is created once, and shared between all other references.
Since 3.19
Since Gambas 3.19, collections, arrays and structures are always duplicated.
Only serializable objects implementing the
_write special method are shared.
Compatibility with Gambas 2
BEWARE!
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
specify
AS Datatype when need.
By default, the compiler supports the old
READ syntax, and the old WRITE syntax too 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