include/llvm/ADT/APFloat.h

   1 //== llvm/Support/APFloat.h - Arbitrary Precision Floating Point -*- C++ -*-==//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by Neil Booth and is distributed under the
   6 // University of Illinois Open Source License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file declares a class to represent arbitrary precision floating
  11 // point values and provide a variety of arithmetic operations on them.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15 /*  A self-contained host- and target-independent arbitrary-precision
  16     floating-point software implementation using bignum integer
  17     arithmetic, as provided by static functions in the APInt class.
  18     The library will work with bignum integers whose parts are any
  19     unsigned type at least 16 bits wide.  64 bits is recommended.
  20
  21     Written for clarity rather than speed, in particular with a view
  22     to use in the front-end of a cross compiler so that target
  23     arithmetic can be correctly performed on the host.  Performance
  24     should nonetheless be reasonable, particularly for its intended
  25     use.  It may be useful as a base implementation for a run-time
  26     library during development of a faster target-specific one.
  27
  28     All 5 rounding modes in the IEEE-754R draft are handled correctly
  29     for all implemented operations.  Currently implemented operations
  30     are add, subtract, multiply, divide, fused-multiply-add,
  31     conversion-to-float, conversion-to-integer and
  32     conversion-from-integer.  New rounding modes (e.g. away from zero)
  33     can be added with three or four lines of code.  The library reads
  34     and correctly rounds hexadecimal floating point numbers as per
  35     C99; syntax is required to have been validated by the caller.
  36     Conversion from decimal is not currently implemented.
  37
  38     Four formats are built-in: IEEE single precision, double
  39     precision, quadruple precision, and x87 80-bit extended double
  40     (when operating with full extended precision).  Adding a new
  41     format that obeys IEEE semantics only requires adding two lines of
  42     code: a declaration and definition of the format.
  43
  44     All operations return the status of that operation as an exception
  45     bit-mask, so multiple operations can be done consecutively with
  46     their results or-ed together.  The returned status can be useful
  47     for compiler diagnostics; e.g., inexact, underflow and overflow
  48     can be easily diagnosed on constant folding, and compiler
  49     optimizers can determine what exceptions would be raised by
  50     folding operations and optimize, or perhaps not optimize,
  51     accordingly.
  52
  53     At present, underflow tininess is detected after rounding; it
  54     should be straight forward to add support for the before-rounding
  55     case too.
  56
  57     Non-zero finite numbers are represented internally as a sign bit,
  58     a 16-bit signed exponent, and the significand as an array of
  59     integer parts.  After normalization of a number of precision P the
  60     exponent is within the range of the format, and if the number is
  61     not denormal the P-th bit of the significand is set as an explicit
  62     integer bit.  For denormals the most significant bit is shifted
  63     right so that the exponent is maintained at the format's minimum,
  64     so that the smallest denormal has just the least significant bit
  65     of the significand set.  The sign of zeroes and infinities is
  66     significant; the exponent and significand of such numbers is
  67     not stored, but has a known implicit (deterministic) value:
  68     0 for the significands, 0 for zero exponent, all 1 bits for
  69     infinity exponent.  For NaNs the sign and significand are
  70     deterministic, although not really meaningful; the exponent is
  71     implicitly all 1 bits.
  72
  73     TODO
  74     ====
  75
  76     Some features that may or may not be worth adding:
  77
  78     Conversions to and from decimal strings (hard).
  79
  80     Conversions to hexadecimal string.
  81
  82     Read and write IEEE-format in-memory representations.
  83
  84     Optional ability to detect underflow tininess before rounding.
  85
  86     New formats: x87 in single and double precision mode (IEEE apart
  87     from extended exponent range) and IBM two-double extended
  88     precision (hard).
  89
  90     New operations: sqrt, copysign, nextafter, nexttoward.
  91 */
  92
  93 #ifndef LLVM_FLOAT_H
  94 #define LLVM_FLOAT_H
  95
  96 // APInt contains static functions implementing bignum arithmetic.
  97 #include "llvm/ADT/APInt.h"
  98 #include "llvm/CodeGen/ValueTypes.h"
  99
 100 namespace llvm {
 101
 102   /* Exponents are stored as signed numbers.  */
 103   typedef signed short exponent_t;
 104
 105   struct fltSemantics;
 106
 107   /* When bits of a floating point number are truncated, this enum is
 108      used to indicate what fraction of the LSB those bits represented.
 109      It essentially combines the roles of guard and sticky bits.  */
 110   enum lostFraction {           // Example of truncated bits:
 111     lfExactlyZero,              // 000000
 112     lfLessThanHalf,             // 0xxxxx  x's not all zero
 113     lfExactlyHalf,              // 100000
 114     lfMoreThanHalf              // 1xxxxx  x's not all zero
 115   };
 116
 117   class APFloat {
 118   public:
 119
 120     /* We support the following floating point semantics.  */
 121     static const fltSemantics IEEEsingle;
 122     static const fltSemantics IEEEdouble;
 123     static const fltSemantics IEEEquad;
 124     static const fltSemantics x87DoubleExtended;
 125     /* And this psuedo, used to construct APFloats that cannot
 126        conflict with anything real. */
 127     static const fltSemantics Bogus;
 128
 129     static unsigned int semanticsPrecision(const fltSemantics &);
 130
 131     /* Floating point numbers have a four-state comparison relation.  */
 132     enum cmpResult {
 133       cmpLessThan,
 134       cmpEqual,
 135       cmpGreaterThan,
 136       cmpUnordered
 137     };
 138
 139     /* IEEE-754R gives five rounding modes.  */
 140     enum roundingMode {
 141       rmNearestTiesToEven,
 142       rmTowardPositive,
 143       rmTowardNegative,
 144       rmTowardZero,
 145       rmNearestTiesToAway
 146     };
 147
 148     /* Operation status.  opUnderflow or opOverflow are always returned
 149        or-ed with opInexact.  */
 150     enum opStatus {
 151       opOK          = 0x00,
 152       opInvalidOp   = 0x01,
 153       opDivByZero   = 0x02,
 154       opOverflow    = 0x04,
 155       opUnderflow   = 0x08,
 156       opInexact     = 0x10
 157     };
 158
 159     /* Category of internally-represented number.  */
 160     enum fltCategory {
 161       fcInfinity,
 162       fcNaN,
 163       fcNormal,
 164       fcZero
 165     };
 166
 167     /* Constructors.  */
 168     APFloat(const fltSemantics &, const char *);
 169     APFloat(const fltSemantics &, integerPart);
 170     APFloat(const fltSemantics &, fltCategory, bool negative);
 171     APFloat(double d);
 172     APFloat(float f);
 173     APFloat(const APFloat &);
 174     ~APFloat();
 175
 176     /* Arithmetic.  */
 177     opStatus add(const APFloat &, roundingMode);
 178     opStatus subtract(const APFloat &, roundingMode);
 179     opStatus multiply(const APFloat &, roundingMode);
 180     opStatus divide(const APFloat &, roundingMode);
 181     opStatus mod(const APFloat &, roundingMode);
 182     void copySign(const APFloat &);
 183     opStatus fusedMultiplyAdd(const APFloat &, const APFloat &, roundingMode);
 184     void changeSign();    // neg
 185     void clearSign();     // abs
 186
 187     /* Conversions.  */
 188     opStatus convert(const fltSemantics &, roundingMode);
 189     opStatus convertToInteger(integerPart *, unsigned int, bool,
 190                               roundingMode) const;
 191     opStatus convertFromInteger(const integerPart *, unsigned int, bool,
 192                                 roundingMode);
 193     opStatus convertFromString(const char *, roundingMode);
 194     double convertToDouble() const;
 195     float convertToFloat() const;
 196
 197     /* The definition of equality is not straightforward for floating point,
 198        so we won't use operator==.  Use one of the following, or write
 199        whatever it is you really mean. */
 200     // bool operator==(const APFloat &) const;     // DO NOT IMPLEMENT
 201
 202     /* IEEE comparison with another floating point number (NaNs
 203        compare unordered, 0==-0). */
 204     cmpResult compare(const APFloat &) const;
 205
 206     /* Bitwise comparison for equality (QNaNs compare equal, 0!=-0). */
 207     bool bitwiseIsEqual(const APFloat &) const;
 208
 209     /* Simple queries.  */
 210     fltCategory getCategory() const { return category; }
 211     const fltSemantics &getSemantics() const { return *semantics; }
 212     bool isZero() const { return category == fcZero; }
 213     bool isNonZero() const { return category != fcZero; }
 214     bool isNegative() const { return sign; }
 215     bool isPosZero() const { return isZero() && !isNegative(); }
 216     bool isNegZero() const { return isZero() && isNegative(); }
 217
 218     APFloat& operator=(const APFloat &);
 219
 220     /* Return an arbitrary integer value usable for hashing. */
 221     uint32_t getHashValue() const;
 222
 223   private:
 224
 225     /* Trivial queries.  */
 226     integerPart *significandParts();
 227     const integerPart *significandParts() const;
 228     unsigned int partCount() const;
 229
 230     /* Significand operations.  */
 231     integerPart addSignificand(const APFloat &);
 232     integerPart subtractSignificand(const APFloat &, integerPart);
 233     lostFraction addOrSubtractSignificand(const APFloat &, bool subtract);
 234     lostFraction multiplySignificand(const APFloat &, const APFloat *);
 235     lostFraction divideSignificand(const APFloat &);
 236     void incrementSignificand();
 237     void initialize(const fltSemantics *);
 238     void shiftSignificandLeft(unsigned int);
 239     lostFraction shiftSignificandRight(unsigned int);
 240     unsigned int significandLSB() const;
 241     unsigned int significandMSB() const;
 242     void zeroSignificand();
 243
 244     /* Arithmetic on special values.  */
 245     opStatus addOrSubtractSpecials(const APFloat &, bool subtract);
 246     opStatus divideSpecials(const APFloat &);
 247     opStatus multiplySpecials(const APFloat &);
 248
 249     /* Miscellany.  */
 250     opStatus normalize(roundingMode, lostFraction);
 251     opStatus addOrSubtract(const APFloat &, roundingMode, bool subtract);
 252     cmpResult compareAbsoluteValue(const APFloat &) const;
 253     opStatus handleOverflow(roundingMode);
 254     bool roundAwayFromZero(roundingMode, lostFraction);
 255     opStatus convertFromUnsignedInteger(integerPart *, unsigned int,
 256                                         roundingMode);
 257     lostFraction combineLostFractions(lostFraction, lostFraction);
 258     opStatus convertFromHexadecimalString(const char *, roundingMode);
 259
 260     void assign(const APFloat &);
 261     void copySignificand(const APFloat &);
 262     void freeSignificand();
 263
 264     /* What kind of semantics does this value obey?  */
 265     const fltSemantics *semantics;
 266
 267     /* Significand - the fraction with an explicit integer bit.  Must be
 268        at least one bit wider than the target precision.  */
 269     union Significand
 270     {
 271       integerPart part;
 272       integerPart *parts;
 273     } significand;
 274
 275     /* The exponent - a signed number.  */
 276     exponent_t exponent;
 277
 278     /* What kind of floating point number this is.  */
 279     fltCategory category: 2;
 280
 281     /* The sign bit of this number.  */
 282     unsigned int sign: 1;
 283   };
 284 } /* namespace llvm */
 285
 286 #endif /* LLVM_FLOAT_H */