Subject: [Boost-commit] svn:boost r81133 - in sandbox/big_number/libs/multiprecision/doc: . html html/boost_multiprecision html/boost_multiprecision/indexes html/boost_multiprecision/map html/boost_multiprecision/tut
From: john_at_[hidden]
Date: 2012-11-01 07:20:01
Author: johnmaddock
Date: 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
New Revision: 81133
URL: http://svn.boost.org/trac/boost/changeset/81133
Log:
More doc updates.
Regenerate docs.
Added:
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map/faq.html (contents, props changed)
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut/lits.html (contents, props changed)
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut/rounding.html (contents, props changed)
Text files modified:
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s01.html | 5 +
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s02.html | 4
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s03.html | 4
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s04.html | 15 ++++-
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map.html | 1
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map/ack.html | 6 +-
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map/todo.html | 26 ++++++----
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/ref.html | 6 +-
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut.html | 3 +
sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut/primetest.html | 6 +-
sandbox/big_number/libs/multiprecision/doc/html/index.html | 6 ++
sandbox/big_number/libs/multiprecision/doc/multiprecision.qbk | 100 ++++++++++++++++++++++++++++++++++++++-
12 files changed, 148 insertions(+), 34 deletions(-)
Modified: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s01.html
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s01.html (original)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s01.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -13,9 +13,9 @@
<div class="spirit-nav">
<a accesskey="p" href="../indexes.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../indexes.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="s02.html"><img src="../../images/next.png" alt="Next"></a>
</div>
-<div class="section id992651">
+<div class="section id971892">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id992651"></a>Function Index</h3></div></div></div>
+<a name="id971892"></a>Function Index</h3></div></div></div>
<p><a class="link" href="s01.html#idx_id_0">A</a> <a class="link" href="s01.html#idx_id_1">B</a> <a class="link" href="s01.html#idx_id_2">C</a> <a class="link" href="s01.html#idx_id_3">D</a> <a class="link" href="s01.html#idx_id_4">E</a> <a class="link" href="s01.html#idx_id_5">F</a> <a class="link" href="s01.html#idx_id_7">I</a> <a class="link" href="s01.html#idx_id_8">L</a> <a class="link" href="s01.html#idx_id_9">M</a> <a class="link" href="s01.html#idx_id_12">P</a> <a class="link" href="s01.html#idx_id_13">R</a> <a class="link" href="s01.html#idx_id_14">S</a> <a class="link" href="s01.html#idx_id_15">T</a> <a class="link" href="s01.html#idx_id_17">Z</a></p>
<div class="variablelist"><dl class="variablelist">
<dt>
@@ -421,6 +421,7 @@
<li class="listitem" style="list-style-type: none">
<p><span class="index-entry-level-0">precision</span></p>
<div class="index"><ul class="index" style="list-style-type: none; ">
+<li class="listitem" style="list-style-type: none"><p><a class="link" href="../map/faq.html" title="FAQ"><span class="index-entry-level-1">FAQ</span></a></p></li>
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../intro.html" title="Introduction"><span class="index-entry-level-1">Introduction</span></a></p></li>
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../ref/number.html" title="number"><span class="index-entry-level-1">number</span></a></p></li>
</ul></div>
Modified: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s02.html
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s02.html (original)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s02.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -13,9 +13,9 @@
<div class="spirit-nav">
<a accesskey="p" href="s01.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../indexes.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="s03.html"><img src="../../images/next.png" alt="Next"></a>
</div>
-<div class="section id996678">
+<div class="section id975922">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id996678"></a>Class Index</h3></div></div></div>
+<a name="id975922"></a>Class Index</h3></div></div></div>
<p><a class="link" href="s02.html#idx_id_20">C</a> <a class="link" href="s02.html#idx_id_22">E</a> <a class="link" href="s02.html#idx_id_24">G</a> <a class="link" href="s02.html#idx_id_25">I</a> <a class="link" href="s02.html#idx_id_27">M</a> <a class="link" href="s02.html#idx_id_28">N</a> <a class="link" href="s02.html#idx_id_33">T</a></p>
<div class="variablelist"><dl class="variablelist">
<dt>
Modified: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s03.html
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s03.html (original)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s03.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -13,9 +13,9 @@
<div class="spirit-nav">
<a accesskey="p" href="s02.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../indexes.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="s04.html"><img src="../../images/next.png" alt="Next"></a>
</div>
-<div class="section id997095">
+<div class="section id978047">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id997095"></a>Typedef Index</h3></div></div></div>
+<a name="id978047"></a>Typedef Index</h3></div></div></div>
<p><a class="link" href="s03.html#idx_id_38">C</a> <a class="link" href="s03.html#idx_id_43">I</a> <a class="link" href="s03.html#idx_id_44">L</a> <a class="link" href="s03.html#idx_id_45">M</a> <a class="link" href="s03.html#idx_id_51">T</a> <a class="link" href="s03.html#idx_id_52">U</a></p>
<div class="variablelist"><dl class="variablelist">
<dt>
Modified: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s04.html
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s04.html (original)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/indexes/s04.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -12,9 +12,9 @@
<div class="spirit-nav">
<a accesskey="p" href="s03.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../indexes.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a>
</div>
-<div class="section id999680">
+<div class="section id978993">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id999680"></a>Index</h3></div></div></div>
+<a name="id978993"></a>Index</h3></div></div></div>
<p><a class="link" href="s04.html#idx_id_54">A</a> <a class="link" href="s04.html#idx_id_55">B</a> <a class="link" href="s04.html#idx_id_56">C</a> <a class="link" href="s04.html#idx_id_57">D</a> <a class="link" href="s04.html#idx_id_58">E</a> <a class="link" href="s04.html#idx_id_59">F</a> <a class="link" href="s04.html#idx_id_60">G</a> <a class="link" href="s04.html#idx_id_61">I</a> <a class="link" href="s04.html#idx_id_62">L</a> <a class="link" href="s04.html#idx_id_63">M</a> <a class="link" href="s04.html#idx_id_64">N</a> <a class="link" href="s04.html#idx_id_65">O</a> <a class="link" href="s04.html#idx_id_66">P</a> <a class="link" href="s04.html#idx_id_67">R</a> <a class="link" href="s04.html#idx_id_68">S</a> <a class="link" href="s04.html#idx_id_69">T</a> <a class="link" href="s04.html#idx_id_70">U</a> <a class="link" href="s04.html#idx_id_71">Z</a></p>
<div class="variablelist"><dl class="variablelist">
<dt>
@@ -475,10 +475,16 @@
<dt>
<a name="idx_id_59"></a><span class="term">F</span>
</dt>
-<dd><div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none">
+<dd><div class="index"><ul class="index" style="list-style-type: none; ">
+<li class="listitem" style="list-style-type: none">
+<p><span class="index-entry-level-0">FAQ</span></p>
+<div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><p><a class="link" href="../map/faq.html" title="FAQ"><span class="index-entry-level-1">precision</span></a></p></li></ul></div>
+</li>
+<li class="listitem" style="list-style-type: none">
<p><span class="index-entry-level-0">fpclassify</span></p>
<div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><p><a class="link" href="../ref/number.html" title="number"><span class="index-entry-level-1">number</span></a></p></li></ul></div>
-</li></ul></div></dd>
+</li>
+</ul></div></dd>
<dt>
<a name="idx_id_60"></a><span class="term">G</span>
</dt>
@@ -859,6 +865,7 @@
<li class="listitem" style="list-style-type: none">
<p><span class="index-entry-level-0">precision</span></p>
<div class="index"><ul class="index" style="list-style-type: none; ">
+<li class="listitem" style="list-style-type: none"><p><a class="link" href="../map/faq.html" title="FAQ"><span class="index-entry-level-1">FAQ</span></a></p></li>
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../intro.html" title="Introduction"><span class="index-entry-level-1">Introduction</span></a></p></li>
<li class="listitem" style="list-style-type: none"><p><a class="link" href="../ref/number.html" title="number"><span class="index-entry-level-1">number</span></a></p></li>
</ul></div>
Modified: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map.html
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map.html (original)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -20,6 +20,7 @@
<div class="toc"><dl>
<dt><span class="section">History</span></dt>
<dt><span class="section">TODO</span></dt>
+<dt><span class="section">FAQ</span></dt>
<dt><span class="section">Acknowledgements</span></dt>
</dl></div>
</div>
Modified: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map/ack.html
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map/ack.html (original)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map/ack.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -6,12 +6,12 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Multiprecision">
<link rel="up" href="../map.html" title="Roadmap">
-<link rel="prev" href="todo.html" title="TODO">
+<link rel="prev" href="faq.html" title="FAQ">
<link rel="next" href="../indexes.html" title="Indexes">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="spirit-nav">
-<a accesskey="p" href="todo.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../map.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../indexes.html"><img src="../../images/next.png" alt="Next"></a>
+<a accesskey="p" href="faq.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../map.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../indexes.html"><img src="../../images/next.png" alt="Next"></a>
</div>
<div class="section boost_multiprecision_map_ack">
<div class="titlepage"><div><div><h3 class="title">
@@ -49,7 +49,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="todo.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../map.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../indexes.html"><img src="../../images/next.png" alt="Next"></a>
+<a accesskey="p" href="faq.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../map.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../indexes.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>
Added: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map/faq.html
==============================================================================
--- (empty file)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map/faq.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -0,0 +1,111 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>FAQ</title>
+<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
+<link rel="home" href="../../index.html" title="Chapter 1. Boost.Multiprecision">
+<link rel="up" href="../map.html" title="Roadmap">
+<link rel="prev" href="todo.html" title="TODO">
+<link rel="next" href="ack.html" title="Acknowledgements">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="spirit-nav">
+<a accesskey="p" href="todo.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../map.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="ack.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+<div class="section boost_multiprecision_map_faq">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_multiprecision.map.faq"></a><a class="link" href="faq.html" title="FAQ">FAQ</a>
+</h3></div></div></div>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl class="variablelist">
+<dt><span class="term">Why do I get compiler errors when passing a <code class="computeroutput"><span class="identifier">number</span></code>
+ to a template function?</span></dt>
+<dd><p>
+ Most likely you are actually passing an expression template type to
+ the function and template-argument-deduction deduces the "wrong"
+ type. Try casting the arguments involving expressions to the actual
+ number type, or as a last resort turning off expression template support
+ in the number type you are using.
+ </p></dd>
+<dt><span class="term">When is expression template support a performance gain?</span></dt>
+<dd><p>
+ As a general rule, expression template support adds a small runtime
+ overhead creating and unpacking the expression templates, but greatly
+ reduces the number of temporaries created. So it's most effective in
+ improving performance when the cost of creating a temporary is high:
+ for example when creating a temporary involves a memory allocation.
+ It is least effective (and may even be a dis-optimisation) when temporaries
+ are cheap: for example if the number type is basically a thin wrapper
+ around a native arithmetic type. In addition, since the library makes
+ extensive use of thin inline wrapper functions, turning on compiler
+ optimization is essential to achieving high performance.
+ </p></dd>
+<dt><span class="term">Do expression templates reorder operations?</span></dt>
+<dd><p>
+ Yes they do, sometimes quite radically so, if this is a concern then
+ they should be turned off for the number type you are using.
+ </p></dd>
+<dt><span class="term">I can't construct my number type from <span class="emphasis"><em>some other type</em></span>,
+ but the docs indicate that the conversion should be allowed, what's up?</span></dt>
+<dd><p>
+ Some conversions are <span class="emphasis"><em>explicit</em></span>, that includes construction
+ from a string, or constructing from any type that may result in loss
+ of precision (for example constructing an integer type from a float).
+ </p></dd>
+<dt><span class="term">Why do I get an exception thrown (or the program crash due to an
+ uncaught exception) when using the bitwise operators on a checked <code class="computeroutput"><span class="identifier">cpp_int</span></code>?</span></dt>
+<dd><p>
+ Bitwise operations on negative values (or indeed any signed integer
+ type) are unspecified by the standard. As a result any attempt to carry
+ out a bitwise operation on a negative checked-integer will result in
+ a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">range_error</span></code> being thrown.
+ </p></dd>
+<dt><span class="term">Why do I get compiler errors when trying to use the complement operator?</span></dt>
+<dd><p>
+ Use of the complement operator on signed types is problematic as the
+ result is unspecified by the standard, and is further complicated by
+ the fact that most extended precision integer types use a sign-magnitude
+ representation rather than the 2's complement one favored by most native
+ integer types. As a result the complement operator is deliberately
+ disabled for checked <code class="computeroutput"><span class="identifier">cpp_int</span></code>'s.
+ Unchecked <code class="computeroutput"><span class="identifier">cpp_int</span></code>'s
+ give the same valued result as a 2's complement type would, but not
+ the same bit-pattern.
+ </p></dd>
+<dt><span class="term">Why can't I negate an unsigned type?</span></dt>
+<dd><p>
+ The unary negation operator is deliberately disabled for unsigned integer
+ types as it's use would almost always be a programming error.
+ </p></dd>
+<dt><span class="term">Why doesn't the library use proto?</span></dt>
+<dd><p>
+ A very early version of the library did use proto, but compile times
+ became too slow for the library to be usable. Since the library only
+ required a tiny fraction of what proto has to offer anyway, a lightweight
+ expression template mechanism was used instead. Compile times are still
+ too slow...
+ </p></dd>
+<dt><span class="term">Why not abstract out addition/multiplication algorithms?</span></dt>
+<dd><p>
+ This was deamed not to be practical: these algorithms are intimately
+ tied to the actual data representation used.
+ </p></dd>
+</dl>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2002-2012 John Maddock and Christopher Kormanyos<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="todo.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../map.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="ack.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Modified: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map/todo.html
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map/todo.html (original)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/map/todo.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -7,11 +7,11 @@
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Multiprecision">
<link rel="up" href="../map.html" title="Roadmap">
<link rel="prev" href="hist.html" title="History">
-<link rel="next" href="ack.html" title="Acknowledgements">
+<link rel="next" href="faq.html" title="FAQ">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="spirit-nav">
-<a accesskey="p" href="hist.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../map.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="ack.html"><img src="../../images/next.png" alt="Next"></a>
+<a accesskey="p" href="hist.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../map.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="../../images/next.png" alt="Next"></a>
</div>
<div class="section boost_multiprecision_map_todo">
<div class="titlepage"><div><div><h3 class="title">
@@ -48,6 +48,9 @@
<li class="listitem">
Should there be a choice of rounding mode (probably MPFR specific)?
</li>
+<li class="listitem">
+ We can reuse temporaries in multiple subtrees (temporary caching).
+ </li>
</ul></div>
<p>
Things requested in review:
@@ -64,26 +67,27 @@
done, just need to update docs to the latest results).
</li>
<li class="listitem">
- The rounding applied when converting must be documented.
+ cpp_dec_float should round to nearest.
</li>
<li class="listitem">
- cpp_dec_float should round to nearest.
+ Should we provide min/max overloads for expression templates?
</li>
<li class="listitem">
- We can reuse temporaries in multiple subtrees (temporary caching).
+ The rounding applied when converting must be documented (Done).
</li>
<li class="listitem">
- Emphasise in the docs that ET's may reorder operations.
+ Document why we don't abstract out addition/multiplication algorithms
+ etc. (done - FAQ)
</li>
<li class="listitem">
- Document why we don't use proto (compile times).
+ Document why we don't use proto (compile times) (Done).
</li>
<li class="listitem">
- Should we provide min/max overloads for expression templates?
+ We can reuse temporaries in multiple subtrees (temporary caching) Moved
+ to TODO list.
</li>
<li class="listitem">
- Document why we don't abstract out addition/multiplication algorithms
- etc.
+ Emphasise in the docs that ET's may reorder operations (done 2012/10/31).
</li>
<li class="listitem">
Document what happens to small fixed precision cpp_int's (done 2012/10/31).
@@ -215,7 +219,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="hist.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../map.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="ack.html"><img src="../../images/next.png" alt="Next"></a>
+<a accesskey="p" href="hist.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../map.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>
Modified: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/ref.html
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/ref.html (original)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/ref.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -6,12 +6,12 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../index.html" title="Chapter 1. Boost.Multiprecision">
<link rel="up" href="../index.html" title="Chapter 1. Boost.Multiprecision">
-<link rel="prev" href="tut/primetest.html" title="Primality Testing">
+<link rel="prev" href="tut/rounding.html" title="Rounding Rules for Conversions">
<link rel="next" href="ref/number.html" title="number">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="spirit-nav">
-<a accesskey="p" href="tut/primetest.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="ref/number.html"><img src="../images/next.png" alt="Next"></a>
+<a accesskey="p" href="tut/rounding.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="ref/number.html"><img src="../images/next.png" alt="Next"></a>
</div>
<div class="section boost_multiprecision_ref">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -41,7 +41,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="tut/primetest.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="ref/number.html"><img src="../images/next.png" alt="Next"></a>
+<a accesskey="p" href="tut/rounding.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="ref/number.html"><img src="../images/next.png" alt="Next"></a>
</div>
</body>
</html>
Modified: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut.html
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut.html (original)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -60,6 +60,9 @@
Interconverting Between Number Types</a></span></dt>
<dt><span class="section">Generating Random Numbers</span></dt>
<dt><span class="section">Primality Testing</span></dt>
+<dt><span class="section">Literal Types and constexpr Support</span></dt>
+<dt><span class="section"><a href="tut/rounding.html">Rounding Rules for
+ Conversions</a></span></dt>
</dl></div>
<p>
In order to use this library you need to make two choices: what kind of number
Added: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut/lits.html
==============================================================================
--- (empty file)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut/lits.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -0,0 +1,63 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Literal Types and constexpr Support</title>
+<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
+<link rel="home" href="../../index.html" title="Chapter 1. Boost.Multiprecision">
+<link rel="up" href="../tut.html" title="Tutorial">
+<link rel="prev" href="primetest.html" title="Primality Testing">
+<link rel="next" href="rounding.html" title="Rounding Rules for Conversions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="spirit-nav">
+<a accesskey="p" href="primetest.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="rounding.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+<div class="section boost_multiprecision_tut_lits">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_multiprecision.tut.lits"></a><a class="link" href="lits.html" title="Literal Types and constexpr Support">Literal Types and <code class="computeroutput"><span class="identifier">constexpr</span></code> Support</a>
+</h3></div></div></div>
+<p>
+ There is limited support for <code class="computeroutput"><span class="identifier">constexpr</span></code>
+ in the library, currently the <code class="computeroutput"><span class="identifier">number</span></code>
+ front end supports <code class="computeroutput"><span class="identifier">constexpr</span></code>
+ on default construction and all forwarding constructors, but not on any of
+ the non-member operators. So if some type <code class="computeroutput"><span class="identifier">B</span></code>
+ is a literal type, then <code class="computeroutput"><span class="identifier">number</span><span class="special"><</span><span class="identifier">B</span><span class="special">></span></code>
+ is also a literal type, and you will be able to compile-time-construct such
+ a type from any literal that <code class="computeroutput"><span class="identifier">B</span></code>
+ is compile-time-constructible from. However, you will not be able to perform
+ compile-time arithmetic on such types.
+ </p>
+<p>
+ Currently the only backend type provided by the library that is also a literal
+ type are instantiations of <code class="computeroutput"><span class="identifier">cpp_int_backend</span></code>
+ where the Allocator parameter is type <code class="computeroutput"><span class="keyword">void</span></code>,
+ and the Checked parameter is <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">unchecked</span></code>.
+ </p>
+<p>
+ For example:
+ </p>
+<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">;</span>
+
+<span class="identifier">constexpr</span> <span class="identifier">int128_t</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="comment">// OK, fixed precision int128_t has no allocator.</span>
+<span class="identifier">constexpr</span> <span class="identifier">uint1024_t</span> <span class="identifier">j</span> <span class="special">=</span> <span class="number">0</span><span class="identifier">xFFFFFFFF00000000uLL</span><span class="special">;</span> <span class="comment">// OK, fixed precision uint1024_t has no allocator.</span>
+
+<span class="identifier">constexpr</span> <span class="identifier">checked_uint128_t</span> <span class="identifier">k</span> <span class="special">=</span> <span class="special">-</span><span class="number">1</span><span class="special">;</span> <span class="comment">// Error, checked type is not a literal type as we need runtime error checking.</span>
+<span class="identifier">constexpr</span> <span class="identifier">cpp_int</span> <span class="identifier">l</span> <span class="special">=</span> <span class="number">2</span><span class="special">;</span> <span class="comment">// Error, type is not a literal as it performs memory management.</span>
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2002-2012 John Maddock and Christopher Kormanyos<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="primetest.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="rounding.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Modified: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut/primetest.html
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut/primetest.html (original)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut/primetest.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -7,11 +7,11 @@
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Multiprecision">
<link rel="up" href="../tut.html" title="Tutorial">
<link rel="prev" href="random.html" title="Generating Random Numbers">
-<link rel="next" href="../ref.html" title="Reference">
+<link rel="next" href="lits.html" title="Literal Types and constexpr Support">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="spirit-nav">
-<a accesskey="p" href="random.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../ref.html"><img src="../../images/next.png" alt="Next"></a>
+<a accesskey="p" href="random.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="lits.html"><img src="../../images/next.png" alt="Next"></a>
</div>
<div class="section boost_multiprecision_tut_primetest">
<div class="titlepage"><div><div><h3 class="title">
@@ -103,7 +103,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="random.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../ref.html"><img src="../../images/next.png" alt="Next"></a>
+<a accesskey="p" href="random.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="lits.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>
Added: sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut/rounding.html
==============================================================================
--- (empty file)
+++ sandbox/big_number/libs/multiprecision/doc/html/boost_multiprecision/tut/rounding.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -0,0 +1,182 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Rounding Rules for Conversions</title>
+<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
+<link rel="home" href="../../index.html" title="Chapter 1. Boost.Multiprecision">
+<link rel="up" href="../tut.html" title="Tutorial">
+<link rel="prev" href="lits.html" title="Literal Types and constexpr Support">
+<link rel="next" href="../ref.html" title="Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="spirit-nav">
+<a accesskey="p" href="lits.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../ref.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+<div class="section boost_multiprecision_tut_rounding">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_multiprecision.tut.rounding"></a><a class="link" href="rounding.html" title="Rounding Rules for Conversions">Rounding Rules for
+ Conversions</a>
+</h3></div></div></div>
+<p>
+ As a general rule, all conversions between unrelated types are performed
+ using basic arithmetic operations, therefore conversions are either exact,
+ or follow the same rounding rules as arithmetic for the type in question.
+ </p>
+<p>
+ The following table summarises the situation for conversions from native
+ types:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Backend
+ </p>
+ </th>
+<th>
+ <p>
+ Rounding Rules
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ <a class="link" href="ints/cpp_int.html" title="cpp_int">cpp_int</a>
+ </p>
+ </td>
+<td>
+ <p>
+ Conversions from integer types are exact if the target has sufficient
+ precision, otherwise they truncate to the first 2^MaxBits bits
+ (modulo arithmetic). Conversions from floating point types are
+ truncating to the nearest integer.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a class="link" href="ints/gmp_int.html" title="gmp_int">gmp_int</a>
+ </p>
+ </td>
+<td>
+ <p>
+ Conversions are performed by the GMP library except for conversion
+ from <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>
+ which is truncating.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a class="link" href="ints/tom_int.html" title="tom_int">tom_int</a>
+ </p>
+ </td>
+<td>
+ <p>
+ Conversions from floating point types are truncating, all others
+ are performed by libtommath and are exact.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a class="link" href="floats/gmp_float.html" title="gmp_float">gmp_float</a>
+ </p>
+ </td>
+<td>
+ <p>
+ Conversions are performed by the GMP library except for conversion
+ from <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>
+ which should be exact provided the target type has as much precision
+ as a <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a class="link" href="floats/mpfr_float.html" title="mpfr_float">mpfr_float</a>
+ </p>
+ </td>
+<td>
+ <p>
+ All conversions are performed by the underlying MPFR library.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a class="link" href="floats/cpp_dec_float.html" title="cpp_dec_float">cpp_dec_float</a>
+ </p>
+ </td>
+<td>
+ <p>
+ All conversions are performed using basic arithmetic operations
+ and are truncating.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a class="link" href="rational/gmp_rational.html" title="gmp_rational">gmp_rational</a>
+ </p>
+ </td>
+<td>
+ <p>
+ See <a class="link" href="ints/gmp_int.html" title="gmp_int">gmp_int</a>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a class="link" href="rational/cpp_rational.html" title="cpp_rational">cpp_rational</a>
+ </p>
+ </td>
+<td>
+ <p>
+ See <a class="link" href="ints/cpp_int.html" title="cpp_int">cpp_int</a>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a class="link" href="rational/tommath_rational.html" title="tommath_rational">tommath_rational</a>
+ </p>
+ </td>
+<td>
+ <p>
+ See <a class="link" href="ints/tom_int.html" title="tom_int">tom_int</a>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2002-2012 John Maddock and Christopher Kormanyos<p>
+ 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)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lits.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../ref.html"><img src="../../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Modified: sandbox/big_number/libs/multiprecision/doc/html/index.html
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/html/index.html (original)
+++ sandbox/big_number/libs/multiprecision/doc/html/index.html 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -75,6 +75,9 @@
Interconverting Between Number Types</a></span></dt>
<dt><span class="section">Generating Random Numbers</span></dt>
<dt><span class="section">Primality Testing</span></dt>
+<dt><span class="section">Literal Types and constexpr Support</span></dt>
+<dt><span class="section"><a href="boost_multiprecision/tut/rounding.html">Rounding Rules for
+ Conversions</a></span></dt>
</dl></dd>
<dt><span class="section">Reference</span></dt>
<dd><dl>
@@ -107,6 +110,7 @@
<dd><dl>
<dt><span class="section">History</span></dt>
<dt><span class="section">TODO</span></dt>
+<dt><span class="section">FAQ</span></dt>
<dt><span class="section">Acknowledgements</span></dt>
</dl></dd>
<dt><span class="section">Indexes</span></dt>
@@ -120,7 +124,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: October 31, 2012 at 16:58:22 GMT</small></p></td>
+<td align="left"><p><small>Last revised: November 01, 2012 at 11:12:34 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>
Modified: sandbox/big_number/libs/multiprecision/doc/multiprecision.qbk
==============================================================================
--- sandbox/big_number/libs/multiprecision/doc/multiprecision.qbk (original)
+++ sandbox/big_number/libs/multiprecision/doc/multiprecision.qbk 2012-11-01 07:19:59 EDT (Thu, 01 Nov 2012)
@@ -1172,6 +1172,55 @@
[endsect]
+[section:lits Literal Types and `constexpr` Support]
+
+There is limited support for `constexpr` in the library, currently the `number` front end supports `constexpr`
+on default construction and all forwarding constructors, but not on any of the non-member operators. So if
+some type `B` is a literal type, then `number<B>` is also a literal type, and you will be able to
+compile-time-construct such a type from any literal that `B` is compile-time-constructible from.
+However, you will not be able to perform compile-time arithmetic on such types.
+
+Currently the only backend type provided by the library that is also a literal type are instantiations
+of `cpp_int_backend` where the Allocator parameter is type `void`, and the Checked parameter is
+`boost::multiprecision::unchecked`.
+
+For example:
+
+ using namespace boost::multiprecision;
+
+ constexpr int128_t i = 0; // OK, fixed precision int128_t has no allocator.
+ constexpr uint1024_t j = 0xFFFFFFFF00000000uLL; // OK, fixed precision uint1024_t has no allocator.
+
+ constexpr checked_uint128_t k = -1; // Error, checked type is not a literal type as we need runtime error checking.
+ constexpr cpp_int l = 2; // Error, type is not a literal as it performs memory management.
+
+[endsect]
+
+[section:rounding Rounding Rules for Conversions]
+
+As a general rule, all conversions between unrelated types are performed using basic arithmetic operations, therefore
+conversions are either exact, or follow the same rounding rules as arithmetic for the type in question.
+
+The following table summarises the situation for conversions from native types:
+
+[table
+[[Backend][Rounding Rules]]
+[[__cpp_int][Conversions from integer types are exact if the target has sufficient precision, otherwise they
+ truncate to the first 2^MaxBits bits (modulo arithmetic). Conversions from floating point types
+ are truncating to the nearest integer.]]
+[[__gmp_int][Conversions are performed by the GMP library except for conversion from `long double` which is truncating.]]
+[[__tom_int][Conversions from floating point types are truncating, all others are performed by libtommath and are exact.]]
+[[__gmp_float][Conversions are performed by the GMP library except for conversion from `long double` which should be exact
+ provided the target type has as much precision as a `long double`.]]
+[[__mpfr_float_backend][All conversions are performed by the underlying MPFR library.]]
+[[__cpp_dec_float][All conversions are performed using basic arithmetic operations and are truncating.]]
+[[__gmp_rational][See __gmp_int]]
+[[__cpp_rational][See __cpp_int]]
+[[__tommath_rational][See __tom_int]]
+]
+
+[endsect]
+
[endsect]
[section:ref Reference]
@@ -2886,11 +2935,11 @@
* The performances of mp_number<a_trivial_adaptor<float>, false>respect to
float and mp_number<a_trivial_adaptor<int>, false> and int should be
given to show the cost of using the generic interface (Mostly done, just need to update docs to the latest results).
-* The rounding applied when converting must be documented.
* cpp_dec_float should round to nearest.
-* Document why we don't use proto (compile times).
* Should we provide min/max overloads for expression templates?
-* Document why we don't abstract out addition/multiplication algorithms etc.
+* The rounding applied when converting must be documented (Done).
+* Document why we don't abstract out addition/multiplication algorithms etc. (done - FAQ)
+* Document why we don't use proto (compile times) (Done).
* We can reuse temporaries in multiple subtrees (temporary caching) Moved to TODO list.
* Emphasise in the docs that ET's may reorder operations (done 2012/10/31).
* Document what happens to small fixed precision cpp_int's (done 2012/10/31).
@@ -2944,6 +2993,51 @@
[endsect]
+[section:faq FAQ]
+
+[variablelist
+[[Why do I get compiler errors when passing a `number` to a template function?]
+ [Most likely you are actually passing an expression template type to the function and
+ template-argument-deduction deduces the "wrong" type. Try casting the arguments
+ involving expressions to the actual number type, or as a last resort turning off
+ expression template support in the number type you are using.]]
+[[When is expression template support a performance gain?]
+ [As a general rule, expression template support adds a small runtime overhead
+ creating and unpacking the expression templates, but greatly reduces the number of
+ temporaries created. So it's most effective in improving performance when the cost
+ of creating a temporary is high: for example when creating a temporary involves a memory
+ allocation. It is least effective (and may even be a dis-optimisation) when temporaries
+ are cheap: for example if the number type is basically a thin wrapper around a native
+ arithmetic type. In addition, since the library makes extensive use of thin inline wrapper
+ functions, turning on compiler optimization is essential to achieving high performance.]]
+[[Do expression templates reorder operations?]
+ [Yes they do, sometimes quite radically so, if this is a concern then they should be turned
+ off for the number type you are using.]]
+[[I can't construct my number type from ['some other type], but the docs indicate that the conversion should be allowed, what's up?]
+ [Some conversions are ['explicit], that includes construction from a string, or constructing from any type
+ that may result in loss of precision (for example constructing an integer type from a float).]]
+[[Why do I get an exception thrown (or the program crash due to an uncaught exception) when using the bitwise operators on a checked `cpp_int`?]
+ [Bitwise operations on negative values (or indeed any signed integer type) are unspecified by the standard. As a result
+ any attempt to carry out a bitwise operation on a negative checked-integer will result in a `std::range_error` being thrown.]]
+[[Why do I get compiler errors when trying to use the complement operator?]
+ [Use of the complement operator on signed types is problematic as the result is unspecified by the standard, and is further
+ complicated by the fact that most extended precision integer types use a sign-magnitude representation rather than the 2's
+ complement one favored by most native integer types. As a result the complement operator is deliberately disabled for
+ checked `cpp_int`'s. Unchecked `cpp_int`'s give the same valued result as a 2's complement type would, but not the same bit-pattern.]]
+[[Why can't I negate an unsigned type?]
+ [The unary negation operator is deliberately disabled for unsigned integer types as it's use would almost always be a programming error.]]
+[[Why doesn't the library use proto?]
+ [A very early version of the library did use proto, but compile times became too slow
+ for the library to be usable. Since the library only required a tiny fraction of what
+ proto has to offer anyway, a lightweight expression template mechanism was used instead.
+ Compile times are still too slow...]]
+[[Why not abstract out addition/multiplication algorithms?]
+ [This was deamed not to be practical: these algorithms are intimately
+ tied to the actual data representation used.]]
+]
+
+[endsect]
+
[section:ack Acknowledgements]
This library would not have happened without: