Both arithmetic (built-in) and user-defined numeric types require proper specialization of std::numeric_limits<> (that is, with (in-class) integral constants).

The library uses std::numeric_limits<T>::is_specialized to detect whether the type is builtin or user defined, and std::numeric_limits<T>::is_integer, std::numeric_limits<T>::is_signed to detect whether the type is integer or floating point; and whether it is signed/unsigned.

The default Float2IntRounder policies uses unqualified calls to functions floor() and ceil(); but the standard functions are introduced in scope by a using directive:

using std::floor ; return floor(s);

Therefore, for builtin arithmetic types, the std functions will be used. User defined types should provide overloaded versions of these functions in order to use the default rounder policies. If these overloads are defined within a user namespace argument dependent lookup (ADL) should find them, but if your compiler has a weak ADL you might need to put these functions some place else or write your own rounder policy.

The default Trunc<> rounder policy needs to determine if the source value is positive or not, and for this it evaluates the expression s < static_cast<S>(0). Therefore, user defined types require a visible operator< in order to use the Trunc<> policy (the default).

Conversion Traits

If a User Defined Type is involved in a conversion, it is assumed that the UDT has wider range than any built-in type, and consequently the values of some converter_traits<> members are hardwired regardless of the reality. The following table summarizes this:

The Traits member udt_mixture can be used to detect whether a UDT is involved and to infer the validity of the other members as shown above.

Range Checking

Because User Defined Numeric Types might have peculiar ranges (such as an unbounded range), this library does not attempt to supply a meaningful range checking logic when UDTs are involved in a conversion. Therefore, if either Target or Source are not built-in types, the bundled range checking of the converter<> function object is automatically disabled. However, it is possible to supply a user-defined range-checker. See Special Policies

There are two components of the converter<> class that might require special behavior if User Defined Numeric Types are involved: the Range Checking and the Raw Conversion.

When both Target and Source are built-in types, the converter class uses an internal range checking logic which is optimized and customized for the combined properties of the types.

However, this internal logic is disabled when either type is User Defined. In this case, the user can specify an external range checking policy which will be used in place of the internal code. See numeric_cast_traits for details on using UDTs with numeric_cast.

The converter class performs the actual conversion using a Raw Converter policy. The default raw converter simply performs a static_cast<Target>(source).

However, if the a UDT is involved, the static_cast might not work. In this case, the user can implement and pass a different raw converter policy. See RawConverter policy for details.

In order to employ UDTs with numeric_cast, the user should define a numeric_cast_traits specialization on the UDT for each conversion. Here is an example of specializations for converting between the UDT and any other type:

namespace boost { namespace numeric {
template <typename Source>
struct numeric_cast_traits<UDT, Source>
{
    typedef conversion_traits<UDT, Source>      conv_traits;

    //! The following are required:
    typedef YourOverflowHandlerPolicy           overflow_policy;
    typedef YourRangeCheckerPolicy<conv_traits> range_checking_policy;
    typedef YourFloat2IntRounderPolicy<Source>  rounding_policy;
};
template <typename Target>
struct numeric_cast_traits<Target, UDT>
{
    typedef conversion_traits<Target, UDT>      conv_traits;

    //! The following are required:
    typedef YourOverflowHandlerPolicy           overflow_policy;
    typedef YourRangeCheckerPolicy<conv_traits> range_checking_policy;
    typedef YourFloat2IntRounderPolicy<UDT>     rounding_policy;
};
}}//namespace boost::numeric;

These specializations are already defined with default values for the built-in numeric types. It is possible to disable the generation of specializations for built-in types by defining BOOST_NUMERIC_CONVERSION_RELAX_BUILT_IN_CAST_TRAITS. For details on defining custom policies see Converter Policies.

Here is a full example of how to define a custom UDT for use with numeric_cast:

//! Define a simple custom number
struct Double
    :   boost::ordered_field_operators
        <
            Double
          , boost::ordered_field_operators2< Double, long double
          , boost::ordered_field_operators2< Double, double
          , boost::ordered_field_operators2< Double, float
          , boost::ordered_field_operators2< Double, int
          , boost::ordered_field_operators2< Double, unsigned int
          , boost::ordered_field_operators2< Double, long
          , boost::ordered_field_operators2< Double, unsigned long
          , boost::ordered_field_operators2< Double, long long
          , boost::ordered_field_operators2< Double, unsigned long long
          , boost::ordered_field_operators2< Double, char
          , boost::ordered_field_operators2< Double, unsigned char
          , boost::ordered_field_operators2< Double, short
          , boost::ordered_field_operators2< Double, unsigned short
        > > > > > > > > > > > > > >
{
    Double()
        : v(0)
    {}

    template <typename T>
    explicit Double( T v )
        : v(static_cast<double>(v))
    {}

    template <typename T>
    Double& operator= ( T t )
    {
        v = static_cast<double>(t);
        return *this;
    }

    bool operator < ( const Double& rhs ) const
    {
        return v < rhs.v;
    }

    template <typename T>
    bool operator < ( T rhs ) const
    {
        return v < static_cast<double>(rhs);
    }

    bool operator > ( const Double& rhs ) const
    {
        return v > rhs.v;
    }

    template <typename T>
    bool operator > ( T rhs ) const
    {
        return v > static_cast<double>(rhs);
    }

    bool operator ==( const Double& rhs ) const
    {
        return v == rhs.v;
    }

    template <typename T>
    bool operator == ( T rhs ) const
    {
        return v == static_cast<double>(rhs);
    }

    bool operator !() const
    {
        return v == 0;
    }

    Double operator -() const
    {
        return Double(-v);
    }

    Double& operator +=( const Double& t )
    {
        v += t.v;
        return *this;
    }

    template <typename T>
    Double& operator +=( T t )
    {
        v += static_cast<double>(t);
        return *this;
    }

    Double& operator -=( const Double& t )
    {
        v -= t.v;
        return *this;
    }

    template <typename T>
    Double& operator -=( T t )
    {
        v -= static_cast<double>(t);
        return *this;
    }

    Double& operator *= ( const Double& factor )
    {
        v *= factor.v;
        return *this;
    }

    template <typename T>
    Double& operator *=( T t )
    {
        v *= static_cast<double>(t);
        return *this;
    }

    Double& operator /= (const Double& divisor)
    {
        v /= divisor.v;
        return *this;
    }

    template <typename T>
    Double& operator /=( T t )
    {
         v /= static_cast<double>(t);
        return (*this);
    }

    double v;
};

