Arxx::Buffer

Arxx::Buffer Class Reference

#include <Buffer.h>

Inheritance diagram for Arxx::Buffer:

[legend]Collaboration diagram for Arxx::Buffer:

[legend]List of all members.

Detailed Description

The core class of the Buffer.

This class provides the concept of nested buffers. That means: you create one main buffer and it will behave like any other ordinary buffer you know. It is autoresizing as you add data, it provides prepend and append function, it has a position pointer which can be placed anywhere in the buffer to allow appending to that particular position.

Additionally to that the nested buffers allow you to create compositions of buffers all acting on the same data block.

Imagine a buffer of the size 16 bytes (name: Superior). Although this data may be handled as one entity, you, as the user of the Buffers library, know the semantics of this buffer: It may actually be three entities of data:

a 7-byte long block
a 5-byte long block
a 4-byte long block

Suppose now, that there is a library which (in any way) allows handling of a certain kind of data blocks. In our example it may be the first block of length 7. What you have to do is pass the buffer to the library, but this will violate the information hiding principle since this library now has access to the other datablock as well, maybe not even realizing that it isn't meant to meddle with them.

Here comes the Buffers library which allows you to create sub buffers of our Superior buffer. By creating a buffer via Buffer(Superior, 0, 7) you get a sub buffer with length 7 and I/O position at 0 which you may pass to the library. The content of this sub buffer is a reference to the superior buffer and thus contains exactly what is in the superior buffer from 0 to 7 at any given time. Now the library is only able to access the content it is meant to see.

But this concept strives for more functionality. So it is also possible to perform any operations like appending, inserting and deleting. Using these operations will affect the content of the superior buffer but the effect will be limited to the region of the sub buffer. Any increases of the size of the sub buffer will also expand the superior buffer by the same amount.

The concept of buffers doesn't end at the first level of depth. They allow you to nest sub buffers in sub buffers, thus creating a buffer structure of arbitrary depth and complexity.

For that reason all operations that work on the buffer have to be implemented recursively. If you change a portion of data in a sub buffer, that change has to be propagated to the most superior buffer, which actually owns the associated memory. Only this sup buffer is allowed to change the content of the memory and in turn it has to ensure that the effect of any such change will be passed down to the leaf childs.

Public Types

typedef unsigned char value_type

The type of an element stored in this buffer.

typedef value_type & reference

The type of a reference to an element stored in this buffer.

typedef value_type * pointer

The type of a pointer to elements stored in this buffer.

typedef const value_type const_value_type

The type of a const element stored in this buffer.

typedef const_value_type * const_pointer

The type of a const pointer to elements stored in this buffer.

typedef Arxx::u4byte size_type

The type of positions, lengths and sizes in this buffer.

Public Member Functions

Buffer (void)

The standard constructor.

Buffer (Buffer &Buffer, size_type stPosition, size_type stLength)

The sub buffer constructor.

virtual ~Buffer (void)

The destructor of a buffer. It is virtual since the Buffer may be overloaded to support external data.

size_type stGetLength (void) const

Returns the length of the buffer.

void vSetLength (size_type stLength=0)

Sets the length of the data actually in the buffer.

void vInsert (size_type stPosition, size_type stDataLength, const_pointer Data=0)

Insert a given amount of data at a specified postion.

void vDelete (size_type stPosition, size_type stLength)

Deletes a given amount of data at a specified position.

value_type operator[] (size_type stIndex) const

Allows read-only access to indexed data members for const buffers.

reference operator[] (size_type stIndex)

Allows read/write access to indexed data members.

const_pointer GetBegin (void) const

Retreives a const pointer to the data of this buffer.

Static Protected Attributes

static const size_type m_stDataUpdated = 0x01

A constant. Its value will be passed to vParentDataChanged() whenever data is to be updated.

static const size_type m_stDataDeleted = 0x02

A constant. Its value will be passed to vParentDataChanged() whenever data was deleted.

static const size_type m_stDataInserted = 0x03

A constant. Its value will be passed to vParentDataChanged() whenever data was inserted.

Private Member Functions

Buffer (const Buffer &Buffer)

made private to prevent copy creation of a Buffer.

Buffer & operator= (const Buffer &Buffer)

made private to prevent assignment copies of the Buffer.

void vRegister (Buffer &Buffer)

This function registers a buffer to be a sub buffer of this buffer.

void vUnregister (Buffer &Buffer)

This function removes a buffer from the list of all sub buffer of this buffer.

void vRegister (Arxx::Buffer::Marker &Marker) const

