code::BOIStream Class Reference

Inheritance diagram for code::BOIStream:

List of all members.

---

Detailed Description

An input stream that lets you deserialize data from a byte-swapped character array received from a persistent store.

BOOStreams are somewhat more flexible in that

• They can be passed around to different functions that work together to break up a message.
• The &gt&gt operator is typesafe, so the format list in ByteOrderIO is unnecessary
• Support can be added for non-builtin types (such as stl std::strings)

Example:

 char* pch = CharBufferFromSomewhere ( );
 BOIStream in ( pch );
 in >> id >> ch >> iVal >> lVal;
 

Author:

: Charles Kerr, Lakshman

Version:

:

Id

code_BOStream.h,v 1.15 2009/06/02 20:17:39 lakshman Exp

Public Member Functions
	BOIStream (const Buffer &buf, bool fileIsLittleEndian=true)
	Create a BOIStream from a buffer.
	BOIStream (bool fileIsLittleEndian=true)
	Create an empty BOIStream.
void	setBuffer (const Buffer &buf)
	Set the buffer that the IStream will pull data from.
Buffer	getRemainingBuffer () const
	Returns a separate copy of the buffer that hasn't yet been pulled out.
size_t	getRemainingByteQty () const
	Returns the remaining number of unread bytes in this stream.
int	getReadPosition () const
	Returns the current read pointer position.
void	moveReadPointer (int num_bytes) throw (std::string)
	Moves the read pointer position N bytes from current position.
void	setReadPosition (int new_value) throw (std::string)
	Moves the read pointer position to this new absolute position.
bool	isValid (std::string *setme_error_text=0) const
	Returns true if the object passes its internal sanity checks, false otherwise.
virtual BOIStream &	operator>> (char &c) throw (std::string)
	Read a char from the stream, throwing an error message on failure.
virtual BOIStream &	operator>> (unsigned char &c) throw (std::string)
	Read an unsigned char from the stream, throwing an error message on failure.
virtual BOIStream &	operator>> (int16_t &i) throw (std::string)
	Read a 16-bit signed integer from the stream, throwing an error message on failure.
virtual BOIStream &	operator>> (uint16_t &i) throw (std::string)
	Read a 16-bit unsigned integer from the stream, throwing an error message on failure.
virtual BOIStream &	operator>> (int32_t &i) throw (std::string)
	Read a 32-bit signed integer from the stream, throwing an error message on failure.
virtual BOIStream &	operator>> (uint32_t &i) throw (std::string)
	Read a 32-bit unsigned integer from the stream, throwing an error message on failure.
virtual BOIStream &	operator>> (int64_t &i) throw (std::string)
	Read a 64-bit signed integer from the stream, throwing an error message on failure.
virtual BOIStream &	operator>> (uint64_t &i) throw (std::string)
	Read a 64-bit unsigned integer from the stream, throwing an error message on failure.
virtual BOIStream &	operator>> (bool &b) throw (std::string)
	Read a bool from the stream, throwing an error message on failure.
virtual BOIStream &	operator>> (std::string &) throw (std::string)
	Read a string from the stream, throwing an error message on failure.
virtual BOIStream &	operator>> (float &f) throw (std::string)
	Read a float from the stream, throwing an error message on failure.
virtual BOIStream &	operator>> (double &d) throw (std::string)
	Read a double from the stream, throwing an error message on failure.
Protected Member Functions
void	getBytes (char *ptr, int byte_qty) throw ( std::string )
	Get bytes from the buffer, swap them as necessary, and store the value in ptr.
template<typename X>
BOIStream &	extract (X &x) throw (std::string)
Protected Attributes
bool	_fileOrder
Buffer	_buf
int	_readpos

---

Constructor & Destructor Documentation

code::BOIStream::BOIStream	(	const Buffer &	buf,
		bool	fileIsLittleEndian = true
	)			[inline]

Create a BOIStream from a buffer.

BOIStream uses the same copy of the buffer as is passed in; so either make a clone() before passing in or don't change the buffer.

Parameters:

Pass

in the buffer to pull data from.

code::BOIStream::BOIStream

(

bool

fileIsLittleEndian = true

)

[inline]

Create an empty BOIStream.

Usually, you will then use setBuffer() to set the buffer to extract from.

---

Member Function Documentation

template<typename X>

BOIStream& code::BOIStream::extract

(

X &

x

)

throw (std::string) [inline, protected]

void code::BOIStream::getBytes	(	char *	ptr,
		int	byte_qty
	)			throw ( std::string ) [protected]

Get bytes from the buffer, swap them as necessary, and store the value in ptr.

Parameters:

	ptr	the place to write the swapped bytes
	byte_qty	the number of bytes to pull from the buffer

Exceptions:

