feedc0de/boost_integer
1
0
Fork 0
forked from boostorg/integer
Code Pull Requests Activity

Integrated Daryle Walker's dlw_int.zip changes

Browse Source 
[SVN r11866]
This commit is contained in:
Dave Abrahams
2001-12-03 03:29:57 +00:00
parent 24e6bfbfaa
commit 162c6aefa1
4 changed files with 533 additions and 423 deletions
Download Patch File Download Diff File Expand all files Collapse all files

236
integer.htm
View File

@ -1,112 +1,214 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Integer Type Selection Templates</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<body bgcolor="white" text="black">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)"
align="middle" width="277" height="86">Integer Type Selection
Templates</h1>
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" width="277" height="86">Integer
Type Selection Templates</h1>
<p>The <code><a href="../../boost/integer.hpp">&lt;boost/integer.hpp&gt;</a></code>
type selection templates allow integer types to be selected based on desired
characteristics such as number of bits or maximum value.&nbsp; This facility is
particularly useful for solving generic programming problems.</p>
<p>The <cite><a
href="../../boost/integer.hpp">&lt;boost/integer.hpp&gt;</a></cite> type
selection templates allow integer types to be selected based on desired
characteristics such as number of bits or maximum value. This facility
is particularly useful for solving generic programming problems.</p>
<p>The templates <b>int_t&lt;&gt;</b> and <b>uint_t&lt;&gt;</b> supply typedefs <b>least</b>
and <b>fast</b>.&nbsp; The <b>least</b> type be the smallest type which holds at
least the number of bits (including sign) specified. The <b>fast</b> type will
be at least as large as the <b>least</b> type, but may possible be larger.&nbsp;
There is no guarantee that the <b>fast</b> type will actually be faster than
other possible types.</p>
<h2><a name="contents">Contents</a></h2>
<h2>Alternative</h2>
<ul>
<li><a href="#contents">Contents</a></li>
<li><a href="#synopsis">Synopsis</a></li>
<li><a href="#easy">Easiest-to-Manipulate Types</a></li>
<li><a href="#sized">Sized Types</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="#alternative">Alternative</a></li>
<li><a href="#credits">Credits</a></li>
</ul>
<p>If the number of bits required is known beforehand, it may be more
appropriate to use the types supplied in <code><a href="../../boost/cstdint.hpp">&lt;boost/cstdint.hpp&gt;</a></code>.</p>
<h2><a name="synopsis">Synopsis</a></h2>
<h2>Synopsis</h2>
<blockquote>
<pre>namespace boost
<blockquote><pre>
namespace boost
{
// fast integers from least integers
// int_fast_t&lt;&gt; works correctly for unsigned too, in spite of the name.
template&lt; typename LeastInt &gt; // Required: LeastInt is integral type, not bool
struct int_fast_t { typedef LeastInt fast; }; // implementations may specialize
template&lt; typename LeastInt &gt;
struct int_fast_t
{
typedef <em>implementation_supplied</em> fast;
};
// signed
template&lt; int Bits &gt; // bits (including sign) required, 0-32 valid
template&lt; int Bits &gt;
struct int_t
{
typedef <i>implementation-supplied</i> least;
typedef <em>implementation_supplied</em> least;
typedef int_fast_t&lt;least&gt;::fast fast;
};
// unsigned
template&lt; int Bits &gt; // bits required, 0-32 valid
template&lt; int Bits &gt;
struct uint_t
{
typedef <i>implementation-supplied</i> least;
typedef <em>implementation_supplied</em> least;
typedef int_fast_t&lt;least&gt;::fast fast;
};
// signed
template&lt; long MaxValue &gt;
struct int_max_value_t
{
typedef <em>implementation_supplied</em> least;
typedef int_fast_t&lt;least&gt;::fast fast;
};
template&lt; long MinValue &gt;
struct int_min_value_t
{
typedef <em>implementation_supplied</em> least;
typedef int_fast_t&lt;least&gt;::fast fast;
};
// unsigned
template&lt; unsigned long Value &gt;
struct uint_value_t
{
typedef <em>implementation_supplied</em> least;
typedef int_fast_t&lt;least&gt;::fast fast;
// int_fast_t&lt;&gt; works correctly for unsigned too, in spite of the name.
};
} // namespace boost
</pre>
</pre></blockquote>
</blockquote>
<p>[Templates to select type based on maximum value are under development.]
</p>
<h2><a name="easy">Easiest-to-Manipulate Types</a></h2>
<h2>Example</h2>
<p>The <code>int_fast_t</code> class template maps its input type to the
next-largest type that the processor can manipulate the easiest, or to
itself if the input type is already an easy-to-manipulate type. For
instance, processing a bunch of <code>char</code> objects may go faster
if they were converted to <code>int</code> objects before processing.
The input type, passed as the only template parameter, must be a
built-in integral type, except <code>bool</code>. Unsigned integral
types can be used, as well as signed integral types, despite the name.
The output type is given as the class member <code>fast</code>.</p>
<blockquote>
<pre>#include &lt;boost/integer.hpp&gt;
using boost::int_t;
<p><strong>Implementation Notes</strong><br>
By default, the output type is identical to the input type. Eventually,
this code's implementation should be conditionalized for each platform
to give accurate mappings between the built-in types and the
easiest-to-manipulate built-in types. Also, there is no guarantee that
the output type actually is easier to manipulate than the input
type.</p>
...
int_t&lt;24&gt;::least my_var; </pre>
<h2><a name="sized">Sized Types</a></h2>
</blockquote>
<h2>Demonstration Program</h2>
<p>The <code>int_t</code>, <code>uint_t</code>,
<code>int_max_value_t</code>, <code>int_min_value_t</code>, and
<code>uint_value_t</code> class templates find the most appropiate
built-in integral type for the given template parameter. This type is
given by the class member <code>least</code>. The easiest-to-manipulate
version of that type is given by the class member <code>fast</code>.
The following table describes each template's criteria.</p>
<p>The program <a href="integer_test.cpp">integer_test.cpp</a> is a not very
smart demonstration of the results from instantiating various <b>int_t&lt;&gt;</b>
and <b>uint_t&lt;&gt;</b> examples.</p>
<table border="1" cellpadding="5">
<caption>Criteria for the Sized Type Class Templates</caption>
<tr>
<th>Class Template</th>
<th>Template Parameter Mapping</th>
</tr>
<tr>
<td><code>boost::int_t</code></td>
<td>The smallest built-in signed integral type with at least the
given number of bits, including the sign bit. The parameter
should be a positive number. A compile-time error results if
the parameter is larger than the number of bits in a
<code>long</code>.</td>
</tr>
<tr>
<td><code>boost::uint_t</code></td>
<td>The smallest built-in unsigned integral type with at least
the given number of bits. The parameter should be a positive
number. A compile-time error results if the parameter is
larger than the number of bits in an <code>unsigned
long</code>.</td>
</tr>
<tr>
<td><code>boost::int_max_value_t</code></td>
<td>The smallest built-in signed integral type that supports the
given value as a maximum. The parameter should be a
positive number.</td>
</tr>
<tr>
<td><code>boost::int_min_value_t</code></td>
<td>The smallest built-in signed integral type that supports the
given value as a minimum. The parameter should be a
negative number.</td>
</tr>
<tr>
<td><code>boost::uint_value_t</code></td>
<td>The smallest built-in unsigned integral type that supports
the given value as a maximum. The parameter should be a
positive number.</td>
</tr>
</table>
<h2>Rationale</h2>
<h2><a name="example">Example</a></h2>
<blockquote><pre>
#include &lt;boost/integer.hpp&gt;
//...
int main()
{
boost::int_t&lt;24&gt;::least my_var;
//...
}
</pre></blockquote>
<h2><a name="demo">Demonstration Program</a></h2>
<p>The program <a href="integer_test.cpp">integer_test.cpp</a> is a
simplistic demonstration of the results from instantiating various
examples of the sized type class templates.</p>
<h2><a name="rationale">Rationale</a></h2>
<p>The rationale for the design of the templates in this header includes:</p>
<ul>
<li>Avoid&nbsp; recursion because of concern about C++'s limited guaranteed
recursion depth (17).</li>
<li>Avoid macros on general principles.</li>
<li>Try to keep the design as simple as possible.</li>
<li>Avoid recursion because of concern about C++'s limited
guaranteed recursion depth (17).</li>
<li>Avoid macros on general principles.</li>
<li>Try to keep the design as simple as possible.</li>
</ul>
<h2>Credits</h2>
<h2><a name="alternative">Alternative</a></h2>
<p>The author of the Boost integer type choosing templates is <a href="../../people/beman_dawes.html">Beman
Dawes</a>.&nbsp; He thanks to <a href="../../people/valentin_bonnard.htm"> Valentin Bonnard</a> and
<a href="../../people/kevlin_henney.htm"> Kevlin Henney</a> for sharing their designs for similar templates.</p>
<p>If the number of bits required is known beforehand, it may be more
appropriate to use the types supplied in <cite><a
href="../../boost/cstdint.hpp">&lt;boost/cstdint.hpp&gt;</a></cite>.</p>
<h2><a name="credits">Credits</a></h2>
<p>The author of most of the Boost integer type choosing templates is <a
href="../../people/beman_dawes.html">Beman Dawes</a>. He gives thanks
to <a href="../../people/valentin_bonnard.htm">Valentin Bonnard</a> and
<a href="../../people/kevlin_henney.htm"> Kevlin Henney</a> for sharing
their designs for similar templates. <a
href="../../people/daryle_walker.html">Daryle Walker</a> designed the
value-based sized templates.</p>
<hr>
<p>Revised&nbsp; August 31, 1999</p>
<p><EFBFBD> Copyright Beman Dawes 1999. 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>
<p></p>
<p>&nbsp;</p>
<p>Revised May 20, 2001</p>
<p>&copy; Copyright Beman Dawes 1999. 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>