void vUnregister (Arxx::Buffer::Marker &Marker) const

void vWrite (Arxx::Buffer &Buffer, Arxx::Buffer::size_type stPosition, Arxx::Buffer::size_type stDataLength, Arxx::Buffer::const_pointer Data=0)

This function is responsible for any functionality that writes data to the buffer.

void vParentDataChanged (size_type stChangeMode, size_type stPosition, size_type stLength)

This function is called whenever the data of the sup buffer is changed in a way that also affects this buffer.

Private Attributes

Buffer * m_pSupBuffer

A pointer pointing to the superior buffer.

pointer m_Begin

The pointer to the actual content of this buffer.

size_type m_stLength

The length of the content within this buffer.

size_type m_stCapacity

The size of the memory block reserved for the content of this buffer.

std::set< Arxx::Buffer::Marker * > m_Markers

The associated markers.

size_type m_stPosition

The position of the begin of this buffer itside its superior buffer.

std::vector< SubBuffer * > m_SubBuffers

A vector of pointers to structures describing the sub buffers.

bool m_bChanging

Indicates the changing state of this buffer.

Friends

class Arxx::Buffer::Marker

std::string sIndentation (Arxx::Buffer *pBuffer)

Classes

class Marker

A marked position in a buffer, changing with content changes. More...

class SubBuffer

This class represents a sub buffer and its maintainance information inside a superior buffer. More...

Member Typedef Documentation

typedef const_value_type* Arxx::Buffer::const_pointer

The type of a const pointer to elements stored in this buffer.

Use Buffers::Buffer::const_pointer to work with const arrays of elements in the buffer to be safe from API changes.

typedef const value_type Arxx::Buffer::const_value_type

The type of a const element stored in this buffer.

Use Buffers::Buffer::const_value_type to work with const elements in the buffer to be safe from API changes.

typedef value_type* Arxx::Buffer::pointer

The type of a pointer to elements stored in this buffer.

Use Buffers::Buffer::pointer to work with arrays of elements to be safe from API changes.

typedef value_type& Arxx::Buffer::reference

The type of a reference to an element stored in this buffer.

Use Buffers::Buffer::reference to work with the elements to be safe from API changes.

typedef Arxx::u4byte Arxx::Buffer::size_type

The type of positions, lengths and sizes in this buffer.

Use Buffers::Buffer::size_type when working with positions, sizes and length in a buffer to be safe from API changes.

typedef unsigned char Arxx::Buffer::value_type

The type of an element stored in this buffer.

Use Buffers::Buffer::value_type to work with the elements to be safe from API changes.

Constructor & Destructor Documentation

Arxx::Buffer::Buffer ( void )

The standard constructor.

Constructs a buffer of size 0, I/O position is 0, overwrite state is false.

Arxx::Buffer::Buffer	(	Buffer &	Buffer,
		size_type	stPosition,
		size_type	stLength
	)

The sub buffer constructor.

Parameters:

	Buffer	The superior buffer.
	stPosition	The sub buffer's begining position in the superior buffer.
	stLength	The length that should be covered inside the superior buffer starting from u4Position.

Use this constructor if you want to have a sub buffer of the superior buffer Buffer. It may be of length 0 to get an insertion spot at a later time.

Arxx::Buffer::~Buffer ( void ) [virtual]

The destructor of a buffer. It is virtual since the Buffer may be overloaded to support external data.

The destructor of a buffer deletes it's content if it is the most superior buffer. Otherwise it will unregister itself from its superior buffer.

Note:: The destructor of a buffer will not touch its sub buffers (e.g. to delete them). Currently it will not even notify them that their reference buffers are dead. That will be changed later.

Arxx::Buffer::Buffer ( const Buffer & Buffer ) [private]

made private to prevent copy creation of a Buffer.

This may be implemented later but not as long as the buffer itself is not completed.

Member Function Documentation

Arxx::Buffer::const_pointer Arxx::Buffer::GetBegin ( void ) const

Retreives a const pointer to the data of this buffer.

There is no public way to access the content of the buffer directly. m_Begin is private so only the Buffers library may access the content directly for read/write access. To fill the gap between no public access and full private access lies the read-only access for derivatives.

Buffer& Arxx::Buffer::operator= ( const Buffer & Buffer ) [private]

made private to prevent assignment copies of the Buffer.

This may be implemented later but not as long as the buffer itself is not completed.

Arxx::Buffer::reference Arxx::Buffer::operator[] ( size_type stIndex )

Allows read/write access to indexed data members.

Parameters:

stIndex

