Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/integer/integer.htm @ 20

Last change on this file since 20 was 12, checked in by landauf, 18 years ago

added boost
File size: 6.9 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2<html>
3<head>
4<title>Integer Type Selection Templates</title>
5</head>
6
7<body bgcolor="white" text="black">
8<h1>
9<img src="../../boost.png" alt="boost.png (6897 bytes)"
10align="middle" width="277" height="86">Integer Type Selection
11Templates</h1>
12
13<p>The <cite><a
14href="../../boost/integer.hpp">&lt;boost/integer.hpp&gt;</a></cite> type
15selection templates allow integer types to be selected based on desired
16characteristics such as number of bits or maximum value.  This facility
17is particularly useful for solving generic programming problems.</p>
18
19<h2><a name="contents">Contents</a></h2>
20
21<ul>
22        <li><a href="#contents">Contents</a></li>
23        <li><a href="#synopsis">Synopsis</a></li>
24        <li><a href="#easy">Easiest-to-Manipulate Types</a></li>
25        <li><a href="#sized">Sized Types</a></li>
26        <li><a href="#example">Example</a></li>
27        <li><a href="#demo">Demonstration Program</a></li>
28        <li><a href="#rationale">Rationale</a></li>
29        <li><a href="#alternative">Alternative</a></li>
30        <li><a href="#credits">Credits</a></li>
31</ul>
32
33<h2><a name="synopsis">Synopsis</a></h2>
34
35<blockquote><pre>namespace boost
36{
37  //  fast integers from least integers
38  template&lt; typename LeastInt &gt;
39  struct int_fast_t
40  {
41      typedef <em>implementation_supplied</em>  fast;
42  };
43
44  //  signed
45  template&lt; int Bits &gt;
46  struct int_t
47  {
48      typedef <em>implementation_supplied</em>  least;
49      typedef int_fast_t&lt;least&gt;::fast  fast;
50  };
51
52  //  unsigned
53  template&lt; int Bits &gt;
54  struct uint_t
55  {
56      typedef <em>implementation_supplied</em>  least;
57      typedef int_fast_t&lt;least&gt;::fast  fast;
58  };
59
60  //  signed
61  template&lt; long MaxValue &gt;
62  struct int_max_value_t
63  {
64      typedef <em>implementation_supplied</em>  least;
65      typedef int_fast_t&lt;least&gt;::fast  fast;
66  };
67
68  template&lt; long MinValue &gt;
69  struct int_min_value_t
70  {
71      typedef <em>implementation_supplied</em>  least;
72      typedef int_fast_t&lt;least&gt;::fast  fast;
73  };
74
75  //  unsigned
76  template&lt; unsigned long Value &gt;
77  struct uint_value_t
78  {
79      typedef <em>implementation_supplied</em>  least;
80      typedef int_fast_t&lt;least&gt;::fast  fast;
81  };
82} // namespace boost
83</pre></blockquote>
84
85<h2><a name="easy">Easiest-to-Manipulate Types</a></h2>
86
87<p>The <code>int_fast_t</code> class template maps its input type to the
88next-largest type that the processor can manipulate the easiest, or to
89itself if the input type is already an easy-to-manipulate type.  For
90instance, processing a bunch of <code>char</code> objects may go faster
91if they were converted to <code>int</code> objects before processing.
92The input type, passed as the only template parameter, must be a
93built-in integral type, except <code>bool</code>.  Unsigned integral
94types can be used, as well as signed integral types, despite the name.
95The output type is given as the class member <code>fast</code>.</p>
96
97<p><strong>Implementation Notes</strong><br>
98By default, the output type is identical to the input type.  Eventually,
99this code's implementation should be conditionalized for each platform
100to give accurate mappings between the built-in types and the
101easiest-to-manipulate built-in types.  Also, there is no guarantee that
102the output type actually is easier to manipulate than the input
103type.</p>
104
105<h2><a name="sized">Sized Types</a></h2>
106
107<p>The <code>int_t</code>, <code>uint_t</code>,
108<code>int_max_value_t</code>, <code>int_min_value_t</code>, and
109<code>uint_value_t</code> class templates find the most appropiate
110built-in integral type for the given template parameter.  This type is
111given by the class member <code>least</code>.  The easiest-to-manipulate
112version of that type is given by the class member <code>fast</code>.
113The following table describes each template's criteria.</p>
114
115<table border="1" cellpadding="5">
116        <caption>Criteria for the Sized Type Class Templates</caption>
117        <tr>
118                <th>Class Template</th>
119                <th>Template Parameter Mapping</th>
120        </tr>
121        <tr>
122                <td><code>boost::int_t</code></td>
123                <td>The smallest built-in signed integral type with at least the
124                        given number of bits, including the sign bit.  The parameter
125                        should be a positive number.  A compile-time error results if
126                        the parameter is larger than the number of bits in a
127                        <code>long</code>.</td>
128        </tr>
129        <tr>
130                <td><code>boost::uint_t</code></td>
131                <td>The smallest built-in unsigned integral type with at least
132                        the given number of bits.  The parameter should be a positive
133                        number.  A compile-time error results if the parameter is
134                        larger than the number of bits in an <code>unsigned
135                        long</code>.</td>
136        </tr>
137        <tr>
138                <td><code>boost::int_max_value_t</code></td>
139                <td>The smallest built-in signed integral type that supports the
140                        given value as a maximum.  The parameter should be a
141                        positive number.</td>
142        </tr>
143        <tr>
144                <td><code>boost::int_min_value_t</code></td>
145                <td>The smallest built-in signed integral type that supports the
146                        given value as a minimum.  The parameter should be a
147                        negative number.</td>
148        </tr>
149        <tr>
150                <td><code>boost::uint_value_t</code></td>
151                <td>The smallest built-in unsigned integral type that supports
152                        the given value as a maximum.  The parameter should be a
153                        positive number.</td>
154        </tr>
155</table>
156
157<h2><a name="example">Example</a></h2>
158
159<blockquote><pre>#include &lt;boost/integer.hpp&gt;
160
161//...
162
163int main()
164{
165    boost::int_t&lt;24&gt;::least my_var;
166    //...
167}
168</pre></blockquote>
169
170<h2><a name="demo">Demonstration Program</a></h2>
171
172<p>The program <a href="integer_test.cpp">integer_test.cpp</a> is a
173simplistic demonstration of the results from instantiating various
174examples of the sized type class templates.</p>
175
176<h2><a name="rationale">Rationale</a></h2>
177
178<p>The rationale for the design of the templates in this header includes:</p>
179
180<ul>
181        <li>Avoid recursion because of concern about C++'s limited
182                guaranteed recursion depth (17).</li>
183        <li>Avoid macros on general principles.</li>
184        <li>Try to keep the design as simple as possible.</li>
185</ul>
186
187<h2><a name="alternative">Alternative</a></h2>
188
189<p>If the number of bits required is known beforehand, it may be more
190appropriate to use the types supplied in <cite><a
191href="../../boost/cstdint.hpp">&lt;boost/cstdint.hpp&gt;</a></cite>.</p>
192
193<h2><a name="credits">Credits</a></h2>
194
195<p>The author of most of the Boost integer type choosing templates is <a
196href="../../people/beman_dawes.html">Beman Dawes</a>.  He gives thanks
197to Valentin Bonnard and
198<a href="../../people/kevlin_henney.htm"> Kevlin Henney</a> for sharing
199their designs for similar templates.  <a
200href="../../people/daryle_walker.html">Daryle Walker</a> designed the
201value-based sized templates.</p>
202
203<hr>
204
205<p>Revised May 20, 2001</p>
206
207<p>&copy; Copyright Beman Dawes 1999.  Permission to copy, use, modify,
208sell and distribute this document is granted provided this copyright
209notice appears in all copies.  This document is provided &quot;as
210is&quot; without express or implied warranty, and with no claim as to
211its suitability for any purpose.</p>
212</body>
213</html>
Note: See TracBrowser for help on using the repository browser.