From f543ec2639dbbc506d64018cee50d1d518f3f3cb Mon Sep 17 00:00:00 2001 From: John Maddock Date: Mon, 4 Jun 2012 17:50:57 +0000 Subject: [PATCH] Address doc concerns of Vincente Botet Escriba in pre-review comments. Rebuild docs. [SVN r78807] --- .../boost_multiprecision/indexes/s01.html | 4 +- .../boost_multiprecision/indexes/s02.html | 4 +- .../boost_multiprecision/indexes/s03.html | 4 +- .../boost_multiprecision/indexes/s04.html | 4 +- doc/html/boost_multiprecision/intro.html | 20 ++ doc/html/boost_multiprecision/perf.html | 6 +- .../perf/float_performance.html | 18 +- .../perf/integer_performance.html | 40 +-- .../perf/rational_performance.html | 18 +- .../boost_multiprecision/perf/realworld.html | 4 +- doc/html/boost_multiprecision/ref.html | 1 + .../boost_multiprecision/ref/backendconc.html | 17 +- .../boost_multiprecision/ref/cpp_dec_ref.html | 3 + .../boost_multiprecision/ref/cpp_int_ref.html | 3 + .../boost_multiprecision/ref/gmp_int_ref.html | 3 + .../boost_multiprecision/ref/headers.html | 331 ++++++++++++++++++ .../boost_multiprecision/ref/mp_number.html | 24 +- .../boost_multiprecision/ref/mpf_ref.html | 3 + .../boost_multiprecision/ref/mpfr_ref.html | 3 + .../boost_multiprecision/ref/tom_int_ref.html | 3 + .../boost_multiprecision/tut/conversions.html | 15 + .../tut/floats/cpp_dec_float.html | 15 + .../tut/floats/mpfr_float.html | 5 + .../tut/ints/cpp_int.html | 14 + .../tut/ints/gmp_int.html | 5 + doc/html/index.html | 3 +- doc/multiprecision.qbk | 101 +++++- .../multiprecision/detail/mp_number_base.hpp | 14 + include/boost/multiprecision/mpfr.hpp | 2 +- 29 files changed, 628 insertions(+), 59 deletions(-) create mode 100644 doc/html/boost_multiprecision/ref/headers.html diff --git a/doc/html/boost_multiprecision/indexes/s01.html b/doc/html/boost_multiprecision/indexes/s01.html index 0ae96943..3f5d4981 100644 --- a/doc/html/boost_multiprecision/indexes/s01.html +++ b/doc/html/boost_multiprecision/indexes/s01.html @@ -13,9 +13,9 @@
PrevUpHomeNext
-
+

-Function Index

+Function Index

A B C D E F I L M P R S T Z

diff --git a/doc/html/boost_multiprecision/indexes/s02.html b/doc/html/boost_multiprecision/indexes/s02.html index d7ff7db4..227b42a5 100644 --- a/doc/html/boost_multiprecision/indexes/s02.html +++ b/doc/html/boost_multiprecision/indexes/s02.html @@ -13,9 +13,9 @@
PrevUpHomeNext
-
+

-Class Index

+Class Index

C G M N T

diff --git a/doc/html/boost_multiprecision/indexes/s03.html b/doc/html/boost_multiprecision/indexes/s03.html index 15f2b2a6..f078a0ef 100644 --- a/doc/html/boost_multiprecision/indexes/s03.html +++ b/doc/html/boost_multiprecision/indexes/s03.html @@ -13,9 +13,9 @@
PrevUpHomeNext
-
+

-Typedef Index

+Typedef Index

C I L M T

diff --git a/doc/html/boost_multiprecision/indexes/s04.html b/doc/html/boost_multiprecision/indexes/s04.html index 2fe2796a..5c34b04c 100644 --- a/doc/html/boost_multiprecision/indexes/s04.html +++ b/doc/html/boost_multiprecision/indexes/s04.html @@ -12,9 +12,9 @@
PrevUpHome
-
+

-Index

+Index

A B C D E F G I L M N O P R S T Z

diff --git a/doc/html/boost_multiprecision/intro.html b/doc/html/boost_multiprecision/intro.html index af4854f1..e13b16a1 100644 --- a/doc/html/boost_multiprecision/intro.html +++ b/doc/html/boost_multiprecision/intro.html @@ -86,6 +86,26 @@ my_float a, b, c; // These variables have 300 decimal digits precision +

+ Note that mixing arithmetic operations using types of different precision is + strictly forbidden: +

+
#include <boost/multiprecision/cpp_int.hpp>
+
+namespace mp = boost::multiprecision;     // Reduce the typing a bit later...
+
+mp::mp_int128_t a(3), b(2);
+mp::mp_int512_t c(50), d;
+
+d = c * a;   // Compiler error
+
+

+ However, conversions are allowed: +

