4 Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
6 Distributed under the Boost Software License, Version 1.0.
7 (See accompanying file LICENSE_1_0.txt or copy at
8 http://www.boost.org/LICENSE_1_0.txt)
11 [section converter<> function object]
15 namespace boost { namespace numeric {
20 class Traits, = conversion_traits<T,S>
21 class OverflowHandler = def_overflow_handler,
22 class Float2IntRounder = Trunc< typename Traits::source_type >,
23 class RawConverter = raw_converter<Traits>,
24 class UserRangeChecker = UseInternalRangeChecker
28 typedef Traits traits ;
30 typedef typename Traits::source_type source_type ;
31 typedef typename Traits::argument_type argument_type ;
32 typedef typename Traits::result_type result_type ;
34 static result_type convert ( argument_type s ) ;
36 result_type operator() ( argument_type s ) const ;
38 // Internal member functions:
40 static range_check_result out_of_range ( argument_type s ) ;
41 static void validate_range ( argument_type s ) ;
42 static result_type low_level_convert ( argument_type s ) ;
43 static source_type nearbyint ( argument_type s ) ;
47 } } // namespace numeric, boost
50 `boost::numeric::converter<>` is a __SGI_UNARY_FUNCTION__ encapsulating
51 the code to perform a numeric conversion with the direction and
52 properties specified by the Traits template parameter. It can optionally
53 take some [link boost_numericconversion.numeric_converter_policy_classes policies] which can be used to customize its behavior. The
54 `Traits` parameter is not a policy but the parameter that defines
59 [section Template parameters]
64 The [link boost_numericconversion.definitions.numeric_types Numeric Type]
65 which is the ['Target] of the conversion.
68 The [link boost_numericconversion.definitions.numeric_types Numeric Type]
69 which is the ['Source] of the conversion.
72 This must be a conversion traits class with the interface of
73 [link boost_numericconversion.conversion_traits___traits_class `boost::numeric::conversion_traits`]
76 [*Stateless Policy] called to administrate the result of the range checking.
78 It is a [*Function Object] which receives the result of `out_of_range()`
79 and is called inside the `validate_range()` static member function exposed
82 [[`Float2IntRounder`][
83 [*Stateless Policy] which specifies the rounding mode used for float to
86 It supplies the `nearbyint()` static member function exposed by the converter.
89 [*Stateless Policy] which is used to perform the actual conversion.
91 It supplies the `low_level_convert()` static member function exposed
94 [[`UserRangeChecker`][
95 ['Special and Optional] [*Stateless Policy] which can be used to override
96 the internal range checking logic.
98 If given, supplies alternative code for the `out_of_range()` and
99 `validate_range()` static member functions exposed by the converter.
105 [section Member functions]
107 [: `static result_type converter<>::convert ( argument_type s ) ; // throw
110 This static member function converts an rvalue of type `source_type` to
111 an rvalue of type `target_type`.
113 If the conversion requires it, it performs a range checking before the conversion
114 and passes the result of the check to the overflow handler policy (the default
115 policy throws an exception if out-of-range is detected)
117 The implementation of this function is actually built from the policies and is
118 basically as follows:
120 result_type converter<>::convert ( argument_type s )
122 validate_range(s); // Implemented by the internal range checking logic
123 // (which also calls the OverflowHandler policy)
124 // or externally supplied by the UserRangeChecker policy.
126 s = nearbyint(s); // Externally supplied by the Float2IntRounder policy.
127 // NOTE: This is actually called only for float to int conversions.
129 return low_level_convert(s); // Externally supplied by the RawConverter policy.
132 `converter<>::operator() const` just calls `convert()`
136 [: `static range_check_result numeric_converter<>::out_of_range ( argument_type s ) ;`]
138 This [link numeric_conversion_converter_internal internal] static member function
139 determines if the value `s` can be
140 represented by the target type without overflow.
142 It does not determine if the conversion is ['exact]; that is, it does not detect
143 ['inexact] conversions, only ['out-of-range] conversions (see the
144 [link boost_numericconversion.definitions.exact__correctly_rounded_and_out_of_range_representations Definitions] for further details).
146 The return value is of enum type
147 [link boost_numericconversion.numeric_converter_policy_classes.enum_range_check_result `boost::numeric::range_check_result`]
149 The actual code for the range checking logic is optimized for the combined
150 properties of the source and target types. For example, a non-subranged
151 conversion (i.e: `int`->`float`), requires no range checking, so `out_of_range()`
152 returns `cInRange` directly. See the following
153 [link boost_numericconversion.converter___function_object.range_checking_logic table] for more details.
155 If the user supplied a
156 [link boost_numericconversion.numeric_converter_policy_classes.policy_userrangechecker UserRangeChecker] policy,
157 is this policy which implements this function, so the implementation is user
158 defined, although it is expected to perform the same conceptual check and
159 return the appropriate result.
163 [: `static void numeric_converter<>::validate_range ( argument_type s ) ; // no throw
166 This [link numeric_conversion_converter_internal internal] static member function
167 calls out_of_range(s), and passes the
168 result to the [link boost_numericconversion.numeric_converter_policy_classes.policy_overflowhandler OverflowHandler]
171 For those Target/Source combinations which don't require range checking, this
172 is an empty inline function.
174 If the user supplied a
175 [link boost_numericconversion.numeric_converter_policy_classes.policy_userrangechecker UserRangeChecker] policy,
176 is this policy which implements this function, so the implementation is user
177 defined, although it is expected to perform the same action as the default.
178 In particular, it is expected to pass the result of the check to the overflow handler.
182 [: `static result_type numeric_converter<>::low_level_convert ( argument_type s ) ;` ]
184 This [link numeric_conversion_converter_internal internal] static member function
185 performs the actual conversion.
187 This function is externally supplied by the
188 [link boost_numericconversion.numeric_converter_policy_classes.policy_rawconverter RawConverter] policy class.
192 [: `static source_type converter<>::nearbyint ( argument_type s ) ;`]
194 This [link numeric_conversion_converter_internal internal] static member function,
195 which is [_only used] for
196 `float` to `int` conversions, returns an ['integer] value of ['[_floating-point
197 type]] according to some rounding direction.
199 This function is externally supplied by the
200 [link boost_numericconversion.numeric_converter_policy_classes.policy_float2introunder Float2IntRounder] policy class
201 which encapsulates the specific rounding mode.
205 [#numeric_conversion_converter_internal]
207 [heading Internal Member Functions]
209 These static member functions build the actual conversion code used by `convert()`.
210 The user does not have to call these if calling `convert()`, since `convert()` calls
211 them infernally, but they can be called separately for specific needs.
215 [section Range Checking Logic]
217 The following table summarizes the internal range checking logic performed for
218 each combination of the properties of Source and Target.
220 LowestT/HighestT denotes the highest and lowest values of the Target type, respectively.
222 `S(n)` is short for `static_cast<S>(n)` (`S` denotes the Source type).
224 `NONE` indicates that for this case there is no range checking.
228 int_to_int |--> sig_to_sig |--> subranged |--> ( s >= S(LowestT) ) && ( s <= S(HighestT) )
229 | |--> not subranged |--> NONE
231 |--> unsig_to_unsig |--> subranged |--> ( s >= S(LowestT) ) && ( s <= S(HighestT) )
232 | |--> not subranged |--> NONE
234 |--> sig_to_unsig |--> pos subranged |--> ( s >= S(0) ) && ( s <= S(HighestT) )
235 | |--> not pos subranged |--> ( s >= S(0) )
237 |--> unsig_to_sig |--> subranged |--> ( s <= S(HighestT) )
238 | |--> not subranged |--> NONE
241 int_to_float |--> NONE
244 float_to_int |--> round_to_zero |--> ( s > S(LowestT)-S(1) ) && ( s < S(HighestT)+S(1) )
245 |--> round_to_even_nearest |--> ( s >= S(LowestT)-S(0.5) ) && ( s < S(HighestT)+S(0.5) )
246 |--> round_to_infinity |--> ( s > S(LowestT)-S(1) ) && ( s <= S(HighestT) )
247 |--> round_to_neg_infinity |--> ( s >= S(LowestT) ) && ( s < S(HighestT)+S(1) )
250 float_to_float |--> subranged |--> ( s >= S(LowestT) ) && ( s <= S(HighestT) )
251 |--> not subranged |--> NONE
262 #include <boost/numeric/conversion/converter.hpp>
266 typedef boost::numeric::converter<int,double> Double2Int ;
268 int x = Double2Int::convert(2.0);
271 int y = Double2Int()(3.14); // As a function object.
272 assert ( y == 3 ) ; // The default rounding is trunc.
276 double m = boost::numeric::bounds<double>::highest();
277 int z = Double2Int::convert(m); // By default throws positive_overflow()
279 catch ( boost::numeric::positive_overflow const& )