bit::Array Class Reference

A bit-packed array of fixed-bit-width elements. More...

#include <Array.hh>

Inheritance diagram for bit::Array:

bit::FloatArray List of all members.

Public Member Functions

 Array ()
 Construct an empty array with zero bit-width.
 Array (u64 num_elems, unsigned int bits_per_elem)
 Create an array with initial size.
u64 num_elems () const
 Return the number of elements in the array.
unsigned int bits_per_elem () const
 Return the width of the array, i.e.
u64 capacity () const
 Return the number of elements allocated for the underlying buffer.
void resize (u64 num_elems)
 Change the number of elements in the array.
void reserve (u64 capacity)
 Change the capacity (number of allocated elements) of the array.
void set_width (unsigned int bits_per_elem)
 Change the width of the elements to given width.
void set (u64 elem, u32 value)
 Set the value of an element.
void set_grow (u64 elem, u32 value)
 Set the value of an element growing the buffer if necessary.
void set_grow_widen (u64 elem, u32 value)
 Set the value of an element growing and widening the buffer if necessary.
u32 get (u64 elem) const
 Return value of an element.
const unsigned char * data () const
 Const access the internal data buffer.
unsigned char * data ()
 Access the internal data buffer.
u64 data_len () const
 Return the safe access length of the internal data buffer obtained with data() (i.e.
void write (FILE *file) const
 Write the array in file.
void read (FILE *file)
 Read the array from file.

Static Public Attributes

static const u64 index_limit = (u64)-1
 A limit index value used for return values.

Private Attributes

unsigned int m_bits_per_elem
 Bits reserved for each element in the array.
u64 m_num_elems
 Number of elements in the array.
u64 m_capacity
 Number of elements allocated for the underlying buffer.
Buffer m_buffer
 Buffer containing the array elements.

Detailed Description

A bit-packed array of fixed-bit-width elements.

Bug:
Growing the array may have some problems when the number of elements is larger than 2^63. For example, when the capacity is doubled in set_grow().


Constructor & Destructor Documentation

bit::Array::Array  )  [inline]
 

Construct an empty array with zero bit-width.

bit::Array::Array u64  num_elems,
unsigned int  bits_per_elem
[inline]
 

Create an array with initial size.

The initial elements are guaranteed to be zero.

Parameters:
bits_per_elem = bits_per_element (0-32 bits)
num_elems = initial number of elements in the array
Exceptions:
bit::invalid_argument one of the bit arguments is invalid


Member Function Documentation

unsigned int bit::Array::bits_per_elem  )  const [inline]
 

Return the width of the array, i.e.

the number of bits allocated for each element.

u64 bit::Array::capacity  )  const [inline]
 

Return the number of elements allocated for the underlying buffer.

unsigned char* bit::Array::data  )  [inline]
 

Access the internal data buffer.

It is safe to write and read the first data_len() bytes of the pointer. Note that set_grow(), set_grow_widen(), set_width(), resize() and reserve() may invalidate the pointer.

const unsigned char* bit::Array::data  )  const [inline]
 

Const access the internal data buffer.

It is safe to write and read the first data_len() bytes of the pointer. Note that set_grow(), set_grow_widen(), set_width(), resize() and reserve() may invalidate the pointer.

u64 bit::Array::data_len  )  const [inline]
 

Return the safe access length of the internal data buffer obtained with data() (i.e.

minimum number of bytes needed to store the elements of the array.

u32 bit::Array::get u64  elem  )  const [inline]
 

Return value of an element.

Parameters:
elem = the index of the element
Returns:
the value
Exceptions:
bit::out_of_range accessing outside the array

Reimplemented in bit::FloatArray.

u64 bit::Array::num_elems  )  const [inline]
 

Return the number of elements in the array.

void bit::Array::read FILE *  file  )  [inline]
 

Read the array from file.

Note that capacity is not stored in the file. The capacity is set to number of elements stored in the file.

Parameters:
file = file stream to read from
Exceptions:
bit::io_error if read fails

Reimplemented in bit::FloatArray.

void bit::Array::reserve u64  capacity  )  [inline]
 

Change the capacity (number of allocated elements) of the array.

Making the capacity smaller does nothing.

Parameters:
capacity = the number of elements to allocate

void bit::Array::resize u64  num_elems  )  [inline]
 

Change the number of elements in the array.

The values of the possible new elements are guaranteed to be zero ONLY if the array has never been resized smaller.

Parameters:
num_elems = the new number of elements

void bit::Array::set u64  elem,
u32  value
[inline]
 

Set the value of an element.

Parameters:
elem = the index of the element to set
value = the value to set
Exceptions:
bit::invalid_argument value wider than the bit-width of the array or trying to write to zero-width array
bit::out_of_range accessing outside the array

void bit::Array::set_grow u64  elem,
u32  value
[inline]
 

Set the value of an element growing the buffer if necessary.

If the current capacity is not enough, the capacity is doubled (set to one from zero), and if that is not enough, the capacity is set to (elem+1).

Warning:
Reserving capacity and resizing the array happens before the actual value is written to the buffer. Thus, the size and capacity of the array may change even if the write throws bit::invalid_argument for too wide write.
Parameters:
elem = the index of the element to set
value = the value to set
Exceptions:
bit::invalid_argument value wider than the bit-width of the array

void bit::Array::set_grow_widen u64  elem,
u32  value
[inline]
 

Set the value of an element growing and widening the buffer if necessary.

See set_grow() for info how capacity is handled and warnings about exceptions.

Parameters:
elem = the index of the element to set
value = the value to set

void bit::Array::set_width unsigned int  bits_per_elem  )  [inline]
 

Change the width of the elements to given width.

All elements must fit in the given width or bit::invalid_argument will be thrown and the array is guaranteed to be left in the original state.

Parameters:
bits_per_elem = the number of bits to use per element (1-32 bits)
Exceptions:
bit::invalid_argument invalid bits_per_elem

void bit::Array::write FILE *  file  )  const [inline]
 

Write the array in file.

Note that capacity is not written into the file. When the array is read, the capacity is set to number of elements.

Parameters:
file = file stream to write to
Exceptions:
bit::io_error if write fails

Reimplemented in bit::FloatArray.


Member Data Documentation

const u64 bit::Array::index_limit = (u64)-1 [static]
 

A limit index value used for return values.

All real indices must be less than this value.

unsigned int bit::Array::m_bits_per_elem [private]
 

Bits reserved for each element in the array.

Buffer bit::Array::m_buffer [private]
 

Buffer containing the array elements.

u64 bit::Array::m_capacity [private]
 

Number of elements allocated for the underlying buffer.

When values are written outside the buffer with set_grow() method, the size of the underlying buffer is doubled.

u64 bit::Array::m_num_elems [private]
 

Number of elements in the array.


The documentation for this class was generated from the following file:
Generated on Mon Jan 8 15:51:04 2007 for bit by  doxygen 1.4.6