[boost] [Numeric Conversion] Documentation Notes/Questions

Subject: [boost] [Numeric Conversion] Documentation Notes/Questions
From: Dave Abrahams (dave_at_[hidden])
Date: 2012-10-27 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
  super-quick "hello, world" example and a very short tutorial at the
  beginning would help a *lot*.  numeric_cast is arguably the most
  generally-useful 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 well-defined?  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 non-generic 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 whatever-the-max+1-is.  That's a well-defined
  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.

* Uh-oh:

    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