| Home | Libraries | People | FAQ | More

## Type Requirements and User-defined-types support

### Type Requirements

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).

### UDT's special semantics

##### 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:

- `Target=`UDT and `Source=`built-in
  - `subranged=false`
  - `supertype=Target`
  - `subtype=Source`
- `Target=`built-in and `Source=`UDT
  - `subranged=true`
  - `supertype=Source`
  - `subtype=Target`
- `Target=`UDT and `Source=`UDT
  - `subranged=false`
  - `supertype=Target`
  - `subtype=Source`

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

### 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.

### UDTs with numeric_cast

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;