...one of the most highly
regarded and expertly designed C++ library projects in the
world.

— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards

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
- Example
- Demonstration Program
- Rationale
- Credits

#include <cstddef>// for std::size_tnamespace boost { template < std::size_t Bit > struct high_bit_mask_t { typedefimplementation_suppliedleast; typedefimplementation_suppliedfast; 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 { typedefimplementation_suppliedleast; typedefimplementation_suppliedfast; 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

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`

.

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

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`

.

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

**Implementation Note**

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.

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

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

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.

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

Revised September 23, 2001

© Copyright Daryle Walker 2001. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.