IT_Bus::BinaryBuffer Class Reference

#include <it_bus/binary_buffer.h>

Inheritance diagram for IT_Bus::BinaryBuffer:

List of all members.

---

Detailed Description

Class implementing the binary buffer.

The binary buffer class encapsulates a pointer to a character array, which contains the data content managed by the buffer. An instance of the binary buffer class may, or may not, be responsible for managing the memory allocated to the character array. This behavior is modified through the class' methods.

This class is the superclass for the classes representing the HexBinary and Base64Binary types.

Definition at line 27 of file binary_buffer.h.

Public Member Functions
	BinaryBuffer ()
	No argument constructor.
	BinaryBuffer (const BinaryBuffer &rhs)
	Copy constructor.
virtual	~BinaryBuffer ()
	Destructor.
	BinaryBuffer (String rhs)
	Constructor.
	BinaryBuffer (const char *data, long size=-1)
	Constructor.
void	operator= (const BinaryBuffer &rhs)
	Assignment operator.
void	operator= (String rhs)
	Assignment operator.
BinaryBuffer &	assign (const String &rhs, size_t n)
	Initialize the binary buffer with the string value.
void	operator= (const char *rhs)
	Assigment operator.
BinaryBuffer &	assign (const char *rhs, size_t n)
	Initialize the binary buffer with the contents of the character array.
char	operator[] (long lIndex)
	Indexing operator.
bool	operator== (const BinaryBuffer &rhs) const
	Equality operator.
void	attach (BinaryBuffer &attach_buffer)
	Set the data pointer in this binary buffer to the value in the data pointer in the binary buffer parameter.
void	borrow (const BinaryBuffer &borrow_buffer)
	Set the data pointer within this binary buffer to the value in the data pointer in the binary buffer parameter; both binary buffers point to the same memory allocation.
void	borrow (const char *borrow_data, long size=-1)
	Set the data pointer within this binary buffer to point to a character array.
bool	is_borrowing ()
	Returns true if this binary buffer instance does not assume responsibility for managing the memory allocated to the buffer content.
void	attach_external (char *p, long size, bool borrow=true)
	Set the data pointer within this binary buffer to point to a character array.
void	attach_external_const (const char *p, long size)
	Set the data pointer within this binary buffer to point to a const character array.
void	detach_external ()
	Null the data pointer, effectively emptying the binary buffer.
void	allocate (long size)
	Allocates memory for the binary buffer contents.
void	clear ()
	Sets the internal pointer to null.
const char *	get_const_pointer () const
	Return the internal pointer to the character array representing the buffer content.
IT_String	get_it_string () const
	Returns an IT_String initialized with the buffer content.
char *	at (long lIndex)
	Returns a pointer to a specific character in the buffer.
String	substr (long lIndex, long size=-1) const
	Returns a substring from within the buffer.
long	find_binary_buffer (long &dwFindIdx, long dwFindMaxIdx, BinaryBuffer &vvPacketTerminator) const
	Returns the position in the buffer content of the search buffer.
char *	instr (char c, long lIndex=0)
	Returns a pointer to the position in the buffer content of the first occurrence of the search character.
long	find (const char *s, long lIndex=0) const
	Returns the position in the buffer content of the search string.
char *	concat (const char *szThisString, long size=-1)
	Concatenates a character array to the existing buffer content.
bool	empty () const
	Checks if the binary buffer is pointing to content.
String	get_string () const
	Return a String initialized with the buffer content.
Private Attributes
char *	m_data
	The pointer to the character array representing the buffer content.
long	m_size
	The length of the buffer content.
bool	m_just_borrowing
	Flag indicating whether the buffer content is borrowed.
bool	m_borrowed_const
	Flag indicating whether the borrowed content is const.

---

Member Function Documentation

void IT_Bus::BinaryBuffer::allocate

(

long

size

)

Allocates memory for the binary buffer contents.

If the binary buffer is not responsible for memory management of its current data, the current memory will not be released and additional memory will be allocated; the binary buffer will be responsible for this newly allocated memory.

If the binary buffer is responsible for memory management of its current data, and the current memory allocation is a different size than the requested allocation, then the current memory is released and new memory allocated. The binary buffer will be responsible for this newly allocated memory.

