ceph/src/boost/libs/numeric/conversion/doc/conversion.qbk

   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
  13 Distributed 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
  47 The Boost Numeric Conversion library is a collection of tools to describe and
  48 perform conversions between values of different
  49 [link boost_numericconversion.definitions.numeric_types numeric types].
  50
  51 The library includes a special alternative for a subset of `std::numeric_limits<>`,
  52 the [link boost_numericconversion.bounds___traits_class bounds<>] traits class, which provides
  53 a consistent way to obtain the [link boost_numericconversion.definitions.range_and_precision boundary]
  54 values for the [link boost_numericconversion.definitions.range_and_precision range] of a numeric type.
  55
  56 It also includes a set of [link boost_numericconversion.conversion_traits___traits_class trait classes]
  57 which describes the compile-time
  58 properties of a conversion from a source to a target numeric type.
  59 Both [link boost_numericconversion.definitions.c___arithmetic_types arithmetic] and
  60 [link boost_numericconversion.definitions.numeric_types user-defined numeric types] can be used.
  61
  62 A policy-based [link boost_numericconversion.converter___function_object converter] object which
  63 uses `conversion_traits` to select
  64 an optimized implementation is supplied. Such implementation uses an optimal
  65 range 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
  96 the previous version of `numeric_cast<>` which already presented the idea of a runtime
  97 range check.
  98
  99 * Later, Eric Ford, Kevin Lynch and the author spotted some genericity problems with
 100 that `numeric_cast<>` which prevented it from being used in a generic layer of math
 101 functions.
 102
 103 * An improved `numeric_cast<>` which properly handled all combinations of arithmetic
 104 types 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
 108 Darin 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
 111 problems with `numeric_cast<>` himself, he revised very carefully the original submission
 112 and spot a subtle bug in the range checking implementation. He also wrote part of
 113 this documentation and proof-read and corrected other parts. And most importantly:
 114 the features now presented here in this library evolved from the original submission as
 115 a 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
 120 rounding conversions.
 121
 122 * The following people contributed an important review of the design, documentation and c
 123 ode: Kevin Lynch, Thorsten Ottosen, Paul Bristow, Daryle Walker, Jhon Torjo, Eric Ford,
 124 Gennadiy 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