[boost] [gsoc][review/comments] Request community input on project interface

Subject: [boost] [gsoc][review/comments] Request community input on project interface
From: Brian Bartman (bbartmanboost_at_[hidden])
Date: 2010-06-21 12:39:40

Hello,

I'm currently working on my GSoC project and I wanted some feedback from the
community about the interface of a data structure I'm working on called a
"bitfield_tuple". The bitfield_tuple makes it easy and simple to create and
use specific bitfields.  Currently, this works only over integral types,
although there are plans to extend this in later versions of the data
structure.  bitfield_tuples correctly work with different types of
endianness as well as provide the mechanisms to allow users to explicitly
define the size of the structure's storage space.

The bitfield_tuple is a tuple like sequence of elements but, instead of
providing direct access to an instance of a type, a proxy to the element
stored within the bitfield_tuple is returned. This is similar to
std::vector<bool>'s reference type.

Example bitfield_tuple declaration,

struct red;
struct green;
struct blue;

typedef bitfield_tuple<
    storage<unsigned int>,
    member<int,red,5>,
    member<int,green,6>,
    member<ing,blue,5>
>  bft_example;

The internal storage type which all of the bitfields are stored in is
specified by the storage template. The members are used to specify the
different bitfields which are to be stored within that storage type. The
member template is specified the exact same way a normal c++ bitfield would
be specified inside of a struct or class.

int red:5;
member<int,red,5>

A member template is specified in the order of: type, name, width of
bitfield.

The order the member templates are given in is the order in which they are
stored within the bitfield_tuple. However, the storage template does not
take up an index within the bitfield_tuple. So the template
member<int,red,5> will be stored at index 0. Each member template requires a
name be specified; this is for ease of access, later described in the get
function. Each name must be unique within a single bitfield_tuple. The width
of the bitfield is handled internally. The starting point for each bitfield
is the bit after the previous bitfield, or 0 if it's the first bitfield.

bitfield_tuple interface summary:

Default constructor, copy constructor, and a constructor which allows for
the construction over an initial value which is of the same as the storage
type.

bitfield_tuple();
bitfield_tuple (bitfield_tuple  const&);
bitfield_tuple (storage_type);

Assignment operators for assignment from the storage type, similar to the
constructor above, and copy assignment.

bitfield_tuple const& operator=(storage_type);
bitfield_tuple const& operator=(bitfield_tuple const&);

The get function operates similar to the boost.tuple with slight
modification.  Specifically, the get function will return a reference type.

There are two ways to use the get function.  The first way is by using a
unsigned integral constant as an index:

bft_example temp;
temp.get<0>(); // returns a proxy reference to the bitfield represented by
member<int,red,5>

The second way to use it is to call get using the name provided to the
member parameter:

temp.get<red>(); // does the same thing as get<0>();

I provide both const and non const versions of both functions.

The bitfield_tuple is also a boost.fusion sequence. It models an associative
array type by using the following category:

struct bft_category
 : boost::fusion::random_access_

traversal_tag,
   boost::fusion::associative_tag
{ };

The btifield_tuple's fusion extension was created through the fusion
sequence extension provided by boost.fusion.

bitfield_tuple supports the following fusion functions and all of the
intrinsic functions which are supported from the implementation of these
functions.

 begin
 end
 is_sequence
 is_view
 category_of
 at
 size
 at_key
 tag_of

The btifield_tuple_iterator supports the following fusion functions:

deref
value_of
next
prior
distance
key_of
value_at_data
deref_data
advance

If you would like to look at the code for bitfield_tuple, it is located
here:
http://svn.boost.org/svn/boost/sandbox/SOC/2010/bit_masks/boost/integer/bitfield_tuple.hpp

--
thanks,
Brian Bartman