+
d = a; // OK, widening conversion.
+d = a * b;  // OK, can convert from an expression template too.
+d = mp::mp_int512_t(a) * c; // OK, all the types in the expression are the same now.
+
Expression diff --git a/doc/html/boost_multiprecision/perf.html b/doc/html/boost_multiprecision/perf.html index 7460f077..7a2b730a 100644 --- a/doc/html/boost_multiprecision/perf.html +++ b/doc/html/boost_multiprecision/perf.html @@ -6,12 +6,12 @@ - +
-PrevUpHomeNext +PrevUpHomeNext

@@ -40,7 +40,7 @@
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/boost_multiprecision/perf/float_performance.html b/doc/html/boost_multiprecision/perf/float_performance.html index 9e9b8217..d34ab87c 100644 --- a/doc/html/boost_multiprecision/perf/float_performance.html +++ b/doc/html/boost_multiprecision/perf/float_performance.html @@ -33,7 +33,7 @@ The tests were run on 32-bit Windows Vista machine.

-

Table 1.8. Operator +

+

Table 1.10. Operator +

@@ -134,7 +134,7 @@

-

Table 1.9. Operator +(int)

+

Table 1.11. Operator +(int)

@@ -235,7 +235,7 @@

-

Table 1.10. Operator -

+

Table 1.12. Operator -

@@ -336,7 +336,7 @@

-

Table 1.11. Operator -(int)

+

Table 1.13. Operator -(int)

@@ -437,7 +437,7 @@

-

Table 1.12. Operator *

+

Table 1.14. Operator *

@@ -538,7 +538,7 @@

-

Table 1.13. Operator *(int)

+

Table 1.15. Operator *(int)

@@ -639,7 +639,7 @@

-

Table 1.14. Operator /

+

Table 1.16. Operator /

@@ -740,7 +740,7 @@

-

Table 1.15. Operator /(int)

+

Table 1.17. Operator /(int)

@@ -841,7 +841,7 @@

-

Table 1.16. Operator str

+

Table 1.18. Operator str

diff --git a/doc/html/boost_multiprecision/perf/integer_performance.html b/doc/html/boost_multiprecision/perf/integer_performance.html index b7bbe0e7..56ea5b0e 100644 --- a/doc/html/boost_multiprecision/perf/integer_performance.html +++ b/doc/html/boost_multiprecision/perf/integer_performance.html @@ -37,7 +37,7 @@ much better there.

-

Table 1.17. Operator +

+

Table 1.19. Operator +

@@ -186,7 +186,7 @@

-

Table 1.18. Operator +(int)

+

Table 1.20. Operator +(int)

@@ -335,7 +335,7 @@

-

Table 1.19. Operator -

+

Table 1.21. Operator -

@@ -484,7 +484,7 @@

-

Table 1.20. Operator -(int)

+

Table 1.22. Operator -(int)

@@ -633,7 +633,7 @@

-

Table 1.21. Operator *

+

Table 1.23. Operator *

@@ -782,7 +782,7 @@

-

Table 1.22. Operator *(int)

+

Table 1.24. Operator *(int)

@@ -931,7 +931,7 @@

-

Table 1.23. Operator /

+

Table 1.25. Operator /

@@ -1080,7 +1080,7 @@

-

Table 1.24. Operator /(int)

+

Table 1.26. Operator /(int)

@@ -1229,7 +1229,7 @@

-

Table 1.25. Operator %

+

Table 1.27. Operator %

@@ -1378,7 +1378,7 @@

-

Table 1.26. Operator %(int)

+

Table 1.28. Operator %(int)

@@ -1527,7 +1527,7 @@

-

Table 1.27. Operator <<

+

Table 1.29. Operator <<

@@ -1676,7 +1676,7 @@

-

Table 1.28. Operator >>

+

Table 1.30. Operator >>

@@ -1825,7 +1825,7 @@

-

Table 1.29. Operator &

+

Table 1.31. Operator &

@@ -1974,7 +1974,7 @@

-

Table 1.30. Operator &(int)

+

Table 1.32. Operator &(int)

@@ -2123,7 +2123,7 @@

-

Table 1.31. Operator ^

+

Table 1.33. Operator ^

@@ -2272,7 +2272,7 @@

-

Table 1.32. Operator ^(int)

+

Table 1.34. Operator ^(int)

@@ -2421,7 +2421,7 @@

-

Table 1.33. Operator |

+

Table 1.35. Operator |

@@ -2570,7 +2570,7 @@

-

Table 1.34. Operator |(int)

+

Table 1.36. Operator |(int)

@@ -2719,7 +2719,7 @@

-

Table 1.35. Operator gcd

+

Table 1.37. Operator gcd

@@ -2868,7 +2868,7 @@

-

Table 1.36. Operator str

+

Table 1.38. Operator str