If the binary buffer is responsible for memory management of its current data, and the current memory allocation is the same size as the requested allocation, then the current memory is not released. The binary buffer retains responsibility for memory management.

Parameters:

Long

representing the requested memory allocation.

BinaryBuffer& IT_Bus::BinaryBuffer::assign	(	const char *	rhs,
		size_t	n
	)

Initialize the binary buffer with the contents of the character array.

The character array is copied into newly allocated memory. The binary buffer is responsible for managing this memory.

Parameters:

	Pointer	to the character array.
	size_t	size of the binary buffer.

BinaryBuffer& IT_Bus::BinaryBuffer::assign	(	const String &	rhs,
		size_t	n
	)

Initialize the binary buffer with the string value.

The string is copied into newly allocated memory. The binary buffer is responsible for managing this memory.

Parameters:

	String	to use in initializing the binary buffer.
	size_t	size of the binary buffer.

char* IT_Bus::BinaryBuffer::at

(

long

lIndex

)

Returns a pointer to a specific character in the buffer.

The following invocations return equivalent values.

   get_const_pointer()[lIndex]
   get_pointer()[lIndex]
 

Parameters:

Long

specifying the position (index) of the desired character.

Returns:

Pointer to the desired character.

Exceptions:

Exception

thrown if the index of the desired character is outside the bounds of the buffer.

void IT_Bus::BinaryBuffer::attach

(

BinaryBuffer &

attach_buffer

)

Set the data pointer in this binary buffer to the value in the data pointer in the binary buffer parameter.

Set the data pointer within the binary buffer parameter to null.

If the binary buffer parameter was responsible for the managing the memory allocated to the buffer content, then this binary buffer assumes responsibility for managing the memory. If the binary buffer parameter was not responsible for managing the memory, then this binary buffer does not assume responsibility for the memory allocation.

Parameters:

BinaryBuffer

instance.

void IT_Bus::BinaryBuffer::attach_external	(	char *	p,
		long	size,
		bool	borrow = true
	)

Set the data pointer within this binary buffer to point to a character array.

Parameters:

	Pointer	to the character array.
	Long	indicating the size of the character array.
	boolean	indicating whether this binary buffer is borrowing the data content. If false, this binary buffer assumes responsibility for management of the memory allocated for the character array. If true (the default), the binary buffer is not responsible for memory management.

void IT_Bus::BinaryBuffer::attach_external_const	(	const char *	p,
		long	size
	)

Set the data pointer within this binary buffer to point to a const character array.

The binary buffer is not responsible for memory management.

Parameters:

	Pointer	to the character array.
	Long	indicating the size of the character array.

void IT_Bus::BinaryBuffer::borrow	(	const char *	borrow_data,
		long	size = -1
	)

Set the data pointer within this binary buffer to point to a character array.

This binary buffer instance does not assume responsibility for managing the memory allocated to the buffer content.

Parameters:

	Pointer	to the character array.
	Long	indicating the size of the character array. If equal to -1 (the default), the method determines the length of the character array.

void IT_Bus::BinaryBuffer::borrow

(

const BinaryBuffer &

borrow_buffer

)

Set the data pointer within this binary buffer to the value in the data pointer in the binary buffer parameter; both binary buffers point to the same memory allocation.

This binary buffer instance does not assume responsibility for managing the memory allocated to the buffer content.

Parameters:

BinaryBuffer

instance.

void IT_Bus::BinaryBuffer::clear

(

)

Sets the internal pointer to null.

If the binary buffer is responsible for managing the memory allocated to the buffer content, the memory is released.

char* IT_Bus::BinaryBuffer::concat	(	const char *	szThisString,
		long	size = -1
	)

Concatenates a character array to the existing buffer content.

Since this method requires a resizing of the buffer, it can only be invoked on a binary buffer instance that is responsible for managing the memory allocated to the buffer. The method uses the get_pointer() method, which will throw an exception if this binary buffer instance points to borrowed content.

Parameters:

	Pointer	to the character array.
	Long	the number of characters to be concatenated to the buffer content. If this value is -1 (the default), the entire character array is concatenated to the buffer content.

void IT_Bus::BinaryBuffer::detach_external

(

)

Null the data pointer, effectively emptying the binary buffer.

