Integer Bit Mask Templates

The class templates in <boost/integer/integer_mask.hpp> provide bit masks for a certain bit position or a contiguous-bit pack of a certain size. The types of the masking constants come from the integer type selection templates header.

Contents
Synopsis
Single Bit-Mask Class Template
Group Bit-Mask Class Template
MPL-Compatible Variants
Example
Demonstration Program
Rationale
Credits

Synopsis

#include <boost/integer_fwd.hpp>  // forwarding header
#include <boost/integer.hpp>      // for boost::int_fast_t
#include <cstddef>                // for std::size_t

namespace boost
{

// MPL-compatible
template < int Offset >
struct integer_hi_mask
{
    static  bool const  is_specialized = implementation_supplied;
    static  int const   bit_offset = Offset;

    typedef implementation_supplied  type;
    typedef implementation_supplied  value_type;
    static  value_type const  value = implementation_supplied;
    // There are other (optional) operations....
};

template < int Length >
struct integer_lo_mask
{
    static  bool const  is_specialized = implementation_supplied;
    static  int const   bit_count = Length;

    typedef implementation_supplied  type;
    typedef implementation_supplied  value_type;
    static  value_type const  value = implementation_supplied;
    // There are other (optional) operations....
};

// single
template < std::size_t Bit >
class high_bit_mask_t
{
public:
    typedef typename integer_hi_mask<Bit>::value_type  least;
    typedef int_fast_t<least>::fast                     fast;

    static const least  high_bit = integer_hi_mask<Bit>::value;
    static const fast   high_bit_fast = high_bit;

    static const std::size_t  bit_position = Bit;

};

// group
template < std::size_t Bits >
class low_bits_mask_t
{
public:
    typedef typename integer_lo_mask<Bits>::value_type  least;
    typedef int_fast_t<least>::fast                      fast;

    static const least  sig_bits = integer_lo_mask<Bits>::value;
    static const fast   sig_bits_fast = sig_bits;

    static const std::size_t  bit_count = Bits;

};

}  // namespace boost

Single Bit-Mask Class Template

The boost::high_bit_mask_t class template provides constants for bit masks representing the bit at a certain position. The masks are equivalent to the value 2^Bit, where Bit is the template parameter. The bit position must be a nonnegative number from zero to Max, where Max is one less than the number of bits supported by the largest unsigned built-in integral type. The following table describes the members of an instantiation of high_bit_mask_t.

Members of the `boost::high_bit_mask_t` Class Template
Member	Meaning
`least`	The smallest unsigned built-in type that supports the given bit position.
`fast`	The quick-to-manipulate analog of `least`.
`high_bit`	A `least` constant of the desired bit-masking value.
`high_bit_fast`	A `fast` analog of `high_bit`.
`bit_position`	The value of the template parameter, in case its needed from a renamed instantiation of the class template.

Group Bit-Mask Class Template

The boost::low_bits_mask_t class template provides constants for bit masks representing the lowest bits of a certain amount. The masks are equivalent to the value (2^Bits - 1), where Bits is the template parameter. The bit amount must be a nonnegative number from zero to Max, where Max is the number of bits supported by the largest unsigned built-in integral type. The following table describes the members of an instantiation of low_bits_mask_t.

Members of the `boost::low_bits_mask_t` Class Template
Member	Meaning
`least`	The smallest unsigned built-in type that supports the given bit count.
`fast`	The quick-to-manipulate analog of `least`.
`sig_bits`	A `least` constant of the desired bit-masking value.
`sig_bits_fast`	A `fast` analog of `sig_bits`.
`bit_count`	The value of the template parameter, in case its needed from a renamed instantiation of the class template.

MPL-Compatible Variants

The single and group bit-mask class templates have several drawbacks:

You must know the valid bit-lengths in advance.
Using an inappropriate parameter value results in a compiler diagnostic.
The type names used are inconsistent with other transformations in Boost, like in MPL.
The above two facts make use of the regular bit-mask class templates incompatible with template meta-programming techniques.

The integer_hi_mask and integer_lo_mask class templates provide MPL-compatible alternatives. These alternatives have the form:

template< int Size >
struct name
{
    static  bool const  is_specialized = implementation_supplied;
    static  int const   switch_id = Size;

    typedef implementation_supplied  type;
    typedef implementation_supplied  value_type;
    static  value_type const  value = implementation_supplied;
    // with other operations...
};

Only some of the members are always present. The presence of other members and operations is flagged by the (always-present) is_specialized.

Permanent Members of the MPL-Compatible Masking Class Template Types
Class Template Member	Meaning
`is_specialized`	Flag indicating when a particular template class instantiation is a valid meta-function (`true`) or not (`false`).
`switch_id` (Actual name is template-specific.)	The value of the main control parameter, accessible even if the template class instantiation is aliased.

The optional members are based from inheriting from a MPL-style Integral Constant type, but only if is_specialized is true.

Optional Members of the MPL-Compatible Masking Types
Class Template Member	Meaning
`value`	The actual bit mask.
`value_type`	The type of the bit mask value.
`type`	The Integral Constant implementation type, which should be `boost::mpl:: integral_c< value_type, value >`.

The Integral Constant prototype also adds the following operations:

Optional Operations of the MPL-Compatible Masking Types
Operation (with `n` as a masking type)	Meaning
`boost::mpl::next< n >::type`	`boost::mpl::next< n::type >::type`, i.e. `boost::mpl::integral_c< n::value_type, n::value + 1 >`.
`boost::mpl::prior< n >::type`	`boost::mpl::prior< n::type >::type`, i.e. `boost::mpl::integral_c< n::value_type, n::value - 1 >`.
`n::value_type const c = n();`	`c` is set to `n::value`.

The specifics for each masking class template are:

Criteria for the MPL-Compatible Masking Types
(Everything besides the parameter ID is in name-space `boost` except where indicated.)
Class Template	Parameter Member ID	Classic Equivalent	Value Type	Value	Valid Range
`integer_hi_mask`	`bit_offset`	`high_bit_mask_t`	`sized_integral < bit_offset + 1, unsigned >`	2^bit_offset	`0 <= bit_offset < std::numeric_limits< uintmax_t >::digits`
`integer_lo_mask`	`bit_count`	`low_bits_mask_t`	`sized_integral < bit_count, unsigned >`	2^bit_offset - 1	`0 <= bit_count <= std::numeric_limits< uintmax_t >::digits`

Example

#include <boost/integer/integer_mask.hpp>

//...

int main()
{
    typedef boost::high_bit_mask_t<29>  mask1_type;
    typedef boost::low_bits_mask_t<15>  mask2_type;

    mask1_type::least  my_var1;
    mask2_type::fast   my_var2;
    //...

    my_var1 |= mask1_type::high_bit;
    my_var2 &= mask2_type::sig_bits_fast;

    //...
}

Demonstration Program

The program integer_mask_test.cpp is a simplistic demonstration of the results from instantiating various examples of the bit mask class templates.

Rationale

The class templates in this header are an extension of the integer type selection class templates. The new class templates provide the same sized types, but also convienent masks to use when extracting the highest or all the significant bits when the containing built-in type contains more bits. This prevents contaimination of values by the higher, unused bits.

Credits

The author of the Boost bit mask class templates is Daryle Walker.

Revised July 29, 2008

© Copyright Daryle Walker 2001. Use, modification, and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or a copy at <http://www.boost.org/LICENSE_1_0.txt>.)