descriptive_error_string

int code::BOIStream::getReadPosition

(

)

const [inline]

Returns the current read pointer position.

Buffer code::BOIStream::getRemainingBuffer

(

)

const [inline]

Returns a separate copy of the buffer that hasn't yet been pulled out.

Returns:

a separate of the buffer that hasn't yet been pulled out.

size_t code::BOIStream::getRemainingByteQty

(

)

const [inline]

Returns the remaining number of unread bytes in this stream.

Returns:

the remaining number of unread bytes in this stream.

bool code::BOIStream::isValid

(

std::string *

setme_error_text = 0

)

const

Returns true if the object passes its internal sanity checks, false otherwise.

Returns:

true if the object passes its internal sanity checks, false otherwise.

Parameters:

setme_error_text

if not null, and if isValid fails, a description of the failure is placed here. This setup is so that isValid can still be embedded in a throwaway assert (ie, "<code>assert(isValid())</code>") and in a exception check (ie, "<code>string s; if ( !isValid(&s) ) throw s;").

void code::BOIStream::moveReadPointer

(

int

num_bytes

)

throw (std::string) [inline]

Moves the read pointer position N bytes from current position.

Pass in a negative number to move the pointer backward

virtual BOIStream& code::BOIStream::operator>>

(

double &

d

)

throw (std::string) [inline, virtual]

Read a double from the stream, throwing an error message on failure.

WARNING: doubles are not portable. If you are defining a new data format, please use int/long, multiplying your value by the needed precision. This function is for existing formats that can't be changed.

Implements code::InputStream.

virtual BOIStream& code::BOIStream::operator>>

(

float &

f

)

throw (std::string) [inline, virtual]

Read a float from the stream, throwing an error message on failure.

WARNING: floats are not portable. If you are defining a new data format, please use int/long, multiplying your value by the needed precision. This function is for existing formats that can't be changed.

Implements code::InputStream.

virtual BOIStream& code::BOIStream::operator>>

(

std::string &

)

throw (std::string) [virtual]

Read a string from the stream, throwing an error message on failure.

Implements code::InputStream.

virtual BOIStream& code::BOIStream::operator>>

(

bool &

b

)

throw (std::string) [virtual]

Read a bool from the stream, throwing an error message on failure.

Implements code::InputStream.

virtual BOIStream& code::BOIStream::operator>>

(

uint64_t &

i

)

throw (std::string) [inline, virtual]

Read a 64-bit unsigned integer from the stream, throwing an error message on failure.

Implements code::InputStream.

virtual BOIStream& code::BOIStream::operator>>

(

int64_t &

i

)

throw (std::string) [inline, virtual]

Read a 64-bit signed integer from the stream, throwing an error message on failure.

Implements code::InputStream.

virtual BOIStream& code::BOIStream::operator>>

(

uint32_t &

i

)

throw (std::string) [inline, virtual]

Read a 32-bit unsigned integer from the stream, throwing an error message on failure.

Implements code::InputStream.

virtual BOIStream& code::BOIStream::operator>>

(

int32_t &

i

)

throw (std::string) [inline, virtual]

Read a 32-bit signed integer from the stream, throwing an error message on failure.

Implements code::InputStream.

virtual BOIStream& code::BOIStream::operator>>

(

uint16_t &

i

)

throw (std::string) [inline, virtual]

Read a 16-bit unsigned integer from the stream, throwing an error message on failure.

Implements code::InputStream.

virtual BOIStream& code::BOIStream::operator>>

(

int16_t &

i

)

throw (std::string) [inline, virtual]

Read a 16-bit signed integer from the stream, throwing an error message on failure.

Implements code::InputStream.

virtual BOIStream& code::BOIStream::operator>>

(

unsigned char &

c

)

throw (std::string) [inline, virtual]

Read an unsigned char from the stream, throwing an error message on failure.

Implements code::InputStream.

virtual BOIStream& code::BOIStream::operator>>

(

char &

c

)

throw (std::string) [inline, virtual]

Read a char from the stream, throwing an error message on failure.

Implements code::InputStream.

void code::BOIStream::setBuffer

(

const Buffer &

buf

)

[inline]

Set the buffer that the IStream will pull data from.

BOIStream uses the same copy of the buffer as is passed in; so either make a clone() before passing in or don't change the buffer.

Parameters:

buf

the buffer that the IStream will pull data from.

void code::BOIStream::setReadPosition

(

int

new_value

)

throw (std::string)

Moves the read pointer position to this new absolute position.

Often, this is the value returned by getReadPosition()

---

Member Data Documentation

Buffer code::BOIStream::_buf [protected]

bool code::BOIStream::_fileOrder [protected]

int code::BOIStream::_readpos [protected]

---