PIRL  PIRL++

Public Types | Public Member Functions | Public Attributes | Static Public Attributes | Static Protected Member Functions

PIRL::Binary_IO Class Reference

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

#include <Binary_IO.hh>

Inheritance diagram for PIRL::Binary_IO:
Inheritance graph
[legend]

List of all members.

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_IOBinder

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_IOreversed (bool reverse)
 Sets the data reversal mode.
Data_Order IO ()
 Gets the external data ordering.
Binary_IOIO (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_IOget (std::istream &stream, T &value)
 Input from a stream to a value of any type.
template<typename T >
Binary_IOput (std::ostream &stream, T &value)
 Output to a stream from a value of any type.
template<typename T >
Binary_IOget (std::istream &stream, T *value, unsigned int amount)
 Input from a stream to an array of values of any type.
template<typename T >
Binary_IOput (std::ostream &stream, T *value, unsigned int amount)
 Output to a stream from an array of values of any type.
Binary_IOget_3 (std::istream &stream, int &value)
 Input of 3 binary bytes to LSBs of an integer value.
Binary_IOput_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)

Member Enumeration Documentation

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:
reversetrue 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_orderA 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:
reversetrue 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_orderA 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:
valueA 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:
streamThe istream from which to read bytes.
dataThe address (char*) to receive the data bytes.
amountThe 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:
streamThe istream from which to read bytes.
dataThe address (char*) to receive the data bytes.
amountThe 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:
streamThe ostream into which to write bytes.
dataThe address (char*) from which to get the data bytes.
amountThe 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:
streamThe ostream into which to write bytes.
dataThe address (char*) from which to get the data bytes.
amountThe 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.

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

The data is read in the correct order.

Parameters:
streamThe istream from which to read bytes.
dataThe address (char*) to receive the data bytes.
amountThe number of data bytes to be read.
Returns:
The stream.

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

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

The data is written in the correct order.

Parameters:
streamThe ostream into which to write bytes.
dataThe address (char*) from which to get the data bytes.
amountThe 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: