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.

Поскольку 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

Поскольку 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

Поскольку 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.

Поскольку 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