ceph/src/boost/libs/numeric/conversion/doc/conversion_traits.qbk

   1 [/
   2     Boost.Optional
   3
   4     Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
   5
   6     Distributed under the Boost Software License, Version 1.0.
   7     (See accompanying file LICENSE_1_0.txt or copy at
   8     http://www.boost.org/LICENSE_1_0.txt)
   9 ]
  10
  11 [section conversion_traits<> traits class]
  12
  13 [section Types]
  14
  15 [section enumeration int_float_mixture_enum]
  16
  17     namespace boost { namespace numeric {
  18
  19         enum int_float_mixture_enum
  20         {
  21            integral_to_integral
  22           ,integral_to_float
  23           ,float_to_integral
  24           ,float_to_float
  25         } ;
  26
  27     } } // namespace boost::numeric
  28
  29 [endsect]
  30
  31 [section enumeration sign_mixture_enum]
  32
  33     namespace boost { namespace numeric {
  34
  35     enum sign_mixture_enum
  36     {
  37        unsigned_to_unsigned
  38       ,signed_to_signed
  39       ,signed_to_unsigned
  40       ,unsigned_to_signed
  41     } ;
  42
  43     } } // namespace boost::numeric
  44
  45 [endsect]
  46
  47 [section enumeration udt_builtin_mixture_enum]
  48
  49     namespace boost { namespace numeric {
  50
  51         enum udt_builtin_mixture_enum
  52         {
  53            builtin_to_builtin
  54           ,builtin_to_udt
  55           ,udt_to_builtin
  56           ,udt_to_udt
  57         } ;
  58
  59     } } // namespace boost::numeric
  60
  61 [endsect]
  62
  63 [section template class int_float_mixture<>]
  64
  65     namespace boost { namespace numeric {
  66
  67         template <class T, class S>
  68         struct int_float_mixture : mpl::integral_c<int_float_mixture_enum, impl-def-value> {} ;
  69
  70     } } // namespace boost::numeric
  71
  72 Classifying `S` and `T` as either integral or float, this __MPL_INTEGRAL_CONSTANT__
  73 indicates the combination of these attributes.
  74
  75 Its `::value` is of enumeration type
  76 [link boost_numericconversion.conversion_traits___traits_class.types.enumeration_int_float_mixture_enum `boost::numeric::int_float_mixture_enum`]
  77
  78 [endsect]
  79
  80 [section template class sign_mixture<>]
  81
  82     namespace boost { namespace numeric {
  83
  84         template <class T, class S>
  85         struct sign_mixture : mpl::integral_c<sign_mixture_enum, impl-def-value> {} ;
  86
  87     } } // namespace boost::numeric
  88
  89 Classifying `S` and `T` as either signed or unsigned, this __MPL_INTEGRAL_CONSTANT__
  90 indicates the combination of these attributes.
  91
  92 Its `::value` is of enumeration type
  93 [link boost_numericconversion.conversion_traits___traits_class.types.enumeration_sign_mixture_enum `boost::numeric::sign_mixture_enum`]
  94
  95 [endsect]
  96
  97 [section template class udt_builtin_mixture<>]
  98
  99     namespace boost { namespace numeric {
 100
 101         template <class T, class S>
 102         struct udt_builtin_mixture : mpl::integral_c<udt_builtin__mixture_enum, impl-def-value> {} ;
 103
 104     } } // namespace boost::numeric
 105
 106 Classifying `S` and `T` as either user-defined or builtin, this __MPL_INTEGRAL_CONSTANT__
 107 indicates the combination of these attributes.
 108
 109 Its `::value` is of enumeration type
 110 [link boost_numericconversion.conversion_traits___traits_class.types.enumeration_udt_builtin_mixture_enum `boost::numeric::udt_builtin_mixture_enum`]
 111
 112 [endsect]
 113
 114 [section template class is_subranged<>]
 115
 116     namespace boost { namespace numeric {
 117
 118         template <class T, class S>
 119         struct is_subranged : mpl::bool_<impl-def-value> {} ;
 120
 121     } } // namespace boost::numeric
 122
 123 Indicates if the range of the target type `T` is a subset of the range of the source
 124 type `S`. That is: if there are some source values which fall out of the
 125 Target type's range.
 126
 127 It is a boolean __MPL_INTEGRAL_CONSTANT__.
 128
 129 It does not indicate if a particular conversion is effectively out of range;
 130 it indicates that some conversion might be out of range because not all the
 131 source values are representable as Target type.
 132
 133 [endsect]
 134
 135 [section template class conversion_traits<>]
 136
 137     namespace boost { namespace numeric {
 138
 139         template <class T, class S>
 140         struct conversion_traits
 141         {
 142             mpl::integral_c<int_float_mixture_enum  , ...> int_float_mixture ;
 143             mpl::integral_c<sign_mixture_enum       , ...> sign_mixture;
 144             mpl::integral_c<udt_builtin_mixture_enum, ...> udt_builtin_mixture ;
 145
 146             mpl::bool_<...> subranged ;
 147             mpl::bool_<...> trivial ;
 148
 149             typedef T target_type   ;
 150             typedef S source_type   ;
 151             typedef ... argument_type ;
 152             typedef ... result_type   ;
 153             typedef ... supertype     ;
 154             typedef ... subtype       ;
 155         } ;
 156
 157     } } // namespace numeric, namespace boost
 158
 159
 160 This traits class indicates some properties of a ['numeric conversion] direction:
 161 from a source type `S` to a target type `T`. It does not indicate the properties
 162 of a ['specific] conversion, but of the conversion direction. See
 163 [link boost_numericconversion.definitions.subranged_conversion_direction__subtype_and_supertype Definitions] for details.
 164
 165 The traits class provides the following __MPL_INTEGRAL_CONSTANT__\s of enumeration
 166 type. They express the combination of certain attributes of the Source and
 167 Target types (thus they are call mixture):
 168
 169 [table
 170 [[       ][        ]]
 171 [[[*int_float_mixture   ]][
 172 Same as given by the traits class
 173 [link boost_numericconversion.conversion_traits___traits_class.types.template_class_int_float_mixture__ int_float_mixture]
 174 ]]
 175 [[[*sign_mixture        ]][
 176 Same as given by the traits class
 177 [link boost_numericconversion.conversion_traits___traits_class.types.template_class_sign_mixture__ sign_mixture]
 178 ]]
 179 [[[*udt_builtin_mixture ]]
 180 [Same as given by the traits class
 181 [link boost_numericconversion.conversion_traits___traits_class.types.template_class_udt_builtin_mixture__ udt_builtin_mixture]
 182 ]]
 183 ]
 184
 185 The traits class provides the following __MPL_INTEGRAL_CONSTANT__\s of boolean type
 186 which indicates indirectly the relation between the Source and Target ranges
 187 (see [link boost_numericconversion.definitions.range_and_precision Definitions] for details).
 188
 189 [table
 190 [[       ][        ]]
 191 [[subranged ][
 192 Same as given by [link boost_numericconversion.conversion_traits___traits_class.types.template_class_is_subranged__ is_subranged]
 193 ]]
 194 [[trivial][
 195 Indicates if both Source and Target, [_without cv-qualifications], are the same type.
 196
 197 Its `::value` is of boolean type.
 198 ]]
 199 ]
 200
 201 The traits class provides the following types. They are the Source and Target types classified
 202 and qualified for different purposes.
 203
 204
 205 [table
 206 [[            ][         ]]
 207 [[[*target_type]][
 208 The template parameter `T` without cv-qualifications
 209 ]]
 210 [[[*source_type]][
 211 The template parameter `S` without cv-qualifications
 212 ]]
 213 [[[*argument_type]][
 214 This type is either source_type or `source_type const&`.
 215
 216 It represents the optimal argument type for the
 217 [link boost_numericconversion.converter___function_object converter] member functions.
 218
 219 If S is a built-in type, this is `source_type`, otherwise, this is `source_type const&`.
 220 ]]
 221 [[[*result_type]][
 222 This type is either target_type or target_type const&
 223
 224 It represents the return type of the
 225 [link boost_numericconversion.converter___function_object converter] member functions.
 226
 227 If `T==S`, it is `target_type const&`, otherwise, it is `target_type`.
 228 ]]
 229 [[[*supertype]][
 230 If the conversion is subranged, it is `source_type`, otherwise, it is `target_type`
 231 ]]
 232 [[[*subtype]][
 233 If the conversion is subranged, it is `target_type`, otherwise, it is `source_type`
 234 ]]
 235 ]
 236
 237 [endsect]
 238
 239 [endsect]
 240
 241 [section Examples]
 242
 243     #include <cassert>
 244     #include <typeinfo>
 245     #include <boost/numeric/conversion/conversion_traits.hpp>
 246
 247     int main()
 248     {
 249
 250         // A trivial conversion.
 251         typedef boost::numeric::conversion_traits<short,short> Short2Short_Traits ;
 252         assert ( Short2Short_Traits::trivial::value ) ;
 253
 254         // A subranged conversion.
 255         typedef boost::numeric::conversion_traits<double,unsigned int> UInt2Double_Traits ;
 256         assert (  UInt2Double_Traits::int_float_mixture::value == boost::numeric::integral_to_float ) ;
 257         assert (  UInt2Double_Traits::sign_mixture::value == boost::numeric::unsigned_to_signed ) ;
 258         assert ( !UInt2Double_Traits::subranged::value ) ;
 259         assert ( typeid(UInt2Double_Traits::supertype) == typeid(double) ) ;
 260         assert ( typeid(UInt2Double_Traits::subtype) == typeid(unsigned int) ) ;
 261
 262         // A doubly subranged conversion.
 263         assert ( (boost::numeric::conversion_traits<short, unsigned short>::subranged::value) );
 264         assert ( (boost::numeric::conversion_traits<unsigned short, short>::subranged::value) );
 265
 266         return 0;
 267     }
 268
 269 [endsect]
 270
 271 [endsect]
 272