1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
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"><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="../../../people/daryle_walker.html">Daryle Walker</a>.</p>
<hr>
<p>Revised September 23, 2001</p>
<p>© 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
"as is" without express or implied warranty, and with no claim
as to its suitability for any purpose.</p>
</body>
</html>
|
