bit::Buffer Class Reference
[Buffers]

#include <bit/buffer.h>

Inheritance diagram for bit::Buffer:

Inheritance graph
[legend]
List of all members.

Detailed Description

This class manages a packed bit (or octet) buffer.

Although this class manages bit oriented buffers, it attempts to optimize for octet (byte) based buffers.

The methods pack, unpack and clear provide a means of extracting bit segments from the buffer, setting se

Todo:
create an overloaded = operator that copies memory if the buffer is the owner
Author:
Rick L. Vinyard, Jr.


Public Member Functions

 Buffer (size_t initial_size=0, Growth growth=DYNAMIC, size_t sizemax=0)
 Construct a buffer of a given size that is allowed to dynamically grown as pack/unpack requests are made.
 Buffer (void *external_data, size_t data_octets, DataMode datamode=COPY, Growth growth=DYNAMIC, size_t sizemax=0)
 Construct a buffer that is a copy of external data.
const uint8_t *const data () const
 Get the underlying data buffer.
size_t size () const
 Get the currently allocated size.
bool unpack (void *mem, size_t mem_octets, Location mem_loc, size_t buf_offset_bits, size_t extract_bits)
template<typename T>
bool unpack (T &val, Location mem_loc, size_t buf_offset_bits, size_t extract_bits)
bool pack (const void *mem, size_t mem_octets, Location mem_loc, size_t buf_offset, size_t buf_tgtsize, size_t n)
template<typename T>
bool pack (const T &val, Location mem_loc, size_t offset, size_t destsize, size_t n)
bool clear_bits (size_t offset, size_t bits)
void clear ()
bool is_dynamic () const
 Returns true if the buffer is allowed to dynamically expand as necessary to accommodate pack requests.
bool is_fixed () const
Growth growth () const
void set_growth (Growth growth)
 If true, allow the buffer to dynamically expand as necessary to accommodate pack requests that are beyond the bounds of the buffer.
virtual void set_data (void *data, size_t size, DataMode datamode=COPY)
 Sets the buffer to a copy of the memory location pointed at by data to be of octet size.
virtual size_t set_size (size_t size_request)
 Sets the underlying data buffer to the requested size.
size_t sizemax ()
 Gets the maximum size this buffer is allowed to grow.
void set_sizemax (size_t sizemax)
 Sets the maximum size that this buffer is allowed to grow.
Bufferoperator= (const Buffer &other)
 Overloaded = operator does 'the right thing' for the buffer chunk according to the ownership semantics of the 'other' buffer.
sigc::signal< void > signal_data_location_changed ()
 Signals changes to the underlying data buffer location in memory.
sigc::signal< void > signal_data_changed ()
 Signals a change to the data within the buffer.
sigc::signal< void > signal_size_changed ()
 Signals a change to the size of the internal buffer.

Protected Member Functions

void free_buffer ()
 Utility method to clear the buffer.
bool clear_bits (size_t offset, size_t bits, bool suppress)
 Utility method to clear bits and suppress calling the on_changed* methods.
virtual void on_data_location_changed ()
virtual void on_size_changed ()
virtual void on_data_changed ()

Protected Attributes

uint8_t * m_pdata
size_t m_size
bool m_is_owner
Growth m_growth
size_t m_sizemax


Member Function Documentation

const uint8_t *const bit::Buffer::data  )  const
 

Get the underlying data buffer.

Note: if this is a dynamically resizeable buffer, you should connect to the data_location_changed signal.

void bit::Buffer::free_buffer  )  [protected]
 

Utility method to clear the buffer.

on_changed* methods are not called since this is protected. Therefore it is the responsibility of the calling method to call the appropriate on_changed* methods

bool bit::Buffer::is_dynamic  )  const
 

Returns true if the buffer is allowed to dynamically expand as necessary to accommodate pack requests.

If pack requests an offset and size that is beyond the bounds of the currently allocated buffer and the buffer is set to dynamic, the buffer will be dynamically expanded and the expanded area cleared to zero to accommodate the request.

Buffer & bit::Buffer::operator= const Buffer other  ) 
 

Overloaded = operator does 'the right thing' for the buffer chunk according to the ownership semantics of the 'other' buffer.

If the other buffer does not own its memory chunk, then niether will this buffer, and if necessary the old memory chunk will be cleaned up. This means that both memory buffers will operate on the same piece of memory.

If the other buffer did own its memory chunk then a copy will be made and the same semantics for dynamic growth will apply.

bool bit::Buffer::pack const void *  mem,
size_t  mem_octets,
Location  mem_loc,
size_t  buf_offset,
size_t  buf_tgtsize,
size_t  n
 

Parameters:
mem The memory location to transfer from
mem_octets The size of the memory location in octets
buf_offset The offset from the start of the data buffer in bits
buf_tgtsize The size of the target area in the buffer in bits
n The size of the data to extract in bits
Returns:
true if transfer accomplished, false otherwise. If
Parameters:
offset +
destsize are greater than the size of the buffer and the buffer cannot be expanded to accommodate the request zero is returned.
Memory Buffer ================================================== |000000000011111111112222222222333333333344444444| |012345678901234567890123456789012345678901234567| ================================================== ^ mem = start of memory address ^ mem_octets = 6 ^ ^ n = 10 ^ when mem_loc = END ^ cpy out^ when mem_loc = END ^ n = 10 ^ when mem_loc = START ^ cpy out^ when mem_loc = START

Bit Buffer ================================================== |000000000011111111112222222222333333333344444444| |012345678901234567890123456789012345678901234567| ================================================== ^ buf_offset_bits = 14 ^ buf_tgtsize = 20 ^ ^ n = 10 ^ ^ cpy in ^

size_t bit::Buffer::set_size size_t  size_request  )  [virtual]
 

Sets the underlying data buffer to the requested size.

If size_request is 0, the buffer will be freed. The new size is limited to the set maximum size, or unlimited if sizemax=0.

Returns:
The new size of the data buffer.

void bit::Buffer::set_sizemax size_t  sizemax  ) 
 

Sets the maximum size that this buffer is allowed to grow.

Note: if sizemax is set to a value less than the current buffer size the buffer will be truncated immediately.

sigc::signal<void> bit::Buffer::signal_data_location_changed  )  [inline]
 

Signals changes to the underlying data buffer location in memory.

This most likely occurs when the buffer is dynamically resized.

bool bit::Buffer::unpack void *  mem,
size_t  mem_octets,
Location  mem_loc,
size_t  buf_offset_bits,
size_t  extract_bits
 

Parameters:
mem The memory location to transfer buffer data into
mem_octets The size of the memory location in octets
buf_offset_bits The offset from the beginning of the buffer in bits to begin extraction from
bits The size of the data to extract in bits
Returns:
true if transfer accomplished, false otherwise
Bit Buffer ================================================== |000000000011111111112222222222333333333344444444| |012345678901234567890123456789012345678901234567| ================================================== ^ buf_offset_bits = 14 ^ extract_bits = 20 ^

Memory Buffer ================================================== |000000000011111111112222222222333333333344444444| |012345678901234567890123456789012345678901234567| ================================================== ^ mem = start of memory address ^ mem_octets = 6 ^ ^ Resulting data ^ when mem_loc = END ^ Resulting data ^ when mem_loc = START


The documentation for this class was generated from the following files:
Generated on Thu Jul 6 14:38:08 2006 by  doxygen 1.4.6