2001-12-07 13:19:38 +00:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
< html >
< head >
< title > Integer Bit Mask Templates< / title >
< / head >
< body bgcolor = "white" text = "black" link = "blue" vlink = "purple" alink = "red" >
2004-10-05 15:45:52 +00:00
< h1 > < img src = "../../../boost.png" alt = "boost.png (6897 bytes)"
2001-12-07 13:19:38 +00:00
align="middle" width="277" height="86">Integer Bit Mask Templates< / h1 >
2009-11-11 18:57:24 +00:00
< p > The class templates in < cite > < a href = "../../../boost/integer/integer_mask.hpp" > < boost/integer/integer_mask.hpp> < / a > < / cite > 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 < a href = "../integer.htm" > integer type selection templates< / a > header.< / p >
2001-12-07 13:19:38 +00:00
< h2 > < a name = "contents" > Contents< / a > < / h2 >
< ul >
< li > < a href = "#contents" > Contents< / a > < / li >
< li > < a href = "#synopsis" > Synopsis< / a > < / li >
< li > < a href = "#single" > Single Bit-Mask Class Template< / a > < / li >
< li > < a href = "#group" > Group Bit-Mask Class Template< / a > < / li >
< li > < a href = "#example" > Example< / a > < / li >
< li > < a href = "#demo" > Demonstration Program< / a > < / li >
< li > < a href = "#rationale" > Rationale< / a > < / li >
< li > < a href = "#credits" > Credits< / a > < / li >
< / ul >
< h2 > < a name = "synopsis" > Synopsis< / a > < / h2 >
< blockquote > < pre >
2009-11-11 18:57:24 +00:00
#include < cstddef> < i > // for std::size_t< / i >
2001-12-07 13:19:38 +00:00
namespace boost
{
template < std::size_t Bit >
2009-11-11 18:57:24 +00:00
struct high_bit_mask_t
2001-12-07 13:19:38 +00:00
{
2009-11-11 18:57:24 +00:00
typedef < em > implementation_supplied< / em > least;
typedef < em > implementation_supplied< / em > fast;
2001-12-07 13:19:38 +00:00
2009-11-11 18:57:24 +00:00
static const least high_bit = < em > implementation_defined< / em > ;
static const fast high_bit_fast = < em > implementation_defined< / em > ;
2001-12-07 13:19:38 +00:00
static const std::size_t bit_position = Bit;
};
template < std::size_t Bits >
2009-11-11 18:57:24 +00:00
struct low_bits_mask_t
2001-12-07 13:19:38 +00:00
{
2009-11-11 18:57:24 +00:00
typedef < em > implementation_supplied< / em > least;
typedef < em > implementation_supplied< / em > fast;
2001-12-07 13:19:38 +00:00
2009-11-11 18:57:24 +00:00
static const least sig_bits = < em > implementation_defined< / em > ;
static const fast sig_bits_fast = < em > implementation_defined< / em > ;
2001-12-07 13:19:38 +00:00
static const std::size_t bit_count = Bits;
};
2009-11-11 18:57:24 +00:00
// Specializations for low_bits_mask_t exist for certain bit counts.
2001-12-07 13:19:38 +00:00
} // namespace boost
< / pre > < / blockquote >
< h2 > < a name = "single" > Single Bit-Mask Class Template< / a > < / h2 >
< p > The < code > boost::high_bit_mask_t< / code > class template provides
constants for bit masks representing the bit at a certain position. The
masks are equivalent to the value 2< sup > < code > Bit< / code > < / sup > , where
< code > Bit< / code > is the template parameter. The bit position must be a
nonnegative number from zero to < i > Max< / i > , where < dfn > Max< / dfn > 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 < code > high_bit_mask_t< / code > .< / p >
< table border = "1" cellpadding = "5" >
< caption > Members of the < code > boost::high_bit_mask_t< / code > Class
Template< / caption >
< tr >
< th > Member< / th >
< th > Meaning< / th >
< / tr >
< tr >
< td > < code > least< / code > < / td >
< td > The smallest unsigned built-in type that supports the given
bit position.< / td >
< / tr >
< tr >
< td > < code > fast< / code > < / td >
< td > The quick-to-manipulate analog of < code > least< / code > .< / td >
< / tr >
< tr >
< td > < code > high_bit< / code > < / td >
< td > A < code > least< / code > constant of the desired bit-masking
value.< / td >
< / tr >
< tr >
< td > < code > high_bit_fast< / code > < / td >
< td > A < code > fast< / code > analog of < code > high_bit< / code > .< / td >
< / tr >
< tr >
< td > < code > bit_position< / code > < / td >
< td > The value of the template parameter, in case its needed from
a renamed instantiation of the class template.< / td >
< / tr >
< / table >
< h2 > < a name = "group" > Group Bit-Mask Class Template< / a > < / h2 >
< p > The < code > boost::low_bits_mask_t< / code > class template provides
constants for bit masks representing the lowest bits of a certain
amount. The masks are equivalent to the value
(2< sup > < code > Bits< / code > < / sup > - 1), where < code > Bits< / code > is the
template parameter. The bit amount must be a nonnegative number from
zero to < i > Max< / i > , where < dfn > Max< / dfn > is the number of bits supported
by the largest unsigned built-in integral type. The following table
describes the members of an instantiation of
< code > low_bits_mask_t< / code > .< / p >
< table border = "1" cellpadding = "5" >
< caption > Members of the < code > boost::low_bits_mask_t< / code > Class
Template< / caption >
< tr >
< th > Member< / th >
< th > Meaning< / th >
< / tr >
< tr >
< td > < code > least< / code > < / td >
< td > The smallest unsigned built-in type that supports the given
bit count.< / td >
< / tr >
< tr >
< td > < code > fast< / code > < / td >
< td > The quick-to-manipulate analog of < code > least< / code > .< / td >
< / tr >
< tr >
< td > < code > sig_bits< / code > < / td >
< td > A < code > least< / code > constant of the desired bit-masking
value.< / td >
< / tr >
< tr >
< td > < code > sig_bits_fast< / code > < / td >
< td > A < code > fast< / code > analog of < code > sig_bits< / code > .< / td >
< / tr >
< tr >
< td > < code > bit_count< / code > < / td >
< td > The value of the template parameter, in case its needed from
a renamed instantiation of the class template.< / td >
< / tr >
< / table >
2009-11-11 18:57:24 +00:00
< p > < strong > Implementation Note< / strong > < br >
When < code > Bits< / code > is the exact size of a built-in unsigned type,
the implementation has to change to prevent undefined behavior.
Therefore, there are specializations of < code > low_bits_mask_t< / code > at
those bit counts.< / p >
2001-12-07 13:19:38 +00:00
< h2 > < a name = "example" > Example< / a > < / h2 >
< blockquote > < pre >
2009-11-11 18:57:24 +00:00
#include < boost/integer/integer_mask.hpp>
2001-12-07 13:19:38 +00:00
//...
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;
//...
}
< / pre > < / blockquote >
< h2 > < a name = "demo" > Demonstration Program< / a > < / h2 >
< p > The program < a href = "../test/integer_mask_test.cpp" > integer_mask_test.cpp< / a >
is a simplistic demonstration of the results from instantiating various
examples of the bit mask class templates.< / p >
< h2 > < a name = "rationale" > Rationale< / a > < / h2 >
< p > The class templates in this header are an extension of the < a
href="../integer.htm">integer type selection class templates< / a > . 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.< / p >
< h2 > < a name = "credits" > Credits< / a > < / h2 >
< p > The author of the Boost bit mask class templates is < a
2008-02-10 14:56:22 +00:00
href="http://www.boost.org/people/daryle_walker.html">Daryle Walker< / a > .< / p >
2001-12-07 13:19:38 +00:00
< hr >
2009-11-11 18:57:24 +00:00
< p > Revised September 23, 2001< / p >
2001-12-07 13:19:38 +00:00
2006-11-04 22:58:43 +00:00
< p > © Copyright Daryle Walker 2001. Use, modification, and distribution are
subject to the Boost Software License, Version 1.0. (See accompanying file < a
href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt< / a > or a copy at < < a
href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt< / a > > .)< / p >
2001-12-07 13:19:38 +00:00
< / body >
< / html >
