
Boost : 
Subject: [boost] [Numeric Conversion] Documentation Notes/Questions
From: Dave Abrahams (dave_at_[hidden])
Date: 20121027 09:55:08
* First thing to note: the documentation makes this library less
approachable than it could be. In order to even begin, one has to
bury onesself in terminology (the "Definitions" section). A
superquick "hello, world" example and a very short tutorial at the
beginning would help a *lot*. numeric_cast is arguably the most
generallyuseful interface of the whole library and yet it's not even
discussed until the end of the docs.
* It's not clear what the purpose of abt(x) is. In expressions, "x"
usually means its value. When you introduce a mechanism like this, it
would be a good idea to explain why it's needed. Most places, the use
of "abstract" just seems to complicate things:
"A ulp is a quantity whose abstract magnitude"
what's wrong with
"A ulp is a quantity whose magnitude"
??
The end of the section on "Range and Precision" begins to explain why
you want "abstract," but it takes the reader a long time to get to it.
* are next() and prev() always welldefined? Seems to me that an
unlimited precision rational number type might not have them. Is that
type not numeric?
* How do size, width, and density relate to unlimited precision
rationals? I imagine:
size = infinity
width = infinity
density = ?
* This is slightly ambiguous:
"This definition allows for a concise definition of subranged as
given in the last section."
"final section" would be clearer. A link would help too.
* This is unclear:
"Abstract intervals are easier to compare and overlap since
only boundary values need to be considered."
an example would help. How can one kind of thing be "easier to
overlap" than another?
* Precision has a very nongeneric description, being different for
types with density 1 and other types. It's hard to see what use such
a concept has, and as far as Google can tell it is not used anywhere
outside the Definitions section
* Description of unsigned types, I think, is wrong:
Notice that a numeric type, such as a C++ unsigned type, can define
that any V does not overflow by always representing not V itself
but the abstract value U = [ V % (abt(h)+1) ], which is always in
range.
Seems to me that the abstract values represented by an unsigned
integer type are not the set of whole numbers, but the set of whole
numbers modulo whateverthemax+1is. That's a welldefined
mathematical abstraction, isn't it? Is there a problem with that,
such as multiplication not working properly (I don't think so)?
* There seems to be a contradiction here:
If V >= abt(l) and V <= abt(h), V is representable (can be
represented) in the type T
...
Given an abstract value V represented in the type T as v, the
roundoff error of the representation is the abstract difference: (
abt(v)V).
If V is not representable in type T, can you write formulae using its
representation in type T? Given what I read later, maybe you should
have just said "exactly representable" in the first phrase.
* s/at most/less than/?:
Because a correctly rounded representation is always one of adjacents
of the abstract value being represented, the roundoff is guaranteed
to be at most 1ulp.
* s/cannot be represented/cannot be exactly represented/ ?:
The integer number 1 can be exactly represented in Int, Real
and Whole, but cannot be represented in Cardinal, yielding
negative overflow.
* Uhoh:
Floating to Floating conversions are defined only if N is
representable; if it is not, the conversion has undefined behavior.
in many places you've used "representable" to mean "exactly
representable," but I can't believe you mean that here; it would imply
most double=>float conversions have undefined behavior.
What does this mean, anyway? If an abstract value can be "inexactly
representable," aren't all abstract values representable if there's at
least one abstract value that's exactly representable? Just convert
to that and you're done. I think you need to give some serious
thought to the definition of "representable."
* s/then/so/:
R(X) & R(Y) == R(X), then X>Y is not subranged. Thus, all
values of type X are representable in the type Y.
(b) Y>X:
R(Y) & R(X) == R(Y), then Y>X is not subranged. Thus, all
* What's the difference between a policy and a "parameter that defines
the conversion" in
It can optionally take some policies which can be used to customize
its behavior. The Traits parameter is not a policy but the parameter
that defines the conversion.
??
 Dave Abrahams BoostPro Computing Software Development Training http://www.boostpro.com Clang/LLVM/EDG Compilers C++ Boost
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk