Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members

ustl::istream Class Reference
[Binary Streams]

Helper class to read packed binary streams. More...

#include <ustl.h>

Inheritance diagram for ustl::istream:

ustl::cmemlink ustl::istringstream ustl::fdistringstream List of all members.

Public Member Functions

 istream (void)
 Constructs a stream attached to nothing. A stream attached to nothing is not usable. Call Link() functions inherited from cmemlink to attach to some memory block.
 istream (const void *p, size_type n)
 Attaches the stream to a block at p of size n.
 istream (const cmemlink &source)
 Attaches to the block pointed to by source.
 istream (const ostream &source)
 Attaches to the block pointed to by source of size source.pos().
void link (const void *p, size_type n)
 Attaches the object to pointer p of size n.
void link (const cmemlink &l)
 Links to l.
void link (const void *f, const void *l)
 Links to iterator range first - last.
virtual void unlink (void)
 Links to p of size n.
void seek (uoff_t newPos)
 Sets the current read position to newPos.
void seek (const_iterator newPos)
 Sets the current read position to newPos.
void skip (size_type nBytes)
 skips nBytes without reading anything.
uoff_t pos (void) const
 Returns the current read position.
const_iterator ipos (void) const
 Returns the current read position.
size_type remaining (void) const
 Returns the number of bytes remaining in the input buffer.
bool aligned (size_type grain=c_DefaultAlignment) const
 Returns true if the read position is aligned on grain.
size_type align_size (size_type grain=c_DefaultAlignment) const
 Returns the number of bytes to skip to be aligned on grain.
void align (size_type grain=c_DefaultAlignment)
 aligns the read position on grain
void swap (istream &is)
 Swaps contents with is.
void read (void *buffer, size_type size)
 Reads n bytes into buffer.
void read (memlink &buf)
 Reads buf.size() bytes into buf.
void read_strz (string &str)
 Reads a null-terminated string into str.
void read (istream &is)
 No reading into an input stream allowed, so this is a NOP.
void write (ostream &is) const
 Writes all unread bytes into os.
size_t stream_size (void) const
 Returns number of unread bytes.
template<typename T>
void iread (T &v)
 Reads type T from the stream via a direct pointer cast.

Detailed Description

Helper class to read packed binary streams.

This class contains a set of functions to read integral types from an unstructured memory block. Unpacking binary file data can be done this way, for instance. aligning the data is your responsibility, and can be accomplished by proper ordering of reads and by calling the align() function. Unaligned access is usually slower by orders of magnitude and, on some architectures, such as PowerPC, can cause your program to crash. Therefore, all read functions have asserts to check alignment. Overreading the end of the stream will also cause a crash (an assert in debug builds). Oh, and don't be intimidated by the size of the inlines here. In the assembly code the compiler will usually chop everything down to five instructions each.

Alignment rules for your objects:

Example code:
        memblock b;
        int br = read (fd, b, b.size());
        b.resize (br);
        ostream is (b);
        is >> boolVar;
        is.align (sizeof(int));
        is >> intVar >> floatVar;
        is.read (binaryData, binaryDataSize);
        is.align ();
        // Assuming the input is written by code in mostream.h
        assert (is.pos() == b.size()); 


Member Function Documentation

void ustl::istream::link const void *  p,
size_type  n
[inline]
 

Attaches the object to pointer p of size n.

If p is NULL and n is non-zero, bad_alloc is thrown and current state remains unchanged.

Reimplemented from ustl::cmemlink.


The documentation for this class was generated from the following files:
Generated on Mon Jan 17 14:35:02 2005 for uSTL by 1.3.9 Doxygen Hosted on SourceForge.net