[Boost-users] [bitfield] Pre-review request

Subject: [Boost-users] [bitfield] Pre-review request
From: vicente.botet (vicente.botet_at_[hidden])
Date: 2009-10-19 18:00:05

Hi all,

I have adapted the Boost.Bitfield library from Emile Cormier with its permision and I have requested the Review Wizards to include Boost.Bitfield on the review schedule. The library is now quite stable.

Even if there were not too much interest in the Boost ML, only 140 dowloads from the Boost Vault, the version on which it is based had more that 1500 downloads, so I suppose that the subject interest a lot of people. I really think Boost.Bitfield is the complement the Boost.Endian library to manage with all the endian issue, allowing to mange not only endian interger issues, but also endian bitfield issues.

I hope that including it on the review schedule will generate more interest and help me to improve the library. I would appreciate it if people could participate to this Pre-review, reading the documentation, testing on their compiler, .... 
Every comment is wellcome. 

BTW, I'm looking for a review manager.

Thanks for all,
Vicente

Boost.Bitfield
Author(s): Vicente J. Botet Escribá, Emile Cormier
Download: `Boost Vault: <http://www.boostpro.com/vault/index.php?action=downloadfile&filename=bitfield.zip&directory=Portability&>
Boost Sandbox: https://svn.boost.org/svn/boost/sandbox/bitfield
Documentation: https://svn.boost.org/svn/boost/sandbox/bitfield/libs/bitfield/doc/index.html
Html doc also included the Vault package

Categories: Portability, Integer
Description: Portable bitfields traits. Boost.Bitfield consists of: 
* a generic bitfield traits class providing generic getter and setter methods. 
* a BOOST_BITFIELD_DCL macro making easier the definition of the bitfield traits and the bitfield getter and setter functions. 

Example declaration:

        struct Rgb565
        {
            uint16_t storage;
            BOOST_BITFIELD_DCL(uint16_t, storage, unsigned char, red, 0, 4);
            BOOST_BITFIELD_DCL(uint16_t, storage, unsigned char, green, 5, 10);
            BOOST_BITFIELD_DCL(uint16_t, storage, unsigned char, blue, 11,15);
        };

Example usage:

        Rgb565 r;
        r.storage= 0xffff;

        // Write to a bitfield. Note that parenthesis are needed around the bitfield
        r.red() = 23;

        // Read from a bitfield
        unsigned char b = r.blue();

In a near future the library could add the following if the users consider it useful.

* Add bitfields group *

Used to easily manipulate groups of bitfields the same way as does C bitfields, but in a portable manner. 

Example declaration: 

struct Rgb565
{
    struct red {};
    struct green {};
    struct blue {};
    typedef bitfields<mpl::vector<
            member<unsigned char, red,   5>,
            member<unsigned char, green, 6>,
            member<unsigned char, blue,  5> 
    > > type; 
};

Example usage: 

Rgb565::type r = make_bitfields<Rgb565::type, 1,2,3>;

// Write to a bitfield.
r.get<Rgb565::red>() = 23;
//or
r.set<Rgb565::red>(23);

// Read from a bitfield
Rgb565::at<Rgb565::blue>::value_type b = r.get<Rgb565::blue>();

* Add pointer_plus_bits *

Based on 

  a.. The article of Joaquin Optimizing red-black tree color bits, 
  b.. the implementation of Ion pointer_plus_bits from Boost.Intrusive , and 
  c.. Clang's QualType smart pointer
This class will allows to use the unsused bits of a pointer to reduce the size of the nodes containing pointers and bits and sometimes improving also the performances. 

I have not reached yet the interface I would like to have. For the moment we can do 

typedef pointer_plus_bits<int*,1,bool>::type pint_and_bool;

int i=0;
pint_and_bool v1;
ASSERT_EQUALS(v1.pointer(),0);
ASSERT_EQUALS(v1.small_int(),false);
pint_and_bool v2(&i, true);
ASSERT_EQUALS(v2.pointer(),&i);
ASSERT_EQUALS(v2.small_int(),true);
v1.pointer()=v2.pointer();
v1.small_int()=true;
ASSERT_EQUALS(v1.pointer(),&i);
ASSERT_EQUALS(v1.small_int(),true);

typedef pointer_plus_bits<
        pointer_plus_bits<int*,1,bool>::type
                        ,1, bool>::type  pint_and_bool_bool
pint_and_bool_bool v1;
ASSERT_EQUALS(v1.small_int(),false);
ASSERT_EQUALS(v1.pointer().get_pointer(),0);
ASSERT_EQUALS(v1.get_pointer().get_pointer(),0);
ASSERT_EQUALS(v1.get_pointer().small_int(),false);