libcommonc++  0.7
DataEncoder Class Referenceabstract

An abstract class with basic functionality that is common to all data decoders (readers) and data encoders (writers). More...

#include <DataEncoder.h++>

Inheritance diagram for DataEncoder:

Classes

class  Align
 A manipulator that skips past enough bytes to re-align the data stream at a specified boundary. More...
 
struct  Context
 A DataEncoder context. More...
 
class  Manipulator
 A base class for DataEncoder manipulators. More...
 
class  ScopedContext
 A lexically scoped DataEncoder context. More...
 
class  SetEndianness
 A manipulator that specifies the endianness of integer values to be subsequently encoded/decoded. More...
 
class  SetLength
 A manipulator that specifies the length of String, Blob, and array values to be subsequently encoded/decoded. More...
 
class  SetLimit
 A manipulator that specifies the maximum number of bytes that can be read/written. More...
 
class  Skip
 A manipulator that skips past bytes in the stream. More...
 

Public Member Functions

virtual void reset ()
 Reset the encoder. More...
 
void pushContext ()
 Push a new encoder context. More...
 
void popContext ()
 Pop the active encoder context. More...
 
bool isTopContext () const
 Determine if the active context is the topmost (and only) context. More...
 
uint_t getContextDepth () const
 Get the current context depth. More...
 
void setEndianness (Endianness endianness)
 Specify the byte-endianness for reading/writing primitive integer types in the active context. More...
 
Endianness getEndianness () const
 Get the byte-endianness in the active context. More...
 
void setLength (size_t length)
 Specify the length of String, Blob, and array values for subsequent reading/writing in the active context. More...
 
size_t getLength () const
 Get the current length for string values. More...
 
void setLimit (int64_t limit)
 Specify the maximum number of bytes that can be read/written in the active context. More...
 
int64_t getLimit () const
 Get the current limit. More...
 
int64_t getOffset () const
 Get the current encoding/decoding offset. More...
 
virtual void setOffset (int64_t offset)=0
 Set the current reading/writing offset. More...
 
int64_t getCumulativeOffset () const
 Get the cumulative reading/writing offset. More...
 
int64_t getRemaining () const
 Get the number of bytes between the current offset and the limit, i.e., the number of bytes remaining to be read or written. More...
 
void align (size_t size)
 Skip past enough bytes to re-align the data stream at a specified boundary. More...
 
virtual void skip (size_t count)=0
 Skip past the given number of bytes in the data stream. More...
 
virtual ~DataEncoder ()
 Destructor. More...
 

Protected Member Functions

 DataEncoder ()
 Constructor. More...
 
bool isSameEndianness () const
 Test if the endianness of the encoder is the same as the endianness of the host system. More...
 
ContextcurrentContext ()
 Get a reference to the current context. More...
 
const ContextcurrentContext () const
 Get a reference to the current context. More...
 
void checkRemaining (const Context &ctx, size_t count) const
 Check if at least the given number of bytes are available to be read or written. More...
 

Detailed Description

An abstract class with basic functionality that is common to all data decoders (readers) and data encoders (writers).

A DataEncoder operates on an input source or an output destination, such as a stream or buffer. Subclasses provide specific input/output functionality, such as reading and writing primitive data types.

The class supports nested encoding contexts. Initially, there is a top-level context, which represents the entire range of bytes being read or written. A nested context represents a sub-range of bytes within its parent context. Each context has an offset and a limit; the offset is the position, relative to the beginning of the context, of the next byte to be read or written, and the limit is the maximum offset within the context beyond which further reading or writing is not allowed.

A new context is created by calling pushContext(). The new context inherits the encoder attributes—such as byte endianness, and value length—of its parent context, and its offset is initially 0. It represents the range of bytes between the parent context's current offset and limit.

A context is destroyed by calling popContext(). The parent context then becomes the current context, and its offset is incremented by the offset of the popped context.

Though data is typically read or written sequentially, random access is also possible. The offset in the current context can be changed insofar as it remains within the bounds of that context. When reading, the offset can be set to any value between 0 and the current context's limit. When writing, the offset can be set to any value between 0 and the maximum offset to which data has already been written within the current context.

Nested contexts can be used to implement an encoder that reads or writes hierarchical data structures, such as "chunks" in a RIFF file.

Author
Mark Lindner

Constructor & Destructor Documentation

◆ ~DataEncoder()

~DataEncoder ( )
virtual

Destructor.

◆ DataEncoder()

DataEncoder ( )
protected

Constructor.

Member Function Documentation

◆ align()

void align ( size_t  size)

Skip past enough bytes to re-align the data stream at a specified boundary.

When reading, the bytes are simply skipped over; when writing, the bytes are filled with NULs.

Parameters
sizeThe alignment size. Typical values include 2, 4, or 8. Other values are allowed but are of limited usefulness.
Exceptions
IOExceptionIf an I/O error occurs.

◆ checkRemaining()

void checkRemaining ( const Context ctx,
size_t  count 
) const
protected

Check if at least the given number of bytes are available to be read or written.

Parameters
ctxThe context to check.
countThe number of bytes.
Exceptions
IOExceptionIf there are not enough bytes remaining.

◆ currentContext() [1/2]

DataEncoder::Context & currentContext ( )
protected

Get a reference to the current context.

◆ currentContext() [2/2]

const DataEncoder::Context & currentContext ( ) const
protected

Get a reference to the current context.

◆ getContextDepth()

uint_t getContextDepth ( ) const

Get the current context depth.

◆ getCumulativeOffset()

int64_t getCumulativeOffset ( ) const

Get the cumulative reading/writing offset.

This is a sum of the offsets across all contexts.

◆ getEndianness()

Endianness getEndianness ( ) const

Get the byte-endianness in the active context.

◆ getLength()

size_t getLength ( ) const

Get the current length for string values.

◆ getLimit()

int64_t getLimit ( ) const

Get the current limit.

◆ getOffset()

int64_t getOffset ( ) const

Get the current encoding/decoding offset.

◆ getRemaining()

int64_t getRemaining ( ) const

Get the number of bytes between the current offset and the limit, i.e., the number of bytes remaining to be read or written.

◆ isSameEndianness()

bool isSameEndianness ( ) const
protected

Test if the endianness of the encoder is the same as the endianness of the host system.

◆ isTopContext()

bool isTopContext ( ) const

Determine if the active context is the topmost (and only) context.

◆ popContext()

void popContext ( )

Pop the active encoder context.

The previous context becomes the active context, and the offset in the current context is incremented by the offset of the popped context.

◆ pushContext()

void pushContext ( )

Push a new encoder context.

◆ reset()

void reset ( )
virtual

Reset the encoder.

Discards all but the topmost context, and resets the topmost context to default values.

Exceptions
IOExceptionIf an I/O error occurs.

Reimplemented in ByteArrayDataWriter, CircularByteBufferDataWriter, ByteBufferDataWriter, CircularByteBufferDataReader, StreamDataReader, ByteArrayDataReader, and ByteBufferDataReader.

◆ setEndianness()

void setEndianness ( Endianness  endianness)

Specify the byte-endianness for reading/writing primitive integer types in the active context.

◆ setLength()

void setLength ( size_t  length)

Specify the length of String, Blob, and array values for subsequent reading/writing in the active context.

◆ setLimit()

void setLimit ( int64_t  limit)

Specify the maximum number of bytes that can be read/written in the active context.

Attempts to read/write past this limit will raise an IOException.

Exceptions
IOExceptionIf an I/O error occurs.

◆ setOffset()

virtual void setOffset ( int64_t  offset)
pure virtual

◆ skip()

virtual void skip ( size_t  count)
pure virtual

Skip past the given number of bytes in the data stream.

When reading, the bytes are simply skipped over; when writing, the bytes are filled with NULs.

Parameters
countThe number of bytes to skip.
Exceptions
IOExceptionIf an I/O error occurs.

Implemented in StreamDataWriter, ByteArrayDataWriter, CircularByteBufferDataReader, StreamDataReader, ByteArrayDataReader, ByteBufferDataReader, ByteBufferDataWriter, and DataWriter.


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