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, always up to max-length characters are
read from the stream. 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]). You also do not need to
supply a delimiter, as it is set to \0 by default (to
prevent you from reading a virtually unlimited number of characters
and flood your memory, since you can't supply a max-length
argument this time). 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.