Integer Masks

Overview

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.

Synopsis

#include <cstddef>  // for std::size_t

namespace boost
{

template <std::size_t Bit>
struct high_bit_mask_t
{
    typedef implementation-defined-type  least;
    typedef implementation-defined-type  fast;

    static const least       high_bit       = implementation-defined;
    static const fast        high_bit_fast  = implementation-defined;

    static const std::size_t bit_position   = Bit;
};

template <std::size_t Bits>
struct low_bits_mask_t
{
    typedef implementation-defined-type  least;
    typedef implementation-defined-type  fast;

    static const least       sig_bits       = implementation-defined;
    static const fast        sig_bits_fast  = implementation-defined;

    static const std::size_t bit_count      = Bits;
};

// Specializations for low_bits_mask_t exist for certain bit counts.

}  // 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.

Table 2. 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 easiest-to-manipulate analog of `least`.
`high_bit`	A `least` constant of the value 2^Bit.
`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 equivalent to the value (2^Bits - 1), where Bits is the template parameter. The parameter Bits must be a non-negative integer 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 low_bits_mask_t.

Table 3. 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 easiest-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.

Implementation Notes

When Bits is the exact size of a built-in unsigned type, the implementation has to change to prevent undefined behavior. Therefore, there are specializations of low_bits_mask_t at those bit counts.

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 convenient masks to use when extracting the highest or all the significant bits when the containing built-in type contains more bits. This prevents contamination of values by the higher, unused bits.

Credits

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