Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Numeric Converter Policy Classes 數字轉換器策略類

enum range_check_result
Policy OverflowHandler 策略 OverflowHandler
Policy Float2IntRounder 策略 Float2IntRounder
Policy RawConverter 策略 RawConverter
Policy UserRangeChecker 策略 UserRangeChecker

namespace boost { namespace numeric {

    enum range_check_result
    {
        cInRange     ,
        cNegOverflow ,
        cPosOverflow
    } ;

} }

Defines the values returned by boost::numeric::converter<>::out_of_range()
定義由 boost::numeric::converter<>::out_of_range() 返回的值。

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.
這個無狀態非模板策略類必須是一個函數對像,它被調用來對範圍檢查的結果進行處理。如果範圍檢查已檢測出溢出並通過調用實參來表示,則它可以拋出一個異常。如果要拋出異常,建議使用 std::bad_cast 或其派生類。

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().
該函數函數被以 validate_range() 內的轉換器的 out_of_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
// 拋出
bad_numeric_conversion 的派生類
{ 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_cast { public: virtual const char *what() const // throw()
{ return "bad numeric conversion: negative overflow"; } }; class positive_overflow : public bad_numeric_cast { public: virtual const char *what() const // throw()
{ return "bad numeric conversion: positive overflow"; } }; } }

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

對 1.33 版本的說明 在 boost 版本 1.33 之前,異常類 bad_numeric_cast 命名為 bad_numeric_conversion。但是,在 1.33 中,來自 boost/cast.hpp 的舊函數 numeric_cast<> 已完全被 boost/numeric/conversion/cast.hpp 中的新 numeric_cast<> 所替代(而且現在 boost/cast.hpp 被包含在 boost/numeric/conversion/cast.hpp 中)。那些在 boost 中已經存在了一段時間的舊函數是把 bad_numeric_cast 用作其異常類型的,所以我決定通過採用這個異常類以避免後向兼容性的問題(我猜測基於舊代碼的用戶經多於基於新代碼的)。

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.
這個無狀態模板策略類指定用於 浮點至整型 轉換的捨入方式。它提供了由轉換器暴露出來的 nearbyint() 靜態成員函數,即轉換器要 公有地繼承自這個策略

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

這些類並不是通用的捨入函數,而是專門用於 converter<> 的策略。這正是為什麼它們不是函數對象的原因。

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.
這個頭文件所提供的捨入器策略使用了數學函數 floor()ceil()。這些函數的標準版本是通過一個 using 指令引入到上下文中的,所以在正常情況下,將使用標準函數。

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.
這一技術允許缺省的捨入器策略直接用於用戶自定義類型。用戶只要求適當的 floor()ceil() 重載是可見的。請參見 用戶自定義數字類型的支持

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.
這個無狀態模板策略類用於執行從源類型到目標類型的實際轉換。它提供了由轉換器所暴露的 low_level_convert() 靜態成員函數,即轉換器是公有地繼承自該策略的。

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
對於不支持 static_cast<> 轉換為某些類型的用戶自定義類型,通常將這一策略作為一個吊鉤提供。

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

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.
它提供了由轉換器所暴露的 validate_range() 靜態成員函數,即轉換器是公有地繼承自該策略的。

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.
// 判斷值 's' 是否適合目標類型的範圍
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.
// 檢查值 's' 是否為 out_of_range(),並將檢查結果傳遞給 OverflowHandler 策略。
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.
該策略對需要範圍檢查(當涉及UDT時,缺省是禁用範圍檢查的)的用戶自定義類型作為一個吊鉤提供。本庫提供了一個類:UseInternalRangeChecker{}; 它是一個假的 RangeChecker 策略,用於通知轉換器使用內部的範圍檢查實現。


PrevUpHomeNext