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
{
2008-07-29 19:33:20 +00:00
template < std::size_t Bit >
2009-11-11 18:57:24 +00:00
struct high_bit_mask_t
2008-07-29 19:33:20 +00:00
{
2009-11-11 18:57:24 +00:00
typedef < em > implementation_supplied</ em > least;
typedef < em > implementation_supplied</ em > fast;
2008-07-29 19:33:20 +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 >
