mirror of
https://github.com/boostorg/integer.git
synced 2025-07-20 16:02:14 +02:00
Reverted Integer back to Release branch state - as per devel-list discussions.
[SVN r57580]
This commit is contained in:
John Maddock
@ -8,11 +8,7 @@
|
||||
<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>
|
||||
<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>
|
||||
|
||||
@ -21,7 +17,6 @@ href="../integer.htm">integer type selection templates</a> header.</p>
|
||||
<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="#mpl">MPL-Compatible Variants</a></li>
|
||||
<li><a href="#example">Example</a></li>
|
||||
<li><a href="#demo">Demonstration Program</a></li>
|
||||
<li><a href="#rationale">Rationale</a></li>
|
||||
@ -31,68 +26,39 @@ href="../integer.htm">integer type selection templates</a> header.</p>
|
||||
<h2><a name="synopsis">Synopsis</a></h2>
|
||||
|
||||
<blockquote><pre>
|
||||
#include <<a href="../../../boost/integer_fwd.hpp">boost/integer_fwd.hpp</a>> <i>// forwarding header</i>
|
||||
#include <<a href="../../../boost/integer.hpp">boost/integer.hpp</a>> <i>// for boost::int_fast_t</i>
|
||||
#include <cstddef> <i>// for std::size_t</i>
|
||||
#include <cstddef> <i>// for std::size_t</i>
|
||||
|
||||
namespace boost
|
||||
{
|
||||
|
||||
// MPL-compatible
|
||||
template < int Offset >
|
||||
struct integer_hi_mask
|
||||
{
|
||||
static bool const is_specialized = <em>implementation_supplied</em>;
|
||||
static int const bit_offset = Offset;
|
||||
|
||||
typedef <em>implementation_supplied</em> type;
|
||||
typedef <em>implementation_supplied</em> value_type;
|
||||
static value_type const value = <em>implementation_supplied</em>;
|
||||
// There are other (optional) operations....
|
||||
};
|
||||
|
||||
template < int Length >
|
||||
struct integer_lo_mask
|
||||
{
|
||||
static bool const is_specialized = <em>implementation_supplied</em>;
|
||||
static int const bit_count = Length;
|
||||
|
||||
typedef <em>implementation_supplied</em> type;
|
||||
typedef <em>implementation_supplied</em> value_type;
|
||||
static value_type const value = <em>implementation_supplied</em>;
|
||||
// There are other (optional) operations....
|
||||
};
|
||||
|
||||
// single
|
||||
template < std::size_t Bit >
|
||||
class high_bit_mask_t
|
||||
struct high_bit_mask_t
|
||||
{
|
||||
public:
|
||||
typedef typename integer_hi_mask<Bit>::value_type least;
|
||||
typedef int_fast_t<least>::fast fast;
|
||||
typedef <em>implementation_supplied</em> least;
|
||||
typedef <em>implementation_supplied</em> fast;
|
||||
|
||||
static const least high_bit = integer_hi_mask<Bit>::value;
|
||||
static const fast high_bit_fast = high_bit;
|
||||
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;
|
||||
|
||||
};
|
||||
|
||||
// group
|
||||
template < std::size_t Bits >
|
||||
class low_bits_mask_t
|
||||
struct low_bits_mask_t
|
||||
{
|
||||
public:
|
||||
typedef typename integer_lo_mask<Bits>::value_type least;
|
||||
typedef int_fast_t<least>::fast fast;
|
||||
typedef <em>implementation_supplied</em> least;
|
||||
typedef <em>implementation_supplied</em> fast;
|
||||
|
||||
static const least sig_bits = integer_lo_mask<Bits>::value;
|
||||
static const fast sig_bits_fast = sig_bits;
|
||||
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>
|
||||
|
||||
@ -183,149 +149,16 @@ describes the members of an instantiation of
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h2><a name="mpl">MPL-Compatible Variants</a></h2>
|
||||
|
||||
<p>The single and group bit-mask class templates have several drawbacks:</p>
|
||||
|
||||
<ul>
|
||||
<li>You must know the valid bit-lengths in advance.</li>
|
||||
<li>Using an inappropriate parameter value results in a compiler
|
||||
diagnostic.</li>
|
||||
<li>The type names used are inconsistent with other transformations in
|
||||
Boost, like in <a href="../../mpl/">MPL</a>.</li>
|
||||
<li>The above two facts make use of the regular bit-mask class templates
|
||||
incompatible with template meta-programming techniques.</li>
|
||||
</ul>
|
||||
|
||||
<p>The <code>integer_hi_mask</code> and <code>integer_lo_mask</code> class
|
||||
templates provide MPL-compatible alternatives. These alternatives have the
|
||||
form:</p>
|
||||
|
||||
<blockquote><pre>
|
||||
template< int <var>Size</var> >
|
||||
struct <var>name</var>
|
||||
{
|
||||
static bool const is_specialized = <em>implementation_supplied</em>;
|
||||
static int const <var>switch_id</var> = <var>Size</var>;
|
||||
|
||||
typedef <em>implementation_supplied</em> type;
|
||||
typedef <em>implementation_supplied</em> value_type;
|
||||
static value_type const value = <em>implementation_supplied</em>;
|
||||
// with other operations...
|
||||
};
|
||||
</pre></blockquote>
|
||||
|
||||
<p>Only some of the members are always present. The presence of other members
|
||||
and operations is flagged by the (always-present) <code>is_specialized</code>.</p>
|
||||
|
||||
<table border="2" cellpadding="5" align="center">
|
||||
<caption>Permanent Members of the MPL-Compatible Masking Class Template
|
||||
Types</caption>
|
||||
<tr>
|
||||
<th>Class Template Member</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>is_specialized</code></td>
|
||||
<td>Flag indicating when a particular template class instantiation is a
|
||||
valid meta-function (<code>true</code>) or not (<code>false</code>).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><var>switch_id</var></code> (Actual name is template-specific.)</td>
|
||||
<td>The value of the main control parameter, accessible even if the
|
||||
template class instantiation is aliased.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>The optional members are based from inheriting from a <a
|
||||
href="../../mpl/doc/refmanual/integral-constant.html">MPL-style Integral
|
||||
Constant</a> type, but only if <code>is_specialized</code> is <code>true</code>.</p>
|
||||
|
||||
<table border="2" cellpadding="5" align="center">
|
||||
<caption>Optional Members of the MPL-Compatible Masking Types</caption>
|
||||
<tr>
|
||||
<th>Class Template Member</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>value</code></td>
|
||||
<td>The actual bit mask.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>value_type</code></td>
|
||||
<td>The type of the bit mask value.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>type</code></td>
|
||||
<td>The Integral Constant</a> implementation type, which should be
|
||||
<code><a href="../../mpl/doc/refmanual/integral-c.html">boost::mpl::
|
||||
integral_c</a>< <var>value_type</var>, <var>value</var>
|
||||
></code>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>The Integral Constant prototype also adds the following operations:</p>
|
||||
|
||||
<table border="2" cellpadding="5" align="center">
|
||||
<caption>Optional Operations of the MPL-Compatible Masking Types</caption>
|
||||
<tr>
|
||||
<th>Operation (with <var>n</var> as a masking type)</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>boost::mpl::next< n >::type</code></td>
|
||||
<td><code>boost::mpl::next< n::type >::type</code>, i.e.
|
||||
<code>boost::mpl::integral_c< n::value_type, n::value + 1
|
||||
></code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>boost::mpl::prior< n >::type</code></td>
|
||||
<td><code>boost::mpl::prior< n::type >::type</code>, i.e.
|
||||
<code>boost::mpl::integral_c< n::value_type, n::value - 1
|
||||
></code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>n::value_type const c = n();</code></td>
|
||||
<td><var>c</var> is set to <code>n::value</code>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>The specifics for each masking class template are:</p>
|
||||
|
||||
<table border="2" cellpadding="5" align="center">
|
||||
<caption>Criteria for the MPL-Compatible Masking Types<br>
|
||||
(Everything besides the parameter ID is in name-space
|
||||
<code>boost</code> except where indicated.)</caption>
|
||||
<tr>
|
||||
<th>Class Template</th>
|
||||
<th>Parameter Member ID</th>
|
||||
<th>Classic Equivalent</th>
|
||||
<th>Value Type</th>
|
||||
<th>Value</th>
|
||||
<th>Valid Range</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>integer_hi_mask</code></td>
|
||||
<td><code>bit_offset</code></td>
|
||||
<td><code>high_bit_mask_t</code></td>
|
||||
<td><code>sized_integral < bit_offset + 1, unsigned ></code></td>
|
||||
<td>2<sup><code>bit_offset</code></sup></td>
|
||||
<td><code>0 <= bit_offset < std::numeric_limits< uintmax_t >::digits</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>integer_lo_mask</code></td>
|
||||
<td><code>bit_count</code></td>
|
||||
<td><code>low_bits_mask_t</code></td>
|
||||
<td><code>sized_integral < bit_count, unsigned ></code></td>
|
||||
<td>2<sup><code>bit_offset</code></sup> - 1</td>
|
||||
<td><code>0 <= bit_count <= std::numeric_limits< uintmax_t >::digits</code></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 <<a href="../../../boost/integer/integer_mask.hpp">boost/integer/integer_mask.hpp</a>>
|
||||
#include <boost/integer/integer_mask.hpp>
|
||||
|
||||
//...
|
||||
|
||||
@ -367,7 +200,7 @@ href="http://www.boost.org/people/daryle_walker.html">Daryle Walker</a>.</p>
|
||||
|
||||
<hr>
|
||||
|
||||
<p>Revised July 29, 2008</p>
|
||||
<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
|
||||
|
||||
Reference in New Issue
Block a user