Overview

Stream is an abstraction that represents a device on which input and output operations are performed. A stream can basically be represented as a source or destination of characters.

The STL iostream library provides general streams that are associated to a physical source or destination of characters, like a disk file, the keyboard, or the console. The characters gotten or written from/to the abstraction called stream are physically input/output to the physical device. (see http://www.cplusplus.com/reference/iostream/)

Beside the STL streams, MIRA provides additional streams that are useful for different occasions.

BufferStream

The BufferStream can be used as a replacement to the STL std::stringstream. It provides better flexibility when accessing the underlying data buffer and has a better performance compared to std::stringstream.

The BufferStream can be used as any other STL stream via its implemented << and >> operators.

Example:

// create a buffer for the stream
Buffer<char> buffer;
// create the stream that operates on 'buffer'
BufferStream stream(buffer);
// write something into the stream
stream << "This is a test: " << 1234 << ", " << 12.34f;
// read from stream
std::string s;
stream >> s;

BinaryStream

Usually, streams like all the STL streams operate with text or ASCII data. Numbers for example are always stored using their textual representation. In contrast to those text streams, MIRA Streams provide a BinaryIstream and a BinaryOstream class. Both are able to take binary data. Instead of the text streams, these binary streams store the data directly using the binary representation. A float number e.g. is stored using its 4 bytes also representing the number in memory.

The BinaryIstream / BinaryOstream classes come in two different flavors:

BinaryStlIstream / BinaryStlOstream: These two classes can be wrapped around another STL stream. This allows to store/read data in binary format to/from existing (text) streams.
BinaryBufferIstream / BinaryBufferOstream: These two classes use a Buffer to write/read the data. This bypasses the STL stream mechanism and achieves a performance that is about 10 times faster than using the BinaryStream with STL streams. Hence, you should use this kind of Binary Stream whenever possible.

Example for using a Binary Stream wrapped around an STL stream:

// open a file for writing
ofstream ofs("myfile.bin");
// create binary stream and attach it to file stream (wrap ofstream)
BinaryStlOstream os(ofs); 
// write binary data to the stream using the stream operator <<
int a = 4;
os << a;
char c = 'A';
os << 1.234f << c;
os << "This is a string";

Example for using a Binary Stream that operates directly on a Buffer for best performance:

// the buffer the binary ostream will operate on
Buffer<uint8> buffer;
// create the binary stream and attach it directly to the buffer
BinaryBufferOstream os(&buffer);
// write binary data to the stream using the stream operator <<
int a = 4;
os << a;

Binary data is usually stored in the byte order of the host machine. However, if you want to share the data with other machines, you can change the byte order to network byte order (Big Endian). Switching between host and network byte order is done using the net and host manipulators:

uint32 x = 0x12345F;
os << net << x; // write x in network byte order (Big Endian)
os << host;     // set stream back to host byte order

GZip Compression Streams

Data in streams can also be compressed using the ogzstream and igzstream classes. They are part of the Gzstream Library (http://www.cs.unc.edu/Research/compgeom/gzstream/) written by Deepak Bandyopadhyay and Lutz Kettner.

Both classes can be used instead of std::ofstream and std::ifstream and will compress/decompress the data that is written to or read from the streams on the fly.

Example:

// create output file stream with compression
ogzstream os("myfile.dat")
os << "Data written to this stream will be compressed on the fly.";
...
// create input file stream with compression
igzstream is("myfile.dat")
std::string s;
is >> s;

The igzstream input stream class also handles uncompressed files.

Contents

Overview

BufferStream

BinaryStream

GZip Compression Streams