diff --git a/doc/html/boost_multiprecision/perf/rational_performance.html b/doc/html/boost_multiprecision/perf/rational_performance.html index 6736d065..98fb8836 100644 --- a/doc/html/boost_multiprecision/perf/rational_performance.html +++ b/doc/html/boost_multiprecision/perf/rational_performance.html @@ -33,7 +33,7 @@ The tests were run on 32-bit Windows Vista machine.

-

Table 1.37. Operator +

+

Table 1.39. Operator +

@@ -128,7 +128,7 @@

-

Table 1.38. Operator +(int)

+

Table 1.40. Operator +(int)

@@ -223,7 +223,7 @@

-

Table 1.39. Operator -

+

Table 1.41. Operator -

@@ -318,7 +318,7 @@

-

Table 1.40. Operator -(int)

+

Table 1.42. Operator -(int)

@@ -413,7 +413,7 @@

-

Table 1.41. Operator *

+

Table 1.43. Operator *

@@ -508,7 +508,7 @@

-

Table 1.42. Operator *(int)

+

Table 1.44. Operator *(int)

@@ -603,7 +603,7 @@

-

Table 1.43. Operator /

+

Table 1.45. Operator /

@@ -698,7 +698,7 @@

-

Table 1.44. Operator /(int)

+

Table 1.46. Operator /(int)

@@ -793,7 +793,7 @@

-

Table 1.45. Operator str

+

Table 1.47. Operator str

diff --git a/doc/html/boost_multiprecision/perf/realworld.html b/doc/html/boost_multiprecision/perf/realworld.html index 4dd0d5ef..a084ecc1 100644 --- a/doc/html/boost_multiprecision/perf/realworld.html +++ b/doc/html/boost_multiprecision/perf/realworld.html @@ -33,7 +33,7 @@ The tests were run on 32-bit Windows Vista machine.

-

Table 1.6. Bessel Function Performance

+

Table 1.8. Bessel Function Performance

@@ -147,7 +147,7 @@

-

Table 1.7. Non-Central T Distribution Performance

+

Table 1.9. Non-Central T Distribution Performance

diff --git a/doc/html/boost_multiprecision/ref.html b/doc/html/boost_multiprecision/ref.html index 35ad59f4..4f869c43 100644 --- a/doc/html/boost_multiprecision/ref.html +++ b/doc/html/boost_multiprecision/ref.html @@ -26,6 +26,7 @@
mpfr_float_backend
cpp_dec_float
Backend Requirements
+
Header File Structure
diff --git a/doc/html/boost_multiprecision/ref/backendconc.html b/doc/html/boost_multiprecision/ref/backendconc.html index 3bf6b60f..c2465281 100644 --- a/doc/html/boost_multiprecision/ref/backendconc.html +++ b/doc/html/boost_multiprecision/ref/backendconc.html @@ -7,11 +7,11 @@ - +
-PrevUpHomeNext +PrevUpHomeNext

@@ -2266,7 +2266,16 @@

-
+

+ The tables above place no throws requirements on any + of the operations. It is up to each type modelling this concept to decide + when or whether throwing an exception is desirable. However, thrown exceptions + should always either be the type, or inherit from the type std::runtime_error. + For example, a floating point type might choose to throw std::overflow_error + whenever the result of an operation would be infinite, and std::underflow_error + whenever it would round to zero. +

+
@@ -2289,7 +2298,7 @@
[Note] Note
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/boost_multiprecision/ref/cpp_dec_ref.html b/doc/html/boost_multiprecision/ref/cpp_dec_ref.html index 9d34b1e6..48ce9b5b 100644 --- a/doc/html/boost_multiprecision/ref/cpp_dec_ref.html +++ b/doc/html/boost_multiprecision/ref/cpp_dec_ref.html @@ -41,6 +41,9 @@ template argument should not be set too high or the classes size will grow unreasonably large.

+

+ The type of number_category<cpp_int<Args...> >::type is mpl::int_<number_kind_floating_point>. +

More information on this type can be found in the tutorial.

diff --git a/doc/html/boost_multiprecision/ref/cpp_int_ref.html b/doc/html/boost_multiprecision/ref/cpp_int_ref.html index 40530e86..43160fed 100644 --- a/doc/html/boost_multiprecision/ref/cpp_int_ref.html +++ b/doc/html/boost_multiprecision/ref/cpp_int_ref.html @@ -79,6 +79,9 @@

+

+ The type of number_category<cpp_int<Args...> >::type is mpl::int_<number_kind_integer>. +

More information on this type can be found in the tutorial.

diff --git a/doc/html/boost_multiprecision/ref/gmp_int_ref.html b/doc/html/boost_multiprecision/ref/gmp_int_ref.html index 71dfb0ae..6d536179 100644 --- a/doc/html/boost_multiprecision/ref/gmp_int_ref.html +++ b/doc/html/boost_multiprecision/ref/gmp_int_ref.html @@ -31,6 +31,9 @@ type. It's members and non-member functions are deliberately not documented: these are considered implementation details that are subject to change.

