Clean Singleton Docstrings

[Marko Rauhamaa]

Chris Angelico <rosuav at gmail.com>:
> With a single abstract numeric type, what exactly does "inexact" mean,
> where does it come from, and how does that affect the expected
> behaviour and performance of numbers?

Not much is said in the standard:

   Thus inexactness is a contagious property of a number. If two
   implementations produce exact results for a computation that did not
   involve inexact intermediate results, the two ultimate results will
   be mathematically equivalent. This is generally not true of
   computations involving inexact numbers since approximate methods such
   as floating point arithmetic may be used, but it is the duty of each
   implementation to make the result as close as practical to the
   mathematically ideal result.

   <URL: http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.h
   tml#%_sec_6.2.2>

Exactness should be considered a flag that expresses whether the result
is an approximation.

> Will an "Exact" non-integer be stored as Decimal or Fraction? How do
> you know? They have vastly different semantics, and you should be able
> to choose.

The manual of the Scheme implementation would likely explain the
particular properties of its number system implementation. At its
simplest, you could have an implementation that only supports, say,
signed 16-bit exact integers. All other numbers would be inexact floats.

   Implementations are encouraged, but not required, to support exact
   integers and exact rationals of practically unlimited size and
   precision, and to implement the above procedures and the / procedure
   in such a way that they always return exact results when given exact
   arguments. If one of these procedures is unable to deliver an exact
   result when given exact arguments, then it may either report a
   violation of an implementation restriction or it may silently coerce
   its result to an inexact number. Such a coercion may cause an error
   later.

   An implementation may use floating point and other approximate
   representation strategies for inexact numbers. This report
   recommends, but does not require, that the IEEE 32-bit and 64-bit
   floating point standards be followed by implementations that use
   flonum representations, and that implementations using other
   representations should match or exceed the precision achievable using
   these floating point standards [12].

   In particular, implementations that use flonum representations must
   follow these rules: A flonum result must be represented with at least
   as much precision as is used to express any of the inexact arguments
   to that operation. It is desirable (but not required) for potentially
   inexact operations such as sqrt, when applied to exact arguments, to
   produce exact answers whenever possible (for example the square root
   of an exact 4 ought to be an exact 2).

   <URL: http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.h
   tml#%_sec_6.2.3>


Marko