]>
Commit | Line | Data |
---|---|---|
1 | [article Boost.Integer | |
2 | [quickbook 1.6] | |
3 | [compatibility-mode 1.5] | |
4 | [copyright 2001-2009 Beman Dawes, Daryle Walker, Gennaro Prota, John Maddock] | |
5 | [purpose Integer Type Selection] | |
6 | [license | |
7 | Distributed under the Boost Software License, Version 1.0. | |
8 | (See accompanying file LICENSE_1_0.txt or copy at | |
9 | [@http://www.boost.org/LICENSE_1_0.txt]) | |
10 | ] | |
11 | [authors [Dawes, Beman], [Walker, Daryle], [Prota, Gennaro], [Maddock, John]] | |
12 | [/last-revision $Date: 2008-02-21 12:58:15 +0000 (Thu, 21 Feb 2008) $] | |
13 | ] | |
14 | ||
15 | [template super[x]'''<superscript>'''[x]'''</superscript>'''] | |
16 | ||
17 | [section:overview Overview] | |
18 | ||
19 | Boost.Integer provides integer type support, particularly helpful in generic programming. | |
20 | It provides the means to select an integer type based upon its properties, like the number of bits or | |
21 | the maximum supported value, as well as compile-time bit mask selection. There is a derivative of | |
22 | std::numeric_limits that provides integral constant expressions for `min` and `max`. | |
23 | Finally, it provides two compile-time algorithms: determining the highest power of two in a | |
24 | compile-time value; and computing min and max of constant expressions. | |
25 | ||
26 | [table | |
27 | [[Component][Header][Purpose]] | |
28 | [ | |
29 | [Forward Declarations.] | |
30 | [[^[@../../../../boost/integer_fwd.hpp <boost/integer_fwd.hpp>]]] | |
31 | [Forward declarations of classes and class templates - for use when just the name of a class is needed.] | |
32 | ] | |
33 | [ | |
34 | [[link boost_integer.traits Integer Traits].] | |
35 | [[^[@../../../../boost/integer_traits.hpp <boost/integer_traits.hpp>]]] | |
36 | [Class template [^boost::integer_traits], derives from [^std::numeric_limits] and adds [^const_min] and [^const_max] members.] | |
37 | ] | |
38 | [ | |
39 | [[link boost_integer.integer Integer Type Selection].] | |
40 | [[^[@../../../../boost/integer.hpp <boost/integer.hpp>]]] | |
41 | [Templates for integer type selection based on properties such as maximum value or number of bits: | |
42 | Use to select the type of an integer when some property such as maximum value or number of bits is known. | |
43 | Useful for generic programming. ] | |
44 | ] | |
45 | [ | |
46 | [[link boost_integer.mask Integer Masks].] | |
47 | [[^[@../../../../boost/integer/integer_mask.hpp <boost/integer/integer_mask.hpp>]]] | |
48 | [Templates for the selection of integer masks, single or lowest group, based on the number of bits: | |
49 | Use to select a particular mask when the bit position(s) are based on a compile-time variable. Useful for generic programming. ] | |
50 | ] | |
51 | [ | |
52 | [[link boost_integer.log2 Compile time log2 Calculation].] | |
53 | [[^[@../../../../boost/integer/static_log2.hpp <boost/integer/static_log2.hpp>]]] | |
54 | [Template for finding the highest power of two in a number: | |
55 | Use to find the bit-size/range based on a maximum value. Useful for generic programming. ] | |
56 | ] | |
57 | [ | |
58 | [[link boost_integer.minmax Compile time min/max calculation].] | |
59 | [[^[@../../../../boost/integer/static_min_max.hpp <boost/integer/static_min_max.hpp>]]] | |
60 | [Templates for finding the extrema of two numbers: | |
61 | Use to find a bound based on a minimum or maximum value. Useful for generic programming. ] | |
62 | ] | |
63 | ] | |
64 | ||
65 | [endsect] | |
66 | ||
67 | [section:traits Integer Traits] | |
68 | ||
69 | [section Motivation] | |
70 | ||
71 | The C++ Standard Library <limits> header supplies a class template `numeric_limits<>` with specializations for each fundamental type. | |
72 | ||
73 | For integer types, the interesting members of `std::numeric_limits<>` are: | |
74 | ||
75 | static const bool is_specialized; // Will be true for integer types. | |
76 | static T min() throw(); // Smallest representable value. | |
77 | static T max() throw(); // Largest representable value. | |
78 | static const int digits; // For integers, the number of value bits. | |
79 | static const int digits10; // The number of base 10 digits that can be represented. | |
80 | static const bool is_signed; // True if the type is signed. | |
81 | static const bool is_integer; // Will be true for all integer types. | |
82 | ||
83 | For many uses, these are sufficient. | |
84 | But min() and max() are problematical because they are not constant expressions (std::5.19), | |
85 | yet some usages require constant expressions. | |
86 | ||
87 | The template class [^integer_traits] addresses this problem. | |
88 | ||
89 | [endsect] | |
90 | ||
91 | [section Synopsis] | |
92 | ||
93 | namespace boost { | |
94 | template<class T> | |
95 | class integer_traits : public std::numeric_limits<T> | |
96 | { | |
97 | public: | |
98 | static const bool is_integral = false; | |
99 | // | |
100 | // These members are defined only if T is a built-in | |
101 | // integal type: | |
102 | // | |
103 | static const T const_min = ``['implementation-defined]``; | |
104 | static const T const_max = ``['implementation-defined]``; | |
105 | }; | |
106 | } | |
107 | ||
108 | [endsect] | |
109 | ||
110 | [section Description] | |
111 | ||
112 | Template class [^integer_traits] is derived from [^std::numeric_limits]. The primary specialization adds the single | |
113 | [^bool] member [^is_integral] with the compile-time constant value [^false]. | |
114 | However, for all integral types [^T] (std::3.9.1/7 [basic.fundamental]), there are specializations | |
115 | provided with the following compile-time constants defined: | |
116 | ||
117 | [table | |
118 | [[member][type][value]] | |
119 | [[[^is_integral]][bool][[^true]]] | |
120 | [[[^const_min]][[^T]][equivalent to [^std::numeric_limits<T>::min()]]] | |
121 | [[[^const_max]][[^T]][equivalent to [^std::numeric_limits<T>::max()]]] | |
122 | ] | |
123 | ||
124 | Note: The /is_integral/ flag is provided, because a user-defined integer class should specialize | |
125 | [^std::numeric_limits<>::is_integer = true], while compile-time constants | |
126 | [^const_min] and [^const_max] are not provided for that user-defined class, unless boost::integer_traits is also specialized. | |
127 | ||
128 | [endsect] | |
129 | ||
130 | [section Test Program] | |
131 | ||
132 | The program [^[@../../test/integer_traits_test.cpp integer_traits_test.cpp]] exercises the [^integer_traits] class. | |
133 | ||
134 | [endsect] | |
135 | ||
136 | [section Acknowledgements] | |
137 | ||
138 | Beman Dawes, Ed Brey, Steve Cleary, and Nathan Myers discussed the integer traits idea on the boost mailing list in August 1999. | |
139 | ||
140 | [endsect] | |
141 | [endsect] | |
142 | ||
143 | [section:integer Integer Type Selection] | |
144 | ||
145 | The [@../../../../boost/integer.hpp <boost/integer.hpp>] type selection templates allow | |
146 | integer types to be selected based on desired characteristics such as number of bits or maximum value. | |
147 | This facility is particularly useful for solving generic programming problems. | |
148 | ||
149 | [section:synopsis Synopsis] | |
150 | ||
151 | namespace boost | |
152 | { | |
153 | // fast integers from least integers | |
154 | template<typename LeastInt> | |
155 | struct int_fast_t | |
156 | { | |
157 | typedef ``['implementation-defined-type]`` type; | |
158 | }; | |
159 | ||
160 | // signed | |
161 | template<int Bits> | |
162 | struct int_t | |
163 | { | |
164 | /* Member exact may or may not be defined depending upon Bits */ | |
165 | typedef ``['implementation-defined-type]`` exact; | |
166 | typedef ``['implementation-defined-type]`` least; | |
167 | typedef int_fast_t<least>::fast fast; | |
168 | }; | |
169 | ||
170 | // unsigned | |
171 | template<int Bits> | |
172 | struct uint_t | |
173 | { | |
174 | /* Member exact may or may not be defined depending upon Bits */ | |
175 | typedef ``['implementation-defined-type]`` exact; | |
176 | typedef ``['implementation-defined-type]`` least; | |
177 | typedef int_fast_t<least>::fast fast; | |
178 | }; | |
179 | ||
180 | // signed | |
181 | template<long long MaxValue> | |
182 | struct int_max_value_t | |
183 | { | |
184 | typedef ``['implementation-defined-type]`` least; | |
185 | typedef int_fast_t<least>::fast fast; | |
186 | }; | |
187 | ||
188 | template<long long MinValue> | |
189 | struct int_min_value_t | |
190 | { | |
191 | typedef ``['implementation-defined-type]`` least; | |
192 | typedef int_fast_t<least>::fast fast; | |
193 | }; | |
194 | ||
195 | // unsigned | |
196 | template<unsigned long long Value> | |
197 | struct uint_value_t | |
198 | { | |
199 | typedef ``['implementation-defined-type]`` least; | |
200 | typedef int_fast_t<least>::fast fast; | |
201 | }; | |
202 | } // namespace boost | |
203 | ||
204 | [endsect] | |
205 | ||
206 | [section:easiest Easiest-to-Manipulate Types] | |
207 | ||
208 | The [^int_fast_t] class template maps its input type to the next-largest type that the processor | |
209 | can manipulate the easiest, or to itself if the input type is already an easy-to-manipulate type. | |
210 | For instance, processing a bunch of [^char] objects may go faster if they were converted to [^int] objects before processing. | |
211 | The input type, passed as the only template parameter, must be a built-in integral type, except [^bool]. | |
212 | Unsigned integral types can be used, as well as signed integral types. | |
213 | The output type is given as the nested type [^fast]. | |
214 | ||
215 | [*Implementation Notes:] | |
216 | By default, the output type is identical to the input type. Eventually, this code's implementation should | |
217 | be customized for each platform to give accurate mappings between the built-in types and the easiest-to-manipulate | |
218 | built-in types. Also, there is no guarantee that the output type actually is easier to manipulate than the input type. | |
219 | ||
220 | [endsect] | |
221 | ||
222 | [section:sized Sized Types] | |
223 | ||
224 | The [^int_t], [^uint_t], [^int_max_value_t], [^int_min_value_t], and [^uint_value_t] class templates find | |
225 | the most appropiate built-in integral type for the given template parameter. This type is given by the | |
226 | nested type [^least]. The easiest-to-manipulate version of that type is given by the nested type [^fast]. | |
227 | The following table describes each template's criteria. | |
228 | ||
229 | [table Criteria for the Sized Type Class Templates | |
230 | [ | |
231 | [Class Template][Template Parameter Mapping] | |
232 | ] | |
233 | [ | |
234 | [[^boost::int_t<N>::least]] | |
235 | [The smallest, built-in, signed integral type with at least /N/ bits, including the sign bit. | |
236 | The parameter should be a positive number. A compile-time error results if the parameter is | |
237 | larger than the number of bits in the largest integer type.] | |
238 | ] | |
239 | [ | |
240 | [[^boost::int_t<N>::fast]] | |
241 | [The easiest-to-manipulate, built-in, signed integral type with at least /N/ bits, including the sign bit. | |
242 | The parameter should be a positive number. A compile-time error results if the parameter is | |
243 | larger than the number of bits in the largest integer type.] | |
244 | ] | |
245 | [ | |
246 | [[^boost::int_t<N>::exact]] | |
247 | [A built-in, signed integral type with exactly /N/ bits, including the sign bit. | |
248 | The parameter should be a positive number. Note that the member /exact/ is defined | |
249 | [*only] if there exists a type with exactly /N/ bits.] | |
250 | ] | |
251 | [ | |
252 | [[^boost::uint_t<N>::least]] | |
253 | [The smallest, built-in, unsigned integral type with at least /N/ bits. | |
254 | The parameter should be a positive number. A compile-time error results if the | |
255 | parameter is larger than the number of bits in the largest integer type.] | |
256 | ] | |
257 | [ | |
258 | [[^boost::uint_t<N>::fast]] | |
259 | [The easiest-to-manipulate, built-in, unsigned integral type with at least /N/ bits. | |
260 | The parameter should be a positive number. A compile-time error results if the | |
261 | parameter is larger than the number of bits in the largest integer type.] | |
262 | ] | |
263 | [ | |
264 | [[^boost::uint_t<N>::exact]] | |
265 | [A built-in, unsigned integral type with exactly /N/ bits. | |
266 | The parameter should be a positive number. A compile-time error results if the | |
267 | parameter is larger than the number of bits in the largest integer type. | |
268 | Note that the member /exact/ is defined | |
269 | [*only] if there exists a type with exactly N bits.] | |
270 | ] | |
271 | [ | |
272 | [[^boost::int_max_value_t<V>::last]] | |
273 | [The smallest, built-in, signed integral type that can hold all the values in the inclusive range ['0 - V]. | |
274 | The parameter should be a positive number.] | |
275 | ] | |
276 | [ | |
277 | [[^boost::int_max_value_t<V>::fast]] | |
278 | [The easiest-to-manipulate, built-in, signed integral type that can hold all the values in the inclusive range ['0 - V]. | |
279 | The parameter should be a positive number.] | |
280 | ] | |
281 | [ | |
282 | [[^boost::int_min_value_t<V>::least]] | |
283 | [The smallest, built-in, signed integral type that can hold all the values in the inclusive range ['V - 0]. | |
284 | The parameter should be a negative number.] | |
285 | ] | |
286 | [ | |
287 | [[^boost::int_min_value_t<V>::fast]] | |
288 | [The easiest-to-manipulate, built-in, signed integral type that can hold all the values in the inclusive range ['V - 0]. | |
289 | The parameter should be a negative number.] | |
290 | ] | |
291 | [ | |
292 | [[^boost::uint_value_t<V>::least]] | |
293 | [The smallest, built-in, unsigned integral type that can hold all positive values | |
294 | up to and including /V/. The parameter should be a positive number.] | |
295 | ] | |
296 | [ | |
297 | [[^boost::uint_value_t<V>::fast]] | |
298 | [The easiest-to-manipulate, built-in, unsigned integral type that can hold all positive values | |
299 | up to and including /V/. The parameter should be a positive number.] | |
300 | ] | |
301 | ] | |
302 | ||
303 | [endsect] | |
304 | ||
305 | [section Example] | |
306 | ||
307 | #include <boost/integer.hpp> | |
308 | ||
309 | //... | |
310 | ||
311 | int main() | |
312 | { | |
313 | boost::int_t<24>::least my_var; // my_var has at least 24-bits | |
314 | //... | |
315 | // This one is guarenteed not to be truncated: | |
316 | boost::int_max_value_t<1000>::least my1000 = 1000; | |
317 | //... | |
318 | // This one is guarenteed not to be truncated, and as fast | |
319 | // to manipulate as possible, its size may be greater than | |
320 | // that of my1000: | |
321 | boost::int_max_value_t<1000>::fast my_fast1000 = 1000; | |
322 | } | |
323 | ||
324 | [endsect] | |
325 | ||
326 | [section Demonstration Program] | |
327 | ||
328 | The program [@../../test/integer_test.cpp integer_test.cpp] is a simplistic demonstration of the results from instantiating | |
329 | various examples of the sized type class templates. | |
330 | ||
331 | [endsect] | |
332 | ||
333 | [section Rationale] | |
334 | ||
335 | The rationale for the design of the templates in this header includes: | |
336 | ||
337 | * Avoid recursion because of concern about C++'s limited guaranteed recursion depth (17). | |
338 | * Avoid macros on general principles. | |
339 | * Try to keep the design as simple as possible. | |
340 | ||
341 | [endsect] | |
342 | ||
343 | [section Alternative] | |
344 | ||
345 | If the number of bits required is known beforehand, it may be more appropriate to use the types supplied | |
346 | in [@../../../../boost/cstdint.hpp <boost/cstdint.hpp>]. | |
347 | ||
348 | [endsect] | |
349 | ||
350 | [section Credits] | |
351 | ||
352 | The author of most of the Boost integer type choosing templates is | |
353 | [@http://www.boost.org/people/beman_dawes.html Beman Dawes]. | |
354 | He gives thanks to Valentin Bonnard and [@http://www.boost.org/people/kevlin_henney.htm Kevlin Henney] | |
355 | for sharing their designs for similar templates. | |
356 | [@http://www.boost.org/people/daryle_walker.html Daryle Walker] designed the value-based sized templates. | |
357 | ||
358 | [endsect] | |
359 | [endsect] | |
360 | ||
361 | ||
362 | ||
363 | [section:mask Integer Masks] | |
364 | ||
365 | [section Overview] | |
366 | ||
367 | The class templates in [@../../../../boost/integer/integer_mask.hpp <boost/integer/integer_mask.hpp>] | |
368 | provide bit masks for a certain bit position or a contiguous-bit pack of a certain size. | |
369 | The types of the masking constants come from the [link boost_integer.integer integer type selection templates] header. | |
370 | ||
371 | [endsect] | |
372 | ||
373 | [section Synopsis] | |
374 | ||
375 | #include <cstddef> // for std::size_t | |
376 | ||
377 | namespace boost | |
378 | { | |
379 | ||
380 | template <std::size_t Bit> | |
381 | struct high_bit_mask_t | |
382 | { | |
383 | typedef ``['implementation-defined-type]`` least; | |
384 | typedef ``['implementation-defined-type]`` fast; | |
385 | ||
386 | static const least high_bit = ``['implementation-defined]``; | |
387 | static const fast high_bit_fast = ``['implementation-defined]``; | |
388 | ||
389 | static const std::size_t bit_position = Bit; | |
390 | }; | |
391 | ||
392 | template <std::size_t Bits> | |
393 | struct low_bits_mask_t | |
394 | { | |
395 | typedef ``['implementation-defined-type]`` least; | |
396 | typedef ``['implementation-defined-type]`` fast; | |
397 | ||
398 | static const least sig_bits = ``['implementation-defined]``; | |
399 | static const fast sig_bits_fast = ``['implementation-defined]``; | |
400 | ||
401 | static const std::size_t bit_count = Bits; | |
402 | }; | |
403 | ||
404 | // Specializations for low_bits_mask_t exist for certain bit counts. | |
405 | ||
406 | } // namespace boost | |
407 | ||
408 | [endsect] | |
409 | ||
410 | [section Single Bit-Mask Class Template] | |
411 | ||
412 | The [^boost::high_bit_mask_t] class template provides constants for bit masks representing the bit at a | |
413 | certain position. The masks are equivalent to the value 2[super Bit], where [^Bit] is the template parameter. | |
414 | The bit position must be a nonnegative number from zero to ['Max], where Max is one less than the | |
415 | number of bits supported by the largest unsigned built-in integral type. The following table describes | |
416 | the members of an instantiation of [^high_bit_mask_t]. | |
417 | ||
418 | [table Members of the `boost::high_bit_mask_t` Class Template | |
419 | [[Member][Meaning]] | |
420 | [[[^least]][The smallest, unsigned, built-in type that supports the given bit position.]] | |
421 | [[[^fast]][The easiest-to-manipulate analog of [^least].]] | |
422 | [[[^high_bit]][A [^least] constant of the value 2[super Bit].]] | |
423 | [[[^high_bit_fast]][A [^fast] analog of [^high_bit].]] | |
424 | [[[^bit_position]][The value of the template parameter, in case its needed from a renamed instantiation of the class template.]] | |
425 | ] | |
426 | ||
427 | [endsect] | |
428 | ||
429 | [section Group Bit-Mask Class Template] | |
430 | ||
431 | The [^boost::low_bits_mask_t] class template provides constants for bit masks | |
432 | equivalent to the value (2[super Bits] - 1), where [^Bits] is the template parameter. | |
433 | The parameter [^Bits] must be a non-negative integer from | |
434 | zero to ['Max], where Max is the number of bits supported by the largest, unsigned, built-in integral type. | |
435 | The following table describes the members of [^low_bits_mask_t]. | |
436 | ||
437 | [table Members of the [^boost::low_bits_mask_t] Class Template | |
438 | [[Member][Meaning]] | |
439 | [[[^least]][The smallest, unsigned built-in type that supports the given bit count.]] | |
440 | [[[^fast]][The easiest-to-manipulate analog of [^least].]] | |
441 | [[[^sig_bits]][A [^least] constant of the desired bit-masking value.]] | |
442 | [[[^sig_bits_fast]][A [^fast] analog of [^sig_bits].]] | |
443 | [[[^bit_count]][The value of the template parameter, in case its needed from a renamed instantiation of the class template.]] | |
444 | ] | |
445 | ||
446 | [endsect] | |
447 | ||
448 | [section Implementation Notes] | |
449 | ||
450 | When [^Bits] is the exact size of a built-in unsigned type, the implementation has to change to | |
451 | prevent undefined behavior. Therefore, there are specializations of [^low_bits_mask_t] at those bit counts. | |
452 | ||
453 | [endsect] | |
454 | ||
455 | [section Example] | |
456 | ||
457 | #include <boost/integer/integer_mask.hpp> | |
458 | ||
459 | //... | |
460 | ||
461 | int main() | |
462 | { | |
463 | typedef boost::high_bit_mask_t<29> mask1_type; | |
464 | typedef boost::low_bits_mask_t<15> mask2_type; | |
465 | ||
466 | mask1_type::least my_var1; | |
467 | mask2_type::fast my_var2; | |
468 | //... | |
469 | ||
470 | my_var1 |= mask1_type::high_bit; | |
471 | my_var2 &= mask2_type::sig_bits_fast; | |
472 | ||
473 | //... | |
474 | } | |
475 | ||
476 | [endsect] | |
477 | ||
478 | [section Demonstration Program] | |
479 | ||
480 | The program [@../../test/integer_mask_test.cpp integer_mask_test.cpp] is a simplistic demonstration of the | |
481 | results from instantiating various examples of the bit mask class templates. | |
482 | ||
483 | [endsect] | |
484 | ||
485 | [section Rationale] | |
486 | ||
487 | The class templates in this header are an extension of the [link boost_integer.integer integer type selection class templates]. | |
488 | The new class templates provide the same sized types, but also convenient masks to use when extracting the | |
489 | highest or all the significant bits when the containing built-in type contains more bits. | |
490 | This prevents contamination of values by the higher, unused bits. | |
491 | ||
492 | [endsect] | |
493 | ||
494 | [section Credits] | |
495 | ||
496 | The author of the Boost bit mask class templates is [@http://www.boost.org/people/daryle_walker.html Daryle Walker]. | |
497 | ||
498 | [endsect] | |
499 | [endsect] | |
500 | ||
501 | [section:log2 Compile Time log2 Calculation] | |
502 | ||
503 | The class template in [@../../../../boost/integer/static_log2.hpp <boost/integer/static_log2.hpp>] | |
504 | determines the position of the highest bit in a given value. This facility is useful for solving generic programming problems. | |
505 | ||
506 | [section Synopsis] | |
507 | ||
508 | namespace boost | |
509 | { | |
510 | ||
511 | typedef ``['implementation-defined]`` static_log2_argument_type; | |
512 | typedef ``['implementation-defined]`` static_log2_result_type; | |
513 | ||
514 | template <static_log2_argument_type arg> | |
515 | struct static_log2 | |
516 | { | |
517 | static const static_log2_result_type value = ``['implementation-defined]``; | |
518 | }; | |
519 | ||
520 | ||
521 | template < > | |
522 | struct static_log2< 0 > | |
523 | { | |
524 | // The logarithm of zero is undefined. | |
525 | }; | |
526 | ||
527 | ||
528 | } // namespace boost | |
529 | ||
530 | [endsect] | |
531 | ||
532 | [section Usage] | |
533 | ||
534 | The [^boost::static_log2] class template takes one template parameter, a value of type | |
535 | [^static_log2_argument_type]. The template only defines one member, [^value], which gives the | |
536 | truncated, base-two logarithm of the template argument. | |
537 | ||
538 | Since the logarithm of zero, for any base, is undefined, there is a specialization of [^static_log2] | |
539 | for a template argument of zero. This specialization has no members, so an attempt to use the base-two | |
540 | logarithm of zero results in a compile-time error. | |
541 | ||
542 | Note: | |
543 | ||
544 | * [^static_log2_argument_type] is an ['unsigned integer type] (C++ standard, 3.9.1p3). | |
545 | * [^static_log2_result_type] is an ['integer type] (C++ standard, 3.9.1p7). | |
546 | ||
547 | [endsect] | |
548 | ||
549 | [section Demonstration Program] | |
550 | ||
551 | The program [@../../test/static_log2_test.cpp static_log2_test.cpp] is a simplistic | |
552 | demonstration of the results from instantiating various examples of the binary logarithm class template. | |
553 | ||
554 | [endsect] | |
555 | ||
556 | [section Rationale] | |
557 | ||
558 | The base-two (binary) logarithm, abbreviated lb, function is occasionally used to give order-estimates | |
559 | of computer algorithms. The truncated logarithm can be considered the highest power-of-two in a value, | |
560 | which corresponds to the value's highest set bit (for binary integers). Sometimes the highest-bit position | |
561 | could be used in generic programming, which requires the position to be available statically (['i.e.] at compile-time). | |
562 | ||
563 | [endsect] | |
564 | ||
565 | [section Credits] | |
566 | ||
567 | The original version of the Boost binary logarithm class template was | |
568 | written by [@http://www.boost.org/people/daryle_walker.html Daryle Walker] and then | |
569 | enhanced by Giovanni Bajo with support for compilers without partial template specialization. | |
570 | The current version was suggested, together with a reference implementation, by Vesa Karvonen. | |
571 | Gennaro Prota wrote the actual source file. | |
572 | ||
573 | [endsect] | |
574 | [endsect] | |
575 | ||
576 | [section:minmax Compile time min/max calculation] | |
577 | ||
578 | The class templates in [@../../../../boost/integer/static_min_max.hpp <boost/integer/static_min_max.hpp>] | |
579 | provide a compile-time evaluation of the minimum or maximum of two integers. These facilities are useful | |
580 | for generic programming problems. | |
581 | ||
582 | [section Synopsis] | |
583 | ||
584 | namespace boost | |
585 | { | |
586 | ||
587 | typedef ``['implementation-defined]`` static_min_max_signed_type; | |
588 | typedef ``['implementation-defined]`` static_min_max_unsigned_type; | |
589 | ||
590 | template <static_min_max_signed_type Value1, static_min_max_signed_type Value2 > | |
591 | struct static_signed_min; | |
592 | ||
593 | template <static_min_max_signed_type Value1, static_min_max_signed_type Value2> | |
594 | struct static_signed_max; | |
595 | ||
596 | template <static_min_max_unsigned_type Value1, static_min_max_unsigned_type Value2> | |
597 | struct static_unsigned_min; | |
598 | ||
599 | template <static_min_max_unsigned_type Value1, static_min_max_unsigned_type Value2> | |
600 | struct static_unsigned_max; | |
601 | ||
602 | } | |
603 | ||
604 | [endsect] | |
605 | ||
606 | [section Usage] | |
607 | ||
608 | The four class templates provide the combinations for finding the minimum or maximum of two [^signed] or | |
609 | [^unsigned] ([^long]) parameters, /Value1/ and /Value2/, at compile-time. Each template has a single static data member, | |
610 | [^value], which is set to the respective minimum or maximum of the template's parameters. | |
611 | ||
612 | [endsect] | |
613 | ||
614 | [section Example] | |
615 | ||
616 | #include <boost/integer/static_min_max.hpp> | |
617 | ||
618 | template < unsigned long AddendSize1, unsigned long AddendSize2 > | |
619 | class adder | |
620 | { | |
621 | public: | |
622 | static unsigned long const addend1_size = AddendSize1; | |
623 | static unsigned long const addend2_size = AddendSize2; | |
624 | static unsigned long const sum_size = boost::static_unsigned_max<AddendSize1, AddendSize2>::value + 1; | |
625 | ||
626 | typedef int addend1_type[ addend1_size ]; | |
627 | typedef int addend2_type[ addend2_size ]; | |
628 | typedef int sum_type[ sum_size ]; | |
629 | ||
630 | void operator ()( addend1_type const &a1, addend2_type const &a2, sum_type &s ) const; | |
631 | }; | |
632 | ||
633 | //... | |
634 | ||
635 | int main() | |
636 | { | |
637 | int const a1[] = { 0, 4, 3 }; // 340 | |
638 | int const a2[] = { 9, 8 }; // 89 | |
639 | int s[ 4 ]; | |
640 | adder<3,2> obj; | |
641 | ||
642 | obj( a1, a2, s ); // 's' should be 429 or { 9, 2, 4, 0 } | |
643 | //... | |
644 | } | |
645 | ||
646 | [endsect] | |
647 | ||
648 | [section Demonstration Program] | |
649 | ||
650 | The program [@../../test/static_min_max_test.cpp static_min_max_test.cpp] is a simplistic demonstration of | |
651 | various comparisons using the compile-time extrema class templates. | |
652 | ||
653 | [endsect] | |
654 | ||
655 | [section Rationale] | |
656 | ||
657 | Sometimes the minimum or maximum of several values needs to be found for later compile-time processing, | |
658 | ['e.g.] for a bound for another class template. | |
659 | ||
660 | [endsect] | |
661 | ||
662 | [section Credits] | |
663 | ||
664 | The author of the Boost compile-time extrema class templates is [@http://www.boost.org/people/daryle_walker.html Daryle Walker]. | |
665 | ||
666 | [endsect] | |
667 | [endsect] | |
668 | ||
669 | [section:history History] | |
670 | ||
671 | [h4 1.56.0] | |
672 | ||
673 | * Moved `<boost/cstdint.hpp>` into [@boost:/libs/config/index.html | |
674 | Boost.Config]. | |
675 | ||
676 | [h4 1.42.0] | |
677 | ||
678 | * Reverted Trunk to release branch state (i.e. a "known good state"). | |
679 | * Fixed issues: [@https://svn.boost.org/trac/boost/ticket/653 653], | |
680 | [@https://svn.boost.org/trac/boost/ticket/3084 3084], | |
681 | [@https://svn.boost.org/trac/boost/ticket/3177 3177], | |
682 | [@https://svn.boost.org/trac/boost/ticket/3180 3180], | |
683 | [@https://svn.boost.org/trac/boost/ticket/3548 3568], | |
684 | [@https://svn.boost.org/trac/boost/ticket/3657 3657], | |
685 | [@https://svn.boost.org/trac/boost/ticket/2134 2134]. | |
686 | * Added long long support to [^boost::static_log2], [^boost::static_signed_min], [^boost::static_signed_max], | |
687 | [^boost::static_unsigned_min][^boost::static_unsigned_max], when available. | |
688 | * The argument type and the result type of [^boost::static_signed_min] etc are now typedef'd. | |
689 | Formerly, they were hardcoded as [^unsigned long] and [^int] respectively. Please, use the | |
690 | provided typedefs in new code (and update old code as soon as possible). | |
691 | ||
692 | [h4 1.32.0] | |
693 | ||
694 | * The argument type and the result type of [^boost::static_log2] are now typedef'd. | |
695 | Formerly, they were hardcoded as [^unsigned long] and [^int] respectively. Please, use the | |
696 | provided typedefs in new code (and update old code as soon as possible). | |
697 | ||
698 | [endsect] | |
699 | ||
700 | [section:cstdint Removed from library: Standard Integer Types] | |
701 | ||
702 | The [@boost:/libs/config/doc/html/boost_config/cstdint.html Boost.Config] module provides | |
703 | the typedefs useful for writing portable code that requires certain | |
704 | integer widths. | |
705 | ||
706 | [endsect] |