mirror of
https://github.com/boostorg/integer.git
synced 2025-11-04 02:01:38 +01:00
211 lines
6.8 KiB
HTML
211 lines
6.8 KiB
HTML
<!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">
|
|
<h1><img src="../../../boost.png" alt="boost.png (6897 bytes)"
|
|
align="middle" width="277" height="86">Integer Bit Mask Templates</h1>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
#include <cstddef> <i>// for std::size_t</i>
|
|
|
|
namespace boost
|
|
{
|
|
|
|
template < std::size_t Bit >
|
|
struct high_bit_mask_t
|
|
{
|
|
typedef <em>implementation_supplied</em> least;
|
|
typedef <em>implementation_supplied</em> fast;
|
|
|
|
static const least high_bit = <em>implementation_defined</em>;
|
|
static const fast high_bit_fast = <em>implementation_defined</em>;
|
|
|
|
static const std::size_t bit_position = Bit;
|
|
|
|
};
|
|
|
|
template < std::size_t Bits >
|
|
struct low_bits_mask_t
|
|
{
|
|
typedef <em>implementation_supplied</em> least;
|
|
typedef <em>implementation_supplied</em> fast;
|
|
|
|
static const least sig_bits = <em>implementation_defined</em>;
|
|
static const fast sig_bits_fast = <em>implementation_defined</em>;
|
|
|
|
static const std::size_t bit_count = Bits;
|
|
|
|
};
|
|
|
|
// Specializations for low_bits_mask_t exist for certain bit counts.
|
|
|
|
} // 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>
|
|
|
|
<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>
|
|
|
|
<h2><a name="example">Example</a></h2>
|
|
|
|
<blockquote><pre>
|
|
#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;
|
|
|
|
//...
|
|
}
|
|
</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
|
|
href="http://www.boost.org/people/daryle_walker.html">Daryle Walker</a>.</p>
|
|
|
|
<hr>
|
|
|
|
<p>Revised September 23, 2001</p>
|
|
|
|
<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>
|
|
</body>
|
|
</html>
|