IT_Bus::BinaryBuffer Class Reference

#include <it_bus/binary_buffer.h>

Inheritance diagram for IT_Bus::BinaryBuffer:

IT_Bus::Base64Binary IT_Bus::HexBinary 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.
BinaryBufferassign (const String &rhs, size_t n)
 Initialize the binary buffer with the string value.
void operator= (const char *rhs)
 Assigment operator.
BinaryBufferassign (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.


Generated on Thu Sep 7 11:39:48 2006 for Artix by  doxygen 1.4.7