boostorg/integer
1
0
Fork 1
mirror of https://github.com/boostorg/integer.git synced 2025-07-25 02:07:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

initial checkin

Browse Source 
[SVN r11972]
This commit is contained in:
Dave Abrahams
2001-12-07 13:19:38 +00:00
parent c50993d5d4
commit 3bb567ad9d
6 changed files with 811 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
doc/integer_mask.html Normal file
View File

@ -0,0 +1,211 @@
<!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="../../../c++boost.gif" alt="c++boost.gif (8819 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">&lt;boost/integer/integer_mask.hpp&gt;</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 &lt;cstddef&gt; <i>// for std::size_t</i>
namespace boost
{
template &lt; std::size_t Bit &gt;
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 &lt; std::size_t Bits &gt;
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 &lt;boost/integer/integer_mask.hpp&gt;
//...
int main()
{
typedef boost::high_bit_mask_t&lt;29&gt; mask1_type;
typedef boost::low_bits_mask_t&lt;15&gt; mask2_type;
mask1_type::least my_var1;
mask2_type::fast my_var2;
//...
my_var1 |= mask1_type::high_bit;
my_var2 &amp;= 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="../../../people/daryle_walker.html">Daryle Walker</a>.</p>
<hr>
<p>Revised September 23, 2001</p>
<p>&copy; 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
&quot;as is&quot; without express or implied warranty, and with no claim
as to its suitability for any purpose.</p>
</body>
</html>

122
doc/static_log2.html Normal file
View File

@ -0,0 +1,122 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>Binary Logarithm Template</title>
</head>
<body bgcolor="white" text="black">
<h1><img src="../../../c++boost.gif" alt="c++boost.gif (8819 bytes)"
align="middle" width="277" height="86">Binary Logarithm Template</h1>
<p>The class template in <cite><a href="../../../boost/integer/static_log2.hpp">&lt;boost/integer/static_log2.hpp&gt;</a></cite> determines the position of the highest bit in a given value. This facility is useful for solving generic programming problems.</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="#usage">Usage</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>
namespace boost
{
template &lt; unsigned long Value &gt;
struct static_log2
{
static const int value = <em>implementation_defined</em>;
};
template &lt; &gt;
struct static_log2&lt; 0ul &gt;
{
// The logarithm of zero is undefined.
};
} // namespace boost
</pre></blockquote>
<h2><a name="usage">Usage</a></h2>
<p>The <code>boost::static_log2</code> class template takes one template
parameter, a value of type <code>unsigned long</code>. The template
only defines one member, <code>value</code>, that returns the truncated
base-two logarithm of the template parameter.</p>
<p>Since the logarithm of zero, for any base, is undefined, there is a
specialization of <code>static_log2</code> for a template parameter
of zero. This specialization has no members, so an attempt to use
the base-two logarithm of zero results in a compile-time error.</p>
<h2><a name="example">Example</a></h2>
<blockquote><pre>
#include &lt;boost/integer/static_log2.hpp&gt;
template &lt; unsigned long Value &gt;
bool is_it_what()
{
typedef boost::static_log2&lt;Value&gt; lb_type;
int temp = lb_type::value;
//...
return (temp % 2) != 0;
}
//...
int main()
{
bool temp = is_it_what&lt;2000&gt;();
//...
#if 0
temp = is_it_what&lt;0&gt;(); // would give an error
#endif
//...
temp = is_it_what&lt;24&gt;();
//...
}
</pre></blockquote>
<h2><a name="demo">Demonstration Program</a></h2>
<p>The program <a href="../test/static_log2_test.cpp">static_log2_test.cpp</a>
is a simplistic demonstration of the results from instantiating various
examples of the binary logarithm class template.</p>
<h2><a name="rationale">Rationale</a></h2>
<p>The base-two (binary) logarithm, abbreviated <dfn>lb</dfn>, function
is occasionally used to give order-estimates of computer algorithms.
The truncated logarithm can be considered the highest power-of-two in a
value, which corresponds to the value's highest set bit (for binary
integers). Sometimes the highest-bit position could be used in generic
programming, which requires the position to be statically (<i>i.e.</i>
at compile-time) available.</p>
<h2><a name="credits">Credits</a></h2>
<p>The author of the Boost binary logarithm class template is <a
href="../../../people/daryle_walker.html">Daryle Walker</a>.</p>
<hr>
<p>Revised October 1, 2001</p>
<p>&copy; 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
&quot;as is&quot; without express or implied warranty, and with no claim
as to its suitability for any purpose.</p>
</body>
</html>

121
doc/static_min_max.html Normal file
View File

@ -0,0 +1,121 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>Compile-Time Extrema Templates</title>
</head>
<body bgcolor="white" text="black" link="blue" alink="red" vlink="purple">
<h1><img src="../../../c++boost.gif" alt="c++boost.gif (8819 bytes)"
align="middle" width="277" height="86">Compile-Time Extrema
Templates</h1>
<p>The class templates in <cite><a
href="../../../boost/integer/static_min_max.hpp">&lt;boost/integer/static_min_max.hpp&gt;</a></cite>
provide a compile-time evaluation of the minimum or maximum of
two integers. These facilities are useful for generic programming problems.</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="#usage">Usage</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>
namespace boost
{
template &lt; long Value1, long Value2 &gt;
struct static_signed_min;
template &lt; long Value1, long Value2 &gt;
struct static_signed_max;
template &lt; unsigned long Value1, unsigned long Value2 &gt;
struct static_unsigned_min;
template &lt; unsigned long Value1, unsigned long Value2 &gt;
struct static_unsigned_max;
}
</pre></blockquote>
<h2><a name="usage">Usage</a></h2>
<p>The four class templates provide the combinations for finding the
minimum or maximum of two signed or <code>unsigned</code>
(<code>long</code>) parameters, <var>Value1</var> and <var>Value2</var>,
at compile-time. Each template has a single static data member,
<code>value</code>, which is set to the respective minimum or maximum
of the template's parameters.</p>
<h2><a name="example">Example</a></h2>
<blockquote><pre>
#include &lt;boost/integer/static_min_max.hpp&gt;
template &lt; unsigned long AddendSize1, unsigned long AddendSize2 &gt;
class adder
{
public:
static unsigned long const addend1_size = AddendSize1;
static unsigned long const addend2_size = AddendSize2;
static unsigned long const sum_size = boost::static_unsigned_max&lt;AddendSize1, AddendSize2&gt;::value + 1;
typedef int addend1_type[ addend1_size ];
typedef int addend2_type[ addend2_size ];
typedef int sum_type[ sum_size ];
void operator ()( addend1_type const &amp;a1, addend2_type const &amp;a2, sum_type &amp;s ) const;
};
//...
int main()
{
int const a1[] = { 0, 4, 3 }; // 340
int const a2[] = { 9, 8 }; // 89
int s[ 4 ];
adder&lt;3,2&gt; obj;
obj( a1, a2, s ); // 's' should be 429 or { 9, 2, 4, 0 }
//...
}
</pre></blockquote>
<h2><a name="demo">Demonstration Program</a></h2>
<p>The program <a
href="../test/static_min_max_test.cpp">static_min_max_test.cpp</a> is a
simplistic demonstration of various comparisons using the compile-time
extrema class templates.</p>
<h2><a name="rationale">Rationale</a></h2>
<p>Sometimes the minimum or maximum of several values needs to be found
for later compile-time processing, <i>e.g.</i> for a bound for another
class template.</p>
<h2><a name="credits">Credits</a></h2>
<p>The author of the Boost compile-time extrema class templates is <a
href="../../../../people/daryle_walker.html">Daryle Walker</a>.</p>
<hr>
<p>Revised October 12, 2001</p>
<p>&copy; 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
&quot;as is&quot; without express or implied warranty, and with no claim
as to its suitability for any purpose.</p>
</body>
</html>