The index of the data member to access. Begining with zero.

Returns a refernece to the data member with index stIndex. This function will throw a std::out_of_range error if stIndex is beyond stGetLength().

Note:: Since this function addresses data in the buffer it will call vAssureDataPresence().

Arxx::Buffer::value_type Arxx::Buffer::operator[] ( size_type stIndex ) const

Allows read-only access to indexed data members for const buffers.

Parameters:

stIndex

The index of the data member to access. Begining with zero.

Returns a copy of the data member with index stIndex. This function will throw a std::out_of_range error if stIndex is beyond stGetLength().

Note:: Since this function addresses data in the buffer it will call vAssureDataPresence().

Arxx::Buffer::size_type Arxx::Buffer::stGetLength ( void ) const

Returns the length of the buffer.

This length is the length of the data inside the buffer, so the number of bytes actually used by the data.

void Arxx::Buffer::vDelete	(	size_type	stPosition,
		size_type	stLength
	)

Deletes a given amount of data at a specified position.

Parameters:

	stPosition	The position inside the buffer.
	stLength	The length of the block that should be deleted.

This function deletes stLength elements at position stPosition.

void Arxx::Buffer::vInsert	(	size_type	stPosition,
		size_type	stDataLength,
		const_pointer	Data = `0`
	)

Insert a given amount of data at a specified postion.

Parameters:

	stPosition	The position inside the buffer.
	stDataLength	The length of the data block identified by Data.
	Data	The block of data to be inserted in the buffer. This parameter may be omitted which will result in a null-pointer, indicating that the inserted block of data will be filled with Zeros.

The data which is defined by Data will be inserted at position stPosition. The data is taken to be of length stDataLength at minimum. The buffer will be expanded to contain stGetLength() + stDataLength bytes.

Note:: This function directly calls the private function vWrite(), so this function throws the same exceptions as vWrite().

void Arxx::Buffer::vParentDataChanged	(	size_type	stChangeMode,
		size_type	stPosition,
		size_type	stLength
	)			`[private]`

This function is called whenever the data of the sup buffer is changed in a way that also affects this buffer.

Parameters:

	stChangeMode	Categorizes the type of change that affects this buffer.
	stPosition	Indicates the location of the change inside this buffer.
	stLength	Specifies the length of the change inside this buffer.

There are three kinds of changes that may occure:

Updates
Deletes
Inserts

Additionally there are two kinds of actions that need to be taken:

changes to this buffer (local changes)
changes to this buffer's sub buffers (structural changes).

Updates are those changes that neither affect the length of this buffer nor its location inside the superior buffer. For that reason the parameters stPosition and stLength are not considered. The most probable reason why this change is issued is that the most superior buffer had to reallocate the memory for the buffer, because somewhere else so much data was inserted in the buffer that the capacity had to be enlarged.

The only local action taken here is to reset the m_Begin pointer to the correct location inside the sup buffer (m_pSupBuffer->m_Begin + m_stPosition).
The structural changes are equally simple: notify all sub buffers via vParentDataChanged(m_stDataUpdated, ?, ?). Position and length are not important here.

Inserts are issued whenever the superior buffer inserts data. The stPosition indicates the location of the insert inside the sup buffer, so it is comparable with m_stPosition without further calculation. The stLength is the length of the portion of inserted data.

Note:: Notice that this function is called even if the insert was not inside this buffer. If the Insertion was before this buffer (stPosition < m_stPosition) we need to reset m_stPosition. (This SHOULD be changed.)

The local changes depend on the position of the insertion. If the data was inserted before this buffer we need to reset m_stPosition and m_Begin. If the data was inserted inside the buffer we need to reset m_stLength and possibly m_stIOPosition if (stPosition - m_stPosition) <= m_stIOPosition.
The structural changes are easy enough: just pass the change to any sub buffer by calling vParentDataChanged(m_stDataInserted, stPosition - m_stPosition, stLength). There is one exception to this: If this buffer made the initial change and the change request was passed up to the most superior buffer and now the changes are passed down again we don't apply changes here. Once all the changes are done and we return to the initial insertion function it is done then.

Deletes are emitted whenever the superior buffer has deleted a portion of its data. The stPosition inticates where the beginning of the deletion block inside the parent is. Because of its scope, stPosition is directly comparable with m_stPosition. The stLength defines the length of the deletion.

