Streams



Jarog has built-in support of file streams. Stream can be attached to a file on a hard drive or it can be in-memory. In-memory streams are used to work with network and some other kinds of processing binary data.

Each stream is a resource, represented by a handle - integer value unique for each stream. This is similar to how it was implemented in C language.

Stream routines are provided by a file unit. Some routines also are provided by a fs unit.

Stream opening and closing

For stream opening there is a function open. It accpets string parameter with path and returns handle of a stream. It creates a file if it does not exists by given path but folder structure must exist before file creation.

If path is empty stream is created in memory.

After the work with stream is over, stream has to be closed to complete data writing to disc and release OS resources. For this purpose there is a procedure close. It accepts stream handle only.

Reading and writing data

Thre are three different funtions for four simple types respectively used for reading data from stream and three procedures for writing data into stream. All these functions and procedures are provided via file unit.

Integer

To read and write integer numbers there are readInt and writeInt routines. Jarog does not support platform specific integer types like byte or word. It supports one abstract integer type with arbitrary length but streams can contain integers of any length.

To handle this situation both routines accept parameter size to determine the length of an integer. It can be 1, 2, 4 or 8. Constans sz_byte, sz_word, sz_int and sz_long are defined in file untit.

Float

For float numbers unit file provides readFloat and writeFloat routines. Similar as with integers there are two precision levels, single and double, that can be read from stream when Jarog supports only abstract float value.

Float routines also accept size parameter and this time it can be 4 or 8 reflecting float value length in bytes for single and double precision.

String

String values can be read and wrote to steam via readStr and writeStr routines from file unit.

This routines also perform string encoding and decoding. They accept encodingparameter - integer value containing codepage. Unit file has some codepage constants, see list of constants.

Other stream operation

Position

Each stream has a position, this is where data is read or written. Function getPos accepts stream handle and returns single integer - current position in stream. Position can be changed with setPos procedure taking stream handle and a new position.

Size

Stream size can be retrieved with size function. It accepts stream handle and returns it’s size. Stream size can be changed with trunc procedure. It accepts stream hanle and truncates file at it’s current position.

Stream copying

Data can be copied from one stream to another directly with copy procedure. It accepts handle of source stream, handle of destination string and amount of bytes to be copied from source to destination. This procedure starts to copy bytes from source current position and writes bytes to destination current position.