The Binary_IO class provides input and output of binary data values. More...

#include <Binary_IO.hh>

Inheritance diagram for PIRL::Binary_IO:

Public Types
enum	Data_Order { MSB, LSB }
	External data order selection. More...
typedef std::istream &(*	Reader )(std::istream &, char *, unsigned long)
typedef std::ostream &(*	Writer )(std::ostream &, const char *, unsigned long)
typedef Data_Binder< Binary_IO >	Binder
Public Member Functions
	Binary_IO (bool reverse=false)
	Construct a Binary_IO object based on data reversal specification.
	Binary_IO (Data_Order data_order)
	Construct a Binary_IO object based on the external data order.
bool	reversed () const
	Tests if data is reversed during I/O.
Binary_IO &	reversed (bool reverse)
	Sets the data reversal mode.
Data_Order	IO ()
	Gets the external data ordering.
Binary_IO &	IO (Data_Order data_order)
	Sets the external data ordering.
template<typename T >
Binder	operator() (T &value) const
	Functor that binds a data value to this Binary_IO.
template<typename T >
Binary_IO &	get (std::istream &stream, T &value)
	Input from a stream to a value of any type.
template<typename T >
Binary_IO &	put (std::ostream &stream, T &value)
	Output to a stream from a value of any type.
template<typename T >
Binary_IO &	get (std::istream &stream, T *value, unsigned int amount)
	Input from a stream to an array of values of any type.
template<typename T >
Binary_IO &	put (std::ostream &stream, T *value, unsigned int amount)
	Output to a stream from an array of values of any type.
Binary_IO &	get_3 (std::istream &stream, int &value)
	Input of 3 binary bytes to LSBs of an integer value.
Binary_IO &	put_3 (std::ostream &stream, const int &value)
	Output of 3 binary bytes from LSBs of an integer value.
Public Attributes
Reader	read
	Reads some amount of data bytes into an address from a stream.
Writer	write
	Writes some amount of data bytes from an address into a stream.
Static Public Attributes
static const char *	ID = "PIRL::Binary_IO ($Revision: 1.2 $ $Date: 2005/01/22 01:37:06 $)"
	Class identification name with source code version and date.
Static Protected Member Functions
static std::istream &	read_forwards (std::istream &stream, char *data, unsigned long amount)
	Reads some amount of data bytes into an address from a stream.
static std::istream &	read_backwards (std::istream &stream, char *data, unsigned long amount)
	Reads some amount of data bytes into an address from a stream.
static std::ostream &	write_forwards (std::ostream &stream, const char *data, unsigned long amount)
	Writes some amount of data bytes from an address into a stream.
static std::ostream &	write_backwards (std::ostream &stream, const char *data, unsigned long amount)
	Writes some amount of data bytes from an address into a stream.

Detailed Description

The Binary_IO class provides input and output of binary data values.

The data may optionally be reversed to handle byte ordering differences between the host system that writes the binary data and the host system that reads it.

A stream manipulator interface is provided. This provides an operator() method that takes an argument of any type (for which a reference can be provided) and returns a Binder, and the external operator<< and operator>> functions that take an ostream or istream, repsectively, and a Binder. For example:

ofstream output (filename, ios::out | ios::binary); Binary_IO binary (REVERSED); int number = 42; output << binary (number);

This will write the binary value of the int number to the stream with the bytes of the value reversed. On a low-endian host this will result in MSB-ordered output data.

Note: The argument of the manipulator must be a referencable variable, not a literal constant (use a temporary variable for constant output). Also, because the manipulator does not know about the structure of complex objects, only primitive data types should be reversed during I/O (use a Data_Block to define complex binary structures that can be properly reordered during I/O).

The get and put methods, which are used by the input and output operator methods from the bound manipulator, may be used directly. Their advantage over direct use of the ostream.read or istream.write methods is that they correctly handle data input reversing and non-destructive output data reversing depending on the Binary_IO object Reversed mode.

Author:: Bradford Castalia, UA/PIRL, 12/03

Revision:: 1.17

Member Typedef Documentation

typedef std::istream&(* PIRL::Binary_IO::Reader)(std::istream &, char *, unsigned long)

typedef std::ostream&(* PIRL::Binary_IO::Writer)(std::ostream &, const char *, unsigned long)

typedef Data_Binder<Binary_IO> PIRL::Binary_IO::Binder

Member Enumeration Documentation

enum PIRL::Binary_IO::Data_Order

External data order selection.

Enumerator:

MSB
LSB

Constructor & Destructor Documentation

PIRL::Binary_IO::Binary_IO ( bool reverse = false ) [inline, explicit]

Construct a Binary_IO object based on data reversal specification.

Parameters:

reverse true if data is to be reversed on IO; false otherwise.

References reversed().

PIRL::Binary_IO::Binary_IO ( Data_Order data_order ) [inline, explicit]

Construct a Binary_IO object based on the external data order.

Parameters:

data_order A Data_Order value of either MSB or LSB.

References IO().

Member Function Documentation

bool PIRL::Binary_IO::reversed ( ) const [inline]

Tests if data is reversed during I/O.

Returns:: true if the data is reversed; false otherwise.

Referenced by Binary_IO(), and IO().

Binary_IO& PIRL::Binary_IO::reversed ( bool reverse ) [inline]

