binio

binio is the general base class, containing important method, type and variable declarations. As a user, you normally do not need it directly, except for scoping types and variables to it.

Header file: binio.h

Public methods:

binio()

The constructor.

~binio()

The destructor.

void setFlag(Flag f, bool set = true)

Is used to set or erase flags to change the behaviour of the stream. Available flags and their meaning are listed in the types table for this class, below. The optional argument set is used to set or erase the specified flag. If it is not specified, it defaults to true, setting (activating) the specified flag.

bool getFlag(Flag f)

Returns whether the specified flag is set (active) or not. Refer to setFlag, above, for more information.

Error error()

Returns the current error status of the stream. A status of no error is always indicated with a value of 0, as to allow easy error checks with a simple if construct.

bool eof()

Returns true if the last access to the stream was unsuccessful because the stream pointer was already past the end of the stream. false is returned otherwise. Synonymous to checking if the return value of a call to error() sets the Eof error code flag.

virtual void seek(long, Offset = Set)

Abstract virtual method for seeking into streams. Implemented by the stream layer. The first argument specifies the relative position to seek to. Use a negative value to seek backwards. The optional second argument specifies from where to start seeking. Set specifies the beginning of a stream, Add specifies the current position and End specifies the end of the stream. If it is omitted, it defaults to Set, seeking from the beginning of the stream.

virtual long pos()

Abstract virtual method that returns the current position inside the stream. Implemented by the stream layer.

Protected methods:

Float pow(Float base, signed int exp)

Is a stripped-down version of the pow() function from the math.h standard C math library include file. It is used during conversion between floating-point formats and can calculate powers of a floating-point base argument, using a signed integer exponent.

Public data types and variables:

enum Flag

Enumeration of all defined stream flags that can be set using the setFlag() and getFlag() methods. This type defines the following values:

BigEndian

If set, sets the stream's byte-ordering to big endian notation. Otherwise, little endian notation is used.

FloatIEEE

If set, all floating-point access to the stream will assume IEEE-754 standardized floating-point numbers. Only this type of data is expected from and written to the stream.

If your architecture does not support IEEE-754 floating-point numbers, the value will be converted. Various conversion errors can occur and sometimes the conversion is not possible at all. In this case, the Unsupported error is issued and a specific value is returned. The following table summarizes all possible return codes for certain problematic values:

Real value	Return value
Infinity	1.0
-Infinity	-1.0
Not a Number (NaN)	0.0

Both positive and negative zero (0) are mapped to the same zero value, if your architecture does not support both positive and negative zeroes. There is no way to distinguish between the two values in this case.

enum ErrorCode

Enumeration of all possible error values. This type defines the following values:

NoError

No error at all. This is always mapped to an integer value of 0.

Fatal

An unspecified, fatal error occured. This error is issued only if something really strange happened (i.e. on internal logic errors in the library, or if something else, undefined happens, etc.). It is advised to immediately terminate any binary stream I/O activity and fail with an error message to the application user, maybe even terminate the application completely.

Unsupported

You tried to access stream data in an unsupported way. This error is issued whenever an (explicit or implicit) conversion between two types of data storage is requested, that isn't supported by libbinio yet.

NotOpen

The stream you tried to access is not open yet.

Denied

Access to this stream is denied. This error is normally issued when you try to open a file on a filesystem, but you have insufficient rights to access it.

NotFound

The stream you tried to access was not found. This is mostly issued on a file not found error, when accessing normal files on a filesystem.

Eof

The end of the stream has been passed. Issued when you tried to read past the last byte of a stream.

enum Offset

Specifies the position inside a stream, from where a seek is started with the seek() method. This type defines the following values:

Set

Start seeking at the beginning of the stream.

Add

Start seeking from the current position in the stream.

End

Start seeking from the end of the stream.

enum FType

Specifies what type of floating-point number is to be accessed next, using the readFloat() or writeFloat() methods. Most floating-point formats specify multiple data types to support a broader range of precision. libbinio generalizes the idea by categorizing them only into single and double precision numbers. This type defines the following values:

Single

Access a single precision floating-point number.

Double

Access a double precision floating-point number.

int Error

This integer holds a bit field of all error values for a stream. Returned by error(). A status of "no error" is always indicated when the whole field is set to 0 (zero), i.e. the integer is 0. Test for an error by binary or'ing this integer with one of the error values from ErrorCode.

Protected data types and variables:

Int

The largest integer type supported by the architecture.

Float

The largest floating-point type supported by the architecture.

Byte

This type is always one byte (8 bits) wide.

Flags

Type to hold a flag variable, containing the status of all flags of a stream.

Flags my_flags

This variable holds the current status of all flags for the stream.

static const Flags system_flags

This variable holds the status of the flags, defining the standard behaviour of the system. This is determined once at runtime, at startup of the library.

Error err

This variable holds the error status of a stream.