namespace boost { namespace numeric {


    template<class T,
             class S,
             class Traits,          = conversion_traits<T,S>
             class OverflowHandler  = def_overflow_handler,
             class Float2IntRounder = Trunc< typename Traits::source_type >,
             class RawConverter     = raw_converter<Traits>,
             class UserRangeChecker = UseInternalRangeChecker
            >
    struct converter
    {
        typedef Traits traits ;

        typedef typename Traits::source_type   source_type   ;
        typedef typename Traits::argument_type argument_type ;
        typedef typename Traits::result_type   result_type   ;

        static result_type convert ( argument_type s ) ;

        result_type operator() ( argument_type s ) const ;

        // Internal member functions:

        static range_check_result out_of_range      ( argument_type s ) ;
        static void               validate_range    ( argument_type s ) ;
        static result_type        low_level_convert ( argument_type s ) ;
        static source_type        nearbyint         ( argument_type s ) ;

    } ;

} } // namespace numeric, boost

boost::numeric::converter<> is a Unary Function Object encapsulating the code to perform a numeric conversion with the direction and properties specified by the Traits template parameter. It can optionally take some policies which can be used to customize its behavior. The Traits parameter is not a policy but the parameter that defines the conversion.

This static member function converts an rvalue of type source_type to an rvalue of type target_type.

If the conversion requires it, it performs a range checking before the conversion and passes the result of the check to the overflow handler policy (the default policy throws an exception if out-of-range is detected)

The implementation of this function is actually built from the policies and is basically as follows:

result_type converter<>::convert ( argument_type s )
{
    validate_range(s); // Implemented by the internal range checking logic
                       // (which also calls the OverflowHandler policy)
                       // or externally supplied by the UserRangeChecker policy.

    s = nearbyint(s); // Externally supplied by the Float2IntRounder policy.
                      // NOTE: This is actually called only for float to int conversions.

    return low_level_convert(s); // Externally supplied by the RawConverter policy.
}

converter<>::operator() const just calls convert()

This internal static member function determines if the value s can be represented by the target type without overflow.

It does not determine if the conversion is exact; that is, it does not detect inexact conversions, only out-of-range conversions (see the Definitions for further details).

The return value is of enum type boost::numeric::range_check_result

The actual code for the range checking logic is optimized for the combined properties of the source and target types. For example, a non-subranged conversion (i.e: int->float), requires no range checking, so out_of_range() returns cInRange directly. See the following table for more details.

If the user supplied a UserRangeChecker policy, is this policy which implements this function, so the implementation is user defined, although it is expected to perform the same conceptual check and return the appropriate result.

This internal static member function calls out_of_range(s), and passes the result to the OverflowHandler policy class.

For those Target/Source combinations which don't require range checking, this is an empty inline function.

If the user supplied a UserRangeChecker policy, is this policy which implements this function, so the implementation is user defined, although it is expected to perform the same action as the default. In particular, it is expected to pass the result of the check to the overflow handler.

This internal static member function performs the actual conversion.

This function is externally supplied by the RawConverter policy class.

This internal static member function, which is only used for float to int conversions, returns an integer value of floating-point type according to some rounding direction.

This function is externally supplied by the Float2IntRounder policy class which encapsulates the specific rounding mode.

Internal Member Functions

These static member functions build the actual conversion code used by convert(). The user does not have to call these if calling convert(), since convert() calls them infernally, but they can be called separately for specific needs.

The following table summarizes the internal range checking logic performed for each combination of the properties of Source and Target.

LowestT/HighestT denotes the highest and lowest values of the Target type, respectively.

S(n) is short for static_cast<S>(n) (S denotes the Source type).

NONE indicates that for this case there is no range checking.

int_to_int    |--> sig_to_sig     |--> subranged     |--> ( s >= S(LowestT) ) && ( s <= S(HighestT) )
              |                   |--> not subranged |--> NONE
              |
              |--> unsig_to_unsig |--> subranged     |--> ( s >= S(LowestT) ) && ( s <= S(HighestT) )
              |                   |--> not subranged |--> NONE
              |
              |--> sig_to_unsig   |--> pos subranged     |--> ( s >= S(0) ) && ( s <= S(HighestT) )
              |                   |--> not pos subranged |--> ( s >= S(0) )
              |
              |--> unsig_to_sig   |--> subranged     |--> ( s <= S(HighestT) )
              |                   |--> not subranged |--> NONE


int_to_float   |--> NONE


float_to_int   |--> round_to_zero         |--> ( s >  S(LowestT)-S(1)   ) && ( s <  S(HighestT)+S(1)   )
               |--> round_to_even_nearest |--> ( s >= S(LowestT)-S(0.5) ) && ( s <  S(HighestT)+S(0.5) )
               |--> round_to_infinity     |--> ( s >  S(LowestT)-S(1)   ) && ( s <= S(HighestT)        )
               |--> round_to_neg_infinity |--> ( s >= S(LowestT)        ) && ( s <  S(HighestT)+S(1)   )


float_to_float |--> subranged     |--> ( s >= S(LowestT) ) && ( s <= S(HighestT) )
               |--> not subranged |--> NONE

#include <cassert>
#include <boost/numeric/conversion/converter.hpp>

int main() {

    typedef boost::numeric::converter<int,double> Double2Int ;

    int x = Double2Int::convert(2.0);
    assert ( x == 2 );

    int y = Double2Int()(3.14); // As a function object.
    assert ( y == 3 ) ; // The default rounding is trunc.

    try
    {
        double m = boost::numeric::bounds<double>::highest();
        int z = Double2Int::convert(m); // By default throws positive_overflow()
    }
    catch ( boost::numeric::positive_overflow const& )
    {
    }

    return 0;
}