1 [template tr1_overview[]
2 Many of the special functions included in this library are also a part
3 of the either the [C99] or the [tr1]. Therefore this library
4 includes a thin wrapper header `boost/math/tr1.hpp` that provides
5 compatibility with these two standards.
7 There are various pros and cons to using the library in this way:
11 * The header to include is lightweight (i.e. fast to compile).
12 * The functions have extern "C" linkage,
13 and so are usable from other languages (not just C and C++).
14 * C99 and C++ TR1 Standard compatibility.
18 * You will need to compile and link to the external Boost.Math libraries.
19 * Limited to support for the types, `float`, `double` and `long double`.
20 * Error handling is handled via setting ::errno and returning NaN's and
21 infinities: this may be less flexible than an C++ exception based approach.
23 [note The separate libraries are required *only* if you choose to use
24 boost/math/tr1.hpp rather than some other Boost.Math header, the rest
25 of Boost.Math remains header-only.]
27 The separate libraries required in order to use tr1.hpp can be compiled
28 using bjam from within the libs/math/build directory, or from the Boost
29 root directory using the usual Boost-wide install procedure.
30 Alternatively the source files are located in libs/math/src and each have
31 the same name as the function they implement. The various libraries are
35 [[Name][Type][Functions]]
36 [[boost_math_c99f-<suffix>][float][C99 Functions]]
37 [[boost_math_c99-<suffix>][double][C99 Functions]]
38 [[boost_math_c99l-<suffix>][long double][C99 Functions]]
39 [[boost_math_tr1f-<suffix>][float][TR1 Functions]]
40 [[boost_math_tr1-<suffix>][double][TR1 Functions]]
41 [[boost_math_tr1l-<suffix>][long double][TR1 Functions]]
44 Where `<suffix>` encodes the compiler and build options used to
45 build the libraries: for example "libboost_math_tr1-vc80-mt-gd.lib"
46 would be the statically linked TR1 library to use with Visual C++ 8.0,
47 in multithreading debug mode, with the DLL VC++ runtime, where as
48 "boost_math_tr1-vc80-mt.lib" would be import library for the TR1 DLL
49 to be used with Visual C++ 8.0 with the release multithreaded DLL
51 Refer to the getting started guide for a
52 [@http://www.boost.org/doc/libs/1_35_0/more/getting_started/windows.html#library-naming
53 full explanation of the `<suffix>` meanings].
56 Visual C++ users will typically have the correct library variant to link
57 against selected for them by boost/math/tr1.hpp based on your compiler
60 Users will need to define BOOST_MATH_TR1_DYN_LINK when building
61 their code if they want to link against the DLL versions of these libraries
62 rather than the static versions.
64 Users can disable auto-linking by defining BOOST_MATH_TR1_NO_LIB when
65 building: this is typically only used when linking against a customised
66 build of the libraries.]
68 [note Linux and Unix users will generally only have one variant of
69 these libraries installed, and can generally just link against
70 -lboost_math_tr1 etc.]
72 [h4 Usage Recomendations]
74 This library now presents the user with a choice:
76 * To include the header only versions of the functions and have
77 an easier time linking, but a longer compile time.
78 * To include the TR1 headers and link against an external library.
80 Which option you choose depends largely on how you prefer to work
81 and how your system is set up.
83 For example a casual user who just needs the acosh function, would
84 probably be better off including `<boost/math/special_functions/acosh.hpp>`
85 and using `boost::math::acosh(x)` in their code.
87 However, for large scale
88 software development where compile times are significant, and where the
89 Boost libraries are already built and installed on the system, then
90 including `<boost/math/tr1.hpp>` and using `boost::math::tr1::acosh(x)`
91 will speed up compile times, reduce object files sizes (since there are
92 no templates being instantiated any more), and also speed up debugging
93 runtimes - since the externally compiled libraries can be
94 compiler optimised, rather than built using full settings - the difference
95 in performance between
96 [link math_toolkit.getting_best
97 release and debug builds can be as much as 20 times],
98 so for complex applications this can be a big win.
100 [h4 Supported C99 Functions]
102 See also the [link math_toolkit.c99
103 quick reference guide for these functions].
105 namespace boost{ namespace math{ namespace tr1{ extern "C"{
107 typedef unspecified float_t;
108 typedef unspecified double_t;
110 double acosh(double x);
111 float acoshf(float x);
112 long double acoshl(long double x);
114 double asinh(double x);
115 float asinhf(float x);
116 long double asinhl(long double x);
118 double atanh(double x);
119 float atanhf(float x);
120 long double atanhl(long double x);
122 double cbrt(double x);
123 float cbrtf(float x);
124 long double cbrtl(long double x);
126 double copysign(double x, double y);
127 float copysignf(float x, float y);
128 long double copysignl(long double x, long double y);
130 double erf(double x);
132 long double erfl(long double x);
134 double erfc(double x);
135 float erfcf(float x);
136 long double erfcl(long double x);
138 double expm1(double x);
139 float expm1f(float x);
140 long double expm1l(long double x);
142 double fmax(double x, double y);
143 float fmaxf(float x, float y);
144 long double fmaxl(long double x, long double y);
146 double fmin(double x, double y);
147 float fminf(float x, float y);
148 long double fminl(long double x, long double y);
150 double hypot(double x, double y);
151 float hypotf(float x, float y);
152 long double hypotl(long double x, long double y);
154 double lgamma(double x);
155 float lgammaf(float x);
156 long double lgammal(long double x);
158 long long llround(double x);
159 long long llroundf(float x);
160 long long llroundl(long double x);
162 double log1p(double x);
163 float log1pf(float x);
164 long double log1pl(long double x);
166 long lround(double x);
167 long lroundf(float x);
168 long lroundl(long double x);
170 double nextafter(double x, double y);
171 float nextafterf(float x, float y);
172 long double nextafterl(long double x, long double y);
174 double nexttoward(double x, long double y);
175 float nexttowardf(float x, long double y);
176 long double nexttowardl(long double x, long double y);
178 double round(double x);
179 float roundf(float x);
180 long double roundl(long double x);
182 double tgamma(double x);
183 float tgammaf(float x);
184 long double tgammal(long double x);
186 double trunc(double x);
187 float truncf(float x);
188 long double truncl(long double x);
192 [h4 Supported TR1 Functions]
194 See also the [link math_toolkit.main_tr1
195 quick reference guide for these functions].
197 namespace boost{ namespace math{ namespace tr1{ extern "C"{
199 // [5.2.1.1] associated Laguerre polynomials:
200 double assoc_laguerre(unsigned n, unsigned m, double x);
201 float assoc_laguerref(unsigned n, unsigned m, float x);
202 long double assoc_laguerrel(unsigned n, unsigned m, long double x);
204 // [5.2.1.2] associated Legendre functions:
205 double assoc_legendre(unsigned l, unsigned m, double x);
206 float assoc_legendref(unsigned l, unsigned m, float x);
207 long double assoc_legendrel(unsigned l, unsigned m, long double x);
209 // [5.2.1.3] beta function:
210 double beta(double x, double y);
211 float betaf(float x, float y);
212 long double betal(long double x, long double y);
214 // [5.2.1.4] (complete) elliptic integral of the first kind:
215 double comp_ellint_1(double k);
216 float comp_ellint_1f(float k);
217 long double comp_ellint_1l(long double k);
219 // [5.2.1.5] (complete) elliptic integral of the second kind:
220 double comp_ellint_2(double k);
221 float comp_ellint_2f(float k);
222 long double comp_ellint_2l(long double k);
224 // [5.2.1.6] (complete) elliptic integral of the third kind:
225 double comp_ellint_3(double k, double nu);
226 float comp_ellint_3f(float k, float nu);
227 long double comp_ellint_3l(long double k, long double nu);
229 // [5.2.1.8] regular modified cylindrical Bessel functions:
230 double cyl_bessel_i(double nu, double x);
231 float cyl_bessel_if(float nu, float x);
232 long double cyl_bessel_il(long double nu, long double x);
234 // [5.2.1.9] cylindrical Bessel functions (of the first kind):
235 double cyl_bessel_j(double nu, double x);
236 float cyl_bessel_jf(float nu, float x);
237 long double cyl_bessel_jl(long double nu, long double x);
239 // [5.2.1.10] irregular modified cylindrical Bessel functions:
240 double cyl_bessel_k(double nu, double x);
241 float cyl_bessel_kf(float nu, float x);
242 long double cyl_bessel_kl(long double nu, long double x);
244 // [5.2.1.11] cylindrical Neumann functions;
245 // cylindrical Bessel functions (of the second kind):
246 double cyl_neumann(double nu, double x);
247 float cyl_neumannf(float nu, float x);
248 long double cyl_neumannl(long double nu, long double x);
250 // [5.2.1.12] (incomplete) elliptic integral of the first kind:
251 double ellint_1(double k, double phi);
252 float ellint_1f(float k, float phi);
253 long double ellint_1l(long double k, long double phi);
255 // [5.2.1.13] (incomplete) elliptic integral of the second kind:
256 double ellint_2(double k, double phi);
257 float ellint_2f(float k, float phi);
258 long double ellint_2l(long double k, long double phi);
260 // [5.2.1.14] (incomplete) elliptic integral of the third kind:
261 double ellint_3(double k, double nu, double phi);
262 float ellint_3f(float k, float nu, float phi);
263 long double ellint_3l(long double k, long double nu, long double phi);
265 // [5.2.1.15] exponential integral:
266 double expint(double x);
267 float expintf(float x);
268 long double expintl(long double x);
270 // [5.2.1.16] Hermite polynomials:
271 double hermite(unsigned n, double x);
272 float hermitef(unsigned n, float x);
273 long double hermitel(unsigned n, long double x);
275 // [5.2.1.18] Laguerre polynomials:
276 double laguerre(unsigned n, double x);
277 float laguerref(unsigned n, float x);
278 long double laguerrel(unsigned n, long double x);
280 // [5.2.1.19] Legendre polynomials:
281 double legendre(unsigned l, double x);
282 float legendref(unsigned l, float x);
283 long double legendrel(unsigned l, long double x);
285 // [5.2.1.20] Riemann zeta function:
286 double riemann_zeta(double);
287 float riemann_zetaf(float);
288 long double riemann_zetal(long double);
290 // [5.2.1.21] spherical Bessel functions (of the first kind):
291 double sph_bessel(unsigned n, double x);
292 float sph_besself(unsigned n, float x);
293 long double sph_bessell(unsigned n, long double x);
295 // [5.2.1.22] spherical associated Legendre functions:
296 double sph_legendre(unsigned l, unsigned m, double theta);
297 float sph_legendref(unsigned l, unsigned m, float theta);
298 long double sph_legendrel(unsigned l, unsigned m, long double theta);
300 // [5.2.1.23] spherical Neumann functions;
301 // spherical Bessel functions (of the second kind):
302 double sph_neumann(unsigned n, double x);
303 float sph_neumannf(unsigned n, float x);
304 long double sph_neumannl(unsigned n, long double x);
308 In addition sufficient additional overloads of the `double` versions of the
309 above functions are provided, so that calling the function with any mixture
310 of `float`, `double`, `long double`, or /integer/ arguments is supported, with the
311 return type determined by the __arg_promotion_rules.
313 [h4 Currently Unsupported C99 Functions]
315 double exp2(double x);
316 float exp2f(float x);
317 long double exp2l(long double x);
319 double fdim(double x, double y);
320 float fdimf(float x, float y);
321 long double fdiml(long double x, long double y);
323 double fma(double x, double y, double z);
324 float fmaf(float x, float y, float z);
325 long double fmal(long double x, long double y, long double z);
329 int ilogbl(long double x);
331 long long llrint(double x);
332 long long llrintf(float x);
333 long long llrintl(long double x);
335 double log2(double x);
336 float log2f(float x);
337 long double log2l(long double x);
339 double logb(double x);
340 float logbf(float x);
341 long double logbl(long double x);
343 long lrint(double x);
344 long lrintf(float x);
345 long lrintl(long double x);
347 double nan(const char *str);
348 float nanf(const char *str);
349 long double nanl(const char *str);
351 double nearbyint(double x);
352 float nearbyintf(float x);
353 long double nearbyintl(long double x);
355 double remainder(double x, double y);
356 float remainderf(float x, float y);
357 long double remainderl(long double x, long double y);
359 double remquo(double x, double y, int *pquo);
360 float remquof(float x, float y, int *pquo);
361 long double remquol(long double x, long double y, int *pquo);
363 double rint(double x);
364 float rintf(float x);
365 long double rintl(long double x);
367 double scalbln(double x, long ex);
368 float scalblnf(float x, long ex);
369 long double scalblnl(long double x, long ex);
371 double scalbn(double x, int ex);
372 float scalbnf(float x, int ex);
373 long double scalbnl(long double x, int ex);
375 [h4 Currently Unsupported TR1 Functions]
377 // [5.2.1.7] confluent hypergeometric functions:
378 double conf_hyperg(double a, double c, double x);
379 float conf_hypergf(float a, float c, float x);
380 long double conf_hypergl(long double a, long double c, long double x);
382 // [5.2.1.17] hypergeometric functions:
383 double hyperg(double a, double b, double c, double x);
384 float hypergf(float a, float b, float c, float x);
385 long double hypergl(long double a, long double b, long double c,
392 Copyright 2008 John Maddock and Paul A. Bristow.
393 Distributed under the Boost Software License, Version 1.0.
394 (See accompanying file LICENSE_1_0.txt or copy at
395 http://www.boost.org/LICENSE_1_0.txt).