The local changes is defined by the position and length of the deletion. There are six possibilities:
- The deletion is completely before this buffer: only m_stPosition needs to be decremented by stLength.
- The deletion begins before this buffer and overlaps the beginning: m_stPosition needs to be set to stPosition, m_stLength needs to be reduced by the overlapping.
- The deletion is completely inside this buffer: m_stLength needs to be reduced by stLength.
- The deletion begins inside this buffer and overlaps the end: m_stLength needs to be reduced by the size of the overlapping.
- The deletion is completely behind this buffer: nothing to be done.
- The deletion overlaps this buffer completely: m_stLength is set to 0 and m_stPosition is set to stPosition.
The structural changes are very much the same as for Inserts. We just need to pass this change down to all sub buffers by calling vParentDataChanged(m_stDataDeleted, stPosition - m_stPosition, stLength).

void Arxx::Buffer::vRegister ( Arxx::Buffer::Marker & Marker ) const [private]

void Arxx::Buffer::vRegister ( Buffer & Buffer ) [private]

This function registers a buffer to be a sub buffer of this buffer.

This function handles the necessary steps to organise the control structure which contains all the sub buffers. This structure is needed to propagate changes.

void Arxx::Buffer::vSetLength ( size_type stLength = 0 )

Sets the length of the data actually in the buffer.

Parameters:

stLength

The new length of the data.

This is a convenience function as explained below:

If the specified length is greater than the current length the buffer will be expanded to this length. The call is then equivalent to:
```
 vInsert(stGetLength(), stLength - stGetLength()); 
```

If the specified length is smaller than the current length the buffer will be shrunken to this length. This will happen back to front, so all child buffers which reside anywhere between stLength and stGetLength() will be modified as well. This call is then equivalent to:
```
 vDelete(stLength, stGetLength() - stLength); 
```

void Arxx::Buffer::vUnregister ( Arxx::Buffer::Marker & Marker ) const [private]

void Arxx::Buffer::vUnregister ( Buffer & Buffer ) [private]

This function removes a buffer from the list of all sub buffer of this buffer.

This function handles the necessary steps to organise the control structure which contains all the sub buffers. This structure is needed to propagate changes.

void Arxx::Buffer::vWrite	(	Arxx::Buffer &	Buffer,
		Arxx::Buffer::size_type	stPosition,
		Arxx::Buffer::size_type	stDataLength,
		Arxx::Buffer::const_pointer	Data = `0`
	)			`[private]`

This function is responsible for any functionality that writes data to the buffer.

Parameters:

	Buffer	The buffer that makes the write request.
	stPosition	The position (inside this buffer) where the data is to be stored.
	stDataLength	The length of the data block Data.
	Data	The data block to be written into the buffer.

This function is one of the two core functions of the buffer. It allows to insert any data in any buffer and will pipe the call to the most superior buffer which actually copies the data. It will then decide which sub buffers should be notified that content or position has changed.

Friends And Related Function Documentation

friend class Arxx::Buffer::Marker [friend]

std::string sIndentation ( Arxx::Buffer * pBuffer ) [friend]

Member Data Documentation

bool Arxx::Buffer::m_bChanging [private]

Indicates the changing state of this buffer.

This is a fluid state and will be changed in vWrite() and vDelete() when this buffer is actually changing. It will not be true from anywhere outside the library.

pointer Arxx::Buffer::m_Begin [private]

The pointer to the actual content of this buffer.

std::set< Arxx::Buffer::Marker * > Arxx::Buffer::m_Markers [mutable, private]

The associated markers.

Buffer* Arxx::Buffer::m_pSupBuffer [private]

A pointer pointing to the superior buffer.

This pointer points to the Buffer that this buffer is a part of. In case this buffer is the most superior buffer it is '0'.

size_type Arxx::Buffer::m_stCapacity [private]

The size of the memory block reserved for the content of this buffer.

This is an internal-only data. It describes how much data may be stored in this buffer currently without having to reallocate the buffers' memory.

Note:: There is a separate property m_stLength for the length of the content.

const Arxx::Buffer::size_type Arxx::Buffer::m_stDataDeleted = 0x02 [static, protected]

A constant. Its value will be passed to vParentDataChanged() whenever data was deleted.

See also:: vParentDataChanged() for further details.

const Arxx::Buffer::size_type Arxx::Buffer::m_stDataInserted = 0x03 [static, protected]

A constant. Its value will be passed to vParentDataChanged() whenever data was inserted.

See also:: vParentDataChanged() for further details.

const Arxx::Buffer::size_type Arxx::Buffer::m_stDataUpdated = 0x01 [static, protected]

A constant. Its value will be passed to vParentDataChanged() whenever data is to be updated.

See also:: vParentDataChanged() for further details.

