Node:Binary stream I/O, Next:, Previous:Files, Up:Usage

Binary stream I/O

Every binary stream class offers the same set of binary I/O methods, inherited from one of the general stream base classes binistream, binostream or both of them. These, in turn, inherit from the binio class, which provides additional general methods, as well as some important type declarations.

The binary I/O methods differenciate between integers, floating-point numbers and character strings.

To read an integer from a binary stream, you would use readInt(size). The size argument specifies the size of the integer in bytes. The method returns the integer, that has just been read.

readFloat(type) reads a floating-point number of type type from the stream. As all floating-point formats are well defined, you just have to specify the right floating-point type to this method and it will figure out the correct size by itself. Refer to Reference for information of what floating-point formats are supported and how to specify them. The method returns the floating-point number, that has just been read.

A character string can be read by using the readString() method. To read a character string into a pre-allocated C style ASCIIZ string buffer, you would use readString(string, max-length, [delimiter]) and give a pointer to the string buffer with string, the maximum length of the string (not including the final \0) in max-length and optionally a delimiter character delimiter, at which libbinio would stop reading the string, even if it could read more characters. The delimiter is extracted from the stream and then discarded. It will not appear in the final string. If you do not supply a delimiter, it is \0 by default. The method returns the number of characters actually read from the stream.

You can also read an STL string object from the stream, using an overloaded version of readString(). The syntax is readString([delimiter]). Again, you do not need to supply the delimiter, as it is \0 by default. The method returns a string object, containing all characters up to, but not including, delimiter or the end of the stream, whichever was encountered first.

All the above mentioned "read" methods have a "write" equivalent, with the same options and features. All "write" methods take the data to be written as first argument, as in (for example) writeInt(value, size), value is the actual value to be written to the stream.

Sometimes, you need to reposition within your stream. To do this, you use the seek(position, [offset]) method. position is the new position in the stream, counted byte-wise and starting at 0. The optional argument offset specifies from where the method should seek. If it is Set, counting is started at the beginning of the stream. Add indicates to seek from the current stream position and End means seeking from the end of the stream. Note that position is a signed integer value and you can also seek backwards by inserting a negative number.

You can use the pos() method to determine your current position within the stream, which is returned by the method.