//! Define numeric_limits for the custom type.
namespace std
{
    template<>
    class numeric_limits<Double> : public numeric_limits<double>
    {
    public:

        //! Limit our Double to a range of +/- 100.0
        static Double (min)()
        {
            return Double(1.e-2);
        }

        static Double (max)()
        {
            return Double(1.e2);
        }

        static Double epsilon()
        {
            return Double( std::numeric_limits<double>::epsilon() );
        }
    };
}

//! Define range checking and overflow policies.
namespace custom
{
    //! Define a custom range checker
    template<typename Traits, typename OverFlowHandler>
    struct range_checker
    {
        typedef typename Traits::argument_type argument_type ;
        typedef typename Traits::source_type S;
        typedef typename Traits::target_type T;

        //! Check range of integral types.
        static boost::numeric::range_check_result out_of_range( argument_type s )
        {
            using namespace boost::numeric;
            if( s > bounds<T>::highest() )
                return cPosOverflow;
            else if( s < bounds<T>::lowest() )
                return cNegOverflow;
            else
                return cInRange;
        }

        static void validate_range ( argument_type s )
        {
            BOOST_STATIC_ASSERT( std::numeric_limits<T>::is_bounded );
            OverFlowHandler()( out_of_range(s) );
        }
    };

    //! Overflow handler
    struct positive_overflow{};
    struct negative_overflow{};

    struct overflow_handler
    {
        void operator() ( boost::numeric::range_check_result r )
        {
            using namespace boost::numeric;
            if( r == cNegOverflow )
                throw negative_overflow() ;
            else if( r == cPosOverflow )
                throw positive_overflow() ;
        }
    };

    //! Define a rounding policy and specialize on the custom type.
    template<class S>
    struct Ceil : boost::numeric::Ceil<S>{};

    template<>
    struct Ceil<Double>
    {
      typedef Double source_type;

      typedef Double const& argument_type;

      static source_type nearbyint ( argument_type s )
      {
#if !defined(BOOST_NO_STDC_NAMESPACE)
          using std::ceil ;
#endif
          return Double( ceil(s.v) );
      }

      typedef boost::mpl::integral_c< std::float_round_style, std::round_toward_infinity> round_style;
    };

    //! Define a rounding policy and specialize on the custom type.
    template<class S>
    struct Trunc: boost::numeric::Trunc<S>{};

    template<>
    struct Trunc<Double>
    {
      typedef Double source_type;

      typedef Double const& argument_type;

      static source_type nearbyint ( argument_type s )
      {
#if !defined(BOOST_NO_STDC_NAMESPACE)
          using std::floor;
#endif
          return Double( floor(s.v) );
      }

      typedef boost::mpl::integral_c< std::float_round_style, std::round_toward_zero> round_style;
    };
}//namespace custom;

namespace boost { namespace numeric {

    //! Define the numeric_cast_traits specializations on the custom type.
    template <typename S>
    struct numeric_cast_traits<Double, S>
    {
        typedef custom::overflow_handler                         overflow_policy;
        typedef custom::range_checker
                <
                    boost::numeric::conversion_traits<Double, S>
                  , overflow_policy
                >                                                range_checking_policy;
        typedef boost::numeric::Trunc<S>                         rounding_policy;
    };

    template <typename T>
    struct numeric_cast_traits<T, Double>
    {
        typedef custom::overflow_handler                         overflow_policy;
        typedef custom::range_checker
                <
                    boost::numeric::conversion_traits<T, Double>
                  , overflow_policy
                >                                                range_checking_policy;
        typedef custom::Trunc<Double>                            rounding_policy;
    };

    //! Define the conversion from the custom type to built-in types and vice-versa.
    template<typename T>
    struct raw_converter< conversion_traits< T, Double > >
    {
        static T low_level_convert ( const Double& n )
        {
            return static_cast<T>( n.v );
        }
    };

    template<typename S>
    struct raw_converter< conversion_traits< Double, S > >
    {
        static Double low_level_convert ( const S& n )
        {
            return Double(n);
        }
    };
}}//namespace boost::numeric;