Boost Numeric Conversion Library - Converter Policies

###  | # Boost Numeric Conversion Library # Header boost/numeric/conversion/converter_policies.hpp

## Contents

1. `enumeration range_check_result`
2. `Policy OverflowHandler`
   - class `silent_overflow_handler`
   - class `def_overflow_handler` (Default Policy)
   - class `bad_numeric_cast` (see IMPORTANT note)
   - class `negative_overflow`
   - class `positive_overflow`
3. `Policy FloatToIntRounder`
   - class `Trunc<T>` (Default Policy)
   - class `RoundEven<T>`
   - class `Ceil<T>`
   - class `Floor<T>`
4. `Policy RawConverter`
   - class `raw_converter class` (Default)
5. `Policy UserRangeChecker`
   - class `UseInternalRangeChecker class` (Default)

## Types

## `enum range_check_result`

    namespace boost { namespace numeric {

      enum range_check_result
      {
        cInRange     ,
        cNegOverflow ,
        cPosOverflow
      } ;

    } }

Defines the values returned by `boost::numeric::converter<>::out_of_range()`

## Policy `OverflowHandler`

This stateless non-template policy class must be a function object and is called to administrate the result of the range checking. It can throw an exception if overflow has been detected by the range checking as indicated by its argument. If it throws, is is recommended that it be `std::bad_cast` or derived.

It must have the following interface (it does not has to be a template class):

      struct YourOverflowHandlerPolicy
      {
        void operator() ( boost::range_check_result ) ; // throw bad_cast or derived
      } ;

It is called with the result of the converter's `out_of_range()` inside `validate_range()`.

These are the two overflow handler classes provided by the library:

    namespace boost { namespace numeric {

      struct def_overflow_handler
      {
        void operator() ( range_check_result r ) // throw bad_numeric_conversion derived
        {
          if ( r == cNegOverflow )
            throw negative_overflow() ;
          else if ( r == cPosOverflow )
                 throw positive_overflow() ;
        }
      } ;

      struct silent_overflow_handler
      {
        void operator() ( range_check_result ) // no-throw
          {}
      } ;

    } }

And these are the Exception Classes thrown by the default overflow handler (see IMPORTANT note)

    namespace boost { namespace numeric {

      class bad_numeric_cast : public std::bad_cast
      {
        public:

          virtual const char *what() const // throw()
            {  return "bad numeric conversion: overflow"; }
      };

      class negative_overflow : public bad_numeric_conversion
      {
        public:

          virtual const char *what() const // throw()
            {  return "bad numeric conversion: negative overflow"; }
      };
      class positive_overflow : public bad_numeric_conversion
      {
        public:

          virtual const char *what() const // throw()
            { return "bad numeric conversion: positive overflow"; }
      };
    } }

IMPORTANT RELEASE NOTE for 1.33

> Previous to boost version 1.33, the exception class `bad_numeric_cast` was named `bad_numeric_conversion`. However, in 1.33, the old function `numeric_cast<>` from `boost/cast.hpp` was completly replaced by the new `numeric_cast<>` in `boost/numeric/conversion/cast.hpp` (and `boost/cast.hpp` is including `boost/numeric/conversion/cast.hpp` now). That old function which existed in boost for quite some time used the `bad_numeric_cast` as its exception type so I decided to avoid backward compatibility problems by adopting it (guessing that the user base for the old code is wider than for the new code).

## Policy `FloatToIntRounder`

This stateless template policy class specifies the rounding mode used for float to integral conversions. It supplies the `"nearbyint()"` static member function exposed by the converter, which means that it publicly inherits from this policy.

The policy must have the following interface:

      template<class S>
      struct YourFloat2IntRounderPolicy
      {
        typedef S               source_type ;
        typedef {S or S const&} argument_type ;

        static source_type nearbyint ( argument_type s ) { ... }

        typedef mpl::integral_c<std::float_round_style,std::round_...> round_style ;
      } ;

These are the rounder classes provided by the library:

> NOTE: These classes are not intended to be general purpose rounding functions but specific policies for converter<>. This is why they are not function objects.

> (only the specific parts are shown, see the general policy form above)

>     namespace boost { namespace numeric {

>       template<class S>
>       struct Trunc
>       {
>         static source_type nearbyint ( argument_type s )
>           {
>             using std::floor ;
>             using std::ceil  ;
>             return s >= static_cast<S>(0) ? floor(s) : ceil(s) ;
>           }

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

>       template<class S>
>       struct RoundEven
>       {
>         static source_type nearbyint ( argument_type s )
>           {
>             return impl-defined-value ;
>           }

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

>       template<class S>
>       struct Ceil
>       {
>         static source_type nearbyint ( argument_type s )
>         {
>           using std::ceil ;
>           return ceil(s) ;
>         }

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

>       template<class S>
>       struct Floor
>       {
>         static source_type nearbyint ( argument_type s )
>         {
>           using std::floor ;
>           return floor(s) ;
>         }

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

>     } } // namespace numeric, namespace boost

### Math Functions used by the rounder policies

The rounder policies supplied by this header use math functions floor() and ceil(). The standard versions of these functions are introduced in context by a using directive, so in normal conditions, the standard functions will be used.
However, if there are other visible corresponding overloads an ambiguity could arise. In this case, the user can supply her own rounder policy which could, for instance, use a fully qualified call.
This technique allows the default rounder policies to be used directly with user defined types. The user only requires that suitable overloads of floor() and ceil() be visible. See also User Defined Numeric Types support

## Policy `RawConverter`

This stateless template policy class is used to perform the actual conversion from Source to Target. It supplies the `"low_level_convert()"` static member function exposed by the converter, which means that it publicly inherits from this policy.

The policy must have the following interface:

      template<class Traits>
      struct YourRawConverterPolicy
      {
        typedef typename Traits::result_type   result_type   ;
        typedef typename Traits::argument_type argument_type ;

        static result_type low_level_convert ( argument_type s ) { return <impl defined> ; }
      } ;

This policy is mostly provided as a hook for user defined types which don't support `static_cast<>` conversions to some types

This is the only raw converter policy class provided by the library:

    namespace boost { namespace numeric {

      template<class Traits>
      struct raw_numeric_converter
      {
        typedef typename Traits::result_type   result_type   ;
        typedef typename Traits::argument_type argument_type ;

        static result_type low_level_convert ( argument_type s )
          { return static_cast<result_type>(s) ; }
      } ;

    }

## Policy `UserRangeChecker`

This stateless template policy class is used -only if supplied- to override the internal range checking logic.
It supplies the `"validate_range()"` static member function exposed by the converter, which means that it publicly inherits from this policy.

The policy must have the following interface:

      template<class Traits>
      struct YourRangeCheckerPolicy
      {
         typedef typename Traits::argument_type argument_type ;

         // Determines if the value 's' fits in the range of the Target type.
         static range_check_result out_of_range ( argument_type s ) ;

         // Checks whether the value 's' is out_of_range()
         // and passes the result of the check to the OverflowHandler policy.
         static void validate_range ( argument_type s )
           {
             OverflowHandler()( out_of_range(s) ) ;
           }
      } ;

This policy is only provided as a hook for user defined types which require range checking (which is disabled by default when a UDT is involved).
The library provides a class: `UseInternalRangeChecker{};` which is a fake RangeChecker policy used to signal the converter to use its internal range checking implementation.

Back to Numeric Conversion library index

Revised 23 June 2004

© Copyright Fernando Luis Cacciola Carballal, 2004

Use, modification, and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)