Sets the data reversal mode.

Parameters:

reverse true if the data is to be reversed; false otherwise.

References read, read_backwards(), read_forwards(), write, write_backwards(), and write_forwards().

Data_Order PIRL::Binary_IO::IO ( ) [inline]

Gets the external data ordering.

Returns:: A Data_Order value of either MSB or LSB.

References PIRL::high_endian_host(), PIRL::low_endian_host(), LSB, and MSB.

Referenced by Binary_IO().

Binary_IO& PIRL::Binary_IO::IO ( Data_Order data_order ) [inline]

Sets the external data ordering.

Parameters:

data_order A Data_Order value of either MSB or LSB.

References PIRL::high_endian_host(), PIRL::low_endian_host(), MSB, and reversed().

template<typename T >

Binder PIRL::Binary_IO::operator() ( T & value ) const [inline]

Functor that binds a data value to this Binary_IO.

Parameters:

value A reference to a data value of arbitrary type.

Returns:: The Binder object that contains a reference to this Binary_IO object and the data's address and amount.

See also:: Data_Binder

template<typename T >

Binary_IO& PIRL::Binary_IO::get	(	std::istream &	stream,
		T &	value
	)		`[inline]`

Input from a stream to a value of any type.

References read.

template<typename T >

Binary_IO& PIRL::Binary_IO::put	(	std::ostream &	stream,
		T &	value
	)		`[inline]`

Output to a stream from a value of any type.

References write.

template<typename T >

Binary_IO& PIRL::Binary_IO::get	(	std::istream &	stream,
		T *	value,
		unsigned int	amount
	)		`[inline]`

Input from a stream to an array of values of any type.

References read.

template<typename T >

Binary_IO& PIRL::Binary_IO::put	(	std::ostream &	stream,
		T *	value,
		unsigned int	amount
	)		`[inline]`

Output to a stream from an array of values of any type.

References write.

Binary_IO& PIRL::Binary_IO::get_3	(	std::istream &	stream,
		int &	value
	)		`[inline]`

Input of 3 binary bytes to LSBs of an integer value.

References PIRL::high_endian_host(), and read.

Binary_IO& PIRL::Binary_IO::put_3	(	std::ostream &	stream,
		const int &	value
	)		`[inline]`

Output of 3 binary bytes from LSBs of an integer value.

References PIRL::high_endian_host(), and write.

static std::istream& PIRL::Binary_IO::read_forwards	(	std::istream &	stream,
		char *	data,
		unsigned long	amount
	)		`[inline, static, protected]`

Reads some amount of data bytes into an address from a stream.

The data is read in forwards (native) order.

Parameters:

stream	The istream from which to read bytes.
data	The address (char*) to receive the data bytes.
amount	The number of data bytes to be read.

Returns:: The stream.

Referenced by reversed().

static std::istream& PIRL::Binary_IO::read_backwards	(	std::istream &	stream,
		char *	data,
		unsigned long	amount
	)		`[inline, static, protected]`

Reads some amount of data bytes into an address from a stream.

The data is read in reverse order.

Parameters:

stream	The istream from which to read bytes.
data	The address (char*) to receive the data bytes.
amount	The number of data bytes to be read.

Returns:: The stream.

Referenced by reversed().

static std::ostream& PIRL::Binary_IO::write_forwards	(	std::ostream &	stream,
		const char *	data,
		unsigned long	amount
	)		`[inline, static, protected]`

Writes some amount of data bytes from an address into a stream.

The data is written in forward (native) order.

Parameters:

stream	The ostream into which to write bytes.
data	The address (char*) from which to get the data bytes.
amount	The number of data bytes to be written.

Returns:: The stream.

Referenced by reversed().

static std::ostream& PIRL::Binary_IO::write_backwards	(	std::ostream &	stream,
		const char *	data,
		unsigned long	amount
	)		`[inline, static, protected]`

Writes some amount of data bytes from an address into a stream.

The data is written in backwards (reverse) order.

Parameters:

stream	The ostream into which to write bytes.
data	The address (char*) from which to get the data bytes.
amount	The number of data bytes to be written.

Returns:: The stream.

Referenced by reversed().

Member Data Documentation

const char * PIRL::Binary_IO::ID = "PIRL::Binary_IO ($Revision: 1.2 $ $Date: 2005/01/22 01:37:06 $)" [static]

Class identification name with source code version and date.

Reader PIRL::Binary_IO::read

Reads some amount of data bytes into an address from a stream.

The data is read in the correct order.

Parameters:

stream	The istream from which to read bytes.
data	The address (char*) to receive the data bytes.
amount	The number of data bytes to be read.

Returns:: The stream.

Referenced by PIRL::Binary_Input::get(), get(), get_3(), and reversed().

Writer PIRL::Binary_IO::write

Writes some amount of data bytes from an address into a stream.

The data is written in the correct order.

Parameters:

stream	The ostream into which to write bytes.
data	The address (char*) from which to get the data bytes.
amount	The number of data bytes to be written.

Returns:: The stream.

Referenced by PIRL::Binary_Output::put(), put(), put_3(), and reversed().

The documentation for this class was generated from the following files:

PIRL::Binary_IO Class Reference

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Static Protected Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation