boost/libs/numeric/conversion/doc/requirements.qbk - nest-cam/4320010/boost - Git at Google

 [/
     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 Type Requirements and User-defined-types support]

 [section Type Requirements]

 Both arithmetic (built-in) and user-defined numeric types require proper
 specialization of `std::numeric_limits<>` (that is, with (in-class) integral
 constants).

 The library uses `std::numeric_limits<T>::is_specialized` to detect whether
 the type is builtin or user defined, and `std::numeric_limits<T>::is_integer`,
 `std::numeric_limits<T>::is_signed` to detect whether the type is integer
 or floating point; and whether it is signed/unsigned.

 The default `Float2IntRounder` policies uses unqualified calls to functions
 `floor()` and `ceil()`; but the standard functions are introduced in scope
 by a using directive:

     using std::floor ; return floor(s);

 Therefore, for builtin arithmetic types, the std functions will be used.
 User defined types should provide overloaded versions of these functions in
 order to use the default rounder policies. If these overloads are defined
 within a user namespace argument dependent lookup (ADL) should find them,
 but if your compiler has a weak ADL you might need to put these functions
 some place else or write your own rounder policy.

 The default `Trunc<>` rounder policy needs to determine if the source value
 is positive or not, and for this it evaluates the expression
 `s < static_cast<S>(0)`. Therefore, user defined types require a visible
 `operator<` in order to use the `Trunc<>` policy (the default).


 [endsect]

 [section UDT's special semantics]

 [heading Conversion Traits]

 If a User Defined Type is involved in a conversion, it is ['assumed] that
 the UDT has [link boost_numericconversion.definitions.range_and_precision wider range]
 than any built-in type, and consequently the values
 of some `converter_traits<>` members are hardwired regardless of the reality.
 The following table summarizes this:

 * `Target=`['UDT] and `Source=`['built-in]
     * `subranged=false`
     * `supertype=Target`
     * `subtype=Source`
 * `Target=`['built-in] and `Source=`['UDT]
     * `subranged=true`
     * `supertype=Source`
     * `subtype=Target`

 * `Target=`['UDT] and `Source=`['UDT]
     * `subranged=false`
     * `supertype=Target`
     * `subtype=Source`


 The `Traits` member `udt_mixture` can be used to detect whether a UDT is involved
 and to infer the validity of the other members as shown above.

 [heading Range Checking]

 Because User Defined Numeric Types might have peculiar ranges (such as an
 unbounded range), this library does not attempt to supply a meaningful range
 checking logic when UDTs are involved in a conversion. Therefore, if either
 Target or Source are not built-in types, the bundled range checking of the
 `converter<>` function object is automatically disabled. However, it is possible
 to supply a user-defined range-checker. See
 [link boost_numericconversion.type_requirements_and_user_defined_types_support.special_policies Special Policies]

 [endsect]

 [section Special Policies]

 There are two components of the `converter<>` class that might require special
 behavior if User Defined Numeric Types are involved: the Range Checking and the
 Raw Conversion.

 When both Target and Source are built-in types, the converter class uses an internal
 range checking logic which is optimized and customized for the combined properties
 of the types.

 However, this internal logic is disabled when either type is User Defined.
 In this case, the user can specify an ['external] range checking policy which will be
 used in place of the internal code. See
 [link boost_numericconversion.type_requirements_and_user_defined_types_support.udts_with_numeric_cast numeric_cast_traits]
 for details on using UDTs with `numeric_cast`.

 The converter class performs the actual conversion using a Raw Converter policy.
 The default raw converter simply performs a `static_cast<Target>(source)`.

 However, if the a UDT is involved, the `static_cast` might not work. In this case,
 the user can implement and pass a different raw converter policy.
 See [link boost_numericconversion.numeric_converter_policy_classes.policy_rawconverter RawConverter] policy for details.

 [endsect]

 [section UDTs with numeric_cast]

 In order to employ UDTs with `numeric_cast`, the user should define
 a `numeric_cast_traits` specialization on the UDT for each conversion.
 Here is an example of specializations for converting between the UDT
 and any other type:

     namespace boost { namespace numeric {
     template <typename Source>
     struct numeric_cast_traits<UDT, Source>
     {
         typedef conversion_traits<UDT, Source>      conv_traits;

         //! The following are required:
         typedef YourOverflowHandlerPolicy           overflow_policy;
         typedef YourRangeCheckerPolicy<conv_traits> range_checking_policy;
         typedef YourFloat2IntRounderPolicy<Source>  rounding_policy;
     };
     template <typename Target>
     struct numeric_cast_traits<Target, UDT>
     {
         typedef conversion_traits<Target, UDT>      conv_traits;

         //! The following are required:
         typedef YourOverflowHandlerPolicy           overflow_policy;
         typedef YourRangeCheckerPolicy<conv_traits> range_checking_policy;
         typedef YourFloat2IntRounderPolicy<UDT>     rounding_policy;
     };
     }}//namespace boost::numeric;

 These specializations are already defined with default values for the built-in
 numeric types. It is possible to disable the generation of specializations for
 built-in types by defining `BOOST_NUMERIC_CONVERSION_RELAX_BUILT_IN_CAST_TRAITS`.
 For details on defining custom policies see [link boost_numericconversion.numeric_converter_policy_classes Converter Policies].

 Here is a full example of how to define a custom UDT for use with `numeric_cast`:

     //! Define a simple custom number
     struct Double
         :   boost::ordered_field_operators
             <
                 Double
               , boost::ordered_field_operators2< Double, long double
               , boost::ordered_field_operators2< Double, double
               , boost::ordered_field_operators2< Double, float
               , boost::ordered_field_operators2< Double, int
               , boost::ordered_field_operators2< Double, unsigned int
               , boost::ordered_field_operators2< Double, long
               , boost::ordered_field_operators2< Double, unsigned long
               , boost::ordered_field_operators2< Double, long long
               , boost::ordered_field_operators2< Double, unsigned long long
               , boost::ordered_field_operators2< Double, char
               , boost::ordered_field_operators2< Double, unsigned char
               , boost::ordered_field_operators2< Double, short
               , boost::ordered_field_operators2< Double, unsigned short
             > > > > > > > > > > > > > >
     {
         Double()
             : v(0)
         {}

         template <typename T>
         explicit Double( T v )
             : v(static_cast<double>(v))
         {}

         template <typename T>
         Double& operator= ( T t )
         {
             v = static_cast<double>(t);
             return *this;
         }

         bool operator < ( const Double& rhs ) const
         {
             return v < rhs.v;
         }

         template <typename T>
         bool operator < ( T rhs ) const
         {
             return v < static_cast<double>(rhs);
         }

         bool operator > ( const Double& rhs ) const
         {
             return v > rhs.v;
         }

         template <typename T>
         bool operator > ( T rhs ) const
         {
             return v > static_cast<double>(rhs);
         }

         bool operator ==( const Double& rhs ) const
         {
             return v == rhs.v;
         }

         template <typename T>
         bool operator == ( T rhs ) const
         {
             return v == static_cast<double>(rhs);
         }

         bool operator !() const
         {
             return v == 0;
         }

         Double operator -() const
         {
             return Double(-v);
         }

         Double& operator +=( const Double& t )
         {
             v += t.v;
             return *this;
         }

         template <typename T>
         Double& operator +=( T t )
         {
             v += static_cast<double>(t);
             return *this;
         }

         Double& operator -=( const Double& t )
         {
             v -= t.v;
             return *this;
         }

         template <typename T>
         Double& operator -=( T t )
         {
             v -= static_cast<double>(t);
             return *this;
         }

         Double& operator *= ( const Double& factor )
         {
             v *= factor.v;
             return *this;
         }

         template <typename T>
         Double& operator *=( T t )
         {
             v *= static_cast<double>(t);
             return *this;
         }

         Double& operator /= (const Double& divisor)
         {
             v /= divisor.v;
             return *this;
         }

         template <typename T>
         Double& operator /=( T t )
         {
              v /= static_cast<double>(t);
             return (*this);
         }

         double v;
     };

     //! Define numeric_limits for the custom type.
     namespace std
     {
         template<>
         class numeric_limits<Double> : public numeric_limits<double>
         {
         public:

             //! Limit our Double to a range of +/- 100.0
             static Double (min)()
             {
                 return Double(1.e-2);
             }

             static Double (max)()
             {
                 return Double(1.e2);
             }

             static Double epsilon()
             {
                 return Double( std::numeric_limits<double>::epsilon() );
             }
         };
     }

     //! Define range checking and overflow policies.
     namespace custom
     {
         //! Define a custom range checker
         template<typename Traits, typename OverFlowHandler>
         struct range_checker
         {
             typedef typename Traits::argument_type argument_type ;
             typedef typename Traits::source_type S;
             typedef typename Traits::target_type T;

             //! Check range of integral types.
             static boost::numeric::range_check_result out_of_range( argument_type s )
             {
                 using namespace boost::numeric;
                 if( s > bounds<T>::highest() )
                     return cPosOverflow;
                 else if( s < bounds<T>::lowest() )
                     return cNegOverflow;
                 else
                     return cInRange;
             }

             static void validate_range ( argument_type s )
             {
                 BOOST_STATIC_ASSERT( std::numeric_limits<T>::is_bounded );
                 OverFlowHandler()( out_of_range(s) );
             }
         };

         //! Overflow handler
         struct positive_overflow{};
         struct negative_overflow{};

         struct overflow_handler
         {
             void operator() ( boost::numeric::range_check_result r )
             {
                 using namespace boost::numeric;
                 if( r == cNegOverflow )
                     throw negative_overflow() ;
                 else if( r == cPosOverflow )
                     throw positive_overflow() ;
             }
         };

         //! Define a rounding policy and specialize on the custom type.
         template<class S>
         struct Ceil : boost::numeric::Ceil<S>{};

         template<>
         struct Ceil<Double>
         {
           typedef Double source_type;

           typedef Double const& argument_type;

           static source_type nearbyint ( argument_type s )
           {
     #if !defined(BOOST_NO_STDC_NAMESPACE)
               using std::ceil ;
     #endif
               return Double( ceil(s.v) );
           }

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

         //! Define a rounding policy and specialize on the custom type.
         template<class S>
         struct Trunc: boost::numeric::Trunc<S>{};

         template<>
         struct Trunc<Double>
         {
           typedef Double source_type;

           typedef Double const& argument_type;

           static source_type nearbyint ( argument_type s )
           {
     #if !defined(BOOST_NO_STDC_NAMESPACE)
               using std::floor;
     #endif
               return Double( floor(s.v) );
           }

           typedef boost::mpl::integral_c< std::float_round_style, std::round_toward_zero> round_style;
         };
     }//namespace custom;

     namespace boost { namespace numeric {

         //! Define the numeric_cast_traits specializations on the custom type.
         template <typename S>
         struct numeric_cast_traits<Double, S>
         {
             typedef custom::overflow_handler                         overflow_policy;
             typedef custom::range_checker
                     <
                         boost::numeric::conversion_traits<Double, S>
                       , overflow_policy
                     >                                                range_checking_policy;
             typedef boost::numeric::Trunc<S>                         rounding_policy;
         };

         template <typename T>
         struct numeric_cast_traits<T, Double>
         {
             typedef custom::overflow_handler                         overflow_policy;
             typedef custom::range_checker
                     <
                         boost::numeric::conversion_traits<T, Double>
                       , overflow_policy
                     >                                                range_checking_policy;
             typedef custom::Trunc<Double>                            rounding_policy;
         };

         //! Define the conversion from the custom type to built-in types and vice-versa.
         template<typename T>
         struct raw_converter< conversion_traits< T, Double > >
         {
             static T low_level_convert ( const Double& n )
             {
                 return static_cast<T>( n.v );
             }
         };

         template<typename S>
         struct raw_converter< conversion_traits< Double, S > >
         {
             static Double low_level_convert ( const S& n )
             {
                 return Double(n);
             }
         };
     }}//namespace boost::numeric;

 [endsect]

 [endsect]
	[/
	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 Type Requirements and User-defined-types support]

	[section Type Requirements]

	Both arithmetic (built-in) and user-defined numeric types require proper
	specialization of `std::numeric_limits<>` (that is, with (in-class) integral
	constants).

	The library uses `std::numeric_limits<T>::is_specialized` to detect whether
	the type is builtin or user defined, and `std::numeric_limits<T>::is_integer`,
	`std::numeric_limits<T>::is_signed` to detect whether the type is integer
	or floating point; and whether it is signed/unsigned.

	The default `Float2IntRounder` policies uses unqualified calls to functions
	`floor()` and `ceil()`; but the standard functions are introduced in scope
	by a using directive:

	using std::floor ; return floor(s);

	Therefore, for builtin arithmetic types, the std functions will be used.
	User defined types should provide overloaded versions of these functions in
	order to use the default rounder policies. If these overloads are defined
	within a user namespace argument dependent lookup (ADL) should find them,
	but if your compiler has a weak ADL you might need to put these functions
	some place else or write your own rounder policy.

	The default `Trunc<>` rounder policy needs to determine if the source value
	is positive or not, and for this it evaluates the expression
	`s < static_cast<S>(0)`. Therefore, user defined types require a visible
	`operator<` in order to use the `Trunc<>` policy (the default).


	[endsect]

	[section UDT's special semantics]

	[heading Conversion Traits]

	If a User Defined Type is involved in a conversion, it is ['assumed] that
	the UDT has [link boost_numericconversion.definitions.range_and_precision wider range]
	than any built-in type, and consequently the values
	of some `converter_traits<>` members are hardwired regardless of the reality.
	The following table summarizes this:

	* `Target=`['UDT] and `Source=`['built-in]
	* `subranged=false`
	* `supertype=Target`
	* `subtype=Source`
	* `Target=`['built-in] and `Source=`['UDT]
	* `subranged=true`
	* `supertype=Source`
	* `subtype=Target`

	* `Target=`['UDT] and `Source=`['UDT]
	* `subranged=false`
	* `supertype=Target`
	* `subtype=Source`


	The `Traits` member `udt_mixture` can be used to detect whether a UDT is involved
	and to infer the validity of the other members as shown above.

	[heading Range Checking]

	Because User Defined Numeric Types might have peculiar ranges (such as an
	unbounded range), this library does not attempt to supply a meaningful range
	checking logic when UDTs are involved in a conversion. Therefore, if either
	Target or Source are not built-in types, the bundled range checking of the
	`converter<>` function object is automatically disabled. However, it is possible
	to supply a user-defined range-checker. See
	[link boost_numericconversion.type_requirements_and_user_defined_types_support.special_policies Special Policies]

	[endsect]

	[section Special Policies]

	There are two components of the `converter<>` class that might require special
	behavior if User Defined Numeric Types are involved: the Range Checking and the
	Raw Conversion.

	When both Target and Source are built-in types, the converter class uses an internal
	range checking logic which is optimized and customized for the combined properties
	of the types.

	However, this internal logic is disabled when either type is User Defined.
	In this case, the user can specify an ['external] range checking policy which will be
	used in place of the internal code. See
	[link boost_numericconversion.type_requirements_and_user_defined_types_support.udts_with_numeric_cast numeric_cast_traits]
	for details on using UDTs with `numeric_cast`.

	The converter class performs the actual conversion using a Raw Converter policy.
	The default raw converter simply performs a `static_cast<Target>(source)`.

	However, if the a UDT is involved, the `static_cast` might not work. In this case,
	the user can implement and pass a different raw converter policy.
	See [link boost_numericconversion.numeric_converter_policy_classes.policy_rawconverter RawConverter] policy for details.

	[endsect]

	[section UDTs with numeric_cast]

	In order to employ UDTs with `numeric_cast`, the user should define
	a `numeric_cast_traits` specialization on the UDT for each conversion.
	Here is an example of specializations for converting between the UDT
	and any other type:

	namespace boost { namespace numeric {
	template <typename Source>
	struct numeric_cast_traits<UDT, Source>
	{
	typedef conversion_traits<UDT, Source> conv_traits;

	//! The following are required:
	typedef YourOverflowHandlerPolicy overflow_policy;
	typedef YourRangeCheckerPolicy<conv_traits> range_checking_policy;
	typedef YourFloat2IntRounderPolicy<Source> rounding_policy;
	};
	template <typename Target>
	struct numeric_cast_traits<Target, UDT>
	{
	typedef conversion_traits<Target, UDT> conv_traits;

	//! The following are required:
	typedef YourOverflowHandlerPolicy overflow_policy;
	typedef YourRangeCheckerPolicy<conv_traits> range_checking_policy;
	typedef YourFloat2IntRounderPolicy<UDT> rounding_policy;
	};
	}}//namespace boost::numeric;

	These specializations are already defined with default values for the built-in
	numeric types. It is possible to disable the generation of specializations for
	built-in types by defining `BOOST_NUMERIC_CONVERSION_RELAX_BUILT_IN_CAST_TRAITS`.
	For details on defining custom policies see [link boost_numericconversion.numeric_converter_policy_classes Converter Policies].

	Here is a full example of how to define a custom UDT for use with `numeric_cast`:

	//! Define a simple custom number
	struct Double
	: boost::ordered_field_operators
	<
	Double
	, boost::ordered_field_operators2< Double, long double
	, boost::ordered_field_operators2< Double, double
	, boost::ordered_field_operators2< Double, float
	, boost::ordered_field_operators2< Double, int
	, boost::ordered_field_operators2< Double, unsigned int
	, boost::ordered_field_operators2< Double, long
	, boost::ordered_field_operators2< Double, unsigned long
	, boost::ordered_field_operators2< Double, long long
	, boost::ordered_field_operators2< Double, unsigned long long
	, boost::ordered_field_operators2< Double, char
	, boost::ordered_field_operators2< Double, unsigned char
	, boost::ordered_field_operators2< Double, short
	, boost::ordered_field_operators2< Double, unsigned short
	> > > > > > > > > > > > > >
	{
	Double()
	: v(0)
	{}

	template <typename T>
	explicit Double( T v )
	: v(static_cast<double>(v))
	{}

	template <typename T>
	Double& operator= ( T t )
	{
	v = static_cast<double>(t);
	return *this;
	}

	bool operator < ( const Double& rhs ) const
	{
	return v < rhs.v;
	}

	template <typename T>
	bool operator < ( T rhs ) const
	{
	return v < static_cast<double>(rhs);
	}

	bool operator > ( const Double& rhs ) const
	{
	return v > rhs.v;
	}

	template <typename T>
	bool operator > ( T rhs ) const
	{
	return v > static_cast<double>(rhs);
	}

	bool operator ==( const Double& rhs ) const
	{
	return v == rhs.v;
	}

	template <typename T>
	bool operator == ( T rhs ) const
	{
	return v == static_cast<double>(rhs);
	}

	bool operator !() const
	{
	return v == 0;
	}

	Double operator -() const
	{
	return Double(-v);
	}

	Double& operator +=( const Double& t )
	{
	v += t.v;
	return *this;
	}

	template <typename T>
	Double& operator +=( T t )
	{
	v += static_cast<double>(t);
	return *this;
	}

	Double& operator -=( const Double& t )
	{
	v -= t.v;
	return *this;
	}

	template <typename T>
	Double& operator -=( T t )
	{
	v -= static_cast<double>(t);
	return *this;
	}

	Double& operator *= ( const Double& factor )
	{
	v *= factor.v;
	return *this;
	}

	template <typename T>
	Double& operator *=( T t )
	{
	v *= static_cast<double>(t);
	return *this;
	}

	Double& operator /= (const Double& divisor)
	{
	v /= divisor.v;
	return *this;
	}

	template <typename T>
	Double& operator /=( T t )
	{
	v /= static_cast<double>(t);
	return (*this);
	}

	double v;
	};

	//! Define numeric_limits for the custom type.
	namespace std
	{
	template<>
	class numeric_limits<Double> : public numeric_limits<double>
	{
	public:

	//! Limit our Double to a range of +/- 100.0
	static Double (min)()
	{
	return Double(1.e-2);
	}

	static Double (max)()
	{
	return Double(1.e2);
	}

	static Double epsilon()
	{
	return Double( std::numeric_limits<double>::epsilon() );
	}
	};
	}

	//! Define range checking and overflow policies.
	namespace custom
	{
	//! Define a custom range checker
	template<typename Traits, typename OverFlowHandler>
	struct range_checker
	{
	typedef typename Traits::argument_type argument_type ;
	typedef typename Traits::source_type S;
	typedef typename Traits::target_type T;

	//! Check range of integral types.
	static boost::numeric::range_check_result out_of_range( argument_type s )
	{
	using namespace boost::numeric;
	if( s > bounds<T>::highest() )
	return cPosOverflow;
	else if( s < bounds<T>::lowest() )
	return cNegOverflow;
	else
	return cInRange;
	}

	static void validate_range ( argument_type s )
	{
	BOOST_STATIC_ASSERT( std::numeric_limits<T>::is_bounded );
	OverFlowHandler()( out_of_range(s) );
	}
	};

	//! Overflow handler
	struct positive_overflow{};
	struct negative_overflow{};

	struct overflow_handler
	{
	void operator() ( boost::numeric::range_check_result r )
	{
	using namespace boost::numeric;
	if( r == cNegOverflow )
	throw negative_overflow() ;
	else if( r == cPosOverflow )
	throw positive_overflow() ;
	}
	};

	//! Define a rounding policy and specialize on the custom type.
	template<class S>
	struct Ceil : boost::numeric::Ceil<S>{};

	template<>
	struct Ceil<Double>
	{
	typedef Double source_type;

	typedef Double const& argument_type;

	static source_type nearbyint ( argument_type s )
	{
	#if !defined(BOOST_NO_STDC_NAMESPACE)
	using std::ceil ;
	#endif
	return Double( ceil(s.v) );
	}

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

	//! Define a rounding policy and specialize on the custom type.
	template<class S>
	struct Trunc: boost::numeric::Trunc<S>{};

	template<>
	struct Trunc<Double>
	{
	typedef Double source_type;

	typedef Double const& argument_type;

	static source_type nearbyint ( argument_type s )
	{
	#if !defined(BOOST_NO_STDC_NAMESPACE)
	using std::floor;
	#endif
	return Double( floor(s.v) );
	}

	typedef boost::mpl::integral_c< std::float_round_style, std::round_toward_zero> round_style;
	};
	}//namespace custom;

	namespace boost { namespace numeric {

	//! Define the numeric_cast_traits specializations on the custom type.
	template <typename S>
	struct numeric_cast_traits<Double, S>
	{
	typedef custom::overflow_handler overflow_policy;
	typedef custom::range_checker
	<
	boost::numeric::conversion_traits<Double, S>
	, overflow_policy
	> range_checking_policy;
	typedef boost::numeric::Trunc<S> rounding_policy;
	};

	template <typename T>
	struct numeric_cast_traits<T, Double>
	{
	typedef custom::overflow_handler overflow_policy;
	typedef custom::range_checker
	<
	boost::numeric::conversion_traits<T, Double>
	, overflow_policy
	> range_checking_policy;
	typedef custom::Trunc<Double> rounding_policy;
	};

	//! Define the conversion from the custom type to built-in types and vice-versa.
	template<typename T>
	struct raw_converter< conversion_traits< T, Double > >
	{
	static T low_level_convert ( const Double& n )
	{
	return static_cast<T>( n.v );
	}
	};

	template<typename S>
	struct raw_converter< conversion_traits< Double, S > >
	{
	static Double low_level_convert ( const S& n )
	{
	return Double(n);
	}
	};
	}}//namespace boost::numeric;

	[endsect]

	[endsect]