libs/math/doc/overview/result_type_calc.qbk

   1 [section:result_type Calculation of the Type of the Result]
   2
   3 The functions in this library are all overloaded to accept
   4 mixed floating point (or mixed integer and floating point type)
   5 arguments.  So for example:
   6
   7    foo(1.0, 2.0);
   8    foo(1.0f, 2);
   9    foo(1.0, 2L);
  10
  11 etc, are all valid calls, as long as "foo" is a function taking two
  12 floating-point arguments.  But that leaves the question:
  13
  14 [blurb ['"Given a special function with N arguments of
  15 types T1, T2, T3 ... TN, then what type is the result?"]]
  16
  17 [*If all the arguments are of the same (floating point) type then the
  18 result is the same type as the arguments.]
  19
  20 Otherwise, the type of the result
  21 is computed using the following logic:
  22
  23 # Any arguments that are not template arguments are disregarded from
  24 further analysis.
  25 # For each type in the argument list, if that type is an integer type
  26 then it is treated as if it were of type `double` for the purposes of
  27 further analysis.
  28 # If any of the arguments is a user-defined class type, then the result type
  29 is the first such class type that is constructible from all of the other
  30 argument types.
  31 # If any of the arguments is of type `long double`, then the result is of type
  32 `long double`.
  33 # If any of the arguments is of type `double`, then the result is of type
  34 `double`.
  35 # Otherwise the result is of type `float`.
  36
  37 For example:
  38
  39    cyl_bessel(2, 3.0);
  40
  41 Returns a `double` result, as does:
  42
  43    cyl_bessel(2, 3.0f);
  44
  45 as in this case the integer first argument is treated as a `double` and takes
  46 precedence over the `float` second argument.  To get a `float` result we would need
  47 all the arguments to be of type float:
  48
  49    cyl_bessel_j(2.0f, 3.0f);
  50
  51 When one or more of the arguments is not a template argument then it
  52 doesn't effect the return type at all, for example:
  53
  54    sph_bessel(2, 3.0f);
  55
  56 returns a `float`, since the first argument is not a template argument and
  57 so doesn't effect the result: without this rule functions that take
  58 explicitly integer arguments could never return `float`.
  59
  60 And for user-defined types, typically __multiprecision,
  61
  62 All of the following return a `boost::multiprecision::cpp_bin_quad_float` result:
  63
  64    cyl_bessel_j(0, boost::multiprecision::cpp_bin_quad_float(2));
  65
  66    cyl_bessel_j(boost::multiprecision::cpp_bin_quad_float(2), 3);
  67
  68    cyl_bessel_j(boost::multiprecision::cpp_bin_quad_float(2), boost::multiprecision::cpp_bin_quad_float(3));
  69
  70 but rely on the parameters provided being exactly representable, avoiding loss of precision from construction from `double`.
  71
  72 [tip All new projects should use Boost.Multiprecision.]
  73
  74 During development of Boost.Math, __NTL was invaluable to create highly precise tables.
  75
  76 All of the following return an `NTL::RR` result:
  77
  78    cyl_bessel_j(0, NTL::RR(2));
  79
  80    cyl_bessel_j(NTL::RR(2), 3);
  81
  82    cyl_bessel_j(NTL::quad_float(2), NTL::RR(3));
  83
  84 In the last case, `quad_float` is convertible to `RR`, but not vice-versa, so
  85 the result will be an `NTL::RR`.  Note that this assumes that you are using
  86 a [link math_toolkit.high_precision.use_ntl patched NTL library].
  87
  88
  89 These rules are chosen to be compatible with the behaviour of
  90 ['ISO/IEC 9899:1999 Programming languages - C]
  91 and with the
  92 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf Draft Technical Report on C++ Library Extensions, 2005-06-24, section 5.2.1, paragraph 5].
  93
  94 [endsect] [/section:result_type Calculation of the Type of the Result]
  95
  96 [/
  97   Copyright 2006, 2012 John Maddock and Paul A. Bristow.
  98   Distributed under the Boost Software License, Version 1.0.
  99   (See accompanying file LICENSE_1_0.txt or copy at
 100   http://www.boost.org/LICENSE_1_0.txt).
 101 ]