+

+ The type of number_category<cpp_int<Args...> >::type is mpl::int_<number_kind_integer>. +

More information on this type can be found in the tutorial.

diff --git a/doc/html/boost_multiprecision/ref/headers.html b/doc/html/boost_multiprecision/ref/headers.html new file mode 100644 index 00000000..010807eb --- /dev/null +++ b/doc/html/boost_multiprecision/ref/headers.html @@ -0,0 +1,331 @@ + + + +Header File Structure + + + + + + + + +
+PrevUpHomeNext +
+
+

+Header File Structure +

+
+

Table 1.6. Top level headers

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ Header +

+ 		+

+ Contains +

+
+

+ cpp_int.hpp +

+ 		+

+ The cpp_int backend + type. +

+
+

+ gmp.hpp +

+ 		+

+ Defines all GMP related + backends. +

+
+

+ integer_ops.hpp +

+ 		+

+ Integer specific non-member functions. +

+
+

+ miller_rabin.hpp +

+ 		+

+ Miller Rabin primality testing code. +

+
+

+ mp_number.hpp +

+ 		+

+ Defines the mp_number + backend, is included by all the backend headers. +

+
+

+ mpfr.hpp +

+ 		+

+ Defines the mpfr_float_backend backend. +

+
+

+ random.hpp +

+ 		+

+ Defines code to interoperate with Boost.Random. +

+
+

+ rational_adapter.hpp +

+ 		+

+ Defines the rational_adapter + backend. +

+
+

+ cpp_dec_float.hpp +

+ 		+

+ Defines the cpp_dec_float + backend. +

+
+

+ tommath.hpp +

+ 		+

+ Defines the tommath_int + backend. +

+
+

+ concepts/mp_number_architypes.hpp +

+ 		+

+ Defines a backend concept architypes for testing use. +

+
+
+
+

Table 1.7. Implementation Headers]

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ Header +

+ 		+

+ Contains +

+
+

+ detail/big_lanczos.hpp +

+ 		+

+ Lanczos support for Boost.Math integration. +

+
+

+ detail/cpp_int_core.hpp +

+ 		+

+ Platform and peformance tuning for the cpp_int + backend. +

+
+

+ detail/default_ops.hpp +

+ 		+

+ Default versions of the optional backend non-member functions. +

+
+

+ detail/generic_interconvert.hpp +

+ 		+

+ Generic interconversion routines. +

+
+

+ detail/mp_number_base.hpp +

+ 		+

+ All the expression template code, metaprogramming, and operator + overloads for mp_number. +

+
+

+ detail/no_et_ops.hpp +

+ 		+

+ The non-expression template operators. +

+
+

+ defail/functions/constants.hpp +

+ 		+

+ Defines constants used by the floating point functions. +

+
+

+ detail/functions/pow.hpp +

+ 		+

+ Defines default versions of the power and exponential related floating + point functions. +

+
+

+ detail/functions/trig.hpp +

+ 		+

+ Defines default versions of the trigonometric related floating + point functions. +

+
+
+
+
+ + + +
Copyright © 2002-2012 John Maddock and Christopher Kormanyos