If the binary buffer was responsible for memory management, the buffer gives up that responsibility. The buffer does not, however, release the memory allocated to the content.

bool IT_Bus::BinaryBuffer::empty

(

)

const [inline]

Checks if the binary buffer is pointing to content.

Returns:

bool true if the buffer is pointing to content.

Definition at line 422 of file binary_buffer.h.

long IT_Bus::BinaryBuffer::find	(	const char *	s,
		long	lIndex = 0
	)			const

Returns the position in the buffer content of the search string.

Parameters:

	Pointer	to the search string.
	Long	the position within the buffer to begin the search. If this value is zero (the default), the search starts at the beginning of the buffer.

Returns:

Long corresponding to the point in the buffer content where the search string begins.

Exceptions:

Exception

thrown if the start position is outside the bounds of the buffer.

long IT_Bus::BinaryBuffer::find_binary_buffer	(	long &	dwFindIdx,
		long	dwFindMaxIdx,
		BinaryBuffer &	vvPacketTerminator
	)			const

Returns the position in the buffer content of the search buffer.

Parameters:

	Long	the position within the buffer to begin the search.
	Long	the position within the buffer to stop the search, even if a match has not been made.
	A	reference to the search buffer.

Returns:

Long corresponding to the point in the buffer content where the search buffer begins.

const char* IT_Bus::BinaryBuffer::get_const_pointer

(

)

const

Return the internal pointer to the character array representing the buffer content.

This version of the method will return the pointer regardless of whether this binary buffer instance is responsible for managing the memory allocated to the buffer content.

Returns:

Pointer to the buffer content.

IT_String IT_Bus::BinaryBuffer::get_it_string

(

)

const

Returns an IT_String initialized with the buffer content.

Returns:

IT_String of the buffer content.

String IT_Bus::BinaryBuffer::get_string

(

)

const

Return a String initialized with the buffer content.

Returns:

String of the buffer content.

char* IT_Bus::BinaryBuffer::instr	(	char	c,
		long	lIndex = 0
	)

Returns a pointer to the position in the buffer content of the first occurrence of the search character.

Parameters:

	char	the search character.
	Long	the position within the buffer to begin the search. If this value is zero (the default), the search starts at the beginning of the buffer.

Returns:

Pointer to the location of the first occurrence of the character in the buffer content.

Exceptions:

Exception

thrown if the start position is outside the bounds of the buffer.

bool IT_Bus::BinaryBuffer::is_borrowing

(

)

Returns true if this binary buffer instance does not assume responsibility for managing the memory allocated to the buffer content.

Returns:

true if the buffer is borrowing the data pointer.

void IT_Bus::BinaryBuffer::operator=

(

const char *

rhs

)

Assigment operator.

Parameters:

Pointer

to character array

void IT_Bus::BinaryBuffer::operator=

(

String

rhs

)

Assignment operator.

Parameters:

String

value

void IT_Bus::BinaryBuffer::operator=

(

const BinaryBuffer &

rhs

)

Assignment operator.

Parameters:

BinaryBuffer

instance

bool IT_Bus::BinaryBuffer::operator==

(

const BinaryBuffer &

rhs

)

const

Equality operator.

Parameters:

BinaryBuffer

instance for the comparison.

char IT_Bus::BinaryBuffer::operator[]

(

long

lIndex

)

Indexing operator.

Parameters:

Long

the index.

String IT_Bus::BinaryBuffer::substr	(	long	lIndex,
		long	size = -1
	)			const

Returns a substring from within the buffer.

Parameters:

	Long	the position within the buffer to begin the substring.
	Long	the length of the substring. If this value is -1 (the default), the substring is from the start position to the end of the buffer.

Exceptions:

Exception

thrown if the start position is outside the bounds of the buffer.

---

Member Data Documentation

bool IT_Bus::BinaryBuffer::m_borrowed_const [private]

Flag indicating whether the borrowed content is const.

If the borrowed buffer is const, certain operations like get_pointer will throw an exception as you cannot get a non-const-pointer if the content is const

Definition at line 458 of file binary_buffer.h.

bool IT_Bus::BinaryBuffer::m_just_borrowing [private]

Flag indicating whether the buffer content is borrowed.

The binary buffer instance is not responsible for managing the memory for borrowed content.

Definition at line 448 of file binary_buffer.h.

---