conversion/doc/converter_policies.qbk

[/
    Boost.Optional

    Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal

    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
    http://www.boost.org/LICENSE_1_0.txt)
]

[section Numeric Converter Policy Classes]


[section 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()`

[endsect]

[section 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
[link numeric_conversion_policy_overflow_handler_important_note (see IMPORTANT note)]

    namespace boost { namespace numeric {

        ``[#numeric_conversion_bad_numeric_cast]``
        class bad_numeric_cast : public std::bad_cast
        {
            public:
            virtual const char *what() const // throw()
            {
                return "bad numeric conversion: overflow";
            }

        };

        ``[#numeric_conversion_negative_overflow]``
        class negative_overflow : public bad_numeric_cast
        {
            public:
            virtual const char *what() const // throw()
            {
                return "bad numeric conversion: negative overflow";
            }
        };

        ``[#numeric_conversion_possitive_overflow]``
        class positive_overflow : public bad_numeric_cast
        {
            public:
            virtual const char *what() const // throw()
            {
                return "bad numeric conversion: positive overflow";
            }
        };


    } }

[#numeric_conversion_policy_overflow_handler_important_note]

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

[endsect]

[section Policy Float2IntRounder]

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 (only the specific parts are shown,
see the general policy form above)

[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.
]

    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

[heading 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 [link boost_numericconversion.type_requirements_and_user_defined_types_support User Defined Numeric Types]
support.

[endsect]

[section 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) ;
            }
        } ;

    } }

[endsect]

[section 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.

[endsect]

[endsect]