-/* A self-contained host- and target-independent arbitrary-precision
- floating-point software implementation. It uses bignum integer
- arithmetic as provided by static functions in the APInt class.
- The library will work with bignum integers whose parts are any
- unsigned type at least 16 bits wide, but 64 bits is recommended.
-
- Written for clarity rather than speed, in particular with a view
- to use in the front-end of a cross compiler so that target
- arithmetic can be correctly performed on the host. Performance
- should nonetheless be reasonable, particularly for its intended
- use. It may be useful as a base implementation for a run-time
- library during development of a faster target-specific one.
-
- All 5 rounding modes in the IEEE-754R draft are handled correctly
- for all implemented operations. Currently implemented operations
- are add, subtract, multiply, divide, fused-multiply-add,
- conversion-to-float, conversion-to-integer and
- conversion-from-integer. New rounding modes (e.g. away from zero)
- can be added with three or four lines of code.
-
- Four formats are built-in: IEEE single precision, double
- precision, quadruple precision, and x87 80-bit extended double
- (when operating with full extended precision). Adding a new
- format that obeys IEEE semantics only requires adding two lines of
- code: a declaration and definition of the format.
-
- All operations return the status of that operation as an exception
- bit-mask, so multiple operations can be done consecutively with
- their results or-ed together. The returned status can be useful
- for compiler diagnostics; e.g., inexact, underflow and overflow
- can be easily diagnosed on constant folding, and compiler
- optimizers can determine what exceptions would be raised by
- folding operations and optimize, or perhaps not optimize,
- accordingly.
-
- At present, underflow tininess is detected after rounding; it
- should be straight forward to add support for the before-rounding
- case too.
-
- The library reads hexadecimal floating point numbers as per C99,
- and correctly rounds if necessary according to the specified
- rounding mode. Syntax is required to have been validated by the
- caller. It also converts floating point numbers to hexadecimal
- text as per the C99 %a and %A conversions. The output precision
- (or alternatively the natural minimal precision) can be specified;
- if the requested precision is less than the natural precision the
- output is correctly rounded for the specified rounding mode.
-
- It also reads decimal floating point numbers and correctly rounds
- according to the specified rounding mode.
-
- Conversion to decimal text is not currently implemented.
-
- Non-zero finite numbers are represented internally as a sign bit,
- a 16-bit signed exponent, and the significand as an array of
- integer parts. After normalization of a number of precision P the
- exponent is within the range of the format, and if the number is
- not denormal the P-th bit of the significand is set as an explicit
- integer bit. For denormals the most significant bit is shifted
- right so that the exponent is maintained at the format's minimum,
- so that the smallest denormal has just the least significant bit
- of the significand set. The sign of zeroes and infinities is
- significant; the exponent and significand of such numbers is not
- stored, but has a known implicit (deterministic) value: 0 for the
- significands, 0 for zero exponent, all 1 bits for infinity
- exponent. For NaNs the sign and significand are deterministic,
- although not really meaningful, and preserved in non-conversion
- operations. The exponent is implicitly all 1 bits.
-
- APFloat does not provide any exception handling beyond default exception
- handling. We represent Signaling NaNs via IEEE-754R 2008 6.2.1 should clause
- by encoding Signaling NaNs with the first bit of its trailing significand as
- 0.
-
- TODO
- ====
-
- Some features that may or may not be worth adding:
-
- Binary to decimal conversion (hard).
-
- Optional ability to detect underflow tininess before rounding.
-
- New formats: x87 in single and double precision mode (IEEE apart
- from extended exponent range) (hard).
-
- New operations: sqrt, IEEE remainder, C90 fmod, nextafter,
- nexttoward.
-*/
-