Re: Document C++ Special Math Functions.
On 08/04/16 16:36 -0400, Ed Smith-Rowland wrote: I wanted to ship the TR29124 special math functions in libstdc++ with some documentation. More could be done but this covers the function definitions, argument ranges, template parms, and arguments. There is a little mainpage with some overview, history, biblio, and links. This is great, thank you. As this is only a documentation change it's OK for trunk with the typo fixes noted below. 2016-04-08 Edward Smith-Rowland <3dw...@verizon.net> Document C++19/TR29124 C++ Special Math Functions. * include/bits/specfun.h: Add Doxygen markup. s/C++19/C++17/ Index: include/bits/specfun.h === --- include/bits/specfun.h (revision 234525) +++ include/bits/specfun.h (working copy) @@ -75,16 +75,182 @@ * @{ */ + /** + * @mainpage Mathematical Special Functions + * + * @section intro Introduction and History + * The first significant library upgrade on the road to C++2011, + * http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1836.pdf;> + * TR1, included a set of 23 mathematical functions that significntly s/significntly/significantly/ + * extended the standard trancendental functions inherited from C and declared s/trancendental/transcendental/ + * in @. + * + * Although most components from TR1 were eventually adopted for C++11 these + * math function were left behind out of concern for implementability. + * The math functions were published as a separate international standard + * http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2010/n3060.pdf;> + * IS 29124 - Extensions to the C++ Library to Support Mathematical Special + * Functions. + * + * For C++17 these functions were incorporated into the main standard. + * + * @section contents Contents + * The folowing functions are implemented in namespace @c std: s/folowing/following/ + * - @ref assoc_laguerre "assoc_laguerre - Associated Laguerre functions" + * - @ref assoc_legendre "assoc_legendre - Associated Legendre functions" + * - @ref beta "beta - Beta functions" + * - @ref comp_ellint_1 "comp_ellint_1 - Complete elliptic functions of the first kind" + * - @ref comp_ellint_2 "comp_ellint_2 - Complete elliptic functions of the second kind" + * - @ref comp_ellint_3 "comp_ellint_3 - Complete elliptic functions of the third kind" + * - @ref cyl_bessel_i "cyl_bessel_i - Regular modified cylindrical Bessel functions" + * - @ref cyl_bessel_j "cyl_bessel_j - Cylindrical Bessel functions of the first kind" + * - @ref cyl_bessel_k "cyl_bessel_k - Irregular modified cylindrical Bessel functions" + * - @ref cyl_neumann "cyl_neumann - Cylindrical Neumann functions or Cylindrical Bessel functions of the second kind" + * - @ref ellint_1 "ellint_1 - Incomplete elliptic functions of the first kind" + * - @ref ellint_2 "ellint_2 - Incomplete elliptic functions of the second kind" + * - @ref ellint_3 "ellint_3 - Incomplete elliptic functions of the third kind" + * - @ref expint "expint - The exponential integral" + * - @ref hermite "hermite - Hermite polynomials" + * - @ref laguerre "laguerre - Laguerre functions" + * - @ref legendre "legendre - Legendre polynomials" + * - @ref riemann_zeta "riemann_zeta - The Riemann zeta function" + * - @ref sph_bessel "sph_bessel - Spherical Bessel functions" + * - @ref sph_legendre "sph_legendre - Spherical Legendre functions" + * - @ref sph_neumann "sph_neumann - Spherical Neumann functions" + * + * The hypergeometric functions were stricken from the TR29124 and C++17 + * versions of this math library because of implementation concerns. + * However, since they were in the TR1 version and since they are popular + * we kept them as an extension in namespace @c __gnu_cxx: + * - @ref conf_hyperg "conf_hyperg - Confluent hypergeometric functions" + * - @ref hyperg "hyperg - Hypergeometric functions" + * + * @section general General Features + * + * @subsection "Argument Promotion" + * The arguments suppled to the non-suffixed functions will be promoted + * according to the following rules: + * 1. If any argument intended to be floating opint is given an integral value + * That integral value is promoted to double. + * 2. All floating point arguments are promoted up to the largest floating + *point precision among them. + * + * @subsection NaN NaN Arguments + * If any of the floating point arguments supplied to these functions is + * invalid or NaN (std::numeric_limits::quiet_NaN), + * the value NaN is returned. + * + * @section impl Implementation + * + * We strive to implement the underlying math with type generic algorithms + * to the greatest extent possible. In practice, the function are thin s/function/functions/ + * wrappers that dispatch to function templates. Type dependence is + * controlled
Document C++ Special Math Functions.
I wanted to ship the TR29124 special math functions in libstdc++ with some documentation. More could be done but this covers the function definitions, argument ranges, template parms, and arguments. There is a little mainpage with some overview, history, biblio, and links. 2016-04-08 Edward Smith-Rowland <3dw...@verizon.net> Document C++19/TR29124 C++ Special Math Functions. * include/bits/specfun.h: Add Doxygen markup. Index: include/bits/specfun.h === --- include/bits/specfun.h (revision 234525) +++ include/bits/specfun.h (working copy) @@ -75,16 +75,182 @@ * @{ */ + /** + * @mainpage Mathematical Special Functions + * + * @section intro Introduction and History + * The first significant library upgrade on the road to C++2011, + * http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1836.pdf;> + * TR1, included a set of 23 mathematical functions that significntly + * extended the standard trancendental functions inherited from C and declared + * in @. + * + * Although most components from TR1 were eventually adopted for C++11 these + * math function were left behind out of concern for implementability. + * The math functions were published as a separate international standard + * http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2010/n3060.pdf;> + * IS 29124 - Extensions to the C++ Library to Support Mathematical Special + * Functions. + * + * For C++17 these functions were incorporated into the main standard. + * + * @section contents Contents + * The folowing functions are implemented in namespace @c std: + * - @ref assoc_laguerre "assoc_laguerre - Associated Laguerre functions" + * - @ref assoc_legendre "assoc_legendre - Associated Legendre functions" + * - @ref beta "beta - Beta functions" + * - @ref comp_ellint_1 "comp_ellint_1 - Complete elliptic functions of the first kind" + * - @ref comp_ellint_2 "comp_ellint_2 - Complete elliptic functions of the second kind" + * - @ref comp_ellint_3 "comp_ellint_3 - Complete elliptic functions of the third kind" + * - @ref cyl_bessel_i "cyl_bessel_i - Regular modified cylindrical Bessel functions" + * - @ref cyl_bessel_j "cyl_bessel_j - Cylindrical Bessel functions of the first kind" + * - @ref cyl_bessel_k "cyl_bessel_k - Irregular modified cylindrical Bessel functions" + * - @ref cyl_neumann "cyl_neumann - Cylindrical Neumann functions or Cylindrical Bessel functions of the second kind" + * - @ref ellint_1 "ellint_1 - Incomplete elliptic functions of the first kind" + * - @ref ellint_2 "ellint_2 - Incomplete elliptic functions of the second kind" + * - @ref ellint_3 "ellint_3 - Incomplete elliptic functions of the third kind" + * - @ref expint "expint - The exponential integral" + * - @ref hermite "hermite - Hermite polynomials" + * - @ref laguerre "laguerre - Laguerre functions" + * - @ref legendre "legendre - Legendre polynomials" + * - @ref riemann_zeta "riemann_zeta - The Riemann zeta function" + * - @ref sph_bessel "sph_bessel - Spherical Bessel functions" + * - @ref sph_legendre "sph_legendre - Spherical Legendre functions" + * - @ref sph_neumann "sph_neumann - Spherical Neumann functions" + * + * The hypergeometric functions were stricken from the TR29124 and C++17 + * versions of this math library because of implementation concerns. + * However, since they were in the TR1 version and since they are popular + * we kept them as an extension in namespace @c __gnu_cxx: + * - @ref conf_hyperg "conf_hyperg - Confluent hypergeometric functions" + * - @ref hyperg "hyperg - Hypergeometric functions" + * + * @section general General Features + * + * @subsection "Argument Promotion" + * The arguments suppled to the non-suffixed functions will be promoted + * according to the following rules: + * 1. If any argument intended to be floating opint is given an integral value + * That integral value is promoted to double. + * 2. All floating point arguments are promoted up to the largest floating + *point precision among them. + * + * @subsection NaN NaN Arguments + * If any of the floating point arguments supplied to these functions is + * invalid or NaN (std::numeric_limits::quiet_NaN), + * the value NaN is returned. + * + * @section impl Implementation + * + * We strive to implement the underlying math with type generic algorithms + * to the greatest extent possible. In practice, the function are thin + * wrappers that dispatch to function templates. Type dependence is + * controlled with std::numeric_limits and functions thereof. + * + * We don't promote *c float to *c double or *c double to long double + * reflexively. The goal is for float functions to operate more quickly, + * at the cost of float accuracy and possibly a smaller domain of validity. + * Similaryly, long