1[library Boost.NumericConversion 2 [quickbook 1.4] 3 [authors [Cacciola Carballal, Fernando Luis]] 4 [copyright 2004-2007 Fernando Luis Cacciola Carballal] 5 [category numerics] 6 [id numeric_conversion] 7 [dirname numeric_conversion] 8 [purpose 9 Optimized Policy-based Numeric Conversions 10 ] 11 [source-mode c++] 12 [license 13Distributed under the Boost Software License, Version 1.0. 14(See accompanying file LICENSE_1_0.txt or copy at 15[@http://www.boost.org/LICENSE_1_0.txt]) 16 ] 17] 18 19[/ Macros will be used for links so we have a central place to change them ] 20 21 22[/ Cited Boost resources ] 23 24[def __MPL_INTEGRAL_CONSTANT__ [@../../../../mpl/doc/refmanual/integral-constant.html MPL's Integral Constant] ] 25 26 27 28[/ Other web resources ] 29 30[def __SGI_UNARY_FUNCTION__ [@http://www.sgi.com/tech/stl/UnaryFunction.html Unary Function Object]] 31 32[/ Icons ] 33 34[def __NOTE__ [$images/note.png]] 35[def __ALERT__ [$images/caution.png]] 36[def __DETAIL__ [$images/note.png]] 37[def __TIP__ [$images/tip.png]] 38[def __QUESTION_MARK__ [$images/question.png]] 39[def __SPACE__ [$images/space.png]] 40[def __GO_TO__ [$images/callouts/R.png]] 41 42 43 44 45[section Overview] 46 47The Boost Numeric Conversion library is a collection of tools to describe and 48perform conversions between values of different 49[link boost_numericconversion.definitions.numeric_types numeric types]. 50 51The library includes a special alternative for a subset of `std::numeric_limits<>`, 52the [link boost_numericconversion.bounds___traits_class bounds<>] traits class, which provides 53a consistent way to obtain the [link boost_numericconversion.definitions.range_and_precision boundary] 54values for the [link boost_numericconversion.definitions.range_and_precision range] of a numeric type. 55 56It also includes a set of [link boost_numericconversion.conversion_traits___traits_class trait classes] 57which describes the compile-time 58properties of a conversion from a source to a target numeric type. 59Both [link boost_numericconversion.definitions.c___arithmetic_types arithmetic] and 60[link boost_numericconversion.definitions.numeric_types user-defined numeric types] can be used. 61 62A policy-based [link boost_numericconversion.converter___function_object converter] object which 63uses `conversion_traits` to select 64an optimized implementation is supplied. Such implementation uses an optimal 65range checking code suitable for the source/target combination. 66 67* The converter's out-of-range behavior can be customized via an 68[link boost_numericconversion.numeric_converter_policy_classes.policy_overflowhandler OverflowHandler] policy. 69* For floating-point to integral conversions, the rounding mode can be selected via the 70[link boost_numericconversion.numeric_converter_policy_classes.policy_float2introunder Float2IntRounder] policy. 71* A custom low-level conversion routine (for UDTs for instance) can be passed via a 72[link boost_numericconversion.numeric_converter_policy_classes.policy_rawconverter RawConverter] policy. 73* The optimized automatic range-checking logic can be overridden via a 74[link boost_numericconversion.numeric_converter_policy_classes.policy_userrangechecker UserRangeChecker] policy. 75 76[endsect] 77 78 79 80[include definitions.qbk] 81[include converter.qbk] 82[include requirements.qbk] 83[include bounds.qbk] 84[include conversion_traits.qbk] 85[include converter_policies.qbk] 86[include numeric_cast.qbk] 87 88 89 90[section History and Acknowledgments] 91 92 93[heading Pre-formal review] 94 95* Kevlin Henney, with help from David Abrahams and Beman Dawes, originally contributed 96the previous version of `numeric_cast<>` which already presented the idea of a runtime 97range check. 98 99* Later, Eric Ford, Kevin Lynch and the author spotted some genericity problems with 100that `numeric_cast<>` which prevented it from being used in a generic layer of math 101functions. 102 103* An improved `numeric_cast<>` which properly handled all combinations of arithmetic 104types was presented. 105 106* David Abrahams and Beman Dawes acknowledged the need of an improved version of 107`numeric_cast<>` and supported the submission as originally laid out. Daryl Walker and 108Darin Adler made some important comments and proposed fixes to the original submission. 109 110* Special thanks go to Björn Karlsoon who helped the author considerably. Having found the 111problems with `numeric_cast<>` himself, he revised very carefully the original submission 112and spot a subtle bug in the range checking implementation. He also wrote part of 113this documentation and proof-read and corrected other parts. And most importantly: 114the features now presented here in this library evolved from the original submission as 115a result of the useful private communications between Björn and the author. 116 117[heading Post-formal review] 118 119* Guillaume Melquiond spoted some documentation and code issues, particularly about 120rounding conversions. 121 122* The following people contributed an important review of the design, documentation and c 123ode: Kevin Lynch, Thorsten Ottosen, Paul Bristow, Daryle Walker, Jhon Torjo, Eric Ford, 124Gennadiy Rozental. 125 126 127[endsect] 128 129[section Bibliography] 130 131* Standard Documents: 132 # ISO/IEC 14882:98 (C++98 Standard) 133 # ISO/IEC 9899:1999 (C99 Standard) 134 # ISO/IEC 10967-1 (Language Independent Arithmetic (LIA), Part I, 1994) 135 # ISO/IEC 2382-1:1993 (Information Technology - Vocabulary - Part I: Fundamental Terms) 136 # ANSI/IEEE 754-1985 [and IEC 60559:1989] (Binary floating-point) 137 # ANSI/IEEE 854-1988 (Radix Independent floating-point) 138 # ANSI X3/TR-1-82 (Dictionary for Information Processing Systems) 139 # ISO/IEC JTC1/SC22/WG14/N753 C9X Revision Proposal: LIA-1 Binding: Rationale 140* Papers: 141 # David Goldberg What Every Computer Scientist Should Know About Floating-Point Arithmetic 142 # Prof. William Kahan papers on floating-point. 143 144[endsect] 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162
