Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

converter<> function object  converter<> 函數對像

Synopsis 摘要
Template parameters 模板參數
Member functions 成員函數
Range Checking Logic 範圍檢查邏輯
Examples 例子
namespace boost { namespace numeric {


    template<class T,
             class S,
             class Traits,          = conversion_traits<T,S>
             class OverflowHandler  = def_overflow_handler,
             class Float2IntRounder = Trunc< typename Traits::source_type >,
             class RawConverter     = raw_converter<Traits>,
             class UserRangeChecker = UseInternalRangeChecker
            >
    struct converter
    {
        typedef Traits traits ;

        typedef typename Traits::source_type   source_type   ;
        typedef typename Traits::argument_type argument_type ;
        typedef typename Traits::result_type   result_type   ;

        static result_type convert ( argument_type s ) ;

        result_type operator() ( argument_type s ) const ;

        // Internal member functions: 內部成員函數:
static range_check_result out_of_range ( argument_type s ) ; static void validate_range ( argument_type s ) ; static result_type low_level_convert ( argument_type s ) ; static source_type nearbyint ( argument_type s ) ; } ; } } // namespace numeric, boost

boost::numeric::converter<> is a Unary Function Object encapsulating the code to perform a numeric conversion with the direction and properties specified by the Traits template parameter. It can optionally take some policies which can be used to customize its behavior. The Traits parameter is not a policy but the parameter that defines the conversion.
boost::numeric::converter<> 是一個 單參函數對像,它封裝了執行數字轉換的代碼,轉換的方向和各種屬性由 Traits 模板參數指定。它可選地接受一些 策略 以定制其行為。Traits 參數並非策略,但該參數定義了該轉換。

T

The Numeric Type which is the Target of the conversion.

作為轉換目標t數字類型

S

The Numeric Type which is the Source of the conversion.

作為轉換數字類型

Traits

This must be a conversion traits class with the interface of boost::numeric::conversion_traits
必須是一個轉換 traits 類,具有 boost::numeric::conversion_traits 的接口

OverflowHandler

Stateless Policy called to administrate the result of the range checking.

無狀態策略,被調用以處理範圍檢查的結果。

It is a Function Object which receives the result of out_of_range() and is called inside the validate_range() static member function exposed by the converter.
它是一個 函數對像,接受 out_of_range() 的結果,在由轉換器所開放的 validate_range() 靜態成員函數中被調用。

Float2IntRounder

Stateless Policy which specifies the rounding mode used for float to integral conversions.

無狀態策略,指定用於浮點數到整數轉換的捨入方式。

It supplies the nearbyint() static member function exposed by the converter.
它提供由轉換器開放的 nearbyint() 靜態成員函數。

RawConverter

Stateless Policy which is used to perform the actual conversion.

無狀態策略,用於執行實際的轉換。

It supplies the low_level_convert() static member function exposed by the converter.
它提供由轉換器開放的 low_level_convert() 過靜態成員函數。

UserRangeChecker

Special and Optional Stateless Policy which can be used to override the internal range checking logic.

特定且可選的 無狀態策略,可用於覆蓋內部的範圍檢查邏輯。

If given, supplies alternative code for the out_of_range() and validate_range() static member functions exposed by the converter.
如果給出,則提供由轉換器開放的 out_of_range()validate_range() 靜態成員函數的替換代碼。

static result_type converter<>::convert ( argument_type s ) ; // throw 有拋出

This static member function converts an rvalue of type source_type to an rvalue of type target_type.
該靜態成員函數將一個類型為 source_type 的右值轉換為一個類型為 target_type 的右值。

If the conversion requires it, it performs a range checking before the conversion and passes the result of the check to the overflow handler policy (the default policy throws an exception if out-of-range is detected)
如果轉換需要,則在轉換前執行一個範圍檢查,並將檢查結果傳遞給溢出處理器策略(缺省的策略是在檢測到溢出時拋出一個異常)。

The implementation of this function is actually built from the policies and is basically as follows:
該函數的實現實際上是依據策略來建造,基本如下:

result_type converter<>::convert ( argument_type s )
{
    validate_range(s); // Implemented by the internal range checking logic
// (which also calls the OverflowHandler policy)
// or externally supplied by the UserRangeChecker policy.
// 由內部的範圍檢查邏輯來實現(它也調用 OverflowHandler 策略)
// 或者由 UserRangeChecker 策略所提供的外部邏輯來實現
s = nearbyint(s); // Externally supplied by the Float2IntRounder policy.
// NOTE: This is actually called only for float to int conversions.
// 由 Float2IntRounder 策略提供的外部邏輯
// 註:僅在浮點數至整數轉換時實際調用
return low_level_convert(s); // Externally supplied by the RawConverter policy.
// 由 RawConverter 策略提供的外部邏輯
}

converter<>::operator() const just calls convert()
converter<>::operator() const
只是調用 convert()

space

static range_check_result numeric_converter<>::out_of_range ( argument_type s ) ;

This internal static member function determines if the value s can be represented by the target type without overflow.
內部 靜態成員函數判斷值 s 是否可以被目標類型表示而沒有溢出。

It does not determine if the conversion is exact; that is, it does not detect inexact conversions, only out-of-range conversions (see the Definitions for further details).
它不判斷轉換是否 精確;即它不檢查 非精確的 轉換,只檢查 超出範圍的 轉換(進一步的細節請見 定義)。

The return value is of enum type boost::numeric::range_check_result
返回值為枚舉類型 boost::numeric::range_check_result

The actual code for the range checking logic is optimized for the combined properties of the source and target types. For example, a non-subranged conversion (i.e: int->float), requires no range checking, so out_of_range() returns cInRange directly. See the following table for more details.
範圍檢查邏輯的實際代碼是根據源類型和目標類型的組合特性進行優化的。例如,一個非子範圍的轉換(如:int->float),就不需要範圍檢查,所以 out_of_range() 直接返回 cInRange。更多細節請見後文中的 表格

If the user supplied a UserRangeChecker policy, is this policy which implements this function, so the implementation is user defined, although it is expected to perform the same conceptual check and return the appropriate result.
如果用戶提供了一個 UserRangeChecker 策略,該策略要實現這個函數,則該實現就是用戶自定義的,當然所期望的是要執行相同概念上的檢查並返回適當的結果。

space

static void numeric_converter<>::validate_range ( argument_type s ) ; // no throw 無拋出

This internal static member function calls out_of_range(s), and passes the result to the OverflowHandler policy class.
內部 靜態成員函數調用 out_of_range(s),並將結果傳給 OverflowHandler 策略類。

For those Target/Source combinations which don't require range checking, this is an empty inline function.
對於那些不需要範圍檢查的目標/源類型組合,它是一個空的內聯函數。

If the user supplied a UserRangeChecker policy, is this policy which implements this function, so the implementation is user defined, although it is expected to perform the same action as the default. In particular, it is expected to pass the result of the check to the overflow handler.
如果用戶提供了一個 UserRangeChecker 策略,該策略要實現這個函數,則該實現就是用戶自定義的,當然所期望的是要執行與缺省相同的動作。特別是,要將檢查的結果傳遞給溢出處理器。

space

static result_type numeric_converter<>::low_level_convert ( argument_type s ) ;

This internal static member function performs the actual conversion.
內部 靜態成員函數執行實際的轉換。

This function is externally supplied by the RawConverter policy class.
該函數在外部由 RawConverter 策略類提供。

space

static source_type converter<>::nearbyint ( argument_type s ) ;

This internal static member function, which is only used for float to int conversions, returns an integer value of floating-point type according to some rounding direction.
內部 靜態成員函數,僅用於 floatint 的轉換,根據某個捨入的方向返回浮點數類型的一個整數值。

This function is externally supplied by the Float2IntRounder policy class which encapsulates the specific rounding mode.
該函數在外部由封裝了特定捨入方式的 Float2IntRounder 策略類提供。

space

Internal Member Functions 內部成員函數

These static member functions build the actual conversion code used by convert(). The user does not have to call these if calling convert(), since convert() calls them infernally, but they can be called separately for specific needs.
這些靜態成員函數構建了用於 convert() 的實際轉換代碼。用戶代碼如果調用了 convert() 就無需調用它們,因為 convert() 已經在內部調用了它們,不過如果有特別需要,它們也可以被單獨調用。

The following table summarizes the internal range checking logic performed for each combination of the properties of Source and Target.
下表總結了對各種源類型和目標類型組合所執行的內部範圍檢查邏輯。

LowestT/HighestT denotes the highest and lowest values of the Target type, respectively.
LowestT/HighestT 分別表示目標類型的最大值和最小值。

S(n) is short for static_cast<S>(n) (S denotes the Source type).
S(n)static_cast<S>(n) 的縮寫(S 表示源類型)。

NONE indicates that for this case there is no range checking.
NONE 表示此種情況無範圍檢查。


int_to_int    |--> sig_to_sig     |--> subranged     |--> ( s >= S(LowestT) ) && ( s <= S(HighestT) )
              |                   |--> not subranged |--> NONE
              |
              |--> unsig_to_unsig |--> subranged     |--> ( s >= S(LowestT) ) && ( s <= S(HighestT) )
              |                   |--> not subranged |--> NONE
              |
              |--> sig_to_unsig   |--> pos subranged     |--> ( s >= S(0) ) && ( s <= S(HighestT) )
              |                   |--> not pos subranged |--> ( s >= S(0) )
              |
              |--> unsig_to_sig   |--> subranged     |--> ( s <= S(HighestT) )
              |                   |--> not subranged |--> NONE


int_to_float   |--> NONE


float_to_int   |--> round_to_zero         |--> ( s >  S(LowestT)-S(1)   ) && ( s <  S(HighestT)+S(1)   )
               |--> round_to_even_nearest |--> ( s >= S(LowestT)-S(0.5) ) && ( s <  S(HighestT)+S(0.5) )
               |--> round_to_infinity     |--> ( s >  S(LowestT)-S(1)   ) && ( s <= S(HighestT)        )
               |--> round_to_neg_infinity |--> ( s >= S(LowestT)        ) && ( s <  S(HighestT)+S(1)   )


float_to_float |--> subranged     |--> ( s >= S(LowestT) ) && ( s <= S(HighestT) )
               |--> not subranged |--> NONE

#include <cassert>
#include <boost/numeric/conversion/converter.hpp>

int main() {

    typedef boost::numeric::converter<int,double> Double2Int ;

    int x = Double2Int::convert(2.0);
    assert ( x == 2 );

    int y = Double2Int()(3.14); // As a function object. 因為是函數對象。
assert ( y == 3 ) ; // The default rounding is trunc. 缺省的捨入方式是截斷。
try { double m = boost::numeric::bounds<double>::highest(); int z = Double2Int::convert(m); // By default throws positive_overflow()
// 缺省拋出 positive_overflow()
} catch ( boost::numeric::positive_overflow const& ) { } return 0; }

PrevUpHomeNext