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"; }
  };
} }

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)