size_type Arxx::Buffer::m_stLength [private]

The length of the content within this buffer.

Note:: There is a separate property m_stCapacity for the size of the allocated memory.

size_type Arxx::Buffer::m_stPosition [private]

The position of the begin of this buffer itside its superior buffer.

This value is zero-based.

std::vector< SubBuffer * > Arxx::Buffer::m_SubBuffers [private]

A vector of pointers to structures describing the sub buffers.

The order of thesepointers is irrelevant except for one thing: the last sub buffer must always have the greatest m_stOrder value because it will be the reference for the m_stOrder of new registering buffers.

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

Generated on Tue Oct 10 11:34:43 2006 for libarxx by

1.4.7


Public Types
typedef unsigned char	value_type
	The type of an element stored in this buffer.
typedef value_type &	reference
	The type of a reference to an element stored in this buffer.
typedef value_type *	pointer
	The type of a pointer to elements stored in this buffer.
typedef const value_type	const_value_type
	The type of a const element stored in this buffer.
typedef const_value_type *	const_pointer
	The type of a const pointer to elements stored in this buffer.
typedef Arxx::u4byte	size_type
	The type of positions, lengths and sizes in this buffer.
Public Member Functions
	Buffer (void)
	The standard constructor.
	Buffer (Buffer &Buffer, size_type stPosition, size_type stLength)
	The sub buffer constructor.
virtual	~Buffer (void)
	The destructor of a buffer. It is virtual since the Buffer may be overloaded to support external data.
size_type	stGetLength (void) const
	Returns the length of the buffer.
void	vSetLength (size_type stLength=0)
	Sets the length of the data actually in the buffer.
void	vInsert (size_type stPosition, size_type stDataLength, const_pointer Data=0)
	Insert a given amount of data at a specified postion.
void	vDelete (size_type stPosition, size_type stLength)
	Deletes a given amount of data at a specified position.
value_type	operator[] (size_type stIndex) const
	Allows read-only access to indexed data members for const buffers.
reference	operator[] (size_type stIndex)
	Allows read/write access to indexed data members.
const_pointer	GetBegin (void) const
	Retreives a const pointer to the data of this buffer.
Static Protected Attributes
static const size_type	m_stDataUpdated = 0x01
	A constant. Its value will be passed to vParentDataChanged() whenever data is to be updated.
static const size_type	m_stDataDeleted = 0x02
	A constant. Its value will be passed to vParentDataChanged() whenever data was deleted.
static const size_type	m_stDataInserted = 0x03
	A constant. Its value will be passed to vParentDataChanged() whenever data was inserted.
Private Member Functions
	Buffer (const Buffer &Buffer)
	made private to prevent copy creation of a Buffer.
Buffer &	operator= (const Buffer &Buffer)
	made private to prevent assignment copies of the Buffer.
void	vRegister (Buffer &Buffer)
	This function registers a buffer to be a sub buffer of this buffer.
void	vUnregister (Buffer &Buffer)
	This function removes a buffer from the list of all sub buffer of this buffer.
void	vRegister (Arxx::Buffer::Marker &Marker) const
void	vUnregister (Arxx::Buffer::Marker &Marker) const
void	vWrite (Arxx::Buffer &Buffer, Arxx::Buffer::size_type stPosition, Arxx::Buffer::size_type stDataLength, Arxx::Buffer::const_pointer Data=0)
	This function is responsible for any functionality that writes data to the buffer.
void	vParentDataChanged (size_type stChangeMode, size_type stPosition, size_type stLength)
	This function is called whenever the data of the sup buffer is changed in a way that also affects this buffer.
Private Attributes
Buffer *	m_pSupBuffer
	A pointer pointing to the superior buffer.
pointer	m_Begin
	The pointer to the actual content of this buffer.
size_type	m_stLength
	The length of the content within this buffer.
size_type	m_stCapacity
	The size of the memory block reserved for the content of this buffer.
std::set< Arxx::Buffer::Marker * >	m_Markers
	The associated markers.
size_type	m_stPosition
	The position of the begin of this buffer itside its superior buffer.
std::vector< SubBuffer * >	m_SubBuffers
	A vector of pointers to structures describing the sub buffers.
bool	m_bChanging
	Indicates the changing state of this buffer.
Friends
class	Arxx::Buffer::Marker
std::string	sIndentation (Arxx::Buffer *pBuffer)
Classes
class	Marker
	A marked position in a buffer, changing with content changes. More...
class	SubBuffer
	This class represents a sub buffer and its maintainance information inside a superior buffer. More...