+ 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) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/boost_multiprecision/ref/mp_number.html b/doc/html/boost_multiprecision/ref/mp_number.html index 75a54542..5f2605b4 100644 --- a/doc/html/boost_multiprecision/ref/mp_number.html +++ b/doc/html/boost_multiprecision/ref/mp_number.html @@ -74,6 +74,8 @@ }; // Non member operators: +unmentionable-expression-template-type operator+(const see-below&); +unmentionable-expression-template-type operator-(const see-below&); unmentionable-expression-template-type operator+(const see-below&, const see-below&); unmentionable-expression-template-type operator-(const see-below&, const see-below&); unmentionable-expression-template-type operator*(const see-below&, const see-below&); @@ -242,6 +244,13 @@
  • Any type that the Backend is constructible or assignable from.
    • +
  • + An rvalue reference to another mp_number. + Move-semantics are used for construction if the backend also supports + rvalue reference construction. In the case of assignment, move semantics + are always supported when the argument is an rvalue reference irrespective + of the backend. +

    • In addition, if the type has multiple components (for example rational or @@ -292,6 +301,10 @@ type with a positive value (negative values result in a std::runtime_error being thrown).

    +

    + Note that all the types involved in the expression must evaluate to the same + type - which is to say we cannot mix an mp_number<B1> with an mp_number<B2> where B1 and B2 are different types. + 

    operator convertible-to-bool-type()const;

    @@ -383,6 +396,8 @@ operators 

    // Non member operators:
+unmentionable-expression-template-type operator+(const see-below&);
+unmentionable-expression-template-type operator-(const see-below&);
 unmentionable-expression-template-type operator+(const see-below&, const see-below&);
 unmentionable-expression-template-type operator-(const see-below&, const see-below&);
 unmentionable-expression-template-type operator*(const see-below&, const see-below&);
@@ -439,6 +454,10 @@
             is a comparison operator.
           
 
+
    
+        Note that all the types involved in the expression must evaluate to the same
+        type - which is to say we cannot mix an mp_number<B1> with an mp_number<B2> where B1 and B2 are different types.
+      
    
 
    
         Finally note that the second argument to the left and right shift operations
         must be a builtin integer type, and that the argument must be positive (negative
@@ -530,7 +549,10 @@
       
    
 
    
         Also note that with the exception of abs
-        that these functions can only be used with floating-point Backend types.
+        that these functions can only be used with floating-point Backend types (if
+        any other types such as fixed precision or complex types are added to the
+        library later, then these functions may be extended to support those number
+        types).
       
    
 
    
 
diff --git a/doc/html/boost_multiprecision/ref/mpf_ref.html b/doc/html/boost_multiprecision/ref/mpf_ref.html
index fd2d8f50..9481059c 100644
--- a/doc/html/boost_multiprecision/ref/mpf_ref.html
+++ b/doc/html/boost_multiprecision/ref/mpf_ref.html
@@ -47,6 +47,9 @@
         and also mix gmp_floats of
         differing precision.
       
    
+
    
+        The type of number_category<cpp_int<Args...> >::type is mpl::int_<number_kind_floating_point>.
+      
    
 
    
         More information on this type can be found in the tutorial.
       
    
diff --git a/doc/html/boost_multiprecision/ref/mpfr_ref.html b/doc/html/boost_multiprecision/ref/mpfr_ref.html
index 7588f301..eb96296a 100644
--- a/doc/html/boost_multiprecision/ref/mpfr_ref.html
+++ b/doc/html/boost_multiprecision/ref/mpfr_ref.html
@@ -47,6 +47,9 @@
         that uses GMP or MPFR, and also mix mpfr_float_backends
         of differing precision.
       
    
+
    
+        The type of number_category<cpp_int<Args...> >::type is mpl::int_<number_kind_floating_point>.
+      
    
 
    
         More information on this type can be found in the tutorial.
       
    
diff --git a/doc/html/boost_multiprecision/ref/tom_int_ref.html b/doc/html/boost_multiprecision/ref/tom_int_ref.html
index 95abdcbe..9855b80a 100644
--- a/doc/html/boost_multiprecision/ref/tom_int_ref.html
+++ b/doc/html/boost_multiprecision/ref/tom_int_ref.html
@@ -31,6 +31,9 @@
         type. It's members and non-member functions are deliberately not documented:
         these are considered implementation details that are subject to change.
       
    
+
    
+        The type of number_category<cpp_int<Args...> >::type is mpl::int_<number_kind_integer>.
+      
    
 
    
         More information on this type can be found in the tutorial.
       
    
diff --git a/doc/html/boost_multiprecision/tut/conversions.html b/doc/html/boost_multiprecision/tut/conversions.html
index b34da26c..dd36b344 100644
--- a/doc/html/boost_multiprecision/tut/conversions.html
+++ b/doc/html/boost_multiprecision/tut/conversions.html
@@ -89,6 +89,21 @@
 mpf_init_set_ui(m, 0); // set to a value;
 mpf_float i(m);        // copies the value of the native type.
    +

    + More information on what additional types a backend supports conversions + from are given in the tutorial for each backend. +

    +
    +
    mpz_int z(2);
+int i = z.template convert_to<int>(); // sets i to 2
+
    +

    + Additional conversions may be supported by particular backends. +

    diff --git a/doc/html/boost_multiprecision/tut/floats/cpp_dec_float.html b/doc/html/boost_multiprecision/tut/floats/cpp_dec_float.html index aea653f8..a109f6fc 100644 --- a/doc/html/boost_multiprecision/tut/floats/cpp_dec_float.html +++ b/doc/html/boost_multiprecision/tut/floats/cpp_dec_float.html @@ -70,6 +70,21 @@ specified in the template argument. Normally these should not be visible to the user. +
  • + The type supports both infinities and NaN's. An infinity is generated + whenever the result would overflow, and a NaN is generated for any + mathematically undefined operation. +
    • +
  • + There is a std::numeric_limits specialisation for + this type. +
    • +
  • + Any mp_number instantiated + on this type, is convertible to any other mp_number + instantiated on this type - for example you can convert from mp_number<cpp_dec_float<50> > to mp_number<cpp_dec_float<SomeOtherValue> >. + Narrowing conversions are truncating. +
    • diff --git a/doc/html/boost_multiprecision/tut/floats/mpfr_float.html b/doc/html/boost_multiprecision/tut/floats/mpfr_float.html index 595e9d2c..8d42e7ac 100644 --- a/doc/html/boost_multiprecision/tut/floats/mpfr_float.html +++ b/doc/html/boost_multiprecision/tut/floats/mpfr_float.html @@ -107,6 +107,11 @@ in place of GMP - indeed that is the preferred option on Win32. +
  • + This backend supports rvalue-references and is move-aware, making instantiations + of mp_number on this + backend move aware. +
    • diff --git a/doc/html/boost_multiprecision/tut/ints/cpp_int.html b/doc/html/boost_multiprecision/tut/ints/cpp_int.html index 98340475..021c5d0c 100644 --- a/doc/html/boost_multiprecision/tut/ints/cpp_int.html +++ b/doc/html/boost_multiprecision/tut/ints/cpp_int.html @@ -134,6 +134,20 @@ difference to the performance of these types either way - so we may as well have the faster compile times by turning the feature off. +
  • + Unsigned types support subtraction, and unary negation - the result + is "as if" a 2's complement operation had been performed + - in other words they behave pretty much as a built in integer type + would in this situation. So for example if we were using mp_uint128_t then both mp_uint128_t(1)-4 + and -mp_uint128(3) + would result in the value 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD + of type mp_uint128_t. +
    • +
  • + This backend supports rvalue-references and is move-aware, making instantiations + of mp_number on this + backend move aware. +
    • diff --git a/doc/html/boost_multiprecision/tut/ints/gmp_int.html b/doc/html/boost_multiprecision/tut/ints/gmp_int.html index 1bf12605..1b7c9282 100644 --- a/doc/html/boost_multiprecision/tut/ints/gmp_int.html +++ b/doc/html/boost_multiprecision/tut/ints/gmp_int.html @@ -85,6 +85,11 @@ Indeed use of MPIR is recommended on Win32. +
  • + This backend supports rvalue-references and is move-aware, making instantiations + of mp_number on this + backend move aware. +
    • diff --git a/doc/html/index.html b/doc/html/index.html index 3984146c..284440fb 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -86,6 +86,7 @@
    mpfr_float_backend
    cpp_dec_float
    Backend Requirements
    +
    Header File Structure
    Performance Comparison
    @@ -117,7 +118,7 @@
    - +

    Last revised: June 04, 2012 at 15:17:54 GMT

    Last revised: June 04, 2012 at 17:33:32 GMT
    diff --git a/doc/multiprecision.qbk b/doc/multiprecision.qbk index 4299d633..144abd36 100644 --- a/doc/multiprecision.qbk +++ b/doc/multiprecision.qbk @@ -100,6 +100,23 @@ by passing a second template argument to `mp_number`: my_float a, b, c; // These variables have 300 decimal digits precision +Note that mixing arithmetic operations using types of different precision is strictly forbidden: + + #include + + namespace mp = boost::multiprecision; // Reduce the typing a bit later... + + mp::mp_int128_t a(3), b(2); + mp::mp_int512_t c(50), d; + + d = c * a; // Compiler error + +However, conversions are allowed: + + d = a; // OK, widening conversion. + d = a * b; // OK, can convert from an expression template too. + d = mp::mp_int512_t(a) * c; // OK, all the types in the expression are the same now. + [h4 Expression Templates] Class `mp_number` is expression-template-enabled: that means that rather than having a multiplication @@ -333,6 +350,12 @@ this is a direct consequence of the sign-magnitude representation. * The fixed precision types `mp_[u]intXXX_t` have expression template support turned off - it seems to make little difference to the performance of these types either way - so we may as well have the faster compile times by turning the feature off. +* Unsigned types support subtraction, and unary negation - the result is "as if" a 2's complement operation had been performed + - in other words they behave pretty much as a built in integer type would in this situation. So for example if we were using + `mp_uint128_t` then both `mp_uint128_t(1)-4` and `-mp_uint128(3)` would result in the value `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD` + of type `mp_uint128_t`. +* This backend supports rvalue-references and is move-aware, making instantiations of `mp_number` on this backend move aware. + [h5 Example:] @@ -373,6 +396,7 @@ as a result performing formatted output on this type when the argument is negati * Division by zero is handled by the [gmp] library - it will trigger a division by zero signal. * Although this type is a wrapper around [gmp] it will work equally well with [mpir]. Indeed use of [mpir] is recommended on Win32. +* This backend supports rvalue-references and is move-aware, making instantiations of `mp_number` on this backend move aware. [h5 Example:] @@ -543,6 +567,7 @@ Things you should know when using this type: * No changes are made to [gmp] or [mpfr] global settings, so this type can coexist with existing [mpfr] or [gmp] code. * The code can equally use [mpir] in place of [gmp] - indeed that is the preferred option on Win32. +* This backend supports rvalue-references and is move-aware, making instantiations of `mp_number` on this backend move aware. [h5 [mpfr] example:] @@ -582,6 +607,12 @@ Things you should know when using this type: (this is a result of the type having some hidden internal guard digits). * The type has a number of internal guard digits over and above those specified in the template argument. Normally these should not be visible to the user. +* The type supports both infinities and NaN's. An infinity is generated whenever the result would overflow, +and a NaN is generated for any mathematically undefined operation. +* There is a `std::numeric_limits` specialisation for this type. +* Any `mp_number` instantiated on this type, is convertible to any other `mp_number` instantiated on this type - +for example you can convert from `mp_number >` to `mp_number >`. +Narrowing conversions are truncating. [h5 cpp_dec_float example:] @@ -865,6 +896,15 @@ In particular: mpf_init_set_ui(m, 0); // set to a value; mpf_float i(m); // copies the value of the native type. +More information on what additional types a backend supports conversions from are given in the tutorial for each backend. + +* An `mp_number` can be converted to any built in type, via the `convert_to` member function: + + mpz_int z(2); + int i = z.template convert_to(); // sets i to 2 + +Additional conversions may be supported by particular backends. + [endsect] [section:random Generating Random Numbers] @@ -1131,6 +1171,9 @@ Type `mp_number` is default constructible, and both copy constructible and assig * Any builtin arithmetic type. * A `std::string` or any type which is convertible to `const char*`. * Any type that the Backend is constructible or assignable from. +* An rvalue reference to another `mp_number`. Move-semantics are used for construction if the backend also +supports rvalue reference construction. In the case of assignment, move semantics are always supported +when the argument is an rvalue reference irrespective of the backend. In addition, if the type has multiple components (for example rational or complex number types), then there is a two argument constructor: @@ -1166,6 +1209,9 @@ The arguments to these operators is either: For the left and right shift operations, the argument must be a builtin integer type with a positive value (negative values result in a `std::runtime_error` being thrown). +Note that all the types involved in the expression must evaluate to the same type - which is to say +we cannot mix an `mp_number` with an `mp_number` where B1 and B2 are different types. + operator ``['convertible-to-bool-type]``()const; Returns an ['unmentionable-type] that is usable in Boolean contexts (this allows `mp_number` to be used in any @@ -1262,6 +1308,9 @@ The return type of these operators is either: * Type `mp_number` when `ExpressionTemplates` is `false`. * Type `bool` if the operator is a comparison operator. +Note that all the types involved in the expression must evaluate to the same type - which is to say +we cannot mix an `mp_number` with an `mp_number` where B1 and B2 are different types. + Finally note that the second argument to the left and right shift operations must be a builtin integer type, and that the argument must be positive (negative arguments result in a `std::runtime_error` being thrown). @@ -1329,7 +1378,8 @@ don't have native support for these functions. Please note however, that this d to be a compile time constant - this means for example that the [gmp] MPF Backend will not work with these functions when that type is used at variable precision. -Also note that with the exception of `abs` that these functions can only be used with floating-point Backend types. +Also note that with the exception of `abs` that these functions can only be used with floating-point Backend types (if any other types +such as fixed precision or complex types are added to the library later, then these functions may be extended to support those number types). [h4 Traits Class Support] @@ -1487,6 +1537,8 @@ The template arguments are: no dymanic memory will ever be allocated.]] ] +The type of `number_category >::type` is `mpl::int_`. + More information on this type can be found in the [link boost_multiprecision.tut.ints.cpp_int tutorial]. [endsect] @@ -1505,6 +1557,8 @@ Class template `gmp_int` fulfills all of the requirements for a [link boost_mult It's members and non-member functions are deliberately not documented: these are considered implementation details that are subject to change. +The type of `number_category >::type` is `mpl::int_`. + More information on this type can be found in the [link boost_multiprecision.tut.ints.gmp_int tutorial]. [endsect] @@ -1523,6 +1577,8 @@ Class template `tommath_int` fulfills all of the requirements for a [link boost_ It's members and non-member functions are deliberately not documented: these are considered implementation details that are subject to change. +The type of `number_category >::type` is `mpl::int_`. + More information on this type can be found in the [link boost_multiprecision.tut.ints.tom_int tutorial]. [endsect] @@ -1552,6 +1608,8 @@ and `mp_number::precision`. Note that this type does not in any way change the it does not change the default precision of the mpf_t data type), therefore you can safely mix this type with existing code that uses GMP, and also mix `gmp_float`s of differing precision. +The type of `number_category >::type` is `mpl::int_`. + More information on this type can be found in the [link boost_multiprecision.tut.floats.gmp_float tutorial]. [endsect] @@ -1581,6 +1639,8 @@ and `mp_number::precision`. Note that this type does not in any way change the it does not change the default precision of the mpfr_t data type), therefore you can safely mix this type with existing code that uses GMP or MPFR, and also mix `mpfr_float_backend`s of differing precision. +The type of `number_category >::type` is `mpl::int_`. + More information on this type can be found in the [link boost_multiprecision.tut.floats.mpfr_float tutorial]. [endsect] @@ -1605,6 +1665,8 @@ The class takes a single template parameter - `Digits10` - which is the number o should support. Note that this type does not ever perform any dynamic memory allocation, as a result the `Digits10` template argument should not be set too high or the classes size will grow unreasonably large. +The type of `number_category >::type` is `mpl::int_`. + More information on this type can be found in the [link boost_multiprecision.tut.floats.cpp_dec_float tutorial]. [endsect] @@ -1771,12 +1833,49 @@ of type B2. [[`eval_lcm(b, cb, cb2)`][`void`][Sets `b` to the least common multiple of `cb` and `cb2`. Only required when `B` is an integer type.]] ] +The tables above place no ['throws] requirements on any of the operations. It is up to each type modelling this concept to +decide when or whether throwing an exception is desirable. However, thrown exceptions should always either be the type, or +inherit from the type `std::runtime_error`. For example, a floating point type might choose to throw `std::overflow_error` +whenever the result of an operation would be infinite, and `std::underflow_error` whenever it would round to zero. + [note The non-member functions are all named with an "eval_" prefix to avoid conflicts with template classes of the same name - in point of fact this naming convention shouldn't be necessary, but rather works around some compiler bugs.] [endsect] +[section:headers Header File Structure] + +[table Top level headers +[[Header][Contains]] +[[cpp_int.hpp][The `cpp_int` backend type.]] +[[gmp.hpp][Defines all [gmp] related backends.]] +[[integer_ops.hpp][Integer specific non-member functions.]] +[[miller_rabin.hpp][Miller Rabin primality testing code.]] +[[mp_number.hpp][Defines the `mp_number` backend, is included by all the backend headers.]] +[[mpfr.hpp][Defines the mpfr_float_backend backend.]] +[[random.hpp][Defines code to interoperate with Boost.Random.]] +[[rational_adapter.hpp][Defines the `rational_adapter` backend.]] +[[cpp_dec_float.hpp][Defines the `cpp_dec_float` backend.]] +[[tommath.hpp][Defines the `tommath_int` backend.]] +[[concepts/mp_number_architypes.hpp][Defines a backend concept architypes for testing use.]] +] + +[table Implementation Headers] +[[Header][Contains]] +[[detail/big_lanczos.hpp][Lanczos support for Boost.Math integration.]] +[[detail/cpp_int_core.hpp][Platform and peformance tuning for the `cpp_int` backend.]] +[[detail/default_ops.hpp][Default versions of the optional backend non-member functions.]] +[[detail/generic_interconvert.hpp][Generic interconversion routines.]] +[[detail/mp_number_base.hpp][All the expression template code, metaprogramming, and operator overloads for `mp_number`.]] +[[detail/no_et_ops.hpp][The non-expression template operators.]] +[[defail/functions/constants.hpp][Defines constants used by the floating point functions.]] +[[detail/functions/pow.hpp][Defines default versions of the power and exponential related floating point functions.]] +[[detail/functions/trig.hpp][Defines default versions of the trigonometric related floating point functions.]] +] + +[endsect] + [endsect] [section:perf Performance Comparison] diff --git a/include/boost/multiprecision/detail/mp_number_base.hpp b/include/boost/multiprecision/detail/mp_number_base.hpp index d57d30dd..cc24dfbd 100644 --- a/include/boost/multiprecision/detail/mp_number_base.hpp +++ b/include/boost/multiprecision/detail/mp_number_base.hpp @@ -1234,6 +1234,20 @@ struct promote_arg > typedef typename boost::multiprecision::detail::mp_exp::result_type type; }; +template +inline R real_cast(const boost::multiprecision::mp_number& val) +{ + return val.template convert_to(); +} + +template +inline R real_cast(const boost::multiprecision::detail::mp_exp& val) +{ + typedef typename boost::multiprecision::detail::mp_exp::result_type val_type; + return val_type(val).template convert_to(); +} + + }}} #endif // BOOST_MATH_BIG_NUM_BASE_HPP diff --git a/include/boost/multiprecision/mpfr.hpp b/include/boost/multiprecision/mpfr.hpp index e72d320a..58039d23 100644 --- a/include/boost/multiprecision/mpfr.hpp +++ b/include/boost/multiprecision/mpfr.hpp @@ -25,7 +25,7 @@ struct mpfr_float_backend; namespace detail{ -long get_default_precision() { return 50; } +inline long get_default_precision() { return 50; } template struct mpfr_float_imp