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 encoding
parameter - 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.